API设计中对用户传入参数执行校验的最佳实践位置是哪里？

核心结论 #

参数校验是多层级协同完成的工作，你提到的两种方案都需要配合使用，不存在非此即彼的选择，不同层级负责不同类型的校验职责，这个规则是和编程语言、技术栈无关的通用最佳实践。

1. Controller/路由层（方案A）适合做什么校验 #

这层是用户请求进入系统的第一道关口，适合放和接口约定强绑定的基础校验：

• 必填参数是否存在（比如示例中接口约定必须传id，就可以在这层判断id是否为空）
• 参数格式是否符合要求（比如id是否为数字、邮箱格式是否正确、字符串长度是否超出接口限制）
• 枚举类参数是否在允许的取值范围内

这么做的优势很明显：

• 快速失败：不符合基本要求的请求直接在最外层返回400错误，不会占用核心业务层的计算资源
• 错误定位清晰：接口层面的参数错误直接和请求关联，不用走到业务逻辑就能定位问题
• 避免重复校验：同一类接口的格式校验可以抽成装饰器/中间件统一处理，不用每个业务方法都写重复的格式判断

2. 业务核心层（方案B）适合做什么校验 #

这层是系统核心逻辑的承载方，它的调用方可能不止Controller（比如内部定时任务、其他微服务、同应用内的其他业务模块等），所以必须做两类校验：

• 防御性入参校验：不管上游调用方有没有做过校验，核心业务方法都要对关键入参做基础合法性判断（比如判断job_id非空），避免非法输入导致业务逻辑异常甚至数据污染
• 业务规则类校验：和具体业务逻辑绑定的校验必须放在这层，比如id对应的任务是否存在、当前请求用户是否有权限访问这个id对应的任务、任务是否处于允许查询的状态等，这类校验放到Controller层会导致逻辑泄露，其他调用方调用业务方法时会漏掉校验，引发业务错误。

优化方案：独立校验组件 #

如果校验逻辑比较复杂，可以把通用的校验逻辑抽成独立的Validator组件，通过注解、装饰器、配置文件等方式声明校验规则，不用在每层写重复的if判断，进一步降低代码重复率，提升可维护性。

通用分层校验原则（技术栈无关） #

• 越靠近外部输入的层，越偏向做协议、接口约定层面的格式、必填性校验，核心目标是过滤无效请求
• 越靠近核心业务的层，越偏向做业务规则校验、防御性入参校验，核心目标是保证核心逻辑的正确性和稳定性

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