HTTP If-Match 参考

If-Match HTTP 请求头控制数据墙DBW 的 PUT 和 PATCH 操作是执行 upsert（不存在则插入）还是仅更新（不存在则报错）。默认行为是 upsert。

默认行为（无 If-Match）

不携带 If-Match 头时，PUT 和 PATCH 都是 upsert 操作：

方法	记录存在	记录不存在
PUT	替换整条记录 → 200 OK	插入新记录 → 201 Created
PATCH	更新指定字段 → 200 OK	插入新记录 → 201 Created

If-Match 行为

头值	行为
If-Match: *	仅更新——记录存在则更新，不存在返回 404 Not Found
If-Match: <任意其他值>	拒绝 → 400 Bad Request（错误信息：Etags not supported, use '*'）
缺失	默认 upsert 行为

IMPORTANT

数据墙DBW 不支持逐记录 ETag 或版本匹配。* 仅断言"记录必须存在"。并发令牌不被评估。

适用协议

协议	支持
REST	✓
GraphQL	✗
MCP	✗

PUT 场景

无 If-Match + 记录存在 → 更新

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

{ "title": "更新后的书名", "publisher_id": 7 }

HTTP/1.1 200 OK
{ "id": 1, "title": "更新后的书名", "publisher_id": 7 }

无 If-Match + 记录不存在 → 插入

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

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

HTTP/1.1 201 Created
Location: id/500
{ "id": 500, "title": "新插入的书", "publisher_id": 7 }

If-Match: * + 记录存在 → 更新

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

{ "title": "更新后的书名", "publisher_id": 7 }

HTTP/1.1 200 OK
{ "id": 1, "title": "更新后的书名", "publisher_id": 7 }

If-Match: * + 记录不存在 → 拒绝

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

{ "title": "尝试更新" }

HTTP/1.1 404 Not Found
{ "error": "No Update could be performed, record not found" }

非法 If-Match 值 → 拒绝

PUT /api/Books/id/1
If-Match: "abc123"
Content-Type: application/json

{ "title": "书名" }

HTTP/1.1 400 Bad Request
{ "error": "Etags not supported, use '*'" }

PATCH 场景

PATCH 与 PUT 的行为完全一致，只是请求体只需包含要更新的字段：

PATCH /api/Books/id/1
If-Match: *
Content-Type: application/json

{ "title": "只更新书名" }

HTTP/1.1 200 OK

PUT 的特别注意事项

IMPORTANT

PUT 执行完整替换，即使携带 If-Match: *，请求体仍必须包含所有非空列。省略必填列会导致 400 Bad Request 数据库错误。如果只想发送字段子集，请使用 PATCH 而非 PUT。

DELETE 与 If-Match

If-Match: * 对 DELETE 操作无实际意义——删除不存在的记录本身不会报错。当前 DELETE 操作的行为不受 If-Match 头影响。

场景速查

场景	方法	If-Match	存在	不存在的行
Upsert 替换	PUT	无	200 OK	201 Created
仅更新	PUT	*	200 OK	404
Upsert 部分更新	PATCH	无	200 OK	201 Created
仅更新	PATCH	*	200 OK	404
删除	DELETE	—	204	204

下一步

• REST 端点 — 完整的端点结构和 HTTP 方法参考。
• HTTP Location — 创建操作的位置响应头。