Skip to content

features_en.md

Latest commit

 

History

History
229 lines (191 loc) · 22.7 KB

features_en.md

File metadata and controls

229 lines (191 loc) · 22.7 KB

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.
WriteFloatSpecialAsString When enabled, NaN/Infinity will be serialized as "NaN", "Infinity", "-Infinity".

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.