多配置文件管理

当实体数量多、或者需要同时连接多个数据库时，把所有配置塞进一个文件会变得难以维护。数据墙DBW 支持通过 data-source-files 将实体拆分到多个配置文件中，实现模块化的配置管理。

适用场景

• 连接多个不同类型或不同位置的数据库。
• 实体数量庞大（几十张表以上），需要按业务域拆分。
• 不同团队维护各自负责的实体配置。
• 按环境差异化部分配置。

基本用法

创建一个顶层配置文件作为入口，在 data-source-files 中引用其他配置文件：

顶层文件：dab-config.json

{
  "$schema": "dab.draft.schema.json",
  "data-source-files": [
    "config-crm.json",
    "config-erp.json",
    "subsystems/config-logistics.json"
  ],
  "runtime": {
    "rest": { "enabled": true },
    "graphql": { "enabled": true },
    "host": { "mode": "production" }
  }
}

子文件：config-crm.json

{
  "$schema": "dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('CRM_DB_CONN')"
  },
  "entities": {
    "Customer": {
      "source": { "object": "dbo.customers", "type": "table" },
      "permissions": [
        { "role": "authenticated", "actions": ["read"] }
      ]
    }
  }
}

子文件：config-erp.json

{
  "$schema": "dab.draft.schema.json",
  "data-source": {
    "database-type": "postgresql",
    "connection-string": "@env('ERP_DB_CONN')"
  },
  "entities": {
    "Order": {
      "source": { "object": "public.orders", "type": "table" },
      "permissions": [
        { "role": "authenticated", "actions": ["read"] }
      ]
    }
  }
}

合并规则

多配置文件在加载时遵循以下规则：

规则	说明
顶层 runtime 生效	只有顶层文件中的 runtime 设置会被使用，子文件中的 runtime 会被忽略
子文件必须有 data-source	每个子文件各自定义自己的数据库连接
子文件必须有 entities	每个子文件提供自己的实体集合
实体名全局唯一	所有文件中不能有重复的实体名
不支持跨文件关系	不同文件中定义的实体之间不能配置 relationships
支持嵌套引用	子配置文件还可以再引用自己的 data-source-files
支持子目录	配置文件可以放在子文件夹中

同一个数据库的分文件

即使是同一个数据库，也可以把实体按业务域拆分到不同文件中：

顶层文件：

{
  "data-source-files": ["config-products.json", "config-users.json", "config-orders.json"],
  "runtime": { ... }
}

config-products.json：

{
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('MAIN_DB_CONN')"
  },
  "entities": {
    "Product": { ... },
    "Category": { ... }
  }
}

这种方式让每个业务域的配置独立维护，减少修改冲突。

组织建议

场景	建议组织方式
按数据库分文件	每个数据库一个配置文件，顶层文件做路由
按业务域分文件	同一数据库按 Domain 拆分，各团队维护自己的文件
按环境分文件	配合 DAB_ENVIRONMENT 加载不同环境配置
混合模式	顶层定义公共运行时，子文件各自定义数据源和实体

限制与注意事项

• 跨文件不能定义实体关系。如果需要跨数据源关联查询，需要在应用层实现。
• 不允许循环引用（文件 A 引用 B，B 又引用 A）。
• 如果子文件路径错误或不存在，服务启动会报错。
• 配置文件较多时，建议统一放在子目录中保持整洁。

下一步

• 环境变量与密钥 — 安全地管理多环境的连接信息。
• 配置最佳实践 — 生产级配置建议。