企业级java开发中基本类型与包装类须按语义选型：字段层依业务定类型，接口层入参出参强制包装类，工具层封装安全转换，配置层通过静态检查和文档约束保障演进。
字段定义层：按语义选型，禁用模糊赋值
实体类（Entity）、DTO、VO 等数据载体中的字段，必须根据业务含义决定使用基本类型还是包装类：
-
用基本类型：表示“该值绝对不可为空”且有明确默认语义（如订单状态码
int status，0=待支付，1=已支付）；或性能敏感场景（如高频计算的中间变量） -
用包装类：表示“该值可能缺失/未设置”，需区分“0”和“未传”（如用户年龄
Integer age，null 表示未填写，0 表示真实年龄为 0）；或需参与泛型/集合操作（如List<long> ids</long>） -
禁止写法：
private int id;用于数据库主键但允许为空；private Integer amount;却在 service 层直接amount + 1而不判空
接口契约层：入参出参强制包装类，内部流转按需优化
对外暴露的 API 接口（Controller、Feign Client、RPC 方法）必须统一使用包装类作为参数和返回值类型：
- 入参用
Long userId而非long userId，便于前端不传时接收为null，再由校验器（如@NotNull）或业务逻辑明确处理缺失场景 - 出参 DTO 字段全部声明为包装类（如
BigDecimal price、Boolean isVip），避免反序列化失败或默认值污染（如boolean反序列化失败会默认为false，掩盖真实问题） - 服务内部调用可按需转为基本类型（如 DAO 层查出
Integer后，在非空校验通过后转int参与计算），但转换点必须显式注释说明依据
工具与常量层：封装装箱/拆箱逻辑，杜绝裸调xxxValue()
避免散落在各处的intValue()、longValue()等裸拆箱操作——这是空指针高发区：
- 提供统一工具方法，如
NumberUtils.safeInt(Integer i, int defaultVal)，内部自动判空并返回默认值 - 对必须非空的场景（如 DB 主键回写），使用断言：
Objects.requireNonNull(id, "id must not be null")，而非静默转基本类型 - 禁止在日志、监控埋点等非核心路径中做隐式拆箱（如
log.info("user id: {}", user.getId())），应先转字符串：String.valueOf(user.getId())
配置与演进层：版本化约束 + 静态检查兜底
标准要能持续生效，需配套机制：
- 在代码扫描规则（如 SonarQube 或 Alibaba Java Coding Guidelines）中启用：
Prefer wrapper types in DTOs、Avoid unboxing without null check等规则 - 在 Swagger/OpenAPI 文档生成时，配置包装类字段自动标注
nullable: true，基本类型字段标nullable: false，形成前后端契约共识 - 新模块上线前，要求 DTO 类必须实现
Serializable并添加serialVersionUID，防止因包装类序列化差异引发兼容问题
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
