Skip to content

Latest commit

 

History

History
426 lines (365 loc) · 62.2 KB

Document.md

File metadata and controls

426 lines (365 loc) · 62.2 KB

English

APIJSON 通用文档

本文是通用文档,只和 APIJSON 协议有关,和 C#, Go, Java, JavaScript, PHP, Python, TypeScript 等开发语言无关。
具体开发语言相关的 配置、运行、部署 等文档见各个相关项目的文档,可以在首页点击对应语言的入口来查看。
https://github.com/Tencent/APIJSON image

后端开发者可以先看 图文入门教程1图文入门教程2 (和本文档有出入的点以本文档为准。例如正则匹配 key? 已废弃,用 key~ 替代;例如 "@column":"store_id,sum(amt):totAmt" 中逗号 , 有误,应该用分号 ; 隔开 SQL 函数,改为 "@column":"store_id;sum(amt):totAmt")

1.示例

获取用户

请求:

{
  "User":{
    "id":38710
  }
}

点击这里测试

返回:

{
  "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"
}

[GIF] APIJSON 各种单表对象查询:简单查询、统计、分组、排序、聚合、比较、筛选字段、字段别名 等


获取用户列表

请求:

{
  "[]":{
    "count":3,             //只要3个
    "User":{
      "@column":"id,name"  //只要id,name这两个字段
    }
  }
}

点击这里测试

返回:

{
  "[]":[
    {
      "User":{
        "id":38710,
        "name":"TommyLemon"
      }
    },
    {
      "User":{
        "id":70793,
        "name":"Strong"
      }
    },
    {
      "User":{
        "id":82001,
        "name":"Android"
      }
    }
  ],
  "code":200,
  "msg":"success"
}

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


获取动态及发布者用户

请求:

{
  "Moment":{
  },
  "User":{
    "id@":"Moment/userId"  //User.id = Moment.userId
  }
}

点击这里测试

返回:

{
  "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"
}

获取类似微信朋友圈的动态列表

请求:

{
  "[]":{                             //请求一个数组
    "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  完整引用赋值路径
      }
    }
  }
}

点击这里测试

返回:

{
  "[]":[
    {
      "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"
}

[GIF] APIJSON 各种多表关联查询:一对一、一对多、多对一、各种条件 等


[GIF] APIJSON 各种 JOIN:< LEFT JOIN, & INNER JOIN 等


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


[GIF] APIJSON 部分功能演示集合,由浅入深、由简单到复杂


在线测试



2.对比传统RESTful方式

2.1 开发流程

开发流程 传统方式 APIJSON
接口传输 等后端编辑接口,然后更新文档,前端再按照文档编辑请求和解析代码 前端按照自己的需求编辑请求和解析代码。
没有接口,更不需要文档!前端再也不用和后端沟通接口或文档问题了!
兼容旧版 后端增加新接口,用v2表示第2版接口,然后更新文档 什么都不用做!

2.2 前端请求

前端请求 传统方式 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/
{
   TableName0:{
     key0:value0,
     key1:value1,
     ...
   },
   TableName1:{
     ...
   }
   ...
}

2.3 后端操作

后端操作 传统方式 APIJSON
解析和返回 取出键值对,把键值对作为条件用预设的的方式去查询数据库,最后封装JSON并返回给前端 把Parser#parse方法的返回值返回给前端就行
返回JSON结构的设定方式 由后端设定,前端不能修改 由前端设定,后端不能修改

2.4 前端解析

前端解析 传统方式 APIJSON
查看方式 查文档或问后端,或等请求成功后看日志 看请求就行,所求即所得,不用查、不用问、不用等。也可以等请求成功后看日志
解析方法 用JSON解析器来解析JSONObject 可以用JSONResponse解析JSONObject,或使用传统方式

2.5 前端对应不同需求的请求

前端的请求 传统方式 APIJSON
User base_url/get/user?id=38710 base_url/get/
{
   "User":{
     "id":38710
   }
}
Moment和对应的User 分两次请求
Moment:
base_url/get/moment?userId=38710

User:
base_url/get/user?id=38710
base_url/get/
{
   "Moment":{
     "userId":38710
   },
   "User":{
     "id":38710
   }
}
User列表 base_url/get/user/list?
page=0&count=3&sex=0
base_url/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/
{
   "[]":{
     "page":0,
     "count":3,
     "Moment":{},
     "User":{
       "id@":"/Moment/userId"
     },
     "Comment[]":{
       "count":3,
       "Comment":{
         "momentId@":"[]/Moment/id"
       }
     }
   }
}
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}

② 或把User放在上面的最外层省去重复的User
base_url/get/
{
   "User":{
     "id":38710
   },
   "[]":{
     "page":0,
     "count":3,
     "Moment":{
       "userId":38710
     },
     "Comment[]":{
       "count":3,
       "Comment":{
         "momentId@":"[]/Moment/id"
       }
     }
   }
}


③ 如果User之前已经获取到了,还可以不传User来节省请求和返回数据的流量并提升速度
base_url/get/
{
   "[]":{
     "page":0,
     "count":3,
     "Moment":{
       "userId":38710
     },
     "Comment[]":{
       "count":3,
       "Comment":{
         "momentId@":"[]/Moment/id"
       }
     }
   }
}

2.6 后端对应不同请求的返回结果

后端的返回结果 传统方式 APIJSON
User {
   "data":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}
{
   "User":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}
Moment和对应的User 分别返回两次请求的结果,获取到Moment后取出userId作为User的id条件去查询User

Moment:
{
   "data":{
     "id":235,
     "content":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}

User:
{
   "data":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}
一次性返回,没有传统方式导致的 长时间等待结果、两次结果间关联、线程多次切换 等问题

{
   "Moment":{
     "id":235,
     "content":"xxx",
     ...
   },
   "User":{
     "id":38710,
     "name":"xxx",
     ...
   },
   "code":200,
   "msg":"success"
}
User列表 {
   "data":[
     {
       "id":38710,
       "name":"xxx",
       ...
     },
     {
       "id":82001,
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}
{
   "User[]":[
     {
       "id":38710,
       "name":"xxx",
       ...
     },
     {
       "id":82001,
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}
Moment列表,每个Moment包括发布者User和前3条Comment Moment里必须有
1.User对象
2.Comment数组

{
   "data":[
     {
       "id":235,
       "content":"xxx",
       ...,
       "User":{
         ...
       },
       "Comment":[
         ...
       ]
     },
     {
       "id":301,
       "content":"xxx",
       ...,
       "User":{
         ...
       },
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}
1.高灵活,可任意组合
2.低耦合,逻辑很清晰

{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     {
       "Moment":{
         "id":301,
         "content":"xxx",
         ...
       },
       "User":{
         ...
       },
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}
User发布的Moment列表,每个Moment包括发布者User和前3条Comment 1.大量重复User,浪费流量和服务器性能
2.优化很繁琐,需要后端扩展接口、写好文档,前端/前端再配合优化

{
   "data":[
     {
       "id":235,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":470,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":511,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     {
       "id":595,
       "content":"xxx",
       ...,
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment":[
         ...
       ]
       ...
     },
     ...
   ],
   "code":200,
   "msg":"success"
}
以上不同请求方式的结果:

① 常规请求
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "User":{
         "id":38710,
         "name":"Tommy"
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

② 省去重复的User
{
   "User":{
     "id":38710,
     "name":"Tommy",
     ...
   },
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "msg":"success"
}

③ 不查询已获取到的User
{
   "[]":[
     {
       "Moment":{
         "id":235,
         "content":"xxx",
         ...
       },
       "Comment[]":[
         ...
       ]
     },
     ...
   ],
   "code":200,
   "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等字段对应的值仅供说明,不一定是数据库里存在的,请求里用的是真实存在的值。下同。



3.设计规范

3.1 操作方法

 方法及说明 URL Request Response
GET:
普通获取数据,
可用浏览器调试
base_url/get/ {
   TableName:{
     …
   }
}
{…}内为限制条件

例如获取一个 id = 235 的 Moment:
{
   "Moment":{
     "id":235
   }
}

后端校验通过后自动解析为 SQL 并执行:
SELECT * FROM Moment WHERE id=235 LIMIT 1
{
   TableName:{
     ...
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Moment":{
     "id":235,
     "userId":38710,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "code":200,
   "msg":"success"
}
HEAD:
普通获取数量,
可用浏览器调试
base_url/head/ {
   TableName:{
     …
   }
}
{…}内为限制条件

例如获取一个 id = 38710 的 User 所发布的 Moment 总数:
{
   "Moment":{
     "userId":38710
   }
}

后端校验通过后自动解析为 SQL 并执行:
SELECT count(*) FROM Moment WHERE userId=38710 LIMIT 1
{
   TableName:{
     "code":200,
     "msg":"success",
     "count":10
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Moment":{
     "code":200,
     "msg":"success",
     "count":10
   },
   "code":200,
   "msg":"success"
}
GETS:
安全/私密获取数据,
用于获取钱包等
对安全性要求高的数据
base_url/gets/ 最外层加一个 "tag":tag,例如 "tag":"Privacy",其它同GET 同GET
HEADS:
安全/私密获取数量,
用于获取银行卡数量等
对安全性要求高的数据总数
base_url/heads/ 最外层加一个 "tag":tag,例如 "tag":"Verify",其它同HEAD 同HEAD
POST:
新增数据
base_url/post/ 单个:
{
   TableName:{
     …
   },
   "tag":tag
}
{…}中id由后端生成,不能传

例如当前登录用户 38710 发布一个新 Comment:
{
   "Comment":{
     "momentId":12,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "tag":"Comment"
}

后端校验通过后自动解析为 SQL 并执行:
INSERT INTO Comment(userId,momentId,content) VALUES(38710,12,'APIJSON,let interfaces and documents go to hell !')

批量:
{
   TableName[]:[{
       …
     }, {
       …
     }
     …
   ],
   "tag":tag
}
{…}中id由后端生成,不能传

例如当前登录用户 82001 发布 2 个 Comment:
{
   "Comment[]":[{
     "momentId":12,
     "content":"APIJSON,let interfaces and documents go to hell !"
     }, {
     "momentId":15,
     "content":"APIJSON is a JSON transmision protocol."
   }],
   "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.');
单个:
{
   TableName:{
     "code":200,
     "msg":"success",
     "id":38710
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Comment":{
     "code":200,
     "msg":"success",
     "id":120
   },
   "code":200,
   "msg":"success"
}

批量:
{
   TableName:{
     "code":200,
     "msg":"success",
     "count":5,
     "id[]":[1, 2, 3, 4, 5]
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Comment":{
     "code":200,
     "msg":"success",
     "count":2,
     "id[]":[1, 2]
   },
   "code":200,
   "msg":"success"
}
PUT:
修改数据,
只修改所传的字段
base_url/put/ {
   TableName:{
     "id":id,
     …
   },
   "tag":tag
}
{…} 中 id 或 id{} 至少传一个

例如当前登录用户 82001 修改 id = 235 的 Moment 的 content:
{
   "Moment":{
     "id":235,
     "content":"APIJSON,let interfaces and documents go to hell !"
   },
   "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/ {
   TableName:{
     "id":id
   },
   "tag":tag
}
{…} 中 id 或 id{} 至少传一个,一般只传 id 或 id{}

例如当前登录用户 82001 批量删除 id = 100,110,120 的 Comment:
{
   "Comment":{
     "id{}":[100,110,120]
   },
   "tag":"Comment[]"
}

后端校验通过后自动解析为 SQL 并执行:
DELETE FROM Comment WHERE id IN(100,110,120) AND userId=82001 LIMIT 3
{
   TableName:{
     "code":200,
     "msg":"success",
     "id[]":[100,110,120]
      "count":3
   },
   "code":200,
   "msg":"success"
}
例如
{
   "Comment":{
      "code":200,
      "msg":"success",
      "id[]":[100,110,120],
      "count":3
   },
   "code":200,
   "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}

相当于
base_url/gets/
{"tag":"Privacy", "Privacy":{"id":82001}}


例如批量修改 id = 114, 124 的 Comment 的 content:
base_url/put/Comemnt[]/
{
   "id{}":[114,124],
   "content":"test multi put"
}

相当于
base_url/put/
{
   "tag":"Comment[]",
   "Comment":{
     "id{}":[114,124],
     "content":"test multi put"
   }
}
同以上对应的方法

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 表示。下同。


3.2 功能符

功能 键值对格式 使用示例
查询数组 "key[]":{},后面是JSONObject,key可省略。当key和里面的Table名相同时,Table会被提取出来,即 {Table:{Content}} 会被转化为 {Content} {"User[]":{"User":{}}},查询一个User数组。这里key和Table名都是User,User会被提取出来,即 {"User":{"id", ...}} 会被转化为 {"id", ...},如果要进一步提取User中的id,可以把User[]改为User-id[]
匹配选项范围 "key{}":[],后面是JSONArray,作为key可取的值的选项 "id{}":[38710,82001,70793],对应SQL是id IN(38710,82001,70793),查询id符合38710,82001,70793中任意一个的一个User数组
匹配条件范围 "key{}":"条件0,条件1...",条件为SQL表达式字符串,可进行数字比较运算等 "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,对应SQL是json_contains(contactIdList,38710),查询contactIdList包含38710的一个User数组
判断是否存在 "key}{@":{
   "from":"Table",
   "Table":{ ... }
}
其中:
}{ 表示 EXISTS;
key 用来标识是哪个判断;
@ 后面是 子查询 对象,具体见下方 子查询 的说明。
"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)",会调用远程函数 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)"

会转为
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"
}

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)"
   }
}

WHERE id=(SELECT min(userId) FROM Comment)
模糊搜索 "key$":"SQL搜索表达式" => "key$":["SQL搜索表达式"],任意SQL搜索表达式字符串,如 %key%(包含key), key%(以key开始), %k%e%y%(包含字母k,e,y) 等,%表示任意字符 "name$":"%m%",对应SQL是name LIKE '%m%',查询name包含"m"的一个User数组
正则匹配 "key~":"正则表达式" => "key~":["正则表达式"],任意正则表达式字符串,如 ^[0-9]+$ ,*~ 忽略大小写,可用于高级搜索 "name~":"^[0-9]+$",对应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",对应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",对应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,对应SQL是id<=90000,查询符合id<=90000的一个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",对应SQL是id>80000 AND id<=90000,即id满足id>80000 & id<=90000

"id|{}":">90000,<=80000",同"id{}":">90000,<=80000",对应SQL是id>80000 OR id<=90000,即id满足id>90000 | id<=80000

"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":{
   "&/Table0":{}, // 支持 ON 多个字段关联,
   "</Table1/key1@":{ // ON 只允许指定的 key1 关联
     "key0":value0, // 其它ON条件
     "key2":value2,
     ...
     "@combine":"...", // 其它ON条件的组合方式
     "@column":"...", // 外层 SELECT
     "@group":"...", // 外层 GROUP BY
     "@having":"..." // 外层 HAVING
   }
}
多表连接方式:
"@" - 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
对应SQL是LIMIT 5

② 查询第3页的User数组,每页5个:
"count":5,
"page":3

对应SQL是LIMIT 5 OFFSET 15

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

返回的数据中,总数及分页详情结构为:
"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",
   "Moment":{
     "@group":"id" //主副表不是一对一,要去除重复数据
   },
   "User":{
     "name~":"t",
     "id@":"/Moment/userId"
   },
   "Comment":{
     "momentId@":"/Moment/id"
   }
}


⑤ 每一层都加当前用户名:
"User":{},
"[]":{
   "name@":"User/name", //自定义关键词
   "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":{
   "h0":"function0(...)?value0",
   "h1":function1(...)?value1",
   "h2":function2(...)?value2...",
   "@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~"

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

② 只查询id,sex,name这几列并且请求结果也按照这个顺序:
"@column":"id,sex,name"
对应SQL是SELECT id,sex,name

③ 查询按 name降序、id默认顺序 排序的User数组:
"@order":"name-,id"
对应SQL是ORDER BY name DESC,id

④ 查询按userId分组的Moment数组:
"@group":"userId,id"
对应SQL是GROUP BY userId,id

⑤ 查询 按userId分组、id最大值>=100 的Moment数组:
"@column":"userId;max(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"

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

⑥ 查询 sys 内的 User 表:
"@schema":"sys"
对应SQL是FROM sys.User

⑦ 查询 PostgreSQL 数据库的 User 表:
"@database":"POSTGRESQL"

⑧ 使用 Druid 连接池查询 User 表:
"@datasource":"DRUID"

⑨ 将 VARCHAR 字符串字段 get 转为 JSONArray 返回:
"@json":"get"

⑩ 查询当前用户的动态:
"@role":"OWNER"

⑪ 开启性能分析:
"@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"

对应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)"
全局关键词 为最外层对象 {} 内的关键词。其中 @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}}

② 使用第 1 版接口查隐私信息:
{"version":1,"tag":"Privacy","Privacy":{"id":82001}}

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