# 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",
  "msg": "操作成功",
  "data": {},
  "errors": {
    "title": "不能为空"
  }
}

code:错误码,任何情况下必须返回

msg:错误信息,可选

data:业务数据,可选,该字段是一个 Map

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

# 错误码

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