Document.md · 宇哥不是NPC/APIJSON

# APIJSON 通用文档 
本文是通用文档，只和 APIJSON 协议有关，和 C#, Go, Java, JavaScript, PHP, Python, TypeScript 等开发语言无关。 
具体开发语言相关的 配置、运行、部署 等文档见各个相关项目的文档，可以在首页点击对应语言的入口来查看。 
https://github.com/Tencent/APIJSON
![image](https://user-images.githubusercontent.com/5738175/134520081-a63d3817-321c-4e7b-9e03-73c6827a19c1.png)

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

* ### [1.示例](#1)
* ### [2.对比传统方式](#2)
* [2.1 开发流程](#2.1)
* [2.2 前端请求](#2.2)
* [2.3 后端操作](#2.3)
* [2.4 前端解析](#2.4)
* [2.5 对应不同需求的请求](#2.5)
* [2.6 对应不同请求的结果](#2.6)
* ### [3.设计规范](#3)
* [3.1 操作方法](#3.1)
* [3.2 功能符](#3.2)

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

#### 获取用户
请求：
<pre><code class="language-json">{
 "User":{
 "id":38710
  }
}
</code></pre>

[点击这里测试](http://apijson.cn:8080/get/{"User":{"id":38710}})

返回：
<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>

<a >[GIF] APIJSON 各种单表对象查询：简单查询、统计、分组、排序、聚合、比较、筛选字段、字段别名 等</a>
 
 
![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_single.gif)

#### 获取用户列表
请求：
<pre><code class="language-json">{
 "[]":{
   "count":3,             //只要3个
   "User":{
     "@column":"id,name" //只要id,name这两个字段
   }
 }
}
</code></pre>

[点击这里测试](http://apijson.cn:8080/get/{"[]":{"count":3,"User":{"@column":"id,name"}}})

返回：
<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>

<a >[GIF] APIJSON 各种单表数组查询：简单查询、统计、分组、排序、聚合、分页、比较、搜索、正则、条件组合 等</a>

![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_array.gif)

#### 获取动态及发布者用户
请求：
<pre><code class="language-json">{
 "Moment":{
 },
 "User":{
 "id@":"Moment/userId" //User.id = Moment.userId
 }
}
</code></pre>

[点击这里测试](http://apijson.cn:8080/get/{"Moment":{},"User":{"id@":"Moment%252FuserId"}})

返回：
<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>

[点击这里测试](http://apijson.cn:8080/get/{"[]":{"page":0,"count":2,"Moment":{"content$":"%2525a%2525"},"User":{"id@":"%252FMoment%252FuserId","@column":"id,name,head"},"Comment[]":{"count":2,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}})

返回：
<pre><code class="language-json">{
 "[]":[
 {
 "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"
}
</code></pre>

<a >[GIF] APIJSON 各种多表关联查询：一对一、一对多、多对一、各种条件 等</a>

![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_associate.gif)

<a >[GIF] APIJSON 各种 JOIN：< LEFT JOIN, & INNER JOIN 等</a>

![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_join.gif)
 
 
 

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

![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_subquery.gif)
 
 
 

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

![](https://raw.githubusercontent.com/TommyLemon/StaticResources/master/APIJSON/APIJSON_query_summary.gif)

[在线测试](http://apijson.cn/api)

## <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/ { &nbsp;&nbsp; TableName0:{ &nbsp;&nbsp;&nbsp;&nbsp; key0:value0, &nbsp;&nbsp;&nbsp;&nbsp; key1:value1, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; TableName1:{ &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; } &nbsp;&nbsp; ... }
 
 
 
### <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/ { &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710 &nbsp;&nbsp; } }](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/ { &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "userId":38710 &nbsp;&nbsp; }, &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710 &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"Moment":{"userId":38710},"User":{"id":38710}})
 User列表 | base_url/get/user/list? page=0&count=3&sex=0 | [base_url/get/ { &nbsp;&nbsp; "User[]":{ &nbsp;&nbsp;&nbsp;&nbsp; "page":0, &nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "sex":0 &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp; } }](http://apijson.cn:8080/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/ { &nbsp;&nbsp; "[]":{ &nbsp;&nbsp;&nbsp;&nbsp; "page":0, &nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp; "Moment":{}, &nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id@":"/Moment/userId" &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "momentId@":"[]/Moment/id" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"[]":{"page":0,"count":3,"Moment":{},"User":{"id@":"%252FMoment%252FuserId"},"Comment[]":{"count":3,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}})
 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}](http://apijson.cn:8080/get/{"[]":{"page":0,"count":3,"Moment":{"userId":38710},"User":{"id":38710},"Comment[]":{"count":3,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}}) ② 或把User放在上面的最外层省去重复的User [base_url/get/ { &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710 &nbsp;&nbsp; }, &nbsp;&nbsp; "[]":{ &nbsp;&nbsp;&nbsp;&nbsp; "page":0, &nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "userId":38710 &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "momentId@":"[]/Moment/id" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"User":{"id":38710},"[]":{"page":0,"count":3,"Moment":{"userId":38710},"Comment[]":{"count":3,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}}) ③ 如果User之前已经获取到了，还可以不传User来节省请求和返回数据的流量并提升速度 [base_url/get/ { &nbsp;&nbsp; "[]":{ &nbsp;&nbsp;&nbsp;&nbsp; "page":0, &nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "userId":38710 &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "momentId@":"[]/Moment/id" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"[]":{"page":0,"count":3,"Moment":{"userId":38710},"Comment[]":{"count":3,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}})
 
 
 
### <h3 id="2.6">2.6 后端对应不同请求的返回结果<h3/>
 后端的返回结果 | 传统方式 | APIJSON
-------- | ------------ | ------------
 User | { &nbsp;&nbsp; "data":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } | { &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
 Moment和对应的User | 分别返回两次请求的结果，获取到Moment后取出userId作为User的id条件去查询User Moment: { &nbsp;&nbsp; "data":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } User: { &nbsp;&nbsp; "data":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } | 一次性返回，没有传统方式导致的 长时间等待结果、两次结果间关联、线程多次切换 等问题 { &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
 User列表 | { &nbsp;&nbsp; "data":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":82001, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } | { &nbsp;&nbsp; "User[]":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":82001, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
 Moment列表，每个Moment包括发布者User和前3条Comment | Moment里必须有 1.User对象 2.Comment数组 { &nbsp;&nbsp; "data":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":301, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } | 1.高灵活，可任意组合 2.低耦合，逻辑很清晰 { &nbsp;&nbsp; "[]":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":301, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
 User发布的Moment列表，每个Moment包括发布者User和前3条Comment | 1.大量重复User，浪费流量和服务器性能 2.优化很繁琐，需要后端扩展接口、写好文档，前端/前端再配合优化 { &nbsp;&nbsp; "data":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":470, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":511, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":595, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ..., &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } | 以上不同请求方式的结果: ① 常规请求 { &nbsp;&nbsp; "[]":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } ② 省去重复的User { &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":38710, &nbsp;&nbsp;&nbsp;&nbsp; "name":"Tommy", &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "[]":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } ③ 不查询已获取到的User { &nbsp;&nbsp; "[]":[ &nbsp;&nbsp;&nbsp;&nbsp; { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "content":"xxx", &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":[ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ] &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; ], &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "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/ | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp; } } {…}内为限制条件 例如获取一个 id = 235 的 Moment： [{ &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":235 &nbsp;&nbsp; } }](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fget&type=JSON&json={"Moment"%3A{"id"%3A235}}) 后端校验通过后自动解析为 SQL 并执行： `SELECT * FROM Moment WHERE id=235 LIMIT 1` | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 例如 { &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp; "userId":38710, &nbsp;&nbsp;&nbsp;&nbsp; "content":"APIJSON,let interfaces and documents go to hell !" &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
HEAD: 普通获取数量， 可用浏览器调试 | base_url/head/ | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp; } } {…}内为限制条件 例如获取一个 id = 38710 的 User 所发布的 Moment 总数： [{ &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "userId":38710 &nbsp;&nbsp; } }](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fhead&type=JSON&json={"Moment"%3A{"userId"%3A38710}}) 后端校验通过后自动解析为 SQL 并执行： `SELECT count(*) FROM Moment WHERE userId=38710 LIMIT 1` | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "count":10 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 例如 { &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "count":10 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
GETS: 安全/私密获取数据， 用于获取钱包等 对安全性要求高的数据 | base_url/gets/ | 最外层加一个 "tag":tag，例如 ["tag":"Privacy"](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fgets&type=JSON&json={"tag"%3A"Privacy","Privacy"%3A{"id"%3A82001}})，其它同GET | 同GET
HEADS: 安全/私密获取数量， 用于获取银行卡数量等 对安全性要求高的数据总数 | base_url/heads/ | 最外层加一个 "tag":tag，例如 ["tag":"Verify"](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fheads&type=JSON&json={"tag"%3A"Verify","Verify"%3A{"phone"%3A13000082001}})，其它同HEAD | 同HEAD
POST: 新增数据 | base_url/post/ | 单个： { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":tag } {…}中id由后端生成，不能传 例如当前登录用户 38710 发布一个新 Comment： [{ &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "momentId":12, &nbsp;&nbsp;&nbsp;&nbsp; "content":"APIJSON,let interfaces and documents go to hell !" &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":"Comment" }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fpost&type=JSON&json={"Comment":{"momentId":12,"content":"APIJSON,let%20interfaces%20and%20documents%20go%20to%20hell%20!"},"tag":"Comment"}) 后端校验通过后自动解析为 SQL 并执行： `INSERT INTO Comment(userId,momentId,content) VALUES(38710,12,'APIJSON,let interfaces and documents go to hell !')` 批量： { &nbsp;&nbsp; TableName\[]:\[{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp;&nbsp;&nbsp; }, { &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp; ], &nbsp;&nbsp; "tag":tag } {…}中id由后端生成，不能传 例如当前登录用户 82001 发布 2 个 Comment： [{ &nbsp;&nbsp; "Comment[]":[{ &nbsp;&nbsp;&nbsp;&nbsp; "momentId":12, &nbsp;&nbsp;&nbsp;&nbsp; "content":"APIJSON,let interfaces and documents go to hell !" &nbsp;&nbsp;&nbsp;&nbsp; }, { &nbsp;&nbsp;&nbsp;&nbsp; "momentId":15, &nbsp;&nbsp;&nbsp;&nbsp; "content":"APIJSON is a JSON transmision protocol." &nbsp;&nbsp; }], &nbsp;&nbsp; "tag":"Comment:[]" }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fpost&type=JSON&json={"Comment[]":[{"momentId":12,"content":"APIJSON,let%20interfaces%20and%20documents%20go%20to%20hell%20!"},{"momentId":15,"content":"APIJSON%20is%20a%20JSON%20transmision%20protocol."}],"tag":"Comment:[]"}) 后端校验通过后自动解析为 SQL 并执行： `INSERT INTO Comment(userId,momentId,content) VALUES(82001,12,'APIJSON,let interfaces and documents go to hell !');` `INSERT INTO Comment(userId,momentId,content) VALUES(82001,15,'APIJSON is a JSON transmision protocol.');` | 单个： { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "id":38710 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 例如 { &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "id":120 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 批量： { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "count":5, &nbsp;&nbsp;&nbsp;&nbsp; "id[]":[1, 2, 3, 4, 5] &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 例如 { &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "count":2, &nbsp;&nbsp;&nbsp;&nbsp; "id[]":\[1, 2] &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" }
PUT: 修改数据， 只修改所传的字段 | base_url/put/ | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "id":id, &nbsp;&nbsp;&nbsp;&nbsp; … &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":tag } {…} 中 id 或 id{} 至少传一个 例如当前登录用户 82001 修改 id = 235 的 Moment 的 content： [{ &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id":235, &nbsp;&nbsp;&nbsp;&nbsp; "content":"APIJSON,let interfaces and documents go to hell !" &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":"Moment" }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fput&type=JSON&json={"Moment":{"id":235,"content":"APIJSON,let%20interfaces%20and%20documents%20go%20to%20hell%20!"},"tag":"Moment"}) 后端校验通过后自动解析为 SQL 并执行： `UPDATE Moment SET content='APIJSON,let interfaces and documents go to hell !' 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/ | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "id":id &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":tag } {…} 中 id 或 id{} 至少传一个，一般只传 id 或 id{} 例如当前登录用户 82001 批量删除 id = 100,110,120 的 Comment： [{ &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id{}":[100,110,120] &nbsp;&nbsp; }, &nbsp;&nbsp; "tag":"Comment[]" }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fdelete&type=JSON&json={"Comment":{"id{}":[100,110,120]},"tag":"Comment[]"}) 后端校验通过后自动解析为 SQL 并执行： `DELETE FROM Comment WHERE id IN(100,110,120) AND userId=82001 LIMIT 3` | { &nbsp;&nbsp; TableName:{ &nbsp;&nbsp;&nbsp;&nbsp; "code":200, &nbsp;&nbsp;&nbsp;&nbsp; "msg":"success", &nbsp;&nbsp;&nbsp;&nbsp; "id[]":[100,110,120] &nbsp;&nbsp; &nbsp;&nbsp; "count":3 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "msg":"success" } 例如 { &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp; &nbsp;&nbsp; "code":200, &nbsp;&nbsp; &nbsp;&nbsp; "msg":"success", &nbsp;&nbsp; &nbsp;&nbsp; "id[]":[100,110,120], &nbsp;&nbsp; &nbsp;&nbsp; "count":3 &nbsp;&nbsp; }, &nbsp;&nbsp; "code":200, &nbsp;&nbsp; "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}](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fgets%2FPrivacy&type=JSON&json={"id"%3A82001}) 相当于 [base_url/gets/ {"tag":"Privacy", "Privacy":{"id":82001}}](http://apijson.cn/api/?url=http%3A%2F%2Fapijson.cn%3A8080%2Fgets&type=JSON&json={"tag"%3A"Privacy","Privacy"%3A{"id"%3A82001}}) 例如批量修改 id = 114, 124 的 Comment 的 content： [base_url/put/Comemnt[]/ { &nbsp;&nbsp; "id{}":[114,124], &nbsp;&nbsp; "content":"test multi put" }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fput%2FComment[]&type=JSON&json={"id{}"%3A[114,124],"content"%3A"test%20multi%20put"}) 相当于 [base_url/put/ { &nbsp;&nbsp; "tag":"Comment[]", &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "id{}":[114,124], &nbsp;&nbsp;&nbsp;&nbsp; "content":"test multi put" &nbsp;&nbsp; } }](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fput&type=JSON&json={"tag"%3A"Comment[]","Comment"%3A{"id{}"%3A[114,124],"content"%3A"test%20multi%20put"}}) | 同以上对应的方法

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":{}}}](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{}}})，查询一个User数组。这里key和Table名都是User，User会被提取出来，即 {"User":{"id", ...}} 会被转化为 {"id", ...}，如果要进一步提取User中的id，可以把User[]改为User-id[]
 匹配选项范围 | "key{}":[]，后面是JSONArray，作为key可取的值的选项 | ["id{}":[38710,82001,70793]](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"id{}":[38710,82001,70793]}}})，对应SQL是`id IN(38710,82001,70793)`，查询id符合38710,82001,70793中任意一个的一个User数组
 匹配条件范围 | "key{}":"条件0,条件1..."，条件为SQL表达式字符串，可进行数字比较运算等 | ["id{}":"<=80000,\>90000"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"id{}":"<=80000,\>90000"}}})，对应SQL是`id<=80000 OR id>90000`，查询id符合id\<=80000 \| id>90000的一个User数组
 包含选项范围 | "key<\>":Object => "key<\>":[Object]，key对应值的类型必须为JSONArray，Object类型不能为JSON | ["contactIdList<\>":38710](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"contactIdList<\>":38710}}})，对应SQL是`json_contains(contactIdList,38710)`，查询contactIdList包含38710的一个User数组
 判断是否存在 | "key}{@":{ &nbsp;&nbsp; "from":"Table", &nbsp;&nbsp; "Table":{ ... } } 其中： }{ 表示 EXISTS； key 用来标识是哪个判断； @ 后面是 子查询 对象，具体见下方 子查询 的说明。 | ["id}{@":{ &nbsp;&nbsp; "from":"Comment", &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp; &nbsp;&nbsp; "momentId":15 &nbsp;&nbsp; } }](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)"](http://apijson.cn:8080/get/{"Moment":{"id":301,"isPraised()":"isContain(praiseUserIdList,userId)"}})，会调用远程函数 [boolean isContain(JSONObject request, String array, String value)](https://github.com/APIJSON/apijson-framework/blob/master/src/main/java/apijson/framework/APIJSONFunctionParser.java#L361-L374) ，然后变为 "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":{ &nbsp;&nbsp; "count":-1, &nbsp;&nbsp; "update":false, &nbsp;&nbsp; "list":[] } 其中 count 是指写操作影响记录行数，-1 表示不是写操作；update 是指是否为写操作（增删改）；list 为返回结果集
 引用赋值 | "key@":"key0/key1/.../refKey"，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明key所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。 被引用的refKey必须在声明key的上面。如果对refKey的容器指定了返回字段，则被引用的refKey必须写在@column对应的值内，例如 "@column":"refKey,key1,..." | ["Moment":{ &nbsp;&nbsp; "userId":38710 }, "User":{ &nbsp;&nbsp; "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@":{ &nbsp;&nbsp; "range":"ALL", &nbsp;&nbsp; "from":"Table", &nbsp;&nbsp; "Table":{ ... } } 其中： range 可为 ALL,ANY； from 为目标表 Table 的名称； @ 后面的对象类似数组对象，可使用 count 和 join 等功能。 | ["id@":{ &nbsp;&nbsp; "from":"Comment", &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp; &nbsp;&nbsp; "@column":"min(userId)" &nbsp;&nbsp; } }](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%"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"name$":"%2525m%2525"}}})，对应SQL是`name LIKE '%m%'`，查询name包含"m"的一个User数组
 正则匹配 | "key~":"正则表达式" => "key~":["正则表达式"]，任意正则表达式字符串，如 ^[0-9]+$ ，*~ 忽略大小写，可用于高级搜索 | ["name~":"^[0-9]+$"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"name~":"^[0-9]%252B$"}}})，对应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"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"date%2525":"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类型的请求 | ["@column":"toId:parentId"](http://apijson.cn:8080/get/{"Comment":{"@column":"id,toId:parentId","id":51}})，对应SQL是`toId AS parentId`，将查询的字段toId变为parentId返回
 增加 或 扩展 | "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](http://apijson.cn:8080/get/{"[]":{"User":{"id<=":90000}}})，对应SQL是`id<=90000`，查询符合id<=90000的一个User数组 ② ["id>@":{ &nbsp;&nbsp; "from":"Comment", &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp; &nbsp;&nbsp; "@column":"min(userId)" &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"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"](http://apijson.cn:8080/head/{"User":{"id&{}":">80000,<=90000"}})，对应SQL是`id>80000 AND id<=90000`，即id满足id>80000 & id<=90000 ② ["id\|{}":">90000,<=80000"](http://apijson.cn:8080/head/{"User":{"id\|{}":">90000,<=80000"}})，同"id{}":">90000,<=80000"，对应SQL是`id>80000 OR id<=90000`，即id满足id>90000 \| id<=80000 ③ ["id!{}":[82001,38710]](http://apijson.cn:8080/head/{"User":{"id!{}":[82001,38710]}})，对应SQL是`id NOT IN(82001,38710)`，即id满足 ! (id=82001 \| id=38710)，可过滤黑名单的消息
 数组关键词，可自定义 | "key":Object，key为 "[]":{} 中{}内的关键词，Object的类型由key指定 ① "count":Integer，查询数量，0 表示最大值，默认最大值为100 ② "page":Integer，查询页码，从0开始，默认最大值为100，一般和count一起用 ③ "query":Integer，查询内容 0-对象，1-总数和分页详情，2-数据、总数和分页详情 总数关键词为 total，分页详情关键词为 info， 它们都和 query 同级，通过引用赋值得到，例如 "total@":"/[]/total", "info@":"/[]/info" 这里query及total仅为GET类型的请求提供方便， 一般可直接用HEAD类型的请求获取总数 ④ "join":"&/Table0,\</Table1/key1@" 或 "join":{ &nbsp;&nbsp; "&/Table0":{}, // 支持 ON 多个字段关联, &nbsp;&nbsp; "\</Table1/key1@":{ // ON 只允许指定的 key1 关联 &nbsp;&nbsp;&nbsp;&nbsp; "key0":value0, // 其它ON条件 &nbsp;&nbsp;&nbsp;&nbsp; "key2":value2, &nbsp;&nbsp;&nbsp;&nbsp; ... &nbsp;&nbsp;&nbsp;&nbsp; "@combine":"...", // 其它ON条件的组合方式 &nbsp;&nbsp;&nbsp;&nbsp; "@column":"...", // 外层 SELECT &nbsp;&nbsp;&nbsp;&nbsp; "@group":"...", // 外层 GROUP BY &nbsp;&nbsp;&nbsp;&nbsp; "@having":"..." // 外层 HAVING &nbsp;&nbsp; } } 多表连接方式： "@" - 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](http://apijson.cn:8080/get/{"[]":{"count":5,"User":{}}}) 对应SQL是`LIMIT 5` ② 查询第3页的User数组，每页5个： ["count":5, "page":3](http://apijson.cn:8080/get/{"[]":{"count":5,"page":3,"User":{}}}) 对应SQL是`LIMIT 5 OFFSET 15` ③ 查询User数组和对应的User总数： ["[]":{ &nbsp;&nbsp; "query":2, &nbsp;&nbsp; "User":{} }, "total@":"/[]/total", "info@":"/[]/info"](http://apijson.cn:8080/get/{"[]":{"query":2,"count":5,"User":{}},"total@":"%252F[]%252Ftotal","info@":"%252F[]%252Finfo"}) 返回的数据中，总数及分页详情结构为： "total":139, //总数 "info":{ //分页详情 &nbsp;&nbsp; "total":139, //总数 &nbsp;&nbsp; "count":5, //每页数量 &nbsp;&nbsp; "page":0, //当前页码 &nbsp;&nbsp; "max":27, //最大页码 &nbsp;&nbsp; "more":true, //是否还有更多 &nbsp;&nbsp; "first":true, //是否为首页 &nbsp;&nbsp; "last":false //是否为尾页 } ④ Moment INNER JOIN User LEFT JOIN Comment： ["[]":{ &nbsp;&nbsp; "join":"&/User/id@,\</Comment", &nbsp;&nbsp; "Moment":{ &nbsp;&nbsp;&nbsp;&nbsp; "@group":"id" //主副表不是一对一，要去除重复数据 &nbsp;&nbsp; }, &nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp; "name~":"t", &nbsp;&nbsp;&nbsp;&nbsp; "id@":"/Moment/userId" &nbsp;&nbsp; }, &nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp; "momentId@":"/Moment/id" &nbsp;&nbsp; } }](http://apijson.cn/api/?type=JSON&url=http://apijson.cn:8080/get&json=%7B%22%5B%5D%22:%7B%22count%22:5,%22join%22:%22%26%2FUser%2Fid@,%3C%2FComment%22,%22Moment%22:%7B%22@column%22:%22id,userId,content%22,%22@group%22:%22id%22%7D,%22User%22:%7B%22name~%22:%22t%22,%22id@%22:%22%2FMoment%2FuserId%22,%22@column%22:%22id,name,head%22%7D,%22Comment%22:%7B%22momentId@%22:%22%2FMoment%2Fid%22,%22@column%22:%22id,momentId,content%22%7D%7D%7D) ⑤ 每一层都加当前用户名： ["User":{}, "[]":{ &nbsp;&nbsp; "name@":"User/name", //自定义关键词 &nbsp;&nbsp; "Moment":{} }](http://apijson.cn:8080/get/{"User":{},"[]":{"name@":"User%252Fname","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":{ &nbsp;&nbsp; "h0":"function0(...)?value0", &nbsp;&nbsp; "h1":function1(...)?value1", &nbsp;&nbsp; "h2":function2(...)?value2...", &nbsp;&nbsp; "@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注入 ⑬ "@otherKey":Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值 | ① 搜索name或tag任何一个字段包含字符a的User列表： ["name~":"a", "tag~":"a", "@combine":"name~ \| tag~"](http://apijson.cn:8080/get/{"User[]":{"count":10,"User":{"@column":"id,name,tag","name~":"a","tag~":"a","@combine":"name~%20%7C%20tag~"}}}) 对应SQL是`name REGEXP 'a' OR tag REGEXP 'a'` ② 只查询id,sex,name这几列并且请求结果也按照这个顺序： ["@column":"id,sex,name"](http://apijson.cn:8080/get/{"User":{"@column":"id,sex,name","id":38710}}) 对应SQL是`SELECT id,sex,name` ③ 查询按 name降序、id默认顺序 排序的User数组： ["@order":"name-,id"](http://apijson.cn:8080/get/{"[]":{"count":10,"User":{"@column":"name,id","@order":"name-,id"}}}) 对应SQL是`ORDER BY name DESC,id` ④ 查询按userId分组的Moment数组： ["@group":"userId,id"](http://apijson.cn:8080/get/{"[]":{"count":10,"Moment":%7B"@column":"userId,id","@group":"userId,id"}}}) 对应SQL是`GROUP BY userId,id` ⑤ 查询 按userId分组、id最大值>=100 的Moment数组： ["@column":"userId;max(id)", "@group":"userId", "@having":"max(id)>=100"](http://apijson.cn:8080/get/{"[]":{"count":10,"Moment":{"@column":"userId%253Bmax(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"](http://apijson.cn:8080/get/{"[]":{"count":10,"Moment":{"@column":"userId%253Bmax(id):maxId","@group":"userId","@having":"(maxId)>=100"}}}) 对应SQL是`SELECT userId,max(id) AS maxId ... GROUP BY userId HAVING (maxId)>=100` ⑥ 查询 sys 内的 User 表： ["@schema":"sys"](http://apijson.cn:8080/get/{"User":{"@schema":"sys"}}) 对应SQL是`FROM sys.User` ⑦ 查询 PostgreSQL 数据库的 User 表： ["@database":"POSTGRESQL"](http://apijson.cn:8080/get/{"User":{"@database":"POSTGRESQL","@explain":true}}) ⑧ 使用 Druid 连接池查询 User 表： ["@datasource":"DRUID"](http://apijson.cn:8080/get/{"User":{"@datasource":"DRUID"}}) ⑨ 将 VARCHAR 字符串字段 get 转为 JSONArray 返回： ["@json":"get"](http://apijson.cn:8080/get/{"Access":{"@json":"get"}}) ⑩ 查询当前用户的动态： ["@role":"OWNER"](http://apijson.cn:8080/get/{"[]":{"Moment":{"@role":"OWNER"}}}) ⑪ 开启性能分析： ["@explain":true](http://apijson.cn:8080/get/{"[]":{"Moment":{"@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"](http://apijson.cn:8080/get/{"[]":{"Moment":{"@column":"date%3bleft(date,10):day%3bsum(if(userId%252=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`` ⑬ 从pictureList获取第0张图片： ["@position":0, //自定义关键词 "firstPicture()":"getFromArray(pictureList,@position)"](http://apijson.cn:8080/get/{"User":{"id":38710,"@position":0,"firstPicture()":"getFromArray(pictureList,@position)"}})
 全局关键词 | 为最外层对象 {} 内的关键词。其中 @database，@schema, @datasource, @role, @explain 基本同对象关键词，见上方说明，区别是全局关键词会每个表对象中没有时自动放入，作为默认值。 ① "tag":String，后面的 tag 是非 GET、HEAD 请求中匹配请求的 JSON 结构的标识，一般是要查询的 Table 的名称或该名称对应的数组 Table[] 或 Table:[]，由后端 Request 表中指定。 ② "version":Integer，接口版本，version 不传、为 null 或 <=0 都会使用最高版本，传了其它有效值则会使用最接近它的最低版本，由后端 Request 表中指定。 ③ "format":Boolean，格式化返回 Response JSON 的 key，一般是将 TableName 转为 tableName, TableName[] 转为 tableNameList, Table:alias 转为 alias, TableName-key[] 转为 tableNameKeyList 等小驼峰格式。 | ① 查隐私信息： [{"tag":"Privacy","Privacy":{"id":82001}}](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fgets&type=JSON&json={%22tag%22:%22Privacy%22,%22Privacy%22:{%22id%22:82001}}) ② 使用第 1 版接口查隐私信息： [{"version":1,"tag":"Privacy","Privacy":{"id":82001}}](http://apijson.cn/api?url=http%3A%2F%2Fapijson.cn%3A8080%2Fgets&type=JSON&json={%22version%22:1,%22tag%22:%22Privacy%22,%22Privacy%22:{%22id%22:82001}}) ③ 格式化朋友圈接口返回 JSON 中的 key： [{ &nbsp;&nbsp; "format":true, &nbsp;&nbsp; "[]":{ &nbsp;&nbsp;&nbsp;&nbsp; "page":0, &nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp; "Moment":{}, &nbsp;&nbsp;&nbsp;&nbsp; "User":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "id@":"/Moment/userId" &nbsp;&nbsp;&nbsp;&nbsp; }, &nbsp;&nbsp;&nbsp;&nbsp; "Comment[]":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "count":3, &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "Comment":{ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "momentId@":"[]/Moment/id" &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp;&nbsp;&nbsp; } &nbsp;&nbsp; } }](http://apijson.cn:8080/get/{"format":true,"[]":{"page":0,"count":3,"Moment":{},"User":{"id@":"%252FMoment%252FuserId"},"Comment[]":{"count":3,"Comment":{"momentId@":"[]%252FMoment%252Fid"}}}})

宇哥不是NPC/APIJSON

About

Releases

Contributors

Activities