Http参数格式约定

Posted on Edited on In

前提

微服务通过http协议进行内容传递，因为http协议自由且松散，所以有必要提供一套强有力的约定来限制接口。
服务内部实现，可以基于个人编程风格，但涉及到交互协作，必须提供风格一致的输入输出，减少开发与维护成本。

疑问

Request 疑问

  1. 接口不兼容升级，如何区分版本？
  2. 如何使用request method？ include GET、PUT、POST、PATCH、DELETE and so on.
  3. 入参如何定义？ include path、param、RequestBody、Header

Response 疑问

常见格式如下:

1
2
3
4
5
6
7
8
{
    "code": 0,
    "data": {
        "name": "zhangsan",
        "age": 4
    },
    "message": "ok"
}
  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内容。

附录

常见的http状态码，可以基于实际场景选用。

2xx

  1. 200 (OK) = 成功
  2. 201 (Created) = 成功创建了一个资源
  3. 202 (Accepted) = 请求已接受，但未处理完成。如：定时触发的批量任务，以及触发，则返回202状态，实体内容返回已处理进度
  4. 204 (No Content) = 成功 but 无实体内容
  5. 206 (Partial Content) = 响应范围请求，request报文中包含range，response报文中包含Content-Range，断点续传

3xx

  1. 301 (Moved Permanently) = 永久性重定向， 基于Location更新书签
  2. 302 (Found) = 临时更新，无需更新
  3. 303 (See Other) = 功能和302一致，但是必须通过GET方法再次发起请求
  4. 304 (Not Modified) = 不满足附带条件(If-Modified-Since) 不返回主体。非重定向，客户端可以使用本地缓存资源。
  5. 307 (Temporary Redirect) = 功能和302一致，但是不会从POST变成GET

4xx

  1. 400 (Bad Request) = 请求报文存在语法错误，调用方参数异常
  2. 401 (Unauthorized) = 未通过认证授权，not login
  3. 403 (Forbidden) = 未给出原因，可以在实体中定义错误原因及错误码
  4. 404 (Not Found) = 资源不存在
  5. 405 (Method Not Allowed) = 请求方法错误，如用GET方法请求一个POST接口
  6. 429 (Too Many Requests) = 用户单位时间内发送了太多请求，限流

5xx

  1. 500 (Internal Server Error) = 程序执行错误，服务端不知道如何处理
  2. 502 (Bad Gateway) = 网关无法得到响应，如:nginx无法找到负载服务
  3. 503 (Service Unavailable) = 超负载或服务启动中，通过Retry-After标识可提供服务时间
  4. 504 (Gateway Timeout) = 网关和内部服务通信超时