2.2. 错误处理 (Error Handling)

2.2. 错误处理 (Error Handling)

已知有若干条件可能导致 PATCH 请求失败.

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

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

无法处理的请求: 当服务器理解补丁文档, 且补丁文档的语法看起来有效, 但服务器无法处理该请求时, 可使用 422 (Unprocessable Entity) 响应 ([RFC4918] 第 11.2 节) 来表示. 这可能包括试图以会导致资源无效的方式修改资源; 例如, 对一个格式良好的 XML 文档进行会使其不再格式良好的修改. 也可能存在更具体的错误, 例如上文提到的 "Conflicting State". 在这类情况下, 服务器可以在响应正文中包含错误信息, 以便用户判断补丁请求出了什么问题.

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

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

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

并发修改: 如果所用补丁格式要求客户端基于底层基础文档工作, 同时使用 PATCH 修改资源的请求可能产生不可预测的结果. 因此, 如果并发更新造成冲突, PATCH 请求可能会失败. 所有这类并发修改风险都适用于多个参与方更改同一资源的任何交互. PATCH 方法并未引入任何独有风险, 但值得在本节中特别指出.

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