感谢 moxixi527 贡献：新增 函数调用映射 "@key": "fun:avg(id);keyA:(keyB)" 的功能符通用文档 Tencent#836

TommyLemon · web-flow · commit dda9e314dd0d · 2025-08-09T02:27:51.000+08:00
Tencent#836
diff --git a/Document-English.md b/Document-English.md
@@ -324,7 +324,7 @@ Response:
  Fuzzy matching | `"key$":"SQL search expressions"`  =>  `"key$":["SQL search expressions"]`<br />Any SQL search expressions.Eg.%key%(include key), key%(start with key),%k%e%y%(include k, e, y). % means any characters. | ["name$":"%m%"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"name$":"%2525m%2525"}}}) <br />In SQL, it's <br />`name LIKE '%m%'`, <br />meaning that get User with ‘m’ in name.
  Regular Expression| `"key~":"regular expression"`  =>  `"key~":["regular expression"]`<br />It can be any regular expressions.Eg. ^[0-9]+$ ，*~ not case sensitive, advanced search is applicable.| ["name~":"^[0-9]+$"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"name~":"^[0-9]%252B$"}}}) <br />In SQL, it's <br />`name REGEXP '^[0-9]+$'`.
  Get data in a range| `"key%":"start,end"`  =>  `"key%":["start,end"]`<br />The data type of start and end can only be either Boolean, Number or String. Eg. "2017-01-01,2019-01-01" ，["1,90000", "82001,100000"]. It's used for getting data from a specific time range. | ["date%":"2017-10-01,2018-10-01"](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"date%2525":"2017-10-01,2018-10-01"}}}) <br />In SQL, it's <br />`date BETWEEN '2017-10-01' AND '2018-10-01'`, <br />meaning to get User data that registered between 2017-10-01 and 2018-10-01.
- Make an alias | `"name:alias"`<br />this changes name to alias in returning results. It’s applicable to column, tableName, SQL Functions, etc. but only in GET, HEAD requests. | ["@column":"toId:parentId"](http://apijson.cn:8080/get/{"Comment":{"@column":"id,toId:parentId","id":51}}) <br />In SQL, it's <br />`toId AS parentId`. <br />It'll return `parentId` instead of `toId`.
+ Make an alias | `"name:alias"`<br />this changes name to alias in returning results. It’s applicable to column, tableName, SQL Functions, etc. but only in GET, HEAD requests. | ["@column":"toId:parentId"](http://apijson.cn:8080/get/{"Comment":{"@column":"id,toId:parentId","id":51}}) <br />In SQL, it's <br />`toId AS parentId`. <br />It'll return `parentId` instead of `toId`.<br /><br />For @key format like "lc_wai6b3vk2:(lc_wai6b3vk)", it means renaming field lc_wai6b3vk2 to lc_wai6b3vk, commonly used for field renaming scenarios. Example:<br />{<br />&nbsp;&nbsp;"lc_sinan_ba074fbb": {<br />&nbsp;&nbsp;&nbsp;&nbsp;"lc_wai6b3vk": "11",<br />&nbsp;&nbsp;&nbsp;&nbsp;"lc_wai6b3vk2": "22",<br />&nbsp;&nbsp;&nbsp;&nbsp;"@combine": "lc_wai6b3vk \\| lc_wai6b3vk2",<br />&nbsp;&nbsp;&nbsp;&nbsp;"@key": "lc_wai6b3vk2:(lc_wai6b3vk)"<br />&nbsp;&nbsp;}<br />}<br />corresponds to SQL `(lc_wai6b3vk = '11' OR lc_wai6b3vk2 = '22')`, but the lc_wai6b3vk2 field will be renamed and displayed as lc_wai6b3vk in the returned result
  Add / expand an item | `"key+":Object` <br /> The type of Object is decided by *key*. Types can be Number, String, JSONArray. Froms are 82001,"apijson",["url0","url1"] respectively. It’s only applicable to PUT request.| "praiseUserIdList+":[82001]. In SQL, it's <br />`json_insert(praiseUserIdList,82001)`. <br />Add an *id* that praised the Moment.
  Delete / decrease an item | `"Key-":Object`<br /> It’s the contrary of "key+" | "balance-":100.00. In SQL, it's <br />`balance = balance - 100.00`, <br />meaning there's 100 less in balance.
  Operations | &, \|, ! <br /> They're used in logic operations. It’s the same as AND, OR, NOT in SQL respectively. <br />By default, for the same key, it’s ‘\|’ (OR)operation among conditions; for different keys, the default operation among conditions is ‘&’(AND). <br /> |  ① ["id&{}":">80000,<=90000"](http://apijson.cn:8080/head/{"User":{"id&{}":">80000,<=90000"}}) <br />In SQL, it's <br />`id>80000 AND id<=90000`, <br />meaning *id* needs to be id>80000 & id<=90000<br /><br /> ② ["id\|{}":">90000,<=80000"](http://apijson.cn:8080/head/{"User":{"id\|{}":">90000,<=80000"}}) <br />It's the same as "id{}":">90000,<=80000". <br />In SQL, it's <br />`id>80000 OR id<=90000`, <br />meaning that *id* needs to be id>90000 \| id<=80000<br /><br /> ③ ["id!{}":[82001,38710]](http://apijson.cn:8080/head/{"User":{"id!{}":[82001,38710]}}) <br />In SQL, it's <br />`id NOT IN(82001,38710)`, <br />meaning id needs to be ! (id=82001 \| id=38710).
diff --git a/Document.md b/Document.md
@@ -408,15 +408,15 @@ DELETE: <br > 删除数据 | base_url/delete/ | {<br > &nbsp;&nbsp; TableName:{<
  匹配条件范围 | "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<\>":value  =>  "key<\>":[value]，key 对应值的类型必须为 JSONArray，value 值类型只能为 Boolean, Number, String 中的一种 |  ["contactIdList<\>":38710](http://apijson.cn:8080/get/{"User[]":{"count":3,"User":{"contactIdList<\>":38710}}})，对应SQL是`json_contains(contactIdList,38710)`，查询 contactIdList 包含 38710 的一个 User 数组
  判断是否存在 | "key}{@":{<br /> &nbsp;&nbsp; "from":"Table",<br /> &nbsp;&nbsp; "Table":{ ... }<br />}<br />其中：<br />}{ 表示 EXISTS；<br /> key 用来标识是哪个判断；<br /> @ 后面是 子查询 对象，具体见下方 子查询 的说明。 | ["id}{@":{<br /> &nbsp;&nbsp; "from":"Comment",<br /> &nbsp;&nbsp; "Comment":{<br /> &nbsp;&nbsp;  &nbsp;&nbsp; "momentId":15 <br /> &nbsp;&nbsp; }<br />}](http://apijson.cn:8080/get/{"User":{"id}{@":{"from":"Comment","Comment":{"momentId":15}}}})<br /> WHERE EXISTS(SELECT * FROM Comment WHERE momentId=15)
- 远程调用函数 | "key()":"函数表达式"，函数表达式为 function(key0,key1...)，会调用后端对应的函数 function(JSONObject request, String key0, String key1...)，实现 参数校验、数值计算、数据同步、消息推送、字段拼接、结构变换 等特定的业务逻辑处理，<br>可使用 - 和 + 表示优先级，解析 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函数表达式"，函数表达式为 <br />  function(key0,key1...) <br /> 会调用后端数据库对应的存储过程 SQL 函数 <br /> function(String key0, String key1...) <br /> 除了参数会提前赋值，其它和 远程函数 一致 | ["@limit":10, <br /> "@offset":0, <br /> "@procedure()":"getCommentByUserId(id,@limit,@offset)"](http://apijson.cn:8080/get/{"User":{"@limit":10,"@offset":0,"@procedure()":"getCommentByUserId(id,@limit,@offset)"}}) <br /> 会转为 <br /> `getCommentByUserId(38710,10,0)` <br /> 来调用存储过程 SQL 函数 <br /> `getCommentByUserId(IN id bigint, IN limit int, IN offset int)` <br /> 然后变为 <br />"procedure":{<br /> &nbsp;&nbsp; "count":-1, <br /> &nbsp;&nbsp; "update":false, <br /> &nbsp;&nbsp; "list":[] <br /> } <br /> 其中 count 是指写操作影响记录行数，-1 表示不是写操作；update 是指是否为写操作（增删改）；list 为返回结果集
- 引用赋值 | "key@":"key0/key1/.../refKey"，引用路径为用 / 分隔的字符串。以 / 开头的是缺省引用路径，从声明 key 所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。<br /> 被引用的 refKey 必须在声明 key 的上面。如果对 refKey 的容器指定了返回字段，则被引用的 refKey 必须写在 @column 对应的值内，例如 "@column":"refKey,key1,..." | ["Moment":{<br /> &nbsp;&nbsp; "userId":38710<br />},<br />"User":{<br /> &nbsp;&nbsp; "id@":"/Moment/userId"<br />}](http://apijson.cn:8080/get/{"Moment":{"userId":38710},"User":{"id@":"%252FMoment%252FuserId"}})<br /> User 内的 id 引用了与 User 同级的 Moment 内的 userId，<br />即 User.id = Moment.userId，请求完成后<br > "id@":"/Moment/userId" 会变成 "id":38710
- 子查询 | "key@":{<br /> &nbsp;&nbsp; "range":"ALL", <br /> &nbsp;&nbsp; "from":"Table", // 可省略，默认为首个表对象 key 名<br /> &nbsp;&nbsp; "Table":{ ... }<br />}<br />其中：<br />range 可为 ALL,ANY；<br />from 为目标表 Table 的名称；<br />@ 后面的对象类似数组对象，可使用 count 和 join 等功能。 | ["id@":{<br /> &nbsp;&nbsp; "from":"Comment", // 可省略<br /> &nbsp;&nbsp; "Comment":{<br /> &nbsp;&nbsp;  &nbsp;&nbsp; "@column":"min(userId)" <br /> &nbsp;&nbsp; }<br />}](http://apijson.cn:8080/get/{"User":{"id@":{"from":"Comment","Comment":{"@column":"min(userId)"}}}})<br /> 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 都只能为 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()":"函数表达式"，函数表达式为 function(key0,key1...)，会调用后端对应的函数 function(JSONObject request, String key0, String key1...)，实现 参数校验、数值计算、数据同步、消息推送、字段拼接、结构变换 等特定的业务逻辑处理，<br>可使用 - 和 + 表示优先级，解析 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函数表达式"，函数表达式为 <br />  function(key0,key1...) <br /> 会调用后端数据库对应的存储过程 SQL函数 <br /> function(String key0, String key1...) <br /> 除了参数会提前赋值，其它和 远程函数 一致 | ["@limit":10, <br /> "@offset":0, <br /> "@procedure()":"getCommentByUserId(id,@limit,@offset)"](http://apijson.cn:8080/get/{"User":{"@limit":10,"@offset":0,"@procedure()":"getCommentByUserId(id,@limit,@offset)"}}) <br /> 会转为 <br /> `getCommentByUserId(38710,10,0)` <br /> 来调用存储过程 SQL 函数 <br /> `getCommentByUserId(IN id bigint, IN limit int, IN offset int)` <br /> 然后变为 <br />"procedure":{<br /> &nbsp;&nbsp; "count":-1, <br /> &nbsp;&nbsp; "update":false, <br /> &nbsp;&nbsp; "list":[] <br /> } <br /> 其中 count 是指写操作影响记录行数，-1 表示不是写操作；update 是指是否为写操作（增删改）；list 为返回结果集
+ 引用赋值 | "key@":"key0/key1/.../refKey"，引用路径为用/分隔的字符串。以/开头的是缺省引用路径，从声明key所处容器的父容器路径开始；其它是完整引用路径，从最外层开始。<br /> 被引用的refKey必须在声明key的上面。如果对refKey的容器指定了返回字段，则被引用的refKey必须写在@column对应的值内，例如 "@column":"refKey,key1,..." | ["Moment":{<br /> &nbsp;&nbsp; "userId":38710<br />},<br />"User":{<br /> &nbsp;&nbsp; "id@":"/Moment/userId"<br />}](http://apijson.cn:8080/get/{"Moment":{"userId":38710},"User":{"id@":"%252FMoment%252FuserId"}})<br /> User内的id引用了与User同级的Moment内的userId，<br />即User.id = Moment.userId，请求完成后<br > "id@":"/Moment/userId" 会变成 "id":38710
+ 子查询 | "key@":{<br /> &nbsp;&nbsp; "range":"ALL", <br /> &nbsp;&nbsp; "from":"Table",<br /> &nbsp;&nbsp; "Table":{ ... }<br />}<br />其中：<br />range 可为 ALL,ANY；<br />from 为目标表 Table 的名称；<br />@ 后面的对象类似数组对象，可使用 count 和 join 等功能。 | ["id@":{<br /> &nbsp;&nbsp; "from":"Comment",<br /> &nbsp;&nbsp; "Comment":{<br /> &nbsp;&nbsp;  &nbsp;&nbsp; "@column":"min(userId)" <br /> &nbsp;&nbsp; }<br />}](http://apijson.cn:8080/get/{"User":{"id@":{"from":"Comment","Comment":{"@column":"min(userId)"}}}})<br /> 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 类型的请求 <br /><br />② 函数调用映射<br />"@key": "fun:avg(id);keyA:(keyB)",<br />"fun>": 1,<br />"keyA": 1<br />其中 fun:fun(arg) 把 SQL 函数调用 fun(arg) 作为左侧表达式替代 fun，即 fun(arg) > 1；<br />keyA:(keyB) 表示将字段 keyA 重命名为 keyB，即实际 SQL 中为 keyB = 1，常用于重命名冲突的多条件同名字段。 | ① ["@column":"toId:parentId"](http://apijson.cn:8080/get/{"Comment":{"@column":"id,toId:parentId","id":51}})，对应 SQL 是 `toId AS parentId`，将查询的字段 toId 变为 parentId 返回<br /><br />② ["@key": "len:length(content);mid:(momentId)",<br />"len<=": 10,<br />"mid": 12,<br />"momentId": 15,<br />"@combine": "(len<= \\| mid) & momentId"](http://apijson.cn/api?type=JSON&json={%22Comment%22:{%22@key%22:%22len%3Alength(content)%3Bmid%3A(momentId)%22,%22len%3C=%22:10,%22mid%22:12,%22momentId%22:15,%22@combine%22:%22(len%3C%3D%20%7C%20mid)%20%26%20momentId%22}})<br />对应 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元
  比较运算 | >, <, >=, <= 比较运算符，用于 <br />① 提供 "id{}":"<=90000" 这种条件范围的简化写法 <br /><br />② 实现子查询相关比较运算<br /><br />不支持 "key=":Object 和 "key!=":Object 这两种写法，直接用更简单的 "key":Object 和 "key!":Object 替代。 |  ① ["id<=":90000](http://apijson.cn:8080/get/{"[]":{"User":{"id<=":90000}}})，对应 SQL 是`id<=90000`，查询符合id<=90000的一个User数组<br /><br /> ② ["id>@":{<br /> &nbsp;&nbsp; "from":"Comment",<br /> &nbsp;&nbsp; "Comment":{<br /> &nbsp;&nbsp;  &nbsp;&nbsp; "@column":"min(userId)" <br /> &nbsp;&nbsp; }<br />}](http://apijson.cn:8080/get/{"User":{"id>@":{"from":"Comment","Comment":{"@column":"min(userId)"}}}})<br /> WHERE id>(SELECT min(userId) FROM Comment)
  逻辑运算 | &, \|, ! 逻辑运算符，对应数据库 SQL 中的 AND, OR, NOT。 <br />横或纵与：同一键值对的值内条件默认 \| 或连接，可以在 key 后加逻辑运算符来具体指定；不同键值对的条件默认 & 与连接，可以用下面说明的对象关键词 @combine 来具体指定。 <br /><br />① & 可用于 "key&{}":"条件"等<br /><br />② \| 可用于 "key\|{}":"条件", "key\|{}":[]等，一般可省略<br /><br />③ ! 可单独使用，如 "key!":Object，也可像 &,\| 一样配合其他功能符使用 <br /> "key!":null 无效，null 值会导致整个键值对被忽略解析，可以用 "key{}":"!=null" 替代，<br />"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<br /><br /> ② ["id\|{}":">90000,<=80000"](http://apijson.cn:8080/head/{"User":{"id\|{}":">90000,<=80000"}})，同 "id{}":">90000,<=80000"，对应 SQL 是`id>90000 OR id<=80000`，即 id 满足 id>90000 \| id<=80000<br /><br /> ③ ["id!{}":[82001,38710]](http://apijson.cn:8080/head/{"User":{"id!{}":[82001,38710]}})，对应 SQL 是`id NOT IN(82001,38710)`，即 id 满足 ! (id=82001 \| id=38710)，可过滤黑名单的消息
