请求：
{
"user":{
}
}
返回：
{
"user":{
"id":38710,
"sex":0,
"name":"ouyang"
},
"code":200,
"msg":"success"
}
请求：
{
"user[]":{
}
}
返回：
{
"user[]":[
{
"id":38710,
"name":"stone"
},
{
"id":70793,
"name":"Strong"
},
{
"id":82001,
"name":"Android"
}
],
"code":200,
"msg":"success"
}
请求：
{
"user":{
"moment":{
},
}
}
返回：
{
"user":{
"id":70793,
"sex":0,
"name":"Strong",
"moment":{
"id":12,
"userId":70793,
"date":"2017-02-08 16:06:11.0",
"content":"1111534034"
},
},
"code":200,
"msg":"success"
}
| 开发流程 | 传统方式 | JSON-API |
|---|---|---|
| 接口传输 | 等后端编辑接口，然后更新文档，前端再按照文档编辑请求和解析代码 | 前端按照自己的需求编辑请求和解析代码。 没有接口，更不需要文档！前端再也不用和后端沟通接口或文档问题了！ |
| 兼容旧版 | 后端增加新接口，用v2表示第2版接口，然后更新文档 | 什么都不用做！ |
| 前端请求 | 传统方式 | JSON-API |
|---|---|---|
| 要求 | 前端按照文档在对应URL后面拼接键值对 | 前端按照自己的需求在固定URL后拼接JSON |
| 结构 | 同一个URL内table_name只能有一个 base_url/get/table_name? key0=value0&key1=value1... |
同一个URL后TableName可传任意数量个 base_url/get/ { TableName0:{ key0:value0, key1:value1, ... }, TableName1:{ ... } ... } |
| URL | 不同的请求对应不同的URL，基本上有多少个不同的请求就得有多少个接口URL | 相同的操作方法(增删改查)都用同一个URL， 大部分请求都用7个通用接口URL的其中一个 |
| 键值对 | key=value | key:value |
| 后端操作 | 传统方式 | JSON-API |
|---|---|---|
| 解析和返回 | 取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给前端 | 把Parser#parse方法的返回值返回给前端就行 |
| 返回JSON结构的设定方式 | 由后端设定，前端不能修改 | 由前端设定，后端不能修改 |
| 前端解析 | 传统方式 | JSON-API |
|---|---|---|
| 查看方式 | 查文档或问后端，或等请求成功后看日志 | 看请求就行，所求即所得，不用查、不用问、不用等。也可以等请求成功后看日志 |
| 解析方法 | 用JSON解析器来解析JSONObject | 可以用JSONResponse解析JSONObject，或使用传统方式 |
| 前端的请求 | 传统方式 | JSON-API |
|---|---|---|
| User | base_url/get/user?id=38710 | [base_url/get/ { "user":{ "where":"id=38710" } }] |
| Moment和对应的User | 分两次请求 Moment: base_url/get/moment?userId=38710 User: base_url/get/user?id=38710 |
base_url/get/ { "Moment":{ "userId":38710 }, "User":{ "id":38710 } } |
| User列表 | base_url/get/user/list? page=0&count=3&sex=0 |
base_url/get/ { "User[]":{ "page":0, "count":3, "User":{ "sex":0 } } } |
| Moment列表， 每个Moment包括 1.发布者User 2.前3条Comment |
Moment里必须有 1.User对象 2.Comment数组 base_url/get/moment/list? page=0&count=3&commentCount=3 |
base_url/get/ { "[]":{ "page":0, "count":3, "Moment":{}, "User":{ "id@":"/Moment/userId" }, "Comment[]":{ "count":3, "Comment":{ "momentId@":"[]/Moment/id" } } } } |
| User发布的Moment列表， 每个Moment包括 1.发布者User 2.前3条Comment |
1.Moment里必须有User对象和Comment数组 2.字段名必须查接口文档，例如评论数量字段名可能是 commentCount,comment_count或者简写cmt_count等各种奇葩写法... base_url/get/moment/list? page=0&count=3 &commentCount=3&userId=38710 |
有以下几种方式: ① 把以上请求里的 "Moment":{}, "User":{"id@":"/Moment/userId"} 改为 "Moment":{"userId":38710}, "User":{"id":38710} ② 或把User放在上面的最外层省去重复的User base_url/get/ { "User":{ "id":38710 }, "[]":{ "page":0, "count":3, "Moment":{ "userId":38710 }, "Comment[]":{ "count":3, "Comment":{ "momentId@":"[]/Moment/id" } } } } ③ 如果User之前已经获取到了，还可以不传User来节省请求和返回数据的流量并提升速度 base_url/get/ { "[]":{ "page":0, "count":3, "Moment":{ "userId":38710 }, "Comment[]":{ "count":3, "Comment":{ "momentId@":"[]/Moment/id" } } } } |
| 后端的返回结果 | 传统方式 | JSON-API |
|---|---|---|
| User | { "data":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
{ "User":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
| Moment和对应的User | 分别返回两次请求的结果，获取到Moment后取出userId作为User的id条件去查询User Moment: { "data":{ "id":235, "content":"xxx", ... }, "code":200, "msg":"success" } User: { "data":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
一次性返回，没有传统方式导致的 长时间等待结果、两次结果间关联、线程多次切换 等问题 { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ "id":38710, "name":"xxx", ... }, "code":200, "msg":"success" } |
| User列表 | { "data":[ { "id":38710, "name":"xxx", ... }, { "id":82001, ... }, ... ], "code":200, "msg":"success" } |
{ "User[]":[ { "id":38710, "name":"xxx", ... }, { "id":82001, ... }, ... ], "code":200, "msg":"success" } |
| Moment列表，每个Moment包括发布者User和前3条Comment | Moment里必须有 1.User对象 2.Comment数组 { "data":[ { "id":235, "content":"xxx", ..., "User":{ ... }, "Comment":[ ... ] }, { "id":301, "content":"xxx", ..., "User":{ ... }, ... }, ... ], "code":200, "msg":"success" } |
1.高灵活，可任意组合 2.低耦合，逻辑很清晰 { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ ... }, "Comment[]":[ ... ] }, { "Moment":{ "id":301, "content":"xxx", ... }, "User":{ ... }, ... }, ... ], "code":200, "msg":"success" } |
| User发布的Moment列表，每个Moment包括发布者User和前3条Comment | 1.大量重复User，浪费流量和服务器性能 2.优化很繁琐，需要后端扩展接口、写好文档，前端/前端再配合优化 { "data":[ { "id":235, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":470, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":511, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, { "id":595, "content":"xxx", ..., "User":{ "id":38710, "name":"Tommy" ... }, "Comment":[ ... ] ... }, ... ], "code":200, "msg":"success" } |
以上不同请求方式的结果: ① 常规请求 { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "User":{ "id":38710, "name":"Tommy" ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } ② 省去重复的User { "User":{ "id":38710, "name":"Tommy", ... }, "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } ③ 不查询已获取到的User { "[]":[ { "Moment":{ "id":235, "content":"xxx", ... }, "Comment[]":[ ... ] }, ... ], "code":200, "msg":"success" } |
1.base_url指基地址，一般是顶级域名，其它分支url都是在base_url后扩展。如base_url:http://JSON-API.cn/ ，对应的GET分支url:http://JSON-API.cn/get/ 。下同。
2.请求中的key或value任意一个为null值时，这个 key:value键值对 被视为无效。下同。
3.请求中的 / 需要转义。JSONRequest.java已经用URLEncoder.encode转义，不需要再写；但如果是浏览器或Postman等直接输入url/request，需要把request中的所有 / 都改成 %252F 。下同。
4.retcode，指返回结果中的状态码，200表示成功，其它都是错误码，值全部都是HTTP标准状态码。下同。
5.msg，指返回结果中的状态信息，对成功结果或错误原因的详细说明。下同。
6.retcode和msg总是在返回结果的同一层级成对出现。对所有请求的返回结果都会在最外层有一对总结式code和msg。对非GET类型的请求，返回结果里面的每个JSONObject里都会有一对code和msg说明这个JSONObject的状态。下同。
7.id等字段对应的值仅供说明，不一定是数据库里存在的，请求里用的是真实存在的值。下同。