API入参应按是否允许“未传”选择类型：可选参数用包装类（如Integer、Boolean）以支持null语义，必填参数用基本类型（如int、boolean）确保非空且性能更优。
API 入参用基本类型还是包装类，关键看这个参数是否允许“未传”或“无值”。基本类型强制有值，包装类能为 null，这是设计分界点。
明确区分语义：什么时候必须用包装类
当参数是可选筛选条件、业务上允许忽略时，必须用包装类。比如：
-
状态码查询：
Integer status—— 传null表示“不限状态”，传1表示查“已启用”；若用int status，调用方无法表达“不传”意图，只能硬塞默认值（如0），易引发歧义。 -
分页可选字段：
Long categoryId—— 用于按分类筛选，不传即查全部；用基本类型则必须约定“-1 表示无效”，破坏语义清晰性。 -
布尔开关：
Boolean isUrgent——null表示“不指定优先级”，true/false才是明确决策；而boolean只能是真或假，没有“未设置”状态。
哪些场景适合用基本类型
参数在业务逻辑中必然存在且不可为空，就该用基本类型。它更轻量、无空指针风险、性能略优：
-
分页参数：
int pageNum、int pageSize—— 分页请求必须带页码和大小，缺一不可，用基本类型可由框架自动校验非负、非零。 -
主键标识：
long id—— 更新或删除操作必须指定有效 ID，不允许模糊匹配。 -
计数类字段：
int retryTimes—— 次数从 0 开始累加，天然有定义域，无需 null 表达“未开始”。
避免混用与陷阱
同一接口中不要对相似含义的参数混用类型，否则增加调用方理解成本：
立即学习“Java免费学习笔记（深入）”；
- ❌ 错误示范：
updateUser(int id, String name, Boolean isActive, int version)——isActive是包装类，version是基本类型，但两者都属“控制状态”的字段，语义不统一。 - ✅ 推荐做法：统一为
Integer version，如果版本号确实必传，就改用Integer并配合@NotNull校验；若允许跳过，则保持Integer并文档注明 “null 表示不校验版本”。 - ⚠️ 注意自动拆箱空指针：
if (status == 1)在status为null时会抛NullPointerException，应改用Objects.equals(status, 1)或先判空。
配合校验与文档强化规范
光选对类型不够，要让意图真正落地：
- 用
@Null/@NotNull等 Bean Validation 注解明确约束，例如：@Null(message = "status 为空表示查询全部") Integer status。 - 在 OpenAPI 文档或 Javadoc 中写清每个包装类参数的
null含义，比如：“status：状态码，null 表示不限制，0 表示禁用，1 表示启用”。 - 入参 DTO 中所有字段尽量使用包装类，再通过全局校验器统一处理必填逻辑，比在每个方法里手工判空更可靠。
