GitHub - re-thc/fastjson2: 🚄 FASTJSON2 is a Java JSON library with excellent performance.

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

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 = array.getObject(0, User.class);
User user = obj.getObject("key", User.class);

Kotlin:

val array: JSONArray = ...
val obj: JSONObject = ...

val user = array.to<User>(0)
val user = obj.to<User>("key")

2.5.3 Convert JSONObject/JSONArray to JavaBean

Java:

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

User user = obj.toJavaObject(User.class);
List<User> users = array.toJavaList(User.class);

Kotlin:

val obj: JSONObject = ...
val array: JSONArray = ...

val user = obj.to<User>()           // User
val users = array.toList<User>()    // List<User>

2.6 Serialize JavaBean to JSON

Java:

class User {
    public int id;
    public String name;
}

User user = new User();
user.id = 2;
user.name = "FastJson2";

String text = JSON.toJSONString(user);
byte[] bytes = JSON.toJSONBytes(user);

Kotlin:

class User(
    var id: Int,
    var name: String
)

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

Output:

{"id":2,"name":"FastJson2"}

3. Advanced Usage

3.1 JSONB Binary Format

JSONB is a high-performance binary JSON format that provides significantly faster serialization/deserialization and smaller payload sizes. See the JSONB Format Specification.

Serialize to JSONB

User user = ...;
byte[] bytes = JSONB.toBytes(user);
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray); // Even more compact

Parse JSONB

byte[] bytes = ...;
User user = JSONB.parseObject(bytes, User.class);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportArrayToBean);

3.2 JSONPath

JSONPath enables partial parsing of JSON documents without full deserialization, which is ideal for extracting specific fields from large payloads. FASTJSON 2 implements SQL:2016 JSONPath syntax.

Extract from String

String text = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.of(text);
Object result = path.extract(parser);

Extract from byte[]

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.of(bytes);
Object result = path.extract(parser);

Extract from JSONB byte[]

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.ofJSONB(bytes); // Note: use ofJSONB method
Object result = path.extract(parser);

See the full JSONPath Documentation for filter expressions, aggregate functions, array slicing, and more.

3.3 Features Configuration

FASTJSON 2 provides fine-grained control over serialization and deserialization behavior through JSONWriter.Feature and JSONReader.Feature. All features are OFF by default.

// Serialization with features
String json = JSON.toJSONString(user,
    JSONWriter.Feature.WriteNulls,
    JSONWriter.Feature.PrettyFormat);

// Deserialization with features
User user = JSON.parseObject(json, User.class,
    JSONReader.Feature.SupportSmartMatch);

See the full Features Reference for all available options and migration mapping from fastjson 1.x.

3.4 Annotations

Use @JSONField and @JSONType to customize serialization/deserialization behavior:

public class User {
    @JSONField(name = "user_name", ordinal = 1)
    public String name;

    @JSONField(format = "yyyy-MM-dd", ordinal = 2)
    public Date birthday;

    @JSONField(serialize = false)
    public String password;
}

See the full Annotations Guide.

3.5 Custom Serializer/Deserializer

Implement ObjectWriter<T> or ObjectReader<T> for custom serialization logic:

// Custom writer
class MoneyWriter implements ObjectWriter<Money> {
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features) {
        Money money = (Money) object;
        jsonWriter.writeString(money.getCurrency() + " " + money.getAmount());
    }
}

// Register
JSON.register(Money.class, new MoneyWriter());

See the full Custom Reader/Writer Guide.

3.6 Filters

FASTJSON 2 provides a comprehensive filter system for serialization:

Filter	Purpose
`ValueFilter`	Transform property values
`NameFilter`	Rename properties
`PropertyFilter`	Include/exclude properties conditionally
`AfterFilter` / `BeforeFilter`	Inject additional content
`LabelFilter`	Scenario-based serialization
`ContextValueFilter` / `ContextNameFilter`	Context-aware transformations

See the full Filter Documentation.

4. Upgrading from Fastjson 1.x

FASTJSON 2 provides both a compatibility mode (drop-in replacement) and a new API mode for upgrading. Key changes:

Aspect	Fastjson 1.x	Fastjson 2.x
Package	`com.alibaba.fastjson`	`com.alibaba.fastjson2`
GroupId	`com.alibaba`	`com.alibaba.fastjson2`
AutoType	Enabled with whitelist	Disabled by default (more secure)
Circular Reference	Detected by default	Not detected by default
Smart Match	On by default	Off by default
Default Features	Multiple features on	All features off

See the full Migration Guide for step-by-step instructions, API mapping table, and common issues.

5. Documentation

Core References

Document	Description
Features Reference	Complete list of JSONReader/JSONWriter features
Annotations Guide	@JSONField, @JSONType, @JSONCreator usage
Architecture	Internal architecture, design patterns, and class hierarchy
FAQ	Frequently asked questions and troubleshooting

Format & Protocol

Document	Description
JSONB Format	Binary JSON format specification
JSONB vs Hessian/Kryo	Performance comparison with other binary formats
JSONB Size Comparison	Payload size comparison
CSV Support	CSV reading and writing support

JSONPath

Document	Description
JSONPath Guide	Syntax, operators, and examples
Multi-value JSONPath	Multi-value extraction
Typed JSONPath	Type-safe JSONPath extraction
JSONPath Benchmark	Performance data

Integrations

Document	Description
Spring Support	Spring MVC, WebFlux, Data Redis, Messaging
Kotlin Extensions	Kotlin API and DSL
Android Support	Android 8+ integration

Customization

Document	Description
Custom Reader/Writer	Implement ObjectReader/ObjectWriter
MixIn Annotations	Inject annotations on third-party classes
AutoType Security	AutoType mechanism and security configuration
JSON Schema	Schema validation
Filter System	Serialization filters

Migration & Performance

Document	Description
v1 to v2 Migration	Upgrade guide with API mapping
Performance Guide	Tuning tips and best practices
Benchmarks	Comprehensive benchmark results

6. Contributing

We welcome contributions of all kinds - bug reports, feature requests, documentation improvements, and code contributions.

See CONTRIBUTING.md for development setup, coding standards, and the pull request process
See CODE_OF_CONDUCT.md for community guidelines
See SECURITY.md for reporting security vulnerabilities

Language: English | 中文

FASTJSON 2

Highlights

Table of Contents

Quick Start

1. Installation

1.1 Core Library

1.2 Fastjson v1 Compatibility Module

1.3 Kotlin Module

1.4 Spring Framework Integration

2. Basic Usage

2.1 Parse JSON to JSONObject

2.2 Parse JSON to JSONArray

2.3 Parse JSON to Java Object

2.4 Serialize Java Object to JSON

2.5 Working with JSONObject and JSONArray

2.5.1 Get Simple Properties

2.5.2 Get JavaBean from JSON Containers

2.5.3 Convert JSONObject/JSONArray to JavaBean

2.6 Serialize JavaBean to JSON

3. Advanced Usage

3.1 JSONB Binary Format

Serialize to JSONB

Parse JSONB

3.2 JSONPath

Extract from String

Extract from byte[]

Extract from JSONB byte[]

3.3 Features Configuration

3.4 Annotations

3.5 Custom Serializer/Deserializer

3.6 Filters

4. Upgrading from Fastjson 1.x

5. Documentation

Core References

Format & Protocol

JSONPath

Integrations

Customization

Migration & Performance

6. Contributing

Star History

2.1 Parse JSON to `JSONObject`

2.2 Parse JSON to `JSONArray`

2.5 Working with `JSONObject` and `JSONArray`