REST API查询无匹配结果时的响应状态码与返回数据选型

针对你提到的/people?name=joe接口（每个名称对应唯一对象）无匹配结果时的状态码选择，核心要结合接口的语义定位来判断：

两种场景的区分逻辑 #

• 路径参数/people/joe返回404的合理性：这个接口的语义是直接定位一个特定的、已命名的资源，当资源不存在时，返回404（Not Found）是HTTP标准约定，客户端能清晰理解“请求的目标资源不存在”。
• 查询参数接口的语义差异：/people?name=joe的语义需要明确是「资源定位」还是「搜索查询」：

情况1：接口语义是“通过名称定位唯一用户” #

如果这个接口的设计目的就是替代路径参数，专门用来获取某个名称对应的唯一用户（业务上名称唯一是强约束），那它的本质和/people/joe一致，只是参数传递方式不同。这种情况下返回404是合理的：

• 客户端的预期是获取一个具体的用户资源，而非执行一次搜索
• 404能准确传递“目标资源不存在”的语义，避免客户端把无结果当成正常的搜索成功

此时响应体可以附带简洁的错误说明，比如：

{"message": "名称为joe的用户不存在"}

情况2：接口语义是“执行名称匹配的搜索” #

如果接口的设计是通用搜索接口（哪怕当前业务上名称唯一，但未来可能支持模糊匹配、多条件组合等扩展），那返回**200 + 空对象{}**更合适：

• 搜索操作本身成功完成，无匹配结果是预期的成功场景，不属于错误
• 返回200能让客户端统一处理“搜索成功”的逻辑，空对象明确表示无匹配结果

也可以返回更清晰的结构，方便客户端解析：

{"user": null}

总结建议 #

如果你的业务中“名称唯一”是长期强约束，且这个接口就是用来精准获取单个用户的，优先选404；如果接口定位是搜索类（哪怕当前是精准匹配），优先选200+空对象。

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