APIJSON语法大全，开发接口常备

核心思想🧠

在深入语法之前，请先理解其核心思想：“你说你要什么，我返回给你什么”。客户端发送一个描述了所需数据结构和关系的 JSON 对象（查询语句），服务端解析这个 JSON，生成相应的 SQL 语句，查询数据库，并将结果以相同的 JSON 结构返回。

APIJSON 的语法主要围绕以下几个核心概念构建：

1. 关键字：以 @ 开头的特殊键，用于执行特定操作。
2. 字段名：对应数据库表中的列名。
3. 值：用于过滤、匹配的具体值。
4. 数组：用于指定要查询的字段或组合多个查询条件。
5. 嵌套对象：用于描述表之间的关联关系（JOIN）。

一、基本查询

1. 查询单个对象

最简单的查询，通常对应数据库中的一行数据。

请求：POST/apijson/get

{
  "User": {
    "id": 1
  }
}

响应：

{
  "User": {
    "id": 1,
    "name": "孙悟空",
    "age": 30
  },
  "code": 200,
  "msg": "su***ess"
}

说明： 查询 User 表中 id 为 1 的用户的所有字段。

2. 指定返回字段

使用 @column 关键字来指定只返回哪些字段，避免返回不必要的数据。

请求：POST/apijson/get

{
  "User": {
    "id": 1,
    "@column": "name,age"
  }
}

响应：

{
  "User": {
    "name": "孙悟空",
    "age": 30
  },
  "code": 200,
  "msg": "su***ess"
}

说明： 只查询 User 的 name 和 age 字段。

3. 条件查询

使用各种操作符来过滤数据。

请求：POST/apijson/get

{
  "User[]": {
    "User": {
      "age{}": [18, 30],
      "@column": "id,name,age"
    },
    "count": 5
  }
}

响应：

{
  "User[]": [
    {"id": 1, "name": "孙悟空", "age": 30},
    {"id": 2, "name": "猪八戒", "age": 28}
  ],
  "code": 200,
  "msg": "su***ess"
}

说明：

• User[]：表示查询一个数组（列表）结果。
• age{}: [18, 30]：表示 age BETWEEN 18 AND 30。
• count: 5：表示最多返回 5 条记录（相当于 LIMIT 5）。

常用条件操作符：

"id|{}": [1, 2, 3] 
SQL等价	id = 1 OR id = 2 OR id = 3 
说明	多个条件 OR

二、分页、排序和函数

1. 分页

使用 @query 子句，结合 page 和 count。

请求：POST/apijson/get

{
  "User[]": {
    "User": {
      "@column": "id,name",
      "age{}": “>=20”
    },
    "page": 0, // 页码，从 0 开始
    "count": 10 // 每页数量
  }
}

说明： 相当于 LIMIT 0, 10。

2. 排序

使用 @order 关键字。

请求：POST/apijson/get

{
  "User[]": {
    "User": {
      "@column": "id,name,age",
      "@order": “age-,id+” // 按年龄降序，再按id升序
    }
  }
}

说明： age- 表示 age DESC，id+ 或 id 表示 id ASC。

3. 数据库函数

可以在 @column 中使用 SQL 函数。

请求：

{
  "User": {
    "id": 1,
    "@column": "name, UPPER(name) as upperName, COUNT(id)"
  }
}

三、关联查询（表连接）

这是 APIJSON 最强大的功能之一，通过嵌套 JSON 来描述表之间的关系。

1. 一对一 / 多对一

例如，一个 Moment（朋友圈）对应一个 User（发布者）。

请求：POST/apijson/get

{
  "Moment": {
    "id": 12,
    "@column": "content,userId",
    "User": { // 嵌套查询，关联到User表
      "@column": "name",
      "id@": “/Moment/userId” // ！关键语法！：将User表的id与Moment表的userId关联
    }
  }
}

响应：

{
  "Moment": {
    "content": "今天天气真好",
    "userId": 38710,
    "User": {
      "name": "孙悟空"
    }
  },
  "code": 200,
  "msg": "su***ess"
}

🎯 说明： "id@": "/Moment/userId" 是核心，意思是 User 表的 id 字段的值由父对象（Moment）的 userId 字段决定。

2. 一对多 / 多对多

例如，一个 User 对应多个 Moment（他发布的所有朋友圈）。

请求：POST/apijson/get

{
  "User": {
    "id": 38710,
    "@column": "name",
    "Moment[]": { // 使用数组表示一对多
      "Moment": {
        "@column": "content",
        "userId@": “/User/id” // ！关键语法！：Moment表的userId等于父对象（User）的id
      }
    }
  }
}

响应：

{
  "User": {
    "name": "孙悟空",
    "Moment[]": [
      {"content": "今天天气真好"},
      {"content": "取经路上..."}
    ]
  },
  "code": 200,
  "msg": "su***ess"
}

3. 多表关联

可以无限嵌套，实现复杂的多表关联。

请求： (查询一个朋友圈，同时包含发布者信息和评论列表，以及每条评论的评论者信息)

{
  "Moment": {
    "id": 12,
    "@column": "content",
    "User": {
      "@column": "name",
      "id@": “/Moment/userId”
    },
    "***ment[]": {
      "***ment": {
        "@column": "content",
        "momentId@": “/Moment/id”, // 评论关联到朋友圈
        "User": { // 每条评论的发布者
          "@column": "name",
          "id@": “/***ment[]/***ment/userId”
        }
      }
    }
  }
}

🎯说明： "id@": “/***ment[]/***ment/userId” 这里的路径需要指向正确的层级。

四、子查询

使用 @sub 关键字来定义子查询。

请求： (查询年龄大于平均年龄的用户)

{
  "User[]": {
    "User": {
      "age>@": {
        "@sub": “getAvgAge” // 引用一个名为getAvgAge的子查询
      },
      "@column": "id,name,age"
    }
  },
  “getAvgAge”: { // 定义子查询
    “func”: “avg”,
    “name”: “age”,
    “from”: “User”
  }
}

五、增删改操作

这些操作通常需要权限验证。

1. 新增 (POST)

使用 @json 关键字包裹要新增的数据。

请求：POST/apijson/post

{
  "User": {
    "@json": {
      "name": "沙和尚",
      "age": 35
    }
  }
}

2. 修改 (PUT)

使用 @replace 关键字。

请求：POST/apijson/put (将 id 为 1 的用户年龄改为 31)

{
  "User": {
    "id": 1,
    "@replace": {
      "age": 31
    }
  }
}

3. 删除 (DELETE)

直接指定要删除的记录的 ID。

请求：POST /apijson/delete

{
  "User": {
    "id": 4,
    "@delete": true
  }
}

六、高级功能

1. 远程函数 (Function)

调用服务端预定义的函数。

请求：

{
  “@func”： “count”， // 调用count函数
  “tag”： “Moment” // 传递参数
}

2. 变量和引用

可以在一个请求中定义变量并在其他地方引用，避免重复查询。

请求：

{
  "userRef": { // 定义一个变量块
    "User": {
      "id": 1,
      "@column": "id,name"
    }
  },
  "Moment": {
    "userId@": “userRef/User/id”， // 引用上面查询到的id
    "@column": "content"
  }
}

3. 权限控制 (@correct / @role)

在表对象上添加 @role 关键字来指定执行该操作所需的角色。

请求：

{
  "User": {
    "id": 1,
    "@column": "name,phone”， // 普通人只能看到name和phone
    "@role": “LOGIN”
  },
  “User-secret”: { // 定义一个只有管理员能访问的“虚拟表”
    "User": {
      "id": 1,
      "@column": “balance,secret”， // 管理员能看到余额和秘密信息
      "@role": “ADMIN”
    }
  }
}

总结

APIJSON 的语法可以总结为以下模式：

最佳实践建议：

1. 从简单开始：先掌握基本查询和条件过滤。
2. 理解路径引用：/Table/field 和 /Table[]/Table/field 的写法是关联查询的核心，需要多加练习。
3. 使用 @column：始终指定需要的字段，这是提升性能的关键。

🔗参考官方文档：APIJSON 的 GitHub 仓库和官方文档有最全、最新的语法说明和示例。

🎀希望这份详细的罗列能帮助你全面掌握 APIJSON 的语法！