mirror of https://github.com/alibaba/fastjson2.git
English Documentation
This commit is contained in:
Aaron
parent
48a4d94b6f
commit
d9c21ffcb4
|
|
@ -1,4 +1,5 @@
|
|||
[](https://github.com/alibaba/fastjson2/actions/workflows/ci.yaml)
|
||||
[](https://github.com/alibaba/fastjson2/actions/workflows/ci.yaml)
|
||||
[](https://codecov.io/gh/alibaba/fastjson2/branch/main)
|
||||
[](https://search.maven.org/artifact/com.alibaba.fastjson2/fastjson2)
|
||||
[](https://github.com/alibaba/fastjson2/releases)
|
||||
|
|
@ -11,6 +12,8 @@
|
|||
[](https://github.com/alibaba/fastjson2/network/dependents)
|
||||
[](https://github.com/alibaba/fastjson2/graphs/contributors)
|
||||
|
||||
##### 语言： 中文 | [English](README_EN.md)
|
||||
|
||||
# 1. FASTJSON v2
|
||||
|
||||
`FASTJSON v2`是`FASTJSON`项目的重要升级，目标是为下一个十年提供一个高性能的`JSON`库。通过同一套`API`，
|
||||
|
|
@ -131,7 +134,7 @@ class JSONReader {
|
|||
static JSONReader of(char[] chars);
|
||||
|
||||
// 构造基于json格式byte数组输入的JSONReader
|
||||
static JSONReader ofJSONB(byte[] jsonbBytes)
|
||||
static JSONReader ofJSONB(byte[] jsonbBytes);
|
||||
}
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,262 @@
|
|||
[](https://github.com/alibaba/fastjson2/actions/workflows/ci.yaml)
|
||||
[](https://github.com/alibaba/fastjson2/actions/workflows/ci.yaml)
|
||||
[](https://codecov.io/gh/alibaba/fastjson2/branch/main)
|
||||
[](https://search.maven.org/artifact/com.alibaba.fastjson2/fastjson2)
|
||||
[](https://github.com/alibaba/fastjson2/releases)
|
||||
[](https://openjdk.java.net/)
|
||||
[](https://www.apache.org/licenses/LICENSE-2.0.html)
|
||||
[](https://gitpod.io/#https://github.com/alibaba/fastjson2)
|
||||
[](https://oss.sonatype.org/content/repositories/snapshots/com/alibaba/fastjson2/)
|
||||
[](https://github.com/alibaba/fastjson2/stargazers)
|
||||
[](https://github.com/alibaba/fastjson2/fork)
|
||||
[](https://github.com/alibaba/fastjson2/network/dependents)
|
||||
[](https://github.com/alibaba/fastjson2/graphs/contributors)
|
||||
|
||||
##### Language: [中文](README.md) | English
|
||||
|
||||
# 1. FASTJSON v2
|
||||
|
||||
`FASTJSONv2` is an upgrade of the `FASTJSON`, with the goal of providing a highly optimized `JSON` library for the next ten years.
|
||||
|
||||
- Supports the JSON and JSONB Protocols
|
||||
- Supports full parsing and partial parsing
|
||||
- Supports Java servers and Android Clients, and has big data applications.
|
||||
|
||||
|
||||
|
||||
Related Documents:
|
||||
|
||||
- `JSONB` format documentation:
|
||||
https://github.com/alibaba/fastjson2/wiki/jsonb_format_cn
|
||||
- `FASTJSON v2`'s performance has been significantly improved. For the benchmark, see here:
|
||||
https://github.com/alibaba/fastjson2/wiki/fastjson_benchmark
|
||||
|
||||
# 2. Setup
|
||||
|
||||
## 2.1 `Maven` Build System
|
||||
|
||||
`FASTJSONv2`'s groupId is different from versions `1.x`, it is instead `com.alibaba.fastjson2`:
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.alibaba.fastjson2</groupId>
|
||||
<artifactId>fastjson2</artifactId>
|
||||
<version>2.0.2</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
Find the latest version of `FASTJSONv2`at [maven.org](https://search.maven.org/artifact/com.alibaba.fastjson2/fastjson2).
|
||||
|
||||
## 2.2 `fastjson v1` Compatibility Package
|
||||
|
||||
If you are using `fastjson 1.2.x`, you can use the compatibility package. The compatibility package cannot guarantee 100% compatibility. Please test it yourself and report any problems.
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.alibaba</groupId>
|
||||
<artifactId>fastjson</artifactId>
|
||||
<version>2.0.2</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## 2.3 Best Practice
|
||||
|
||||
The package name of `fastjson v2` is different from `fastjson v1`. It is `com.alibaba.fastjson2`. If you used `fastjson v1` before, simply change the package name.
|
||||
|
||||
```java
|
||||
package com.alibaba.fastjson2;
|
||||
|
||||
class JSON {
|
||||
// Parse String into JSONObject
|
||||
static JSONObject parseObject(String str);
|
||||
|
||||
// Parse a String into JSONArray
|
||||
static JSONArray parseArray(String str);
|
||||
|
||||
// Parse a String into a Java Object
|
||||
static T parseObject(byte[] utf8Bytes, Class<T> objectClass);
|
||||
|
||||
// Output a Java Object into a string
|
||||
static String toJSONString(Object object);
|
||||
|
||||
// Output a Java Object into a JSON Byte Array
|
||||
static byte[] toJSONBytes(Object object);
|
||||
}
|
||||
|
||||
class JSONB {
|
||||
// Parse a JSONB byte array into a Java Object
|
||||
static T parseObject(byte[] jsonbBytes, Class<T> objectClass);
|
||||
|
||||
// Convert a Java Object into a JSONB Byte Array
|
||||
static byte[] toBytes(Object object);
|
||||
}
|
||||
|
||||
class JSONObject {
|
||||
Object get(String key);
|
||||
int getIntValue(String key);
|
||||
Integer getInteger(String key);
|
||||
long getLongValue(String key);
|
||||
Long getLong(String key);
|
||||
T getObject(String key, Class<T> objectClass);
|
||||
|
||||
// Convert JSONObject into a Java Object
|
||||
T toJavaObject(Class<T> objectClass);
|
||||
}
|
||||
|
||||
class JSONArray {
|
||||
Object get(int index);
|
||||
int getIntValue(int index);
|
||||
Integer getInteger(int index);
|
||||
long getLongValue(int index);
|
||||
Long getLong(int index);
|
||||
T getObject(int index, Class<T> objectClass);
|
||||
}
|
||||
|
||||
class JSONPath {
|
||||
// Construct a JSONPath
|
||||
static JSONPath of(String path);
|
||||
|
||||
// The input is directly parsed according to the path,
|
||||
// which will be parsed and optimized but not fully parsed.
|
||||
Object extract(JSONReader jsonReader);
|
||||
|
||||
// Evaluate object based on the path
|
||||
Object eval(Object rootObject);
|
||||
}
|
||||
|
||||
class JSONReader {
|
||||
// Constructs a JSONReader given a JSON String
|
||||
static JSONReader of(String str);
|
||||
|
||||
// Constructs a JSONReader given a UTF-8 encoded byte array
|
||||
static JSONReader of(byte[] utf8Bytes);
|
||||
|
||||
// Construct a JSONReader given a char array
|
||||
static JSONReader of(char[] chars);
|
||||
|
||||
// Construct a JSONReader given a JSONB-formatted byte array
|
||||
static JSONReader ofJSONB(byte[] jsonbBytes);
|
||||
}
|
||||
```
|
||||
|
||||
# 3. Reading a `JSON` Object
|
||||
|
||||
```java
|
||||
String str = "{\"id\":123}";
|
||||
JSONObject jsonObject = JSON.parseObject(str);
|
||||
int id = jsonObject.getIntValue("id");
|
||||
```
|
||||
|
||||
```java
|
||||
String str = "[\"id\", 123]";
|
||||
JSONArray jsonArray = JSON.parseArray(str);
|
||||
String name = jsonArray.getString(0);
|
||||
int id = jsonArray.getIntValue(1);
|
||||
```
|
||||
|
||||
# 4. Generate `JSON` using a `JavaBean` object
|
||||
|
||||
## 4.1 Generating a `JSON` String using `JavaBean`
|
||||
|
||||
```java
|
||||
class Product {
|
||||
public int id;
|
||||
public String name;
|
||||
}
|
||||
|
||||
Product product = new Product();
|
||||
product.id = 1001;
|
||||
product.name = "DataWorks";
|
||||
|
||||
JSON.toJSONString(product);
|
||||
|
||||
// Produces the following result
|
||||
{
|
||||
"id" : 1001,
|
||||
"name" : "DataWorks"
|
||||
}
|
||||
|
||||
JSON.toJSONString(product, JSONWriter.Feature.BeanToArray);
|
||||
// Produces the following result
|
||||
[1001, "DataWorks"]
|
||||
```
|
||||
|
||||
## 4.2 Generating a UTF-8 encoded byte array from a ``JavaBean`` Object
|
||||
|
||||
```java
|
||||
Product product = ...;
|
||||
byte[] utf8JSONBytes = JSON.toJSONBytes(product);
|
||||
```
|
||||
|
||||
## 4.3 将`JavaBean`对象生成`JSONB`格式的`byte[]`
|
||||
|
||||
```java
|
||||
Product product = ...;
|
||||
byte[] jsonbBytes = JSONB.toBytes(product);
|
||||
|
||||
byte[] jsonbBytes = JSONB.toBytes(product, JSONWriter.Feature.BeanToArray);
|
||||
```
|
||||
|
||||
# 5. Reading `JSON` using `JavaBean`
|
||||
|
||||
## 5.1 Reading a String using `JavaBean`
|
||||
|
||||
```java
|
||||
String str = "{\"id\":123}";
|
||||
Product product = JSON.parseObject(str, Product.class);
|
||||
```
|
||||
|
||||
## 5.2 Reading a `UTF-8`encoded byte array with `JavaBean`
|
||||
|
||||
```java
|
||||
byte[] utf8Bytes = "{\"id\":123}".getBytes(StandardCharsets.UTF_8);
|
||||
Product product = JSON.parseObject(utf8Bytes, Product.class);
|
||||
```
|
||||
|
||||
## 5.3 Reading `JSONB` data with `JavaBean`
|
||||
|
||||
```java
|
||||
byte[] jsonbBytes = ...
|
||||
Product product = JSONB.parseObject(jsonbBytes, Product.class);
|
||||
|
||||
Product product = JSONB.parseObject(jsonbBytes, Product.class, JSONReader.Feature.SupportBeanArrayMapping);
|
||||
```
|
||||
|
||||
# 6. Using `JavaPath`
|
||||
|
||||
## 6.1 Use `JavaPath` selection to read data
|
||||
|
||||
```java
|
||||
String str = ...;
|
||||
|
||||
// Caching and Reusing can improve performance
|
||||
JSONPath path = JSONPath.of("$.id");
|
||||
|
||||
JSONReader parser = JSONReader.of(str);
|
||||
Object result = path.extract(parser);
|
||||
```
|
||||
|
||||
## 6.2 Reading partial `utf8Bytes` data using `JavaPath`
|
||||
|
||||
```java
|
||||
byte[] utf8Bytes = ...;
|
||||
|
||||
// Caching and Reusing can improve perforamance
|
||||
JSONPath path = JSONPath.of("$.id");
|
||||
|
||||
JSONReader parser = JSONReader.of(utf8Bytes);
|
||||
Object result = path.extract(parser);
|
||||
```
|
||||
|
||||
## 6.3 Reading partial `jsonbBytes` data using `JsonPath`
|
||||
|
||||
```java
|
||||
byte[] jsonbBytes = ...;
|
||||
|
||||
// Caching and Reusing can improve performance
|
||||
JSONPath path = JSONPath.of("$.id");
|
||||
|
||||
// Note that this is using the ofJSONB method
|
||||
JSONReader parser = JSONReader.ofJSONB(jsonbBytes);
|
||||
Object result = path.extract(parser);
|
||||
```
|
||||
Loading…
Reference in New Issue