校验配置文件

dab validate 是数据墙DBW 的配置诊断工具。它在不启动服务的情况下，逐步检查配置文件的正确性和完整性。每当配置出现问题或变更后，应首先运行此命令。

基本用法

dab validate

无参数时默认查找当前目录的 dab-config.json。

# 指定配置文件
dab validate --config ./configs/dab-config.prod.json

# 环境专用配置
DAB_ENVIRONMENT=Production dab validate

退出码

退出码	含义
0	所有阶段通过，配置有效
非零	至少一个阶段失败

五阶段诊断流程

验证按顺序执行。每个阶段失败后后续阶段被跳过——应逐个修复。

阶段 1：Schema 语法检查

检查配置 JSON 是否符合 Schema 定义。

可诊断的问题：

• JSON 语法错误（多余的逗号、不匹配的引号）。
• 属性名拼写错误（"conn-string" → "connection-string"）。
• 枚举值非法（"database-type": "mydb" → 改为 mssql 等）。
• 结构错误（"entities" 写成数组而非对象）。

修复后重新运行： dab validate

阶段 2：配置属性一致性

检查配置项之间的逻辑一致性。

可诊断的问题：

• 所有终结点都关闭（REST、GraphQL、MCP 都禁用）。
• JWT issuer 和 audience 不成对——设置了其中一个必须设置另一个。
• REST/GraphQL 路径不以 / 开头。
• 废弃的 *.disabled 属性（仅警告，不导致失败）。

阶段 3：权限配置

检查每个实体的权限定义。

可诊断的问题：

• 空动作列表 "actions": []。
• 非法动作名（如 "drop"）。
• 存储过程配置了 CRUD 动作——应使用 execute 或 *。
• 通配符 * 和显式动作混用在同一集合中。

阶段 4：数据库连接

实际测试数据库连接。

可诊断的问题：

• 连接超时——网络不通或防火墙阻止。
• 登录失败——用户名或密码错误。
• 数据库不存在——连接字符串中指定的数据库未被创建。

NOTE

此阶段需要实际的数据库连接。如果数据库暂时不可用（如 CI 环境），此阶段会失败但不影响对前三个阶段语法和结构问题的修复。

阶段 5：实体元数据

验证实体定义与实际数据库对象的一致性。

可诊断的问题：

• 数据源对象（表、视图、存储过程）不存在。
• 视图缺少主键——需添加 source.key-fields 或 fields[].primary-key。
• 字段引用错误——include/exclude 中的字段名不存在。
• 关系目标实体不存在。
• 多对多关系缺少 linking.object。
• 策略中的 @item.xxx 字段无效。
• 缓存 TTL 为负数。

CI/CD 集成

基本 CI 检查

dab validate --config ./dab-config.json || { echo "Config invalid"; exit 1; }

多环境验证

for env in Development Staging Production; do
  echo "Validating $env..."
  DAB_ENVIRONMENT=$env dab validate || exit 1
done

GitHub Actions 示例

- name: Validate DAB config
  run: |
    dotnet tool install --global Microsoft.DataApiBuilder
    dab validate --config ./dab-config.json

诊断工作流

推荐的诊断修复流程：

1. 运行 dab validate
2. 读取失败阶段和错误信息
3. 修复该阶段报告的第一个错误
4. 重新运行 dab validate
5. 重复步骤 2-4 直到退出码为 0
6. 配置通过所有阶段——可以安全启动服务

常见修复速查

错误信息关键字	修复方向
missing required key-fields	为视图实体添加主键
Invalid database type	改为 mssql、postgresql、mysql
empty actions	在 permissions 中提供至少一个操作
issuer not set	同时配置 jwt.issuer 和 jwt.audience
relationship target not found	确认 target.entity 的名称已定义
negative cache ttl	将 TTL 改为非负整数

下一步

• 查看日志 — 运行时错误日志分析。
• 检查健康状态 — /health 端点诊断。
• 排查权限问题 — 诊断 401/403。