HTTP Location 参考

Location 响应头告知客户端新创建资源的检索地址。数据墙DBW 在特定创建操作中返回此头，使客户端可以直接定位到刚创建的资源。

何时返回 Location

场景	状态码	Location 头
POST 创建新行（表实体）	201 Created	存在，包含主键路径
POST 执行返回新行的存储过程	201 Created	可推导主键时存在，无法推导时可能为空
PUT upsert 更新现有行	200 OK	不存在
PUT upsert 插入新行（无 If-Match）	201 Created	可能被省略——不要依赖
PATCH upsert 更新现有行	200 OK	不存在
PATCH upsert 插入新行（无 If-Match）	201 Created	可能被省略——不要依赖
PUT / PATCH 带 If-Match: * 且行缺失	404 Not Found	不存在

IMPORTANT

只有 POST 创建操作的 Location 头是可依赖的。PUT 和 PATCH 的 upsert 插入即使返回了 Location 也应视为不可靠，不应在客户端代码中依赖。

Location 路径格式

单主键

Location: /{rest-path}/{entity}/{pk-name}/{pk-value}

示例：

Location: /api/Books/id/123

复合主键

Location: /{rest-path}/{entity}/{pk1-name}/{pk1-value}/{pk2-name}/{pk2-value}

复合主键按实体定义中的顺序显示为有序段。

示例：

Location: /api/Inventory/categoryid/3/pieceid/1

字段别名

路径中的主键名使用 API 层字段名（fields[].alias），而非数据库原始列名。

示例

POST 创建单主键记录

POST /api/Books
Content-Type: application/json

{ "title": "新书", "publisher_id": 42 }

HTTP/1.1 201 Created
Location: /api/Books/id/123
Content-Type: application/json

{ "id": 123, "title": "新书", "publisher_id": 42 }

客户端可以用 Location 头的值直接访问新建资源：

curl http://localhost:5000/api/Books/id/123

POST 创建复合主键记录

POST /api/Inventory
Content-Type: application/json

{ "categoryid": 3, "pieceid": 1, "categoryName": "科幻" }

HTTP/1.1 201 Created
Location: /api/Inventory/categoryid/3/pieceid/1
Content-Type: application/json

{ "categoryid": 3, "pieceid": 1, "categoryName": "科幻" }

PUT 更新（无 Location）

PUT /api/Books/id/1
Content-Type: application/json

{ "title": "更新后的书名" }

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 1, "title": "更新后的书名" }

响应中无 Location 头——客户端已经知道 URL。

PUT 插入新行（Location 不可依赖）

PUT /api/Books/id/500
Content-Type: application/json

{ "title": "插入的书名", "publisher_id": 7 }

HTTP/1.1 201 Created
Content-Type: application/json

{ "id": 500, "title": "插入的书名", "publisher_id": 7 }

Location 头可能被省略。如果存在，值为 /api/Books/id/500。

所有场景速查

场景	状态码	Location	可靠性
POST 创建	201	存在	可靠
POST 存储过程（可推导键）	201	存在	可靠
POST 存储过程（不可推导键）	201	可能为空	不可靠
PUT 更新现有行	200	无	—
PUT 插入新行	201	可能被省略	不可靠
PATCH 更新现有行	200	无	—
PATCH 插入新行	201	可能被省略	不可靠
PUT/PATCH + If-Match: * 行缺失	404	无	—

下一步

• REST 端点 — 完整的端点结构和 HTTP 方法参考。
• HTTP If-Match — 控制更新行为的条件头。