Jackson依赖详解

Jackson 依赖详解

Jackson 是 Java 生态中最流行的 JSON 处理库，由多个模块组成。本文详细介绍各个依赖的作用。

整体架构

Jackson 采用模块化设计，分为三层：

1
2
3
4
5
6
7
8
9
10
┌─────────────────────────────────────────────────────┐
│                   数据格式模块                        │
│  (jackson-dataformat-xml, yaml, csv, properties...) │
├─────────────────────────────────────────────────────┤
│                   数据绑定层                          │
│              (jackson-databind)                      │
├─────────────────────────────────────────────────────┤
│                    核心层                            │
│      (jackson-core + jackson-annotations)           │
└─────────────────────────────────────────────────────┘

核心模块（必需）

1. jackson-core

作用：Jackson 的基础模块，提供底层流式 API。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.17.0</version>
</dependency>

核心类：

类名 作用
JsonFactory 创建解析器和生成器的工厂
JsonParser 流式读取 JSON（拉模式）
JsonGenerator 流式写入 JSON
JsonToken JSON 令牌类型枚举

使用场景：

  • 需要极致性能的场景
  • 处理超大 JSON 文件（流式处理，内存占用低）
  • 自定义底层解析逻辑

2. jackson-annotations

作用：提供注解定义，用于控制序列化/反序列化行为。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.17.0</version>
</dependency>

常用注解：

注解 作用
@JsonProperty 指定 JSON 字段名
@JsonIgnore 忽略字段
@JsonFormat 格式化日期/数字
@JsonInclude 控制空值是否序列化
@JsonCreator 指定反序列化构造器
@JsonValue 指定序列化时使用的值
@JsonAlias 反序列化时的别名

💡 提示: 提示
此模块无任何依赖，可单独使用于 DTO 定义

3. jackson-databind

作用：数据绑定模块，提供 ObjectMapper，是最常用的模块。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.0</version>
</dependency>

依赖关系：

1
2
3
jackson-databind
├── jackson-core
└── jackson-annotations

📝 注意: 说明
引入 jackson-databind 会自动传递依赖 jackson-core 和 jackson-annotations

核心类：

类名 作用
ObjectMapper 核心类，JSON 与对象互转
JsonNode 树模型，动态解析 JSON
TypeReference 处理泛型类型

数据格式模块

用于支持 JSON 以外的数据格式。

jackson-dataformat-xml

作用：支持 XML 格式的序列化/反序列化。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-xml</artifactId>
    <version>2.17.0</version>
</dependency>

jackson-dataformat-yaml

作用：支持 YAML 格式。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-yaml</artifactId>
    <version>2.17.0</version>
</dependency>

jackson-dataformat-csv

作用：支持 CSV 格式。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-csv</artifactId>
    <version>2.17.0</version>
</dependency>

jackson-dataformat-properties

作用：支持 Java Properties 格式。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.dataformat</groupId>
    <artifactId>jackson-dataformat-properties</artifactId>
    <version>2.17.0</version>
</dependency>

数据类型模块

用于支持特定 Java 类型的序列化。

jackson-datatype-jsr310

作用：支持 Java 8 日期时间 API（LocalDate、LocalDateTime 等）。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.17.0</version>
</dependency>

使用方式：

1
2
ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new JavaTimeModule());

⚠️ 警告: 注意
不注册此模块时，Java 8 日期类型会序列化为复杂对象而非字符串

jackson-datatype-jdk8

作用：支持 Java 8 新类型（Optional、Stream 等）。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jdk8</artifactId>
    <version>2.17.0</version>
</dependency>

jackson-datatype-guava

作用：支持 Guava 集合类型。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-guava</artifactId>
    <version>2.17.0</version>
</dependency>

框架集成模块

jackson-module-kotlin

作用：Kotlin 支持，处理 data class、默认参数等。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-kotlin</artifactId>
    <version>2.17.0</version>
</dependency>

jackson-module-parameter-names

作用：使用 Java 8 参数名反射，无需 @JsonProperty。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-parameter-names</artifactId>
    <version>2.17.0</version>
</dependency>

📝 注意: 前提条件
需要编译时添加 -parameters 参数

jackson-jaxrs-json-provider

作用：JAX-RS（Jersey、RESTEasy）集成。

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.jaxrs</groupId>
    <artifactId>jackson-jaxrs-json-provider</artifactId>
    <version>2.17.0</version>
</dependency>

依赖汇总表

模块 ArtifactId 用途说明
核心 jackson-core 底层解析器，逐字符读写 JSON（性能最优）
核心 jackson-annotations 提供 @JsonProperty 等注解
核心 jackson-databind 提供 ObjectMapper，JSON ↔ 对象互转
格式 jackson-dataformat-xml 支持 XML 格式读写
格式 jackson-dataformat-yaml 支持 YAML 格式读写
格式 jackson-dataformat-csv 支持 CSV 格式读写
类型 jackson-datatype-jsr310 支持 LocalDate/LocalDateTime 等
类型 jackson-datatype-jdk8 支持 Optional/Stream 等
集成 jackson-module-kotlin 支持 Kotlin data class

常见组合推荐

Spring Boot 项目（推荐）

Spring Boot 已内置 Jackson，通常只需添加：

1
2
3
4
5
<!-- Java 8 日期支持（Spring Boot 已自动配置） -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
</dependency>

普通 Java 项目

1
2
3
4
5
6
7
8
9
10
11
12
13
<!-- 基础：数据绑定（自动包含 core 和 annotations） -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.17.0</version>
</dependency>

<!-- Java 8 日期支持 -->
<dependency>
    <groupId>com.fasterxml.jackson.datatype</groupId>
    <artifactId>jackson-datatype-jsr310</artifactId>
    <version>2.17.0</version>
</dependency>

Kotlin 项目

1
2
3
4
5
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-kotlin</artifactId>
    <version>2.17.0</version>
</dependency>

最佳实践

使用 BOM 统一版本

1
2
3
4
5
6
7
8
9
10
11
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.fasterxml.jackson</groupId>
            <artifactId>jackson-bom</artifactId>
            <version>2.17.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

⚠️ 警告: 版本一致性
所有 Jackson 模块必须使用相同版本，否则可能出现兼容性问题

核心 API 详解

ObjectMapper

ObjectMapper 是 Jackson 最核心的类，负责 JSON 与 Java 对象的互转。

基本用法

1
2
3
4
5
6
7
8
9
10
11
12
13
ObjectMapper mapper = new ObjectMapper();

// 对象 → JSON 字符串
String json = mapper.writeValueAsString(user);

// JSON 字符串 → 对象
User user = mapper.readValue(json, User.class);

// JSON 字符串 → List
List<User> users = mapper.readValue(json, new TypeReference<List<User>>() {});

// JSON 字符串 → Map
Map<String, Object> map = mapper.readValue(json, new TypeReference<>() {});

文件读写

1
2
3
4
5
6
7
8
9
10
11
// 写入文件
mapper.writeValue(new File("user.json"), user);

// 从文件读取
User user = mapper.readValue(new File("user.json"), User.class);

// 从 InputStream 读取
User user = mapper.readValue(inputStream, User.class);

// 从 URL 读取
User user = mapper.readValue(new URL("http://api.example.com/user"), User.class);

常用配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
ObjectMapper mapper = new ObjectMapper();

// 格式化输出（美化 JSON）
mapper.enable(SerializationFeature.INDENT_OUTPUT);

// 忽略未知字段（反序列化时）
mapper.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);

// 空对象不报错
mapper.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);

// null 值不序列化
mapper.setSerializationInclusion(JsonInclude.Include.NON_NULL);

// 日期格式化
mapper.setDateFormat(new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));

JsonNode 树模型

当 JSON 结构不固定或只需要部分字段时，使用树模型更灵活。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// 解析为树
JsonNode root = mapper.readTree(json);

// 获取字段值
String name = root.get("name").asText();
int age = root.get("age").asInt();
boolean active = root.get("active").asBoolean();

// 嵌套访问
String city = root.get("address").get("city").asText();

// 安全访问（避免 NPE）
String city = root.path("address").path("city").asText("默认值");

// 遍历数组
for (JsonNode item : root.get("items")) {
    System.out.println(item.get("id").asInt());
}

💡 提示: get vs path

  • get() 字段不存在时返回 null
  • path() 字段不存在时返回 MissingNode，可链式调用不会 NPE

常用注解

字段映射

1
2
3
4
5
6
7
8
9
10
public class User {
    @JsonProperty("user_name")  // JSON 字段名映射
    private String name;

    @JsonIgnore  // 忽略此字段
    private String password;

    @JsonAlias({"phone", "mobile"})  // 反序列化时接受多个名称
    private String telephone;
}

格式化

1
2
3
4
5
6
7
public class Order {
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss", timezone = "GMT+8")
    private LocalDateTime createTime;

    @JsonFormat(shape = JsonFormat.Shape.STRING)  // 数字转字符串
    private Long orderId;
}

空值处理

1
2
3
4
5
6
@JsonInclude(JsonInclude.Include.NON_NULL)  // 类级别：null 不序列化
public class Response {

    @JsonInclude(JsonInclude.Include.NON_EMPTY)  // 字段级别：空集合不序列化
    private List<String> tags;
}

构造器与工厂方法

1
2
3
4
5
6
7
8
9
10
11
12
13
public class User {
    private final String name;
    private final int age;

    @JsonCreator  // 指定反序列化使用的构造器
    public User(
        @JsonProperty("name") String name,
        @JsonProperty("age") int age
    ) {
        this.name = name;
        this.age = age;
    }
}

注解汇总

注解 作用 示例
@JsonProperty 字段名映射 @JsonProperty("user_name")
@JsonIgnore 忽略字段 密码等敏感字段
@JsonFormat 格式化 日期、数字格式
@JsonInclude 空值策略 NON_NULL、NON_EMPTY
@JsonCreator 构造器 不可变对象
@JsonAlias 别名 兼容多种字段名
@JsonValue 序列化值 枚举自定义输出

TypeReference 泛型处理

Java 泛型在运行时会被擦除，需要 TypeReference 保留类型信息。

1
2
3
4
5
6
7
8
9
10
11
// 错误：泛型被擦除，无法正确反序列化
List<User> users = mapper.readValue(json, List.class);  // 得到 List<LinkedHashMap>

// 正确：使用 TypeReference
List<User> users = mapper.readValue(json, new TypeReference<List<User>>() {});

// 嵌套泛型
Map<String, List<User>> data = mapper.readValue(
    json,
    new TypeReference<Map<String, List<User>>>() {}
);
Java > Jackson
#Jackson #JSON #序列化
Jackson依赖详解
https://zmmmmy.github.io/2026/01/15/Jackson依赖详解/
作者
ZhiMy
发布于
2026年1月15日
许可协议