REST API中自由文本搜索端点的格式设计最佳实践

你初步设想的/items/search/my+item形式并不符合通用的REST设计规范，核心问题是路径段的作用是定位资源层级/唯一资源标识，搜索关键词是资源集合的筛选条件，不属于资源定位的一部分；而且这种把参数堆在路径里的形式扩展性极差，后续要加分页、分类筛选、排序等能力时，路径会变得非常冗余混乱，还可能出现「某个条目ID刚好叫search导致路由冲突」的bug。

行业内成熟的设计方案按优先级排序如下：

• 优先复用现有资源集合端点，搜索条件全部放在查询参数中
  这是绝大多数公开API采用的标准方案，完全契合REST语义：/items本身就代表所有条目的资源集合，查询参数的作用就是对这个集合做筛选、裁剪、排序，和你现有的/items/34按ID查单个条目的逻辑完全不冲突。
  常见的参数约定：
  • 单字段模糊匹配：用带匹配语义的参数名，比如按名称模糊搜就用name_like或name_contains，示例：GET /items?name_like=my%20item
  • 多字段通用搜索：用通用搜索参数q或search，示例：GET /items?q=my%20item
    这种方案扩展性极强，后续要加其他筛选条件直接追加查询参数即可，比如GET /items?name_like=my%20item&category=electronics&page=1&page_size=20，不需要调整路由结构。
• 仅在特殊场景下单独设计搜索端点
  如果你要实现跨资源的全局搜索，或者搜索逻辑独立（比如走专门的搜索引擎、返回相关度评分、高亮片段等和普通条目列表结构不一致的结果），才需要单独开搜索端点，但注意关键词依然要放在查询参数里，不要塞到路径段中，正确格式示例：GET /search/items?q=my%20item
  这里的/search/items指代的是「条目搜索结果」这个独立的资源集合，依然符合REST用名词定位资源的要求。

额外提几个容易踩的坑：

• 路径里不要出现动词：search是动作不是资源，不应该出现在资源路径段中，HTTP方法本身已经表达了动作语义（GET对应获取资源）
• 不要用+在URL里编码空格：+只有在application/x-www-form-urlencoded格式的请求体中才代表空格，URL路径和查询参数里的空格标准编码是%20，跨网关、跨语言的兼容性更好
• 模糊匹配参数不要和精确匹配参数重名：比如不要直接用name参数传模糊搜索值，很容易让调用方误以为是精确匹配，最好显式加上_like/_contains后缀明确匹配规则

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