308 lines
9.3 KiB
Markdown
308 lines
9.3 KiB
Markdown
# Annotations provided by FASTJSON2
|
|
|
|
## 1. JSONField
|
|
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
|
|
|
|
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
|
|
```java
|
|
public class A {
|
|
@JSONField(name = "ID")
|
|
public int id;
|
|
}
|
|
```
|
|
|
|
* Configured on public getter/setter methods
|
|
```java
|
|
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
|
|
|
|
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.
|
|
|
|
```java
|
|
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
|
|
|
|
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
|
|
```java
|
|
public class VO {
|
|
@JSONField(serialize = false)
|
|
public Date date;
|
|
}
|
|
```
|
|
|
|
* Ignore specific fields when configuring deserialization
|
|
```java
|
|
public class VO {
|
|
@JSONField(deserialize = false)
|
|
public Date date;
|
|
}
|
|
```
|
|
|
|
### 1.4 The order of the serialized output of configuration fields
|
|
|
|
The order of output during serialization can be configured through JSONField.ordinal.
|
|
|
|
```java
|
|
public static class VO {
|
|
@JSONField(ordinal = 1)
|
|
public String type;
|
|
|
|
@JSONField(ordinal = 2)
|
|
public String templateId;
|
|
}
|
|
```
|
|
|
|
### 1.5 Configure Serialize Features
|
|
|
|
The serialized Feature can be specified through JSONField.serializeFeatures. More configuration features reference [https://alibaba.github.io/fastjson2/features_cn](https://alibaba.github.io/fastjson2/features_cn) 。
|
|
```java
|
|
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)
|
|
|
|
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 :
|
|
|
|
```java
|
|
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.6 Configure Enum to serialize and deserialize based on one of the fields through JSONField(value = true)
|
|
|
|
Configure @JSONField(value = true) on the enum field, serialization and serialization will be based on this field
|
|
|
|
For example :
|
|
|
|
```java
|
|
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);
|
|
}
|
|
```
|
|
|
|
## 2. @JSONType
|
|
|
|
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.
|
|
| JSONType Annotation Supported | Introduction |
|
|
|---------------------|-----------------------------------------------------------|
|
|
| ignores | Some fields are ignored when serialize |
|
|
| alphabetic | Maintain native class field order when configuring serialize |
|
|
| serializeFeatures | `Features` of `JSONWriter` when configuring serialize |
|
|
| deserializeFeatures | `Features` of `JSONReader` when configuring deserialize |
|
|
| orders | Field order when configuring serialize |
|
|
| naming | Configure the `NamingStrategy` of the field name, for details, please refer to the `PropertyNamingStrategy` enumeration class |
|
|
| serializer | custom serializer behavior |
|
|
| deserializer | custom deserializer behavior |
|
|
| serializeFilters | Control serializer behavior through custom columnization `Filters` |
|
|
|
|
### 2.1 Configure ignored fields for serialize and deserialize
|
|
|
|
In the example below, the serialized output only includes id1, ignoring id2 and id3.
|
|
|
|
```java
|
|
@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
|
|
|
|
Starting from version 2.0.13, you can use `@JSONType(alphabetic = false)` to configure serialization to maintain the order of native class fields.
|
|
|
|
```java
|
|
@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
|
|
|
|
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_cn.md](features_cn.md) 。
|
|
|
|
```java
|
|
@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
|
|
|
|
You can use `@JSONType(orders = {"filed1", "filed2"})` annotation to specify the field order during serialize.
|
|
|
|
```java
|
|
@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"}
|
|
}
|
|
}
|
|
```
|
|
|
|
# 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](https://alibaba.github.io/fastjson2/mixin_cn)
|