接口入参校验不是为了“写得规范”，而是为了把错误挡在业务层外面。未校验的参数一旦进入 service，后面每一层都要猜字段是否为空、枚举是否合法、时间范围是否合理，代码会越来越难维护。
DTO 先表达业务意图
请求模型不要直接复用数据库实体。DTO 应该表达接口需要的字段、字段含义和边界。新增、编辑、查询可以拆成不同请求对象，不必为了省类数把所有字段都塞进一个大对象。
字段注释要说明用途、单位和敏感性。比如时间字段是秒还是毫秒，时区按用户本地还是服务器时区；金额字段是分还是元；状态字段允许哪些枚举值。
注解校验覆盖基础边界
Spring Boot 项目可以用 Validation 注解处理非空、长度、数值范围、集合大小和格式。Controller 层加 @Valid 或 @Validated，让基础错误在进入业务层前统一返回。
复杂规则不要硬塞进注解。跨字段校验、业务状态校验、权限校验可以放在 service 前置逻辑里，但仍要有清晰错误码和错误信息。
错误返回要稳定
参数错误应该返回稳定结构，包括错误码、用户可读文案和必要字段提示。前端依赖的是契约，不是 Java 异常堆栈。不要把底层异常信息直接暴露给页面，也不要所有错误都返回“系统异常”。
对于批量接口，最好说明是全量失败、部分成功，还是逐条返回错误。这个边界不说清楚，后续补偿和重试会很麻烦。
测试覆盖关键边界
入参校验至少要覆盖必填缺失、非法枚举、越界数值、非法时间范围和权限不足。测试不一定多，但要覆盖最容易被前端或外部调用方传错的点。
好的接口校验会让业务代码更干净。Controller 负责接住请求，DTO 负责表达契约，校验负责拦住明显错误，service 才能专注真正的业务判断。
正文完
