Skip to content
TommyLemon edited this page Nov 5, 2019 · 106 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-自动化接口管理工具 查看测试用例、以及表和字段的属性,
包括名称、类型、长度、默认值、注释等

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开发接口根本就不用时间!
因为根本就不需要写接口!


实现原理:

APIJSON-Server将APIJSON格式的请求JSON自动转换为SQL语句连接数据库并执行,
然后返回对应结构和内容的JSON,期间自动校验角色及对应的操作权限、自动防 SQL 注入。
还可自动校验内容,比如在数据库配置

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

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

"VERIFY": { "money&{}":">0,<=10000" }              //自动验证是否 money>0 & money<=10000
"TYPE": { "balance": "Double" }                    //自动验证balance类型是否为Double
"UNIQUE": "phone"                                  //强制phone的值为数据库中没有的
"NECESSARY": "id,name"                             //强制传id,name两个字段
"DISALLOW": "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/TommyLemon/APIJSON

Clone this wiki locally
You can’t perform that action at this time.