企业级入参校验是贯穿接入层、协议层、业务域的四层系统性防线：传输层校验请求头与大小，协议层做json schema验证，语义层校验业务规则，上下文层依赖外部状态校验；dto需清晰隔离、嵌套加@valid；错误反馈结构化、可定位；工程上通过starter、ci扫描和文档同步固化规范。
企业级入参校验不是“加几个注解就完事”，而是贯穿接入层、协议层、业务域的系统性防线。核心目标是：早拦截、准反馈、可追溯、易维护。
分层校验，各守其责
避免把所有校验逻辑堆在 Service 层或 Controller 里。推荐四层结构：
- 传输层校验：检查 HTTP 方法、Content-Type、请求头（如 Token 是否存在）、请求大小（如限制 ≤10MB），在 Filter 或 WebMvcConfigurer 中统一处理
- 协议层校验：对 JSON 请求体做 Schema 级验证，用 JSON Schema + Ajv 或 Java 的 @Valid + @RequestBody 配合 Hibernate Validator，确保字段类型、必填性、格式（如 UUID、邮箱、手机号正则）合法
- 语义层校验：校验业务含义，例如“开始时间不能晚于结束时间”“优惠券面额必须为正整数”——这类规则适合用自定义 ConstraintValidator 实现，绑定到 DTO 字段或嵌套对象
- 上下文层校验：依赖外部状态的判断，如“用户 ID 是否真实存在”“订单是否属于当前租户”。这类校验应异步前置（如 Feign 调用缓存查证），不阻塞主流程；失败时返回明确错误码（如 40003：资源不存在），而非抛运行时异常
参数建模必须清晰、隔离、可复用
拒绝 Map
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 字段命名与前端一致，使用驼峰，禁止缩写（如用
userEmail，不用uEmail） - DTO 仅用于传输，不与 Entity、VO、BO 混用；不同接口即使字段相同，也应新建 DTO，避免耦合扩散
- 对可选字段显式标注
@Null或@NotBlank，对枚举字段用@Pattern或自定义@EnumValue注解约束取值范围 - 嵌套对象必须加
@Valid，集合字段用@Valid List<itemdto></itemdto>，确保深层结构也被校验
错误反馈要具体、结构化、可定位
不返回笼统的“参数错误”，而应提供机器可解析、前端可展示的明细信息：
- HTTP 状态码统一用
400 Bad Request，响应体结构固定：{"code": "VALIDATION_FAILED", "message": "请求参数校验失败", "details": [{"field": "email", "reason": "邮箱格式不正确"}, {"field": "age", "reason": "年龄必须在 1~120 之间"}]} - 错误 reason 使用中文短语，不带技术术语（不说“@Email constraint violated”，而说“邮箱格式不正确”）
- 对批量操作（如导入 Excel、批量创建），需支持“部分成功+明细错误列表”，便于运营排查
工具与规范必须落地到工程基建
靠人自觉无法保障长期一致性。需通过工程手段固化：
- 在 Maven/Gradle 中强制引入
spring-boot-starter-validation，并禁用未校验的@RequestBody Object写法（CI 阶段用 SonarQube 规则扫描） - 提供内部校验 Starter，封装常用注解（如
@TenantId、@SafeFileName）、全局异常处理器和标准错误响应模板 - 所有对外 API 文档（Swagger/OpenAPI）中的
schema必须与实际校验逻辑一致，建议用@Schema同步描述，避免文档与代码脱节 - 对高危操作（如删除、转账、发布），在参数校验后增加二次确认字段（如
confirmationToken: "I_CONFIRM_DELETION"），并在校验器中强制校验该 token
