REST API通过查询参数查询资源不存在时应返回什么响应码？

首先纠正一个常见认知误区：

很多人误以为404仅代表接口端点不存在，实际上HTTP 404的标准语义是请求的资源未找到，和接口端点本身是否存在没有必然关系。

以下是不同场景下的可行方案，按优先级排序：

• 方案1：返回404 Not Found
  如果你的接口语义明确是「获取匹配参数的唯一用户资源」，返回404完全合理。你请求的资源本质是「姓名为John Smith的用户」，该资源不存在，返回404完全符合HTTP语义，不存在逻辑矛盾。
• 方案2：返回带空结果的200 OK
  如果你担心部分客户端会默认拦截4xx响应导致业务逻辑无法正常处理，这是业界最常用的兼容方案，分两种实现：
  • 如果接口原本设计为返回集合，直接返回空数组即可：[]，由调用方判断数组长度取值
  • 如果接口设计为直接返回单对象，返回null或者带业务状态的封装结构即可，示例：

    {
      "code": 0,
      "msg": "查询成功",
      "data": null
    }
    

• 绝对不要用400 Bad Request
  400的语义是「客户端请求错误」，仅适用于参数格式非法、缺失必填参数等请求本身有问题的场景。你的请求参数完全合法，只是没有匹配的资源，用400属于语义完全错配，会给调用方造成严重误解。

补充设计建议：如果姓名组合是业务上的唯一键，更符合REST规范的做法是将唯一标识放到路径参数中，比如/users/name:John,Sparrow，但如果现有设计已经定型，按上面的方案选择即可。

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