Java Jackson核心注解使用详解_Java

前言

在 java 后端开发中，jackson 是最常用的 json 序列化/反序列化工具之一。jackson 提供了一系列功能强大的注解，用于精确控制 json 与 java 对象之间的映射逻辑。本文将深入讲解常用的几个核心注解：

@jsonproperty：指定字段的 json 名称
@jsonignore：忽略字段序列化/反序列化
@jsoninclude：控制字段是否参与序列化（如 null、空集合等）
@jsonformat：格式化日期时间
@jsoncreator / @jsonvalue：自定义对象的序列化/反序列化逻辑

一、@jsonproperty-指定json字段名

默认情况下，jackson 使用 java 字段名作为 json 字段名。但在前后端字段命名不一致时，可以使用 @jsonproperty 显式指定：

public class user {
    @jsonproperty("user_name")
    private string username;
    // getter/setter
}

输出 json：

{
  "user_name": "tom"
}

二、@jsonignore-忽略字段

@jsonignore 用于在序列化或反序列化过程中跳过某些字段，比如密码、内部字段等：

public class account {
    private string username;
    @jsonignore
    private string password;
    // getter/setter
}

输出 json 不包含 password 字段。

三、@jsoninclude-控制是否输出null或空字段

通过 @jsoninclude 可以控制字段是否输出。常见选项：

include.non_null：忽略 null 值
include.non_empty：忽略 null、空字符串、空集合等

@jsoninclude(jsoninclude.include.non_null)
public class product {
    private string name;
    private string description;
}

当 description 为 null 时不会出现在 json 中。

也可以作用于类、字段或全局配置：

@jsoninclude(jsoninclude.include.non_empty)
private list<string> tags;

四、@jsonformat-格式化时间

java 中的日期类型默认序列化为时间戳。通过 @jsonformat 可以指定格式和时区：

public class event {
    @jsonformat(pattern = "yyyy-mm-dd hh:mm:ss", timezone = "gmt+8")
    private date eventtime;
}

输出 json 中的日期格式为："2025-05-06 16:00:00"

五、@jsoncreator/@jsonvalue-自定义序列化与反序列化

1. @jsoncreator：构造方法反序列化

当对象没有默认构造器，或你希望控制反序列化逻辑时使用：

public class currency {
    private string code;
    @jsoncreator
    public currency(@jsonproperty("code") string code) {
        this.code = code;
    }
    public string getcode() { return code; }
}

2. @jsonvalue：自定义序列化值

如果你希望整个对象在序列化时只输出某个字段，可以使用 @jsonvalue：

public class status {
    private final string value;
    public status(string value) {
        this.value = value;
    }
    @jsonvalue
    public string getvalue() {
        return value;
    }
}

序列化后将只输出字符串：

"active"

六、完整示例

public class user {
    @jsonproperty("user_name")
    private string username;
    @jsonignore
    private string password;
    @jsoninclude(jsoninclude.include.non_null)
    private string email;
    @jsonformat(pattern = "yyyy-mm-dd")
    private date birthday;
    // getters and setters
}

七、实战项目结构与代码仓库

示例接口返回序列化结果

@restcontroller
public class usercontroller {
    @getmapping("/user")
    public user getuser() {
        user user = new user();
        user.setusername("alice");
        user.setpassword("123456");
        user.setemail(null);
        user.setbirthday(new date());
        return user;
    }
}