HTTP API接口设计规范

news2024/10/6 4:01:54

1. 所有请求使用POST方法

使用post，相对于get的query string，可以支持复杂类型的请求参数。例如日常项目中碰到get请求参数为数组类型的情况。
便于对请求和响应统一做签名、加密、日志等处理

2. URL规则

URL中只能含有英文，使用英文单词或简称，不要使用汉语拼音
所有字符使用小写字母
多个单词之前使用连字符-分隔，如third-login, 不要使用thirdlogin,thirdLogin或third_login
URL的path部分使用 系统/模块/操作 的格式，如 ims/video/list
- 系统，表示这个接口是微服务中的哪个服务，可使用简称
- 模块，表示系统的子模块。模块名字使用名词全称，且使用单数形式
- 操作，表示具体的接口，使用动词+名词的形式，需要考虑单复数。比如add-user,list-users,delete-users

3. HTTP头部

将具体业务无关的数据放在HTTP headers
后端系统可以在不涉及请求和响应体的情况下，处理一些公用逻辑

4. 请求和响应体

使用utf-8编码
JSON格式
如果需要加密，可以将正常的JSON加密后用base64编码

5. HTTP状态码

业务的处理结果不体现在http状态码，由响应体的错误码字段表示
只是有部分http状态码表示业务无关的响应，例如
- 200: 业务已处理，但是处理成功还是失败由响应体表示
- 400: 错误的请求，多用在请求参数验证。客户端开发要保证向服务器提交正确格式的请求
- 401: 认证失败，一般没有token或者没有token过期
- 403: 没有权限调用这个接口。客户端应该隐藏用户无权限的操作
- 500: 服务器异常

6. 字段命名

JSON来自javascript语言，所以字段命名遵循javascript语言，使用 lowerCamelCase 小骆驼拼写法
不要使用下划线链接的 snake_case

7. 数据类型

常用数据类型映射

bool：映射为 string，使用Y表示true，N表示false
int: 映射为number
long: 映射为string，因为js的number类型能处理的数值范围不够，实际项目中会导致各种奇怪的问题
float, double, decimal: 映射为string
日期、时间:映射为string

注意：

表示ID概念的字段，统一使用string
数据传输时，如果某个字段为空值，直接省略这个字段不传，减少网络开销
响应体业务数据包含多个数据结构时，优先使用嵌套格式,例如下面这个用户创建的消息

 "item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",