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 CODEOF_CONDUCT.md for community guidelines
• See SECURITY.md for reporting security vulnerabilities

Star History