配置化 API 生成

数据墙DBW 的核心设计理念是"配置即接口"。开发者通过 JSON 配置文件声明数据源、实体、权限和运行时行为，引擎在运行时根据配置动态生成 API。整个过程不产生代码文件，不需要编译，修改配置后重启即可生效。

一个文件驱动一切

单个 JSON 配置文件即可完整描述一个数据 API 服务：

{
  "$schema": "dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": { "enabled": true },
    "graphql": { "enabled": true }
  },
  "entities": {
    "Book": {
      "source": { "object": "dbo.books", "type": "table" },
      "permissions": [
        { "role": "anonymous", "actions": ["read"] }
      ]
    }
  }
}

以上配置定义了一个连接到 SQL Server 的服务，将 dbo.books 表通过 REST 和 GraphQL 对外公开，并允许匿名用户读取。写好这份文件，运行 dab start，API 即可用。

核心配置维度

数据源

data-source 定义数据库类型和连接信息。支持 SQL Server、PostgreSQL、MySQL 等数据库。连接字符串支持环境变量引用 @env('NAME')，避免在配置文件中硬编码密码。

实体

entities 是最核心的配置块。每个实体对应数据库中的一个表、视图或存储过程：

• source：指定映射的数据库对象和类型。
• rest / graphql：控制该实体在哪种协议中公开，可自定义路径和类型名。
• permissions：定义哪些角色可以执行哪些操作。
• fields：字段别名映射和主键指定。
• relationships：实体间的关联关系定义。
• cache：实体级缓存策略。

自动实体发现

除了手工定义每个实体，你还可以使用 autoentities 按模式匹配自动公开数据库对象：

{
  "autoentities": {
    "demo-tables": {
      "patterns": {
        "include": ["dbo.%"],
        "exclude": ["dbo.internal%"],
        "name": "{schema}_{object}"
      },
      "template": {
        "rest": { "enabled": true },
        "graphql": { "enabled": true }
      },
      "permissions": [
        { "role": "anonymous", "actions": ["read"] }
      ]
    }
  }
}

这个配置会自动将 dbo 架构下所有表（排除 dbo.internal*）公开为实体。适合表数量庞大或频繁新增表的场景。

多配置文件

当实体数量多时，可以通过 data-source-files 将实体拆分到多个配置文件中管理。每个文件各自定义实体，顶层文件集中管理运行时设置。实体名称在所有文件中必须唯一。

实体模型即 API

实体配置在数据库内部结构和外部 API 之间建立了一层抽象。这层抽象带来了几个关键收益：

• 命名解耦：API 字段名可以与数据库列名不同。sku_title 可以对外显示为 title。
• 安全边界：未配置的数据库对象不会被 API 暴露，防止意外泄露。
• 多协议一致：同一份实体模型同时驱动 REST、GraphQL 和 MCP，三者的权限与字段规则保持一致。
• 零代码修改：数据库加表、改字段名后，只需调整配置，不需要改代码、重新编译。

配置与代码的关系

数据墙DBW 不排斥业务代码。你可以把它看作数据库访问层的一种配置化实现方式：

• 标准数据读取和写入由配置文件处理。
• 复杂业务逻辑仍然在独立的业务服务中实现。
• 配置可以由 CI/CD 流水线管理，支持多环境切换和版本控制。

下一步

• 阅读配置架构参考 查看完整的配置字段说明。
• 阅读配置数据源 了解数据库连接配置。