HTTP 接口设计

# JSON

如何构造请求和响应体

# 字段命名

  • 由于 JSON(JavaScriptObjectNotation)来自于 JavaScript 语言，所以字段命名遵循 JavaScript 语言， 采用 lowerCamelCase (小骆驼拼写法)
  • 不要采用 snake_case

# 数据类型

  • 常用数据类型映射
    • bool：映射为 string，使用 Y 表示 true，N 表示 false
    • int：映射为 number
    • long：映射为 string
    • float，double，decimal：映射为 string
    • 日期、时间：映射为 string
  • 特殊说明
    • 表示 ID 概念的字段，统一使用 string
    • long 映射为 string，是因为 JavaScript 的 number 能处理的数值范围不够，导致各种奇怪的问题

# 空值处理

  • 在数据传输时，如果某个字段是空值，则直接省略此字段不传，减少网络开销

# 嵌套 vs. 平铺

  • 嵌套 > 平铺
  • 举例，Project 对象有个创建者，前端要显示创建者的名字和头像

Good

{
  "id": "id",
  "name": "项目名称",
  "creator": {
    "id": "111",
    "name": "创建者",
    "avatar": "https://xxx.xxx.xxx/avatar.png"
  }
}

Bad

{
  "id": "id",
  "name": "项目名称",
  "creatorId": "111",
  "creatorName": "创建者",
  "creatorAvatar": "https://xxx.xxx.xxx/avatar.png"
}

# 响应体

{
  "code": "OK",
  "message": "操作成功",
  "data": {},
  "errors": {
    "title": "不能为空"
  }
}

code：错误码，任何情况下必须返回

message：错误信息，可选

data：业务数据，可选，该字段是一个 Map

errors：错误表，发生 HTTP 400 错误时，存在此字段， 该字段是一个 Map，Key 为发生错误的请求字段， Value 为错误描述

# 错误码

  • code 字段表示业务处理的错误码
  • 如果业务处理成功，必须返回 OK
  • 如果业务处理失败，使用不同的错误码区分不同的错误，错误码使用简短的能够体现错误种类的英文单 词来表示，使用大写字母，使用下划线分隔单词
  • 为什么使用 string 而不是 int?传统上经常使用一个数字表示错误码，但是如果错误种类比较多，维护错 误码表就是一个很大的工作，因为相近的错误码数字最好连续，但是后期添加就可能导致已经定义的错 误码的改动。另外，数字错误码很难一看就知道发生了什么错误;使用字符串的话，能够从文字上看出 错误类型，而且错误码的添加和更新也相对独立

← Spring Boot 实现 →