配置实体
entities 是配置文件中最核心的部分。每个实体对应一个数据库对象，实体配置决定了它如何呈现为 REST 端点、GraphQL 类型和 MCP 工具。
实体基本结构
{
"entities": {
"Book": {
"source": { "object": "dbo.books", "type": "table" },
"permissions": [
{ "role": "anonymous", "actions": ["read"] }
]
}
}
}实体名（如 Book）区分大小写，直接决定 REST 路径（/api/Book）和 GraphQL 类型名。建议使用 PascalCase 单数命名。
source — 数据库对象映射
source 定义实体对应哪个数据库对象：
| 字段 | 必需 | 说明 |
|---|---|---|
object | 是 | 数据库对象名称，格式为 schema.name |
type | 是 | 对象类型：table、view、stored-procedure |
parameters | 存储过程 | 存储过程的参数定义 |
* 视图没有显式主键，需要在 fields 数组中通过 primary-key: true 标记主键字段。未指定时 GET 按主键查询会退化为列表查询。
存储过程参数
{
"source": {
"type": "stored-procedure",
"object": "dbo.get_book_by_id",
"parameters": [
{
"name": "id",
"required": true,
"default": null,
"description": "图书 ID"
}
]
}
}参数使用数组格式（推荐），每个参数可指定 name、required、default 和 description。只有带默认值的参数可以省略。
permissions — 权限控制
每个实体必须配置至少一个权限。未配置权限的实体拒绝所有访问：
{
"permissions": [
{ "role": "anonymous", "actions": ["read"] },
{ "role": "authenticated","actions": ["read", "create"] },
{ "role": "editor", "actions": ["read", "create", "update"] },
{ "role": "admin", "actions": ["*"] }
]
}动作（actions）
| 动作 | 适用对象 | 说明 |
|---|---|---|
read | 表、视图 | 查询数据 |
create | 表、视图 | 插入新记录 |
update | 表、视图 | 修改已有记录 |
delete | 表、视图 | 删除记录 |
execute | 存储过程 | 执行存储过程 |
* | 全部 | 通配符，等于该类型支持的全部操作 |
字段过滤
按角色精确控制可访问的字段：
{
"role": "auditor",
"actions": [
{
"action": "read",
"fields": {
"include": ["*"],
"exclude": ["salary", "password_hash"]
}
}
]
}数据库策略
行级数据过滤，策略被转换为 SQL WHERE 条件：
{
"action": "read",
"policy": {
"database": "@item.ownerId eq @claims.userId"
}
}@item.<field> 引用实体字段，@claims.<claim> 引用用户令牌声明。策略仅适用于 read、update、delete。
fields — 字段映射
为数据库字段定义别名、描述和主键标记：
{
"fields": [
{ "name": "sku_product_title", "alias": "title" },
{ "name": "id", "primary-key": true }
]
}| 字段 | 说明 |
|---|---|
name | 数据库字段名（必需） |
alias | API 中的公开名称 |
primary-key | 标记为主键（替代已弃用的 source.key-fields） |
description | 字段描述（用于 MCP 和文档） |
rest — REST 端点控制
{
"rest": {
"enabled": true,
"path": "shopping-cart/item",
"methods": ["GET", "POST"]
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
enabled | 是否生成 REST 端点 | true |
path | 自定义路径，支持子目录 | 实体名 |
methods | 允许的 HTTP 方法（仅存储过程） | ["POST"] |
graphql — GraphQL 控制
{
"graphql": {
"enabled": true,
"type": { "singular": "Book", "plural": "Books" },
"operation": "query"
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
enabled | 是否出现在 GraphQL 架构中 | true |
type | 自定义类型名（单数/复数） | 实体名 |
operation | 存储过程的挂载位置：query 或 mutation | mutation |
relationships — 实体关系
定义实体间的关联，在 GraphQL 中自动生成嵌套查询：
{
"relationships": {
"book_authors": {
"cardinality": "many",
"target.entity": "Author",
"source.fields": ["id"],
"target.fields": ["book_id"]
}
}
}| 基数 | 说明 |
|---|---|
one | 一对一或多对一 |
many | 一对多或多对多 |
多对多关系需要额外指定 linking.object、linking.source.fields、linking.target.fields。关系仅在 GraphQL 中生效，REST 不支持嵌套查询。
cache — 实体级缓存
{
"cache": {
"enabled": true,
"ttl-seconds": 60,
"level": "L1L2"
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
enabled | 启用缓存 | false |
ttl-seconds | 缓存生存时间（秒） | 继承全局值 |
level | L1（仅内存）或 L1L2（内存+分布式） | L1L2 |
缓存仅在 REST 端点生效。数据发生增删改时缓存自动失效。
health — 实体级健康检查
{
"health": {
"enabled": true,
"first": 10,
"threshold-ms": 500
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
enabled | 是否将该实体纳入健康检查 | true |
first | 健康检查查询返回的行数（范围：1-500） | 100 |
threshold-ms | 健康检查查询的最大持续时间（毫秒） | 1000 |
first 值应小于或等于 runtime.pagination.max-page-size 设置。较小的值有助于健康检查更快完成。
注意： 存储过程自动从实体健康检查中排除，因为它们需要参数且可能不是确定性的。
mcp — MCP 工具控制
{
"mcp": {
"dml-tools": true,
"custom-tool": false
}
}| 字段 | 说明 | 默认值 |
|---|---|---|
dml-tools | 是否向 MCP 代理暴露 DML 工具 | true |
custom-tool | 是否将存储过程注册为命名 MCP 工具（仅存储过程） | false |
description — 语义描述
{
"description": "图书信息表，包含书名、作者、出版年份和价格"
}描述出现在 MCP 工具定义和生成的 API 文档中，帮助 API 消费者和 AI 代理理解数据含义。
使用 CLI 管理实体
# 添加表实体
dab add Book --source "dbo.books" --permissions "anonymous:read"
# 添加存储过程实体
dab add GetBook --source "dbo.get_book_by_id" --source.type "stored-procedure" --permissions "anonymous:execute"
# 更新实体权限
dab update Book --permissions "authenticated:*"CLI 命令会直接修改配置文件，你也可以手动编辑 JSON 后再运行 dab validate 校验。