Skip to content

Home

Jump to bottom
TommyLemon edited this page Dec 3, 2021 · 159 revisions

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

后端：零用时开发接口、零沟通零被打扰。

前端/客户端：内容可任意组合、结构可任意嵌套、零沟通零打扰零等待。

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

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

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

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

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

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

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

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

传统RESTful：对象为空时应该返回 null 或 {} ，但实际会返回空数组 []，
甚至是 "", "[]" 等 ，导致前端解析崩溃；
后端擅自改变类型导致线上App崩溃...

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

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

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

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

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

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

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

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

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

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

8.前端/客户端与后端扯皮

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

9.数据库操作不安全

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

10.开发流程繁琐周期长

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

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

...


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

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


实现原理：

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

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

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

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

"VERIFY": { "money&{}":">0,<=10000" }              //自动验证是否 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 的注释

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"                           // 跨数据库

"@explain":true                                    // 性能分析

"@role":"LOGIN"                                    // 访问角色

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


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

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

Clone this wiki locally