# HTTP 协议

针对 HTTP 协议的规则。

# HTTP 请求方法

  • 所有请求使用 POST 方法
  • 理由如下
    • 这份接口设计不是遵循 RESTful 规范的,所以不用纠结读请求用 GET,写请求用 POST,PUT,DELETE 等
    • 使用 POST,相对于 GET 的 Query String,可以支持复杂的请求参数,即使是读请求,可以构造复杂的筛选请 求结构
    • 便于对请求和响应统一做签名、加密、日志等处理

# URL 规则

  • URL 中的只能含有英文,使用英文单词或简称,不要使用汉语拼音。
  • 所有字符使用小写字母。
  • 多个单词间使用“-”(hyphen,连字符)分隔,如 create-user,不要使用 createuser、createUser 或 者 create_user 。
  • URL 的 path 部分,使用 系统/模块/操作 的格式,如 app/account/login
    • 系统,表示这个接口是给谁用的,比如:app、web、h5、weapp 等。命名可使用简称。
    • 模块,表示系统的子模块,比如:account(账户)、project(项目)、contract(合同)等。模块名字使用名词 全称,且使用单数形式。
    • 操作,表示这个模块的具体的接口,比如 create-user(创建用户)、list-users(用户列表)等。使用动词+名词 的形式,需要考虑单复数。对于常用的操作,可以使用习惯词语,比如 login(登录)、logout(登出)。

# HTTP 头

  • 将具体接口业务无关的数据放在 HTTP Headers
  • 后端系统可以在不涉及请求和响应体的情况下,处理一些公用逻辑
  • 例如
    • X-Access-Token:身份认证
    • X-App-Os:客户端 OS
    • X-App-Version:客户端版本
    • X-Network:客户端网络模式,Wi-Fi,蜂窝网络
    • X-Sign:请求签名

# 请求体和响应体

  • 使用 UTF-8 编码
  • JSON 格式
  • 如果有加密功能,可以将正常的 JSON 加密后,使用 Base64 编码

# HTTP 状态码

  • 业务的处理结果不体现在 HTTP 状态码,由响应体的错误码字段表示
  • 只使用部分 HTTP 状态码来表示一些业务无关的响应
  • 例如
    • 200:业务已处理,但是业务处理成功还是失败由响应体表示
    • 400:错误的请求,多用在请求验证,客户端开发要保证向服务器提交正确格式的请求,400 错误不该在生产环 境出现
    • 401:认证失败,一般是没有 Access Token 或者已过期
    • 403:无权限,指没有权限调用这个接口,客户端应该在界面上将用户无权限的操作隐藏
    • 500:服务器发生了未处理的异常, 500 错误不该在生产环境出现