# 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?传统上经常使用一个数字表示错误码,但是如果错误种类比较多,维护错 误码表就是一个很大的工作,因为相近的错误码数字最好连续,但是后期添加就可能导致已经定义的错 误码的改动。另外,数字错误码很难一看就知道发生了什么错误;使用字符串的话,能够从文字上看出 错误类型,而且错误码的添加和更新也相对独立