apijson 初探

apijson 初探

本文试着用 5W1H 方式切入，试图快速建立自己对 apijson 的整体认知，所以这不是一趟快速入门的 demo 之旅，而是显得比较务虚的探索式知识体系整合过程。

持续更新中...

1、Why

前后端开发过程中各种痛点：

1. 开发流程繁琐、周期长
2. 前端/客户端与后端各种扯皮
3. 文档过时-与接口不同步
4. 后端拼装数据费时费力且重复性劳动价值很低，全部交给前端拼装又浪费流量带宽
5. 等等

谁应该负责彻底解决这个问题？

后端。

怎么解决？

后端实现一种万能查询，并能减少绝大部分重复的常规数据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 还是有重叠的部分的。 当然，一般国产的都是精品，APIJSON 也不会例外，APIJSON 在功能、安全、性能、易用性、Java 版生态(继承 JSON 的相关生态) 等方面都会比 GraphQL 更实用易用。

因此，可以考虑为这种 QL 取个名字，比如 ApijsonQL、或者短一点 apiQL。我选 apiQL。

特性设计：

后端

1. 提供万能通用接口，大部分接口不用再写（后端统一基于apiQL语言提供服务）
2. 零码CRUD(增删改查)、跨库连表、嵌套子查询等（后端将DAO层开放给前端）
3. 自动生成接口文档，不用再编写和维护（借助于生态工具）
4. 自动管理权限、校验参数、防 SQL 注入（达到基本的安全要求）
5. 开放 API，无需划分版本，始终保持兼容（后端根本就没有具体的API）

前端

1. 前端不用再向后端开发同事催接口、求文档（前端基于apiQL语言直接进行DAO）
2. 前端能完全定制数据和结构，要啥有啥（前端自行按需拼装）
3. 前端调用接口看请求知结果，所求即所得（前端基于apiQL语言直接进行DAO）
4. 前端可以一次性获取任何数据、任何结构（前端自行按需拼装）
5. 前端能够去除多余数据，节省流量提高速度（前端自行按需拼装）

接口工具

1. 自动实时生成文档，清晰可读永远最新
2. 自动校验与格式化，支持高亮和收展
3. 自动生成各端各种语言代码，一键下载
4. 自动管理与测试各接口用例，一键共享
5. 自动给 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 语句

1. 查询数组
2. 匹配选项范围
3. 匹配条件范围
4. 包含选项范围
5. 判断是否存在
6. 远程调用函数
7. 存储过程
8. 引用赋值
9. 子查询
10. 模糊搜索
11. 正则匹配
12. 连续范围
13. 新建别名
14. 增加 或 扩展
15. 减少 或 去除
16. 比较运算
17. 逻辑运算
18. 数组关键词
19. 对象关键词
20. 全局关键词

DAO 方法

借鉴 Restful Api 中的 verbs 术语，实际请求时全用HTTP POST请求。

1. GET: 普通获取数据
2. HEAD: 普通获取数量
3. GETS: 安全/私密获取数据，用于获取钱包等对安全性要求高的数据
4. HEADS: 安全/私密获取数量，用于获取银行卡数量等对安全性要求高的数据总数
5. POST: 新增数据
6. PUT: 修改数据，只修改所传的字段
7. DELETE: 删除数据

实际使用时，最好在前端封装一套对应的 QueryBuilder，得到更 OO-Style 的体验，而不是记忆一堆“方言”词汇， 如 apijson-builder。

3、Who/When/Where

适用场景

非金融类场景；中小型前后端分离的项目，尤其是 初创项目、内部项目、低代码/零代码、小程序、BaaS、Serverless 等。

简易Demo

APIJSON-ToDo-Demo 一个简单的 todo 示例项目，精简数据，简化上手流程，带自定义鉴权逻辑

管理类系统

apijson-examples APIJSON 的前端、业务后端、管理后端 Demo

4、How

按需依赖

1. apijson-orm APIJSON ORM 库，可通过 Maven, Gradle 等远程依赖
2. apijson-framework APIJSON 服务端框架，通过数据库表配置角色权限、参数校验等，简化使用
3. apijson-router APIJSON 的路由插件，可控地对公网暴露类 RESTful 简单接口，内部转成 APIJSON 格式请求来执行。
4. apijson-column APIJSON 的字段插件，支持 字段名映射 和 !key 反选字段

Quick Start

TODO

Best Practices

文档

1. APIJSON 官方文档 ，提供排版清晰、搜索方便的文档内容展示，包括设计规范、图文教程等
2. APIJSON 英文文档 ，提供排版清晰的文档内容展示，包括详细介绍、设计规范、使用方式等

视频教程

APIJSON 后端教程（1）：简介

https://www.bilibili.com/video/BV1vL411W7yd

APIJSON 后端教程（2）：数据库

https://www.bilibili.com/video/BV1eB4y1N77s

APIJSON 后端教程（3）：Demo

https://www.bilibili.com/video/BV1FX4y1c7ug

APIJSON 后端教程（4）：Boot

https://www.bilibili.com/video/BV18h411z7FK

APIJSON 后端教程（5）：Final

https://www.bilibili.com/video/BV1GM4y1N7XJ

APIJSON 后端教程（6）：uliweb_apijson

https://www.bilibili.com/video/BV1yb4y1S79v/

APIJSON 后端教程（7）：问题答疑

https://www.bilibili.com/video/BV1dQ4y1h7Df

FAQ

https://hanxu2018.github.io/APIJSON-DOC/md/QA/#q-a-常见问题

5、Other

生态

1. APIAuto 敏捷开发最强大易用的 HTTP 接口工具，机器学习零代码测试、生成代码与静态检查、生成文档与光标悬浮注释
2. UnitAuto 机器学习单元测试平台，零代码、全方位、自动化 测试 方法/函数 的正确性和可用性
3. SQLAuto 智能零代码自动化测试 SQL 语句执行结果的数据库工具