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[]": {
        "page": 0,
        "count": 1,
        "User": {
            "sex": 0
        }
    }
}
说明：
 "count":Integer，查询数量，0 表示最大值，默认最大值为100
 "page":Integer，查询页码，从0开始，默认最大值为100，一般和count一起用

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$":"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~”:[“正则表达式”]，任意正则表达式字符串，如 ¹+$ ，*~ 忽略大小写，可用于高级搜索

{
    "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. join关联查询

“join”:"&/Table0/key0@, 多表连接方式：
“<” - LEFT JOIN
“>” - RIGHT JOIN
“&” - INNER JOIN
“|” - FULL JOIN
“!” - OUTTER JOIN
“@” - APP JOIN
其中 @ APP JOIN 为应用层连表，会从已查出的主表里取得所有副表 key@ 关联的主表内的 refKey 作为一个数组 refKeys: [value0, value1…]，然后把原来副表 count 次查询 key=$refKey的SQL用keyIN($refKeys) 的方式合并为一条 SQL 来优化性能；
其它 JOIN 都是 SQL JOIN，具体功能和 MySQL,PostgreSQL 等数据库的 JOIN 一一对应
“join”:" “MainTable”:{},
“ViceTable”:{“key@”:"/MainTable/refKey"}
会对应生成
MainTable LEFT JOIN ViceTable
ON ViceTable.key=MainTable.refKey

{
    "[]": {
        "join": "&/User/id@,

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这几列并且请求结果也按照这个顺序

20.order排序查询

“@order”:“column0+,column1-…”，排序方式

{
    "[]": {
        "count": 10,
        "User": {
            "@column": "name,id",
            "@order": "name-,id"
        }
    }
}
解析：查询按 name降序、id默认顺序 排序的User数组

21.group分组查询

“@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数组

21.sql查看&性能分析

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

{
    "User[]": {
        "page": 0,
        "count": 1,
        "User": {
            "sex": 0
        }
    },
    "@explain": true
}

说明：通过最外层的    "@explain": true 可以起到查看 sql 语句的目的
{
"User[]":  [
 {
"@explain":  {
"sql": "SELECT * FROM `thea`.`apijson_user` WHERE ( (`sex` = 0) ) LIMIT 1 OFFSET 0" ,
"list":  [
	 {
		"id": 1 ,
		"select_type": "SIMPLE" ,
		"table": "apijson_user" ,
		"type": "ALL" ,
		"rows": 141 ,
		"filtered": 10 ,
		"Extra": "Using where"
	}
]
},
"id": 38710 ,
"sex": 0 ,
"name": "TommyLemon" ,
"tag": "Android&Java" ,
"head": "http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000" ,
"contactIdList":  [
	82003 ,
	82005 ,
	90814 ,
	82004 ,
	82009 ,
	82002 ,
	82044 ,
	93793 ,
	70793
],
"pictureList":  [
	"http://static.oschina.net/uploads/user/1218/2437072_100.jpg?t=1461076033000" ,
	"http://common.cnblogs.com/images/icon_weibo_24.png"
],
"date": "2017-02-01 19:21:50.0"
}
],
	"ok": true ,
	"code": 200 ,
	"msg": "success" ,
	"sql:generate|cache|execute|maxExecute": "1|0|1|200" ,
	"depth:count|max": "3|10" ,
	"time:start|duration|end": "1607832122410|133|1607832122543"
}

二、基本操作实例

1. 单表增加

增加不用传id
http://localhost:8080/post

{
    "Moment": {
        "content": "测试保存是否好使"
    },
    "tag": "Moment"
}

2. 单表修改

修改必须传id
http://localhost:8080/put

{
    "Moment": {
        "id": 1607585789895,
        "content": "测试修改是否好使"
    },
    "tag": "Moment"
}

3. 单表删除

直接传id
http://localhost:8080/delete

{
    "Moment": {
        "id": 1607585789895
    },
    "tag": "Moment"
}

未完待续。。。 。。。

总结

对于apijson这里目前正在学习，如果有新的查询也会添加进入这里。

---

1. 0-9 ↩︎