接口规范

---

1. 协议规范

为了确保不同系统/模块间的数据交互，需要事先约定好通讯协议，如：TCP、HTTP、HTTPS 协议。为了确保数据交互安全，建议使用 HTTPS 协议。

2. 接口路径规范

作为接口路径，为了方便清晰的区分来自不同的系统，可以采用不同系统/模块名作为接口路径前缀。

格式规范如下：

• 用户模块 /userCenterApi/xx
• 工单模块 /outwork/xx
• ...

3. 版本控制规范

4. 接口命名规范

5. 请求参数规范

• 请求方式：

按照 GET、POST、DELETE 等含义定义，避免出现不一致现象，对人造成误解、歧义。

• 请求头：

请求头根据项目需求添加配置参数。如：请求数据格式，accept="application/json"等。如有需要，请求头可根据项目需求要求传入用户 Authorization token、唯一验签码等加密数据。

• 请求参数/请求体：

请求参数字段，尽可能与数据库表字段、对象属性名等保持一致，因为保持一致最省事，最舒服的一件事。

6. 返回数据规范

统一规范返回数据的格式，对己对彼都有好处，此处以 json 格式为例。返回数据应包含：返回状态码、返回状态信息、具体数据。

格式规范如下：

{
  "count": 0
  "errorCode": null
  "errorMessage": null
  "resultData": {}
  "status": "complete"
  "success": true
}

返回数据中的状态码、状态信息，常指具体的业务状态，不建议和 HTTP 状态码混在一起。HTTP 状态，是用来体现 HTTP 链路状态情况，如：404-Not Found。HTTP 状态码和 json 结果中的状态码，并存尚可，用于体现不同维度的状态。