wend看源码-APISJON

功能

键值对格式

使用示例

查询数组

"key[]":{}，后面是JSONObject，key可省略。当key和里面的Table名相同时，Table会被提取出来，即 {Table:{Content}} 会被转化为 {Content}

{"User[]":{"User":{}}}(opens new window)

，查询一个User数组。这里key和Table名都是User，User会被提取出来，即 {"User":{"id", ...}} 会被转化为 {"id", ...}，如果要进一步提取User中的id，可以把User[]改为User-id[]

匹配选项范围

"key{}":[]，后面是JSONArray，作为key可取的值的选项

"id{}":[38710,82001,70793](opens new window)

，对应SQL是id IN(38710,82001,70793)

，查询id符合38710,82001,70793中任意一个的一个User数组

匹配条件范围

"key{}":"条件0,条件1..."，条件为SQL表达式字符串，可进行数字比较运算等

"id{}":"<=80000,>90000"(opens new window)

，对应SQL是id<=80000 OR id>90000

，查询id符合id<=80000 | id>90000的一个User数组

包含选项范围

"key<>":Object => "key<>":[Object]，key对应值的类型必须为JSONArray，Object类型不能为JSON

"contactIdList<>":38710(opens new window)

，对应SQL是json_contains(contactIdList,38710)

，查询contactIdList包含38710的一个User数组

判断是否存在

"key}{@":{
"from":"Table",
"Table":{ ... }
}
其中：
}{ 表示 EXISTS；
key 用来标识是哪个判断；
@ 后面是 子查询 对象，具体见下方 子查询 的说明。

"id}{@":{   "from":"Comment",   "Comment":{      "momentId":15   }}(opens new window)

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)"(opens new window)

，会调用远程函数 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)"(opens new window)

会转为
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"}(opens new window)

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)"   }}(opens new window)

WHERE id=(SELECT min(userId) FROM Comment)

模糊搜索

"key$":"SQL搜索表达式" => "key$":["SQL搜索表达式"]，任意SQL搜索表达式字符串，如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等，%表示任意字符

"name$":"%m%"(opens new window)

，对应SQL是name LIKE '%m%'

，查询name包含"m"的一个User数组

正则匹配

"key~":"正则表达式" => "key~":["正则表达式"]，任意正则表达式字符串，如 ^[0-9]+$ ，*~ 忽略大小写，可用于高级搜索

"name~":"^[0-9]+$"(opens new window)

，对应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"(opens new window)

，对应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"(opens new window)

，对应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(opens new window)

，对应SQL是id<=90000

，查询符合id<=90000的一个User数组

② "id>@":{   "from":"Comment",   "Comment":{      "@column":"min(userId)"   }}(opens new window)

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"(opens new window)

，对应SQL是id>80000 AND id<=90000

，即id满足id>80000 & id<=90000

② "id|{}":">90000,<=80000"(opens new window)

，同"id{}":">90000,<=80000"，对应SQL是id>80000 OR id<=90000

，即id满足id>90000 | id<=80000

③ "id!{}":[82001,38710](opens new window)

，对应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/key0@,</Table1/key1@"
多表连接方式：
"<" - LEFT JOIN
">" - RIGHT JOIN
"&" - INNER JOIN
"|" - FULL JOIN
"!" - OUTER JOIN
"@" - APP 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

⑤ "otherKey":Object，自定义关键词，名称和以上系统关键词不一样，且原样返回上传的值

① 查询User数组，最多5个：
"count":5(opens new window)

对应SQL是LIMIT 5

② 查询第3页的User数组，每页5个：
"count":5,"page":3(opens new window)

对应SQL是LIMIT 5 OFFSET 15

③ 查询User数组和对应的User总数：
"[]":{   "query":2,   "User":{}},"total@":"/[]/total","info@":"/[]/info"(opens new window)

返回的数据中，总数及分页详情结构为：
"total":139, //总数
"info":{ //分页详情
"total":139, //总数
"count":5, //每页数量
"page":0, //当前页码
"max":27, //最大页码
"more":true, //是否还有更多
"first":true, //是否为首页
"last":false //是否为尾页
}

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

⑤ 每一层都加当前用户名：
"User":{},"[]":{   "name@":"User/name", //自定义关键词   "Moment":{}}(opens new window)

对象关键词，可自定义

"@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，默认都是 & 连接

② "@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..."，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~"(opens new window)

对应SQL是name REGEXP 'a' OR tag REGEXP 'a'

② 只查询id,sex,name这几列并且请求结果也按照这个顺序：
"@column":"id,sex,name"(opens new window)

对应SQL是SELECT id,sex,name

③ 查询按 name降序、id默认顺序 排序的User数组：
"@order":"name-,id"(opens new window)

对应SQL是ORDER BY name DESC,id

④ 查询按userId分组的Moment数组：
"@group":"userId,id"(opens new window)

对应SQL是GROUP BY userId,id

⑤ 查询 按userId分组、id最大值>=100 的Moment数组：
"@column":"userId;max(id)","@group":"userId","@having":"max(id)>=100"(opens new window)

对应SQL是SELECT userId,max(id) ... GROUP BY userId HAVING max(id)>=100

还可以指定函数返回名：
"@column":"userId;max(id):maxId","@group":"userId","@having":"maxId>=100"(opens new window)

对应SQL是SELECT userId,max(id) AS maxId ... GROUP BY userId HAVING maxId>=100

⑥ 查询 sys 内的 User 表：
"@schema":"sys"(opens new window)

对应SQL是FROM sys.User

⑦ 查询 PostgreSQL 数据库的 User 表：
"@database":"POSTGRESQL"(opens new window)

⑧ 使用 Druid 连接池查询 User 表：
"@datasource":"DRUID"(opens new window)

⑨ 将 VARCHAR 字符串字段 get 转为 JSONArray 返回：
"@json":"get"(opens new window)

⑩ 查询当前用户的动态：
"@role":"OWNER"(opens new window)

⑪ 开启性能分析：
"@explain":true(opens new window)

对应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"(opens new window)

对应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)"(opens new window)

全局关键词

为最外层对象 {} 内的关键词。其中 @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}}(opens new window)

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

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