入参必须用包装类而非基本类型，以准确表达“值是否存在”的语义；DTO/VO字段、路径变量、查询参数均应使用Integer、String、Boolean等包装类型，避免语义丢失、校验失效及空指针风险。
API 入参设计中，基本类型和包装类的选择不是随意的，而是有明确语义和工程约束的。核心原则是：入参必须能准确表达业务含义，尤其是“值是否存在”这一关键语义。
DTO/VO 等请求体字段统一用包装类
所有面向外部（前端、第三方系统、RPC 调用）的请求对象（如 UserCreateRequest、OrderQueryParam），其字段必须使用包装类型（Integer、String、Boolean 等）。
- 数据库字段可能为 NULL，JSON 反序列化时 null 字段需被保留，基本类型会强制转为默认值（如 int → 0），造成语义丢失
- 前端传参可能省略某个字段，Jackson 默认将缺失字段反序列化为 null —— 只有包装类才能区分“未传”和“传了 0”
- 校验框架（如 Hibernate Validator）对 @NotNull、@Min 等注解的生效前提是字段可为空，基本类型无法配合 @NotNull 做空值校验
路径变量和查询参数推荐用包装类 + 显式判空
@PathVariable 和 @RequestParam 的参数类型建议声明为包装类（如 Long id、Integer status），而非 long 或 int。
- Spring MVC 对基本类型参数有隐式强制转换：若 URL 中传了非数字（如 /user/abc），会直接抛 400 错误，而包装类配合 @RequestParam(required = false) 可优雅支持可选参数
- 业务逻辑中常需判断“是否指定了该条件”，例如 status 为 null 表示不限状态，为 0 表示查“待处理”——这种语义只有包装类能承载
- 避免自动拆箱引发的 NullPointerException：若写成 public User getUser(@PathVariable long id)，而调用方传了空或非法值，异常发生在框架层；改用 Long id 后，可在方法内主动 if (id == null) 处理
避免在入参中混用基本类型与包装类
同一个 DTO 内不要一部分字段用 int，一部分用 Integer —— 这会造成语义不一致和维护混乱。
立即学习“Java免费学习笔记（深入）”；
- 例如 age 字段用 int，但 score 用 Integer，会导致调用方无法理解为何一个必须传、另一个可不传
- 团队规范应统一要求：所有入参字段（含嵌套对象）均为包装类型，除非有强性能诉求且经压测验证（极少见）
- IDE 可配置检查规则，禁止在 DTO 类中出现基本类型字段
特殊场景：布尔类型入参务必用 Boolean
boolean 类型尤其容易踩坑。绝对不要用 boolean 接收开关类参数（如 enabled、isDeleted）。
- 前端传 { "enabled": null } 或字段缺失时，boolean 会被设为 false，导致“关闭”语义被错误覆盖
- Boolean 可明确表达三种状态：true（启用）、false（禁用）、null（未指定/忽略该条件）
- 配合 @ApiParam(hidden = true) 或 OpenAPI 注释说明 null 的业务含义，提升 API 可用性
