APIJSON使用例子总结
作者：互联网
虽然apijson的通用文档中提供了很多例子，但是这些例子我在使用中感觉不能直接粘贴使用，不怎么直观，所以这里在通用文档的基础上增加了apijson使用例子的总结，同时这里需要说明一下，apijson所说的官方文档 https://vincentcheng.github.io/apijson-doc 其实并不是最新的文档以及涉及的相关例子并不全面，可做简单的入门，但不能做为手册来做，这里开发者目前推荐的是通用文档 https://github.com/Tencent/APIJSON/blob/master/Document.md 这个确实是比较全的，而且这里也有很多说明，当然对于喜欢眼见为实的我来说总是喜欢实际操作一下，通用文档里面这个是直接点击就可以了，虽然更快捷，但是作为例子我还是喜欢可以直接放到auto里面运行的，就像mybatis log plugin插件一样，直接粘贴复制到指定运行的界面查询；
文章目录
一、官方网站实例
1. 查询数组
“key[]”:{}，后面是JSONObject，key可省略。当key和里面的Table名相同时，Table会被提取出来，即 {Table:{Content}} 会被转化为 {Content}
查询一个User数组。这里key和Table名都是User，User会被提取出来，即 {“User”:{“id”, …}} 会被转化为 {“id”, …}
{
"User[]": {
"count": 3,
"User": {}
}
}
2. 匹配选项范围
“key{}”:[]，后面是JSONArray，作为key可取的值的选项
对应SQL是id IN(38710,82001,70793)，查询id符合38710,82001,70793中任意一个的一个User数组
{
"User[]": {
"count": 3,
"User": {
"id{}": [
38710,
82001,
70793
]
}
}
}
3. 匹配条件范围
“key{}”:“条件0,条件1…”，条件为任意SQL比较表达式字符串，非Number类型必须用’‘包含条件的值，如’a’
对应SQL是id<=80000 OR id>90000，查询id符合id<=80000 | id>90000的一个User数组
{
"User[]": {
"count": 3,
"User": {
"id{}": "<=80000,>90000"
}
}
}
4. 包含选项范围
“key<>”:Object => “key<>”:[Object]，key对应值的类型必须为JSONArray，Object类型不能为JSON
对应SQL是json_contains(contactIdList,38710)，查询contactIdList包含38710的一个User数组
{
"User[]": {
"count": 3,
"User": {
"contactIdList<>": 38710
}
}
}
5. 判断是否存在
“key}{@”:{
“from”:“Table”,
“Table”:{ … }
}
其中：
}{ 表示 EXISTS；
key 用来标识是哪个判断；
@ 后面是 子查询 对象，具体见下方 子查询 的说明。
{
"User": {
"id}{@": {
"from": "Comment",
"Comment": {
"momentId": 15
}
}
}
}
sql: WHERE EXISTS(SELECT * FROM Comment WHERE momentId=15)
6. 远程调用函数
“key()”:“函数表达式”，函数表达式为 function(key0,key1…)，会调用后端对应的函数 function(JSONObject request, String key0, String key1…)，实现 参数校验、数值计算、数据同步、消息推送、字段拼接、结构变换 等特定的业务逻辑处理，
可使用 - 和 + 表示优先级，解析 key-() > 解析当前对象 > 解析 key() > 解析子对象 > 解析 key+()
会调用远程函数 boolean isContain(JSONObject request, String array, String value) ，然后变为 “isPraised”:true 这种（假设点赞用户id列表包含了userId，即这个User点了赞）
{
"Moment": {
"id": 301,
"isPraised()": "isContain(praiseUserIdList,userId)"
}
}
7. 存储过程
“@key()”:“SQL函数表达式”，函数表达式为
function(key0,key1…)
会调用后端数据库对应的存储过程 SQL函数
function(String key0, String key1…)
除了参数会提前赋值，其它和 远程函数 一致
{
"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 为返回结果集
8. 引用赋值
“key@”:“key0/key1/…/refKey”，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明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
9. 子查询
“key@”:{
“range”:“ALL”,
“from”:“Table”,
“Table”:{ … }
}
其中：
range 可为 ALL,ANY；
from 为目标表 Table 的名称；
@ 后面的对象类似数组对象，可使用 count 和 join 等功能。
{
"User": {
"id@": {
"from": "Comment",
"Comment": {
"@column": "min(userId)"
}
}
}
}
sql:WHERE id=(SELECT min(userId) FROM Comment)
10. 模糊搜索
“key " : " S Q L 搜 索 表 达 式 " = > " k e y ":"SQL搜索表达式" => "key ":"SQL搜索表达式"=>"key”:[“SQL搜索表达式”]，任意SQL搜索表达式字符串，如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等，%表示任意字符
{
"User[]": {
"count": 3,
"User": {
"name$": "%m%"
}
}
}
解释：对应SQL是name LIKE '%m%'，查询name包含"m"的一个User数组
11. 正则匹配
“key~”:“正则表达式” => “key~”:[“正则表达式”]，任意正则表达式字符串，如 1+$ ，*~ 忽略大小写，可用于高级搜索
{
"User[]": {
"count": 3,
"User": {
"name~": "^[0-9]+$"
}
}
}
解释：对应SQL是name REGEXP '^[0-9]+$'，查询name中字符全为数字的一个User数组
12. 连续范围
“key%”:“start,end” => “key%”:[“start,end”]，其中 start 和 end 都只能为 Boolean, Number, String 中的一种，如 “2017-01-01,2019-01-01” ，[“1,90000”, “82001,100000”] ，可用于连续范围内的筛选
{
"User[]": {
"count": 3,
"User": {
"date%": "2017-10-01,2018-10-01"
}
}
}
解释：对应SQL是date BETWEEN '2017-10-01' AND '2018-10-01'，
查询在2017-10-01和2018-10-01期间注册的用户的一个User数组
13. 新建别名
“name:alias”，name映射为alias，用alias替代name。可用于 column,Table,SQL函数 等。只用于GET类型、HEAD类型的请求
{
"Comment": {
"@column": "id,toId:parentId",
"id": 51
}
}
解释：对应SQL是toId AS parentId，将查询的字段toId变为parentId返回
14. 增加 或 扩展
“key+”:Object，Object的类型由key指定，且类型为Number,String,JSONArray中的一种。如 82001,“apijson”,[“url0”,“url1”] 等。只用于PUT请求
"praiseUserIdList+":[82001]，
对应SQL是json_insert(praiseUserIdList,82001)，添加一个点赞用户id，即这个用户点了赞
15. 减少 或 去除
“key-”:Object，与"key+"相反
"balance-":100.00，
对应SQL是balance = balance - 100.00，余额减少100.00，即花费了100元
16. 比较运算
>, <, >=, <= 比较运算符，用于
提供 “id{}”:"<=90000" 这种条件范围的简化写法
{
"[]": {
"User": {
"id<=": 90000
}
}
}
解释：对应SQL是id<=90000，查询符合id<=90000的一个User数组
实现子查询相关比较运算
{
"User": {
"id>@": {
"from": "Comment",
"Comment": {
"@column": "min(userId)"
}
}
}
}
sql:WHERE id>(SELECT min(userId) FROM Comment)
不支持 “key=”:Object 和 “key!=”:Object 这两种写法，直接用更简单的 “key”:Object 和 “key!”:Object 替代。
17. 逻辑运算
&, |, ! 逻辑运算符，对应数据库 SQL 中的 AND, OR, NOT。
横或纵与：同一键值对的值内条件默认 | 或连接，不同键值对的条件默认 & 与连接。
& 可用于"key&{}":"条件"等
{
"User": {
"id&{}": ">80000,<=90000"
}
}
解释：对应SQL是id>80000 AND id<=90000，即id满足id>80000 & id<=90000
| 可用于"key|{}":“条件”, “key|{}”:[]等，一般可省略
{
"User": {
"id|{}": ">90000,<=80000"
}
}
解释：同"id{}":">90000,<=80000"，对应SQL是id>80000 OR id<=90000，即id满足id>90000 | id<=80000
! 可单独使用，如"key!":Object，也可像&,|一样配合其他功能符使用
{
"User": {
"id!{}": [
82001,
38710
]
}
}
解释：IN(82001,38710)，即id满足 ! (id=82001 | id=38710)，可过滤黑名单的消息
“key!”:null 无效，null 值会导致整个键值对被忽略解析，可以用 “key{}”:"!=null" 替代，
“key”:null 同理，用 “key{}”:"=null" 替代。
18. 数组关键词&自定义&分页
“key”:Object，key为 “[]”:{} 中{}内的关键词，Object的类型由key指定
“count”:Integer，查询数量，0 表示最大值，默认最大值为100
{
"[]": {
"count": 5,
"User": {}
}
}
解释：查询User数组，最多5个
“page”:Integer，查询页码，从0开始，默认最大值为100，一般和count一起用
{
"[]": {
"count": 5,
"page": 3,
"User": {}
}
}
解释：查询第3页的User数组，每页5个
“query”:Integer，查询内容0-对象，1-总数和分页详情，2-以上全部总数关键词为 total，分页详情关键词为 info，它们都和 query 同级，通过引用赋值得到，例如"total@":"/[]/total", “info@”:"/[]/info"这里query及total仅为GET类型的请求提供方便，一般可直接用HEAD类型的请求获取总数
{
"[]": {
"query": 2,
"count": 5,
"User": {}
},
"total@": "/[]/total",
"info@": "/[]/info"
}
解释：查询User数组和对应的User总数
返回的数据中，总数及分页详情结构为：
"total":139, //总数
"info":{ //分页详情
"total":139, //总数
"count":5, //每页数量
"page":0, //当前页码
"max":27, //最大页码
"more":true, //是否还有更多
"first":true, //是否为首页
"last":false //是否为尾页
}
“join”:"&/Table0/key0@,</Table1/key1@"
多表连接方式：
“<” - LEFT JOIN
“>” - RIGHT JOIN
“&” - INNER JOIN
“|” - FULL JOIN
“!” - OUTTER JOIN
“@” - APP JOIN
其中 @ APP JOIN 为应用层连表，会从已查出的主表里取得所有副表 key@ 关联的主表内的 refKey 作为一个数组 refKeys: [value0, value1…]，然后把原来副表 count 次查询 key=
r
e
f
K
e
y
的
S
Q
L
用
k
e
y
I
N
(
refKey 的 SQL 用 key IN(
refKey的SQL用keyIN(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
{
"[]": {
"join": "&/User/id@,</Comment/momentId@",
"Moment": {},
"User": {
"name~": "t",
"id@": "/Moment/userId"
},
"Comment": {
"momentId@": "/Moment/id"
}
}
}
解析：Moment INNER JOIN User LEFT JOIN Comment
“otherKey”:Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值
{
"User":{},
"[]":{
"name@":"User/name", //自定义关键词
"Moment":{}
}
}
解析：每一层都加当前用户名
19.对象关键词，可自定义
“@key”:Object，@key为 Table:{} 中{}内的关键词，Object的类型由@key指定
“@combine”:"&key0,&key1,|key2,key3,
!key4,!key5,&key6,key7…"，条件组合方式，| 可省略。会自动把同类的合并，外层按照 & | ! 顺序，内层的按传参顺序组合成
(key0 & key1 & key6 & 其它key) & (key2 | key3 | key7) & !(key4 | key5)
这种连接方式，其中 “其它key” 是指与 @combine 在同一对象，且未被它声明的条件 key，默认都是 & 连接
{
'User[]': {
'count': 10,
'User': {
'@column': 'id,name,tag',
'name~': 'a',
'tag~': 'a',
'@combine': 'name~,tag~'
}
}
}
解析：搜索name或tag任何一个字段包含字符a的User列表
“@column”:“column;function(arg)…”，返回字段
{
"User": {
"@column": "id,sex,name",
"id": 38710
}
}
解析：只查询id,sex,name这几列并且请求结果也按照这个顺序
“@order”:“column0+,column1-…”，排序方式
{
"[]": {
"count": 10,
"User": {
"@column": "name,id",
"@order": "name-,id"
}
}
}
解析：查询按 name降序、id默认顺序 排序的User数组
“@group”:“column0,column1…”，分组方式。如果@column里声明了Table的id，则id也必须在@group中声明；其它情况下必须满足至少一个条件:
1.分组的key在@column里声明
2.Table主键在@group中声明
{
"[]": {
"count": 10,
"Moment": {
"@column": "userId,id",
"@group": "userId,id"
}
}
}
解析：查询按userId分组的Moment数组
“@having”:“function0(…)?value0;function1(…)?value1;function2(…)?value2…”，SQL函数条件，一般和@group一起用，函数一般在@column里声明
{
"[]": {
"count": 10,
"Moment": {
"@column": "userId;max(id)",
"@group": "userId",
"@having": "max(id)>=100"
}
}
}
解析：查询 按userId分组、id最大值>=100 的Moment数组
未完待续。。。 。。。
总结
对于apijson这里目前正在学习，如果有新的查询也会添加进入这里。
0-9 ↩︎
标签：总结,APIJSON,name,count,例子,User,key,SQL,id 来源： https://blog.csdn.net/weixin_41077841/article/details/110518007