Language: English | 中文

FASTJSON 2

FASTJSON 2 is a high-performance JSON library for Java, designed as the next-generation successor to FASTJSON with a goal of providing an optimized JSON solution for the next ten years.

Highlights

• Blazing Fast - Significantly outperforms Jackson, Gson, and org.json. Benchmarks
• Dual Format - Native support for both JSON (text) and JSONB (binary) protocols
• Full & Partial Parsing - Complete document parsing or selective extraction via JSONPath (SQL:2016 compatible)
• Modern Java - Optimized for JDK 8/11/17/21 with compact string, Record, and Vector API support
• Multi-Platform - Works on Java servers, Android 8+ clients, and big data pipelines
• Kotlin Native - First-class Kotlin extensions with idiomatic DSL-style API
• JSON Schema - Built-in validation support with high performance
• Secure by Default - AutoType disabled by default; no hardcoded whitelist; SafeMode support
• GraalVM Ready - Compatible with GraalVM Native Image

Table of Contents

• Quick Start
• Installation
  • Core Library
  • Fastjson v1 Compatibility
  • Kotlin Module
  • Spring Integration
• Basic Usage
  • Parse JSON to JSONObject
  • Parse JSON to JSONArray
  • Parse JSON to Java Object
  • Serialize to JSON
  • JSONObject & JSONArray
  • Serialize JavaBean
• Advanced Usage
  • JSONB Binary Format
  • JSONPath
  • Features Configuration
  • Annotations
  • Custom Serializer/Deserializer
  • Filters
• Upgrading from Fastjson 1.x
• Documentation
• Contributing

Quick Start

Add the dependency and start parsing JSON in seconds:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.61</version>
</dependency>

import com.alibaba.fastjson2.JSON;

// Parse
User user = JSON.parseObject("{\"name\":\"John\",\"age\":25}", User.class);

// Serialize
String json = JSON.toJSONString(user);

1. Installation

1.1 Core Library

The groupId for FASTJSON 2 is com.alibaba.fastjson2 (different from 1.x):

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba.fastjson2:fastjson2:2.0.61'
}

Find the latest version on Maven Central.

1.2 Fastjson v1 Compatibility Module

If you are migrating from fastjson 1.2.x, you can use the compatibility package as a drop-in replacement. Note that 100% compatibility is not guaranteed - please test thoroughly and report issues.

Maven:

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba:fastjson:2.0.61'
}

1.3 Kotlin Module

For projects using Kotlin, the fastjson2-kotlin module provides idiomatic Kotlin extensions:

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>2.0.61</version>
</dependency>

Add the Kotlin standard library and reflection library as needed. The reflection library is required when using data classes or constructor-based parameter passing:

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-stdlib</artifactId>
    <version>${kotlin-version}</version>
</dependency>

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-reflect</artifactId>
    <version>${kotlin-version}</version>
</dependency>

Kotlin Gradle:

dependencies {
    implementation("com.alibaba.fastjson2:fastjson2-kotlin:2.0.61")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
    implementation("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
}

1.4 Spring Framework Integration

For Spring Framework projects, use the appropriate extension module. See the full Spring Integration Guide for details.

Maven (Spring 5.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring5</artifactId>
    <version>2.0.61</version>
</dependency>

Maven (Spring 6.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring6</artifactId>
    <version>2.0.61</version>
</dependency>

Gradle:

dependencies {
    // Choose one based on your Spring version:
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring5:2.0.61'
    // or
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring6:2.0.61'
}

2. Basic Usage

The package name for FASTJSON 2 is com.alibaba.fastjson2. If upgrading from v1, simply update the package imports.

2.1 Parse JSON to JSONObject

Java:

String text = "{\"id\":1,\"name\":\"fastjson2\"}";
JSONObject data = JSON.parseObject(text);

byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
JSONObject data = JSON.parseObject(bytes);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"fastjson2"}"""
val data = text.parseObject()

val bytes: ByteArray = text.toByteArray()
val data = bytes.parseObject() // JSONObject

2.2 Parse JSON to JSONArray

Java:

String text = "[{\"id\":1},{\"id\":2}]";
JSONArray data = JSON.parseArray(text);

Kotlin:

import com.alibaba.fastjson2.*

val text = """[{"id":1},{"id":2}]"""
val data = text.parseArray() // JSONArray

2.3 Parse JSON to Java Object

Java:

String text = "{\"id\":1,\"name\":\"John\"}";
User user = JSON.parseObject(text, User.class);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"John"}"""
val user = text.to<User>()          // User
val user = text.parseObject<User>() // User (alternative)

2.4 Serialize Java Object to JSON

Java:

User user = new User(1, "John");
String text = JSON.toJSONString(user);   // String output
byte[] bytes = JSON.toJSONBytes(user);   // byte[] output

Kotlin:

import com.alibaba.fastjson2.*

val user = User(1, "John")
val text = user.toJSONString()      // String
val bytes = user.toJSONByteArray()  // ByteArray

2.5 Working with JSONObject and JSONArray

2.5.1 Get Simple Properties

String text = "{\"id\": 2, \"name\": \"fastjson2\"}";
JSONObject obj = JSON.parseObject(text);

int id = obj.getIntValue("id");
String name = obj.getString("name");

String text = "[2, \"fastjson2\"]";
JSONArray array = JSON.parseArray(text);

int id = array.getIntValue(0);
String name = array.getString(1);

2.5.2 Get JavaBean from JSON Containers

Java:

JSONArray array = ...;
JSONObject obj = ...;

User user