apijson 初探

2022-10-31 20:51 由 x3d 发表于 #软件设计

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 还是有重叠的部分的。当然，一般国产的都是精品，APIJSON 也不会例外，APIJSON 在功能、安全、性能、易用性、Java 版生态(继承 JSON 的相关生态) 等方面都会比 GraphQL 更实用易用。

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

特性设计：

后端

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

前端

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

接口工具

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