Skip to content

Home

Jump to bottom
TommyLemon edited this page Feb 8, 2023 · 159 revisions

为什么要用零代码接口与文档 ORM 库 APIJSON ？
前后端接口的 开发、文档、联调 等 10 大痛点解析

APIJSON 九阴真经 - 软件开发行业的 ATM 机

接口全万能，前端不求人。要啥就有啥，所求即所得。
需求由它变，后端稳如山。不变应万变，上午就上线。

后端：零用时开发接口、零沟通零被打扰。
前端(客户端)：内容可任意组合、结构可任意嵌套、零沟通零打扰零等待。

后端不用写接口、也不用写文档就能提供"接口"和"文档"，前端(客户端)不用看"文档"就能调用"接口"。

APIJSON 实现了前端(客户端)要什么就返回什么，而不是后端给什么才能用什么，
从根本上解决了：

1.开发流程繁琐周期长

传统方式：后端写接口>后端写文档>前端/客户端查文档>(前端(客户端)关于文档向后端提问>后端解决问题并通知或等待再次被问)>前端(客户端)调用接口>(前端(客户端)关于实际使用向后端提问>后端解决问题并通知或等待再次被问)>前端(客户端)解析返回结果>(前端(客户端)关于返回内容或结构向后端提问>后端解决问题并通知或等待再次被问)

APIJSON：前端(客户端)调用接口>前端(客户端)解析返回结果

2.前端(客户端)与后端扯皮

传统方式：前端(客户端)想要一次性返回或者更方便解析的结构，但后端想要少写代码
APIJSON：完全由前端(客户端)发的请求指定返回的 JSON 内容与结构，可任意组合任意嵌套，后端完全是自动解析不需要写代码

3.数据类型不稳定或随意改变

传统方式：对象为空时应该返回 null 或 {} ，但实际会返回空数组 [] (常见于 PHP, Lua 等脚本语言开发的后端 HTTP API)，
甚至是 "", "[]" 等 ，导致前端解析崩溃；
后端擅自改变类型导致线上App崩溃...

APIJSON：提供万能通用 API，所有字段对应值的类型都能保证是稳定的，
后端都不需要写代码也就不会去改变类型。

4.文档过时，与接口不同步

传统方式：后端把接口改了没有及时通知，前端(客户端)莫名其妙调了半天才发现
APIJSON：可以用 APIAuto-机器学习 HTTP 接口工具 查看测试用例、以及表和字段的属性，
包括名称、类型、长度、默认值、注释等

5.数据库操作不安全

传统方式：DELETE 忘加 WHERE 直接删光全部数据，只要发生一次
APIJSON：对写操作强制要求指定 id:1 (单个) 或 id{}:[1,2,3] (批量)，并且自动校验权限、自动加 LIMIT

6.几百甚至上千个混乱的状态码

传统方式：各项目几乎完全不通用，不看相关的内部文档根本不知道对应的错误是什么，而且文档还很可能有错误。
例如
注册: 成功 600, 手机号不合法 601, 验证码错误 603, 手机号已注册 607, 缺少必要字段 609...
评论: 成功 1070, 不允许评论 1071, 参数错误 1073, 动态被删除 1075...

APIJSON：只有十几个 HTTP 标准状态码，注释详细，即便不看注释网上一查也有一大堆正确的结果

7.各种奇葩的缩写、混乱的命名

传统方式：各种缩写、拼音、驼峰和非驼峰混用等，
只有看文档才知道是什么、才知道用哪个，而且文档还很可能有错误。
例如
评论数量可能是 commentCount, comment_count, cmt_count, pl_num...
分页页码可能是 page, pageNum, page_number, page_num, pnum...

APIJSON：常用的字段都已标准化，限制列表数量都用 count，分页页码都用 page，总数都用 total

8.应用界面和接口强耦合难分离

传统方式：比如某个版本的 QQ 空间动态的 JSON 结构必须对应某个版本的某个接口，
有时候 JSON 结构甚至是由后端拍脑袋决定的，不好用也得用
APIJSON：完全由请求指定返回的 JSON 结构，即便 UI 变化也不需要对接口做任何更改

9.版本迭代导致大量重复功能的接口

传统方式：为了兼容旧版应用不好直接改原来的接口，一般只能新增
APIJSON：查询不需要对接口做任何更改，增删改可用 Navicat, DataGrip, MySQLWorkbench 等可视化工具

10.浪费性能、流量和带宽

传统方式：返回不需要的字段、对象等
APIJSON：完全由请求指定返回内容，没有不需要的

...


其它所有的接口开发库、框架、生成代码工具等，
不管是快速还是极速，就算是光速也没 APIJSON 快，
因为它们再怎么快也是要花时间的，
而用 APIJSON 开发接口根本就不用时间！
因为根本就不需要 编写或生成 接口！
需求一提出来就已经支持了，需求变更也不用修改代码或重新生成！

考虑实际情况下不仅要操作数据库，还要校验接口参数和用户权限等，以及需求不会覆盖排列组合嵌套的所有可能，
即便这样算下来 APIJSONBoot(按慢估计) 对比 SSM/SSH(按快估计) 等开发效率保守估计也都还能提升 20 倍以上
https://github.com/Tencent/APIJSON/issues/132

按照一般互联网中小型项目情况可得出以下对比表格：

表数量 T 平均每表字段数 C APIJSONBoot 按慢估计 SSMH 按快估计 APIJSONBoot 提速倍数
1 3 11 min(约十分钟) 179 min(约一上午) 15.27
5 4 70 min(约一小时) 1935 min(约朝九晚六一周) 26.64
10 10 320 min(约一上午) 8550 min(大小周超过半个月) 25.72
20 15 940 min(约上班两天) 31900 min(约 996 两个月) 32.94
50 20 3100 min(约上班一周) 176750 min(11117 超过半年) 56.02

实现原理：

image

APIJSONORM 将 APIJSON 格式的请求 JSON 自动转换为 SQL 语句连接数据库并执行，
然后返回对应结构和内容的JSON，期间自动校验角色及对应的操作权限、自动防 SQL 注入。
(具体见 如何实现其它语言的 APIJSON？ 以及开源中国 Gitee Meetup 的视频讲解 APIJSON-零代码接口和文档 ORM 库)

内置角色见 AbstractVerifier.java 的角色常量。 image

还可自动校验内容，比如在数据库配置 

"VERIFY":{
  "type{}":[0,1,2]
}

就能校验 type 的值是不是 0，1，2 中的一个。
还有 

"VERIFY": { "money&{}":">0,<=10000", "key-()":"verifyAccess()" }  // 自动验证是否 money>0 & money<=10000，通过远程函数自定义验证权限
"TYPE": { "balance": "DECIMAL" }                                  // 自动验证 balance 类型是否为 BigDecimal
"UNIQUE": "phone"                                                 // 强制 phone 的值为数据库中没有的
"MUST": "id,name"                                                 // 强制传 id,name 两个字段
"REFUSE": "balance"                                               // 禁止传 balance 字段
"INSERT": { "@role": "OWNER" }                                    // 如果没传 @role 就自动添加
"UPDATE": { "id@": "User/id" }                                    // 强制放入键值对

全部操作符见 Operation.java 的注释

image



APIJSON目前已实现：

大体功能：
增删改查、分页排序、分组聚合、统计组合、模糊搜索、正则匹配、连续范围、比较运算、逻辑运算、
全文检索、各种JOIN、各种子查询、字段过滤、多数据库、跨库连表、性能分析、排列组合、结构变换、
存储过程、远程函数调用、多级缓存规则、数据与结构校验、角色与操作权限校验 等。

操作方式：
增、删、改、查、调用远程函数

操作对象：
单个对象、可关联的多个对象、数组等

请求方法：
GET, HEAD, GETS, HEADS, POST, PUT, DELETE

请求结构：
{ "Table":{...} }
{ "Table0":{...}, "Table1":{...}, "Table2":{...} ... }
{ "[]":{ "Table":{...} } }
{ "[]":{ "Table0":{...}, "Table1":{...}, "Array0[]":{...}, ... } }
等各种组合和嵌套

返回结构：
对应请求结构的各种JSON结构。

功能符号：

"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"                                    // 访问角色

详细说明见通用文档中的 功能符

APIJSON_Auto_summary


后端接口和文档零代码，前端(客户端) 定制返回JSON的数据和结构！

创作不易、坚持更难，右上角点 ⭐Star 支持下吧，谢谢 ^_^
https://github.com/Tencent/APIJSON

Clone this wiki locally