fastjson2/docs/features_en.md

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

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

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

JSONReader.Feature	Description
FieldBased	Field-based deserialization. If not configured, it will be serialized based on public field and getter methods by default. After configuration, it will be deserialized based on non-static fields (including private). It will be safer under FieldBased configuration.
IgnoreNoneSerializable	Deserialization ignores fields of non-Serializable types.
SupportArrayToBean	Support mapping arrays to Bean objects.
InitStringFieldAsEmpty	Initialize the String field to the empty string, e.g: "".
SupportAutoType	Automatic type is supported. To read JSON data with "@type" type information, you need to open SupportAutoType explicitly.
SupportSmartMatch	The default is camel case exact match, after opening this, it can intelligently identify the case in camel/upper/pascal/snake/Kebab.
UseNativeObject	The default is to use JSONObject and JSONArray, and LinkedHashMap and ArrayList will be used after configuration.
SupportClassForName	To support fields of type Class, use Class.forName. This is disabled by default for security.
IgnoreSetNullValue	Fields with null input are ignored.
UseDefaultConstructorAsPossible	Use the default constructor as much as possible, and use Unsafe.allocateInstance to implement this option when fieldBase is turned on and this option is not turned on.
UseBigDecimalForFloats	The default configuration will use BigDecimal to parse decimals, and will use Float when turned on.
UseBigDecimalForDoubles	The default configuration will use BigDecimal to parse decimals, and Double will be used when turned on.
ErrorOnEnumNotMatch	By default, if the name of the Enum does not match, it will be ignored, and an exception will be thrown if it does not match when turned on.
TrimString	Trim the string values read.
ErrorOnNotSupportAutoType	Throw an error when encountering AutoType (default is to ignore).
DuplicateKeyValueAsArray	Duplicate Key Values are not replaced but combined into an array.
AllowUnQuotedFieldNames	Support field names without double quotes.
NonStringKeyAsString	Treat non-String keys as String.
Base64StringAsByteArray	Deserialize Base64 formatted strings as byte[].
DisableSingleQuote	Do not allow single quote in key name and values.

5. JSONWriter.Feature

JSONWriter.Feature	Description
FieldBased	Field-based serialization. If not configured, it will be serialized based on public field and getter methods by default. After configuration, it will be serialized based on non-static fields (including private).
IgnoreNoneSerializable	Serialization ignores fields of non-Serializable types.
BeanToArray	Sequence the objects into an array format like [101,"XX"], which will be smaller.
WriteNulls	Serialize and output null value fields.
BrowserCompatible	For integers that exceed the range supported by JavaScript, output them in string format.
NullAsDefaultValue	Output null values as default values: Number types as 0, decimal Number types as 0.0, String type as "", Character type as \u0000, array and Collection types as [], and others as {}.
WriteBooleanAsNumber	Write true as 1 and false as 0.
WriteNonStringValueAsString	Write values of non-String types as Strings, excluding objects and data types.
WriteClassName	Write type information when serializing.
NotWriteRootClassName	When WriteClassName is turned on, the type information of the root object is not output.
NotWriteHashMapArrayListClassName	When WriteClassName is opened, the type information of objects of type HashMap/ArrayList is not output, and the deserialization combined with UseNativeObject can save the size of the serialized result.
NotWriteDefaultValue	When the value of the field is the default value, it is not output, which can save the size of the serialized result.
WriteEnumsUsingName	Serialize enum using name.
WriteEnumUsingToString	Serialize enum using toString method.
IgnoreErrorGetter	Ignore errors in getter methods.
PrettyFormat	Format the output.
ReferenceDetection	Turn on reference detection, which is turned off by default, which is inconsistent with fastjson 1.x.
WriteNameAsSymbol	Output field names as symbols, this only works under JSONB.
WriteBigDecimalAsPlain	Serialize BigDecimal using toPlainString, avoiding scientific notation.
UseSingleQuotes	Use single quotes.
MapSortField	Sort the KeyValue in Map by Key before output. This Feature is needed in some signature verification scenarios.
WriteNullListAsEmpty	Serialize null value fields of List type as empty array "[]".
WriteNullStringAsEmpty	Serialize null value fields of String type as empty string "".
WriteNullNumberAsZero	Serialize null value fields of Number type as 0.
WriteNullBooleanAsFalse	Serialize null value fields of Boolean type as false.
NotWriteEmptyArray	Do not output array type fields when length is 0.
WriteNonStringKeyAsString	Treat non-String keys in Map as String type for output.
ErrorOnNoneSerializable	Throw an error when serializing non-Serializable objects.
WritePairAsJavaBean	Serialize Pair objects from Apache Commons as JavaBean.
BrowserSecure	Browser security, will escape '<' '>' '(' ')' characters for output.
WriteLongAsString	Serialize Long as String.
WriteEnumUsingOrdinal	Serialize Enum using Ordinal, the default is name.
WriteThrowableClassName	Include type information when serializing Throwable.
LargeObject	This is a protection measure to prevent serialization of circular reference objects from consuming excessive resources.
UnquoteFieldName	Output Key without quotes.
NotWriteSetClassName	When WriteClassName is turned on and you don't want to output the type information of Set, use this Feature.
NotWriteNumberClassName	When WriteClassName is turned on and you don't want to output the type information of Number, such as the suffixes L/S/B/F/D, use this Feature.

6. Usage Examples

6.1 Serialization Examples

// 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

// 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

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

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.