JSONCoder

JSONCoder 是一个轻量级的通用的 Java 对象序列化和反序列化到 JSON 格式的工具包，类似 Jackson 或者 FastJson。这个库在 eBay 内部广泛使用多年。这并非是要替代其他常用库，主要是解决了一些其他库中不被支持的特别问题。

一般的 JSON 库都有大量的参数，eBay 单独再开发一个 JSONCoder 的原因是，如果我们用 JSON 来做配置文件的时候经常会受限于 JSON 标准的一些约束，但又不想使用放弃 JSON 改用 YAML 或者其他格式，那么你可以试试这个 JSONCoder，该项目主要聚焦于解决如下问题：

• 支持 JSON 扩展建议 (JSONEX) ，该扩展对用作配置用途的 JSON 比较友好，例如：
  • 支持注释
  • key 的引号是可选的
  • 可自定义引号字符（避免选择其他不同引号字符时不必要的转义）
  • 支持 ES6 的多行字符串语义
  • 配置文件的合并 (例如：环境相关的配置覆盖常规配置)
• 其次是 JSONCoder 支持通过检测循环对象引用来支持任意 Java 对象的序列化。你不需要单独再编写序列化器
• 支持对配置信息设置合理的默认值，最小化注释或配置使用。例如，默认情况下，它会自动忽略未知属性以实现向前兼容性。
• 专注于开发人员友好的API，同时还提供灵活的配置

详细特性

• 自动检测循环对象引用，并对引用进行序列化，避免堆栈溢出
• 可以在 getXXX 方法中提供额外的配置来包含类的字段
• 可插入式的自定义编码和解码器
• 可插入式的过滤器来包含和排除特别的字段，基于特定的类型
• 可配置过滤特定的类和子类以及字段
• 可配置过滤某些特定类型属性，例如私有字段、枚举名称，只读字段等
• 支持自定义日期格式以及在反序列化时自动解析
• 在反序列化时通过 $type 属性支持类型的多态
• 反序列化支持泛型
• 反序列化的数据追加到已有的对象（增量解码，例如用来合并多个配置字段)
• 支持嵌套的 JSON 字符串作为子 JSON 对象，避免不必要的字符串语义的转义
• 支持向前兼容特性：静默忽略未知属性，使用 @DefaultEnum 引用默认的枚举
• 支持 JSON 扩展建议格式 (JSONEX), 查看示例
• 要求 JDK 1.7 或者更新版本

更多关于 JSONCoder 的配置项请看 JSONCoderOption 

测试示例请看 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. 简单的序列化和反序列化

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

3. 字段和类的过滤

   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. 反序列并合并到已有对象（增量解码）

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

6. 设置自定义的引号和自定义的缩进

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

7. 注册自定义的编码器

   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);