9.3 KiB
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
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
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
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
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
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)
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.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 :
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.
@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.
@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 。
@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.
@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