ApiJSON

定义

ApiJSON 包含两层含义：一是指一套以 JSON 描述数据请求的传输结构协议，二是指按该协议实现的服务端 ORM 库^[1][4]。与常规 HTTP 接口为每个业务场景定义独立 URL 和参数表不同，ApiJSON 把表名、字段、条件、排序、分页等信息都写在请求 JSON 里，服务端按统一规则解释执行^[5][6]。

请求体最外层放置全局关键词，如版本号、标签和格式化开关；内层以大写字母开头的键表示数据库表，以方括号结尾的键表示数组查询，对象内部还可继续嵌套表和条件，形成分层结构^[6]。响应仍然保持与请求同构的 JSON 结构，并附上状态码与提示信息^[6]。

原理

服务端解析器是协议的执行核心。解析入口逐层遍历请求 JSON，各对象解析器把表名、字段和条件转换为 SQL 配置对象，再由执行器拼装 SQL、绑定参数并访问数据库^[6]。由于 SQL 由程序按白名单规则生成，客户端不能直接提交 SQL 片段，这也是该框架被视为相对安全的基础^[7]。

协议为键名后缀设计了一组功能符，用来表达 SQL 语义。键名以 $ 结尾表示模糊搜索，如 name$ 后接含有百分号的匹配串；以 ~ 结尾表示正则匹配；以 % 结尾表示区间；以 {} 结尾表示从给定集合中取值；以 @ 结尾表示引用，值是另一处的字段路径，用于把两个表关联起来；以 () 结尾表示调用服务端注册的远程函数^[8][9]。

数组查询可以使用 count、page、query 等关键词控制条数、页码和是否返回总数，表对象则可用 @column、@order、@group、@having 控制返回字段、排序、分组与聚合条件^[10][9]。关联查询通过 join 键声明，前缀符号区分连接方式，例如 < 表示左连接，& 表示内连接，@ 表示将副表查询合并为主表条件中的 IN 查询以提高效率^[9][10]。

对写操作而言，请求需要携带 tag 以匹配服务端在 Request 表中登记的规则，表结构、字段和条件须与预置配置一致，否则请求被拒绝；角色和行级权限同样通过数据库表配置完成^[6]。

发展历程

该项目由腾讯工程师 TommyLemon 发起，2016 年 11 月对外开源，最初以 Java 实现为主，并配套提供演示工程、服务端框架与插件等多个子项目^[11][12]。

此后版本持续迭代。2021 年 4 月发布的 4.6.7 版本对外公布项目在代码托管平台上的关注数突破一万，同期的 4.6.1 至 4.6.7 版本加强了对 JOIN 与 SQL 函数的防护^[11]。5.0.0 版本新增 @having& 等条件组合写法，5.1.0 版本扩充了请求参数校验、修正了多项数据库兼容问题并新增路由插件，5.1.5 版本开始支持跨层级的 APP JOIN^[13][14]。

5.3.0 版本增加了对达梦数据库的支持^[14]。根据 2026 年初的公开介绍，项目已迭代到 8 版本，在代码托管平台上获得约 1.8 万个关注和 2400 个复刻，多语言实现覆盖 Go、Node.js、Python、PHP、C#、Rust 等。

应用

该协议面向中小型前后端分离项目，常见于初创项目、内部系统、低代码或零代码平台、小程序后端，以及 BaaS 与 Serverless 类服务^[1]。其价值在于把接口改动从后端转移到请求 JSON 上，需求变化时前端调整参数即可生效，不必等待后端新增接口和文档^[2]。

配套工具 APIAuto 用于在线校验请求 JSON、生成文档与客户端请求代码，并支持接口回归测试，可在不编写测试代码的情况下完成接口验证^[15]。项目文档列举的使用单位覆盖互联网、制造、物流与通信等行业，涉及社交、资讯、影音等非金融类业务^[2]。

局限

适用范围被明确限定在中小型项目。项目说明指出，对安全性要求很高的金融类系统，以及接口普遍承载复杂业务逻辑、维护周期较长或用户规模很大的项目，并不适合采用该方案^[16]。这类系统通常需要在服务端集中编写业务规则，而这与把查询结构交给客户端决定的思路存在冲突。

关联查询的性能取决于写法。若只用 @ 引用而不声明 JOIN，服务端会先查主表、再按每行结果分别查询副表，形成 N+1 次查询，数据量大时耗时随记录数增长；改用具名 JOIN 才能把多次查询合并^[17][14]。因此同一份请求在不同写法下性能差异明显。

协议对请求格式相当敏感。表名、字段名、关键词和值在大小写、逗号、空格与换行上都按规则校验，表名须以大写字母开头，多数情况下不允许出现空格与换行，不符合规范即报错^[3]。客户端传参需按文档约定书写，学习成本相应体现在参数语法而非接口数量上。

可表达的查询能力也受服务端配置约束。查询复杂度设有默认上限，如 WHERE 条件数、HAVING 表达式数、条件组合层数均有固定阈值，超出即被拒绝，需要调整服务端参数才能放开^[18]。面向特定数据库的性能分析等特性，在部分数据库上仍存在使用限制^[19]。

参见

• JSON —— ApiJSON 请求与响应所采用的数据格式基础。

• 对象关系映射 —— 该协议附带的 ORM 库所实现的功能类型。

• SQL —— 服务端解析请求后实际生成并执行的查询语言。

• GraphQL —— 同样让客户端声明所需数据结构的接口查询方案。

• REST —— 传统按资源划分 URL 的接口风格，与该协议的统一入口方式形成对照。