PUT请求路径参数ID与请求体ID不一致时应返回何种HTTP状态码

结论 #

应当返回 400 Bad Request 状态码。

判定依据 #

PUT 方法的官方语义是对请求路径对应的目标资源进行完整覆盖更新，接口路径/resources/{id}中的{id}就是本次要操作的资源的唯一合法标识，出现路径ID和请求体ID不匹配的情况，属于客户端请求本身存在逻辑错误，符合400状态码的适用范围。

你给出的示例请求：

curl -X PUT 'localhost:8080/resources/test2' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "test",
    "name": "my_resource"
}'

路径中的目标资源ID为test2，请求体中的资源ID为test，二者存在明显冲突，服务端无法正常处理该请求，直接返回400即可。

其他常见状态码排除原因 #

• 不适用404：404用于表示请求路径对应的资源不存在，本场景的问题是请求本身参数冲突，和test2资源是否存在没有关联
• 不适用409 Conflict：409用于表示请求与资源当前的状态存在冲突（例如更新时版本校验不通过、资源被占用等），不属于请求自身的参数错误
• 不适用403 Forbidden：403用于表示客户端没有操作权限，与本场景的问题无关

最佳实践 #

返回400状态码时，可在响应体中补充明确的错误提示，例如：

{
    "code": 400,
    "message": "请求路径中的资源ID与请求体携带的资源ID不匹配，请检查参数后重试"
}

方便客户端快速定位问题。

内容的提问来源于stack exchange，提问作者spyroukostas