请求接口及返回值规范[HTTP&RPC]

0. 禁止规则&设计原则

任何接口不允许使用编程语言相关的扩展名，可以使用与返回值类型相关的扩展名 (安全角度考虑，将泄漏后端语言或框架)
接口名不允许以/结尾 (搜索引擎优化角度考虑，一个同样的页面不应该有两个地址，会被搜索引擎认为是作弊，搜索引擎对无/的地址支持更加友好)
接口应该尽量的少, 后端接口不应该因前端的简单格式调整或者查询字段的多少有多调整，请注意一个后端接口不应该仅仅服务于一个前端需求，而应该是服务于一堆类似的各种可能的前端资源请求需求

1. 前端相关

Content-Type应与实际的body类型一致

例如：POST传参方式

Content-Type:application/json                   (推荐，尤其是参数复杂时，可能是趋势，案例：京东，csdn，airbnb，bilibili)
Content-Type:application/x-www-form-urlencoded  (推荐，目前这种方式仍然居多)
Content-Type:multipart/form-data
Content-Type:text/plain

最合适的Ajax内容编码类型 https://segmentfault.com/a/1190000006871099

2. 后端相关

返回的Content-Type Header应与实际的格式一致，并携带编码信息
常用类型：

json数据：Content-Type:application/json; charset=utf-8
html页面：text/html;charset=utf-8

因前端需求通常变更大于后端变更，接口设计时应考虑多种设计需求，后端接口尽量不受前端需求变更影响

3. 接口结构和命名

3.1 无状态接口(stateless)采用restful风格

微服务内部接口(后端编码关心的地址)：http://IP/app_name/v1/resources_name
应用外部映射(前端实际调用的地址)： http://app_name.domain.com/v1/resources_name

resources_name使用 snake_case，使用名词复数形式，尽量一个单词

涉及隐私的参数（例如用户密码）不允许使用地址列表传参

示例

【GET】          /users                # 查询用户信息列表
【GET】          /users/1001           # 查看某个用户信息
【POST】         /users                # 新建用户信息
【PUT】          /users/1001           # 替换用户信息，更新用户信息(可能是更新全部字段，也可能会删除部分信息)
【PATCH】        /users/1001           # 更新用户信息 (部分字段)
【DELETE】       /users/1001           # 删除用户信息

3.2 有状态接口，接口名使用动宾结构

resources_name使用 snake_case 动宾结构，或一个动词

理由: 分隔符"-“与”_"的选择
1） -分隔符从大小写从键盘录入的角度(不需要按Shift键)，与URL中保持小写原则相一致(url的特定部分不区分大小写，且小写字母更容易录入)【缺点】
2) -用于连接和_用于连接语义上有区别，_通常用于连接含义相关的部分，而-用于连接相互较为独立的部分，这样看起来_语义上更接近【优点】
3) 目前蛇底式与驼峰式较为常见，而烤串式不常见【优点】

4. 接口参数命名

接口参数：snake_case

用于排序，搜索，过滤等请求条件参数应放在请求字符串列表(便于用户识别或修改)，不论是get还是post

常用参数或jsonkey名称：

page        页码
per_page    每页条目数
limit       限制返回数据的量
order       升序或降序排列，desc或asc
sort        根据某一列排序  
q           搜索关键字  

total_count 总记录数
total_pages 总页数

4.1 资源分页机制

建议采用 Link Header机制返回分页元信息, 以此不去破坏返回值的资源信息
https://git.d.com/help/api/README.md#pagination-link-header

5. 实现逻辑

用户名或密码不允许使用get方式携带，不允许使用cookie明文保存，不允许明文传递
GET请求请求不允许携带body (不符合http协议标准，因有些web server会直接丢弃)

6. 请求返回结构

{
  "meta":{
    "code":"10000",   
    "msg": "ok";
    "desc": ""
  }
  "data": {} or []， # 内部格式由具体业务决定
}

状态码参考 https://zhuanlan.zhihu.com/p/31298060

系统级错误
服务级错误

7. 错误码与HTTP状态值

错误码为7位数据，0表示正常

第1位表示错误提示级别  
 |-1 按服务器返回提示
 |-2 不提示
 |-3 需要进行友好提示(卖萌)
第2-3位表示服务代码  
 |-00 系统错误(一般为后端bug或故障导致，或多个服务通用的错误)
 |-01 用户权限系统
 |-02 文件管理/上传下载系统
 |-xx 其它服务代码(一般为用户参数输入错误，业务系统建议使用30以上代码)
第4-7位表示具体错误 
 |-xx 具体的错误代码

错误码设计 https://blog.csdn.net/yzzst/article/details/54799971

HTTP状态值：

HTTP状态值https://zhuanlan.zhihu.com/p/31298060

A. 参考：

snake_case：微信开放平台，腾讯开放平台，开源中国百度，阿里云
camelCase：京东，百度，爱奇艺
小写无连字符：百度百科

【主要参考】Restful风格的接口设计 https://juejin.im/entry/59b8d34c6fb9a00a4455dd04

gitee.com 蛇底式

腾讯开放平台 http://open.qq.com/

URI设计原则 https://stackoverflow.com/questions/1619152/how-to-create-rest-urls-without-verbs/1619677#1619677

Gitlab API V3 https://link.zhihu.com/?target=https%3A//developer.github.com/v3/

返回值的处理 https://www.v2ex.com/t/340607?p=2

RESTful API定义及使用规范 https://zhuanlan.zhihu.com/p/31298060

url接口名(蛇底式命名法)，不允许大小写混用
参考：http://wiki.open.qq.com/wiki/v3/user/get_info open.weibo.com
url规则，参数命名
返回值命名

http://wiki.open.qq.com/wiki/website/%E5%BE%AE%E5%8D%9A%E7%A7%81%E6%9C%89%E8%BF%94%E5%9B%9E%E7%A0%81%E8%AF%B4%E6%98%8E
https://docs.open.alipay.com/common/105806
http://open.weibo.com/wiki/Error_code
https://open.weixin.qq.com/cgi-bin/showdocument?action=dir_list&t=resource/res_list&verify=1&id=open1419318634&token=&lang=zh_CN
http://lbs.amap.com/api/webservice/info/

来源：CSDN

作者：zhg_vincent

链接：https://blog.csdn.net/Vincent2014Linux/article/details/103241610

标签

返回值

用户接口

接口

前端

后端接口开发及返回值规范札记