Skip to content
TommyLemon edited this page Jul 2, 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 SSMH 按快估计 APIJSONBoot 按慢估计 APIJSONBoot 提速倍数
1 3 179 min(约一上午) 11 min(约十分钟) 15.27
5 4 1935 min(约朝九晚六一周) 70 min(约一小时) 26.64
10 10 8550 min(大小周超半个月) 320 min(约一下午) 25.72
20 15 31900 min(约 996 两个月) 940 min(约上班两天) 32.94
50 20 176750 min(11117 超半年) 3100 min(约上班一周) 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