Jackson 序列化 / 反序列化注解 完整版笔记
SpringBoot 默认使用 Jackson
序列化：Java 对象 → JSON（后端返回给前端）
反序列化：JSON → Java 对象（接收前端传参）
✅双向 = 序列化、反序列化都生效
✅仅序列化 = 只在对象转 JSON 时生效
✅仅反序列化 = 只在 JSON 转对象时生效
一、注解总表
| 注解 | 生效范围 | 核心功能 | 适用场景 | 重点注意 |
|---|---|---|---|---|
@JsonUnwrapped | 双向 | 把嵌套对象拍平展开，嵌套对象字段和外层同级 | 一对一 VO，想返回单层 JSON | ❌ 不能用于 List 集合（一对多不行）；重名字段建议加prefix前缀避免冲突 |
@JsonIgnore | 双向 | 序列化、反序列化都直接忽略该字段 | 敏感字段（密码、内部操作人） | 完全不参与转换；如果只是入参需要、返回不需要，不要用它 |
@JsonIgnoreProperties(ignoreUnknown = true) | 仅反序列化 | 反序列化时，自动忽略前端多传的多余字段 | 所有 DTO、VO 都推荐加 | 防止前端传额外字段直接报错 |
@JsonProperty("xxx") | 双向 | 修改 JSON 的 key 名称，双向生效 | Java 字段名和前端 key 不一致 | 搭配 access 属性：WRITE_ONLY：仅反序列化（只接收，不返回）READ_ONLY：仅序列化（只返回，不接收） |
@JsonAlias({"k1","k2"}) | 仅反序列化 | 多个 key 都映射到同一个 Java 字段 | 兼容旧前端、多种入参 key | 序列化输出还是@JsonProperty定义的名字，不会输出别名 |
@JsonInclude | 仅序列化 | 控制是否输出空值 | 不想返回 null、空字符串 | NON_NULL：null 值不输出NON_EMPTY：null、空串、空集合都不输出 |
@JsonFormat | 双向 | 日期格式化 + 指定时区 | Date 类型日期 | 必须写时区 timezone = "GMT+8" |
@JsonPropertyOrder | 仅序列化 | 序列化时，自定义 JSON 字段输出顺序 | 需要固定返回字段顺序 | 日常开发很少用，前端一般不依赖顺序 |
@JsonValue | 仅序列化 | 枚举序列化直接输出指定值，不是枚举名称 | 枚举返回 code 数字 | 反序列化一般配合 @JsonCreator 一起用 |
@JsonSerialize / @JsonDeserialize | 仅序列化 / 仅反序列化 | 自定义序列化 / 反序列化转换器 | 特殊格式：BigDecimal、特殊编码 | 复杂场景才用，普通开发少用 |
二、按生效时机分组（背诵用）
🔹 只在【序列化】生效（对象→JSON，返回前端）
@JsonInclude控制空值要不要返回@JsonPropertyOrder字段输出顺序@JsonSerialize自定义序列化转换器@JsonProperty(access = READ_ONLY)只读，只往外返回@JsonValue枚举输出
🔹 只在【反序列化】生效（JSON→对象，接收前端）
@JsonAlias兼容多个入参 key@JsonIgnoreProperties(ignoreUnknown = true)忽略前端多余字段@JsonDeserialize自定义反序列化转换器@JsonProperty(access = WRITE_ONLY)只接收，不返回
🔹 双向都生效（序列化、反序列化一起控制）
@JsonUnwrapped拍平嵌套@JsonIgnore字段完全忽略@JsonProperty("xxx")修改 key 名称（不带 access）@JsonFormat日期格式化
三、高频使用组合（一般项目直接抄）
- 一对一 VO 拍平
@JsonUnwrapped(prefix = "a_")
private A a;
@JsonUnwrapped(prefix = "b_")
private B b;
好处：A、B 都继承 BaseEntity，存在 id 重名，前缀规避冲突
- DTO 统一加：
@JsonIgnoreProperties(ignoreUnknown = true) - 密码字段：
@JsonProperty(access = JsonProperty.Access.WRITE_ONLY)，不要用 @JsonIgnore - 日期：
@JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8") - VO 空值优化：
@JsonInclude(JsonInclude.Include.NON_NULL)
四、必背坑点（重点）
@JsonUnwrapped只支持一对一，不能放在 List 集合上，一对多无法拍平@JsonAlias只在接收参数生效，返回 JSON 不会输出别名@JsonIgnore是双向剔除；WRITE_ONLY 是【入参可读、返回不输出】，二者区分开- 父类 BaseEntity 公共字段，如果不想返回，需要单独加
@JsonIgnore，注解不会自动忽略父类属性 @JsonUnwrapped不加 prefix，A、B 存在同名字段（比如 id）会直接序列化报错
五、场景选型速查
- ✅ 一对一，查询返回单层 JSON：
@JsonUnwrapped - ✅ 前后端 key 名字不一样：
@JsonProperty - ✅ 兼容前端多种传参 key：
@JsonAlias - ✅ 密码：接收要、返回不要：
@JsonProperty(access = WRITE_ONLY) - ✅ 不想返回 null 字段：
@JsonInclude - ✅ 防止前端乱传字段报错：
@JsonIgnoreProperties(ignoreUnknown=true) - ✅ 日期格式化：
@JsonFormat - ✅ 完全不参与转换的内部字段：
@JsonIgnore
六、高频易混对比
@JsonAliasvs@JsonProperty
@JsonAlias：只接收用，输出 json 不会显示别名@JsonProperty("xxx")：接收和输出，key 统一变成 xxx
WRITE_ONLY/READ_ONLY/@JsonIgnore
- WRITE_ONLY：✅收 ❌返回（密码）
- READ_ONLY：❌收 ✅返回（自动生成创建时间）
- @JsonIgnore：❌收 ❌返回（内部字段）
@JsonIgnoreProperties(ignoreUnknown=true)
只管接收参数的时候，前端乱传多余字段不报错；不会影响返回给前端的 json。
七、一句话速记
往外给前端（序列化）：JsonInclude、JsonPropertyOrder、READ_ONLY、@JsonSerialize
接收前端传参（反序列化）：JsonAlias、ignoreUnknown、WRITE_ONLY、@JsonDeserialize
两边都管：@JsonUnwrapped、@JsonIgnore、@JsonProperty、@JsonFormat
转载自 CSDN-专业IT技术社区
原文链接：https://blog.csdn.net/handsome_sai/article/details/170412897
