转自：豆包

建议分成两个独立接口，而非合并为一个。这种设计更符合接口的单一职责原则，能让接口语义更清晰、扩展性更强，同时避免后续维护中的逻辑冗余。

1. 入参 / 出参结构不同

   • 单个订单查询：入参通常是 orderId（单个字符串 / 数字），出参是单个订单对象（OrderResponse）。
   • 批量查询：入参是 orderIds（集合类型，如 List<string>），出参是订单对象列表（List<OrderResponse>）或带总数的分页结构，还可能需要处理 “部分订单不存在” 的特殊逻辑（如返回空对象 / 标记状态）。 若合并为一个接口，需用 object 类型接收入参（兼容单个 / 集合），再通过逻辑判断分支处理，会导致入参校验、返回值解析变得复杂。

2. 性能与扩展性不同

   • 批量查询（50 个）可能需要更优的数据库查询逻辑（如 where in 批量查询），或增加超时时间、限流策略（避免批量请求占用过多资源）。
   • 单个查询通常是简单的主键查询，性能更稳定，无需额外配置。 分开设计可针对两种场景单独优化，例如给批量接口添加 “最大查询数量限制”（防止传入 1000 个 ID 导致性能问题），而单个接口无需此逻辑。

3. 语义与维护成本不同

   • 单个接口（如 /api/orders/{orderId}）和批量接口（如 /api/orders/batch）语义明确，调用方（前端 / 其他服务）能直接通过接口名判断用途，无需查看文档确认 “入参到底该传单个还是集合”。
   • 合并接口会导致逻辑冗余（如判断入参是单个还是集合、处理两种返回格式），后续修改时（如批量查询需要加分页），容易影响到单个查询的正常逻辑。

• 推荐方案：拆分两个接口，语义清晰、易于维护和优化。
• 避免方案：合并为一个接口，会导致入参出参混乱、逻辑冗余，后续扩展风险高。

如果担心调用方需要调用两次接口，可在文档中明确两个接口的用途和差异，或提供前端封装方法（按需调用单个 / 批量接口），但接口层仍需保持职责单一。