Jackson使用指南

Jackson是Java生态中最流行的JSON处理库，提供了强大的JSON处理能力。本文详细介绍Jackson的使用方法和最佳实践。

📋 目录

🎯 一、Maven依赖

1.1 添加依赖

xml

<!-- Jackson核心 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.16.0</version>
</dependency>

<!-- Jackson注解 -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.16.0</version>
</dependency>

<!-- Jackson XML支持 -->
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.16.0</version>
</dependency>

🎯 二、基本使用

2.1 ObjectMapper

创建ObjectMapper：

java

import com.fasterxml.jackson.databind.ObjectMapper;

// 创建ObjectMapper
ObjectMapper objectMapper = new ObjectMapper();

// 配置ObjectMapper
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
objectMapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
objectMapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

2.2 对象序列化

序列化为JSON字符串：

java

// 创建对象
User user = new User("张三", 25, "zhangsan@example.com");

// 序列化为JSON字符串
String json = objectMapper.writeValueAsString(user);
// 结果：{"name":"张三","age":25,"email":"zhangsan@example.com"}

// 序列化为JSON（格式化输出）
String prettyJson = objectMapper.writerWithDefaultPrettyPrinter()
    .writeValueAsString(user);

// 序列化到文件
objectMapper.writeValue(new File("user.json"), user);

// 序列化到输出流
objectMapper.writeValue(new FileOutputStream("user.json"), user);

序列化示例：

java

// 复杂对象序列化
public class Order {
    private Long orderId;
    private List<OrderItem> items;
    private BigDecimal totalAmount;
    private Date createTime;
    
    // getter和setter
}

Order order = new Order();
// ... 设置属性

String json = objectMapper.writeValueAsString(order);

2.3 对象反序列化

从JSON字符串反序列化：

java

String json = "{\"name\":\"张三\",\"age\":25,\"email\":\"zhangsan@example.com\"}";

// 反序列化
User user = objectMapper.readValue(json, User.class);

// 从文件反序列化
User user2 = objectMapper.readValue(new File("user.json"), User.class);

// 从输入流反序列化
User user3 = objectMapper.readValue(
    new FileInputStream("user.json"), 
    User.class
);

// 从URL反序列化
User user4 = objectMapper.readValue(
    new URL("http://example.com/user.json"),
    User.class
);

泛型反序列化：

java

// 反序列化为List
String json = "[{\"name\":\"张三\"},{\"name\":\"李四\"}]";
List<User> users = objectMapper.readValue(
    json,
    new TypeReference<List<User>>() {}
);

// 反序列化为Map
String json2 = "{\"user1\":{\"name\":\"张三\"},\"user2\":{\"name\":\"李四\"}}";
Map<String, User> userMap = objectMapper.readValue(
    json2,
    new TypeReference<Map<String, User>>() {}
);

2.4 JSON节点操作

JsonNode操作：

java

String json = "{\"name\":\"张三\",\"age\":25,\"address\":{\"city\":\"北京\"}}";

// 解析为JsonNode
JsonNode rootNode = objectMapper.readTree(json);

// 获取字段值
String name = rootNode.get("name").asText();
int age = rootNode.get("age").asInt();

// 获取嵌套字段
String city = rootNode.get("address").get("city").asText();

// 判断字段是否存在
boolean hasName = rootNode.has("name");

// 获取数组节点
JsonNode arrayNode = rootNode.get("items");
if (arrayNode.isArray()) {
    for (JsonNode item : arrayNode) {
        // 处理数组元素
    }
}

// 转换为对象
User user = objectMapper.treeToValue(rootNode, User.class);

🎯 三、注解使用

3.1 常用注解

@JsonProperty：

java

public class User {
    @JsonProperty("user_name")
    private String name;
    
    @JsonProperty("user_age")
    private Integer age;
    
    // 序列化时包含，反序列化时忽略
    @JsonProperty(value = "email", access = JsonProperty.Access.READ_ONLY)
    private String email;
}

// JSON: {"user_name":"张三","user_age":25}

@JsonIgnore：

java

public class User {
    private String name;
    
    @JsonIgnore
    private String password;  // 序列化和反序列化时忽略
    
    @JsonIgnore(serialize = true, deserialize = false)  // 仅反序列化时忽略
    private String secret;
}

@JsonFormat：

java

public class Order {
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private Date createTime;
    
    @JsonFormat(shape = JsonFormat.Shape.STRING)
    private BigDecimal amount;
    
    @JsonFormat(pattern = "yyyy-MM-dd")
    private LocalDate orderDate;
}

@JsonInclude：

java

@JsonInclude(JsonInclude.Include.NON_NULL)  // 忽略null值
public class User {
    private String name;
    private Integer age;
    private String email;  // 如果为null，不会出现在JSON中
}

// 或者配置ObjectMapper
objectMapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

@JsonIgnoreProperties：

java

@JsonIgnoreProperties({"password", "secret"})  // 忽略多个字段
public class User {
    private String name;
    private String password;
    private String secret;
}

// 忽略未知属性（反序列化时）
@JsonIgnoreProperties(ignoreUnknown = true)
public class User {
    // ...
}

@JsonPropertyOrder：

java

@JsonPropertyOrder({"age", "name", "email"})  // 指定序列化顺序
public class User {
    private String name;
    private Integer age;
    private String email;
}

3.2 集合和Map注解

集合处理：

java

public class Order {
    @JsonFormat(with = JsonFormat.Feature.ACCEPT_SINGLE_VALUE_AS_ARRAY)
    private List<OrderItem> items;
    
    @JsonDeserialize(contentAs = OrderItem.class)
    private List<OrderItem> items2;
}

Map处理：

java

public class User {
    @JsonFormat(shape = JsonFormat.Shape.OBJECT)
    private Map<String, String> attributes;
    
    @JsonAnySetter  // 反序列化时，未知属性放入Map
    private Map<String, Object> extraProperties = new HashMap<>();
    
    @JsonAnyGetter  // 序列化时，将Map中的属性展开
    public Map<String, Object> getExtraProperties() {
        return extraProperties;
    }
}

🎯 四、自定义序列化

4.1 自定义序列化器

实现自定义序列化器：

java

// 自定义序列化器
public class CustomDateSerializer extends JsonSerializer<Date> {
    private SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
    
    @Override
    public void serialize(Date date, JsonGenerator gen, SerializerProvider serializers)
            throws IOException {
        gen.writeString(formatter.format(date));
    }
}

// 使用自定义序列化器
public class Order {
    @JsonSerialize(using = CustomDateSerializer.class)
    private Date createTime;
}

4.2 自定义反序列化器

实现自定义反序列化器：

java

// 自定义反序列化器
public class CustomDateDeserializer extends JsonDeserializer<Date> {
    private SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd");
    
    @Override
    public Date deserialize(JsonParser p, DeserializationContext ctxt)
            throws IOException {
        try {
            return formatter.parse(p.getText());
        } catch (ParseException e) {
            throw new IOException(e);
        }
    }
}

// 使用自定义反序列化器
public class Order {
    @JsonDeserialize(using = CustomDateDeserializer.class)
    private Date createTime;
}

🎯 五、高级特性

5.1 ObjectMapper配置

常用配置：

java

ObjectMapper mapper = new ObjectMapper();

// 反序列化配置
mapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
mapper.configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false);
mapper.configure(DeserializationFeature.ACCEPT_EMPTY_STRING_AS_NULL_OBJECT, true);

// 序列化配置
mapper.configure(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, false);
mapper.configure(SerializationFeature.FAIL_ON_EMPTY_BEANS, false);
mapper.configure(SerializationFeature.INDENT_OUTPUT, true);  // 格式化输出

// 日期格式配置
mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
mapper.setTimeZone(TimeZone.getTimeZone("GMT+8"));

// 忽略null值
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

// 属性命名策略
mapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE);

5.2 多态处理

@JsonTypeInfo和@JsonSubTypes：

java

@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
@JsonSubTypes({
    @JsonSubTypes.Type(value = Dog.class, name = "dog"),
    @JsonSubTypes.Type(value = Cat.class, name = "cat")
})
public abstract class Animal {
    private String name;
}

public class Dog extends Animal {
    private String breed;
}

public class Cat extends Animal {
    private boolean indoor;
}

5.3 树模型操作

树模型使用：

java

// 创建JSON树
ObjectMapper mapper = new ObjectMapper();
ObjectNode root = mapper.createObjectNode();
root.put("name", "张三");
root.put("age", 25);

ObjectNode address = mapper.createObjectNode();
address.put("city", "北京");
address.put("street", "中关村");
root.set("address", address);

ArrayNode hobbies = mapper.createArrayNode();
hobbies.add("读书");
hobbies.add("编程");
root.set("hobbies", hobbies);

// 转换为JSON字符串
String json = mapper.writeValueAsString(root);

// 从JSON字符串创建树
JsonNode tree = mapper.readTree(json);

📖 学习资源

官方文档

Jackson官方文档

网站资源

Jackson Wiki

✅ 学习检查清单

[ ] 已掌握ObjectMapper的基本使用
[ ] 已熟悉常用注解
[ ] 已了解自定义序列化器
[ ] 已掌握高级特性配置
[ ] 已了解多态处理

上一章节：Apache Commons使用
下一章节：其他工具包使用
返回目录：代码规范

开发与调试

测试能力

运维与监控

NoSQL

中间件

存储

接入层

操作系统

框架

硬件知识

缓存

品质

经验底蕴

能力

任务拆分

文档能力

协议设计

基本理论

接入层架构

数据层架构

通讯机制

逻辑层架构

Jackson使用指南 ​

📋 目录 ​

🎯 一、Maven依赖 ​

1.1 添加依赖 ​

🎯 二、基本使用 ​

2.1 ObjectMapper ​

2.2 对象序列化 ​

2.3 对象反序列化 ​

2.4 JSON节点操作 ​

🎯 三、注解使用 ​

3.1 常用注解 ​

3.2 集合和Map注解 ​

🎯 四、自定义序列化 ​

4.1 自定义序列化器 ​

4.2 自定义反序列化器 ​

🎯 五、高级特性 ​

5.1 ObjectMapper配置 ​

5.2 多态处理 ​

5.3 树模型操作 ​

📖 学习资源 ​

官方文档 ​

网站资源 ​

✅ 学习检查清单 ​

Jackson使用指南

📋 目录

🎯 一、Maven依赖

1.1 添加依赖

🎯 二、基本使用

2.1 ObjectMapper

2.2 对象序列化

2.3 对象反序列化

2.4 JSON节点操作

🎯 三、注解使用

3.1 常用注解

3.2 集合和Map注解

🎯 四、自定义序列化

4.1 自定义序列化器

4.2 自定义反序列化器

🎯 五、高级特性

5.1 ObjectMapper配置

5.2 多态处理

5.3 树模型操作

📖 学习资源

官方文档

网站资源

✅ 学习检查清单