接口开发规范

HTTP接口

• 接口返回值定义规范

{

  "code": 0,

  "message": "success",

  "data": {}

}

# code：0 – 处理成功 ；非0 – 处理失败

# code返回的错误码不要使用httpcode，如500、404

# message：处理失败的原因提示

# 老系统维持现状，新系统使用以上格式

• 接口地址与参数规范

  • 若地址中出现多个单词则单词小写并使用"-"横线进行分割

  • RequestBody参数使用驼峰命名

  • url参数和路径参数使用驼峰命名

  • 返回值使用驼峰命名

·        # 地址使用横线分割

·        http://xxx/api/v1/user/get-count

·         

·        # RequestBody参数使用驼峰命名

·        {

·          "userName": "zhangshan",

·          "userSex": 1

·        }

·         

·        # url参数和路径参数使用"_"分割

·        http://xxx/api/v1/user/get-count?userType=1

·        http://xxx/api/v1/user/get/userType/1

·         

# 老系统维持现状，新系统使用以上格式

• 接口若对外网提供服务，则需要认证机制。若是内网访问则不需要进行认证。

• 应该将API的版本号放入URL，高本版发布低版本仍需要对外提供服务。

如：https://api.example.com/api/v1/

• 若是使用swagger做在线文档，则需要区分测试环境和生产环境，生产环境不能使用swagger调用接口(或者不提供swagger接口)。

• 尽量按照以下方式操作

·        GET    （SELECT）：从服务器检索特定资源，或资源列表。

·        POST   （CREATE）：在服务器上创建一个新的资源。

·        PUT    （UPDATE）：更新服务器上的资源。

DELETE （DELETE）：从服务器删除资源。