REST API设计咨询：按名称查询用户未找到时的返回值及设计合理性

嘿，咱们来一步步拆解你的API设计问题，帮你理清思路～

这个问题核心在于区分请求的语义：

• 如果你用的是api/users/john这种路径参数形式：它的语义是「获取名为John的单个特定用户」，相当于你明确请求了一个具体的资源。如果这个用户不存在，返回404 Not Found是合理的，因为目标资源不存在。
• 如果你用的是api/users?name=John这种查询参数形式：它的语义是「查询所有名称匹配John的用户列表」，本质是对用户集合的过滤操作。这种情况下，即使没有匹配结果，查询操作本身是成功的，只是结果集为空，所以应该返回200 OK加上空数组[]。

你的设计有可取之处，但也有几个需要注意的细节，来让它更符合RESTful API的最佳实践：

• 路径参数的唯一性问题：api/users/john这种设计默认假设「用户名是唯一标识」，但如果你的业务场景中用户名可能重复，这个路径就会有歧义（比如多个叫John的用户，返回哪一个？）。这种情况下，建议只保留api/users?name=John的查询方式，避免语义混淆。
• 接口语义的一致性：同一个api/users路径，同时承载了「集合资源」（返回所有用户、过滤用户）和「单个资源」（通过ID/名称获取单个用户）的语义，这本身是可以接受的，但要确保返回格式一致：比如api/users/1返回单个用户对象，api/users?id=1返回包含该用户的数组，两者格式不同的话，前端处理会更麻烦，最好在文档里明确说明差异，或者统一其中一种格式。
• 大小写与匹配规则的明确性：api/users/john和api/users?name=John涉及到名称的大小写匹配，你需要在API文档里明确说明匹配规则（比如是否大小写敏感、是否支持模糊匹配），避免调用方产生误解。
• 冗余接口的必要性：你提供了两种按ID查询的方式（api/users/1和api/users?id=1），以及两种按名称查询的方式。其实路径参数更适合获取单个唯一资源，查询参数更适合集合过滤，建议根据业务场景做取舍，比如保留api/users/{id}获取单个用户，api/users?name=xxx做名称过滤，减少冗余的接口形式，让API更简洁直观。

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