FastJSON 2.x 核心用法與避坑指南：序列化配置、循環引用、泛型反序列化、安全模式

反序列化配置

JSONReader.Feature[] features = {
    JSONReader.Feature.SupportAutoType,      // 開啟 autoType (需配合白名單)
    JSONReader.Feature.UseDefaultConstructorAsPossible, // 優先無參構造器
    JSONReader.Feature.FieldBased,           // 基於字段反序列化 (含 private)
    JSONReader.Feature.IgnoreSetValueError,  // 忽略 setter 異常
    JSONReader.Feature.InitStringFieldAsEmpty, // null 字符串轉 ""
    JSONReader.Feature.TrimString,           // 字符串去首尾空白
    JSONReader.Feature.SupportSmartMatch,    // 智能匹配 (忽略大小寫/下劃線)
};

// 泛型反序列化 (核心技巧)
List users = JSON.parseObject(jsonStr, new TypeReference>() {});
// 或
Type type = new TypeToken>() {}.getType();
List users = JSON.parseObject(jsonStr, type);

安全模式：autoType 白名單機制 (2.x 核心防線)

// 1. 全局白名單 (啟動時配置)
ParserConfig.getGlobalInstance().addAccept("com.myapp.dto.");
ParserConfig.getGlobalInstance().addAccept("com.myapp.vo.");

// 2. 線程級白名單 (臨時擴展)
ParserConfig config = ParserConfig.getGlobalInstance();
config.addAccept("com.thirdparty.model.");

// 3. 代碼中指定
JSON.parseObject(json, User.class, 
    JSONReader.Feature.SupportAutoType, 
    (typeName, clazz) -> typeName.startsWith("com.myapp.") // 自定義校驗函數
);

// 4. 禁用 autoType (默認關閉，最安全)
JSON.parseObject(json, User.class); // 無 @type 也能正常反序列化

鐵律：生產環境默認關閉 autoType，僅對受信內部類型開啟白名單，絕不對外部輸入開啟。

循環引用處理

public class Node {
    public String name;
    public Node parent;   // 父節點
    public List children; // 子節點
}

// 序列化：默認拋出 StackOverflowError
// 解決：@JSONField(serialize = false) 忽略反向引用
public class Node {
    public String name;
    @JSONField(serialize = false)
    public Node parent;
    public List children;
}

// 或配置
JSONWriter.Feature.DisableCircularReferenceDetect // 不推薦，會無限遞歸
// 最佳：業務層構建無環 DTO / 使用 @JSONField(serialze=false)

日期時間處理最佳實踐

// 實體類
public class Event {
    @JSONField(format = "yyyy-MM-dd HH:mm:ss") // 序列化格式
    @JSONField(parseFormat = "yyyy-MM-dd HH:mm:ss") // 反序列化格式 (可多格式兼容)
    private LocalDateTime eventTime;
    
    @JSONField(format = "yyyy-MM-dd")
    private LocalDate eventDate;
}

// 全局默認格式
JSONFactory.getDefaultObjectWriterProvider().config(
    JSONWriter.Feature.WriteLocalDateTimeAsISO8601 // ISO 8601 標準
);
JSONFactory.getDefaultObjectReaderProvider().config(
    JSONReader.Feature.UseNativeObject // 直接讀為 LocalDateTime
);

Spring Boot 整合 (Web MVC)

@Configuration
public class FastJsonConfig implements WebMvcConfigurer {

    @Override
    public void configureMessageConverters(List> converters) {
        FastJsonHttpMessageConverter converter = new FastJsonHttpMessageConverter();
        
        FastJsonConfig config = new FastJsonConfig();
        config.setWriterFeatures(
            JSONWriter.Feature.WriteNulls,
            JSONWriter.Feature.WriteEnumUsingName,
            JSONWriter.Feature.WriteLocalDateTimeAsISO8601,
            JSONWriter.Feature.BrowserCompatible
        );
        config.setReaderFeatures(
            JSONReader.Feature.SupportSmartMatch,
            JSONReader.Feature.TrimString,
            JSONReader.Feature.InitStringFieldAsEmpty
        );
        // 安全：不開啟 autoType，依賴 @Type 注解或白名單
        config.setParserConfig(ParserConfig.getGlobalInstance());
        
        converter.setFastJsonConfig(config);
        converter.setDefaultCharset(StandardCharsets.UTF_8);
        converters.add(0, converter); // 優先級最高
    }
}

常見坑點速查

總結

FastJSON 2.x 是 Java JSON 處理的**性能之王**與**安全新標桿**。掌握 Feature 配置組合、**TypeReference 泛型保留**、autoType 白名單機制**、Long→String 精度保護**、日期格式統一、Spring MVC 整合，即可覆蓋 99% 場景。記住：安全配置不可妥協，性能優化按需開啟，泛型反序列化用 TypeReference。