DevTool 团队

从 JSON 生成 Java 类:注解、Lombok 与类型推断的选项怎么定

接口返回的 JSON 要变成 Java DTO,手写字段加 getter/setter 是最低效的事。这篇讲清生成器的选项怎么按项目定:序列化库是 Jackson 还是 Gson 决定注解(@JsonProperty vs @SerializedName,用错库读不到),有 Lombok 依赖就开 @Data 省样板,包装类型还是基本类型看字段能否为 null。再讲类型推断的四个盲区——整数一律推 Integer(13 位毫秒时间戳会溢出,手改 Long)、null 与空数组推成 Object、混合数组退化成 List<Object>、snake_case 字段靠注解映射;最后是真话:生成的类是样本快照不是契约,API 加字段要靠 ignoreUnknown 兜底,record 是现代选择但工具生成的是传统 POJO。

先定三个选项:按项目现状选

生成 Java 类不是「点一下就完」,三个选项决定生成的代码能不能直接用。按你项目的现状定(以本站 JSON 转 Java 类生成器 为例):

你的项目 选项 为什么
用 Jackson(Spring Boot 默认) 注解选 Jackson @JsonProperty 字段名映射与反序列化靠它;选错库注解=静默全 null
用 Gson 注解选 Gson @SerializedName 同上,库与注解必须配套
有 Lombok 依赖 开 @Data getter/setter/toString/equals 全省,类体只剩字段
没 Lombok 或团队禁用 关掉,生成显式 getter/setter 代码长但零依赖
字段可能为 null 包装类型(Integer/Boolean) 基本类型装不下 null,反序列化会抛错
字段保证有值且追求性能 基本类型(int/boolean) 省装箱,但遇 null 就炸

类名、包名、访问修饰符按团队规范填;嵌套对象会生成内部类(或独立类),数组生成 List<T>。

类型推断规则与四个盲区

生成器只能看你给的那份样本推断类型,规则与盲区都要清楚:

JSON 值 推断的 Java 类型 盲区
"text" String —
true Boolean / boolean —
42 Integer / int 13 位时间戳、雪花 ID 会溢出——手改 Long
3.14 Double / double 金额场景建议手改 BigDecimal
null Object 样本里是 null 就推不出真实类型
[] List<Object> 空数组推不出元素类型
[1, "a"] List<Object> 混合类型退化
{...} 嵌套类 —

盲区一:整数溢出。 这是生成器最隐蔽的坑——JSON 里 1730000000000 看起来是个普通整数,推成 Integer 后反序列化直接溢出。规则:超过 10 位的整数一律手改 Long,ID 类字段尤其如此(很多 API 干脆用字符串传 ID 规避前端 JS 的 2^53 精度问题,这时推成 String 反而是对的)。

盲区二:null 与空数组。 推成 Object 的字段是生成器在说「我不知道」——拿一份字段都有值、数组都非空的完整样本重新生成,或按接口文档手改。上线前过一遍所有 Object 字段是必要收尾。

盲区三:混合类型数组。 [1, "a"] 只能是 List<Object>,通常意味着接口设计本身有问题——拿着这个结果去跟接口方确认,比在 Java 侧硬处理强。

盲区四:字段命名。 user_name 转成 userName 靠注解映射原名;Java 保留字(class、default)会被加后缀避让——注意改名后的字段要与注解里的原名对得上。

注解:库与注解必须配套

@JsonProperty("user_name") 是 Jackson 的,@SerializedName("user_name") 是 Gson 的——用错一个,反序列化不报错,字段全部 null,这是排查成本最高的一类问题。

三条实践:

  • 项目用什么库就选什么注解,Spring Boot 默认 Jackson;
  • 整个项目都是 snake_case JSON 时,别每个字段加注解——在 ObjectMapper 上配全局命名策略(PropertyNamingStrategies.SNAKE_CASE)一处生效;
  • Lombok @Data 与注解可以共存:注解挂在字段上,Lombok 生成的 getter/setter 不影响序列化库按字段注解工作。

真话:生成的类是快照,不是契约

  • 样本决定一切:生成器按你贴的那份 JSON 推断——样本里没出现的字段它不知道,可选字段它当必有,null 字段它推 Object。拿接口文档或多份真实响应对一遍再上线;
  • API 会演进:上游加字段后,严格模式的反序列化会抛 UnrecognizedPropertyException——给类加 @JsonIgnoreProperties(ignoreUnknown = true) 或配全局 FAIL_ON_UNKNOWN_PROPERTIES=false,让新字段静默忽略而不是把接口打挂;
  • record 是现代选择:Java 16+ 的 record 不可变、极简,纯数据传输很合适;生成器产出的是传统可变 POJO——团队用 Java 17+ 且接受不可变风格的,拿生成结果手改成 record 工作量很小;有 Lombok 的,@Data 已经把样板消掉大半,两者实际差距不大。

生成器的价值是把「照着 JSON 敲字段」这件机械活压到零,字段类型与演进策略仍然是你的工程判断。

常见问题

JSON 字段是 snake_case,Java 字段要 camelCase,怎么对上?

靠序列化注解做映射:生成器把 user_name 转成 Java 字段 userName,同时在字段上加 @JsonProperty("user_name")(Jackson)或 @SerializedName("user_name")(Gson),反序列化时库按注解里的原名找 JSON 键。两点要注意:注解必须与你项目实际用的库配套——混用就是静默全 null;以及整个项目都是 snake_case 时,与其每个字段加注解,不如在 ObjectMapper 上全局配置命名策略,一处配置全局生效。

为什么有的字段被推断成了 Object?

类型推断只能看你给的样本,三种情况推不出具体类型:字段值是 null、数组为空、数组元素类型不一致。这些 Object 字段是生成器在说「样本信息不够」,不是最终答案——拿一份字段都有值、数组都非空的完整样本重新生成,或者按接口文档手工改成正确类型。上线前把所有 Object 字段过一遍,是用生成器的必要收尾。

整数字段为什么用 Integer 会出问题?

生成器看到整数一律推成 Integer(或 int),但 Java 的 int 上限是 2,147,483,647——13 位的毫秒时间戳、雪花算法 ID、大额金额全部超过这个范围,反序列化时直接溢出或抛错。判断方法:JSON 里的整数超过 10 位就该怀疑,时间戳与 ID 类字段一律手改 Long。更稳的做法是金额用 BigDecimal、ID 用 Long 或 String。

应该用生成的可变 POJO 还是 Java record?

record(Java 16+)是不可变的数据载体,代码极简且语义清晰,适合纯数据传输;传统 POJO 适合需要逐步填充、与老框架兼容的场景。生成器产出的是传统 POJO——拿它当起点,项目是 Java 17+ 且团队接受不可变风格的,手工改成 record 工作量很小;团队有 Lombok 的,@Data 已经把样板消掉大半,两者差距其实不大。