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 = 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

Star History