wend看源码-APISJON

项目地址

定义

APIJSON 可以定义为一个面向HTTP 协议的JSON 规范，一个面向数据访问层的ORM 框架。其主要工作流程包括：前端按照既定格式组装 JSON 请求报文，通过 APIJSON-ORM 将这些报文直接转换为 SQL 语句，进而执行数据库操作，如增删改查等。完成后，系统将数据再按照指定格式封装成 JSON 响应报文，高效地实现前后端的数据交互，并将最终结果反馈给用户。

架构

图2.1 基于APIJSON的交互流程图

通过图2.1 基于APIJSON的交互流程图我们可以发现，APIJSON 的设计思路，主要用于前端可以通过基于APIJSON的语法格式直接处理数据的增删改查。也可以说是后端通过使用APIJSON-ORM 框架，定义了一个万能的Controller接口层，从而使得前端可以通过这个接口实现全部的CRUD 操作。

图2.2 基于APIJSON 构件生态的框架图

APIJSON-ORM：APIJSON-ORM 是 APIJSON 框架的核心组件，它是一个对象关系映射（ORM）框架，专门用于将 JSON 格式的请求自动转换为 SQL 语句，从而快速实现对数据库的增删改查操作。
APIJSON-framework：APIJSON-framework 是 APIJSON 的基础框架，它提供了一套完整的解决方案，包括请求的解析、处理、权限验证以及响应的封装等，还包含了基于unitAuto 的自动化单元测试的内容。这个框架使得开发者能够快速搭建起一个高效、安全、易用的后端 API 服务。
APIJSON-cloumn：APIJSON 的字段处理插件，包含了表字段相关工具类
unitauto-java：unitauto-java 是一个自动化测试框架，它可以自动生成和执行单元测试代码。这个框架旨在减少手动编写测试代码的工作量，提高代码质量和测试覆盖率。
APIJSON-router：APIJSON 的路由插件，用于将Restful API 转成 APIJSON API格式请求
APIJSON-builder：采用类似mybaits 中 wrapper 封装的方式组装前端请求报文。用于生成符合 APIJSON 规范的 JSON 请求和响应结构。

主要功能

APIJSON 定义了前端请求后端操作数据库的JSON报文格式。
APIJSON-framework 包含一套完整的前后端CRUD操作的解决方案，主要包括权限校验，远程函数/脚本调用，请求合法性校验，单元测试等功能。
APIJSON-ROM 简化了后端数据仓储层的操作，大大减少了软件运维过程中的重复造轮子过程，让开发者可以将精力专注于开发创新和商业赋能。

优缺点

优点：在此借用APIJSON 官网的图，来表述使用APIJSON的优点:

开发提速对比表：

缺点(个人观点）：
- APIJSON-framework 依赖了mysql和postgresql两个数据库引擎，以及直接集成了作者的另一个自动化单元测试的项目UnitAuto。这使得APIJSON-framework 的技术架构耦合性比较高。
- APIJSON-cloumn 就是一个工具类，在我看来完全可以集成于APIJSON-framework
- APIJSON-ORM 的核心代码有待优化

使用规范

语法

"key[]":{}                                         // 查询数组

"key{}":[1,2,3]                                    // 匹配选项范围

"key{}":"<=10;length(key)>1..."                    // 匹配条件范围

"key()":"function(arg0,arg1...)"                   // 远程调用函数

"key@":"key0/key1.../targetKey"                    // 引用赋值

"key$":"%abc%"                                     // 模糊搜索

"key~":"^[0-9]+$"                                  // 正则匹配

"key%":"2018-01-01,2018-10-01"                     // 连续范围

"key+":[1]                                         // 增加/扩展

"key-":888.88                                      // 减少/去除 

"name:alias"                                       // 新建别名

"@combine":"name~,tag~"                            // 条件组合

"@column":"id,sex,name"                            // 返回字段

"@group":"userId"                                  // 分组方式

"@having":"max(id)>=100"                           // 聚合函数

"@order":"date-,name+"                             // 排序方式

"@schema":"sys"                                    // 集合空间

"@database":"POSTGRESQL"                           // 跨数据库

"@datasource":"DRUID"                              // 多数据源

"@explain":true                                    // 性能分析

"@role":"LOGIN"                                    // 访问角色

功能列表

功能	键值对格式	使用示例
查询数组	"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" } } }}

适用场景

全栈开发一个小型web 项目：初识APIJSON，我认为APIJSON 可以大大简化后端，但需要前端同学学习APIJSON 定义的JSON 协议规则语法，以及需要前端同学对数据库操作语法有一定的理解。所以目前看来，我让前端同学直接从原有开发模式转成基于APIJSON 的开发是不现实的。所以我认为APIJSON 更适合个人全栈开发一个小型的web 项目。
报表类服务：报表类服务没有复杂的项目逻辑，大多数是基于数据的查询，APIJSON 比较适合。
数据维护服务：数据维护服务没有复杂的项目逻辑，大多数是基于数据的增删改查操作，APIJSON 比较适合。

项目重构思路

本人后续准备对APIJSON项目进行重构，编写一个基于APIJSON的开源项目：easy-APIJSON，重构的内容列表包括：

1. 使用配置文件的方式封装APIJSON-ORM 中AbstractSQLConfig 中关于数据库关键字，函数，运算符的配置，我想以文本文档的方式将这些内容封装整理，方便后续的软件维护工作

2. 整体重构 APIJSON-framework

去掉强相关的数据库依赖，以及单元测试依赖等；去掉APIJSON-framework 关于权限校验，请求校验等基于数据库操作的内容。
将APIJSON-clolumn 的内容集成与APIJSON-framework中；
加入通用排序工具，通用分页工具等，丰富APIJSON-framework的内容。

图3.1 easy-APIJSON 架构图

3. 我希望的easy-APIJSON的架构是这样的：easy-APIJSON 整体项目与三方依赖以及数据库无关，APIJSON 提供的是通用的处理方法。用户可以自主选择技术实现方案，如采用数据库配置、代码配置或文件配置等方式去实现某个功能。

4. 基于easy-APIJSON，APIJSON-builder 提供前端明确的语法文档和示例,在easy-APIJSON运行时可提供网页文档。

参考文献

APIJSON 官方网站：腾讯APIJSON官方网站

APIJSON 官方文档：介绍 | apijson-doc