实体

实体是数据墙DBW 中最核心的概念。一个实体代表了你想通过 API 对外公开的一个数据库对象——可以是一张表、一个视图或一个存储过程。实体的配置决定这个数据库对象如何呈现在 REST、GraphQL 和 MCP 接口中。

实体与数据库对象的映射

每个实体通过 source 字段关联到一个具体的数据库对象：

{
  "entities": {
    "Book": {
      "source": {
        "type": "table",
        "object": "dbo.books"
      }
    }
  }
}

type 可以是 table（表）、view（视图）或 stored-procedure（存储过程）。object 是数据库中对象的名称。

实体名与 API 路径

实体名称直接决定 API 的访问路径：

• REST 端点：/api/{实体名}
• GraphQL 查询：{实体名} { items { ... } }
• MCP 工具：实体名出现在 read_records 等工具的参数中

你可以通过 rest.path 和 graphql.type 进一步自定义 REST 路径和 GraphQL 类型名。例如为 GraphQL 配置单复数名称：

{
  "graphql": {
    "type": {
      "singular": "Book",
      "plural": "Books"
    }
  }
}

配置后 GraphQL 查询使用复数形式：{ Books { items { ... } } }。

实体的配置维度

一个实体可以配置以下方面：

配置维度	说明
source	数据库对象类型和名称
fields	字段别名映射和主键指定
permissions	角色与操作的访问控制
relationships	与其他实体的关联关系
rest	REST 端点的启用、路径、方法控制
graphql	GraphQL 的启用、类型名、操作控制
cache	实体级别的缓存策略
mcp	是否对 MCP 工具暴露，以及暴露方式
health	实体级别的健康检查
description	实体的语义描述（用于 MCP 和文档）

自动实体

当数据库表数量庞大时，手工配置每个实体可能很繁琐。autoentities 允许你按模式匹配自动将数据库对象公开为实体：

{
  "autoentities": {
    "public-tables": {
      "patterns": {
        "include": ["dbo.public_%"],
        "exclude": ["dbo.public_internal_%"],
        "name": "{schema}_{object}"
      },
      "permissions": [
        { "role": "anonymous", "actions": ["read"] }
      ]
    }
  }
}

符合命名规则的表会在服务启动时自动成为 API 实体，无需手动逐个添加。目前 autoentities 仅支持 SQL Server。

实体关系

实体之间可以配置关系，这些关系会在 GraphQL 架构中自动体现为嵌套字段，支持一次查询获取关联数据：

{
  "entities": {
    "Category": {
      "source": "dbo.categories",
      "relationships": {
        "category_books": {
          "cardinality": "many",
          "target.entity": "Book",
          "source.fields": ["id"],
          "target.fields": ["category_id"]
        }
      }
    }
  }
}

关系支持三种基数：

基数	说明	示例
one	一对方一	一本书对应一个分类
many	一对方多	一个分类对应多本书
many（多对多）	通过关联表连接	书和作者，需要 linking.object 指定中间表

多对多关系需要额外指定关联表信息：

{
  "cardinality": "many",
  "target.entity": "Author",
  "source.fields": ["id"],
  "target.fields": ["id"],
  "linking.object": "dbo.books_authors",
  "linking.source.fields": ["book_id"],
  "linking.target.fields": ["author_id"]
}

存储过程参数

存储过程类型的实体可以配置参数信息，引擎会根据参数定义自动生成正确的调用方式：

{
  "entities": {
    "GetBookById": {
      "source": {
        "type": "stored-procedure",
        "object": "dbo.get_book_by_id",
        "parameters": [
          {
            "name": "id",
            "required": true,
            "description": "图书的唯一标识"
          }
        ]
      }
    }
  }
}

参数配置包含名称、是否必需、默认值和描述，这些信息会反映在 GraphQL 架构和 MCP 工具定义中。

实体抽象层的价值

实体在数据库内部结构和外部 API 之间建立了一层抽象。这让你可以：

• 为 API 使用更稳定、更面向业务的字段名（通过 fields.alias）：

  { "name": "sku_product_title", "alias": "title" }

• 隐藏不想暴露的数据库对象和字段。
• 让 REST、GraphQL、MCP 共享同一份实体定义和权限规则。