APIJSON
1.简介
APIJSON是一种JSON传输结构协议。
客户端可以定义任何JSON结构去向服务端发起请求，服务端就会返回对应结构的JSON，所求即所得。
一次请求任意结构任意数据，方便灵活，不需要专门接口或多次请求。
支持增删改查、模糊搜索、远程函数、权限管理等。还能去除重复数据，节省流量提高速度！
从此HTTP传输JSON数据没有接口，更不需要文档！
客户端再也不用和服务端沟通接口或文档问题了！再也不会被文档各种错误坑了！
服务端再也不用为了兼容旧版客户端写新版接口和文档了！再也不会被客户端随时随地没完没了地烦了！
为什么要用APIJSON？
举几个例子:
查询用户
请求：
{
"User":{
}
}
返回：
{
"User":{
"id":38710,
"sex":0,
"name":"TommyLemon",
"certified":true,
"tag":"Android&Java",
"phone":13000038710,
"head":"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"date":1485948110000,
"pictureList":[
"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"http://common.cnblogs.com/images/icon_weibo_24.png"
]
},
"code":200,
"msg":"success"
}
查询用户列表
请求：
{
"[]":{
"count":3, //只要3个
"User":{
"@column":"id,name" //只要id,name这两个字段
}
}
}
返回：
{
"[]":[
{
"User":{
"id":38710,
"name":"TommyLemon"
}
},
{
"User":{
"id":70793,
"name":"Strong"
}
},
{
"User":{
"id":82001,
"name":"Android"
}
}
],
"code":200,
"msg":"success"
}
查询动态及发布者用户
请求：
{
"Moment":{
},
"User":{
"id@":"Moment/userId" //User.id = Moment.userId
}
}
返回：
{
"Moment":{
"id":12,
"userId":70793,
"date":"2017-02-08 16:06:11.0",
"content":"1111534034"
},
"User":{
"id":70793,
"sex":0,
"name":"Strong",
"tag":"djdj",
"head":"http://static.oschina.net/uploads/user/585/1170143_50.jpg?t=1390226446000",
"contactIdList":[
38710,
82002
],
"date":"2017-02-01 19:21:50.0"
},
"code":200,
"msg":"success"
}
查询类似微信朋友圈的动态列表
请求：
{
"[]":{ //请求一个数组
"page":0, //数组条件
"count":2,
"Moment":{ //请求一个名为Moment的对象
"content$":"%a%" //对象条件，搜索content中包含a的动态
},
"User":{
"id@":"/Moment/userId", //User.id = Moment.userId 缺省引用赋值路径，从所处容器的父容器路径开始
"@column":"id,name,head" //指定返回字段
},
"Comment[]":{ //请求一个名为Comment的数组，并去除Comment包装
"count":2,
"Comment":{
"momentId@":"[]/Moment/id" //Comment.momentId = Moment.id 完整引用赋值路径
}
}
}
}
返回：
{
"[]":[
{
"Moment":{
"id":15,
"userId":70793,
"date":1486541171000,
"content":"APIJSON is a JSON Transmission Structure Protocol…",
"praiseUserIdList":[
82055,
82002,
82001
],
"pictureList":[
"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000",
"http://common.cnblogs.com/images/icon_weibo_24.png"
]
},
"User":{
"id":70793,
"name":"Strong",
"head":"http://static.oschina.net/uploads/user/585/1170143_50.jpg?t=1390226446000"
},
"Comment[]":[
{
"id":176,
"toId":166,
"userId":38710,
"momentId":15,
"date":1490444883000,
"content":"thank you"
},
{
"id":1490863469638,
"toId":0,
"userId":82002,
"momentId":15,
"date":1490863469000,
"content":"Just do it"
}
]
},
{
"Moment":{
"id":58,
"userId":90814,
"date":1485947671000,
"content":"This is a Content...-435",
"praiseUserIdList":[
38710,
82003,
82005,
93793,
82006,
82044,
82001
],
"pictureList":[
"http://static.oschina.net/uploads/img/201604/22172507_aMmH.jpg"
]
},
"User":{
"id":90814,
"name":7,
"head":"http://static.oschina.net/uploads/user/51/102723_50.jpg?t=1449212504000"
},
"Comment[]":[
{
"id":13,
"toId":0,
"userId":82005,
"momentId":58,
"date":1485948050000,
"content":"This is a Content...-13"
},
{
"id":77,
"toId":13,
"userId":93793,
"momentId":58,
"date":1485948050000,
"content":"This is a Content...-77"
}
]
}
],
"code":200,
"msg":"success"
}
2.对比传统RESTful方式
2.1 开发流程
开发流程
传统方式
APIJSON
接口传输
等服务端编辑接口，然后更新文档，客户端再按照文档编辑请求和解析代码
客户端按照自己的需求编辑请求和解析代码。
没有接口，更不需要文档！客户端再也不用和服务端沟通接口或文档问题了！
兼容旧版
服务端增加新接口，用v2表示第2版接口，然后更新文档
什么都不用做！
2.2 客户端请求
客户端请求
传统方式
APIJSON
要求
客户端按照文档在对应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
2.3 服务端操作
服务端操作
传统方式
APIJSON
解析和返回
取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给客户端
把Parser#parse方法的返回值返回给客户端就行
返回JSON结构的设定方式
由服务端设定，客户端不能修改
由客户端设定，服务端不能修改
2.4 客户端解析
客户端解析
传统方式
APIJSON
查看方式
查文档或问后端，或等请求成功后看日志
看请求就行，所求即所得，不用查、不用问、不用等。也可以等请求成功后看日志
解析方法
用JSON解析器来解析JSONObject
可以用JSONResponse解析JSONObject，或使用传统方式
2.5 客户端对应不同需求的请求
2.6 服务端对应不同请求的返回结果
服务端的返回结果
传统方式
APIJSON
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://www.google.com/ ，对应的GET分支url:http://www.google.com/get/ 。下同。
2.请求中的key或value任意一个为null值时，这个 key:value键值对 被视为无效。下同。
3.请求中的 / 需要转义。JSONRequest.java已经用URLEncoder.encode转义，不需要再写；但如果是浏览器或Postman等直接输入url/request，需要把request中的所有 / 都改成 %252F 。下同。
4.code，指返回结果中的状态码，200表示成功，其它都是错误码，值全部都是HTTP标准状态码。下同。
5.msg，指返回结果中的状态信息，对成功结果或错误原因的详细说明。下同。
6.code和msg总是在返回结果的同一层级成对出现。对所有请求的返回结果都会在最外层有一对总结式code和msg。对非GET类型的请求，返回结果里面的每个JSONObject里都会有一对code和msg说明这个JSONObject的状态。下同。
7.id等字段对应的值仅供说明，不一定是数据库里存在的，请求里用的是真实存在的值。下同。
3.对应关系总览
3.1 操作方法
方法及说明
URL
Request
Response
GET:
普通获取数据，
明文，
可用浏览器调试
base_url/get/
{
TableName:{
…
}
}
{…}内为限制条件
例如获取一个id为235的Moment：
{
"Moment":{
"id":235
}
}
{
TableName:{
...
},
"code":200,
"msg":"success"
}
例如
{
"Moment":{
"id":235,
"userId":38710,
"content":"APIJSON,let interfaces and documents go to hell !"
},
"code":200,
"msg":"success"
}
HEAD:
普通获取数量，
明文，
可用浏览器调试
base_url/head/
{
TableName:{
…
}
}
{…}内为限制条件
例如获取一个id为38710的User所发布的Moment总数：
{
"Moment":{
"userId":38710
}
}
{
TableName:{
"code":200,
"msg":"success",
"count":10
},
"code":200,
"msg":"success"
}
例如
{
"Moment":{
"code":200,
"msg":"success",
"count":10
},
"code":200,
"msg":"success"
}
POST_GET:
安全/私密获取数据，
非明文，
用于获取钱包等
对安全性要求高的数据
base_url/post_get/
最外层加一个"tag":tag，其它同GET
同GET
POST_HEAD:
安全/私密获取数量，
非明文，
用于获取银行卡数量等
对安全性要求高的数据总数
base_url/post_head/
最外层加一个"tag":tag，其它同HEAD
同HEAD
POST:
新增数据，
非明文
base_url/post/
{
TableName:{
…
},
"tag":tag
}
{…}中id由服务端生成，不能传
例如一个id为38710的User发布一个新Moment：
{
"Moment":{
"userId":38710,
"content":"APIJSON,let interfaces and documents go to hell !"
},
"tag":"Moment"
}
{
TableName:{
"code":200,
"msg":"success",
"id":38710
},
"code":200,
"msg":"success"
}
例如
{
"Moment":{
"code":200,
"msg":"success",
"id":120
},
"code":200,
"msg":"success"
}
PUT:
修改数据，
非明文，
只修改所传的字段
base_url/put/
{
TableName:{
"id":id,
…
},
"tag":tag
}
{…}中id必传
例如修改id为235的Moment的content：
{
"Moment":{
"id":235,
"content":"APIJSON,let interfaces and documents go to hell !"
},
"tag":"Moment"
}
同POST
DELETE:
删除数据，
非明文
base_url/delete/
{
TableName:{
"id":id
},
"tag":tag
}
{…}中id必传，一般只传id
例如删除id为120的Moment：
{
"Moment":{
"id":120
},
"tag":"Moment"
}
同POST
1.TableName指要查询的数据库表Table的名称字符串。第一个字符为大写字母，剩下的字符要符合英语字母、数字、下划线中的任何一种。对应的值的类型为JSONObject，结构是 {...}，里面放的是Table的字段(列名)。下同。
2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的key，一般是要查询的table的名称，由服务端Request表中指定。下同。
3.GET、HEAD请求是开放请求，可任意组合任意嵌套。其它请求为受限制的安全/私密请求，对应的 方法、tag、结构 都必须和 服务端Request表中所指定的 一一对应，否则请求将不被通过。下同。
4.POST_GET与GET、POST_HEAD与HEAD分别为同一类型的操作方法，请求稍有不同但返回结果相同。下同。
5.在HTTP通信中，GET、HEAD方法一般用HTTP GET请求，其它一般用HTTP POST请求。下同。
6.所有JSONObject都视为容器(或者文件夹)，结构为 {...} ，里面可以放普通对象或子容器。下同。
7.每个对象都有一个唯一的路径(或者叫地址)，假设对象名为refKey，则用 key0/key1/.../refKey 表示。下同。
3.2 功能符
功能
键值对格式
使用示例
查询数组
"key[]":{}，后面是JSONObject，key可省略。当key和里面的Table名相同时，Table会被提取出来，即 {Table:{Content}} 会被转化为 {Content}
{"User[]":{"User":{}}}，查询一个User数组。这里key和Table名都是User，User会被提取出来，即 {"User":{"id", ...}} 会被转化为 {"id", ...}
匹配选项范围
"key{}":[]，后面是JSONArray，作为key可取的值的选项
"id{}":[38710,82001,70793]，查询id符合38710,82001,70793中任意一个的一个User数组
匹配条件范围
"key{}":"条件0,条件1..."，条件为任意SQL比较表达式字符串，非Number类型必须用''包含条件的值，如'a'
"id{}":"<=80000,>90000"，查询id符合id<=80000 | id>90000的一个User数组
包含选项范围
"key<>":Object => "key<>":[Object]，key对应值的类型必须为JSONArray，Object类型不能为JSON
"contactIdList<>":38710，查询contactIdList包含38710的一个User数组
远程调用函数
"key()":"函数表达式"，函数表达式为 function(Type0:value0,Type1:value1...)。函数参数类型为Object或泛型时可省略类型，即 Object:value 改写为 value
"isPraised()":"isContain(Collection:praiseUserIdList,userId)"，请求完成后会调用 boolean isContain(Collection collection, Object object) 函数，然后变为 "isPraised":true 这种(假设点赞用户id列表包含了userId，即这个User点了赞)
引用赋值
"key@":"引用路径"，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明key所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。
被引用的refKey必须在声明key的上面。如果对refKey的容器指定了返回字段，则被引用的refKey必须写在@column对应的值内，例如 "@column":"refKey,key1,..."
"Moment":{
"userId":38710
},
"User":{
"id@":"/Moment/userId"
}
User内的id引用了与User同级的Moment内的userId，
即User.id = Moment.userId，请求完成后
"id@":"/Moment/userId" 会变成 "id":38710
模糊搜索
"key$":"SQL搜索表达式" => "key$":["SQL搜索表达式"]，任意SQL搜索表达式字符串，如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等，%表示任意字符
"name$":"%m%"，查询name包含"m"的一个User数组
正则匹配
"key?":"正则表达式" => "key?":["正则表达式"]，任意正则表达式字符串，如 ^[0-9]+$ ，可用于高级搜索
"name?":"^[0-9]+$"，查询name中字符全为数字的一个User数组
新建别名
"name:alias"，name映射为alias，用alias替代name。可用于 column,Table,SQL函数 等。只用于GET类型、HEAD类型的请求
增加 或 扩展
"key+":Object，Object的类型由key指定，且类型为Number,String,JSONArray中的一种。如 82001,"apijson",["url0","url1"] 等。只用于PUT请求
"praiseUserIdList+":[82001]，添加一个点赞用户id，即这个用户点了赞
减少 或 去除
"key-":Object，与"key+"相反
"balance-":100.00，余额减少100.00，即花费了100元
逻辑运算
&, |, ! 逻辑运算符。
① & 可用于"key&{}":"条件"等
② | 可用于"key|{}":"条件", "key|{}":[]等，一般可省略
③ ! 可单独使用，如"key!":Object，也可像&,|一样配合其他功能符使用
① "id&{}":">80000,<=90000"，即id满足id>80000 & id<=90000
② "id|{}":">90000,<=80000"，同"id{}":">90000,<=80000"，即id满足id>90000 | id<=80000
③ "id!{}":[82001,38710]，即id满足 ! (id=82001 | id=38710)，可过滤黑名单的消息
数组关键词
"key":Object，key为 "[]":{} 中{}内的关键词，Object的类型由key指定
① "count":Integer，指定查询数量，假设允许查询数组的最大数量为max，则当count在1~max范围内时，查询count个；否则查询max个
② "page":Integer，指定查询页码，从0开始，一般和count一起用
③ "query":Integer，指定查询内容
0-对象，1-总数，2-以上全部
总数关键词为total，和query同级，通过引用赋值得到，如 "total@":"/[]/total"
这里query及total仅为GET类型的请求提供方便，一般可直接用HEAD类型的请求获取总数
对象关键词，可自定义
"@key":Object，@key为 Table:{} 中{}内的关键词，Object的类型由@key指定
① "@about":true, 查询字段属性
② "@column":"key0,key1...", 指定返回字段
③ "@order":"key0,key1+,key2-..."，指定排序方式
④ "@group":"key0,key1,key2..."，指定分组方式。如果@column里声明了Table的id，则id也必须在@group中声明；其它情况下必须满足至少一个条件:
1.分组的key在@column里声明
2.Table主键在@group中声明
⑤ "@having":"function0(...)?valu0,function1(...)?valu1,function2(...)?value2..."，指定SQL函数条件，一般和@group一起用，函数一般在@column里声明
4.快速上手
4.1 下载后解压APIJSON工程
Clone or download > Download ZIP > 解压到一个路径并记住这个路径。
你可以跳过步骤4.2和步骤4.3，用我的服务器IP地址 139.196.140.118:8080 来测试服务端对客户端请求的返回结果。
4.2 导入表文件到数据库
服务端需要MySQL Server和MySQLWorkbench，没有安装的都先下载安装一个。
我的配置是Windows 7 + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.7 和 OSX EI Capitan + MySQL Community Server 5.7.16 + MySQLWorkbench 6.3.8，其中系统和软件都是64位的。
启动MySQLWorkbench > 进入一个Connection > 点击Server菜单 > Data Import > 选择刚才解压路径下的APIJSON-Master/table > Start Import > 刷新SCHEMAS, 左下方sys/tables会出现添加的table。
4.3 用Eclipse for JavaEE或IntellIJ IDEA Ultimate运行服务端工程
如果以上编辑器一个都没安装，运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + Eclipse 4.6.1 + IntellIJ 2016.3 和 OSX EI Capitan + JDK 1.8.0_91 + Eclipse 4.6.1 + IntellIJ 2016.2.5
Eclipse for JavaEE
1.导入
File > Import > Maven > Existing Maven Projects > Next > Browse > 选择刚才解压路径下的APIJSON-Master/APIJSON(Server)/APIJSON(Eclipse_JEE) > Finish
2.运行
Run > Run As > Java Application > 选择APIJSONApplication > OK
IntellIJ IDEA Ultimate
1.导入
Open > 选择刚才解压路径下的APIJSON-Master/APIJSON(Server)/APIJSON(Idea) > OK
2.运行
Run > Run APIJSONApplication
4.4 用ADT Bundle或Android Studio运行客户端工程
可以跳过这个步骤，直接下载下方提供的客户端App。
如果以上编辑器一个都没安装，运行前先下载安装一个。
我的配置是Windows 7 + JDK 1.7.0_71 + ADT Bundle 20140702 + Android Studio 2.2 和 OSX EI Capitan +(JDK 1.7.0_71 + ADT Bundle 20140702)+(JDK 1.8.0_91 + Android Studio 2.1.2)，其中系统和软件都是64位的。
ADT Bundle
1.导入
File > Import > Android > Existing Android Code Into Workspace > Next > Browse > 选择刚才解压路径下的APIJSON-Master/APIJSON(Android)/APIJSON(ADT) > Finish
2.运行
Run > Run As > Android Application
Android Studio
1.导入
Open an existing Android Studio project > 选择刚才解压路径下的APIJSON-Master/APIJSON(Android)/APIJSON(AndroidStudio)/APIJSONApp (或APIJSONTest) > OK
2.运行
Run > Run app
4.5 操作客户端App
选择发送APIJSON请求并等待显示结果。
如果默认url不可用，修改为一个可用的，比如正在运行APIJSON服务端工程的电脑的IPV4地址，然后点击查询按钮重新请求。
5.其它
5.1 相关推荐
5.2 关于作者
如果有什么问题或建议可以提ISSUE、加群或者发我邮件，交流技术，分享经验。
如果你解决了某些bug，或者新增了一些通用性强的功能，欢迎贡献代码，感激不尽^_^
5.3 下载试用客户端App
5.4 更新日志
5.5 点Star支持我，点Fork研究它
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
