fastjson2 Documentation

Technical Documentation: alibaba/fastjson2

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Language: English | [中文](README_cn.md)

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 Copy Chapter

• 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 Copy Chapter

• 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 Copy Chapter

Add the dependency and start parsing JSON in seconds:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.66</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 Copy Chapter

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.66</version>
</dependency>

Gradle:

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

Find the latest version on Maven Central.

1.2 Fastjson v1 Compatibility Module Copy Chapter

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.66</version>
</dependency>

Gradle:

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

1.3 Kotlin Module Copy Chapter

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.66</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.66")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
    implementation("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
}

1.4 Spring Framework Integration Copy Chapter

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.66</version>
</dependency>

Maven (Spring 6.x):

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

Gradle:

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

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` Copy Chapter

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` Copy Chapter

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 Copy Chapter

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 Copy Chapter

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` Copy Chapter

2.5.1 Get Simple Properties Copy Section

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 Copy Section

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 Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Section

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

Parse JSONB Copy Section

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

3.2 JSONPath Copy Chapter

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 Copy Section

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[] Copy Section

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[] Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

FASTJSON 2 provides a comprehensive filter system for serialization:

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:

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

5. Documentation

Core References Copy Chapter

Format & Protocol Copy Chapter

JSONPath Copy Chapter

Integrations Copy Chapter

Customization Copy Chapter

Migration & Performance Copy Chapter

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 Copy Chapter

Overview (`example-solon-test/README.md`) Copy Section

启动方式 Copy Section

运行 SolonTestApp.main 方法（或者直接运行单测 DemoTest ）

测试 Copy Section

测试 Render 是否正常工作

• 访问：http://localhost:8080/demo?username=world&password=1234

测试 找不到的地址异常（技术上和上面一样，Solon 所有的 Web 输出都会走：Render 接口）

• 访问：http://localhost:8080/error

说明 Copy Section

此演示，会自动触发 fastjson2-extension-solon 的:

• Fastjson2RenderFactory
• Fastjson2ActionExecutor

Overview (`example-spring-test/README.md`) Copy Section

启动方式 Copy Section

运行SpringTestApplication.main方法即可

测试 Copy Section

访问http://localhost:8080/test?username=123&password=456，测试HttpMessageConverter是否正常工作。
访问http://localhost:8080/hello进入一个聊天页面，测试websocket是否正常工作。
访问任意找不到的地址，即可测试FastJsonJsonView，错误页面已经使用FastJsonJsonView。

Overview (`example-spring6-test/README.md`) Copy Section

启动方式 Copy Section

运行SpringTestApplication.main方法即可

测试 Copy Section

访问http://localhost:8080/test?username=123&password=456，测试HttpMessageConverter是否正常工作。
访问http://localhost:8080/hello进入一个聊天页面，测试websocket是否正常工作。
访问任意找不到的地址，即可测试FastJsonJsonView，错误页面已经使用FastJsonJsonView。

Index (`docs/index.md`) Copy Section

0. FASTJSON 2.0介绍

FASTJSON v2是FASTJSON项目的重要升级，目标是为下一个十年提供一个高性能的JSON库。通过同一套API，

• 支持JSON/JSONB两种协议，JSONPath 是一等公民。
• 支持全量解析和部分解析。
• 支持Java服务端、客户端Android、大数据场景。
• 支持Kotlin
• 支持JSON Schema https://alibaba.github.io/fastjson2/JSONSchema/json_schema_cn
• 支持Android
• 支持Graal Native-Image

相关文档：

• JSONB格式文档：
  https://alibaba.github.io/fastjson2/JSONB/jsonb_format_cn
• FASTJSON v2性能有了很大提升，具体性能数据看这里：
  https://alibaba.github.io/fastjson2/benchmark_cn

1. 使用准备

1.1 添加依赖 Copy Chapter

在fastjson v2中，groupId和1.x不一样，是com.alibaba.fastjson2：

Maven:

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

Gradle:

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

可以在 maven.org 查看最新可用的版本。

1.2 其他模块 Copy Chapter

`Fastjson v1`兼容模块 Copy Section

如果原来使用fastjson 1.2.x版本，可以使用兼容包，兼容包不能保证100%兼容，请仔细测试验证，发现问题请及时反馈。

Maven:

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

Gradle:

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

`Fastjson Kotlin`集成模块 Copy Section

如果项目使用Kotlin，可以使用fastjson-kotlin模块，使用方式上采用kotlin的特性。

Maven:

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

Gradle:

dependencies {
    implementation("com.alibaba.fastjson2:fastjson2-kotlin:2.0.66")
}

`Fastjson Extension`扩展模块 Copy Section

如果项目使用SpringFramework等框架，可以使用fastjson-extension模块，使用方式参考 SpringFramework Support。

Maven:

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

Gradle:

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

2 简单使用

在fastjson v2中，package和1.x不一样，是com.alibaba.fastjson2。如果你之前用的是fastjson1，大多数情况直接更包名就即可。

2.1 将`JSON`解析为`JSONObject` Copy Section

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 将`JSON`解析为`JSONArray` Copy Section

Java:

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

Kotlin:

import com.alibaba.fastjson2.*

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

2.3 将`JSON`解析为`Java`对象 Copy Section

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 将`Java`对象序列化为`JSON` Copy Section

Java:

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

Kotlin:

import com.alibaba.fastjson2.*

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

2.5 使用`JSONObject`、`JSONArray` Copy Section

2.5.1 获取简单属性

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 读取`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.getObject<User>(0)
val user = obj.getObject<User>("key")

2.5.3 转为`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.toObject<User>() // User
val users = array.toList<User>() // List<User>

2.6 将`JavaBean`对象序列化为`JSON` Copy Section

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

序列化结果:

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

3. 进阶使用

3.1 使用`JSONB` Copy Section

3.1.1 将`JavaBean`对象序列化`JSONB`

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

3.1.2 将`JSONB`数据解析为`JavaBean`

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

3.2 使用`JSONPath` Copy Section

3.2.1 使用`JSONPath`读取部分数据

String text = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

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

3.2.2 使用`JSONPath`读取部分`byte[]`的数据

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

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

3.2.3 使用`JSONPath`读取部分`byte[]`的数据

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // 缓存起来重复使用能提升性能

JSONReader parser = JSONReader.ofJSONB(bytes); // 注意这里使用ofJSONB方法
Object result = path.extract(parser);

ARCHITECTURE (`docs/ARCHITECTURE.md`) Copy Section

Fastjson2 Architecture

Overview Copy Chapter

Fastjson2 is a high-performance JSON library for Java, designed as the next-generation version of Fastjson. It supports both JSON and JSONB (binary JSON) formats, with deeply optimized parsing and serialization capabilities targeting JDK 8 through 21+.

Project Structure Copy Chapter

fastjson2/
├── core/                      # Core library (JDK 8+)
├── extension/                 # Base extensions (Arrow, ClickHouse, Geo, Retrofit, etc.)
├── extension-jaxrs/           # JAX-RS integration
├── extension-solon/           # Solon framework integration
├── extension-spring5/         # Spring 5 integration (Web MVC, WebFlux, Data Redis, Messaging)
├── extension-spring6/         # Spring 6 integration
├── fastjson1-compatible/      # Fastjson 1.x API compatibility layer
├── kotlin/                    # Kotlin extension functions and DSL
├── codegen/                   # Compile-time code generation (APT)
├── benchmark/                 # JMH performance benchmarks
├── safemode-test/             # SafeMode test suite
├── android-test/              # Android compatibility tests
├── test-jdk17/                # JDK 17 feature tests (Records, sealed classes)
├── test-jdk25/                # JDK 25 feature tests
└── docs/                      # Documentation

Core Module Architecture Copy Chapter

Component Overview Copy Section

/* Detailed source-code truncated for AI context efficiency. */

1. JSON API Layer Copy Section

The public-facing API through which users interact with the library:

• JSON.java - Main entry point with static methods (parseObject, parseArray, toJSONString, toJSONBytes)
• JSONObject.java - JSON object (extends LinkedHashMap<String, Object>, maintains insertion order)
• JSONArray.java - JSON array (extends ArrayList<Object>)
• JSONB.java - Binary JSON format support
• JSONPath.java - JSONPath query engine with SQL:2016 compatibility
• JSONFactory.java - Factory for creating reader/writer instances with thread-local caching

2. Reader Layer (Parsing / Deserialization) Copy Section

Encoding-specific parsers that convert input to Java objects:

The abstract JSONReader base class defines the parsing contract. JSONFactory selects the appropriate implementation based on input type and JDK version.

3. Writer Layer (Serialization) Copy Section

Encoding-specific writers that convert Java objects to output:

4. Object Mapping Layer Copy Section

Reader Package (`com.alibaba.fastjson2.reader`)

Writer Package (`com.alibaba.fastjson2.writer`)

Creator Selection Strategy

FASTJSON 2 selects the optimal ObjectReader/ObjectWriter creator based on the runtime environment:

JDK 8 server  → ObjectReaderCreatorASM (best performance)
JDK 17 server → ObjectReaderCreatorASM + Vector API optimizations
Android        → ObjectReaderCreator (LambdaMetafactory-based, no ASM on Android)
GraalVM Native → ObjectReaderCreator (reflection-based, no dynamic bytecode)
SafeMode       → ObjectReaderCreator (reflection-based)

5. JSONPath Layer Copy Section

Full JSONPath implementation compatible with SQL:2016:

• JSONPath - Query compilation and execution
• JSONPathSegment - Base class for path segments
• JSONPathSegmentIndex - Array index access ($[0], $[-1])
• JSONPathSegmentName - Object property access ($.name)
• JSONPathParser - JSONPath expression parser
• JSONPathFilter - Filter operations ($[?(@.price > 10)])

JSONPath instances are immutable and thread-safe after construction. They should be cached and reused.

6. Annotation Layer (`com.alibaba.fastjson2.annotation`) Copy Section

7. Filter Layer (`com.alibaba.fastjson2.filter`) Copy Section

Serialization filters applied during the write phase:

8. Schema Layer (`com.alibaba.fastjson2.schema`) Copy Section

• JSONSchema - JSON Schema validation (draft support)
• Validates JSONObject, JavaBeans, and raw JSON data
• Can be configured via @JSONField(schema = "...") annotations

Key Design Patterns Copy Chapter

Factory Pattern Copy Section

• JSONFactory creates reader/writer instances with thread-local recycling
• ObjectReaderCreator / ObjectWriterCreator create type-specific readers/writers

Provider Pattern Copy Section

• ObjectReaderProvider manages reader instances with ConcurrentHashMap caching
• ObjectWriterProvider manages writer instances with ConcurrentHashMap caching
• First access triggers creation; subsequent accesses retrieve from cache

Strategy Pattern Copy Section

• JSONReader implementations for different encodings (UTF-8, UTF-16, ASCII, JSONB)
• JSONWriter implementations for different output formats
• ObjectReaderCreator (base, uses Lambda/reflection) and ObjectReaderCreatorASM (bytecode) selected by environment

Visitor Pattern Copy Section

• JSONPath segment traversal through document structure
• JSONReader token-based parsing

Module Pattern Copy Section

• ObjectReaderModule / ObjectWriterModule allow extensions to register custom type handlers
• Framework integrations (Spring, JAX-RS) use modules to hook into the serialization pipeline

Performance Optimizations Copy Chapter

1. ASM Code Generation Copy Section

• Generates optimized bytecode at runtime for object readers/writers
• Switch-case on field name hash for O(1) field lookup during deserialization
• Eliminates reflection overhead for field access
• Located in ObjectReaderCreatorASM and ObjectWriterCreatorASM

2. Lambda Metafactory Copy Section

• Uses LambdaMetafactory for method handles on JDK 8+
• Near-native-call performance for getter/setter invocations
• Used by ObjectReaderCreator and ObjectWriterCreator for field access

3. Vector API (JDK 17+) Copy Section

• SIMD optimizations for bulk character processing in UTF-8/UTF-16 parsers
• Accelerates string scanning, whitespace skipping, and validation
• Located in JSONReaderUTF8 and JSONReaderUTF16

4. String Interning Copy Section

• SymbolTable for efficient string reuse of field names
• Reduces memory allocation and GC pressure during parsing
• Keys are interned on first encounter and reused on subsequent parses

5. Lazy Parsing Copy Section

• JSONPath supports partial parsing without full document deserialization
• Only the targeted path is parsed; rest of the document is skipped
• Critical for extracting fields from large JSON documents

6. Thread-Local Buffers Copy Section

• JSONFactory provides thread-local reader/writer instances
• Buffer recycling reduces allocation overhead in high-throughput scenarios

JSONB Binary Format Copy Chapter

JSONB is a binary representation of JSON with the following design:

• Compact encoding: Small integers (-16 to 47) require only 1 byte
• Schema-less: No pre-defined schema needed
• Type-rich: Supports all JSON types plus binary data
• Symbol table: Optional key compression for repeated field names
• Multi-encoding: Strings can be stored as UTF-8, UTF-16, ASCII, or GB18030

Format specification: JSONB Format Documentation

Thread Safety Copy Chapter

Extension Points Copy Chapter

1. Module System Copy Section

• ObjectReaderModule - Register custom deserialization modules
• ObjectWriterModule - Register custom serialization modules
• Modules are registered via JSONFactory.getDefaultObjectReaderProvider().register(module)

2. Custom ObjectReader/ObjectWriter Copy Section

• Implement ObjectReader<T> for custom deserialization logic
• Implement ObjectWriter<T> for custom serialization logic
• Register via JSON.register(Class, ObjectReader/ObjectWriter)

3. Filters Copy Section

• Apply during serialization for value transformation, name mapping, property filtering
• Register per-call via JSON.toJSONString(obj, filter) or globally

4. MixIn Annotations Copy Section

• Inject annotations on third-party classes without modifying source
• JSON.mixIn(TargetClass.class, MixInClass.class)

5. AutoType Handlers Copy Section

• AutoTypeBeforeHandler - Custom type validation before deserialization
• JSONReader.autoTypeFilter(...) - Whitelist-based type filtering per call

Module Dependencies Copy Chapter

core (JDK 8+)
├── extension (core)
│   ├── extension-spring5 (core, extension)
│   ├── extension-spring6 (core, extension)
│   ├── extension-solon (core, extension)
│   └── extension-jaxrs (core, extension)
├── fastjson1-compatible (core)
├── kotlin (core)
├── codegen (core)
└── benchmark (core)

Build System Copy Chapter

• Build tool: Maven with multi-module structure
• Java baseline: JDK 8 (core)
• Kotlin: Version 2.1.20
• ASM: Embedded internally in com.alibaba.fastjson2.internal.asm (for bytecode generation)
• Testing: JUnit 5, Kotest (Kotlin module)
• Code style: Checkstyle (src/checkstyle/fastjson2-checks.xml)
• CI: GitHub Actions across JDK 8/11/17/21/25 on Ubuntu/Windows/macOS

Documentation Copy Chapter

• Features Reference - All JSONReader/JSONWriter features
• Annotations Guide - @JSONField, @JSONType, @JSONCreator
• JSONB Format - Binary format specification
• JSONPath Guide - JSONPath syntax and examples
• Kotlin Support - Kotlin API extensions
• Spring Integration - Spring Framework setup
• Performance Guide - Tuning tips and best practices
• FAQ - Frequently asked questions
• Benchmarks - Performance data

FAQ Cn (`docs/FAQ_cn.md`) Copy Section

常见问题

概述 Copy Chapter

FASTJSON 和 FASTJSON 2 有什么区别？ Copy Section

FASTJSON 2 是对原始 FASTJSON 库的全面重写，面向未来十年设计。主要区别：

• 新包名: com.alibaba.fastjson2（v1 为 com.alibaba.fastjson）
• 更好的性能: 所有操作均有显著提升
• 更安全: AutoType 默认关闭，无硬编码白名单
• 现代 Java: JDK 11/17/21 优化，Record 支持，Vector API
• 二进制格式: 原生 JSONB 支持
• JSON Schema: 内置校验功能

FASTJSON 2 可以和 FASTJSON 1.x 共存吗？ Copy Section

可以。由于使用不同的包名（com.alibaba.fastjson2 vs com.alibaba.fastjson），两者可以在同一项目中共存。但使用兼容模块（com.alibaba:fastjson:2.x）时会与 FASTJSON 1.x 冲突，因为它们共享相同的包名。

支持哪些 Java 版本？ Copy Section

• 核心库: Java 8+
• 完整功能集: Java 11+（compact string 优化）
• Vector API 优化: Java 17+
• Android: Android 8+（API level 26+）

FASTJSON 2 支持 GraalVM Native Image 吗？ Copy Section

支持。FASTJSON 2 兼容 GraalVM Native Image。注意在 native image 中 ASM 代码生成不可用，将使用基于反射或 lambda 的创建器。

解析与反序列化 Copy Chapter

如何解析结构未知的 JSON？ Copy Section

// 解析为 JSONObject（JSON 对象）
JSONObject obj = JSON.parseObject(jsonString);

// 解析为 JSONArray（JSON 数组）
JSONArray arr = JSON.parseArray(jsonString);

// 解析为通用 Object（自动检测）
Object result = JSON.parse(jsonString);

如何解析带泛型的 JSON？ Copy Section

使用 TypeReference 处理复杂泛型：

// List<User>
List<User> users = JSON.parseObject(json, new TypeReference<List<User>>(){});

// Map<String, List<User>>
Map<String, List<User>> map = JSON.parseObject(json,
    new TypeReference<Map<String, List<User>>>(){});

如何处理日期/时间格式？ Copy Section

使用 @JSONField(format = "...") 或全局配置：

// 字段级别
public class Event {
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    public Date eventTime;
}

// 全局配置
JSON.configReaderDateFormat("yyyy-MM-dd");

// 每次调用
User user = JSON.parseObject(json, User.class, "yyyy-MM-dd");

如何进行大小写不敏感的字段匹配？ Copy Section

启用 SupportSmartMatch 可自动处理 camelCase、PascalCase、snake_case 和 kebab-case：

User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportSmartMatch);

注意：智能匹配在 FASTJSON 2 中默认关闭（v1 中默认开启）。

如何使用 BigDecimal 处理浮点数？ Copy Section

JSONObject obj = JSON.parseObject(json,
    JSONReader.Feature.UseBigDecimalForFloats,
    JSONReader.Feature.UseBigDecimalForDoubles);

如何在解析时去除字符串空格？ Copy Section

User user = JSON.parseObject(json, User.class, JSONReader.Feature.TrimString);

序列化 Copy Chapter

如何在 JSON 输出中包含 null 字段？ Copy Section

String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

针对特定 null 值的处理策略：

// null String → ""
JSONWriter.Feature.WriteNullStringAsEmpty

// null List → []
JSONWriter.Feature.WriteNullListAsEmpty

// null Number → 0
JSONWriter.Feature.WriteNullNumberAsZero

// null Boolean → false
JSONWriter.Feature.WriteNullBooleanAsFalse

如何格式化输出 JSON？ Copy Section

String json = JSON.toJSONString(user, JSONWriter.Feature.PrettyFormat);

如何处理 JavaScript 中的大 Long 值？ Copy Section

JavaScript 无法处理超过 Number.MAX_SAFE_INTEGER（2^53 - 1）的 Java long 值。使用 BrowserCompatible 或 WriteLongAsString：

// 自动检测并将大数字转为字符串
String json = JSON.toJSONString(user, JSONWriter.Feature.BrowserCompatible);

// 始终将 Long 序列化为 String
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteLongAsString);

如何按指定顺序序列化字段？ Copy Section

使用 @JSONField(ordinal = N) 或 @JSONType(orders = {...})：

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

    @JSONField(ordinal = 2)
    public int age;
}

// 或在类级别
@JSONType(orders = {"name", "age", "email"})
public class User { ... }

如何排除特定字段不参与序列化？ Copy Section

多种方式：

// 基于注解
@JSONField(serialize = false)
public String password;

// 类级别忽略
@JSONType(ignores = {"password", "secretKey"})
public class User { ... }

// 基于过滤器
PropertyFilter filter = (object, name, value) -> !"password".equals(name);
String json = JSON.toJSONString(user, filter);

AutoType 与安全 Copy Chapter

FASTJSON 2 默认安全吗？ Copy Section

是的。与 FASTJSON 1.x 不同，FASTJSON 2 默认禁用 AutoType。包含 @type 字段的 JSON 数据将被忽略，除非显式启用 AutoType。

如何安全地启用 AutoType？ Copy Section

使用 AutoTypeFilter 配合小范围白名单，而不是启用全局 AutoType：

// 推荐：使用范围有限的过滤器和白名单
Filter autoTypeFilter = JSONReader.autoTypeFilter(
    "com.mycompany.model"  // 仅允许此包下的类
);

Object result = JSON.parseObject(json, Object.class, autoTypeFilter);

如果必须启用全局 AutoType（不推荐用于面向互联网的服务）：

Object result = JSON.parseObject(json, Object.class, JSONReader.Feature.SupportAutoType);

什么是 SafeMode？ Copy Section

SafeMode 完全禁用 AutoType，即使在代码中显式配置也无效。通过 JVM 参数启用：

-Dfastjson2.parser.safeMode=true

性能 Copy Chapter

如何获得最佳解析性能？ Copy Section

1. 尽量使用 byte[] 输入 - JSON.parseObject(bytes, Type.class) 可避免 String 转换开销。
2. 复用 JSONPath 实例 - JSONPath.of("$.id") 是线程安全的，可缓存重复使用。
3. 使用部分解析 - 对于大型文档，使用 JSONPath 仅提取需要的数据。
4. 使用 JSONB - 内部服务通信时，JSONB 比文本 JSON 快得多。
5. 避免不必要的 Feature - 每个启用的 Feature 会增加少量开销。

如何获得最佳序列化性能？ Copy Section

1. 使用 byte[] 输出 - JSON.toJSONBytes(obj) 在大多数场景下比 JSON.toJSONString(obj) 更快。
2. 使用 BeanToArray - JSONWriter.Feature.BeanToArray 产生更小的输出且序列化更快。
3. 使用 JSONB - 对于二进制协议，JSONB 性能显著更优。

FASTJSON 2 与 Jackson 和 Gson 相比如何？ Copy Section

FASTJSON 2 在基准测试中始终优于 Jackson 和 Gson。详细数据请参阅 fastjson_benchmark。

Spring 集成 Copy Chapter

如何在 Spring Boot 中用 FASTJSON 2 替换 Jackson？ Copy Section

添加扩展依赖并配置消息转换器。详见完整的 Spring 集成指南。

Spring 6.x 快速配置：

@Configuration
public class JsonConfig extends WebMvcConfigurationSupport {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        converters.add(0, converter);
    }
}

如何在 Spring Data Redis 中使用 FASTJSON 2？ Copy Section

使用 GenericFastJsonRedisSerializer：

@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
    RedisTemplate<String, Object> template = new RedisTemplate<>();
    template.setConnectionFactory(factory);
    template.setDefaultSerializer(new GenericFastJsonRedisSerializer());
    return template;
}

从 Fastjson 1.x 迁移 Copy Chapter

最简单的迁移方式是什么？ Copy Section

使用兼容包直接替换：

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

这提供与 v1 相同的包名（com.alibaba.fastjson），底层使用 FASTJSON 2 引擎。

`ParserConfig.getGlobalInstance().addAccept()` 如何替换？ Copy Section

在 FASTJSON 2 中，使用 ObjectReaderProvider：

JSONFactory.getDefaultObjectReaderProvider().addAutoTypeAccept("com.mycompany.xxx");

`ObjectSerializer` 和 `ObjectDeserializer` 的替代方案是什么？ Copy Section

完整的 API 映射表请参阅 升级指南。

故障排查 Copy Chapter

遇到 `com.alibaba.fastjson2.JSONException` Copy Section

常见原因：

1. JSON 格式错误 - 使用 JSON 格式检查工具验证您的 JSON。
2. 类型不匹配 - JSON 结构与目标 Java 类型不匹配。
3. 缺少默认构造函数 - 目标类需要无参构造函数（或使用 @JSONCreator）。
4. Enum 不匹配 - 启用 ErrorOnEnumNotMatch 获取详细错误信息。

字段未被序列化 Copy Section

请检查：

1. 字段必须是 public 或有 public getter 方法（除非使用 FieldBased Feature）。
2. transient 字段默认被跳过。
3. 检查是否应用了 @JSONField(serialize = false) 或 @JSONType(ignores = ...)。

字段未被反序列化 Copy Section

请检查：

1. JSON 键名必须与 Java 字段名匹配（或使用 @JSONField(name = "...") 进行映射）。
2. 如果 JSON 使用不同的命名规范，启用 SupportSmartMatch。
3. 字段必须是 public 或有 public setter 方法（除非使用 FieldBased Feature）。

遇到 `ClassNotFoundException` 或 AutoType 错误 Copy Section

FASTJSON 2 默认禁用 AutoType。如果您的 JSON 包含 @type 字段：

1. 使用 AutoTypeFilter 配合窄范围白名单针对特定类。
2. 或启用 SupportAutoType（不推荐用于不可信输入）。
3. 不要在面向互联网的服务中使用 AutoType。

FAQ En (`docs/FAQ_en.md`) Copy Section

Frequently Asked Questions

General Copy Chapter

What is the difference between FASTJSON and FASTJSON 2? Copy Section

FASTJSON 2 is a complete rewrite of the original FASTJSON library, designed for the next decade. Key differences:

• New package: com.alibaba.fastjson2 (v1 was com.alibaba.fastjson)
• Better performance: Significant improvements across all operations
• More secure: AutoType disabled by default, no hardcoded whitelist
• Modern Java: JDK 11/17/21 optimizations, Record support, Vector API
• Binary format: Native JSONB support
• JSON Schema: Built-in validation

Can FASTJSON 2 coexist with FASTJSON 1.x? Copy Section

Yes. Because they use different package names (com.alibaba.fastjson2 vs com.alibaba.fastjson), both can exist in the same project. However, using the compatibility module (com.alibaba:fastjson:2.x) will conflict with FASTJSON 1.x since they share the same package.

What Java versions are supported? Copy Section

• Core library: Java 8+
• Full feature set: Java 11+ (compact string optimizations)
• Vector API optimizations: Java 17+
• Android: Android 8+ (API level 26+)

Does FASTJSON 2 support GraalVM Native Image? Copy Section

Yes. FASTJSON 2 is compatible with GraalVM Native Image. Note that ASM-based code generation is not available in native images, so the reflection-based or lambda-based creator will be used instead.

Parsing & Deserialization Copy Chapter

How do I parse JSON with unknown structure? Copy Section

// Parse as JSONObject (for JSON objects)
JSONObject obj = JSON.parseObject(jsonString);

// Parse as JSONArray (for JSON arrays)
JSONArray arr = JSON.parseArray(jsonString);

// Parse as generic Object (auto-detect)
Object result = JSON.parse(jsonString);

How do I parse JSON with generic types? Copy Section

Use TypeReference for complex generic types:

// List<User>
List<User> users = JSON.parseObject(json, new TypeReference<List<User>>(){});

// Map<String, List<User>>
Map<String, List<User>> map = JSON.parseObject(json,
    new TypeReference<Map<String, List<User>>>(){});

How do I handle date/time formats? Copy Section

Use @JSONField(format = "...") or global configuration:

// Per-field
public class Event {
    @JSONField(format = "yyyy-MM-dd HH:mm:ss")
    public Date eventTime;
}

// Global
JSON.configReaderDateFormat("yyyy-MM-dd");

// Per-call
User user = JSON.parseObject(json, User.class, "yyyy-MM-dd");

How do I handle case-insensitive field matching? Copy Section

Enable SupportSmartMatch to automatically handle camelCase, PascalCase, snake_case, and kebab-case:

User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportSmartMatch);

Note: Smart matching is off by default in FASTJSON 2 (it was on by default in v1).

How do I use BigDecimal for floating-point numbers? Copy Section

JSONObject obj = JSON.parseObject(json,
    JSONReader.Feature.UseBigDecimalForFloats,
    JSONReader.Feature.UseBigDecimalForDoubles);

How do I trim string values during parsing? Copy Section

User user = JSON.parseObject(json, User.class, JSONReader.Feature.TrimString);

Serialization Copy Chapter

How do I include null fields in JSON output? Copy Section

String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

For specific null handling strategies:

// null String → ""
JSONWriter.Feature.WriteNullStringAsEmpty

// null List → []
JSONWriter.Feature.WriteNullListAsEmpty

// null Number → 0
JSONWriter.Feature.WriteNullNumberAsZero

// null Boolean → false
JSONWriter.Feature.WriteNullBooleanAsFalse

How do I pretty-print JSON? Copy Section

String json = JSON.toJSONString(user, JSONWriter.Feature.PrettyFormat);

How do I handle large Long values for JavaScript compatibility? Copy Section

JavaScript cannot handle Java long values beyond Number.MAX_SAFE_INTEGER (2^53 - 1). Use BrowserCompatible or WriteLongAsString:

// Auto-detect and convert large numbers to strings
String json = JSON.toJSONString(user, JSONWriter.Feature.BrowserCompatible);

// Always serialize Long as String
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteLongAsString);

How do I serialize fields in a specific order? Copy Section

Use @JSONField(ordinal = N) or @JSONType(orders = {...}):

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

    @JSONField(ordinal = 2)
    public int age;
}

// or at class level
@JSONType(orders = {"name", "age", "email"})
public class User { ... }

How do I exclude specific fields from serialization? Copy Section

Multiple approaches:

// Annotation-based
@JSONField(serialize = false)
public String password;

// Class-level ignore
@JSONType(ignores = {"password", "secretKey"})
public class User { ... }

// Filter-based
PropertyFilter filter = (object, name, value) -> !"password".equals(name);
String json = JSON.toJSONString(user, filter);

AutoType & Security Copy Chapter

Is FASTJSON 2 secure by default? Copy Section

Yes. Unlike FASTJSON 1.x, FASTJSON 2 disables AutoType by default. JSON data containing @type fields will be ignored unless you explicitly enable AutoType.

How do I enable AutoType safely? Copy Section

Use AutoTypeFilter with a narrow whitelist instead of enabling global AutoType:

// Preferred: scoped filter with narrow whitelist
Filter autoTypeFilter = JSONReader.autoTypeFilter(
    "com.mycompany.model"  // Only allow classes in this package
);

Object result = JSON.parseObject(json, Object.class, autoTypeFilter);

If you must enable global AutoType (not recommended for internet-facing services):

Object result = JSON.parseObject(json, Object.class, JSONReader.Feature.SupportAutoType);

What is SafeMode? Copy Section

SafeMode completely disables AutoType, even if explicitly configured in the code. Enable it with a JVM parameter:

-Dfastjson2.parser.safeMode=true

Performance Copy Chapter

How do I get the best parsing performance? Copy Section

1. Use byte[] input when possible - JSON.parseObject(bytes, Type.class) avoids String conversion overhead.
2. Reuse JSONPath instances - JSONPath.of("$.id") is cacheable and thread-safe.
3. Use partial parsing - For large documents, use JSONPath to extract only what you need.
4. Use JSONB - For internal service communication, JSONB is significantly faster than text JSON.
5. Avoid unnecessary features - Each enabled feature adds a small overhead.

How do I get the best serialization performance? Copy Section

1. Use byte[] output - JSON.toJSONBytes(obj) is faster than JSON.toJSONString(obj) for most use cases.
2. Use BeanToArray - JSONWriter.Feature.BeanToArray produces smaller output and is faster to serialize.
3. Use JSONB - For binary protocols, JSONB is significantly faster.

How does FASTJSON 2 compare to Jackson and Gson? Copy Section

FASTJSON 2 consistently outperforms Jackson and Gson in benchmarks. See the detailed benchmark data at fastjson_benchmark.

Spring Integration Copy Chapter

How do I replace Jackson with FASTJSON 2 in Spring Boot? Copy Section

Add the extension dependency and configure the message converter. See the full Spring Integration Guide.

Quick setup for Spring 6.x:

@Configuration
public class JsonConfig extends WebMvcConfigurationSupport {
    @Override
    public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        converters.add(0, converter);
    }
}

How do I use FASTJSON 2 with Spring Data Redis? Copy Section

Use GenericFastJsonRedisSerializer:

@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
    RedisTemplate<String, Object> template = new RedisTemplate<>();
    template.setConnectionFactory(factory);
    template.setDefaultSerializer(new GenericFastJsonRedisSerializer());
    return template;
}

Migration from Fastjson 1.x Copy Chapter

What is the easiest way to migrate? Copy Section

Use the compatibility package as a drop-in replacement:

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

This provides the same package name (com.alibaba.fastjson) with FASTJSON 2's engine underneath.

What changed with `ParserConfig.getGlobalInstance().addAccept()`? Copy Section

In FASTJSON 2, use ObjectReaderProvider:

JSONFactory.getDefaultObjectReaderProvider().addAutoTypeAccept("com.mycompany.xxx");

What replaces `ObjectSerializer` and `ObjectDeserializer`? Copy Section

See the full Migration Guide for the complete API mapping table.

Troubleshooting Copy Chapter

I'm getting `com.alibaba.fastjson2.JSONException` Copy Section

Common causes:

1. Malformed JSON - Validate your JSON with a linter.
2. Type mismatch - The JSON structure doesn't match the target Java type.
3. Missing default constructor - The target class needs a no-arg constructor (or use @JSONCreator).
4. Enum mismatch - Enable ErrorOnEnumNotMatch to get detailed error messages.

Fields are not being serialized Copy Section

Check for:

1. Fields must be public or have public getter methods (unless using FieldBased feature).
2. transient fields are skipped by default.
3. Check if @JSONField(serialize = false) or @JSONType(ignores = ...) is applied.

Fields are not being deserialized Copy Section

Check for:

1. JSON key names must match Java field names (or use @JSONField(name = "...") to map).
2. Enable SupportSmartMatch if the JSON uses a different naming convention.
3. Fields must be public or have public setter methods (unless using FieldBased feature).

Getting `ClassNotFoundException` or `AutoType` errors Copy Section

FASTJSON 2 disables AutoType by default. If your JSON contains @type fields:

1. Use AutoTypeFilter with a narrow whitelist for specific classes.
2. Or enable SupportAutoType (not recommended for untrusted input).
3. Do not use AutoType in internet-facing services.

Annotations Cn (`docs/annotations_cn.md`) Copy Section

FASTJSON2提供的Annotations

1. JSONField Copy Chapter

JSONField是作用在Field、Method、Parameter上的Annotation，可以用来指定序列化字段的顺序、名字、格式、是否忽略、配置JSONReader/JSONWriter的Features等。

1.1 定制序列化和反序列化时的属性名 Copy Section

可以通过JSONField.name来配置序列化输出的字段名和反序列化是映射的字段名。

• 配置在public field上

public class A {
      @JSONField(name = "ID")
      public int id;
 }

• 配置在public getter/setter method上

public class A {
      private int id;
 
      @JSONField(name = "ID")
      public int getId() {return id;}

      @JSONField(name = "ID")
      public void setId(int value) {this.id = id;}
}

1.2 配置字段输出和反序列化的格式 Copy Section

针对Date类型的字段，经常需要用定制的日期格式进行序列化和反序列化，可以通过JSONField.format来配置自定义日期格式。

public class VO {
      // 配置date序列化和反序列使用yyyyMMdd日期格式
      @JSONField(format = "yyyyMMdd")
      public Date date;
}

1.3 序列化/反序列化时忽略字段 Copy Section

可以通过JSONField.serialize配置该字段是否要序列化，通过JSONField.deserialize配置该字段是否需要反序列化。

• 配置序列化时忽略特定字段

public class VO {
      @JSONField(serialize = false)
      public Date date;
}

• 配置反序列化忽略特定字段

public class VO {
      @JSONField(deserialize = false)
      public Date date;
}

1.4 配置字段的序列化输出的的顺序 Copy Section

可以通过JSONField.ordinal来配置序列化时输出的顺序。

public static class VO {
      @JSONField(ordinal = 1)
      public String type;

      @JSONField(ordinal = 2)
      public String templateId;
}

1.5 配置序列化Features Copy Section

可以通过JSONField.serializeFeatures来指定序列化的Feature。更多配置Features参考 https://alibaba.github.io/fastjson2/features_cn 。

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONWriter.Feature;
import org.junit.jupiter.api.Test;


@Test
public void test() {
    Bean bean = new Bean();
    bean.id = 100;

    assertEquals("{\"id\":\"100\"}", JSON.toJSONString(bean));
}

public static class Bean {
    @JSONField(serializeFeatures = Feature.WriteNonStringValueAsString)
    public int id;
}

1.6 通过JSONField(value = true)配置JavaBean序列化字段和反序列化构造方式 Copy Section

将@JSONField(value = true)配置在其中一个字段上，序列化时，会将对象序列化时按照该字段的值输出。将@JSONField(value = true)配置在构造函数参数上，而且该构造函数只有1个参数，就会按照这个参数来构造对象

比如：

public static class Bean2 {
    private final int code;

    public Bean2(@JSONField(value = true) int code) {
        this.code = code;
    }

    @JSONField (value = true)
    public int getCode() {
        return code;
    }
}

@Test
public void test2() {
    Bean2 bean = new Bean2(101);
    String str = JSON.toJSONString(bean);
    assertEquals("101", str);
    Bean2 bean1 = JSON.parseObject(str, Bean2.class);
    assertEquals(bean.code, bean1.code);
}

1.7 通过JSONField(value = true)配置Enum基于其中一个字段序列化和反序列化 Copy Section

将@JSONField(value = true)配置在enum字段上，序列化和序列化都会基于这个字段来进行，比如：

public enum Type {
    X(101, "Big"),
    M(102, "Medium"),
    S(103, "Small");

    private final int code;
    private final String name;

    Type(int code, String name) {
        this.code = code;
        this.name = name;
    }

    @JSONField(value = true)
    public int getCode() {
        return code;
    }

    public String getName() {
        return name;
    }
}

public class Bean1 {
    public Type type;
}

@Test
public void test1() {
    Bean1 bean = new Bean1();
    bean.type = Type.M;
    String str = JSON.toJSONString(bean);
    assertEquals("{\"type\":102}", str);
    Bean1 bean1 = JSON.parseObject(str, Bean1.class);
    assertEquals(bean.type, bean1.type);
}

1.8 配置序列化时不忽略transient属性 Copy Section

从2.0.61版本开始，将@JSONField(skipTransient = false)配置在transient字段或@java.beans.Transient修饰的getter方法上，可以强制序列化transient属性。

public class Bean1 {
    @JSONField(skipTransient = false)
    public transient int id;
}

public class Bean2 {
    private int id;

    @JSONField(skipTransient = false)
    @java.beans.Transient
    public int getId() {
        return id;
    }
}

2. @JSONType Copy Chapter

JSONType是配置在类/接口上的注解，可以配置改类的所有字段的NamingStrategy、序列化和反序列化忽略的字段、JSONReader/JSONWriter的Features等。

2.1 配置序列化和反序列化时忽略某些字段 Copy Section

在下面的例子中，序列化输出只包括id1，忽略id2和id3。

@JSONType(ignores = {"id2", "id3"})
public static class Bean {
    public int getId() {
        return 101;
    }

    public int getId2() {
        return 102;
    }

    public int getId3() {
        return 103;
    }
}

2.2 配置序列化时保持原生类字段顺序 Copy Section

从2.0.13版本开始，您可以通过@JSONType(alphabetic = false)配置序列化时保持原生类字段顺序。

@Slf4j
public class JSONTypeAlphabetic {

    @JSONType(alphabetic = false)
    public static class Bean {
        public int f3;
        public int f1;
        public int f2;
        public int f0;
    }

    @Test
    public void test() {
        Bean bean = new Bean();
        bean.f0 = 101;
        bean.f1 = 102;
        bean.f2 = 103;
        bean.f3 = 104;
        log.info(JSON.toJSONString(bean));
        //{"f3":104,"f1":102,"f2":103,"f0":101}
    }
}

2.3 配置序列化时的`JSONReader`/`JSONWriter`的`Features` Copy Section

您可以通过@JSONType(serializeFeatures= ...)或@JSONType(deserializeFeatures = ...)注解配置序列化和反序列时JSONWriter/JSONReader的Features。

更多Features配置请参考 Features文档 。

@Slf4j
public class JSONTypeFeatures {

    // 反序列化时对字符串进行trim
    // 序列化时输出为null的字段
    @JSONType(deserializeFeatures = JSONReader.Feature.TrimString, serializeFeatures = JSONWriter.Feature.WriteNulls)
    public static class OrdersBean {
        public String filed1;
        public String filed2;
    }

    @Test
    public void test() {
        OrdersBean bean = new OrdersBean();
        bean.filed1 = "fastjson2";
        
        log.info(JSON.toJSONString(bean));
        //{"filed1":"fastjson2","filed2":null}
        String json="{\"filed1\":\"   fastjson2   \",\"filed2\":\"2\"}";
        
        OrdersBean bean2 = JSON.parseObject(json, OrdersBean.class);
        log.info(bean2.filed1);
        //fastjson2
    }
}

2.4 配置序列化时字段顺序 Copy Section

您可以通过@JSONType(orders = {"filed1", "filed2"})注解指定序列化时的字段顺序。

@Slf4j
public class JSONTypeOrders {

    @JSONType(orders = {"filed4", "filed3", "filed2", "filed1"})
    public static class OrdersBean {
        public String filed1;
        public String filed2;
        public String filed3;
        public String filed4;
  
    }

    @Test
    public void test() {
        OrdersBean bean = new OrdersBean();
        bean.filed1 = "1";
        bean.filed2 = "2";
        bean.filed3 = "3";
        bean.filed4 = "4";
        log.info(JSON.toJSONString(bean));
        //{"filed4":"4","filed3":"3","filed2":"2","filed1":"1"}
    }
}

2.5 配置序列化时不忽略transient属性 Copy Section

从2.0.61版本开始，您可以通过@JSONType(skipTransient = false)配置强制序列化transient属性。

@JSONType(skipTransient = false)
public class Bean1 {
    public transient int id;
}

@JSONType(skipTransient = false)
public class Bean2 {
    private int id;

    @java.beans.Transient
    public int getId() {
        return id;
    }
}

3. 基于mixin机制注入Annotation

当你需要定制化序列化一些LIB里面的类，你无法修改这些类的代码，你可以使用FASTJSON2的Minxin功能注入Annotation。
具体使用介绍参考这里： https://alibaba.github.io/fastjson2/mixin_cn

Annotations En (`docs/annotations_en.md`) Copy Section

Annotations provided by FASTJSON2

1. JSONField Copy Chapter

JSONField is an Annotation that acts on Field, Method, and Parameter. It can be used to specify the order, name, format, and whether to ignore serialized fields, configure JSONReader/JSONWriter Features, etc.

1.1 Attribute names when customizing serialization and deserialization Copy Section

The field name of the serialized output and the mapped field name of the deserialization can be configured through JSONField.name .

• Configured on the public field

public class A {
      @JSONField(name = "ID")
      public int id;
 }

• Configured on public getter/setter methods

public class A {
      private int id;
 
      @JSONField(name = "ID")
      public int getId() {return id;}

      @JSONField(name = "ID")
      public void setId(int value) {this.id = id;}
}

1.2 Configure the format of field output and deserialization Copy Section

For fields of Date type, it is often necessary to use a custom date format for serialization and deserialization, and the custom date format can be configured through JSONField.format.

public class VO {
      // Configure date serialization and deserialization to use the yyyyMMdd date format
      @JSONField(format = "yyyyMMdd")
      public Date date;
}

1.3 Ignore fields when serializing and deserializing Copy Section

You can configure whether the field needs to be serialized through JSONField.serialize, and whether the field needs to be deserialized through JSONField.deserialize.

• Ignore specific fields when configuring serialization

public class VO {
      @JSONField(serialize = false)
      public Date date;
}

• Ignore specific fields when configuring deserialization

public class VO {
      @JSONField(deserialize = false)
      public Date date;
}

1.4 The order of the serialized output of configuration fields Copy Section

The order of output during serialization can be configured through JSONField.ordinal.

public static class VO {
      @JSONField(ordinal = 1)
      public String type;

      @JSONField(ordinal = 2)
      public String templateId;
}

1.5 Configure Serialize Features Copy Section

The serialized Feature can be specified through JSONField.serializeFeatures. More configuration features reference https://alibaba.github.io/fastjson2/features_cn 。

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONWriter.Feature;
import org.junit.jupiter.api.Test;


@Test
public void test() {
    Bean bean = new Bean();
    bean.id = 100;

    assertEquals("{\"id\":\"100\"}", JSON.toJSONString(bean));
}

public static class Bean {
    @JSONField(serializeFeatures = Feature.WriteNonStringValueAsString)
    public int id;
}

1.6 Configure JavaBean serialization fields and deserialization construction methods through JSONField (value = true) Copy Section

Configure @JSONField(value = true) on one of the fields. When serializing, the object will be serialized and output according to the value of the field. Configure @JSONField(value = true) on the constructor parameter, and the constructor has only one parameter, and the object will be constructed according to this parameter

For example :

public static class Bean2 {
    private final int code;

    public Bean2(@JSONField(value = true) int code) {
        this.code = code;
    }

    @JSONField (value = true)
    public int getCode() {
        return code;
    }
}

@Test
public void test2() {
    Bean2 bean = new Bean2(101);
    String str = JSON.toJSONString(bean);
    assertEquals("101", str);
    Bean2 bean1 = JSON.parseObject(str, Bean2.class);
    assertEquals(bean.code, bean1.code);
}

1.7 Configure Enum to serialize and deserialize based on one of the fields through JSONField(value = true) Copy Section

Configure @JSONField(value = true) on the enum field, serialization and serialization will be based on this field

For example :

public enum Type {
    X(101, "Big"),
    M(102, "Medium"),
    S(103, "Small");

    private final int code;
    private final String name;

    Type(int code, String name) {
        this.code = code;
        this.name = name;
    }

    @JSONField(value = true)
    public int getCode() {
        return code;
    }

    public String getName() {
        return name;
    }
}

public class Bean1 {
    public Type type;
}

@Test
public void test1() {
    Bean1 bean = new Bean1();
    bean.type = Type.M;
    String str = JSON.toJSONString(bean);
    assertEquals("{\"type\":102}", str);
    Bean1 bean1 = JSON.parseObject(str, Bean1.class);
    assertEquals(bean.type, bean1.type);
}

1.8 Don't ignore transient fields when serializing Copy Section

Starting from version 2.0.61, configure @JSONField(skipTransient = false) on transient fields or getter methods annotated with @java.beans.Transient. This can force serialization of transient fields.

public class Bean1 {
    @JSONField(skipTransient = false)
    public transient int id;
}

public class Bean2 {
    private int id;

    @JSONField(skipTransient = false)
    @java.beans.Transient
    public int getId() {
        return id;
    }
}

2. @JSONType Copy Chapter

JSONType is an Annotation configured on Class/Interface, which can configure the NamingStrategy of all fields of the modified class, fields ignored by serialization and deserialization, Features of JSONReader/JSONWriter, etc.

2.1 Configure ignored fields for serialize and deserialize Copy Section

In the example below, the serialized output only includes id1, ignoring id2 and id3.

@JSONType(ignores = {"id2", "id3"})
public static class Bean {
    public int getId() {
        return 101;
    }

    public int getId2() {
        return 102;
    }

    public int getId3() {
        return 103;
    }
}

2.2 Maintain native class field order when configuring serialize Copy Section

Starting from version 2.0.13, you can use @JSONType(alphabetic = false) to configure serialization to maintain the order of native class fields.

@Slf4j
public class JSONTypeAlphabetic {

    @JSONType(alphabetic = false)
    public static class Bean {
        public int f3;
        public int f1;
        public int f2;
        public int f0;
    }

    @Test
    public void test() {
        Bean bean = new Bean();
        bean.f0 = 101;
        bean.f1 = 102;
        bean.f2 = 103;
        bean.f3 = 104;
        log.info(JSON.toJSONString(bean));
        //{"f3":104,"f1":102,"f2":103,"f0":101}
    }
}

2.3 `Features` of `JSONReader`/`JSONWriter` when configuring serialize and deserialize Copy Section

You can configure Features of JSONWriter/JSONReader during serialize and deserialize through @JSONType(serializeFeatures= ...) or @JSONType(deserializeFeatures = ...) annotations.

More Features Configuration please refer to Features Documentation 。

@Slf4j
public class JSONTypeFeatures {

    // Trim the string when serialize
    // Fields that output null when deserialize
    @JSONType(deserializeFeatures = JSONReader.Feature.TrimString, serializeFeatures = JSONWriter.Feature.WriteNulls)
    public static class OrdersBean {
        public String filed1;
        public String filed2;
    }

    @Test
    public void test() {
        OrdersBean bean = new OrdersBean();
        bean.filed1 = "fastjson2";
        
        log.info(JSON.toJSONString(bean));
        //{"filed1":"fastjson2","filed2":null}
        String json="{\"filed1\":\"   fastjson2   \",\"filed2\":\"2\"}";
        
        OrdersBean bean2 = JSON.parseObject(json, OrdersBean.class);
        log.info(bean2.filed1);
        //fastjson2
    }
}

2.4 Field order when configuring serialize Copy Section

You can use @JSONType(orders = {"filed1", "filed2"}) annotation to specify the field order during serialize.

@Slf4j
public class JSONTypeOrders {

    @JSONType(orders = {"filed4", "filed3", "filed2", "filed1"})
    public static class OrdersBean {
        public String filed1;
        public String filed2;
        public String filed3;
        public String filed4;
  
    }

    @Test
    public void test() {
        OrdersBean bean = new OrdersBean();
        bean.filed1 = "1";
        bean.filed2 = "2";
        bean.filed3 = "3";
        bean.filed4 = "4";
        log.info(JSON.toJSONString(bean));
        //{"filed4":"4","filed3":"3","filed2":"2","filed1":"1"}
    }
}

2.5 Don't ignore transient fields when serializing Copy Section

Starting from version 2.0.61, you can configure the mandatory serialization of transient properties through @ JSONType (skipTransient=false).

@JSONType(skipTransient = false)
public class Bean1 {
    public transient int id;
}

@JSONType(skipTransient = false)
public class Bean2 {
    private int id;

    @java.beans.Transient
    public int getId() {
        return id;
    }
}

3. Inject Annotation based on mixin mechanism

When you need to customize and serialize some classes in LIB, and you cannot modify the code of these classes, you can use the Minxin function of FASTJSON2 to inject Annotation.
For specific usage, refer to here: https://alibaba.github.io/fastjson2/mixin_cn

Autotype Cn (`docs/autotype_cn.md`) Copy Section

FASTJSON 2 Autotype机制介绍

1. AutoType功能介绍 Copy Chapter

FASTJSON支持AutoType功能，这个功能会在序列化的JSON字符串中带上类型信息，在反序列化时，不需要传入类型，实现自动类型识别。

2. AutoType安全机制介绍 Copy Chapter

• 必须显式打开才能使用。和fastjson 1.x不一样，fastjson 1.x为了兼容有一个白名单，在fastjson 2中，没有任何白名单，也不包括任何Exception类的白名单，必须显式打开才能使用。这可以保证缺省配置下是安全的。
• 支持配置safeMode，在safeMode打开后，显式传入AutoType参数也不起作用。
• 显式打开后，会经过内置黑名单过滤。该黑名单能拦截大部分常见风险，这个机制不能保证绝对安全，打开AutoType不应该在暴露在公网的场景下使用。

2.1 accept前缀不覆盖黑名单类型（2.0.63 起） Copy Section

ClassLoader子类和JDK SQL的DataSource/RowSet实现是反序列化利用链的常见入口，用前缀注册accept不再放行这些类型，必须写全类名才算显式授权。适用于addAutoTypeAccept、-Dfastjson2.autoTypeAccept、JSONReader.autoTypeFilter，以及fastjson 1.x兼容模式的ParserConfig.addAccept。

// 2.0.63 之前：前缀accept会放行 DruidDataSource
// 2.0.63 起：被拒绝
ParserConfig.getGlobalInstance().addAccept("com.alibaba.druid.pool.");

// 确实需要时，写全类名
ParserConfig.getGlobalInstance().addAccept("com.alibaba.druid.pool.DruidDataSource");

在此之前，注册了accept前缀的类型比完全没有注册的类型检查更松：同一个类型名在没有accept前缀时会被黑名单拦下，加了前缀反而能加载出来。

3. AutoType功能使用介绍 Copy Chapter

3.1 序列化时带上类型信息 Copy Section

如果需要序列化时带上类型信息，需要使用JSONWriter.Feature.WriteClassName。比如：

Bean bean = ...;
String jsonString = JSON.toJSONString(bean, JSONWriter.Feature.WriteClassName);

很多时候，root对象是可以知道类型的，里面的对象字段是基类或者不确定类型，这个时候不输出root对象的类型信息，可以减少序列化结果的大小，也能提升反序列化的性能。

Bean bean = ...;
String jsonString = JSON.toJSONString(bean, JSONWriter.Feature.WriteClassName, JSONWriter.Feature.NotWriteRootClassName);

3.2 反序列化时打开AutoType功能以支持自动类型 Copy Section

Bean bean = (Bean) JSON.parseObject(jsonString, Object.class, JSONReader.Feature.SupportAutoType);

4. 配置safeMode Copy Chapter

配置SafeMode会完全禁用AutoType功能，如果程序中显式指定类型，AutoType功能也不会生效。

4.1 JVM启动参数配置 Copy Section

-Dfastjson2.parser.safeMode=true

5. 使用AutoTypeFilter在不打开AutoTypeSupport时实现自动类型 Copy Chapter

当打开AutoTypeSupport，虽然内置了一个比较广泛的黑名单，但仍然是不够安全的。下面有一种办法是控制当前调用的AutoType支持范围，避免全局打开，这个更安全。

public class FastJsonRedisSerializer<T> implements RedisSerializer<T> {
    static final Filter autoTypeFilter = JSONReader.autoTypeFilter(
            // 按需加上需要支持自动类型的类名前缀，范围越小越安全
            "org.springframework.security.core.authority.SimpleGrantedAuthority"
    );

    private Class<T> clazz;

    public FastJsonRedisSerializer(Class<T> clazz) {
        super();
        this.clazz = clazz;
    }

    @Override
    public byte[] serialize(T t) {
        if (t == null) {
            return new byte[0];
        }
        return JSON.toJSONBytes(t, JSONWriter.Feature.WriteClassName);
    }

    @Override
    public T deserialize(byte[] bytes) {
        if (bytes == null || bytes.length <= 0) {
            return null;
        }

        return JSON.parseObject(bytes, clazz, autoTypeFilter);
    }
}

Autotype En (`docs/autotype_en.md`) Copy Section

Introduction to FASTJSON 2 AutoType Mechanism

1. Introduction to the AutoType Feature Copy Chapter

FASTJSON supports the AutoType feature, which includes type information in the serialized JSON string. During deserialization, it is not necessary to pass in the type, as it enables automatic type identification.

2. Introduction to the AutoType Security Mechanism Copy Chapter

• Must be explicitly enabled for use. Unlike fastjson 1.x, which had a whitelist for compatibility, fastjson 2 has no whitelist at all, not even for Exception classes. It must be explicitly enabled to be used. This ensures that the default configuration is secure.
• Supports safeMode configuration. When safeMode is enabled, explicitly passing AutoType parameters will have no effect.
• Filtered by a built-in blacklist when explicitly enabled. This blacklist can intercept most common risks, but this mechanism cannot guarantee absolute security. Enabling AutoType should not be done in scenarios exposed to the public internet.

2.1 Accept prefixes do not cover blacklisted types (since 2.0.63) Copy Section

ClassLoader subclasses and JDK SQL DataSource/RowSet implementations are common deserialization gadget entry points, and registering an accept entry by prefix no longer allows them. Only an accept entry naming the type in full counts as an explicit opt-in. This applies to addAutoTypeAccept, -Dfastjson2.autoTypeAccept, JSONReader.autoTypeFilter, and ParserConfig.addAccept in fastjson 1.x compatibility mode.

// before 2.0.63: the accept prefix allowed DruidDataSource
// since 2.0.63: rejected
ParserConfig.getGlobalInstance().addAccept("com.alibaba.druid.pool.");

// name the type in full where it is genuinely needed
ParserConfig.getGlobalInstance().addAccept("com.alibaba.druid.pool.DruidDataSource");

Before this change, a type covered by an accept prefix was checked less strictly than one that was never registered at all: the same type name was stopped by the blacklist without the accept prefix, and loaded successfully with it.

3. How to Use the AutoType Feature Copy Chapter

3.1 Including Type Information During Serialization Copy Section

If you need to include type information during serialization, you need to use JSONWriter.Feature.WriteClassName. For example:

Bean bean = ...;
String jsonString = JSON.toJSONString(bean, JSONWriter.Feature.WriteClassName);

Often, the type of the root object is known, while the object fields inside are base classes or of uncertain types. In this case, not outputting the type information for the root object can reduce the size of the serialized result and improve deserialization performance.

Bean bean = ...;
String jsonString = JSON.toJSONString(bean, JSONWriter.Feature.WriteClassName, JSONWriter.Feature.NotWriteRootClassName);

3.2 Enabling the AutoType Feature for Automatic Type Support During Deserialization Copy Section

Bean bean = (Bean) JSON.parseObject(jsonString, Object.class, JSONReader.Feature.SupportAutoType);

4. Configuring `safeMode` Copy Chapter

Configuring SafeMode will completely disable the AutoType feature. Even if the type is explicitly specified in the program, the AutoType feature will not take effect.

4.1 JVM Startup Parameter Configuration Copy Section

-Dfastjson2.parser.safeMode=true

5. Using AutoTypeFilter for Automatic Types without Enabling `AutoTypeSupport` Copy Chapter

When AutoTypeSupport is enabled, although there is a relatively extensive built-in blacklist, it is still not secure enough. A safer approach is to control the scope of AutoType support for the current call, avoiding enabling it globally.

public class FastJsonRedisSerializer<T> implements RedisSerializer<T> {
    static final Filter autoTypeFilter = JSONReader.autoTypeFilter(
            // Add class name prefixes that need to support auto-typing as needed. The smaller the scope, the safer.
            "org.springframework.security.core.authority.SimpleGrantedAuthority"
    );

    private Class<T> clazz;

    public FastJsonRedisSerializer(Class<T> clazz) {
        super();
        this.clazz = clazz;
    }

    @Override
    public byte[] serialize(T t) {
        if (t == null) {
            return new byte[0];
        }
        return JSON.toJSONBytes(t, JSONWriter.Feature.WriteClassName);
    }

    @Override
    public T deserialize(byte[] bytes) {
        if (bytes == null || bytes.length <= 0) {
            return null;
        }

        return JSON.parseObject(bytes, clazz, autoTypeFilter);
    }
}

Benchmark Cn (`docs/benchmark_cn.md`) Copy Section

1. Eishay测试

create     ser   deser   total   size  +dfl
json-array/fastjson/databind           30     455     414     869    284   171
protobuf                              159     601     319     919    242   152
cbor/jackson+afterburner/databind      29     565     753    1318    398   251
json/fastjson/databind                 29     659     707    1366    489   271
json/jackson+afterburner/databind      28     663     837    1500    488   271
cbor/jackson/databind                  30     587    1040    1628    398   251
json/jackson/databind                  29     697    1099    1796    488   271
json/gson/databind                     28    2091    1803    3893    489   268
hessian                                29    2062    2619    4681    504   319
java-built-in                          29    2815   15730   18545    892   520

• 测试代码 https://github.com/wenshao/jvm-serializers

2. 直接JMH性能测试比较

2.1 测试环境 Copy Chapter

• MacBook Pro (16-inch, 2021) MacApple M1 Max, 64GB Memory
• ZuluJDK

2.1.1 比较的版本 Copy Chapter

• Fastjson 2.0.1
• Fastjson 1.2.79
• Jackson 2.12.4

2.1.2 JDK版本 Copy Chapter

• JDK 8 zulu8.60.0.21-ca-jdk8.0.322-macosx_aarch64
• JDK 11 zulu11.54.25-ca-jdk11.0.14.1-macosx_aarch64
• JDK 17 zulu17.32.13-ca-jdk17.0.2-macosx_aarch64

2.2 Parse性能比较 Copy Chapter

• 测试代码 https://github.com/alibaba/fastjson2/blob/2.0.1/core/src/test/java/com/alibaba/fastjson_perf/eishay/EishayParse.java

2.2.1 场景介绍及结论 Copy Section

• EishayParseTreeString场景，将String解析成JSONObject/JSONArray或者HashMap/ArrayList。在这个场景，fastjson2表现出了两倍于fastjson1的性能
• EishayParseString场景，将String反序列化为JavaBean对象，在这个场景fastjson2相对于fastjson1性能提升了30%的性能。
• EishayParseStringPretty，将格式化带空格和换行符缩进的String反序列化为JavaBean对象，fastjson2在3.44倍于fastjson1。这个场景在fastjson1中是弱项，在fastjson2中采用新解析的算法，性能有了非常大提升。
• EishayParseUTF8Bytes，将UTF8格式的byte[]反序列化为JavaBean对象，

2.2.2 MacOS_M1Max_ARM_Zulu_JDK8 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.2.3 MacOS_M1Max_ARM_Zulu_JDK11 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.2.4 MacOS_M1Max_ARM_Zulu_JDK17 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.3 WriteString Copy Chapter

• 测试代码 https://github.com/alibaba/fastjson2/blob/2.0.1/core/src/test/java/com/alibaba/fastjson_perf/eishay/EishayWrite.java

2.3.1 场景介绍及结论 Copy Section

• EishayWriteString场景，将JavaBean对象序列化为字符串。这个场景中，fastjson2比fastjson1和jackson分别有164%和85%的性能提升
• EishayWriteUTF8Bytes场景，将JavaBean对象序列化为UTF8格式的byte数组。这个场景中，fastjson2比fastjson1和jackson分别有185%和93%的性能提升

2.3.2 MacOS_M1Max_ARM_Zulu_JDK8 Copy Section

Benchmark                         Mode  Cnt     Score   Error   Units
EishayWriteString.fastjson2      thrpt    5  3076.439 ± 4.692  ops/ms
EishayWriteString.fastjson1      thrpt    5  1162.488 ± 9.076  ops/ms
EishayWriteString.jackson        thrpt    5  1664.961 ± 3.204  ops/ms

EishayWriteUTF8Bytes.fastjson2   thrpt    5  2868.597 ± 5.674  ops/ms
EishayWriteUTF8Bytes.fastjson1   thrpt    5  1005.945 ± 3.602  ops/ms
EishayWriteUTF8Bytes.jackson     thrpt    5  1481.545 ± 5.302  ops/ms

2.3.3 MacOS_M1Max_ARM_Zulu_JDK11 Copy Section

Benchmark                        Mode  Cnt     Score    Error   Units
EishayWriteString.fastjson2     thrpt    5  2816.795 ± 11.322  ops/ms
EishayWriteString.fastjson1     thrpt    5  1063.862 ±  7.016  ops/ms
EishayWriteString.jackson       thrpt    5  1617.422 ±  5.465  ops/ms

EishayWriteUTF8Bytes.fastjson2  thrpt    5  3051.648 ±  8.048  ops/ms
EishayWriteUTF8Bytes.fastjson1  thrpt    5  1033.902 ± 11.964  ops/ms
EishayWriteUTF8Bytes.jackson    thrpt    5  1381.491 ± 12.199  ops/ms

2.3.4 MacOS_M1Max_ARM_Zulu_JDK17 Copy Section

Benchmark                        Mode  Cnt     Score    Error   Units
EishayWriteString.fastjson2     thrpt    5  3064.658 ± 16.216  ops/ms
EishayWriteString.fastjson1     thrpt    5  1250.379 ±  6.057  ops/ms
EishayWriteString.jackson       thrpt    5  1682.306 ±  6.945  ops/ms

EishayWriteUTF8Bytes.fastjson2  thrpt    5  2895.860 ± 78.134  ops/ms
EishayWriteUTF8Bytes.fastjson1  thrpt    5  1015.617 ± 11.698  ops/ms
EishayWriteUTF8Bytes.jackson    thrpt    5  1599.584 ±  3.278  ops/ms

Benchmark En (`docs/benchmark_en.md`) Copy Section

1. Eishay Test

create     ser   deser   total   size  +dfl
json-array/fastjson/databind           30     455     414     869    284   171
protobuf                              159     601     319     919    242   152
cbor/jackson+afterburner/databind      29     565     753    1318    398   251
json/fastjson/databind                 29     659     707    1366    489   271
json/jackson+afterburner/databind      28     663     837    1500    488   271
cbor/jackson/databind                  30     587    1040    1628    398   251
json/jackson/databind                  29     697    1099    1796    488   271
json/gson/databind                     28    2091    1803    3893    489   268
hessian                                29    2062    2619    4681    504   319
java-built-in                          29    2815   15730   18545    892   520

• Test code https://github.com/wenshao/jvm-serializers

2. Direct JMH Performance Comparison

2.1 Test Environment Copy Chapter

• MacBook Pro (16-inch, 2021) MacApple M1 Max, 64GB Memory
• ZuluJDK

2.1.1 Versions Compared Copy Chapter

• Fastjson 2.0.1
• Fastjson 1.2.79
• Jackson 2.12.4

2.1.2 JDK Versions Copy Chapter

• JDK 8 zulu8.60.0.21-ca-jdk8.0.322-macosx_aarch64
• JDK 11 zulu11.54.25-ca-jdk11.0.14.1-macosx_aarch64
• JDK 17 zulu17.32.13-ca-jdk17.0.2-macosx_aarch64

2.2 Parse Performance Comparison Copy Chapter

• Test code https://github.com/alibaba/fastjson2/blob/2.0.1/core/src/test/java/com/alibaba/fastjson_perf/eishay/EishayParse.java

2.2.1 Scenario Introduction and Conclusion Copy Section

• EishayParseTreeString scenario: Parsing a String into JSONObject/JSONArray or HashMap/ArrayList. In this scenario, fastjson2 shows twice the performance of fastjson1.
• EishayParseString scenario: Deserializing a String into a JavaBean object. In this scenario, fastjson2 has a 30% performance improvement over fastjson1.
• EishayParseStringPretty: Deserializing a formatted String with spaces, newlines, and indentation into a JavaBean object. fastjson2 is 3.44 times faster than fastjson1. This was a weak point for fastjson1, but with a new parsing algorithm in fastjson2, the performance has been greatly improved.
• EishayParseUTF8Bytes: Deserializing a UTF8-formatted byte[] into a JavaBean object.

2.2.2 MacOS_M1Max_ARM_Zulu_JDK8 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.2.3 MacOS_M1Max_ARM_Zulu_JDK11 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.2.4 MacOS_M1Max_ARM_Zulu_JDK17 Copy Section

/* Detailed source-code truncated for AI context efficiency. */

2.3 WriteString Copy Chapter

• Test code https://github.com/alibaba/fastjson2/blob/2.0.1/core/src/test/java/com/alibaba/fastjson_perf/eishay/EishayWrite.java

2.3.1 Scenario Introduction and Conclusion Copy Section

• EishayWriteString scenario: Serializing a JavaBean object into a string. In this scenario, fastjson2 shows performance improvements of 164% and 85% over fastjson1 and jackson, respectively.
• EishayWriteUTF8Bytes scenario: Serializing a JavaBean object into a UTF8-formatted byte array. In this scenario, fastjson2 shows performance improvements of 185% and 93% over fastjson1 and jackson, respectively.

2.3.2 MacOS_M1Max_ARM_Zulu_JDK8 Copy Section

Benchmark                         Mode  Cnt     Score   Error   Units
EishayWriteString.fastjson2      thrpt    5  3076.439 ± 4.692  ops/ms
EishayWriteString.fastjson1      thrpt    5  1162.488 ± 9.076  ops/ms
EishayWriteString.jackson        thrpt    5  1664.961 ± 3.204  ops/ms

EishayWriteUTF8Bytes.fastjson2   thrpt    5  2868.597 ± 5.674  ops/ms
EishayWriteUTF8Bytes.fastjson1   thrpt    5  1005.945 ± 3.602  ops/ms
EishayWriteUTF8Bytes.jackson     thrpt    5  1481.545 ± 5.302  ops/ms

2.3.3 MacOS_M1Max_ARM_Zulu_JDK11 Copy Section

Benchmark                        Mode  Cnt     Score    Error   Units
EishayWriteString.fastjson2     thrpt    5  2816.795 ± 11.322  ops/ms
EishayWriteString.fastjson1     thrpt    5  1063.862 ±  7.016  ops/ms
EishayWriteString.jackson       thrpt    5  1617.422 ±  5.465  ops/ms

EishayWriteUTF8Bytes.fastjson2  thrpt    5  3051.648 ±  8.048  ops/ms
EishayWriteUTF8Bytes.fastjson1  thrpt    5  1033.902 ± 11.964  ops/ms
EishayWriteUTF8Bytes.jackson    thrpt    5  1381.491 ± 12.199  ops/ms

2.3.4 MacOS_M1Max_ARM_Zulu_JDK17 Copy Section

Benchmark                        Mode  Cnt     Score    Error   Units
EishayWriteString.fastjson2     thrpt    5  3064.658 ± 16.216  ops/ms
EishayWriteString.fastjson1     thrpt    5  1250.379 ±  6.057  ops/ms
EishayWriteString.jackson       thrpt    5  1682.306 ±  6.945  ops/ms

EishayWriteUTF8Bytes.fastjson2  thrpt    5  2895.860 ± 78.134  ops/ms
EishayWriteUTF8Bytes.fastjson1  thrpt    5  1015.617 ± 11.698  ops/ms
EishayWriteUTF8Bytes.jackson    thrpt    5  1599.584 ±  3.278  ops/ms

Csv Cn (`docs/csv_cn.md`) Copy Section

CSV (comma-separated values)是一种使用逗号作为分隔符的被广泛使用的数据交换文件格式。

fastjson提供了一个高性能CSV读写支持。

1. 识别行数

分析CSV格式的文件有多少行，如果CSV文件有Header，具体数据行数要减1

File file = ...;
int rowCount = CSVReader.rowCount(file);

2. 分析文件内容

File file = ...;
CSVReader parser = CSVReader.of(file);

// 先读取Header第一行
parser.readHeader();

// 对数据进行统计分析
parser.statAll();

// 获取各个列的分析结果
List<StreamReader.ColumnStat> columns = parser.getColumnStats();

// 根据列的统计信息生成建表语句
StringBuilder sql = new StringBuilder();
sql.append("CREATE TABLE ").append(tableName).append(" (\n");
for (int i = 0; i < columns.size(); i++) {
    StreamReader.ColumnStat columnStat = columns.get(i);
    sql.append('\t')
        .append(columnName)
        .append(' ')
        .append(columnStat.getInferSQLType());

    if (i != columns.size() - 1) {
        sql.append(',');
    }
    sql.append("\n");
}
sql.append(");");

3. 缺省按照String类型来读取文件

File file = ...;
CSVReader parser = CSVReader.of(file);

// 根据需要，先读取Header第一行，如果没有Header可以忽略
parser.readHeader();
        
while (true) {
    String[] line = parser.readLine();
    if (line == null) {
        break;
    }
    // handler line
}

4. 指定每列的数据类型来读取文件

File file = ...;
Type[] types = new Type[] {
        Integer.class, 
        Long.class, 
        String.class , 
        Date.class 
};
// 构造CSVReader传入各列的类型信息
CSVReader parser = CSVReader.of(file, types);

// 根据需要，先读取Header第一行，如果没有Header可以忽略
parser.readHeader();
        
while (true) {
    Object[] line = parser.readLineValues();
    if (line == null) {
        break;
    }
    
    // 处理数据，每列的值都会和构造CSVReader时传入的types对应
    Integer v0 = line[0];
    Long v1 = line[1];
    String v2 = line[2];
    Date v3 = line[3];
}

5. 将每行数据读取成一个JavaBean

@Data
class Bean {
    long id;
    int age;
    String name;
    Date created;
}

File file = ...;

// 构造CSVReader传入对象类型
CSVReader parser = CSVReader.of(file, Bean.class);

// 根据需要，先读取Header第一行，如果没有Header可以忽略
parser.readHeader();

while (true) {
    Bean object = (Bean) parser.readLineObject();
    if (object == null) {
        break;
    }
    
    // 处理数据 ...
}

5.1 使用Lambda Consumer来读取JavaBean Copy Chapter

File file = ...;

// 构造CSVReader传入对象类型
CSVReader parser = CSVReader.of(file, Bean.class);

// 根据需要，是否要读取Header第一行
boolean readHeader = true;
parser.readLineObjectAll(
        readHeader,
        e -> {
            处理数据 ...
        }
);

6. 写入CSV格式文件

File file = ...;
CSVWriter writer = CSVWriter.of(file, StandardCharsets.UTF_8);

// 写入数据
Object[] row = ...;
writer.writeLine(row);

writer.close();

Csv En (`docs/csv_en.md`) Copy Section

CSV (comma-separated values) is a widely used data exchange file format that uses commas as delimiters.

fastjson provides high-performance support for reading and writing CSV.

1. Count Rows

Analyze how many rows a CSV file has. If the CSV file has a header, the number of data rows will be one less.

File file = ...;
int rowCount = CSVReader.rowCount(file);

2. Analyze File Content

File file = ...;
CSVReader parser = CSVReader.of(file);

// First, read the header (the first line)
parser.readHeader();

// Perform statistical analysis on the data
parser.statAll();

// Get the analysis results for each column
List<StreamReader.ColumnStat> columns = parser.getColumnStats();

// Generate a CREATE TABLE statement based on the column statistics
StringBuilder sql = new StringBuilder();
sql.append("CREATE TABLE ").append(tableName).append(" (\n");
for (int i = 0; i < columns.size(); i++) {
    StreamReader.ColumnStat columnStat = columns.get(i);
    sql.append('\t')
        .append(columnName)
        .append(' ')
        .append(columnStat.getInferSQLType());

    if (i != columns.size() - 1) {
        sql.append(',');
    }
    sql.append("\n");
}
sql.append(");");

3. Read File with String Type by Default

File file = ...;
CSVReader parser = CSVReader.of(file);

// If needed, read the header first. If there is no header, this can be skipped.
parser.readHeader();
        
while (true) {
    String[] line = parser.readLine();
    if (line == null) {
        break;
    }
    // handler line
}

4. Read File by Specifying Data Types for Each Column

File file = ...;
Type[] types = new Type[] {
        Integer.class, 
        Long.class, 
        String.class , 
        Date.class 
};
// Construct the CSVReader, passing in the type information for each column
CSVReader parser = CSVReader.of(file, types);

// If needed, read the header first. If there is no header, this can be skipped.
parser.readHeader();
        
while (true) {
    Object[] line = parser.readLineValues();
    if (line == null) {
        break;
    }
    
    // Process the data. The value of each column will correspond to the types passed in when constructing the CSVReader.
    Integer v0 = (Integer) line[0];
    Long v1 = (Long) line[1];
    String v2 = (String) line[2];
    Date v3 = (Date) line[3];
}

5. Read Each Row into a JavaBean

@Data
class Bean {
    long id;
    int age;
    String name;
    Date created;
}

File file = ...;

// Construct the CSVReader, passing in the object type
CSVReader parser = CSVReader.of(file, Bean.class);

// If needed, read the header first. If there is no header, this can be skipped.
parser.readHeader();

while (true) {
    Bean object = parser.readLineObject();
    if (object == null) {
        break;
    }
    
    // Process data ...
}

5.1 Read JavaBeans Using a Lambda Consumer Copy Chapter

File file = ...;

// Construct the CSVReader, passing in the object type
CSVReader parser = CSVReader.of(file, Bean.class);

// Specify whether to read the header first
boolean readHeader = true;
parser.readLineObjectAll(
        readHeader,
        e -> {
            // Process data ...
        }
);

6. Write to a CSV Format File

File file = ...;
CSVWriter writer = CSVWriter.of(file, StandardCharsets.UTF_8);

// Write data
Object[] row = ...;
writer.writeLine(row);

writer.close();

Design Jsonreader Cn (`docs/design_jsonreader_cn.md`) Copy Section

JSONReader是fastjson2读取JSON数据的底层实现，为了方便不同的输入，分别提供了如下实现：

• JSONReaderUTF16 用于处理输入为char[]的输入，在JDK8下， String会转成char[]，使用JSONReaderUTF16实现；在JDK 9或者更高版本，如果coder=1，也是会使用这个实现。
• JSONReaderUTF8 用于处理输入为utf8编码的byte[]
• JSONReaderASCII是JSONReaderUTF8的派生类，用于处理JDK 9之后coder=0的优化
• JSONReaderJSONB 如果输入是jsonb格式数据时，使用JSONReaderJSONB实现，通过相同的API实现两套协议，一套API

class JSONReader { }

class JSONReaderUTF16 extends JSONReader {
    char[] chars;
}

class JSONReaderUTF8 extends JSONReader {
    byte[] bytes;
}

class JSONReaderASCII extends JSONReaderUTF8 { }

class JSONReaderJSONB extends JSONReader {}

Design Jsonreader En (`docs/design_jsonreader_en.md`) Copy Section

JSONReader is the underlying implementation for reading JSON data in fastjson2. To facilitate different types of input, it provides the following implementations:

• JSONReaderUTF16: Used to process input that is a char[]. Under JDK 8, a String is converted to a char[] and processed using the JSONReaderUTF16 implementation. On JDK 9 or higher, if coder=1, this implementation is also used.
• JSONReaderUTF8: Used to process input that is a UTF-8 encoded byte[].
• JSONReaderASCII: A subclass of JSONReaderUTF8, used for the coder=0 optimization in JDK 9 and later.
• JSONReaderJSONB: If the input is jsonb format data, the JSONReaderJSONB implementation is used, allowing two protocols to be handled through the same single API.

class JSONReader { }

class JSONReaderUTF16 extends JSONReader {
    char[] chars;
}

class JSONReaderUTF8 extends JSONReader {
    byte[] bytes;
}

class JSONReaderASCII extends JSONReaderUTF8 { }

class JSONReaderJSONB extends JSONReader {}

Design Jsonwriter Cn (`docs/design_jsonwriter_cn.md`) Copy Section

JSONWriter是fastjson2序列化的底层实现，针对toJSONString和toJSONBytes两种场景，会使用JSONWriterUTF8和JSONWriterUTF16两种实现。

• JSONWriterUTF16 当使用JSON.toJSONString时，缺省使用JSONWriterUTF16。
• JSONWriterUTF8 当使用JSON.toJSONBytes时，缺省使用JSONWriterUTF8，在使用JSON.toJSONString结合JSONWriter.Feature.OptimizedForAscii使用时，也会用JSONWriterUTF8实现。
• JSONWriterPretty 当JSONWriter.Feature.PrettyFormat启用时，会使用JSONWriterPretty包装一个JSONWriter实现
• JSONWriterJSONB 如果序列化的结果是jsonb格式，使用JSONWriterJSONB实现，通过相同的API实现两套协议，一套API

class JSONWriter { }

class JSONWriterUTF8 extends JSONWriter { }

class JSONWriterUTF16 extends JSONWriter { }

final class JSONWriterPretty extends JSONWriter {
    JSONWriter jsonWriter;

    JSONWriterPretty(JSONWriter jsonWriter) {
        this.jsonWriter = jsonWriter;
    }
}

class JSONWriterJSONB extends JSONWriter { }

Design Jsonwriter En (`docs/design_jsonwriter_en.md`) Copy Section

JSONWriter is the underlying implementation for serialization in fastjson2. For the two scenarios of toJSONString and toJSONBytes, the JSONWriterUTF8 and JSONWriterUTF16 implementations are used.

• JSONWriterUTF16: When JSON.toJSONString is used, JSONWriterUTF16 is used by default.
• JSONWriterUTF8: When JSON.toJSONBytes is used, JSONWriterUTF8 is used by default. The JSONWriterUTF8 implementation is also used when JSON.toJSONString is combined with JSONWriter.Feature.OptimizedForAscii.
• JSONWriterPretty: When JSONWriter.Feature.PrettyFormat is enabled, a JSONWriter implementation is wrapped with JSONWriterPretty.
• JSONWriterJSONB: If the result of serialization is in jsonb format, the JSONWriterJSONB implementation is used, allowing two protocols to be handled through the same single API.

class JSONWriter { }

class JSONWriterUTF8 extends JSONWriter { }

class JSONWriterUTF16 extends JSONWriter { }

final class JSONWriterPretty extends JSONWriter {
    JSONWriter jsonWriter;

    JSONWriterPretty(JSONWriter jsonWriter) {
        this.jsonWriter = jsonWriter;
    }
}

class JSONWriterJSONB extends JSONWriter { }

Fastjson 1 Upgrade Cn (`docs/fastjson_1_upgrade_cn.md`) Copy Section

FASTJSON 1.x升级指南

1. 为什么要升级 Copy Chapter

• 性能更好，具体性能数据 https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark
• 支持JDK新特性，包括JDK 14引入的Record，Lambda表达式的更原生支持，GraalVM Native-Image支持
• 原生支持kotlin
• 支持 JSON Schema https://github.com/alibaba/fastjson2/wiki/json_schema_cn
• 统一文本和二进制API，在RPC、Redis场景也可以使用FASTJSON v2
• 更安全，完全删除autoType白名单，提升安全性 https://github.com/alibaba/fastjson2/wiki/fastjson2_autotype_cn
• 新版本会长期维护，目标为下一个时间提供高性能JSON库，提需求能更快得到响应，提BUG也更快修复

2. 如何升级 Copy Chapter

2.1. 如何获得最新版本 Copy Section

FASTJSON v2项目目前处于活跃状态，会不定期发布新版本，你可以在fastjson2发布地址中获得最新版本 https://github.com/alibaba/fastjson2/releases

可以两种模式升级：

• 兼容模式
• 使用fastjson v2新的API

2.2. 兼容模式升级 Copy Section

升级可以通过兼容模式升级，兼容模式不需要改代码，但在深度使用的场景，不能做到完全兼容，通过这样的模式升级虽然省事，但请认真测试，遇到问题反馈到 https://github.com/alibaba/fastjson2/issues

• 兼容模式Maven依赖

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

2.3. 使用新API升级 Copy Section

使用新API是建议的升级方式，使用新的API能获得更多的功能。

• 包名变更
  FASTJSON v2和1.x版本使用不同的package，新的package名称是com.alibaba.fastjson2，新package和之前不同，可以实现1.x和2.x共存

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import com.alibaba.fastjson2.JSONArray;

• Maven依赖
  Maven依赖的groupId和1.x不同，使用了新的groupIdcom.alibaba.fastjson2

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

如果你需要用到spring支持的功能，还需要依赖fastjson2-extension

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

如果你是在kotlin中使用fastjson，需要依赖fastjson2-kotlin

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

3. 常见问题 Copy Chapter

3.1. ParserConfig.getGlobalInstance().addAccept()如何兼容 Copy Section

在2.x版本中，ParserConfig添加autoType白名单的功能在ObjectReaderProvider中提供，可以如下的方式配置autoType白名单。

JSONFactory.getDefaultObjectReaderProvider().addAutoTypeAccept("com.mycompany.xxx");

3.2. ObjectSerializer 和 ObjectDeserializer 被移除了，有什么新的代替方案 Copy Section

FASTJSON v2中有比较完善的扩展机制，如下：

• Annotation介绍 https://alibaba.github.io/fastjson2/annotations_cn
• Annotation注入介绍 https://alibaba.github.io/fastjson2/mixin_cn
• Feature介绍 https://alibaba.github.io/fastjson2/features_cn
• 使用Mixin注入Annotation定制序列化和反序列化 https://alibaba.github.io/fastjson2/mixin_cn
• 实现ObjectWriter和ObjectReader实现定制序列化和反序列化 https://alibaba.github.io/fastjson2/register_custom_reader_writer_cn

3.3. 常见的类扩展升级映射 Copy Section

3.4 SerializerFeature.UseISO8601DateFormat在fastjson2的替代方案 Copy Section

fastjson2的JSONWriter.Feature没有和UseISO8601DateFormat的Feature，代替方法是使用format="iso8601"，如下：

import com.alibaba.fastjson2.JSON;

String format = "iso8601";
JSON.toJSONString(obj, format);

3.5 SerializerFeature.DisableCircularReferenceDetect在fastjson2的替代方案 Copy Section

在fastjson2中，代替的是JSONWriter.Feature.ReferenceDetection，但语义相反，缺省不一样。fastjson2中的JSONWriter.Feature.ReferenceDetection缺省是关闭的，而fastjson1缺省是打开的。

3.6 SerializerFeature.SortField在fastjson2的替代方案 Copy Section

不需要，在fastjson2中，JSONObject继承自LinkedHashMap，不需要配置这个Feature

3.7 SerializerFeature.WriteDateUseDateFormat在fastjson2的替代方案 Copy Section

在fastjson2中的缺省行为就是使用dateFormat，如果要修改为成和fastjson 1.x一样的行为，需要配置format = "millis"，如下：

import com.alibaba.fastjson2.JSON;

String format = "millis";
JSON.toJSONString(obj, format);

Fastjson 1 Upgrade En (`docs/fastjson_1_upgrade_en.md`) Copy Section

FASTJSON 1.x Upgrade Guide

1. Why Upgrade? Copy Chapter

• Better Performance: For detailed performance data, see https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark_en
• Support for New JDK Features: Includes support for Records introduced in JDK 14, more native support for Lambda expressions, and GraalVM Native-Image support.
• Native Kotlin Support
• Support for JSON Schema: https://github.com/alibaba/fastjson2/wiki/json_schema_en
• Unified Text and Binary API: FASTJSON v2 can also be used in RPC and Redis scenarios.
• More Secure: The autoType whitelist has been completely removed to enhance security. https://github.com/alibaba/fastjson2/wiki/fastjson2_autotype_en
• Long-Term Maintenance: The new version will be maintained for the long term, aiming to provide a high-performance JSON library for the future. Feature requests will get faster responses, and bugs will be fixed more quickly.

2. How to Upgrade Copy Chapter

2.1. How to Get the Latest Version Copy Section

The FASTJSON v2 project is currently active, and new versions are released from time to time. You can get the latest version from the fastjson2 release page: https://github.com/alibaba/fastjson2/releases

You can upgrade in two modes:

• Compatibility Mode
• Using the new fastjson v2 API

2.2. Upgrading in Compatibility Mode Copy Section

You can upgrade using compatibility mode, which does not require code changes. However, in scenarios of deep usage, it may not be fully compatible. Although this mode is convenient, please test thoroughly and report any issues to https://github.com/alibaba/fastjson2/issues.

• Compatibility Mode Maven Dependency

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

2.3. Upgrading Using the New API Copy Section

Using the new API is the recommended upgrade method, as it provides access to more features.

• Package Name Change
  FASTJSON v2 and v1.x use different package names. The new package name is com.alibaba.fastjson2. Because the new package is different, v1.x and v2.x can coexist.

import com.alibaba.fastjson2.JSON;
import com.alibaba.fastjson2.JSONObject;
import com.alibaba.fastjson2.JSONArray;

• Maven Dependency
  The groupId for the Maven dependency is different from v1.x; it uses the new groupId com.alibaba.fastjson2.

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

If you need Spring support, you also need to depend on fastjson2-extension:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

If you are using fastjson in Kotlin, you need to depend on fastjson2-kotlin:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>${fastjson2.version}</version>
</dependency>

3. Common Issues Copy Chapter

3.1. How to make `ParserConfig.getGlobalInstance().addAccept()` compatible? Copy Section

In v2, the functionality to add an autoType whitelist to ParserConfig is provided by ObjectReaderProvider. You can configure the autoType whitelist as follows:

JSONFactory.getDefaultObjectReaderProvider().addAutoTypeAccept("com.mycompany.xxx");

3.2. `ObjectSerializer` and `ObjectDeserializer` have been removed. What are the new alternatives? Copy Section

FASTJSON v2 has a more comprehensive extension mechanism, as follows:

• Annotation Introduction: https://alibaba.github.io/fastjson2/annotations_en
• Annotation Mixin Introduction: https://alibaba.github.io/fastjson2/mixin_en
• Feature Introduction: https://alibaba.github.io/fastjson2/features_en
• Using Mixin to customize serialization and deserialization: https://alibaba.github.io/fastjson2/mixin_en
• Implementing ObjectWriter and ObjectReader for custom serialization and deserialization: https://alibaba.github.io/fastjson2/register_custom_reader_writer_en

3.3. Common Class Extension Upgrade Mapping Copy Section

3.4 Alternative for `SerializerFeature.UseISO8601DateFormat` in fastjson2 Copy Section

fastjson2's JSONWriter.Feature does not have a feature corresponding to UseISO8601DateFormat. The alternative is to use format="iso8601", as shown below:

import com.alibaba.fastjson2.JSON;

String format = "iso8601";
JSON.toJSONString(obj, format);

3.5 Alternative for `SerializerFeature.DisableCircularReferenceDetect` in fastjson2 Copy Section

In fastjson2, the alternative is JSONWriter.Feature.ReferenceDetection, but the semantics are opposite, and the default is different. JSONWriter.Feature.ReferenceDetection in fastjson2 is disabled by default, whereas in fastjson1 it was enabled by default.

3.6 Alternative for `SerializerFeature.SortField` in fastjson2 Copy Section

Not needed. In fastjson2, JSONObject inherits from LinkedHashMap, so this feature is not necessary.

3.7 Alternative for `SerializerFeature.WriteDateUseDateFormat` in fastjson2 Copy Section

The default behavior in fastjson2 is to use a date format. To change it to behave like fastjson 1.x (outputting milliseconds), you need to configure format = "millis", as shown below:

import com.alibaba.fastjson2.JSON;

String format = "millis";
JSON.toJSONString(obj, format);

Features Cn (`docs/features_cn.md`) Copy Section

通过Features配置序列化和反序列化的行为

1. Feature介绍

在fastjson 2.x中，有两个Feature，分别用来配置序列化和反序列化的行为。

• JSONWriter.Feature 配置序列化的行为
• JSONReader.Feature 配置反序列化的行为

2. 在JSON的toJSONString和parse方法中使用Feature

2.1 在JSON的toJSONString方法中使用JSONWriter.Feature Copy Chapter

Bean bean = ...;
String json = JSON.toJSONString(bean, JSONWriter.Feature.WriteNulls); // 输出对象中值为null的字段

2.2 在JSON的parse方法中使用JSONReader.Feature Copy Chapter

String jsonStr = ...;
Bean bean = JSON.parseObject(jsonStr, Bean.class, JSONReader.Feature.UseBigDecimalForDoubles); // 将小数数值读取为BigDecimal

3. 在JSONField和JSONType上配置features

class Model {
    @JSONField(serializeFeatures = JSONWriter.Feature.BrowserCompatible)
    public long value;
}

也可以在类级别使用JSONType注解：

@JSONType(serializeFeatures = JSONWriter.Feature.WriteMapNullValue)
public class Model {
    public String name;
    public int age;
}

4. JSONReader.Feature 介绍

5. JSONWriter.Feature 介绍

6. 使用示例

6.1 序列化示例 Copy Chapter

// 基本使用
User user = new User(\"张三\", 25, null);
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

// 多个Feature组合使用
String json2 = JSON.toJSONString(user, 
    JSONWriter.Feature.WriteNulls, 
    JSONWriter.Feature.PrettyFormat);

// 使用BeanToArray特性
String json3 = JSON.toJSONString(user, JSONWriter.Feature.BeanToArray);

6.2 反序列化示例 Copy Chapter

// 基本使用
String json = \"{\\\"name\\\":\\\"张三\\\",\\\"age\\\":25}\";
User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportSmartMatch);

// 多个Feature组合使用
User user2 = JSON.parseObject(json, User.class, 
    JSONReader.Feature.SupportSmartMatch, 
    JSONReader.Feature.InitStringFieldAsEmpty);

7. 1.x 特性变更指南

7.1 默认开启的特性 Copy Chapter

在 fastjson 1.x 中，默认开启的特性如下：

序列化：

• SerializerFeature.QuoteFieldNames
• SerializerFeature.SkipTransientField
• SerializerFeature.WriteEnumUsingName
• SerializerFeature.SortField

反序列化：

• Feature.AutoCloseSource
• Feature.InternFieldNames
• Feature.UseBigDecimal
• Feature.AllowUnQuotedFieldNames
• Feature.AllowSingleQuotes
• Feature.AllowArbitraryCommas
• Feature.SortFeidFastMatch
• Feature.IgnoreNotMatch

在 fastjson 2.x 中，所有特性默认关闭。

7.2 1.x特性变更 Copy Chapter

序列化：

• QuoteFieldNames：2.x默认支持，无需配置。且2.x支持UnquoteFieldName特性
• UseISO8601DateFormat：2.x中替代方案如下：
  • JSON.configWriterDateFormat("iso8601")（全局配置）
  • JSON.toJSONString(bean, "iso8601")
  • @JSONField(format = "iso8601")
• SkipTransientField；2.x默认支持，若要关闭，方案如下：
  • JVM参数配置 -Dfastjson2.writer.skipTransient=false（全局配置）
  • JSONFactory.setDefaultSkipTransient(false)（全局配置）
  • @JSONType(skipTransient = false)
  • @JSONField(skipTransient = false)
• SortField：2.x默认支持，无需配置
• WriteDateUseDateFormat：2.x中替代方案如下：
  • JSON.toJSONString(bean, "millis")
  • 使用2.0.58中新增加的特性JSONWriter.Feature.WriterUtilDateAsMillis
• DisableCircularReferenceDetect：1.x中默认有循环引用检测，2.x则默认关闭。2.x若要开启，使用特性ReferenceDetection
• WriteEnumUsingName：2.x中默认关闭
• WriteSlashAsSpecial：2.x未支持
• WriteTabAsSpecial、DisableCheckSpecialChar在1.x中已弃用
• 其余1.x序列化特性无变化

反序列化：

• AllowArbitraryCommas：2.x的语法更加严格，不支持多重逗号
• AllowComment：2.x默认支持，无需配置
• AllowISO8601DateFormat：2.x默认支持，也可通过以下方式显式指定：
  • JSON.configReaderDateFormat("iso8601")（全局配置）
  • JSON.parseObject(str, Bean.class, "iso8601")
• AllowSingleQuotes：2.x默认支持，无需配置
• AutoCloseSource（反序列化不完整JSON抛出异常）：2.x默认支持，无需配置
• CustomMapDeserializer：2.x未支持
• DisableCircularReferenceDetect：更名为DisableReferenceDetect
• DisableFieldSmartMatch：替换为SupportSmartMatch（1.x中智能匹配默认开启，2.x中智能匹配默认关闭）
• DisableSpecialKeyDetect：2.x默认支持，无需配置
• IgnoreAutoType：2.x默认关闭AutoType功能，缺省配置下是安全的
• IgnoreNotMatch：2.x默认支持，无需配置
• OrderedField（反序列化为JSONObject、JSONArray时，保证声明顺序）：2.x默认支持，无需配置
• SupportNonPublicField：可替换为FieldBased
• SafeMode：2.x可通过JVM参数配置 -Dfastjson2.parser.safeMode=true
• TrimStringFieldValue：可替换为TrimString
• UseBigDecimal：替换为UseBigDecimalForFloats、UseBigDecimalForDoubles
• UseNativeJavaObject：更名为UseNativeObject
• UseObjectArray（JSON数组解析为Object[]而非ArrayList）：2.x未支持
• 其余1.x反序列化特性无变化

8. 最佳实践建议

1. 安全性考虑：

   • 默认情况下不要开启SupportAutoType，除非确实需要处理带类型信息的JSON
   • 对于不受信任的数据源，谨慎使用FieldBased特性

2. 性能优化：

   • 对于大数据量的序列化，可以考虑使用BeanToArray特性来减小JSON体积
   • 在需要保持字段顺序的场景下，使用MapSortField特性

3. 兼容性处理：

   • 在Web前端场景中，使用BrowserCompatible来处理大整数
   • 对于需要严格数据格式的场景，开启ErrorOnEnumNotMatch来及时发现枚举不匹配问题

4. 空值处理：

   • 根据业务需求选择合适的空值处理策略，如WriteNulls、WriteNullStringAsEmpty等

Features En (`docs/features_en.md`) Copy Section

Configure serialization and deserialization with `Features`

1. Feature Introduction

In fastjson 2.x, there are two Features, which are used to configure the behavior of serialization and deserialization respectively.

• JSONWriter.Feature Configure serialization behavior
• JSONReader.Feature Configure deserialization behavior

2. Using Feature in JSON `toJSONString` and `parseObject` methods

2.1 Using `JSONWriter.Feature` in JSON `toJSONString` method Copy Chapter

Bean bean = ...;
String json = JSON.toJSONString(bean, JSONWriter.Feature.WriteNulls); // Fields in the output object whose value is null

2.2 Using `JSONReader.Feature` in JSON `parseObject` method Copy Chapter

String jsonStr = ...;
Bean bean = JSON.parseObject(jsonStr, Bean.class, JSONReader.Feature.UseBigDecimalForDoubles); // Read decimal values as BigDecimal

3. Configure Features on `JSONField` and `JSONType`

class Model {
    @JSONField(serializeFeatures = JSONWriter.Feature.BrowserCompatible)
    public long value;
}

You can also use the @JSONType annotation at the class level:

@JSONType(serializeFeatures = JSONWriter.Feature.WriteMapNullValue)
public class Model {
    public String name;
    public int age;
}

4. JSONReader.Feature Introduction

5. JSONWriter.Feature Introduction

6. Usage Examples

6.1 Serialization Examples Copy Chapter

// Basic usage
User user = new User("John", 25, null);
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

// Combining multiple Features
String json2 = JSON.toJSONString(user, 
    JSONWriter.Feature.WriteNulls, 
    JSONWriter.Feature.PrettyFormat);

// Using BeanToArray feature
String json3 = JSON.toJSONString(user, JSONWriter.Feature.BeanToArray);

6.2 Deserialization Examples Copy Chapter

// Basic usage
String json = "{\"name\":\"John\",\"age\":25}";
User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportSmartMatch);

// Combining multiple Features
User user2 = JSON.parseObject(json, User.class, 
    JSONReader.Feature.SupportSmartMatch, 
    JSONReader.Feature.InitStringFieldAsEmpty);

7. 1.x Feature Migration Guide

7.1 Features Enabled by Default Copy Chapter

In fastjson 1.x, the default enabled features are as follows:

Serialization

• SerializerFeature.QuoteFieldNames
• SerializerFeature.SkipTransientField
• SerializerFeature.WriteEnumUsingName
• SerializerFeature.SortField

Deserialization

• Feature.AutoCloseSource
• Feature.InternFieldNames
• Feature.UseBigDecimal
• Feature.AllowUnQuotedFieldNames
• Feature.AllowSingleQuotes
• Feature.AllowArbitraryCommas
• Feature.SortFeidFastMatch
• Feature.IgnoreNotMatch

In fastjson 2.x, all features are OFF by default.

7.2 Changes from 1.x to 2.x Copy Chapter

Serialization:

• QuoteFieldNames: Enabled by default in 2.x; no configuration required. And 2.x supports the UnquoteFieldName feature.
• UseISO8601DateFormat: Replaced in 2.x by:
  • JSON.configWriterDateFormat("iso8601") (global)
  • JSON.toJSONString(bean, "iso8601")
  • @JSONField(format = "iso8601")
• SkipTransientField: Enabled by default in 2.x. To disable:
  • JVM system property -Dfastjson2.writer.skipTransient=false
  • JSONFactory.setDefaultSkipTransient(false)
  • @JSONType(skipTransient = false)
  • @JSONField(skipTransient = false)
• SortField: Enabled by default in 2.x; no configuration required.
• WriteDateUseDateFormat: Alternatives in 2.x:
  • JSON.toJSONString(bean, "millis")
  • JSONWriter.Feature.WriterUtilDateAsMillis (since 2.0.58)
• DisableCircularReferenceDetect: 1.x detects circular refs by default; 2.x does not. To turn detection on in 2.x use ReferenceDetection.
• WriteEnumUsingName: Disabled by default in 2.x.
• WriteSlashAsSpecial: Not supported in 2.x.
• WriteTabAsSpecial & DisableCheckSpecialChar: Already deprecated in 1.x; removed in 2.x.
• All other 1.x serialization features remain unchanged.

Deserialization:

• AllowArbitraryCommas: 2.x uses strict syntax; multiple commas are not allowed.
• AllowComment: Enabled by default in 2.x; no configuration required.
• AllowISO8601DateFormat: Enabled by default in 2.x. Explicit settings:
  • JSON.configReaderDateFormat("iso8601")
  • JSON.parseObject(str, Bean.class, "iso8601")
• AllowSingleQuotes: Enabled by default in 2.x; no configuration required.
• AutoCloseSource (throw on incomplete JSON): Enabled by default in 2.x; no configuration required.
• CustomMapDeserializer: Not supported in 2.x.
• DisableCircularReferenceDetect: Renamed to DisableReferenceDetect.
• DisableFieldSmartMatch: Replaced by SupportSmartMatch. (Smart matching was ON in 1.x, OFF by default in 2.x.)
• DisableSpecialKeyDetect: Enabled by default in 2.x; no configuration required.
• IgnoreAutoType: 2.x disables AutoType by default; safe out-of-the-box.
• IgnoreNotMatch: Enabled by default in 2.x; no configuration required.
• OrderedField (keep declaration order for JSONObject / JSONArray): Enabled by default in 2.x; no configuration required.
• SupportNonPublicField: Use FieldBased in 2.x.
• SafeMode: 2.x: JVM system property -Dfastjson2.parser.safeMode=true.
• TrimStringFieldValue: Use JSONReader.Feature.TrimString in 2.x.
• UseBigDecimal: Split into UseBigDecimalForFloats and UseBigDecimalForDoubles in 2.x.
• UseNativeJavaObject: Renamed to UseNativeObject.
• UseObjectArray (parse JSON arrays as Object[] instead of ArrayList): Not supported in 2.x.
• All other 1.x deserialization features remain unchanged.

8. Best Practices

1. Security Considerations:

   • Do not enable SupportAutoType by default unless you really need to process JSON with type information
   • Be cautious when using the FieldBased feature with untrusted data sources

2. Performance Optimization:

   • For large data serialization, consider using the BeanToArray feature to reduce JSON size
   • Use the MapSortField feature when field order needs to be maintained

3. Compatibility Handling:

   • Use BrowserCompatible for web front-end scenarios to handle large integers
   • Enable ErrorOnEnumNotMatch in scenarios requiring strict data format to quickly identify enum mismatches

4. Null Value Handling:

   • Choose appropriate null value handling strategies based on business requirements, such as WriteNulls, WriteNullStringAsEmpty, etc.

Jsontype Seealso Cn (`docs/jsontype_seealso_cn.md`) Copy Section

在fastjson中，可以使用Annotation JSONType#seeAlso配置，类似于JAXB中的XmlSeeAlso。用法如下：

JavaBean Config Copy Section

@JSONType(seeAlso={Dog.class, Cat.class})
public static class Animal {
}

@JSONType(typeName = "dog")
public static class Dog extends Animal {
    public String dogName;
}

@JSONType(typeName = "cat")
public static class Cat extends Animal {
    public String catName;
}

Usage

Dog dog = new Dog();
dog.dogName = "dog1001";

String text = JSON.toJSONString(dog, SerializerFeature.WriteClassName);
Assert.assertEquals("{\"@type\":\"dog\",\"dogName\":\"dog1001\"}", text);

Dog dog2 = (Dog) JSON.parseObject(text, Animal.class);

Assert.assertEquals(dog.dogName, dog2.dogName);

Cat cat = new Cat();
cat.catName = "cat2001";

String text = JSON.toJSONString(cat, SerializerFeature.WriteClassName);
Assert.assertEquals("{\"@type\":\"cat\",\"catName\":\"cat2001\"}", text);

Cat cat2 = (Cat) JSON.parseObject(text, Animal.class);

Assert.assertEquals(cat.catName, cat2.catName);

Jsontype Seealso En (`docs/jsontype_seealso_en.md`) Copy Section

In Fastjson, you can use the JSONType#seeAlso annotation for configuration, which is similar to XmlSeeAlso in JAXB. The usage is as follows:

JavaBean Config Copy Section

@JSONType(seeAlso={Dog.class, Cat.class})
public static class Animal {
}

@JSONType(typeName = "dog")
public static class Dog extends Animal {
    public String dogName;
}

@JSONType(typeName = "cat")
public static class Cat extends Animal {
    public String catName;
}

Usage

Dog dog = new Dog();
dog.dogName = "dog1001";

String text = JSON.toJSONString(dog, SerializerFeature.WriteClassName);
Assert.assertEquals("{\"@type\":\"dog\",\"dogName\":\"dog1001\"}", text);

Dog dog2 = (Dog) JSON.parseObject(text, Animal.class);

Assert.assertEquals(dog.dogName, dog2.dogName);

Cat cat = new Cat();
cat.catName = "cat2001";

String text = JSON.toJSONString(cat, SerializerFeature.WriteClassName);
Assert.assertEquals("{\"@type\":\"cat\",\"catName\":\"cat2001\"}", text);

Cat cat2 = (Cat) JSON.parseObject(text, Animal.class);

Assert.assertEquals(cat.catName, cat2.catName);

Maven Deploy Guide (`docs/maven_deploy_guide.md`) Copy Section

`FASTJSON2`发布操作说明

FASTJSON2发布到Maven中央库的操作过程/CheckList。

0. 前置准备与配置 Copy Chapter

在Maven的settting.xml中配置https://central.sonatype.com账号：

<servers>
    <server>
        <id>central</id>
        <username>__YOUR_USERNAME__</username>
        <password>__YOUR_PASSWORD__</password>
    </server>
</servers>

更多发布操作说明（如用于GPG签名的GPG安装与配置），参见：

• Maven Central Portal Getting Started
  https://central.sonatype.org/publish/publish-portal-guide/
• Maven Central Portal Publishing By Using the Maven Plugin
  https://central.sonatype.org/publish/publish-portal-maven/

发布过程与发布文件的查看地址：

• Maven Central Portal 的发布控制台
  https://central.sonatype.com
• Maven中央库的文件查看
  https://repo1.maven.org/maven2/com/alibaba/fastjson2/

1. 发布操作 Copy Chapter

1. 如果发布正式版本，先确认版本号，去掉SNAPSHOT，如2.x.y。

2. 更新版本操作可以通过脚本scripts/bump_fastjson2_version来统一完成。

   bash Copy

   scripts/bump_fastjson2_version 2.x.y

3. 在工程根目录，执行发布

   bash Copy

   ./mvnw clean && ./mvnw deploy -DperformRelease

Mixin Cn (`docs/mixin_cn.md`) Copy Section

使用Mixin注入Annotation定制序列化和反序列化

当你需要定制化序列化一些LIB里面的类，你无法修改这些类的代码，你可以使用FASTJSON2的Mixin功能注入Annotation。

比如：

1. 要序列化的类 Copy Chapter

public static class Product {
    public String name;
}

2. 注入配置类 Copy Chapter

public abstract class ProductMixin {
    @JSONField(name =  "productName")
    String name;
}

3. 注入配置 & 使用 Copy Chapter

// 配置注入
JSON.mixIn(Product.class, ProductMixin.class);

// 使用
Product product = new Product();
product.name = "DataWorks";
assertEquals("{\"productName\":\"DataWorks\"}", JSON.toJSONString(product));

Product productParsed = JSON.parseObject("{\"productName\":\"DataWorks\"}", Product.class);
assertEquals("DataWorks", productParsed.name);

4. 结合JSONCreator & JSONField(value=true)的例子 Copy Chapter

如下的Address类，没有缺省构造函数，只有一个字段，我希望序列化结果为address字段的字符串。

public static class Address {
    private final String address;

    public Address(String address) {
        this.address = address;
    }

    public String getAddress() {
        return address;
    }
}

注入使用方式如下：

static class AddressMixin {
    // 通过JSONCreator指定构造函数
    @JSONCreator
    public AddressMixin(@JSONField(value = true) String address) {
    }

    // 配置输出使用此字段
    @JSONField(value = true)
    public String getAddress() {
        return null;
    }
}

@Test
public void test() {
    JSON.mixIn(Address.class, AddressMixin.class); // 通过mixin注入Annotation

    Address address = new Address("HangZhou");

    // 序列化输出结果为address字段
    String str = JSON.toJSONString(address); 
    assertEquals("\"HangZhou\"", str); 

    // 通过结果可以看出使用了JSONCreator指定的构造函数
    Address address1 = JSON.parseObject(str, Address.class);
    assertEquals(address.getAddress(), address1.getAddress()); 
}

Mixin En (`docs/mixin_en.md`) Copy Section

Using Mixin to Inject Annotations for Custom Serialization and Deserialization

When you need to customize the serialization of classes from a library whose code you cannot modify, you can use FASTJSON2's Mixin feature to inject annotations.

For example:

1. The Class to be Serialized Copy Chapter

public static class Product {
    public String name;
}

2. The Mixin Configuration Class Copy Chapter

public abstract class ProductMixin {
    @JSONField(name =  "productName")
    String name;
}

3. Injecting the Configuration & Usage Copy Chapter

// Configure injection
JSON.mixIn(Product.class, ProductMixin.class);

// Usage
Product product = new Product();
product.name = "DataWorks";
assertEquals("{\"productName\":\"DataWorks\"}", JSON.toJSONString(product));

Product productParsed = JSON.parseObject("{\"productName\":\"DataWorks\"}", Product.class);
assertEquals("DataWorks", productParsed.name);

4. Example with JSONCreator & JSONField(value=true) Copy Chapter

Consider the following Address class, which has no default constructor and only one field. We want the serialization result to be the string value of the address field.

public static class Address {
    private final String address;

    public Address(String address) {
        this.address = address;
    }

    public String getAddress() {
        return address;
    }
}

The injection and usage are as follows:

static class AddressMixin {
    // Specify the constructor with @JSONCreator
    @JSONCreator
    public AddressMixin(@JSONField(value = true) String address) {
    }

    // Configure the output to use this field
    @JSONField(value = true)
    public String getAddress() {
        return null;
    }
}

@Test
public void test() {
    JSON.mixIn(Address.class, AddressMixin.class); // Inject annotations via mixin

    Address address = new Address("HangZhou");

    // The serialization output is the value of the address field
    String str = JSON.toJSONString(address); 
    assertEquals("\"HangZhou\"", str); 

    // The result shows that the constructor specified by @JSONCreator was used
    Address address1 = JSON.parseObject(str, Address.class);
    assertEquals(address.getAddress(), address1.getAddress()); 
}

Performance Cn (`docs/performance_cn.md`) Copy Section

性能优化指南

FASTJSON 2 以极致性能为设计目标。本指南介绍调优策略和最佳实践，帮助您充分发挥库的性能。

性能架构 Copy Chapter

FASTJSON 2 通过以下关键优化实现高性能：

ASM 代码生成 Copy Section

FASTJSON 2 在运行时使用 ASM 为对象读取器和写入器生成优化的字节码，消除了字段访问和方法调用的反射开销。生成的代码使用基于字段名称哈希的 switch-case 语句，在反序列化时实现 O(1) 的字段查找。

• 时机: 首次序列化/反序列化某类型时（一次性开销）
• 实现: ObjectReaderCreatorASM、ObjectWriterCreatorASM
• 降级: 当 ASM 不可用时使用反射创建器（Android、GraalVM Native Image）

Lambda Metafactory Copy Section

在 JDK 8+ 上，FASTJSON 2 使用 LambdaMetafactory 创建高性能方法句柄，作为反射的替代方案。这为 getter/setter 调用提供接近原生调用的性能。

Vector API（JDK 17+） Copy Section

在 JDK 17+ 上，FASTJSON 2 利用 Vector API 的 SIMD（单指令多数据）指令进行 UTF-8 和 UTF-16 解析器中的批量字符处理。这极大地加速了字符串扫描和验证。

字符串驻留 Copy Section

SymbolTable 为频繁使用的字段名称提供高效的字符串驻留，减少解析过程中的内存分配和 GC 压力。

编码特化解析器 Copy Section

FASTJSON 2 为不同编码提供专用的解析器实现：

• JSONReaderUTF8 - 针对 UTF-8 字节流优化
• JSONReaderUTF16 - 针对 UTF-16（Java String 内部表示）优化
• JSONReaderASCII - 纯 ASCII 内容的快速路径

库会根据输入类型自动检测最优解析器。

调优策略 Copy Chapter

1. 优先使用 byte[] 而非 String Copy Section

影响: 高

尽量直接使用 byte[] 而非 String：

// 更快：从 bytes 解析
byte[] bytes = getJsonBytes(); // 来自网络、文件等
User user = JSON.parseObject(bytes, User.class);

// 更快：序列化为 bytes
byte[] output = JSON.toJSONBytes(user);

这避免了 String 编码/解码的开销，在 HTTP/RPC 场景中尤其有效。

2. 内部通信使用 JSONB Copy Section

影响: 非常高

对于服务间通信，JSONB（二进制 JSON）比文本 JSON 提供 3-9 倍的性能提升和更小的数据体积：

// 序列化
byte[] bytes = JSONB.toBytes(user);

// 反序列化
User user = JSONB.parseObject(bytes, User.class);

// 配合 BeanToArray 更快
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportArrayToBean);

3. 大文档使用 JSONPath 部分解析 Copy Section

影响: 高（针对大型文档）

当只需从大型 JSON 文档中获取特定字段时，使用 JSONPath 提取而无需解析整个文档：

// 缓存 JSONPath 实例（线程安全）
static final JSONPath ID_PATH = JSONPath.of("$.id");
static final JSONPath NAME_PATH = JSONPath.of("$.name");

// 提取特定字段
Object id = ID_PATH.extract(JSONReader.of(json));
Object name = NAME_PATH.extract(JSONReader.of(json));

4. 使用 BeanToArray 紧凑序列化 Copy Section

影响: 中

BeanToArray Feature 将对象序列化为 JSON 数组而非对象，去除字段名开销：

// 输出: [1,"John",25] 而非 {"id":1,"name":"John","age":25}
String json = JSON.toJSONString(user, JSONWriter.Feature.BeanToArray);
User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportArrayToBean);

5. 最小化 Feature 使用 Copy Section

影响: 低-中

每个启用的 Feature 在热路径中增加一个条件检查。仅启用实际需要的 Feature：

// 好：仅启用需要的
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

// 避免：启用很多"以防万一"的 Feature
String json = JSON.toJSONString(user,
    JSONWriter.Feature.WriteNulls,
    JSONWriter.Feature.PrettyFormat,        // 不需要就跳过
    JSONWriter.Feature.ReferenceDetection,  // 没有循环引用就跳过
    JSONWriter.Feature.MapSortField);       // 不关心顺序就跳过

6. 使用 FieldBased 获取最大速度 Copy Section

影响: 中

FieldBased 模式直接访问字段而非通过 getter/setter 方法，速度略快：

String json = JSON.toJSONString(user, JSONWriter.Feature.FieldBased);
User user = JSON.parseObject(json, User.class, JSONReader.Feature.FieldBased);

注意：这通过反射/ASM 访问私有字段，可能在所有环境中都不可用。

7. 缓存自定义类型的 ObjectReader/ObjectWriter Copy Section

影响: 中

如果注册了自定义 reader/writer，确保它们是单例：

// 好：单例模式
class MoneyWriter implements ObjectWriter<Money> {
    static final MoneyWriter INSTANCE = new MoneyWriter();
    // ...
}
JSON.register(Money.class, MoneyWriter.INSTANCE);

线程安全 Copy Chapter

了解线程安全有助于避免不必要的同步：

JVM 调优 Copy Chapter

推荐 JVM 参数 Copy Section

# 启用紧凑字符串（JDK 9+，默认开启）
-XX:+CompactStrings

# JDK 17+，启用 Vector API 孵化器模块
--add-modules jdk.incubator.vector

内存注意事项 Copy Section

• FASTJSON 2 使用线程本地缓冲区进行序列化，减少 GC 压力但增加每线程内存占用。
• 对于多线程应用，请监控线程本地缓冲区使用情况。
• JSONB 通常比文本 JSON 使用更少的内存，因为编码更紧凑。

性能测试 Copy Chapter

FASTJSON 2 在 benchmark/ 模块中包含 JMH 基准测试。运行方式：

cd benchmark
mvn clean package
java -jar target/benchmarks.jar

已发布的与 Jackson、Gson 等库的对比测试结果请参阅：

• 性能测试结果
• JSONB vs Hessian/Kryo
• Android 性能测试

Performance En (`docs/performance_en.md`) Copy Section

Performance Guide

FASTJSON 2 is designed for maximum performance. This guide covers tuning strategies and best practices to get the most out of the library.

Performance Architecture Copy Chapter

FASTJSON 2 achieves its performance through several key optimizations:

ASM Code Generation Copy Section

At runtime, FASTJSON 2 generates optimized bytecode for object readers and writers using ASM. This eliminates reflection overhead for field access and method invocation. The generated code uses switch-case statements on field name hashes for O(1) field lookup during deserialization.

• When: First time a type is serialized/deserialized (one-time cost)
• Where: ObjectReaderCreatorASM, ObjectWriterCreatorASM
• Fallback: Reflection-based creator when ASM is unavailable (Android, GraalVM Native Image)

Lambda Metafactory Copy Section

On JDK 8+, FASTJSON 2 uses LambdaMetafactory to create high-performance method handles as an alternative to reflection. This provides near-native-call performance for getter/setter invocations.

Vector API (JDK 17+) Copy Section

On JDK 17+, FASTJSON 2 leverages SIMD (Single Instruction, Multiple Data) instructions via the Vector API for bulk character processing in UTF-8 and UTF-16 parsers. This dramatically accelerates string scanning and validation.

String Interning Copy Section

The SymbolTable provides efficient string interning for frequently used field names, reducing memory allocation and GC pressure during parsing.

Encoding-Specific Parsers Copy Section

FASTJSON 2 has dedicated parser implementations for different encodings:

• JSONReaderUTF8 - optimized for UTF-8 byte streams
• JSONReaderUTF16 - optimized for UTF-16 (Java String internal representation)
• JSONReaderASCII - fast path for ASCII-only content

The library auto-detects the optimal parser based on input type.

Tuning Strategies Copy Chapter

1. Prefer byte[] Over String Copy Section

Impact: High

When possible, work with byte[] directly instead of String:

// Faster: parse from bytes
byte[] bytes = getJsonBytes(); // from network, file, etc.
User user = JSON.parseObject(bytes, User.class);

// Faster: serialize to bytes
byte[] output = JSON.toJSONBytes(user);

This avoids the overhead of String encoding/decoding. It is especially effective for HTTP/RPC scenarios where data arrives as bytes.

2. Use JSONB for Internal Communication Copy Section

Impact: Very High

For service-to-service communication, JSONB (binary JSON) provides 3-9x faster performance and smaller payload sizes compared to text JSON:

// Serialize
byte[] bytes = JSONB.toBytes(user);

// Deserialize
User user = JSONB.parseObject(bytes, User.class);

// Even faster with BeanToArray
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportArrayToBean);

3. Use JSONPath for Partial Parsing Copy Section

Impact: High (for large documents)

When you only need specific fields from a large JSON document, use JSONPath to extract them without parsing the entire document:

// Cache the JSONPath instance (thread-safe)
static final JSONPath ID_PATH = JSONPath.of("$.id");
static final JSONPath NAME_PATH = JSONPath.of("$.name");

// Extract specific fields
Object id = ID_PATH.extract(JSONReader.of(json));
Object name = NAME_PATH.extract(JSONReader.of(json));

4. Use BeanToArray for Compact Serialization Copy Section

Impact: Medium

The BeanToArray feature serializes objects as JSON arrays instead of objects, removing field name overhead:

// Output: [1,"John",25] instead of {"id":1,"name":"John","age":25}
String json = JSON.toJSONString(user, JSONWriter.Feature.BeanToArray);
User user = JSON.parseObject(json, User.class, JSONReader.Feature.SupportArrayToBean);

5. Minimize Feature Usage Copy Section

Impact: Low-Medium

Each enabled Feature adds a condition check in the hot path. Only enable features you actually need:

// Good: only enable what you need
String json = JSON.toJSONString(user, JSONWriter.Feature.WriteNulls);

// Avoid: enabling many features "just in case"
String json = JSON.toJSONString(user,
    JSONWriter.Feature.WriteNulls,
    JSONWriter.Feature.PrettyFormat,        // skip if not needed
    JSONWriter.Feature.ReferenceDetection,  // skip if no circular refs
    JSONWriter.Feature.MapSortField);       // skip if order doesn't matter

6. Use FieldBased for Maximum Speed Copy Section

Impact: Medium

FieldBased mode accesses fields directly instead of through getter/setter methods, which is slightly faster:

String json = JSON.toJSONString(user, JSONWriter.Feature.FieldBased);
User user = JSON.parseObject(json, User.class, JSONReader.Feature.FieldBased);

Note: This accesses private fields via reflection/ASM, which may not work in all environments.

7. Cache ObjectReader/ObjectWriter for Custom Types Copy Section

Impact: Medium

If you register custom readers/writers, ensure they are singletons:

// Good: singleton pattern
class MoneyWriter implements ObjectWriter<Money> {
    static final MoneyWriter INSTANCE = new MoneyWriter();
    // ...
}
JSON.register(Money.class, MoneyWriter.INSTANCE);

Thread Safety Copy Chapter

Understanding thread safety helps avoid unnecessary synchronization:

JVM Tuning Copy Chapter

Recommended JVM Flags Copy Section

# Enable compact strings (JDK 9+, on by default)
-XX:+CompactStrings

# For JDK 17+, enable Vector API incubator module
--add-modules jdk.incubator.vector

Memory Considerations Copy Section

• FASTJSON 2 uses thread-local buffers for serialization, which reduces GC pressure but increases per-thread memory.
• For applications with many threads, monitor thread-local buffer usage.
• JSONB typically uses less memory than text JSON due to compact encoding.

Benchmarking Copy Chapter

FASTJSON 2 includes JMH benchmarks in the benchmark/ module. To run:

cd benchmark
mvn clean package
java -jar target/benchmarks.jar

For published benchmark results comparing FASTJSON 2 with Jackson, Gson, and other libraries, see:

• Benchmark Results
• JSONB vs Hessian/Kryo
• Android Benchmarks

Projects Using (`docs/projects_using.md`) Copy Section

如下收录了使用fastjson2的项目列表，收录的条件是github star数量>=100，如下：

• https://github.com/infowangxin/springboot-freemarker
• https://github.com/alibaba/canal
• https://github.com/alibaba/druid
• https://github.com/game-town/ioGame
• https://github.com/yangzongzhuan/RuoYi-Cloud
• https://github.com/yangzongzhuan/RuoYi-Vue-Oracle
• https://github.com/yangzongzhuan/RuoYi-Vue
• https://github.com/yangzongzhuan/RuoYi-Vue-fast
• https://github.com/matevip/matecloud
• https://github.com/wgzhao/Addax
• https://github.com/techa03/goodsKill
• https://github.com/whiteshader/React-Admin-Cloud
• https://github.com/vctgo/vctgo-platform
• https://github.com/wayn111/newbee-mall-pro
• https://github.com/alibaba/jetcache
• https://github.com/newbee-ltd/newbee-mall-plus
• https://github.com/apache/dubbo
• https://github.com/HHa1ey/TKHunter
• https://github.com/dromara/Sa-Token
• https://github.com/yangrunkang/upupor
• https://github.com/PomZWJ/database-export
• https://github.com/648540858/wvp-GB28181-pro
• https://github.com/TechEmpower/FrameworkBenchmarks
• https://github.com/wayn111/waynboot-mall
• https://github.com/PlexPt/chatgpt-java
• https://github.com/topiam/eiam
• https://github.com/martin-chips/DimpleBlog
• https://github.com/dromara/Jpom
• https://github.com/apache/dubbo-samples
• https://github.com/tony2y/RuoYi-flowable
• https://github.com/rstyro/Springboot
• https://github.com/shiyindaxiaojie/eden-architect
• https://github.com/86dbs/dbsyncer
• https://github.com/alibaba/easyexcel
• https://github.com/KrystianLi/ExchangeOWA
• https://github.com/alibaba/DataX
• https://github.com/entropy-cloud/nop-entropy
• https://github.com/C3Stones/blog
• https://github.com/bit4woo/reCAPTCHA
• https://github.com/mybatis-flex/mybatis-flex
• https://github.com/nageoffer/congomall
• https://github.com/qi4L/JYso
• https://github.com/chaitin/HummerRisk
• https://github.com/XiaoMi/mone
• https://github.com/cubefs/compass
• https://github.com/Ginyi3705/ginyi-spring-vue
• https://github.com/kylelin1998/ChatGPTForTelegram
• https://github.com/LuckyPuppy514/jproxy
• https://github.com/HamaWhiteGG/flink-sql-lineage
• https://github.com/HXSecurity/DongTai-agent-java
• https://github.com/Y4er/ysoserial
• https://github.com/alldatacenter/alldata
• https://github.com/alibaba/arthas
• https://github.com/asleepyfish/chatgpt
• https://github.com/libaibaia/cloudSec
• https://github.com/linyimin0812/spring-startup-analyzer
• https://github.com/zfile-dev/zfile
• https://github.com/noear/solon
• https://github.com/nageoffer/12306
• https://github.com/geekidea/spring-boot-plus
• https://github.com/tgscan-dev/tgscan
• https://github.com/chat2db/Chat2DB
• https://github.com/bihell/Dice
• https://github.com/oddfar/campus-imaotai
• https://github.com/OGtwelve/OGTwelveUtilPack
• https://github.com/mfish-qf/mfish-nocode
• https://github.com/pnoker/iot-dc3
• https://github.com/red-velet/qrpc
• https://github.com/smartloli/EFAK
• https://github.com/969025903/ChopperBot
• https://github.com/XiaoMi/mone
• https://github.com/gz-yami/mall4cloud
• https://github.com/cas-bigdatalab/piflow
• https://github.com/DataLinkDC/dinky
• https://github.com/wh1t3p1g/ysomap
• https://github.com/dromara/liteflow
• https://github.com/jar-analyzer/jar-analyzer
• https://github.com/wmsJackWang/jackdking-root
• https://github.com/spring-projects/spring-ai
• https://github.com/XiaoMi/ozhera
• https://github.com/rstyro/admin-plus
  https://github.com/zfoo-project/zfoo
• https://github.com/TongchengOpenSource/ckibana
• https://github.com/geekidea/spring-boot-plus
• https://github.com/02cx/dong-rpc
• https://github.com/smart-doc-group/smart-doc-example-cn
• https://github.com/shuanx/BurpFingerPrint
• https://github.com/sagframe/sagacity-sqltoy
• https://github.com/X1r0z/JNDIMap
• https://github.com/apache/rocketmq
• https://github.com/kerwincui/wumei-smart
• https://github.com/kerwincui/FastBee
• https://github.com/luguosong/programming-notes
• https://github.com/niumoo/JavaNotes
• https://github.com/OpenFeign/feign
• https://github.com/yl-yue/yue-library
• https://github.com/dromara/forest
• https://github.com/xunlu129/teriteri-backend
• https://github.com/moshowgame/SpringBootCodeGenerator
• https://github.com/4379711/lol-helper
• https://github.com/zddgg/novel-cast
• https://github.com/Whoopsunix/PPPYSO
• https://github.com/wangzihaogithub/spring-boot-protocol
• https://github.com/woodwhales/woodwhales-music
• https://github.com/JanesenGit/FastChar
• https://github.com/tokyohost/v2nodeManager
• https://github.com/giteecode/hospitalRegistePublic
• https://github.com/wujun728/jun_java_plugin
• https://github.com/anhan123456/vrpc
• https://github.com/spring-projects/spring-ai
• https://github.com/wujun728/jun_java_plugin
• https://github.com/Alanosy/online-exam-system-backend
• https://github.com/zcode-zjw/zcode-commons
• https://github.com/WeBankFinTech/Exchangis
• https://github.com/Harries/springboot-demo
• https://github.com/642933588/jiron-cloud
• https://github.com/cool-team-official/cool-admin-java
• https://github.com/akto-api-security/akto
• https://github.com/Devo919/Gewechat
• https://github.com/KouShenhai/KCloud-Platform-IoT
• https://github.com/starmcc/qs-beanfun
• https://github.com/Shleter587/aippt_PresentationGen
• https://github.com/dromara/warm-flow
• https://github.com/lich0821/WeChatFerry
• https://github.com/winezer0/APIFinderPlus
• https://github.com/aws/aws-lambda-java-libs
• https://github.com/Joolun/JooLun-wx
• https://github.com/apache/incubator-seata
• https://github.com/jd-opensource/joylive-agent
• https://github.com/mapleplus/feng-shortlink
• https://github.com/yindz/common-random
• https://github.com/alibaba/termd
• https://github.com/CodePhiliaX/fastexcel
• https://github.com/Zy-Fang1102/E-Stega
• https://github.com/Dev0ke/angr-java
• https://github.com/aliyun/alibabacloud-microservice-demo
• https://github.com/javagossip/dorado
• https://github.com/xuxueli/xxl-rpc
• https://github.com/ww20081120/framework
• https://github.com/burukeYou/UniHttp
• https://github.com/xuxueli/xxl-conf
• https://github.com/B0T1eR/ysoSimple
• https://github.com/elunez/eladmin
• https://github.com/elunez/eladmin-mp
• https://github.com/LinQi0777/RiskEngine
• https://github.com/niujt/Hospital
• https://github.com/xbatis/xbatis
• https://github.com/ageerle/ruoyi-ai
• https://github.com/javifalces/HFTFramework
• https://github.com/insmess/insmess-meeting-manager
• https://github.com/zhihuili/flower
• https://github.com/MikuNyanya/RabbitBot_RE
• https://github.com/yuyan-sec/druid_sessions
• https://github.com/javagossip/opendsp
• https://github.com/shaiwz/data-platform-open
• https://github.com/818000/bus
• https://github.com/houbb/sensitive-word-admin
• https://github.com/Auties00/Cobalt
• https://github.com/newVkDing2/coinc
• https://github.com/Romantic-Lei/Learning-in-practice
• https://github.com/xiaou61/U-space
• https://github.com/qiantongtech/qData
• https://github.com/qiantongtech/qKnow
• https://github.com/zuihou/lamp-util
• https://github.com/dromara/lamp-cloud
• https://github.com/KouShenhai/KCloud-Platform-IoT
• https://github.com/alibaba/spring-ai-alibaba
• https://github.com/alibaba/QLExpress

Reader Codegen Cn (`docs/reader_codegen_cn.md`) Copy Section

反序列化CodeGen算法介绍

fastjson2会使用codegen来优化反序列化的性能，用到的codegen技术包括：

• ASM 基于内置asm 9.2裁剪版实现的动态字节码生成类
• Annotation Process Tools(APT)

1. 实现算法介绍 Copy Chapter

上图中算法1是常规实现；算法2是fastjson2的实现（最初是dsljson引入，被fastjson借鉴）；算法3是新引入的实现

我们要将json反序列化为如下的Image类

@Data
public class Image {
    private int height;
    private Size size;
    private String title;
    private String uri;
    private int width;
}

生成如下的代码来快速将json中的name和字段关联起来：

/* Detailed source-code truncated for AI context efficiency. */

相关方法在JSONReader中的实现

class JSONReaderUTF8 implements JSONReader {
    public final int getRawInt() {
        if (offset + 3 < bytes.length) {
            return UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 1);
        }
        return 0;
    }

    public boolean nextIfName4Match3() {
        offset += 5;

        if (bytes[offset - 2] != '"' || bytes[offset - 1] != ':') {
            return false;
        }

        // ...

        return true;
    }

    public final boolean nextIfName4Match4(byte c4) {
        offset += 6;
        if (bytes[offset - 3] != c4 || bytes[offset - 2] != '"' || bytes[offset - 1] != ':') {
            return false;
        }
        // ...
        return true;
    }
    
    public boolean nextIfName4Match5(int name1) {
        offset += 7;
        if (UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 4) != name1) {
            return false;
        }
        // ...
        return true;
    }
    
    public boolean nextIfName4Match6(int name1) {
        offset += 8;
        if (UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 5) != name1 || bytes[offset - 1] != ':') {
            return false;
        }
        // ...
        return true;
    }
}

这样的实现好处是，不需要将key读取出来，也不需要将使用JSONReader#readFieldNameHashCode，通过key的前缀3个字符读取一个int值，使用switch来路由到相应字段的处理。

2. 算法实现代码 Copy Chapter

生成代码的实现：

• ASM实现 com.alibaba.fastjson2.reader.ObjectReaderCreatorASM#genRead243
• APT实现 com.alibaba.fastjson2.internal.processor.JSONCompiledAnnotationProcessor.genRead243

Reader Codegen En (`docs/reader_codegen_en.md`) Copy Section

Introduction to the Deserialization CodeGen Algorithm

fastjson2 uses codegen to optimize deserialization performance. The codegen techniques used include:

• ASM: Dynamic bytecode class generation based on a built-in, trimmed version of ASM 9.2.
• Annotation Processing Tools (APT)

1. Introduction to the Implementation Algorithm Copy Chapter

In the diagram above, Algorithm 1 is a conventional implementation; Algorithm 2 is fastjson2's implementation (originally introduced by dsljson and adopted by fastjson); Algorithm 3 is a newly introduced implementation.

We want to deserialize a JSON into the following Image class:

@Data
public class Image {
    private int height;
    private Size size;
    private String title;
    private String uri;
    private int width;
}

The following code is generated to quickly associate the names in the JSON with the fields:

/* Detailed source-code truncated for AI context efficiency. */

The implementation of the related methods in JSONReader is as follows:

class JSONReaderUTF8 implements JSONReader {
    public final int getRawInt() {
        if (offset + 3 < bytes.length) {
            return UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 1);
        }
        return 0;
    }

    public boolean nextIfName4Match3() {
        offset += 5;

        if (bytes[offset - 2] != '"' || bytes[offset - 1] != ':') {
            return false;
        }

        // ...

        return true;
    }

    public final boolean nextIfName4Match4(byte c4) {
        offset += 6;
        if (bytes[offset - 3] != c4 || bytes[offset - 2] != '"' || bytes[offset - 1] != ':') {
            return false;
        }
        // ...
        return true;
    }
    
    public boolean nextIfName4Match5(int name1) {
        offset += 7;
        if (UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 4) != name1) {
            return false;
        }
        // ...
        return true;
    }
    
    public boolean nextIfName4Match6(int name1) {
        offset += 8;
        if (UNSAFE.getInt(bytes, ARRAY_BYTE_BASE_OFFSET + offset - 5) != name1 || bytes[offset - 1] != ':') {
            return false;
        }
        // ...
        return true;
    }
}

The advantage of this implementation is that it doesn't need to read the entire key, nor does it need to use JSONReader#readFieldNameHashCode. Instead, it reads an integer value from the first few bytes of the key and uses a switch statement to route to the corresponding field's processing logic.

2. Algorithm Implementation Code Copy Chapter

Code Generation Implementation:

• ASM Implementation: com.alibaba.fastjson2.reader.ObjectReaderCreatorASM#genRead243
• APT Implementation: com.alibaba.fastjson2.internal.processor.JSONCompiledAnnotationProcessor.genRead243

Register Custom Reader Writer Cn (`docs/register_custom_reader_writer_cn.md`) Copy Section

实现ObjectWriter和ObjectReader实现定制序列化和反序列化

1. 实现ObjectWriter接口定制化序列化 Copy Chapter

1.1 ObjectWriter的定义 Copy Chapter

package com.alibaba.fastjson2.writer;

public interface ObjectWriter<T> {
    void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features);
}

1.2 实现ObjectWriter举例 Copy Chapter

class InetAddressWriter implements ObjectWriter {
    InetAddressWriter INSTANCE = new InetAddressWriter();

    @Override
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features) {
        if (object == null) {
            jsonWriter.writeNull();
            return;
        }

        InetAddress address = (InetAddress) object;
        // 优先使用name
        jsonWriter.writeString(address.getHostName());
    }
}

1.3 注册Writer Copy Chapter

JSON.register(InetAddress.class, InetAddressWriter.INSTANCE);
JSON.register(Inet4Address.class, InetAddressWriter.INSTANCE);
JSON.register(Inet6Address.class, InetAddressWriter.INSTANCE);

1.4 注册ObjectWriters的一些内置实现 Copy Chapter

ObjectWriters提供了构造ofToString/ofToInt/ofToLong方法，让使用者能更方便序列化，比如：

public static class Bean {
    public int id;

    public String toString() {
        return Integer.toString(id);
    }

    public int getId() {
        return id;
    }
}

@Test
public void testToString() {
    ObjectWriter objectWriter = ObjectWriters.ofToString(Bean::toString);

    Bean bean = new Bean();
    bean.id = 101;

    JSONWriter jsonWriter = JSONWriter.of();
    objectWriter.write(jsonWriter, bean);
    assertEquals("\"101\"", jsonWriter.toString());
}

@Test
public void testToInt() {
    ObjectWriter<Bean> objectWriter = ObjectWriters.ofToInt(
            (ToIntFunction<Bean>) Bean::getId
    );

    Bean bean = new Bean();
    bean.id = 101;

    JSONWriter jsonWriter = JSONWriter.of();
    objectWriter.write(jsonWriter, bean);
    assertEquals("101", jsonWriter.toString());
}

2. 实现ObjectReader定制反序列化

2.1 ObjectReader的定义 Copy Chapter

package com.alibaba.fastjson2.reader;

public interface ObjectReader<T> {
    T readObject(JSONReader jsonReader, Type fieldType, Object fieldName, long features);
}

ObjectReader还有很多其他方法，但都提供了缺省实现，上面这个方法是必须实现的。

2.2 实现ObjectReader举例 Copy Chapter

import java.time.Instant;
import com.alibaba.fastjson2.reader.ObjectReader;

class InstantReader implements ObjectReader {
    public static final InstantReader INSTANCE = new InstantReader();
    @Override
    public Object readObject(JSONReader jsonReader, Type fieldType, Object fieldName, long features) {
        if (jsonReader.nextIfNull()) {
            return null;
        }

        long millis = jsonReader.readInt64Value();
        return Instant.ofEpochMilli(millis);
    }
}

2.3 注册Reader Copy Chapter

JSON.register(Instant.class, InstantReader.INSTANCE);

2.4 注册内置的ObjectReaders提供的一些内置实现 Copy Chapter

ObjectReaders提供了构造ofString/ofInt/ofLong方法，让使用者能更方便反序列化，比如：

public static class Bean {
    final int code;
    public Bean(String str) {
        code = Integer.parseInt(str);
    }
}

@Test
public void test() {
    JSON.register(Bean.class, ObjectReaders.ofString(Bean::new));
    
    Bean bean = JSON.parseObject("\"123\"", Bean.class);
    assertEquals(123, bean.code);
}

Register Custom Reader Writer En (`docs/register_custom_reader_writer_en.md`) Copy Section

Implementing ObjectWriter and ObjectReader for Custom Serialization and Deserialization

1. Implementing the ObjectWriter Interface for Custom Serialization Copy Chapter

1.1 ObjectWriter Definition Copy Section

package com.alibaba.fastjson2.writer;

public interface ObjectWriter<T> {
    void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features);
}

1.2 ObjectWriter Implementation Example Copy Section

class InetAddressWriter implements ObjectWriter {
    static final InetAddressWriter INSTANCE = new InetAddressWriter();

    @Override
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features) {
        if (object == null) {
            jsonWriter.writeNull();
            return;
        }

        InetAddress address = (InetAddress) object;
        // Prioritize using the name
        jsonWriter.writeString(address.getHostName());
    }
}

1.3 Registering the Writer Copy Section

JSON.register(InetAddress.class, InetAddressWriter.INSTANCE);
JSON.register(Inet4Address.class, InetAddressWriter.INSTANCE);
JSON.register(Inet6Address.class, InetAddressWriter.INSTANCE);

1.4 Registering Some Built-in Implementations of ObjectWriters Copy Section

ObjectWriters provides ofToString/ofToInt/ofToLong methods to make serialization more convenient for users, for example:

public static class Bean {
    public int id;

    public String toString() {
        return Integer.toString(id);
    }

    public int getId() {
        return id;
    }
}

@Test
public void testToString() {
    ObjectWriter objectWriter = ObjectWriters.ofToString(Bean::toString);

    Bean bean = new Bean();
    bean.id = 101;

    JSONWriter jsonWriter = JSONWriter.of();
    objectWriter.write(jsonWriter, bean);
    assertEquals("\"101\"", jsonWriter.toString());
}

@Test
public void testToInt() {
    ObjectWriter<Bean> objectWriter = ObjectWriters.ofToInt(
            (ToIntFunction<Bean>) Bean::getId
    );

    Bean bean = new Bean();
    bean.id = 101;

    JSONWriter jsonWriter = JSONWriter.of();
    objectWriter.write(jsonWriter, bean);
    assertEquals("101", jsonWriter.toString());
}

2. Implementing ObjectReader for Custom Deserialization

2.1 ObjectReader Definition Copy Chapter

package com.alibaba.fastjson2.reader;

public interface ObjectReader<T> {
    T readObject(JSONReader jsonReader, Type fieldType, Object fieldName, long features);
}

ObjectReader has many other methods, but they all provide default implementations. The method above must be implemented.

2.2 ObjectReader Implementation Example Copy Chapter

import java.time.Instant;
import com.alibaba.fastjson2.reader.ObjectReader;

class InstantReader implements ObjectReader {
    public static final InstantReader INSTANCE = new InstantReader();
    @Override
    public Object readObject(JSONReader jsonReader, Type fieldType, Object fieldName, long features) {
        if (jsonReader.nextIfNull()) {
            return null;
        }

        long millis = jsonReader.readInt64Value();
        return Instant.ofEpochMilli(millis);
    }
}

2.3 Registering the Reader Copy Chapter

JSON.register(Instant.class, InstantReader.INSTANCE);

2.4 Registering Some Built-in Implementations Provided by ObjectReaders Copy Chapter

ObjectReaders provides ofString/ofInt/ofLong methods to make deserialization more convenient for users, for example:

public static class Bean {
    final int code;
    public Bean(String str) {
        code = Integer.parseInt(str);
    }
}

@Test
public void test() {
    JSON.register(Bean.class, ObjectReaders.ofString(Bean::new));
    
    Bean bean = JSON.parseObject("\"123\"", Bean.class);
    assertEquals(123, bean.code);
}

Vector Optimized Cn (`docs/vector_optimized_cn.md`) Copy Section

JDK 17中提供了vector api，可以用SIMD来优化性能。

fastjson 2.0.61版本开始全面使用SWAR(SIMD within a register)来做SIMD优化，不再需要使用vector api.

Vector Optimized En (`docs/vector_optimized_en.md`) Copy Section

JDK 17 introduced the vector api, which can use SIMD to optimize performance.

Starting from version 2.0.61, fastjson2 comprehensively uses SWAR (SIMD within a register) for SIMD optimization and no longer needs to use the vector api.

Android Android Benchmark Cn (`docs/Android/android_benchmark_cn.md`) Copy Section

1. SerDe Benchmark

执行10000次的耗时，数字越小越好。

2. Parse Benchmark

执行1000次的耗时，数字越小越好。

Android Android Benchmark En (`docs/Android/android_benchmark_en.md`) Copy Section

1. SerDe Benchmark

The time required to execute 10000 times, the smaller the number, the better.

2. Parse Benchmark

The time required to execute 10000 times, the smaller the number, the better.

Filter Index Cn (`docs/Filter/index_cn.md`) Copy Section

仅在序列化（将 Java 对象转换为 JSON 字符串）时生效： Copy Section

• AfterFilter: 在序列化输出的末尾添加额外内容。
• BeforeFilter: 在序列化输出的开头添加额外内容。
• NameFilter: 用于在序列化时修改属性的名称。
• ContextNameFilter: 功能同 NameFilter ，但它可以结合上下文信息修改属性名称。
• ValueFilter: 用于在序列化时修改属性的值。
• ContextValueFilter: 功能同 ValueFilter ，但它可以结合上下文信息修改属性值。
• LabelFilter: 允许根据不同的场景标签（Label）来定制序列化输出不同的字段。
• PascalNameFilter: 这是一个 NameFilter 的具体实现，它会将属性名称的首字母大写，实现驼峰命名到帕斯卡命名（Pascal）的转换。
• PropertyPreFilter: 根据属性名进行快速过滤，决定某个属性是否需要被序列化。
• PropertyFilter: 根据属性名和属性值来判断某个属性是否需要被序列化。
• SimplePropertyPreFilter: 一个简便的属性预过滤器，通过指定包含（includes）或排除（excludes）的属性列表来控制哪些字段参与序列化。

仅在反序列化（将 JSON 字符串转换为 Java 对象）时生效： Copy Section

• ExtraProcessor: 用于处理在反序列化时，JSON 字符串中存在但 Java 对象中不存在的多余字段。
• AutoTypeBeforeHandler: 在 Fastjson 2.x 中，用于在反序列化时提供类似 AutoType 功能，通过白名单机制来控制允许反序列化的类，以增强安全性。
• ContextAutoTypeBeforeHandler: 同样用于处理 AutoType，并提供了上下文信息，内置了一些常用的类型支持。

Filter Index En (`docs/Filter/index_en.md`) Copy Section

Effective only during serialization (converting Java objects to JSON strings): Copy Section

• AfterFilter: Adds extra content to the end of the serialized output.
• BeforeFilter: Adds extra content at the beginning of the serialized output.
• NameFilter: Used to modify property names during serialization.
• ContextNameFilter: Same function as NameFilter, but it can modify property names using contextual information.
• ValueFilter: Used to modify property values during serialization.
• ContextValueFilter: Same function as ValueFilter, but it can modify property values using contextual information.
• LabelFilter: Allows customizing the serialization of different fields based on different scenario labels (Label).
• PascalNameFilter: This is a specific implementation of NameFilter that capitalizes the first letter of property names, converting from camelCase to PascalCase.
• PropertyPreFilter: Performs fast filtering based on the property name to decide whether a property should be serialized.
• PropertyFilter: Determines whether a property should be serialized based on its name and value.
• SimplePropertyPreFilter: A simple property pre-filter that controls which fields are serialized by specifying lists of included or excluded properties.

Effective only during deserialization (converting JSON strings to Java objects): Copy Section

• ExtraProcessor: Used to handle extra fields that exist in the JSON string but not in the Java object during deserialization.
• AutoTypeBeforeHandler: In Fastjson 2.x, it provides AutoType-like functionality during deserialization, using a whitelist mechanism to control which classes are allowed to be deserialized, thus enhancing security.
• ContextAutoTypeBeforeHandler: Also used to handle AutoType, but provides contextual information and has built-in support for some common types.

Filter Name Filter Cn (`docs/Filter/name_filter_cn.md`) Copy Section

NameFilter

FASTJSON提供了一个序列化时对字段名做处理的扩展叫做NameFilter，接口如下

package com.alibaba.fastjson2.filter;

public interface NameFilter
        extends Filter {
    String process(Object object, String name, Object value);
}

NameFilter通过of方法提供了常见需求的实现，比如：

public class Bean {
    public int userId;
}

@Test
public void test() {
    Bean bean = new Bean();
    bean.userId = 101;

    NameFilter pascalNameFilter = NameFilter.of(PropertyNamingStrategy.PascalCase);
    String str = JSON.toJSONString(bean, pascalNameFilter);
    assertEquals("{\"UserId\":101}", str);
    JSONObject object = JSON.parseObject(str);
    assertEquals(101, object.get("UserId"));
}

Filter Name Filter En (`docs/Filter/name_filter_en.md`) Copy Section

NameFilter

FASTJSON provides an extension for processing field names during serialization called NameFilter. The interface is as follows:

package com.alibaba.fastjson2.filter;

public interface NameFilter
        extends Filter {
    String process(Object object, String name, Object value);
}

NameFilter provides implementations for common requirements through the of method, for example:

public class Bean {
    public int userId;
}

@Test
public void test() {
    Bean bean = new Bean();
    bean.userId = 101;

    NameFilter pascalNameFilter = NameFilter.of(PropertyNamingStrategy.PascalCase);
    String str = JSON.toJSONString(bean, pascalNameFilter);
    assertEquals("{\"UserId\":101}", str);
    JSONObject object = JSON.parseObject(str);
    assertEquals(101, object.get("UserId"));
}

Filter Value Filter Cn (`docs/Filter/value_filter_cn.md`) Copy Section

ValueFilter

FASTJSON提供了一个序列化时对字段名做处理的扩展叫做ValueFilter，接口如下

package com.alibaba.fastjson2.filter;

public interface ValueFilter
        extends Filter {
    Object apply(Object object, String name, Object value);
}

ValueFilter允许你在输出的时候自定义输出的值，比如：

public static class Bean {
    public int id;
}

@Test
public void test_valuefilterCompose() {
    ValueFilter filter0 = (source, name, value) -> {
        if ("id".equals(name)) {
            return ((Integer) value).intValue() + 1;
        }
        return value;
    };

    ValueFilter filter1 = (source, name, value) -> {
        if ("id".equals(name)) {
            return ((Integer) value).intValue() + 10;
        }
        return value;
    };

    Bean bean = new Bean();
    bean.id = 100;
    String str = JSON.toJSONString(bean, ValueFilter.compose(filter0, filter1));
    assertEquals("{\"id\":111}", str);
}

Filter Value Filter En (`docs/Filter/value_filter_en.md`) Copy Section

ValueFilter

FASTJSON provides an extension for processing field values during serialization called Value-Filter. The interface is as follows:

package com.alibaba.fastjson2.filter;

public interface ValueFilter
extends Filter {
Object apply(Object object, String name, Object value);
}

ValueFilter allows you to customize the output value during serialization, for example:

public static class Bean {
    public int id;
}

@Test
public void test_valuefilterCompose() {
    ValueFilter filter0 = (source, name, value) -> {
        if ("id".equals(name)) {
            return ((Integer) value).intValue() + 1;
        }
        return value;
    };

    ValueFilter filter1 = (source, name, value) -> {
        if ("id".equals(name)) {
            return ((Integer) value).intValue() + 10;
        }
        return value;
    };

    Bean bean = new Bean();
    bean.id = 100;
    String str = JSON.toJSONString(bean, ValueFilter.compose(filter0, filter1));
    assertEquals("{\"id\":111}", str);
}

JSONB Jsonb Format Cn (`docs/JSONB/jsonb_format_cn.md`) Copy Section

JSONB存储格式设计

1. 设计目标

1. 和JSON格式对应，能完全表示JSON
2. 紧凑，数据不留空洞
3. 对常用整数-16~63做紧凑设计
4. 对null/true/false做紧凑设计
5. 对0~15长度的ARRAY 做紧凑设计
6. 对0~47长度的ascii编码的字符串做紧凑设计
7. 对OBJECT类型的Name做短编码的支持
8. 支持完整的Java序列化和反序列化

2. JSON支持格式定义

/* Detailed source-code truncated for AI context efficiency. */

3. 数值表示设计

jsonb支持的数值类型：

• INT8
• INT16
• INT32
• INT64
• BIGINT
• DECIMAL
• FLOAT
• DOUBLE

数值的表示在连续的区间，范围是0xb2 ~ 0x48

3.1 INT32设计 Copy Chapter

INT32的表示在不同取值范围所需要的字节数不一样

* 0xf0 ~ 0x2f 直接表示-16 ~ 47的INT32整数，只需要1个字节，也不需要额外转换
* 0x30 ~ 0x3f 表示-2048 ~ 2047的INT32整数，需要使用2个字节
* 0x40 ~ 0x47 表示-262144 ~ 262143的，需要使用3个字节
* 0x48 + <bytes4>，第1个byte是0x48，之后4个byte表示数值，需要使用5个字节

3.2 INT64设计 Copy Chapter

* 0xd8 ~ 0xef 直接表示-8 ~ 15的INT64整数，只需要1个字节
* 0xc8 ~ 0xd7 表示-2048 ~ 2047的INT64整数，需要使用2个字节
* 0xc0 ~ 0xc7 表示-262144 ~ 262143的INT64整数，需要使用3个字节
* 0xbf + <bytes4>，第1个byte是0xbf，之后4个byte表示数值，需要使用5个字节
* 0xbe + <bytes8>，第1个byte是0xbe，之后8个byte表示数值，需要使用9个字节

3.3 INT8 & INT16 Copy Chapter

* 0xbd + <bytes1> 表示IN8，需要2个字节
* 0xbc + <bytes2> 表示IN16，需要3个字节

3.4 BIGINT表示设计 Copy Chapter

BIGINT有两种表示法：

* 0xba + <int64> ，当BIGINT的取值范围在0x8000000000000000L ~ 0x7fffffffffffffffL时，在int64之前加一个0xba的字节，所需要的字节数是2 ~ 10。
* 0xbb + <bytes_len> + <bytes>

3.5 DECIMAL表示法 Copy Chapter

DECIMAL有两种表示法

* 0xb8 + <int64>，当没有小数，并且 取值范围在0x8000000000000000L ~ 0x7fffffffffffffffL时，在int64之前加一个0xb8的字节，所需要的字节数是2 ~ 10。
* 0xb9 + <scale_int32> + <int32|int64|bigint>

3.6 FLOAT表示 Copy Chapter

FLOAT有两种表示法

* 0xb6 + <int32> 没有小数的FLOAT，所需要字节数2 ~ 6个
* 0xb7 + <bytes4> 需要5个字节

3.7 DOUBLE表示 Copy Chapter

DOUBLE有三种表示

* 0xb2 ~ 0xb3 表示0和1，占1个字节
* 0xb4 + <int64> 没有小数的double，所需要2~10个字节
* 0xb5 + <bytes8> 需要9个bytes

4. NULL/TRUE/FALSE

NULL/TRUE/FALSE都使用1个字节表示

• 0xaf NULL
• 0xb0 FALSE
• 0xb1 TRUE

5. 字符串表示

字符串的表示有三种办法：

* 0x49 ~ 0x78 表示长度为0 ~ 47的LATIN1字符串
* 0x79 + <int32_bytes_len> + <bytes> LATIN1字符串
* 0x7a + <int32_bytes_len> + <bytes> UTF8字符串
* 0x7b + <int32_bytes_len> + <bytes> UTF16字符串
* 0x7c + <int32_bytes_len> + <bytes> UTF16LE字符串
* 0x7d + <int32_bytes_len> + <bytes> UTF16BE字符串
* 0x7e + <int32_bytes_len> + <bytes> GB18030编码字符串（这个可以减少中文编码的长度）
* 0x7f + <int32_symbol> 如果symbol为负数，则是SymbolTable中的下标。如果是>=0，则是当前数据中字符串符号

字符串专门设计对了LATIN1编码字符的支持。这个对字符串的反序列化性能提升会很有帮助，对Java 9+之后的字符串序列化也会有帮助。

6. 日期表示

* 0xae + <int64_epoch_second> + <int32_nano> TIMESTAMP 需要3~15个字节，对应java中的Instant类型
* 0xad + <bytes4_epoch_minutes> TIMESTAMP_MINUTES 需要5个字节，对应java中的Date类型
* 0xac + <bytes4_epoch_seconds> TIMESTAMP_SECONDS 需要5个字节，对应java中的Date类型
* 0xab + <bytes8_epoch_millis> TIMESTAMP_MILLIS 需要9个字节，对应java中的Date类型
* 0xaa + <bytes2_year> + <bytes1_monthValue> + <bytes1_dayOfMonth> + <bytes1_hour> + <bytes1_minute> + <bytes1_second> + <int32_nano> + <str_zoneId>，对应java中ZonedDateTime
* 0xa9 + <bytes2_year> + <bytes1_monthValue> + <bytes1_dayOfMonth> 需要5个字节，对应java中的LocalDate类型
* 0xa8 + <bytes2_year> + <bytes1_monthValue> + <bytes1_dayOfMonth> + <bytes1_hour> + <bytes1_minute> + <bytes1_second> + <int32_nano> 需要8~12个字符，对应java中的LocalDateTime类型
* 0xa7 + <bytes1_hour> + <bytes1_minute> + <bytes1_second> + <int32_nano> 需要4~8个字符，对应java中的LocalTime类型

7. 对象类型

对象类型以0xa6开始，0xa5结束，中间有若干个key_value对，如下：

0xa6
    [<key_any> <value_any>]...
0xa5

8. 数组类型

数组有两种表示法

* 0x94 ~ 0xa3表示元素个数为0~15的数组
* 0xa4 + <int32_length> + <item...>

9. Reference

* 0x93 + <str_reference_path>

10. Typed_Any

这个类型可以使得支持完整地序列化和反序列化

* 0x92 + <str_typename> + <any>

11. 二进制类型

0x91 + <int32_length> + <bytes>

12. char类型

0x90 <byte1>

JSONB Jsonb Format En (`docs/JSONB/jsonb_format_en.md`) Copy Section

Design of JSONB Storage Format

1. Design Goals

1. To be compatible with the JSON format and capable of fully representing JSON.
2. Compact, with no data gaps.
3. Compact design for commonly used integers from -16 to 63.
4. Compact design for null/true/false.
5. Compact design for ARRAYs of length 0 to 15.
6. Compact design for ASCII-encoded strings of length 0 to 47.
7. Support for short encoding of OBJECT names (keys).
8. Support for complete Java serialization and deserialization.

2. JSON Support Format Definition

/* Detailed source-code truncated for AI context efficiency. */

3. Numeric Representation Design

JSONB supports the following numeric types:

• INT8
• INT16
• INT32
• INT64
• BIGINT
• DECIMAL
• FLOAT
• DOUBLE

The representation of numeric values is in a contiguous range from 0xb2 to 0x48.

3.1 INT32 Design Copy Chapter

The number of bytes required to represent an INT32 varies depending on its value range.

* 0xf0 ~ 0x2f: Directly represents INT32 integers from -16 to 47, requiring only 1 byte without extra conversion.
* 0x30 ~ 0x3f: Represents INT32 integers from -2048 to 2047, requiring 2 bytes.
* 0x40 ~ 0x47: Represents INT32 integers from -262144 to 262143, requiring 3 bytes.
* 0x48 + <4_bytes>: The first byte is 0x48, followed by 4 bytes representing the value, requiring 5 bytes in total.

3.2 INT64 Design Copy Chapter

* 0xd8 ~ 0xef: Directly represents INT64 integers from -8 to 15, requiring only 1 byte.
* 0xc8 ~ 0xd7: Represents INT64 integers from -2048 to 2047, requiring 2 bytes.
* 0xc0 ~ 0xc7: Represents INT64 integers from -262144 to 262143, requiring 3 bytes.
* 0xbf + <4_bytes>: The first byte is 0xbf, followed by 4 bytes representing the value, requiring 5 bytes in total.
* 0xbe + <8_bytes>: The first byte is 0xbe, followed by 8 bytes representing the value, requiring 9 bytes in total.

3.3 INT8 & INT16 Copy Chapter

* 0xbd + <1_byte>: Represents INT8, requires 2 bytes.
* 0xbc + <2_bytes>: Represents INT16, requires 3 bytes.

3.4 BIGINT Representation Design Copy Chapter

BIGINT has two representations:

* 0xba + <int64>: When the BIGINT's value is within the range 0x8000000000000000L ~ 0x7fffffffffffffffL, it is prefixed with a 0xba byte, requiring 2 to 10 bytes.
* 0xbb + <bytes_len> + <bytes>

3.5 DECIMAL Representation Copy Chapter

DECIMAL has two representations:

* 0xb8 + <int64>: When there is no fractional part and the value is within the range 0x8000000000000000L ~ 0x7fffffffffffffffL, it is prefixed with a 0xb8 byte, requiring 2 to 10 bytes.
* 0xb9 + <scale_int32> + <int32|int64|bigint>

3.6 FLOAT Representation Copy Chapter

FLOAT has two representations:

* 0xb6 + <int32>: Represents a FLOAT without a fractional part, requiring 2 to 6 bytes.
* 0xb7 + <4_bytes>: Requires 5 bytes.

3.7 DOUBLE Representation Copy Chapter

DOUBLE has three representations:

* 0xb2 ~ 0xb3: Represents 0 and 1, occupying 1 byte.
* 0xb4 + <int64>: Represents a double without a fractional part, requiring 2 to 10 bytes.
* 0xb5 + <8_bytes>: Requires 9 bytes.

4. NULL/TRUE/FALSE

NULL/TRUE/FALSE are each represented by a single byte:

• 0xaf NULL
• 0xb0 FALSE
• 0xb1 TRUE

5. String Representation

There are several ways to represent strings:

* 0x49 ~ 0x78: Represents a LATIN1 string with a length of 0 to 47.
* 0x79 + <int32_bytes_len> + <bytes>: LATIN1 string.
* 0x7a + <int32_bytes_len> + <bytes>: UTF8 string.
* 0x7b + <int32_bytes_len> + <bytes>: UTF16 string.
* 0x7c + <int32_bytes_len> + <bytes>: UTF16LE string.
* 0x7d + <int32_bytes_len> + <bytes>: UTF16BE string.
* 0x7e + <int32_bytes_len> + <bytes>: GB18030 encoded string (this can reduce the length for Chinese characters).
* 0x7f + <int32_symbol>: If the symbol is negative, it is an index into the SymbolTable. If it is >= 0, it is a string symbol within the current data.

The string format is specifically designed to support LATIN1 encoded characters. This will be very helpful for improving string deserialization performance and will also benefit string serialization in Java 9+.

6. Date Representation

* 0xae + <int64_epoch_second> + <int32_nano>: TIMESTAMP, requires 3 to 15 bytes, corresponds to Java's Instant type.
* 0xad + <4_bytes_epoch_minutes>: TIMESTAMP_MINUTES, requires 5 bytes, corresponds to Java's Date type.
* 0xac + <4_bytes_epoch_seconds>: TIMESTAMP_SECONDS, requires 5 bytes, corresponds to Java's Date type.
* 0xab + <8_bytes_epoch_millis>: TIMESTAMP_MILLIS, requires 9 bytes, corresponds to Java's Date type.
* 0xaa + <2_bytes_year> + <1_byte_monthValue> + <1_byte_dayOfMonth> + <1_byte_hour> + <1_byte_minute> + <1_byte_second> + <int32_nano> + <str_zoneId>: Corresponds to Java's ZonedDateTime.
* 0xa9 + <2_bytes_year> + <1_byte_monthValue> + <1_byte_dayOfMonth>: Requires 5 bytes, corresponds to Java's LocalDate type.
* 0xa8 + <2_bytes_year> + <1_byte_monthValue> + <1_byte_dayOfMonth> + <1_byte_hour> + <1_byte_minute> + <1_byte_second> + <int32_nano>: Requires 8 to 12 bytes, corresponds to Java's LocalDateTime type.
* 0xa7 + <1_byte_hour> + <1_byte_minute> + <1_byte_second> + <int32_nano>: Requires 4 to 8 bytes, corresponds to Java's LocalTime type.

7. Object Type

An object type starts with 0xa6 and ends with 0xa5, containing any number of key-value pairs in between, as follows:

0xa6
    [<key_any> <value_any>]...
0xa5

8. Array Type

An array has two representations:

* 0x94 ~ 0xa3: Represents an array with 0 to 15 elements.
* 0xa4 + <int32_length> + <item...>

9. Reference

* 0x93 + <str_reference_path>

10. Typed_Any

This type enables complete serialization and deserialization.

* 0x92 + <str_typename> + <any>

11. Binary Type

0x91 + <int32_length> + <bytes>

12. char type

0x90 <byte1>

JSONB Jsonb Size Compare Cn (`docs/JSONB/jsonb_size_compare_cn.md`) Copy Section

带类型信息 KeyValue映射

不带类型信息 KeyValue映射

对象使用KeyValue的方式映射，这种方式的好处是增加和删除字段不影响兼容性

不带类型信息 Array映射

对象使用数组的方式映射，这种方式对增加/删除字段会影响兼容性

JSONB Jsonb Size Compare En (`docs/JSONB/jsonb_size_compare_en.md`) Copy Section

Key-Value Mapping with Type Information

Key-Value Mapping without Type Information

Objects are mapped using a Key-Value approach. The advantage of this method is that adding and deleting fields does not affect compatibility.