Http 参数格式约定,接受反驳

前提

SpringCloud 是 http 协议传输,接口协议自由且松散,所以需要强有力的约定来限制接口。
服务内部实现,可以基于个人习惯,但是必须提供风格一致的输入输出,减少开发与维护成本。

疑问

Request 疑问

  1. 接口不兼容升级,如何区分版本?
  2. 如何使用 request method? include GETPUTPOSTDELETE and so on.
  3. 入参如何定义? include pathparamRequestBodyHeader

Response 疑问

常见格式如下:

{
    "code": 0,
    "data": {
        "name": "zhangsan",
        "age": 4
    },
    "message": "ok",
    "isRetry": false
}
  1. code 如何定义? code=0 表示成功 or 返回 http_code 值?
  2. error_code 如何定义? 扩展问题为,前端如何根据 code 进行提示渲染?

预期

Request 规范

  1. 接口无法兼容时,升级版本。非高频事件。默认接口无版本号,升级时 path 中增加版本,从 /v2/ 开始。
  2. 针对 request method,不完全依赖 restful 定义,仅使用GET & POST两种方法。查询接口使用GET,业务逻辑接口使用POST
  3. 入参定义
    1. 不使用@PathVariable,难做到单参数满足业务需求,不方便扩展。
    2. 使用@RequestParam描述参数,不符合时返回400状态码。
    3. 表单提交使用POST, 通过application/json利用 @RequestBody 转换 javaBean。
    4. Header 传输通用信息,如 ip、deviceId、token 等,且在 nginx 转发时,同时转发 header 参数。

Response 规范

  1. 通过http_status返回error_code。常用如:400、500 以及自定义频段。此时 response 内容为error_message
  2. 前端基于http_status查询对应渲染文案(含国际化)。

不使用 json 定义 code 的理由如下:

  1. 更符合 http 规范
  2. 减少性能损耗。读取http_status为 error 时,不需要解析 response 内容。