README_EN.md

📖 English Documentation | 📖 中文文档

The issues of fastjson will be also posted on Alibaba Cloud Developer Community

FASTJSON v2

FASTJSON v2 is an upgrade of the FASTJSON, with the goal of providing a highly optimized JSON library for the next ten years.

• Supports the JSON and JSONB Protocols.
• Supports full parsing and partial parsing.
• Supports Java servers and Android Clients, and has big data applications.
• Supports Kotlin https://alibaba.github.io/fastjson2/kotlin_en
• Supports Android 8+
• Supports Graal Native-Image
• Supports JSON Schema https://alibaba.github.io/fastjson2/json_schema_cn

Related Documents:

• JSONB format documentation:
  https://alibaba.github.io/fastjson2/jsonb_format_cn
• FASTJSON v2's performance has been significantly improved. For the benchmark, see here:
  https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark

1. Prepare

1.1 Download

FASTJSONv2's groupId is different from versions 1.x, it is instead com.alibaba.fastjson2:

Maven:

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

Gradle:

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

Find the latest version of FASTJSONv2 at maven.org.

1.2 Other modules

Compatible dependence of fastjson-v1

If you are using fastjson 1.2.x, you can use the compatibility package. The compatibility package cannot guarantee 100% compatibility. Please test it yourself and report any problems.

Maven:

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

Gradle:

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

Kotlin integration module fastjson-kotlin

If your project uses kotlin, you can use the Fastjson-Kotlin module, and use the characteristics of kotlin.

Maven:

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

Add standard library(kotlin-stdlib) and reflection library(kotlin-reflect) as appropriate. If the data class is used or the parameters are passed in through constructor, then add reflection library.

<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.50")
}

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

Extension integration module fastjson-extension

If your project uses a framework such as SpringFramework, you can use the fastjson-extension module, please refer to the usage SpringFramework Support.

Maven:

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

Gradle:

dependencies {
    implementation 'com.alibaba.fastjson2:fastjson2-extension:2.0.50'
}

2. Usage

The package name of fastjson v2 is different from fastjson v1. It is com.alibaba.fastjson2. If you used fastjson v1 before, simply change the package name.

2.1 Parse JSON into JSONObject

Java:

String text = "...";
JSONObject data = JSON.parseObject(text);

byte[] bytes = ...;
JSONObject data = JSON.parseObject(bytes);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.parseObject()

val bytes = ... // ByteArray
val data = bytes.parseObject() // JSONObject

2.2 Parse JSON into JSONArray

Java:

String text = "...";
JSONArray data = JSON.parseArray(text);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.parseArray() // JSONArray

2.3 Parse JSON into a Java Object

Java:

String text = "...";
User data = JSON.parseObject(text, User.class);

Kotlin:

import com.alibaba.fastjson2.*

val text = ... // String
val data = text.to<User>() // User
val data = text.parseObject<User>() // User

2.4 Serialization Java Object to JSON

Java:

Object data = "...";
String text = JSON.toJSONString(data);
byte[] text = JSON.toJSONBytes(data);

Kotlin:

import com.alibaba.fastjson2.*

val data = ... // Any
val text = text.toJSONString() // String
val bytes = text.toJSONByteArray() // ByteArray

2.5 Use JSONObject, JSONArray

2.5.1 Get simple property

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

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 to JavaBean

Java:

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

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

Kotlin:

val array = ... // JSONArray
val obj = ... // JSONObject

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()
user.id = 2
user.name = "FastJson2"

val text = user.toJSONString() // String
val bytes = user.toJSONByteArray() // ByteArray

Serialization result:

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

3. Advanced usage

3.1 Use JSONB

3.1.1 Serialize JavaBean to JSONB

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

3.1.2 Parse JSONB to JavaBean

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

3.2 Use JSONPath

3.2.1 Use JSONPath to read partial data

String text = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

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

3.2.2 Read part of byte[] data using JSONPath

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

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

3.2.3 Read part of byte[] data using JSONPath

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cached for reuse

JSONReader parser = JSONReader.ofJSONB(bytes); // Use ofJSONB method
Object result = path.extract(parser);