apijson 初探
本文试着从 5W1H 角度切入，试图快速建立自己对 apijson 的整体认知，所以这不是一趟快速入门的 demo 之旅，而是显得比较务虚的探索式知识体系整合。
1、Why
前后端开发过程中各种痛点：
- 开发流程繁琐、周期长
- 前端/客户端与后端各种扯皮
- 文档过时-与接口不同步
- 后端拼装数据费时费力且重复性劳动价值很低，这部分工作全部交给前端又浪费流量带宽
- 等等
谁应该负责彻底解决这个问题？
后端。
怎么解决？
后端实现一种万能查询，并能减少绝大部分重复的常规数据CRUD功能及数据拼装等开发过程，定义一套统一的规范让前端来学习掌握，以后后端除了维护好这个 DSL 的运行时，就只需要做好数据实体的定义及权限维护可以了。
这里的前端，不一定只是 Web 前端开发，而是包含了更广义的 Client 端开发的人员，比如安卓客户端开发人员、甚至包含部分做平台上小应用的后端开发人员。
前端是时候Get一门新技能了。
2、What
官方：
APIJSON 是一种专为 API 而生的 JSON 网络传输协议 以及 基于这套协议实现的 ORM 库。
据个人理解，它定义了一整套 DSL 作为 API Client 的查询语言（Query Language）的规范(Specification)，同时也是的一款对应的后端具体实现(Implementation for the Spec at server side)。
是的，这会让人想起 GraphQL，如果做一些对比工作的话，会发现他们在 Spec 还是有重叠的部分的。
因此，可以考虑为这种 QL 取个名字，比如 ApijsonQL、或者短一点 apiQL。我选 apiQL。
特性：
后端
- 提供万能通用接口，大部分接口不用再写
- 零码CRUD(增删改查)、跨库连表、嵌套子查询等
- 自动生成接口文档，不用再编写和维护
- 自动管理权限、校验参数、防 SQL 注入
- 开放 API，无需划分版本，始终保持兼容
前端
- 前端不用再向后端开发同事催接口、求文档
- 前端能完全定制数据和结构，要啥有啥
- 前端调用接口看请求知结果，所求即所得
- 前端可以一次性获取任何数据、任何结构
- 前端能够去除多余数据，节省流量提高速度
接口工具
- 自动实时生成文档，清晰可读永远最新
- 自动校验与格式化，支持高亮和收展
- 自动生成各端各种语言代码，一键下载
- 自动管理与测试各接口用例，一键共享
- 自动给 JSON 加注释和文档，一键切换
DSL Specification
Client 应用使用 apiQL 查询语言来请求支持 apiQL 的服务。
apiQL 是基于 JSON 数据格式定义的一种 DSL，对于 Cleint 开发人员来说，语法学习成本极低。剩下的，主要是熟悉领域特定的部分。
请求：
{
"[]":{
"page":0,
"count":3,
"Moment":{},
"User":{
"id@":"/Moment/userId"
},
"Comment[]":{
"count":3,
"Comment":{
"momentId@":"[]/Moment/id"
}
}
}
}
响应：
{
"[]":[
{
"Moment":{
"id":235,
"content":"xxx",
...
},
"User":{
...
},
"Comment[]":[
...
]
},
{
"Moment":{
"id":301,
"content":"xxx",
...
},
"User":{
...
},
...
},
...
],
"code":200,
"msg":"success"
}
DAO/实体服务
apijson 如官方所述作为一款 ORM，其实质是将原来传统开发模式中的三层架构中的数据持久化层直接开放给前端，即压缩了领域层和表现层（很薄，仅做可选的权限校验），几乎是让前端的视线直接穿透到数据持久化层来进行他们的对接开发工作。
前端开发需要建立一种新习惯 - 主动进行数据查询和拼接，而非像以前那般，等待后端拼接好再给出来。
apiQL 中目前支持的 Query 语句：
- 查询数组
- 匹配选项范围
- 匹配条件范围
- 包含选项范围
- 判断是否存在
- 远程调用函数
- 存储过程
- 引用赋值
- 子查询
- 模糊搜索
- 正则匹配
- 连续范围
- 新建别名
- 增加 或 扩展
- 减少 或 去除
- 比较运算
- 逻辑运算
- 数组关键词
- 对象关键词
- 全局关键词
DAO 方法：
借鉴 Restful Api 中的 verbs 术语，实际请求时全用HTTP POST请求。
- GET: 普通获取数据
- HEAD: 普通获取数量
- GETS: 安全/私密获取数据，用于获取钱包等对安全性要求高的数据
- HEADS: 安全/私密获取数量，用于获取银行卡数量等对安全性要求高的数据总数
- POST: 新增数据
- PUT: 修改数据，只修改所传的字段
- DELETE: 删除数据
实际使用时，最好在前端封装一套对应的 QueryBuilder，得到更 OO-Style 的体验，而不是记忆一堆“方言”词汇。
3、Who/When/Where
适用场景
非金融类场景；中小型前后端分离的项目，尤其是 初创项目、内部项目、低代码/零代码、小程序、BaaS、Serverless 等。
简易Demo
TODO
管理类系统
TODO
4、How
Best Practices
5、Other
生态
- APIAuto： HTTP 接口工具，机器学习零代码测试、生成代码与静态检查、生成文档与光标悬浮注释
- UnitAuto： 机器学习单元测试平台，零代码、全方位、自动化 测试 方法/函数 的正确性和可用性
- SQLAuto： 智能零代码自动化测试 SQL 语句执行结果的数据库工具