自动生成 REST API

数据墙DBW 会根据实体配置，自动为每个公开的数据库对象生成 RESTful 端点。你不需要编写路由、控制器或数据访问代码——定义好实体和权限后，服务启动即可调用。

端点结构

每个实体会自动获得以下 REST 端点：

端点	方法	用途
/api/{entity}	GET	查询记录列表
/api/{entity}/{pk}/{value}	GET	按主键查询单条记录
/api/{entity}	POST	创建新记录
/api/{entity}/{pk}/{value}	PUT	替换或创建记录
/api/{entity}/{pk}/{value}	PATCH	更新指定字段
/api/{entity}/{pk}/{value}	DELETE	按主键删除记录

端点路径和工作方式完全由配置决定，无需编写任何后台代码。

查询能力

REST API 内置了常见的数据查询能力：

参数	用途	示例
$select	选择返回的字段	?$select=id,title,price
$filter	按条件筛选	?$filter=year ge 1970
$orderby	定义排序规则	?$orderby=year desc,title asc
$first	限制每页记录数	?$first=20
$after	分页游标翻页	?$after={token}

筛选支持 eq、ne、gt、ge、lt、le 等比较运算符，以及 and、or 逻辑组合。排序支持 asc 和 desc 方向。

数据修改

REST API 支持完整的 CRUD 操作：

• 创建：发送 POST 请求，请求体包含 JSON 格式的字段值。
• 更新：使用 PATCH 部分更新或 PUT 完整替换。
• 删除：按主键发送 DELETE 请求。

所有修改操作都受到实体权限配置的约束。只有被授予了相应 create、update 或 delete 权限的角色才能执行这些操作。

分页机制

默认情况下，每次查询最多返回 100 条记录（可通过 runtime.pagination.default-page-size 调整）。响应中会包含 nextLink 字段，指向下一页的 URL。客户端无需理解分页逻辑，只需跟随 nextLink 即可遍历全部结果。

字段级别控制

你可以为每个实体配置字段别名和主键指定：

• 使用 fields[].alias 将数据库列名映射为面向 API 的字段名。
• 使用 fields[].primary-key 明确标记主键字段。
• 通过权限配置中的 fields.include 和 fields.exclude 按角色控制可见字段。

这让 API 契约与数据库内部实现保持解耦，数据库结构调整不影响 API 消费者。

子目录路径

实体 REST 路径支持正斜杠，可以创建层次化 URL：

{
  "entities": {
    "ShoppingCartItem": {
      "rest": {
        "path": "shopping-cart/item"
      }
    }
  }
}

生成端点：GET /api/shopping-cart/item

响应格式

所有 REST 响应统一为以下 JSON 结构：

{
  "value": [
    { "id": 1, "title": "示例数据" }
  ],
  "nextLink": "https://host/api/book?$after=..."
}

无论查询结果是一行还是多行，响应结构保持一致，方便客户端统一解析。

与 OpenAPI 的集成

数据墙DBW 可自动生成 OpenAPI 规范文档，让 API 消费者快速了解所有可用端点、参数和响应格式。开发者可以直接导入 Swagger UI 或其他 API 工具，无需手工维护接口文档。

下一步

• 查看使用 REST API 了解各语言客户端调用示例。
• 了解配置管理 掌握实体和权限的配置方法。