Java API设计应优先使用包装类而非基本类型以支持null语义，金额用BigDecimal，ID用Long，字符串统一用String并加约束，配套OpenAPI文档明确范围与单位。
Java基本数据类型在API设计中不是随便用的，得兼顾语义清晰、类型安全和调用友好。直接暴露原始类型虽简单，但容易引发空指针、精度丢失、范围越界或逻辑歧义等问题。规范使用的关键在于“该用原始类型时用，该用包装类或专用类型时坚决不妥协”。
基础类型与包装类的取舍原则
API方法参数和返回值中，优先考虑使用包装类（Integer、Boolean、Double等），而非基本类型（int、boolean、double）。
- 包装类可表达“缺失/未设置”语义（如 null），而基本类型只能是默认值（0、false），易掩盖业务意图
- JSON序列化（如Spring Web）对基本类型无法区分“未传”和“传了默认值”，而包装类能自然映射为 null
- 注意 Integer 缓存机制（-128 到 127）：用 == 比较可能出错，统一用 .equals()
- 布尔类型尤其敏感：接口中避免用 boolean 接收开关参数；应使用 Boolean 并明确约定 null 表示“忽略”或“保持原值”
数值精度与边界控制
涉及金额、计数、时间戳等关键字段，不能无脑用 int 或 long，需结合业务场景选型。
- 货币类字段必须使用 BigDecimal（且用 String 构造），禁止用 float/double —— 浮点误差在金融场景不可接受
- 主键、ID 类字段推荐 Long（非 long），便于后续兼容分布式ID或空值标识
- 状态码、枚举索引等有明确定义范围的，可用 int，但应在文档中标注合法取值（如 status: 0=待处理, 1=成功, 2=失败）
- 避免在 API 中暴露 byte、short —— 客户端支持度低，且无实际语义优势
字符与字符串的规范表达
char 在 API 层几乎不出现；字符串统一用 String，并配合约束增强健壮性。
立即学习“Java免费学习笔记（深入）”；
- 所有文本字段均用 String，禁用 char（单字符无业务意义，且 JSON 不支持 char 原生类型）
- 对外暴露的 String 字段应声明非空要求（如 Spring 的 @NotBlank）或明确允许 null/空串的语义
- 敏感字段（密码、token）建议标注 @JsonIgnore 或做脱敏处理，不在响应体中明文返回
- 大小写敏感性需文档说明：例如用户名是否区分大小写，搜索字段是否忽略大小写（影响 equalsIgnoreCase 使用）
API文档与类型提示同步
类型声明只是起点，配套文档和工具提示才能让使用者真正理解约束。
- 使用 OpenAPI（Swagger）时，为每个字段补充 description 和 example，尤其是边界值（如 “最大长度 32，仅支持字母数字下划线”）
- 避免在 Javadoc 中只写 “@param id the id” —— 应写 “@param id 用户唯一标识，正整数，范围 1–9223372036854775807”
- 对可能溢出的数值字段（如秒级时间戳），在文档中标注单位（milliseconds since epoch）并提醒客户端使用 long 接收
- 若某参数逻辑上应为枚举，不要用 int 或 String 替代，而应定义对应枚举类，并在 OpenAPI 中生成 enum schema
