FastJson 完全学习指南（初学者从零入门）

一、JSON 数据格式基础

1.1 什么是 JSON？

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式，它基于 ECMAScript 规范，采用文本格式存储和表示数据。其核心特点是：

简洁清晰：层次结构明确，易于人类阅读和编写
跨语言：独立于编程语言，几乎所有编程语言都支持 JSON 解析
高效传输：文本格式体积小，适合网络传输

目前，JSON 已成为前后端数据交互、接口通信的主流格式。

1.2 JSON 基本格式

1.2.1 JSON 键值对规则

键必须是字符串，且必须用双引号 "" 包裹（单引号不合法）
值可以是以下类型：字符串、数字、布尔值（true/false）、null、数组、对象
键值对之间用逗号 , 分隔（最后一个键值对后不能有逗号）

1.2.2 JSON 数组（Array）

由中括号 [] 包裹，元素之间用逗号分隔，元素类型可以是任意 JSON 支持的类型。

示例：

// 数组元素为字符串
["张三", "李四", "王五"]

// 数组元素为混合类型
[18, "张三", true, null, {
   "score": 90}]

访问方式（以 JavaScript 为例）：

var arr = [18, "张三", true];
console.log(arr[0]); // 输出：18（访问第一个元素）
console.log(arr.length); // 输出：3（数组长度）

1.2.3 JSON 对象（Object）

由大括号 {} 包裹，采用键值对 key:value 形式存储。

示例：

{
   
  "id": 1,
  "name": "张三",
  "age": 20,
  "isStudent": true,
  "address": null
}

访问方式（以 JavaScript 为例）：

var obj = {
   "id": 1, "name": "张三"};
console.log(obj.name); // 输出：张三（通过键访问值）
console.log(obj["age"]); // 输出：undefined（键不存在时）

1.2.4 嵌套格式（数组与对象混合）

JSON 支持数组和对象相互嵌套，形成复杂结构。

示例 1：数组中的元素是对象

[
  {
   "id": 1, "name": "张三"},
  {
   "id": 2, "name": "李四"}
]

访问方式：arr[0].name → 输出 "张三"

示例 2：对象中的值是数组

{
   
  "className": "高三(1)班",
  "students": [
    {
   "id": 1, "name": "张三"},
    {
   "id": 2, "name": "李四"}
  ]
}

访问方式：obj.students[1].id → 输出 2

示例 3：多层嵌套

{
   
  "school": "第一中学",
  "grades": [
    {
   
      "gradeName": "高三",
      "classes": [
        {
   "className": "一班", "studentCount": 50},
        {
   "className": "二班", "studentCount": 48}
      ]
    }
  ]
}

访问方式：obj.grades[0].classes[0].className → 输出 "一班"

二、FastJson 介绍

2.1 什么是 FastJson？

FastJson 是阿里巴巴开源的 JSON 解析库，主要功能是：

将 Java 对象序列化为 JSON 字符串（Java → JSON）
将 JSON 字符串反序列化为 Java 对象（JSON → Java）

2.2 FastJson 的优势

速度快：性能远超其他 Java JSON 库（如 Jackson、Gson）
功能全：支持泛型、日期格式化、枚举、流处理等
使用简单：API 简洁，一行代码即可完成序列化/反序列化
兼容性好：广泛应用于阿里巴巴内部及业界，支持各种复杂场景

2.3 环境搭建（引入依赖）

Maven 项目

在 pom.xml 中添加依赖：

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>1.2.83</version> <!-- 推荐使用较新版本，修复安全漏洞 -->
</dependency>

Gradle 项目

在 build.gradle 中添加依赖：

implementation 'com.alibaba:fastjson:1.2.83'

三、FastJson 核心 API 详解

3.1 序列化（Java → JSON）

序列化是将 Java 对象转换为 JSON 字符串的过程，核心方法：JSON.toJSONString(Object obj)

3.1.1 序列化 Java 对象

步骤：

定义 Java 实体类（如 Student）
创建对象并赋值
调用 JSON.toJSONString() 方法

示例：

// 1. 定义实体类
import lombok.Data; // 使用 lombok 简化 getter/setter
@Data
public class Student {
   
    private Integer id;
    private String name;
    private Integer age;
    private String address;
}

// 2. 序列化示例
public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        // 创建对象
        Student student = new Student();
        student.setId(1);
        student.setName("张三");
        student.setAge(20);
        student.setAddress("北京市");

        // 序列化
        String jsonString = JSON.toJSONString(student);
        System.out.println(jsonString);
        // 输出：{"address":"北京市","age":20,"id":1,"name":"张三"}
    }
}

3.1.2 序列化 List 集合

示例：

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        // 创建多个对象
        Student s1 = new Student();
        s1.setId(1);
        s1.setName("张三");
        s1.setAge(20);

        Student s2 = new Student();
        s2.setId(2);
        s2.setName("李四");
        s2.setAge(21);

        // 存入 List
        List<Student> studentList = new ArrayList<>();
        studentList.add(s1);
        studentList.add(s2);

        // 序列化 List
        String jsonString = JSON.toJSONString(studentList);
        System.out.println(jsonString);
        // 输出：[{"age":20,"id":1,"name":"张三"},{"age":21,"id":2,"name":"李四"}]
    }
}

3.1.3 序列化 Map 集合

示例：

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        Student s1 = new Student();
        s1.setId(1);
        s1.setName("张三");

        Student s2 = new Student();
        s2.setId(2);
        s2.setName("李四");

        // 创建 Map
        Map<String, Student> studentMap = new HashMap<>();
        studentMap.put("s1", s1);
        studentMap.put("s2", s2);

        // 序列化 Map
        String jsonString = JSON.toJSONString(studentMap);
        System.out.println(jsonString);
        // 输出：{"s1":{"id":1,"name":"张三"},"s2":{"id":2,"name":"李四"}}
    }
}

3.2 反序列化（JSON → Java）

反序列化是将 JSON 字符串转换为 Java 对象的过程，核心方法：

转换为对象：JSON.parseObject(String json, Class<T> clazz)
转换为 List：JSON.parseArray(String json, Class<T> clazz)
转换为 Map：JSON.parseObject(String json, TypeReference<T> type)

3.2.1 反序列化为 Java 对象

示例：

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        // JSON 字符串
        String jsonString = "{\"address\":\"北京市\",\"age\":20,\"id\":1,\"name\":\"张三\"}";

        // 反序列化
        Student student = JSON.parseObject(jsonString, Student.class);
        System.out.println(student.getName()); // 输出：张三
        System.out.println(student.getAge()); // 输出：20
    }
}

3.2.2 反序列化为 List 集合

示例：

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        // JSON 数组字符串
        String jsonString = "[{\"age\":20,\"id\":1,\"name\":\"张三\"},{\"age\":21,\"id\":2,\"name\":\"李四\"}]";

        // 反序列化为 List
        List<Student> studentList = JSON.parseArray(jsonString, Student.class);
        for (Student s : studentList) {
   
            System.out.println(s.getName());
        }
        // 输出：
        // 张三
        // 李四
    }
}

3.2.3 反序列化为 Map 集合

示例：

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        // JSON 字符串（键为字符串，值为对象）
        String jsonString = "{\"s1\":{\"id\":1,\"name\":\"张三\"},\"s2\":{\"id\":2,\"name\":\"李四\"}}";

        // 反序列化为 Map（使用 TypeReference 处理泛型）
        Map<String, Student> studentMap = JSON.parseObject(
            jsonString, 
            new TypeReference<Map<String, Student>>() {
   }
        );

        // 遍历 Map
        for (Map.Entry<String, Student> entry : studentMap.entrySet()) {
   
            System.out.println(entry.getKey() + " → " + entry.getValue().getName());
        }
        // 输出：
        // s1 → 张三
        // s2 → 李四
    }
}

四、SerializerFeature 序列化特性

SerializerFeature 是 FastJson 提供的枚举类，用于定制序列化行为（如处理 null、格式化日期等）。

常用特性及示例

特性常量	作用描述
WriteMapNullValue	序列化 null 字段（默认不序列化 null）
WriteNullStringAsEmpty	null 字符串字段序列化为空字符串 `""`
WriteNullNumberAsZero	null 数字字段序列化为 0
WriteNullBooleanAsFalse	null 布尔字段序列化为 false
WriteDateUseDateFormat	格式化日期（默认毫秒数，可自定义格式）
PrettyFormat	格式化输出（带缩进和换行，便于阅读）

示例 1：序列化 null 字段

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        Student student = new Student();
        student.setId(1);
        student.setName("张三");
        // age 和 address 未赋值（为 null）

        // 默认序列化（不包含 null 字段）
        String defaultJson = JSON.toJSONString(student);
        System.out.println("默认：" + defaultJson); 
        // 输出：{"id":1,"name":"张三"}

        // 序列化 null 字段
        String withNullJson = JSON.toJSONString(student, SerializerFeature.WriteMapNullValue);
        System.out.println("包含 null：" + withNullJson); 
        // 输出：{"address":null,"age":null,"id":1,"name":"张三"}
    }
}

示例 2：处理 null 字段为默认值

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        Student student = new Student();
        student.setId(1);
        // name、age、address 为 null

        // null 字符串→""，null 数字→0
        String json = JSON.toJSONString(
            student,
            SerializerFeature.WriteNullStringAsEmpty,
            SerializerFeature.WriteNullNumberAsZero
        );
        System.out.println(json); 
        // 输出：{"address":"","age":0,"id":1,"name":""}
    }
}

示例 3：日期格式化

import java.util.Date;

@Data
public class User {
   
    private String name;
    private Date birthday; // 日期字段
}

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        User user = new User();
        user.setName("张三");
        user.setBirthday(new Date()); // 当前时间

        // 默认日期格式（毫秒数）
        String defaultJson = JSON.toJSONString(user);
        System.out.println("默认日期：" + defaultJson); 
        // 输出：{"birthday":1695670000000,"name":"张三"}

        // 格式化日期为 "yyyy-MM-dd HH:mm:ss"
        String formatJson = JSON.toJSONString(
            user,
            SerializerFeature.WriteDateUseDateFormat
        );
        System.out.println("格式化日期：" + formatJson); 
        // 输出：{"birthday":"2023-09-25 10:20:30","name":"张三"}
    }
}

示例 4：格式化输出（PrettyFormat）

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        Student student = new Student();
        student.setId(1);
        student.setName("张三");
        student.setAge(20);

        // 格式化输出（带缩进）
        String prettyJson = JSON.toJSONString(student, SerializerFeature.PrettyFormat);
        System.out.println(prettyJson);
        // 输出：
        // {
   
        //     "age":20,
        //     "id":1,
        //     "name":"张三"
        // }
    }
}

五、FastJson 注解详解

FastJson 提供了注解用于定制类或字段的序列化/反序列化规则，常用注解：@JSONField（作用于字段/方法）和 @JSONType（作用于类）。

5.1 @JSONField 注解

常用属性：

属性名	作用描述
name	指定序列化后的字段名（解决命名不一致问题）
format	字段格式化（如日期格式）
serialize	是否序列化该字段（true/false）
deserialize	是否反序列化该字段（true/false）
ordinal	序列化时的字段顺序（值越小越靠前）

示例：

import com.alibaba.fastjson.annotation.JSONField;
import java.util.Date;

@Data
public class User {
   
    // 序列化后字段名为 "userId"
    @JSONField(name = "userId")
    private Integer id;

    // 不序列化该字段
    @JSONField(serialize = false)
    private String password;

    // 日期格式化
    @JSONField(format = "yyyy年MM月dd日")
    private Date birthday;

    // 序列化顺序（1 比 2 靠前）
    @JSONField(ordinal = 1)
    private String name;

    @JSONField(ordinal = 2)
    private Integer age;
}

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(20);
        user.setPassword("123456"); // 不序列化
        user.setBirthday(new Date());

        String json = JSON.toJSONString(user);
        System.out.println(json);
        // 输出：{"userId":1,"name":"张三","age":20,"birthday":"2023年09月25日"}
    }
}

5.2 @JSONType 注解

作用于类上，对整个类的序列化/反序列化进行全局配置。

常用属性：

属性名	作用描述
includes	指定需要序列化的字段（仅这些字段被序列化）
orders	指定字段序列化顺序（数组形式，按顺序排列）
serializeFeatures	全局序列化特性（如默认格式化日期）

示例：

import com.alibaba.fastjson.annotation.JSONType;
import com.alibaba.fastjson.serializer.SerializerFeature;

// 仅序列化 id 和 name，且按 [name, id] 顺序，默认格式化日期
@JSONType(
    includes = {
   "id", "name"},
    orders = {
   "name", "id"},
    serializeFeatures = SerializerFeature.WriteDateUseDateFormat
)
@Data
public class User {
   
    private Integer id;
    private String name;
    private Integer age; // 不被序列化（未在 includes 中）
    private Date birthday;
}

public class FastJsonDemo {
   
    public static void main(String[] args) {
   
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(20); // 不序列化
        user.setBirthday(new Date());

        String json = JSON.toJSONString(user);
        System.out.println(json);
        // 输出：{"name":"张三","id":1,"birthday":"2023-09-25 10:30:40"}
    }
}

六、Spring Boot 集成 FastJson

Spring Boot 默认使用 Jackson 作为 JSON 解析器，如需替换为 FastJson，步骤如下：

6.1 环境准备

创建 Spring Boot 项目（需引入 spring-boot-starter-web 依赖）
在 pom.xml 中添加 FastJson 依赖（同 2.3 节）

6.2 配置 FastJson 为默认解析器

通过配置 HttpMessageConverter 替换默认解析器。

步骤：

创建配置类（标注 @Configuration）
实现 WebMvcConfigurer 接口
重写 configureMessageConverters 方法，注册 FastJson 消息转换器

示例代码：

import com.alibaba.fastjson.serializer.SerializerFeature;
import com.alibaba.fastjson.support.config.FastJsonConfig;
import com.alibaba.fastjson.support.spring.FastJsonHttpMessageConverter;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.MediaType;
import org.springframework.http.converter.HttpMessageConverter;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import java.nio.charset.StandardCharsets;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class FastJsonConfig implements WebMvcConfigurer {
   

    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
   
        // 1. 创建 FastJson 消息转换器
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();

        // 2. 配置 FastJson 特性
        FastJsonConfig fastJsonConfig = new FastJsonConfig();
        // 序列化 null 字段
        fastJsonConfig.setSerializerFeatures(SerializerFeature.WriteMapNullValue);
        // 格式化日期
        fastJsonConfig.setSerializerFeatures(SerializerFeature.WriteDateUseDateFormat);
        // 格式化输出（开发环境用，生产环境建议关闭）
        fastJsonConfig.setSerializerFeatures(SerializerFeature.PrettyFormat);

        // 设置字符集
        fastJsonConfig.setCharset(StandardCharsets.UTF_8);

        // 3. 配置支持的媒体类型（解决中文乱码）
        List<MediaType> mediaTypes = new ArrayList<>();
        mediaTypes.add(MediaType.APPLICATION_JSON);
        mediaTypes.add(MediaType.APPLICATION_JSON_UTF8);
        converter.setSupportedMediaTypes(mediaTypes);

        // 4. 将配置添加到转换器
        converter.setFastJsonConfig(fastJsonConfig);

        // 5. 将转换器添加到容器（放在首位，优先使用）
        converters.add(0, converter);
    }
}

6.3 测试集成效果

创建一个 Controller 测试接口返回 JSON 格式：

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Date;

@RestController
public class TestController {
   

    @GetMapping("/user")
    public User getUser() {
   
        User user = new User();
        user.setId(1);
        user.setName("张三");
        user.setAge(null); // 测试 null 字段序列化
        user.setBirthday(new Date()); // 测试日期格式化
        return user;
    }
}

启动项目后访问 http://localhost:8080/user，返回结果：

{
   
    "userId": 1,
    "name": "张三",
    "age": null,
    "birthday": "2023-09-25 11:00:00"
}

（结果说明：FastJson 已生效，null 字段被序列化，日期已格式化）

七、常见问题与解决方案

问题：序列化后字段名与 Java 类字段名不一致？
解决：使用 @JSONField(name = "目标字段名") 注解指定。
问题：null 字段未被序列化？
解决：添加特性 SerializerFeature.WriteMapNullValue。
问题：日期字段显示为毫秒数而非字符串？
解决：添加特性 SerializerFeature.WriteDateUseDateFormat 或使用 @JSONField(format = "格式")。
问题：反序列化时提示“无参构造函数不存在”？
解决：确保 Java 类有默认无参构造函数（Lombok 的 @Data 会自动生成）。
问题：Spring Boot 集成后中文乱码？
解决：在配置消息转换器时指定 UTF-8 字符集（如 6.2 节示例）。

通过本文档，初学者可从零掌握 FastJson 的核心用法，包括 JSON 基础、序列化/反序列化、特性定制、注解使用及 Spring Boot 集成，满足日常开发中的 JSON 处理需求。

探索云世界

热门

云计算

大数据

云原生

人工智能

数据库

开发与运维

活动广场

任务中心

训练营

直播

乘风者计划

下载

镜像站

技术资料

FastJson 完全学习指南（初学者从零入门）

FastJson 完全学习指南（初学者从零入门）

一、JSON 数据格式基础

1.1 什么是 JSON？

1.2 JSON 基本格式

1.2.1 JSON 键值对规则

1.2.2 JSON 数组（Array）

1.2.3 JSON 对象（Object）

1.2.4 嵌套格式（数组与对象混合）

二、FastJson 介绍

2.1 什么是 FastJson？

2.2 FastJson 的优势

2.3 环境搭建（引入依赖）

Maven 项目

Gradle 项目

三、FastJson 核心 API 详解

3.1 序列化（Java → JSON）

3.1.1 序列化 Java 对象

3.1.2 序列化 List 集合

3.1.3 序列化 Map 集合

3.2 反序列化（JSON → Java）

3.2.1 反序列化为 Java 对象

3.2.2 反序列化为 List 集合

3.2.3 反序列化为 Map 集合

四、SerializerFeature 序列化特性

常用特性及示例

示例 1：序列化 null 字段

示例 2：处理 null 字段为默认值

示例 3：日期格式化

示例 4：格式化输出（PrettyFormat）

五、FastJson 注解详解

5.1 @JSONField 注解

常用属性：

示例：

5.2 @JSONType 注解

常用属性：

示例：

六、Spring Boot 集成 FastJson

6.1 环境准备

6.2 配置 FastJson 为默认解析器

6.3 测试集成效果

七、常见问题与解决方案

热门文章

最新文章

相关电子书