常见问题

产品概述

数据墙DBW 是什么？

数据墙DBW 是一个配置驱动的数据 API 生成引擎。它连接到你的数据库，将表、视图和存储过程自动发布为 REST API、GraphQL API 和 MCP 工具。你通过一个 JSON 配置文件声明数据源、实体和权限，引擎在运行时根据配置生成接口，不需要编写后端代码。

数据墙DBW 支持哪些数据库？

支持 SQL Server（2016+）、PostgreSQL（11+）和 MySQL（8+）。不同数据库在功能支持上存在差异——SQL Server 支持最完整，包括存储过程、聚合查询和自动实体发现；PostgreSQL 和 MySQL 在基础的 REST 和 GraphQL CRUD 操作上表现一致。

数据墙DBW 是免费的吗？

数据墙DBW 是一个开源引擎，可以免费使用。它可以运行在本地、容器或自托管环境中，没有付费层级或功能限制。

数据墙DBW 可以替代我现有的后端吗？

数据墙DBW 不是替代所有后端服务的通用框架。它擅长将标准化的数据 CRUD 操作配置化，适合承担数据库和应用之间的数据访问网关角色。复杂业务流程、跨系统编排、异步任务等仍然需要独立的业务服务。

数据墙DBW 修改我的数据库结构吗？

不会。数据墙DBW 只读取数据库中的表、视图和存储过程，不会创建、修改或删除任何数据库对象。它是纯运行时的数据访问层。

安装与配置

如何安装数据墙DBW？

通过 .NET CLI 安装为全局工具：

dotnet tool install --global Microsoft.DataApiBuilder

需要 .NET 8 SDK 或更高版本作为前提条件。

配置文件必须手写吗？

不一定。你可以通过 dab init 创建基础配置，通过 dab add 添加实体，通过 dab configure 和 dab update 修改设置。所有 JSON 配置也可以通过 CLI 命令生成。当然，直接编辑 JSON 文件也是完全支持的。

连接字符串中的密码如何处理？

使用 @env('VAR_NAME') 语法引用环境变量：

{
  "connection-string": "@env('SQL_CONNECTION_STRING')"
}

启动前在系统环境变量、.env 文件或容器环境变量中设置实际值。不要将明文密码写入配置文件。

如何为不同环境（开发/测试/生产）管理配置？

三种方式结合使用：

1. 环境差异文件：dab-config.json 存共享配置，dab-config.Production.json 存生产特有字段。通过 DAB_ENVIRONMENT=Production dab start 切换。
2. 环境变量：连接字符串等敏感信息通过 @env() 引用，不同环境使用不同的环境变量值。
3. 多配置文件：通过 data-source-files 引用多个配置文件，按业务域或环境拆分。

修改配置后需要重启吗？

需要。数据墙DBW 在启动时一次性加载配置，修改 dab-config.json 后需重启服务（dab start）才能使变更生效。唯一的例外是日志级别——支持运行时热重载。

REST API

REST API 的默认地址是什么？

http://localhost:5000/api/{entity}。其中 /api 是默认前缀（可通过 runtime.rest.path 修改），{entity} 是你在配置中定义的实体名。

如何实现分页？

REST 使用 $first 和 $after 实现游标分页：

# 每页 5 条
curl "http://localhost:5000/api/Book?\$first=5"

# 下一页（使用响应中 nextLink 包含的 $after 值）
curl "http://localhost:5000/api/Book?\$first=5&\$after=eyJpZCI6NX0="

不支持 ?page=1&size=10 这样的页码式分页。

为什么我的 POST/PUT 请求返回 400？

最常见的原因：

• request-body-strict 默认为 true，请求体中出现了数据库不存在的字段。
• PUT 请求没有包含所有非空列（PUT 是完整替换）。
• 请求的字段名使用了数据库列名而非 API 别名。

如何查看完整的 API 文档？

开发模式（host.mode: development）下访问 http://localhost:5000/swagger 即可浏览 Swagger UI。生产模式下 Swagger 被禁用。无论哪种模式都可以访问 /api/openapi 获取 OpenAPI JSON 规范文档。

为什么按主键查询视图返回空数组？

视图没有物理主键。你必须在实体配置中手动指定 key-fields 或 fields[].primary-key，否则引擎无法确定如何按主键检索视图中的行。

GraphQL API

GraphQL 端点的地址是什么？

POST http://localhost:5000/graphql。所有 GraphQL 操作——包括查询和变更——都通过 POST 方法发送到同一端点。

如何浏览 GraphQL 架构？

默认情况下，GraphQL 内省（Introspection）是启用的。可以使用任何支持 GraphQL 的客户端（如 Postman、Insomnia、Apollo Studio）连接到 /graphql 自动发现可用的查询、变更和类型。生产环境建议关闭内省（allow-introspection: false）。

为什么我的 GraphQL 变更操作失败？

常见原因：

• 数据库连接字符串没有启用 MultipleActiveResultSets=True（SQL Server）。
• 连接池配置了 Pooling=False。
• 实体没有配置对应的操作权限（create、update、delete）。
• 存储过程在 GraphQL 中需要以 execute 为前缀调用。

聚合查询在 PostgreSQL 上能用吗？

不能。GraphQL 聚合查询（count、sum、avg、min、max、groupBy）仅 SQL Server 支持。

多重变更需要事务支持吗？

多重变更不支持数据库事务。多个操作按顺序依次执行，某个操作失败时已执行的操作不会回滚。如果需要事务保证，将逻辑封装在存储过程中，通过存储过程实体调用。

安全与权限

默认的权限是什么？

没有默认权限。未配置 permissions 的实体拒绝所有访问。你必须显式为每个实体配置允许的角色和操作。这是数据墙DBW 的安全设计原则——默认拒绝。

如何实现"只有创建者能修改自己的数据"？

通过数据库策略（行级过滤）实现：

{
  "action": "update",
  "policy": {
    "database": "@item.ownerId eq @claims.userId"
  }
}

这会限制用户只能更新 ownerId 等于自己 userId 的数据库行。

JWT 令牌中必须包含哪些声明？

数据墙DBW 固定从 roles 声明中提取角色，此声明名不可配置。如果你的身份提供程序使用了 groups、permissions 等其他声明名，需要配置提供程序额外输出 roles 声明。

匿名访问安全吗？

取决于部署架构。如果数据墙DBW 部署在可信网关（Nginx、API Gateway）之后且网关已完成用户认证，匿名模式（Unauthenticated）是安全的。如果数据墙DBW 直接暴露在公网上，必须配置 JWT 验证（Custom）。

Simulator 能用在生产环境吗？

绝对不能。Simulator 提供程序会完全跳过身份验证，且强制要求 host.mode: development。在 production 模式下引擎会直接拒绝启动。

如何防止某个角色的用户看到敏感字段？

通过 fields.exclude 配置：

{
  "action": "read",
  "fields": {
    "include": ["*"],
    "exclude": ["salary", "password_hash"]
  }
}

被排除的字段在 REST、GraphQL 和 MCP 三种协议中均不可访问。

缓存

缓存是自动启用的吗？

不是。缓存需要在两个层级显式启用：全局 runtime.cache.enabled: true 和每个实体 cache.enabled: true。两层开关都打开后缓存才生效。

缓存支持 GraphQL 吗？

不支持。一级和二级缓存仅适用于 REST 端点。GraphQL 查询和 MCP 工具调用不使用缓存。

为什么我的缓存写入后立即失效了？

因为实体发生了写操作（POST/PUT/PATCH/DELETE）。数据墙DBW 在写操作后清除该实体的全部缓存条目——无法做精确的缓存失效。

L1 和 L2 缓存有什么区别？

• L1：进程内内存缓存，速度最快（< 1ms），但仅限单实例。重启后丢失。
• L2：Redis 分布式缓存，跨实例共享，重启后可恢复。需要单独部署 Redis 实例。

启用会话上下文后缓存为什么不工作？

启用 set-session-context 后，不同用户的同一查询返回不同结果（因为数据库层面的安全策略根据用户上下文过滤）。数据墙DBW 为保证数据安全，会自动禁用该数据源的缓存。

MCP

MCP 是什么？我需要它吗？

MCP（Model Context Protocol）是让 AI 代理安全访问数据库的标准协议。如果你的应用场景是传统的 Web API 或移动端调用，不需要 MCP。如果你希望 AI 代理（Copilot、Claude）能查询和操作数据库，就需要启用 MCP。

MCP 代理能执行任意 SQL 吗？

不能。MCP 代理通过七个固定的 DML 工具与数据库交互，所有操作都经过实体模型、权限检查和查询构造器。代理不能发送原始 SQL 语句，也不能执行 DDL 操作（建表、修改结构）。

为什么 AI 代理看不到我的表？

检查以下几点：

• runtime.mcp.enabled 是否为 true。
• 实体级 mcp.dml-tools 是否被设为 false。
• 全局 dml-tools 中对应的工具是否被关闭。
• 当前角色在该实体上是否有对应的操作权限。

MCP 的 Stdio 和 HTTP 模式如何选择？

• Stdio：本地开发用。客户端以子进程方式启动数据墙DBW，通过标准输入/输出通信，不开放网络端口。VS Code 和 Claude Desktop 推荐使用。
• HTTP：远程服务用。多客户端共享同一端点，通过网络访问。

部署与运维

数据墙DBW 能在 Kubernetes 中运行吗？

可以。数据墙DBW 是一个无状态服务，天然适合容器化部署。通过 ConfigMap 挂载配置、Secret 注入连接字符串、/health 端点配置存活和就绪探测、HPA 实现自动扩缩。

如何查看日志？

日志输出到标准输出（stdout），可以用 docker logs 或 kubectl logs 查看。也可以配置 runtime.telemetry.file 将日志写入文件。日志级别通过配置或启动参数 --LogLevel 调整。

如何升级数据墙DBW？

dotnet tool update --global Microsoft.DataApiBuilder

升级后重启服务即可。建议先在测试环境验证兼容性。

生产环境必须配置什么？

最低限度的生产配置清单：

• host.mode: "production"
• graphql.allow-introspection: false
• 连接字符串全部使用 @env()
• 身份验证切换为 Custom（JWT）或通过网关认证
• 所有实体都有明确的 permissions 配置
• 日志级别设为 Warning 或 Error

数据墙DBW 支持水平扩展吗？

支持。数据墙DBW 是无状态服务，多个实例可以并行运行——在前面放置负载均衡器，所有实例共享同一份配置文件。如果需要跨实例共享缓存，启用 Redis 二级缓存。

下一步

• 安全总览 — 安全模型的全局视角。
• 配置管理 — 配置文件结构详解。