开发客户查询API应选择通用接口方案还是多特定接口方案？

两种设计没有绝对的优劣，具体选型取决于你的业务场景和接口使用方： #

动态过滤接口（你当前的实现）的适用情况

优势

• 灵活性极强，后续如果新增客户过滤维度（比如手机号、注册时间），不需要新增接口，只需要在动态SQL里加对应判断即可，迭代成本极低
• 避免接口冗余，不需要为不同参数组合重复写相似的业务逻辑和SQL

劣势

• 安全风险更高：如果权限控制不到位，未授权用户可以不传任何参数拉取全量客户数据，不仅容易造成数据泄露，还有可能触发全表扫描拖垮数据库
• 接口契约不清晰：调用方很难直观知道哪些参数可以组合使用，容易出现无意义的参数请求（比如同时传唯一键id和name，其他参数实际不生效），排查问题成本更高
• 性能优化难度大：不同参数组合需要的索引完全不同，多条件组合下很容易出现慢查询，也很难为不同场景单独做缓存优化

适用场景

适合内部可信系统调用、业务对过滤灵活性要求高的场景，使用时必须做好三层限制：

• 强制分页：哪怕不传任何过滤参数，单次请求最多返回限定条数（比如100条）的客户数据
• 参数校验：如果传了唯一键id，直接忽略其他过滤参数，避免无效查询
• 权限兜底：每次查询都校验当前用户可访问的客户范围，禁止返回超出权限的数据

拆分独立REST接口的适用情况

优势

• 接口职责单一，契约清晰，调用方不需要理解内部逻辑，看接口定义就知道传参规则和返回结果，使用成本极低
• 安全和性能可控：按id查询的接口可以单独加缓存、做权限校验；按name/surname查询的接口可以单独做索引优化，甚至对接全文检索服务
• 符合RESTful设计规范，可维护性和可读性更高

劣势

如果后续新增过滤组合需要单独新增接口，容易出现接口膨胀，重复的CRUD逻辑会增多，迭代成本更高

适用场景

适合对外公开API、业务查询场景固定的情况。如果就是你列的4种查询需求，甚至不需要拆成4个独立接口：

• 按id查询的走GET /customers/{id}，返回单个客户对象
• 其他多条件查询走GET /customers，后台只允许接收name、surname两个查询参数，自动按传入的参数组合做过滤即可，完全可以覆盖你列的剩下3种场景

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