配置最佳实践
本文汇总了数据墙DBW 配置管理的推荐实践，覆盖命名规范、安全策略、环境管理和常见陷阱。
命名规范
实体名使用 PascalCase 单数
// 推荐
{ "entities": { "Book": { ... } } }
// 不推荐
{ "entities": { "books": { ... }, "my_book": { ... } } }使用 PascalCase 单数命名的好处：
- GraphQL 会基于实体名自动生成复数形式（
Book→Books→createBook）。 - 类型名在客户端代码中更符合编程语言惯例。
- 存储过程实体自动加
execute前缀，executeGetBookById比executeget_book_by_id更可读。
自定义 GraphQL 类型名
如果默认命名不满足需求，可以显式指定单复数：
{
"graphql": {
"type": { "singular": "Book", "plural": "Books" }
}
}表命名建议
如果计划使用 autoentities，建议提前约定数据库表命名规范（如前缀 public_、api_），让模式匹配更精准。
安全策略
密钥永远不进配置文件
// 正确
{ "connection-string": "@env('SQL_CONN_STR')" }
// 错误
{ "connection-string": "Server=...;Password=MyP@ssw0rd;" }.gitignore 必须包含
# 环境变量文件
.env
*.env
# 包含密钥的配置文件（如使用环境特定配置）
dab-config.Production.json如果环境配置文件包含敏感信息，也应排除在版本控制之外。仅提交模板和开发环境配置。
生产环境关闭 Swagger 和内省
{
"runtime": {
"host": { "mode": "production" },
"graphql": { "allow-introspection": false }
}
}mode: production 自动禁用 Swagger UI 和详细错误信息。
运行前校验配置
dab validate --config ./dab-config.json将 dab validate 加入 CI/CD 流水线，防止错误配置进入生产环境。
环境管理
按环境分层
dab-config.json # 实体定义、权限、关系（所有环境共享）
dab-config.Development.json # 开发环境：mode + 连接字符串
dab-config.Production.json # 生产环境：mode + 连接字符串 + 严格安全设置实体定义只写在基础文件中，避免多环境实体配置不一致。
环境文件只写差异
环境文件中不应该重复基础文件的实体定义。只写该环境特有的覆盖项：
// dab-config.Production.json — 只写与基础不同的字段
{
"data-source": {
"connection-string": "@env('PROD_CONN_STR')"
},
"runtime": {
"host": { "mode": "production" }
}
}CI/CD 中的注意事项
- 构建阶段使用
dab validate校验配置语法。 - 部署阶段通过环境变量注入连接信息，不要在镜像中打包密钥。
- Docker 构建时不要将
.env文件 COPY 到镜像中。
多数据源组织
当需要连接多个数据库时，使用 data-source-files 拆分配置：
// dab-config.json（顶层文件）
{
"data-source-files": [
"config-crm.json",
"config-erp.json"
],
"runtime": { "host": { "mode": "production" } }
}每个子文件各自定义 data-source 和 entities。按业务域或数据库拆分，减少单文件体积和修改冲突。
注意： 跨文件定义的实体之间不能配置
relationships。
组织建议
| 场景 | 建议组织方式 |
|---|---|
| 按数据库分文件 | 每个数据库一个配置文件 |
| 按业务域分文件 | 同一数据库按 Domain 拆分，各团队维护自己的文件 |
| 按环境分文件 | 配合 DAB_ENVIRONMENT 加载不同环境配置 |
配置版本控制
- 使用 Git 管理配置模板文件（
dab-config.json、dab-config.Development.json）。 - 排除包含密钥的文件（
dab-config.Production.json、.env）。 - 生产环境配置通过 CI/CD 流水线动态生成或从密钥管理服务注入。
- 在 PR 审查阶段运行
dab validate确保配置语法正确。
配置热重载
数据墙DBW 支持部分配置的热重载（无需重启服务）：
| 配置项 | 支持热重载 | 说明 |
|---|---|---|
telemetry.log-level | ✅ | 唯一支持生产环境热重载的配置 |
| 其他配置 | ❌ | 需要重启服务生效 |
修改 log-level 后引擎自动应用，无需重启。其他配置修改后需要重启服务。
性能与稳定性
合理设置分页大小
{
"runtime": {
"pagination": {
"default-page-size": 50,
"max-page-size": 1000
}
}
}默认 100 条适用于大多数场景。表数据量大时适当降低默认值，避免单次查询消耗过多内存。max-page-size 防止客户端一次拉取海量数据。
谨慎使用 GraphQL 深度限制
{
"runtime": {
"graphql": {
"depth-limit": 5
}
}
}存在深层嵌套的关系查询时，设置合理的深度限制防止恶意或意外的大查询。
缓存策略
- 读多写少的实体优先开启缓存，显著降低数据库压力。
- 实体级 TTL 应根据数据更新频率设置，而不依赖全局默认值。
- 多实例部署时启用 L2 缓存（Redis）共享缓存。
响应大小限制
{
"runtime": {
"host": {
"max-response-size-mb": 100
}
}
}默认 158 MB。包含大文本或 JSON 列的表建议降低此值，防止单次查询消耗过多内存。
常见错误
实体名重复
多个配置文件中出现同名实体会导致启动失败。在多文件管理的场景下特别注意实体名全局唯一。
视图缺少主键
视图没有物理主键，需要在 fields 中指定 primary-key: true，否则按主键查询会退化为列表查询返回空数组。
权限未配置
忘记配置 permissions 的实体拒绝所有访问。如果 API 返回 403，先检查权限配置。
连接字符串格式错误
不同数据库的连接字符串格式有差异——User Id（SQL Server）vs User ID（PostgreSQL）、端口分隔符（逗号 vs 冒号）等细节容易写错。
request-body-strict 导致创建失败
默认 request-body-strict: true 下，请求体中出现数据库不存在的字段会返回 400。如果使用通用 DTO 包含额外字段，需要将其设为 false。
生产环境健康检查返回 403
生产模式下 health.roles 为必需配置。如果省略，健康检查端点会返回 403。配置 roles: ["anonymous"] 可允许匿名访问。