中文 | English

APIJSON 通用文档

本文是通用文档，只和 APIJSON 协议有关，和 C#, Go, Java, JavaScript, PHP, Python, TypeScript 等开发语言无关。

具体开发语言相关的 配置、运行、部署 等文档见各个相关项目的文档，可以在首页点击对应语言的入口来查看。

https://github.com/Tencent/APIJSON

后端开发者可以先看 图文入门教程1 或 图文入门教程2 （和本文档有出入的点以本文档为准。例如正则匹配 key? 已废弃，用 key~ 替代；例如 "@column":"store_id,sum(amt):totAmt" 中逗号 , 有误，应该用分号 ; 隔开 SQL 函数，改为 "@column":"store_id;sum(amt):totAmt"）

• 1.示例

• 2.对比传统方式

• 2.1 开发流程
• 2.2 前端请求
• 2.3 后端操作
• 2.4 前端解析
• 2.5 对应不同需求的请求
• 2.6 对应不同请求的结果

• 3.设计规范

• 3.1 操作方法
• 3.2 功能符

<h2 id="1">1.示例<h2/>

获取用户

请求：

<pre><code class="language-json">{ "User":{ "id":38710 } } </code></pre>

点击这里测试

返回：

<pre><code class="language-json">{ "User":{ "id":38710, "sex":0, "name":"TommyLemon", "tag":"Android&Java", "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" } </code></pre> <p align="center" > <a >[GIF] APIJSON 各种单表对象查询：简单查询、统计、分组、排序、聚合、比较、筛选字段、字段别名 等</a> </p>

获取用户列表

请求：

<pre><code class="language-json">{ "[]":{ "count":3, //只要3个 "User":{ "@column":"id,name" //只要id,name这两个字段 } } } </code></pre>

点击这里测试

返回：

<pre><code class="language-json">{ "[]":[ { "User":{ "id":38710, "name":"TommyLemon" } }, { "User":{ "id":70793, "name":"Strong" } }, { "User":{ "id":82001, "name":"Android" } } ], "code":200, "msg":"success" } </code></pre> <p align="center" > <a >[GIF] APIJSON 各种单表数组查询：简单查询、统计、分组、排序、聚合、分页、比较、搜索、正则、条件组合 等</a> </p>

获取动态及发布者用户

请求：

<pre><code class="language-json">{ "Moment":{ }, "User":{ "id@":"Moment/userId" //User.id = Moment.userId } } </code></pre>

点击这里测试

返回：

<pre><code class="language-json">{ "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" } </code></pre>

获取类似微信朋友圈的动态列表

请求：

<pre><code class="language-json">{ "[]":{ //请求一个数组 "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 完整引用赋值路径 } } } } </code></pre>

点击这里测试

返回：

<pre><code class="language-json">{ "[]":[ { "Moment":{ "id":15, "userId":70793, "date":1486541171000, "content":"APIJSON is a JSON Transmission 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" } </code></pre> <p align="center" > <a >[GIF] APIJSON 各种多表关联查询：一对一、一对多、多对一、各种条件 等</a> </p>

<p align="center" > <a >[GIF] APIJSON 各种 JOIN：< LEFT JOIN, & INNER JOIN 等</a> </p>

<p align="center" > <a >[GIF] APIJSON 各种子查询：@from@ FROM, key@ =, key>@ >, key{}@ IN, key}{@ EXISTS 等 </a> </p>

<p align="center" > <a >[GIF] APIJSON 部分功能演示集合，由浅入深、由简单到复杂 </a> </p>

在线测试

<h2 id="2">2.对比传统RESTful方式<h2/>

<h3 id="2.1">2.1 开发流程<h3/>

开发流程	传统方式	APIJSON
接口传输	等后端编辑接口，然后更新文档，前端再按照文档编辑请求和解析代码	前端按照自己的需求编辑请求和解析代码。
没有接口，更不需要文档！前端再也不用和后端沟通接口或文档问题了！
兼容旧版	后端增加新接口，用v2表示第2版接口，然后更新文档	什么都不用做！

<h3 id="2.2">2.2 前端请求<h3/>

前端请求	传统方式	APIJSON
要求	前端按照文档在对应URL后面拼接键值对	前端按照自己的需求在固定URL后拼接JSON
URL	不同的请求对应不同的URL，基本上有多少个不同的请求就得有多少个接口URL	相同的操作方法(增删改查)都用同一个URL，
大部分请求都用7个通用接口URL的其中一个
键值对	key=value	key:value
结构	同一个URL内table_name只能有一个

base_url/get/table_name? key0=value0&key1=value1... | 同一个URL后TableName可传任意数量个

base_url/get/ {    TableName0:{      key0:value0,      key1:value1,      ...    },    TableName1:{      ...    }    ... }

<h3 id="2.3">2.3 后端操作<h3/>

后端操作	传统方式	APIJSON
解析和返回	取出键值对，把键值对作为条件用预设的的方式去查询数据库，最后封装JSON并返回给前端	把Parser#parse方法的返回值返回给前端就行
返回JSON结构的设定方式	由后端设定，前端不能修改	由前端设定，后端不能修改

<h3 id="2.4">2.4 前端解析<h3/>

前端解析	传统方式	APIJSON
查看方式	查文档或问后端，或等请求成功后看日志	看请求就行，所求即所得，不用查、不用问、不用等。也可以等请求成功后看日志
解析方法	用JSON解析器来解析JSONObject	可以用JSONResponse解析JSONObject，或使用传统方式

<h3 id="2.5">2.5 前端对应不同需求的请求<h3/>

前端的请求	传统方式	APIJSON
User	base_url/get/user?id=38710	[base_url/get/
{
"User":{
"id":38710
}
}](http://apijson.cn:8080/get/{"User":{"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"        }      }    } }

<h3 id="2.6">2.6 后端对应不同请求的返回结果<h3/>

后端的返回结果	传统方式	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://apijson.cn:8080/ ，对应的GET分支url:http://apijson.cn:8080/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。下同。

7.id等字段对应的值仅供说明，不一定是数据库里存在的，请求里用的是真实存在的值。下同。

<h2 id="3">3.设计规范<h2/>

<h3 id="3.1">3.1 操作方法<h3/>

方法及说明	URL	Request	Response
GET:
普通获取数据，
可用浏览器调试	base_url/get/	{
TableName:{
…
}
}
{…}内为限制条件

例如获取一个 id = 235 的 Moment： {    "Moment":{      "id":235    } } 后端校验通过后自动解析为 SQL 并执行： SELECT * FROM Moment WHERE id=235 LIMIT 1 | {    TableName:{      ...    },    "code":200,    "msg":"success" } 例如 {    "Moment":{      "id":235,      "userId":38710,      "content":"APIJSON is the real-time coding-free, powerful and secure ORM"    },    "code":200,    "msg":"success" } HEAD: 普通获取数量， 可用浏览器调试 | base_url/head/ | {    TableName:{      …    } } {…}内为限制条件

例如获取一个 id = 38710 的 User 所发布的 Moment 总数： {    "Moment":{      "userId":38710    } } 后端校验通过后自动解析为 SQL 并执行： SELECT count(*) FROM Moment WHERE userId=38710 LIMIT 1 | {    TableName:{      "code":200,      "msg":"success",      "count":10    },    "code":200,    "msg":"success" } 例如 {    "Moment":{      "code":200,      "msg":"success",      "count":10    },    "code":200,    "msg":"success" } GETS: 安全/私密获取数据， 用于获取钱包等 对安全性要求高的数据 | base_url/gets/ | 最外层加一个 "tag":tag，例如 "tag":"Privacy"，其它同GET | 同GET HEADS: 安全/私密获取数量， 用于获取银行卡数量等 对安全性要求高的数据总数 | base_url/heads/ | 最外层加一个 "tag":tag，例如 "tag":"Verify"，其它同HEAD | 同HEAD POST: 新增数据 | base_url/post/ | 单个： {    TableName:{      …    },    "tag":tag } {…}中id由后端生成，不能传

例如当前登录用户 38710 发布一个新 Comment： {    "Comment":{      "momentId":12,      "content":"APIJSON is the real-time coding-free, powerful and secure ORM"    },    "tag":"Comment" } 后端校验通过后自动解析为 SQL 并执行： INSERT INTO Comment(userId,momentId,content) VALUES(38710,12,'APIJSON is the real-time coding-free, powerful and secure ORM')

批量： {    TableName[]:[{        …      }, {        …      }      …    ],    "tag":tag } {…}中id由后端生成，不能传

例如当前登录用户 82001 发布 2 个 Comment： {    "Comment[]":[{      "momentId":12,      "content":"APIJSON is the real-time coding-free, powerful and secure ORM"      }, {      "momentId":15,      "content":"APIJSON is a JSON transmision protocol."    }],    "tag":"Comment:[]" } 后端校验通过后自动解析为 SQL 并执行： INSERT INTO Comment(userId,momentId,content) VALUES(82001,12,'APIJSON is the real-time coding-free, powerful and secure ORM');

INSERT INTO Comment(userId,momentId,content) VALUES(82001,15,'APIJSON is a JSON transmision protocol.'); | 单个： {    TableName:{      "code":200,      "msg":"success",      "id":38710    },    "code":200,    "msg":"success" } 例如 {    "Comment":{      "code":200,      "msg":"success",      "id":120    },    "code":200,    "msg":"success" }

批量： {    TableName:{      "code":200,      "msg":"success",      "count":5,      "id[]":[1, 2, 3, 4, 5]    },    "code":200,    "msg":"success" } 例如 {    "Comment":{      "code":200,      "msg":"success",      "count":2,      "id[]":[1, 2]    },    "code":200,    "msg":"success" } PUT: 修改数据， 只修改所传的字段 | base_url/put/ | {    TableName:{      "id":id,      …    },    "tag":tag } {…} 中 id 或 id{} 至少传一个

例如当前登录用户 82001 修改 id = 235 的 Moment 的 content： {    "Moment":{      "id":235,      "content":"APIJSON is the real-time coding-free, powerful and secure ORM"    },    "tag":"Moment" } 后端校验通过后自动解析为 SQL 并执行： UPDATE Moment SET content='APIJSON is the real-time coding-free, powerful and secure ORM' WHERE id=235 AND userId=82001 LIMIT 1

批量除了 id{}:[] 也可类似批量 POST，只是每个 {...} 里面都必须有 id。 "tag":"Comment[]" 对应对象 "Comment":{"id{}":[1,2,3]}，表示指定记录全部统一设置； "tag":"Comment:[]" 多了冒号，对应数组 "Comment[]":[{"id":1},{"id":2},{"id":3}]，表示每项单独设置 | 同POST DELETE: 删除数据 | base_url/delete/ | {    TableName:{      "id":id    },    "tag":tag } {…} 中 id 或 id{} 至少传一个，一般只传 id 或 id{}

例如当前登录用户 82001 批量删除 id = 100,110,120 的 Comment： {    "Comment":{      "id{}":[100,110,120]    },    "tag":"Comment[]" } 后端校验通过后自动解析为 SQL 并执行： DELETE FROM Comment WHERE id IN(100,110,120) AND userId=82001 LIMIT 3 | {    TableName:{      "code":200,      "msg":"success",      "id[]":[100,110,120]       "count":3    },    "code":200,    "msg":"success" } 例如 {    "Comment":{       "code":200,       "msg":"success",       "id[]":[100,110,120],       "count":3    },    "code":200,    "msg":"success" } 以上接口的简单形式: base_url/{method}/{tag} | GET: 普通获取数据 base_url/get/{tag}

HEAD: 普通获取数量 base_url/head/{tag}

GETS: 安全/私密获取数据 base_url/gets/{tag}

HEADS: 安全/私密获取数量 base_url/heads/{tag}

POST: 新增数据 base_url/post/{tag}

PUT: 修改数据 base_url/put/{tag}

DELETE: 删除数据 base_url/delete/{tag} | 例如安全/私密获取一个 id = 82001 的 Privacy： base_url/gets/Privacy/ {"id":82001} 相当于 base_url/gets/ {"tag":"Privacy", "Privacy":{"id":82001}}

例如批量修改 id = 114, 124 的 Comment 的 content： base_url/put/Comemnt[]/ {    "id{}":[114,124],    "content":"test multi put" } 相当于 base_url/put/ {    "tag":"Comment[]",    "Comment":{      "id{}":[114,124],      "content":"test multi put"    } } | 同以上对应的方法

1.TableName指要查询的数据库表Table的名称字符串。第一个字符为大写字母，剩下的字符要符合英语字母、数字、下划线中的任何一种。对应的值的类型为JSONObject，结构是 {...}，里面放的是Table的字段(列名)。下同。

2."tag":tag 后面的tag是非GET、HEAD请求中匹配请求的JSON结构的标识，一般是要查询的Table的名称，由后端Request表中指定。下同。

3.GET、HEAD请求是开放请求，可任意组合任意嵌套。其它请求为受限制的安全/私密请求，对应的 方法（method）, 标识（tag）, 版本（version）, 结构（structure） 都必须和 后端Request表中所指定的 一一对应，否则请求将不被通过。version 不传、为 null 或 <=0 都会使用最高版本，传了其它有效值则会使用最接近它的最低版本。下同。

4.GETS与GET、HEADS与HEAD分别为同一类型的操作方法，请求稍有不同但返回结果相同。下同。

5.在HTTP通信中，自动化接口(get,gets,head,heads,post,put,delete) 全用HTTP POST请求。下同。

6.所有JSONObject都视为容器(或者文件夹)，结构为 {...} ，里面可以放普通对象或子容器。下同。

7.每个对象都有一个唯一的路径(或者叫地址)，假设对象名为refKey，则用 key0/key1/.../refKey 表示。下同。

<h3 id="3.2">3.2 功能符<h3/>

功能	键值对格式	使用示例
查询数组	"key[]":{}，后面是 JSONObject，key 可省略。当 key 和里面的 Table 名相同时，Table 会被提取出来，即 {Table:{Content}} 会被转化为 {Content}	{"User[]":{"User":{}}}，查询一个 User 数组。这里 key 和 Table 名都是 User，User 会被提取出来，即 {"User":{"id", ...}} 会被转化为 {"id", ...}，如果要进一步提取 User 中的 id，可以把 User[] 改为 User-id[]，其中 - 用来分隔路径中涉及的 key
匹配选项范围	"key{}":[]，后面是 JSONArray，作为 key 可取的值的选项	"id{}":[38710,82001,70793]，对应 SQL 是id IN(38710,82001,70793)，查询 id 符合 38710,82001,70793 中任意一个的一个 User 数组
匹配条件范围	"key{}":"条件0,条件1..."，条件为 SQL 表达式字符串，可进行数字比较运算等	"id{}":"<=80000,>90000"，对应 SQL 是id<=80000 OR id>90000，查询 id 符合 id<=80000 | id>90000 的一个 User 数组
包含选项范围	"key<>":value => "key<>":[value]，key 对应值的类型必须为 JSONArray，value 值类型只能为 Boolean, Number, String 中的一种	"contactIdList<>":38710，对应SQL是json_contains(contactIdList,38710)，查询 contactIdList 包含 38710 的一个 User 数组
判断是否存在	"key}{@":{
"from":"Table",
"Table":{ ... }
}
其中：
}{ 表示 EXISTS；
key 用来标识是哪个判断；
@ 后面是 子查询 对象，具体见下方 子查询 的说明。	["id}{@":{
"from":"Comment",
"Comment":{
"momentId":15
}
}](http://apijson.cn:8080/get/{"User":{"id}{@":{"from":"Comment","Comment":{"momentId":15}}}})
WHERE EXISTS(SELECT * FROM Comment WHERE momentId=15)
远程调用函数	"key()":"函数表达式"，函数表达式为 function(key0,key1...)，会调用后端对应的函数 function(JSONObject request, String key0, String key1...)，实现 参数校验、数值计算、数据同步、消息推送、字段拼接、结构变换 等特定的业务逻辑处理，
可使用 - 和 + 表示优先级，解析 key-() > 解析当前对象 > 解析 key() > 解析子对象 > 解析 key+()	"isPraised()":"isContain(praiseUserIdList,userId)"，会调用远程函数 boolean isContain(JSONObject request, String array, String value) ，然后变为 "isPraised":true 这种（假设点赞用户id列表包含了userId，即这个User点了赞）
存储过程	"@key()":"SQL函数表达式"，函数表达式为
function(key0,key1...)
会调用后端数据库对应的存储过程 SQL函数
function(String key0, String key1...)
除了参数会提前赋值，其它和 远程函数 一致	["@limit":10,
"@offset":0,
"@procedure()":"getCommentByUserId(id,@limit,@offset)"](http://apijson.cn:8080/get/{"User":{"@limit":10,"@offset":0,"@procedure()":"getCommentByUserId(id,@limit,@offset)"}})
会转为
getCommentByUserId(38710,10,0)
来调用存储过程 SQL 函数
getCommentByUserId(IN id bigint, IN limit int, IN offset int)
然后变为
"procedure":{
"count":-1,
"update":false,
"list":[]
}
其中 count 是指写操作影响记录行数，-1 表示不是写操作；update 是指是否为写操作（增删改）��list 为返回结果集
引用赋值	"key@":"key0/key1/.../refKey"，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明key所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。
被引用的refKey必须在声明key的上面。如果对refKey的容器指定了返回字段，则被引用的refKey必须写在@column对应的值内，例如 "@column":"refKey,key1,..."	["Moment":{
"userId":38710
},
"User":{
"id@":"/Moment/userId"
}](http://apijson.cn:8080/get/{"Moment":{"userId":38710},"User":{"id@":"%252FMoment%252FuserId"}})
User内的id引用了与User同级的Moment内的userId，
即User.id = Moment.userId，请求完成后
"id@":"/Moment/userId" 会变成 "id":38710
子查询	"key@":{
"range":"ALL",
"from":"Table",
"Table":{ ... }
}
其中：
range 可为 ALL,ANY；
from 为目标表 Table 的名称；
@ 后面的对象类似数组对象，可使用 count 和 join 等功能。	["id@":{
"from":"Comment",
"Comment":{
"@column":"min(userId)"
}
}](http://apijson.cn:8080/get/{"User":{"id@":{"from":"Comment","Comment":{"@column":"min(userId)"}}}})
WHERE id=(SELECT min(userId) FROM Comment)
模糊搜索	"key$":"SQL搜索表达式" => "key$":["SQL搜索表达式"]，任意SQL搜索表达式字符串，如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等，%表示任意字符	"name$":"%m%"，对应SQL是name LIKE '%m%'，查询name包含"m"的一个User数组
正则匹配	"key~":"正则表达式" => "key~":["正则表达式"]，任意正则表达式字符串，如 ^[0-9]+$ ，*~ 忽略大小写，可用于高级搜索	"name~":"^[0-9]+$"，对应SQL是name REGEXP '^[0-9]+$'，查询name中字符全为数字的一个User数组
连续范围	"key%":"start,end" => "key%":["start,end"]，其中 start 和 end 都只能为 Boolean, Number, String 中的一种，如 "2017-01-01,2019-01-01" ，["1,90000", "82001,100000"] ，可用于连续范围内的筛选	"date%":"2017-10-01,2018-10-01"，对应SQL是date BETWEEN '2017-10-01' AND '2018-10-01'，查询在2017-10-01和2018-10-01期间注册的用户的一个User数组
新建别名	① "name:alias"，name 映射为 alias，用 alias 替代 name，可用于 column,Table,SQL 函数 等，只用于 GET 类型、HEAD 类型的请求

② 函数调用映射 "@key": "fun:avg(id);keyA:(keyB)", "fun>": 1, "keyA": 1 其中 fun:fun(arg) 把 SQL 函数调用 fun(arg) 作为左侧表达式替代 fun，即 fun(arg) > 1； keyA:(keyB) 表示将字段 keyA 重命名为 keyB，即实际 SQL 中为 keyB = 1，常用于重命名冲突的多条件同名字段。 | ① "@column":"toId:parentId"，对应 SQL 是 toId AS parentId，将查询的字段 toId 变为 parentId 返回

② "@key": "len:length(content);mid:(momentId)", "len<=": 10, "mid": 12, "momentId": 15, "@combine": "(len<= \| mid) & momentId" 对应 SQL 是 (length(content) <= 10 OR momentId = 12) AND momentId = 15 增加 或 扩展 | "key+":Object，Object的类型由key指定，且类型为Number,String,JSONArray中的一种。如 82001,"apijson",["url0","url1"] 等。只用于PUT请求 | "praiseUserIdList+":[82001]，对应SQL是json_insert(praiseUserIdList,82001)，添加一个点赞用户id，即这个用户点了赞 减少 或 去除 | "key-":Object，与"key+"相反 | "balance-":100.00，对应SQL是balance = balance - 100.00，余额减少100.00，即花费了100元 比较运算 | >, <, >=, <= 比较运算符，用于 ① 提供 "id{}":"<=90000" 这种条件范围的简化写法

② 实现子查询相关比较运算

不支持 "key=":Object 和 "key!=":Object 这两种写法，直接用更简单的 "key":Object 和 "key!":Object 替代。 | ① "id<=":90000，对应 SQL 是id<=90000，查询符合id<=90000的一个User数组

② "id>@":{    "from":"Comment",    "Comment":{       "@column":"min(userId)"    } } WHERE id>(SELECT min(userId) FROM Comment) 逻辑运算 | &, |, ! 逻辑运算符，对应数据库 SQL 中的 AND, OR, NOT。 横或纵与：同一键值对的值内条件默认 | 或连接，可以在 key 后加逻辑运算符来具体指定；不同键值对的条件默认 & 与连接，可以用下面说明的对象关键词 @combine 来具体指定。

① & 可用于 "key&{}":"条件"等

② | 可用于 "key|{}":"条件", "key|{}":[]等，一般可省略

③ ! 可单独使用，如 "key!":Object，也可像 &,| 一样配合其他功能符使用 "key!":null 无效，null 值会导致整个键值对被忽略解析，可以用 "key{}":"!=null" 替代， "key":null 同理，用 "key{}":"=null" 替代。 | ① "id&{}":">80000,<=90000"，对应SQL是id>80000 AND id<=90000，即id满足id>80000 & id<=90000

② "id|{}":">90000,<=80000"，同 "id{}":">90000,<=80000"，对应 SQL 是id>90000 OR id<=80000，即 id 满足 id>90000 | id<=80000

③ "id!{}":[82001,38710]，对应 SQL 是id NOT IN(82001,38710)，即 id 满足 ! (id=82001 | id=38710)，可过滤黑名单的消息 数组关键词，可自定义 | "key":Object，key为 "[]":{} 中 {} 内的关键词，Object 的类型由 key 指定

① "count":5，查询数量，0 表示最大值，默认值为 10，默认最大值为 100

② "page":1，查询页码，从 0 开始，默认值为 0，默认最大值为 100，一般和 count 一起用

③ "query":2，查询内容 0-对象，1-总数和分页详情，2-数据、总数和分页详情 总数关键词为 total，分页详情关键词为 info， 它们都和 query 同级，通过引用赋值得到自定义 key:value 键值对，不传则返回默认键值对，例如
"total@":"/[]/total", "info@":"/[]/info" 这里query及total仅为GET类型的请求提供方便， 一般可直接用HEAD类型的请求获取总数

④ "compat": true 处理最外层查询字段有特殊处理的情况下 "query":2 返回查询总数不准确的问题：如DISTINCT去重、Aggregate 函数等

⑤ "join":"&/Table0,</Table1/key1@" 或 "join":{    "&/Table0":{}, // 支持 ON 多个字段关联,    "</Table1/key1@":{ // ON 只允许指定的 key1 关联      "key0":value0, // 其它ON条件      "key2":value2,      ...      "@combine":"...", // 其它ON条件的组合方式      "@column":"...", // 外层 SELECT      "@group":"...", // 外层 GROUP BY      "@having":"..." // 外层 HAVING    } } 多表连接方式： "@" - APP JOIN "<" - LEFT JOIN ">" - RIGHT JOIN "&" - INNER JOIN "|" - FULL JOIN "!" - OUTER JOIN "*" - CROSS JOIN "^" - SIDE JOIN "(" - ANTI JOIN ")" - FOREIGN JOIN 其中 @ APP JOIN 为应用层连表，会从已查出的主表里取得所有副表 key@ 关联的主表内的 refKey 作为一个数组 refKeys: [value0, value1...]，然后把原来副表 count 次查询 key=$refKey 的 SQL 用 key IN($refKeys) 的方式合并为一条 SQL 来优化性能； 其它 JOIN 都是 SQL JOIN，具体功能和 MySQL,PostgreSQL 等数据库的 JOIN 一一对应 "join":"</ViceTable/key@", "MainTable":{}, "ViceTable":{"key@":"/MainTable/refKey"} 会对应生成 MainTable LEFT JOIN ViceTable ON ViceTable.key=MainTable.refKey AND 其它ON条件 除了 = 等价关联，也支持 ! 不等关联、> < >= <= 等比较关联和 $ ~ {} <> 等其它复杂关联方式

⑥ "otherKey":Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值 | ① 查询User数组，最多5个： "count":5 对应 SQL 是LIMIT 5

② 查询第3页的User数组，每页5个： "count":5, "page":3 对应 SQL 是LIMIT 5 OFFSET 15

③ 查询User数组和对应的User总数： "[]":{    "query":2,    "User":{} }, "total@":"/[]/total", // 可省略 "info@":"/[]/info" // 可省略 返回的数据中，总数及分页详情结构为： "total":139, // 总数 "info":{ // 分页详情    "total":139, // 总数    "count":5, // 每页数量    "page":0, // 当前页码    "max":27, // 最大页码    "more":true, // 是否还有更多    "first":true, // 是否为首页    "last":false // 是否为尾页 }

④查询User数组ID唯一情况下的User总数： "[]":{    "query":2,    "compat":"true",    "User":{      "@column":"DISTINCT id"    } } 返回的数据和结构同上

⑤ Moment INNER JOIN User LEFT JOIN Comment： "[]":{    "join":"&/User/id@,</Comment",    "Moment":{      "@group":"id" // 主副表不是一对一，要去除重复数据    },    "User":{      "name~":"t",      "id@":"/Moment/userId"    },    "Comment":{      "momentId@":"/Moment/id"    } }

⑥ 每一层都加当前用户名： "User":{}, "[]":{    "name@":"User/name", // 自定义关键词    "Moment":{} } 对象关键词，可自定义 | "@key":Object，@key 为 Table:{} 中 {} 内的关键词，Object 的类型由 @key 指定

① "@combine":"key0 | (key1 & (key2 | !key3))..."，条件组合方式，最终按 (其它key条件 AND 连接) AND (key0条件 OR (key1条件 AND (key2条件 OR (NOT key3条件)))) 这种方式连接，其中 "其它key" 是指与 @combine 在同一对象，且未被它声明的条件 key，默认都是 & 连接。注意不要缺少或多余任何一个空格。

② "@column":"column;function(arg)..."，返回字段

③ "@order":"column0+,column1-..."，排序方式

④ "@group":"column0,column1..."，分组方式。如果 @column 里声明了 Table 的 id，则 id 也必须在 @group 中声明；其它情况下必须满足至少一个条件: 1.分组的 key 在 @column 里声明 2.Table 主键在 @group 中声明

⑤ "@having":"function0(...)?value0;function1(...)?value1;function2(...)?value2..." // OR 连接，或 "@having&":"function0(...)?value0;function1(...)?value1;function2(...)?value2..." // AND 连接，或 "@having":{    "h0":"function0(...)?value0",    "h1":function1(...)?value1",    "h2":function2(...)?value2...",    "@combine":"h0 & (h1 | !h2)" // 任意组合，非必传 } SQL 函数条件，一般和 @group 一起用，函数一般在 @column 里声明

⑥ "@schema":"sys"，集合空间(数据库名/模式)，非默认的值可通过它来指定，可以在最外层作为全局默认配置

⑦ "@database":"POSTGRESQL"，数据库类型，非默认的值可通过它来指定，可以在最外层作为全局默认配置

⑧ "@datasource":"DRUID"，跨数据源，非默认的值可通过它来指定，可以在最外层作为全局默认配置

⑨ "@json":"key0,key1..."，转为 JSON 格式返回，符合 JSONObject 则转为 {...}，符合 JSONArray 则转为 [...]

⑩ "@role":"OWNER"，来访角色，包括 UNKNOWN,LOGIN,CONTACT,CIRCLE,OWNER,ADMIN， 可以在最外层作为全局默认配置， 可自定义其它角色并重写 Verifier.verify 等相关方法来自定义校验

⑪ "@explain":true，性能分析，可以在最外层作为全局默认配置

⑫ "@raw":"key0,key1..."，其中 key0, key1 都对应有键值对 "key0":"SQL片段或SQL片段的别名", "key1":"SQL片段或SQL片段的别名" 自定义原始SQL片段，可扩展嵌套SQL函数等复杂语句，必须是后端已配置的，只有其它功能符都做不到才考虑，谨慎使用，注意防 SQL 注入

⑬ "@null":"key1,key2..."，空值键值对，自动插入 key1:null, key2:null ... 并作为有效键值对执行，作为条件时对应 SQL 是 WHERE tag IS NULL，作为值时对应 SQL 是 SET tag = NULL

⑭ "@otherKey":Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值 | ① 搜索 name 或 tag 任何一个字段包含字符 a 的 User 列表： "name~":"a", "tag~":"a", "@combine":"name~ | tag~" 对应SQL是name REGEXP 'a' OR tag REGEXP 'a'

② 只查询 id,sex,name 这几列并且请求结果也按照这个顺序： "@column":"id,sex,name" 对应 SQL 是SELECT id,sex,name

③ 查询按 name 降序、id 默认顺序 排序的 User 数组： "@order":"name-,id" 对应 SQL 是ORDER BY name DESC,id

④ 查询按 userId 分组的 Moment 数组： "@group":"userId,id" 对应 SQL 是GROUP BY userId,id

⑤ 查询 按 userId 分组、id 最大值>=100 的 Moment 数组： "@column":"userId;max(id)", "@group":"userId", "@having":"max(id)>=100" 对应 SQL 是SELECT userId,max(id) ... GROUP BY userId HAVING max(id)>=100 还可以指定函数返回名： "@column":"userId;max(id):maxId", "@group":"userId", "@having":"(maxId)>=100" 对应 SQL 是SELECT userId,max(id) AS maxId ... GROUP BY userId HAVING (maxId)>=100

⑥ 查询 sys 内的 User 表： "@schema":"sys" 对应 SQL 是FROM sys.User

⑦ 查询 PostgreSQL 数据库的 User 表： "@database":"POSTGRESQL"

⑧ 使用 Druid 连接池查询 User 表： "@datasource":"DRUID"

⑨ 将 VARCHAR 字符串字段 get 转为 JSONArray 返回： "@json":"get"

⑩ 查询当前用户的动态： "@role":"OWNER"

⑪ 开启性能分析： "@explain":true 对应 SQL 是EXPLAIN

⑫ 统计最近一周偶数 userId 的数量 "@column":"date;left(date,10):day;sum(if(userId%2=0,1,0))", "@group":"day", "@having":"to_days(now())-to_days(`date`)<=7", "@raw":"@column,@having" 对应 SQL 是SELECT date, left(date,10) AS day, sum(if(userId%2=0,1,0)) ... GROUP BY day HAVING to_days(now())-to_days(`date`)<=7

⑬ 把用户的标签设置为空 "@null":"tag"

⑭ 从pictureList 获取第 0 张图片： "@position":0, // 自定义关键词 "firstPicture()":"getFromArray(pictureList,@position)" 全局关键词 | 为最外层对象 {} 内的关键词。其中 @database，@schema, @datasource, @role, @explain 基本同对象关键词，见上方说明，区别是全局关键词会每个表对象中没有时自动放入，作为默认值。

① "tag":"Table"，后面的 tag 是非 GET、HEAD 请求中匹配请求的 JSON 结构的标识，一般是要查询的 Table 的名称或该名称对应的数组 Table[] 或 Table:[]，由后端 Request 表中指定。

② "version":1，接口版本，version 不传、为 null 或 <=0 都会使用最高版本，传了其它有效值则会使用最接近它的最低版本，由后端 Request 表中指定。

③ "format":true，格式化返回 Response JSON 的 key，一般是将 TableName 转为 tableName, TableName[] 转为 tableNameList, Table:alias 转为 alias, TableName-key[] 转为 tableNameKeyList 等小驼峰格式。 | ① 查隐私信息： {"tag":"Privacy","Privacy":{"id":82001}}

② 使用第 1 版接口查隐私信息： {"version":1,"tag":"Privacy","Privacy":{"id":82001}}

③ 格式化朋友圈接口返回 JSON 中的 key： {    "format":true,    "[]":{      "page":0,      "count":3,      "Moment":{},      "User":{        "id@":"/Moment/userId"      },      "Comment[]":{        "count":3,        "Comment":{          "momentId@":"[]/Moment/id"        }      }    } }