JSONCodereBay 的 JSON 編碼解碼庫(kù)

JSONCoder 是一個(gè)輕量級(jí)的通用的 Java 對(duì)象序列化和反序列化到 JSON 格式的工具包，類似 Jackson 或者 FastJson。這個(gè)庫(kù)在 eBay 內(nèi)部廣泛使用多年。這并非是要替代其他常用庫(kù)，主要是解決了一些其他庫(kù)中不被支持的特別問(wèn)題。

一般的 JSON 庫(kù)都有大量的參數(shù)，eBay 單獨(dú)再開(kāi)發(fā)一個(gè) JSONCoder 的原因是，如果我們用 JSON 來(lái)做配置文件的時(shí)候經(jīng)常會(huì)受限于 JSON 標(biāo)準(zhǔn)的一些約束，但又不想使用放棄 JSON 改用 YAML 或者其他格式，那么你可以試試這個(gè) JSONCoder，該項(xiàng)目主要聚焦于解決如下問(wèn)題：

• 支持 JSON 擴(kuò)展建議 (JSONEX) ，該擴(kuò)展對(duì)用作配置用途的 JSON 比較友好，例如：
  • 支持注釋
  • key 的引號(hào)是可選的
  • 可自定義引號(hào)字符（避免選擇其他不同引號(hào)字符時(shí)不必要的轉(zhuǎn)義）
  • 支持 ES6 的多行字符串語(yǔ)義
  • 配置文件的合并 (例如：環(huán)境相關(guān)的配置覆蓋常規(guī)配置)
• 其次是 JSONCoder 支持通過(guò)檢測(cè)循環(huán)對(duì)象引用來(lái)支持任意 Java 對(duì)象的序列化。你不需要單獨(dú)再編寫(xiě)序列化器
• 支持對(duì)配置信息設(shè)置合理的默認(rèn)值，最小化注釋或配置使用。例如，默認(rèn)情況下，它會(huì)自動(dòng)忽略未知屬性以實(shí)現(xiàn)向前兼容性。
• 專注于開(kāi)發(fā)人員友好的API，同時(shí)還提供靈活的配置

詳細(xì)特性

• 自動(dòng)檢測(cè)循環(huán)對(duì)象引用，并對(duì)引用進(jìn)行序列化，避免堆棧溢出
• 可以在 getXXX 方法中提供額外的配置來(lái)包含類的字段
• 可插入式的自定義編碼和解碼器
• 可插入式的過(guò)濾器來(lái)包含和排除特別的字段，基于特定的類型
• 可配置過(guò)濾特定的類和子類以及字段
• 可配置過(guò)濾某些特定類型屬性，例如私有字段、枚舉名稱，只讀字段等
• 支持自定義日期格式以及在反序列化時(shí)自動(dòng)解析
• 在反序列化時(shí)通過(guò) $type 屬性支持類型的多態(tài)
• 反序列化支持泛型
• 反序列化的數(shù)據(jù)追加到已有的對(duì)象（增量解碼，例如用來(lái)合并多個(gè)配置字段)
• 支持嵌套的 JSON 字符串作為子 JSON 對(duì)象，避免不必要的字符串語(yǔ)義的轉(zhuǎn)義
• 支持向前兼容特性：靜默忽略未知屬性，使用 @DefaultEnum 引用默認(rèn)的枚舉
• 支持 JSON 擴(kuò)展建議格式 (JSONEX), 查看示例
• 要求 JDK 1.7 或者更新版本

更多關(guān)于 JSONCoder 的配置項(xiàng)請(qǐng)看 JSONCoderOption 

測(cè)試示例請(qǐng)看 JSONCoderTest

使用方法

1. Maven 依賴

    <dependency>
      <groupId>com.ebay.jsoncoder</groupId>
      <artifactId>JSONCoder</artifactId>
      <version>${jsonCoderVersion}</version>
    </dependency>

   You can get current version by searching maven central
2. 簡(jiǎn)單的序列化和反序列化

     // serialization
     JSONCoder.global.encode(o)
     // de-serialization
     SomeClass obj = JSONCoder.global.decode(str, SomeClass.class);

3. 字段和類的過(guò)濾

   JSONCoderOption opt = new JSONCoderOption();
   // For SomeClass1 and it's sub-classes, only include field: "field1ForClass1", "field2ForClass1"
   opt.getSimpleFilterFor(SomeClass1.class).setInclude(true).addProperties("field1ForClass1", "field2ForClass1");
   // For SomeClass2, exclude field: "fieldForClass2"
   opt.getSimpleFilterFor(SomeClass2.class).addProperties("fieldForClass2");
   // For any class, exclude field: "fieldInAnyClass"
   opt.getDefaultFilter().addProperties("fieldInAnyClass");
   // Exclude certain classes
   opt.addSkippedClasses(SomeExcludedClass.class);
   String result = JSONCoder.encode(bean, opt);
   

4. 泛型的反序列化

   String str = "['str1', 'str2', 'str3']";
   List<String> result = JSONCoder.global.decode(new DecodeReq<List<String>>(){}.setSource(str));

5. 反序列并合并到已有對(duì)象（增量解碼）

   TestBean bean = JSONCoder.global.decodeTo(jsonStr, bean);

6. 設(shè)置自定義的引號(hào)和自定義的縮進(jìn)

   JSONCoderOption opt = new JSONCoderOption();
   opt.getJsonOption().setQuoteChar('`');
   opt.getJsonOption().setIndentFactor(2);
   String jsonStr = JSONCoder.global.encode(someObj, opt);

7. 注冊(cè)自定義的編碼器

   public class CoderBigInteger implements ICoder<BigInteger>{
     public Class<BigInteger> getType() {return BigInteger.class;}
     
     @Override public TDNode encode(BigInteger o, BeanCoderContext context, TDNode target) {
       return target.setValue(o.toString());
     }
   
     @Override public BigInteger decode(TDNode jsonNode, Type type, BeanCoderContext context) {
       return new BigInteger((String)jsonNode.getValue());
     }
   }
   JSONCoderOption opt = new JSONCoderOption()
     .addCoder(new CoderBigInteger());
   String jsonStr = JSONCoder.global.encode(new BigInteger("1234"), opt);