0%

编程规约(十):前后端规约

1. 【强制】前后端交互的 API,需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体

  1. 协议:生产环境必须使用 HTTPS

  2. 路径:每一个 API 需对应一个路径,表示 API 具体的请求地址

    1. 代表一种资源,只能为名词,推荐使用复数;不能为动词,请求方法以及表达动作意义
    2. URL 路径不能使用大写,单词如果需要分隔,统一使用下划线
    3. 路径禁止携带表示请求内容类型的后缀,比如 “.json”,”.xml”,通过 accept 头表达即可
  3. 请求方法:对具体操作的定义,常见的请求方法如下:

    1. GET: 从服务器取出资源
    2. POST: 在服务器新建一个资源
    3. PUT: 在服务器更新资源
    4. DELETE: 从服务器删除资源
  4. 请求内容:URL 带的参数必须无敏感信息或符合安全要求;body 里带参数时必须设置 Content-Type

  5. 响应体:响应体 body 可放置多种数据类型,由 Content-Type 头来确定

2. 【强制】前后端数据列表相关的接口返回,如果为空,则返回空数组[] 或空集合 {}

  • 说明:此条约定有利于数据层面上的协作更加高效,减少前端很多琐碎的 null 判断

3. 【强制】服务器发生错误时,返回给前端的响应信息必须包含 HTTP 状态码、errorCode、errorMessage 和用户提示信息四个部分

  • 说明:四个部分的涉众对象分别是浏览器、前端开发、错误排查人员、用户。其中,输出给用户的提示信息要求:简短清晰、提示友好,引导用户进行下一步操作或解释错误原因,提示信息可以包括错误原因、上下文环境、推荐操作等。errorCode: 参考附表3。errorMessage: 简要描述后端出错原因,便于错误排查人员快速定位问题,注意不要包含敏感数据信息

  • 正例:常见的 HTTP 状态码如下:

    1. 200 OK: 表明该请求被成功地完成,所请求的资源发送到客户端
    2. 401 Unauthorized: 请求要求身份验证,常见对于需要登录而用户未登录的情况
    3. 403 Forbidden: 服务器拒绝请求,常见于机密信息或复制其它登录用户链接访问服务器的情况
    4. 404 Not Found: 服务器无法取得所请求的网页,请求资源不存在
    5. 500 Internal Server Error: 服务器内部错误

4. 【强制】在前后端交互的 JSON 格式数据中,所有的 key 必须为小写字母开始的 lowerCamelCase 风格,符合英文表达习惯,且表意完整

  • 正例errorCodeerrorMessageassetStatusmenuListorderListconfigFlat
  • 反例ERRORCODEERROR_CODEerror_messageerror-messageerrormessageErrorMessagemsg

5. 【强制】errorMessage 是前后端错误追踪机制的体现,可以在前端输出到 type=”hidden” 文字类控件中,或者用户端的日志中,帮助我们快速地定位出问题

6. 对于需要使用超大整数的场景,服务端一律使用 String 字符串类型返回,禁止使用 Long 类型

  • 说明

    1. Java 服务端如果直接返回 Long 整型数据给前端,JS 会自动转换为 Number 类型(注:此类型为双精度浮点数,表示原理与取值范围等同于 Java 中的 Double
    2. Long 类型能表示的最大值是 2 的 63 次方 - 1,在取值范围内,超过 2 的 53 次 方(9007199254740992)的数值转化为 JS 的 Number 时,有些数值会有精度损失
    3. 扩展说明,在 Long 取值范围内,任何 2 的指数次整数都是绝对不会存在精度损失的,所以说精度损失是一个概率问题。
    4. 若浮点数尾数位与指数位空间不限,则可以精确表示任何整数,但很不幸,双精度浮点数的尾数位只有 52 位
  • 反例:通常在订单号或交易号大于等于 16 位,大概率会出现前后端单据不一致的情况。比如:"orderId": 362909601374617692,前端拿到的值却是:362909601374617660

7. 【强制】HTTP 请求通过 URL 传递参数时,不能超过 2048 字节

  • 说明:不同浏览器对于 URL 的最大长度限制略有不同,并且对超出最大长度的处理逻辑也有差异,2048 字节是取所有浏览器的最小值
  • 反例:某业务将退货的商品 id 列表放在 URL 中作为参数传递,当一次退货商品数量过多时,URL 参数超长,传递后端的参数被截断,导致部分商品未能正确退货

8. 【强制】HTTP 请求通过 body 传递内容时,必须控制长度,超出最大长度后,后端解析会出错

  • 说明:nginx 默认限制是 1 MB,tomcat 默认限制为 2 MB。当确实有业务需要传较大内容时,可以通过调大服务器端的限制

9. 【强制】在翻页场景中,用户输入的参数小于 1,则前端返回第一页参数给后端;后端发现用户输入的参数大于总页数,直接返回最后一页

10. 【强制】服务器内部重定向必须使用 forward;外部重定向地址必须使用 URL 统一代理模块生成,否则会因线上采用 HTTPS 协议而导致浏览器提示“不安全”,并且还会带来 URL 维护不一致的问题

11. 【推荐】服务器返回信息必须被标记是否可以缓存,如果缓存,客户端可能会重用之前的请求结果

  • 说明:缓存有利于减少交互次数,减少交互的平均延迟
  • 正例:http 1.1 中,s-maxage 告诉服务器进行缓存,时间单位为妙。用法如下:response.setHeader("Cache-Control", "s-maxage=" + cacheSecond);

12. 【推荐】服务端返回的数据,使用 JSON 格式而非 XML

  • 说明:尽管 HTTP 支持使用不同的输出格式,例如纯文本、JSON、CSV、XML、RSS 甚至 HTML。如果我们使用的面向用户的服务,应该选择 JSON 作为通信中使用的标准数据交换格式,包括请求和响应。此外,application/JSON 是一种通用的 MIME 类型,具有实用、精简、易读的特点

13. 【推荐】前后端的时间格式统一为 “yyyy-MM-dd HH:mm:ss”,统一为 GMT

14. 【参考】在接口路径中不要加入版本号,版本控制在 HTTP 头信息中体现,有利于向前兼容

  • 说明:当用户在低版本和高版本之间反复切换工作时,会导致迁移复杂度升高,存在数据错乱风险
-------------------- 本文结束感谢您的阅读 --------------------