2.2. 错误处理 (Error Handling)

2.2. 错误处理 (Error Handling)

存在几种已知的 PATCH 请求可能失败的情况.

格式错误的补丁文档 (Malformed patch document): 当服务器确定客户端提供的补丁文档格式不正确时, 它应该 (SHOULD) 返回 400 (Bad Request) 响应. 格式错误的定义取决于所选择的补丁文档.

不支持的补丁文档 (Unsupported patch document): 当客户端发送服务器不支持的补丁文档格式用于 Request-URI 标识的资源时, 可以使用 415 (Unsupported Media Type) 响应来指定. 此类响应应该 (SHOULD) 包含一个 Accept-Patch 响应头, 如第 3.1 节所述, 以通知客户端支持哪些补丁文档媒体类型.

无法处理的请求 (Unprocessable request): 当服务器理解补丁文档并且补丁文档的语法看起来有效, 但服务器无法处理请求时, 可以使用 422 (Unprocessable Entity) 响应 ([RFC4918], 第 11.2 节) 来指定. 这可能包括试图以会导致资源变为无效的方式修改资源; 例如, 对格式良好的 XML 文档进行修改, 使其不再格式良好. 也可能存在如上所述的更具体的错误, 如 "冲突状态 (Conflicting State)". 在这种情况下, 服务器可以 (MAY) 在响应主体中包含错误信息, 以便用户可以确定补丁请求出了什么问题.

资源未找到 (Resource not found): 如果客户端尝试应用补丁的资源不存在, 并且服务器不支持使用 PATCH 创建新资源, 则服务器返回 404 (Not Found) 状态码.

冲突状态 (Conflicting state): 如果请求格式正确并且服务器支持补丁文档中使用的媒体类型, 但服务器无法应用补丁, 因为资源的状态与补丁冲突或补丁将创建冲突 (例如, 尝试添加冲突字段的补丁, 或失败的条件请求), 服务器返回 409 (Conflict) 状态码. 服务器应该 (SHOULD) 在响应主体中包含足够的信息, 以便客户端识别冲突的来源.

冲突修改 (Conflicting modification): 如果请求格式正确并且服务器支持媒体类型, 但由于资源已从预期状态更改 (例如, 条件请求失败, 强 ETag 与当前资源不匹配), 因此无法将补丁应用于资源, 服务器返回 412 (Precondition Failed) 状态码.

并发修改 (Concurrent modification): 如果正在使用的补丁格式要求客户端从基础文档 (base document) 工作, 则使用 PATCH 修改资源的同时请求可能会产生不可预测的结果. 因此, 如果并发更新导致冲突, PATCH 请求可能会失败. 所有此类并发修改风险都适用于多方对同一资源进行更改的任何交互. PATCH 方法不会引入任何独特的风险, 但值得在本节中强调.

注意: 对于所有响应, 服务器可以在响应主体中包含错误信息, 以便客户端可以确定出了什么问题或下一步该做什么.