编码踩坑——记一次fastjson引发的空指针问题、引用标识$ref

本篇介绍在使用fastjson过程中遇到的一个问题，从而引申出使用fastjson时的注意事项——（1）尽量避免在实体中定义 get 开头的方法；（2）避免较深的实体字段层级；（3）避免实体字段之间的引用关系；

问题描述

直接现象：某个预期不为null的字段在调用get方法时抛出了NPE；该字段是通过对存于数据库的某个放JSONString的字段，执行 JSON.parseObject方法反序列化成Java对象；

根据字段来源，找到原始的数据库存放JSONString的字段，发现字段中多了一个属性值，并且在JSON字符串中发现了带有$符号的KV，将该JSON字符格式化，如下：

{
    "allTicketList": [
        {
            "ticketAmount": 5000,
            "ticketId": 119
        }
    ],
    "strategy": "A",
    "loginStrategy": {
        "loginActName": "loginStrategyA",
        "rangeVOList": [
            {
                "days": 7,
                "ticketsInRange": [
                    {
                        "$ref": "$.allTicketList[0]"
                    }
                ]
            }
        ]
    }
}

上图中，allTicketList非预期中的字段，且ticketsInRange的属性值中出现了"$ref": "$.allTicketList[0]"这类变量符号；

实体类的定义如下：

@Data
class StrategyVO {
    private String strategy;
    private LoginStrategyVO loginStrategy;

    public List<TicketVO> getAllTicketList() {
        final List<TicketVO> allTickets = this.getLoginStrategy().getRangeVOList()
                .stream()
                .map(LoginRangeVO::getTicketsInRange)
                .flatMap(Collection::stream)
                .collect(Collectors.toList());
        return allTickets;
    }
}

@Data
class LoginStrategyVO {
    private String loginActName;
    private List<LoginRangeVO> rangeVOList;
}

@Data
class LoginRangeVO {
    private Integer days;
    private List<TicketVO> ticketsInRange;
}

@Data
class TicketVO {
    private Long ticketId;
    private Long ticketAmount;
}

可见，类StrategyVO的属性中存在多层嵌套，且根据领域模型的思想，在该类中定义了getAllTicketList方法（获取属性中的所有TicketVO对象）；

原因初步分析

根据上述的条件，可知：

（1）观察到getAllTicketList方法与JSON字符串中多出来的allTicketList字段存在某种关联，即如果StrategyVO类有allTicketList这个字段，那么它的getter方法就是getAllTicketList()；

（2）观察getAllTicketList方法的逻辑，其值实际上就是StrategyVO对象的属性中的引用，例如 getAllTicketList()[0] -> StrategyVO#loginStrategy#rangeVOList[0]#ticketsInRange[0]；

现在存在两个疑问：

1. fastjson为什么通过getAllTicketList方法推断StrategyVO对象有一个allTicketList属性？

2. 为什么当对象中存在相同引用的属性值时，除第一个引用，后面的会被类似"$ref": "$.allTicketList[0]"的KV替代？

问题1：FastJson如何判断有对象有哪些属性？

为了解决这个问题，需要debug一下JSON的源码，这里选择 JSON.toJsonString方法；以下是debug栈，这里只截图出关键代码；

1. com.alibaba.fastjson.serializer.JSONSerializer#write(java.lang.Object)

2. com.alibaba.fastjson.serializer.SerializeConfig#getObjectWriter(java.lang.Class<?>, boolean)

getObjectWriter方法是流程中的比较重要的方法之一，根据Java对象打印出其JSON字符串就是靠这里返回的 ObjectSerializer对象调用write方法获得的；

3. com.alibaba.fastjson.serializer.SerializeConfig#createJavaBeanSerializer(java.lang.Class<?>)

4. com.alibaba.fastjson.util.TypeUtils#buildBeanInfo(java.lang.Class<?>, java.util.Map<java.lang.String,java.lang.String>, com.alibaba.fastjson.PropertyNamingStrategy, boolean)

这里的FieldInfo类中的属性包括：字段名、类型、顺序、取值方法等，打印json时就是靠每个属性对应的这个类的对象来获取其json值，重点看一下这里的 computeGetters方法；

5. com.alibaba.fastjson.util.TypeUtils#computeGetters(java.lang.Class<?>, com.alibaba.fastjson.annotation.JSONType, java.util.Map<java.lang.String,java.lang.String>, java.util.Map<java.lang.String,java.lang.reflect.Field>, boolean, com.alibaba.fastjson.PropertyNamingStrategy)

这里省略的蓝色部分包含了对fastson注解JSONField的解析：

走到这里可以看到，实际是通过"get"前缀匹配方法名的：

6. com.alibaba.fastjson.util.TypeUtils#getPropertyNameByMethodName

至此，就可以知道，FastJson并不是根据对象的field来确定json属性的，而是根据get为前缀的方法名来计算json属性名的；

因此，在我们上述的例子中，由于getAllTicketList()方法的前缀是"get"，因此走一遍FastJson的解析json属性的逻辑，"误算"出来了一个allTicketList属性；

问题2：关于FastJson中的"$ref"符号？

（1）什么时候会出现"$ref"符号？

先说结论，JSON字符串中出现$ref: "$.list[2]"的原因是因为循环引用或内存对象重复；

（2）FastJson中定义的重复/循环引用？

简单说，重复引用就是一个集合/对象中的多个元素/属性同时引用同一对象；循环引用就是集合/对象中的多个元素/属性存在相互引用导致循环；

（3）为什么要用$ref引用而不是直接使用真实的变量值？

重复引用的情况比较好理解，使用$ref替换真实的对象值，可以很大程度减小JSON字符串的空间，反序列化时只需要根据解析规则找到对应的重复变量即可；

存在循环引用时，会触发StackOverflowError异常；例如，变量A和B互相持有彼此的引用，当序列化引擎解析A时，它发现这个对象持有一个B的引用，转而去解析B；解析B时，发现他又持有A的引用，又转回解析A；如此产生StackOverflowError异常；为了避免StackOverflowError异常，fastjson会对引用进行检测，如果检测到存在重复/循环引用的情况，FastJson默认会以"引用标识"代替同一对象，从而避免继续循环解析变量的值导致StackOverflowError；

（4）关闭FastJson引用检测的方法？

出现上述"$ref"符号的原因，正是FastJson开启了引用检测；查看FastJson的API，关闭FastJson的引用检测有局部关闭和全局关闭两种方式：

（1）局部关闭；就是在调用fastjson的地方指明使用的序列化器的特性，如下：

JSON.toJSONString(object, SerializerFeature.DisableCircularReferenceDetect);

（2）全局关闭；修改全局配置中的默认序列化器的特性，如下：

public class FastJsonHttpMessageConverterEx extends FastJsonHttpMessageConverter{
    public FastJsonHttpMessageConverterEx(){
        //在这里配置fastjson特性(全局设置的)
        FastJsonConfig fastJsonConfig = new FastJsonConfig();
        fastJsonConfig.setDateFormat("yyyy-MM-dd HH:mm:ss");    //自定义时间格式
        fastJsonConfig.setSerializerFeatures(SerializerFeature.WriteMapNullValue);  //正常转换null值
        fastJsonConfig.setSerializerFeatures(SerializerFeature.DisableCircularReferenceDetect);     //关闭循环引用
        this.setFastJsonConfig(fastJsonConfig);
    }

    @Override
    protected boolean supports(Class<?> clazz) {
        return super.supports(clazz);
    }
}

（5）关闭FastJson的“循环引用检测”特性并不能解决问题！

全局关闭这种方式是不推荐的，因为你无法预知在调用JSON.toJSONString方法的哪些地方会出现问题，如果一定要使用优先使用局部关闭的方式；

但是，尽管FastJson提供了SerializerFeature.DisableCircularReferenceDetect这个序列化选项，用来关闭引用检测；关闭引用检测后，重复引用对象时就不会被$ref代替，但是在循环引用时也会导致StackOverflowError异常；

避免重复/循环引用的正确姿势

（1）在编码时，使用新对象为集合或对象赋值，而非使用同一对象；

不要在多处引用同一个对象，这可以说是一种java编码规范；不仅有重复引用问题，这个对象既然被多个对象引用，那么它可能在多个业务场景都有可能被修改，因此需要时刻注意；建议使用深度clone，如Spring中自带的BeanUtil或一些二方包工具，做对象的深拷贝而非仅复制引用，创建新的对象，把原对象的属性值复制给新对象；

关于循环引用，这种逻辑本身就不常见，可能在特殊的设计模式中需要维护两个对象之间的关联；自己编码时需要尽量避免，可以转换成第三个对象持有这2个对象的引用；

（2）尽量不要关闭FastJson的引用检测来避免显示$ref；

引用检测是FastJson提供的一种避免运行时异常的优良机制，如果为了避免在重复引用时显示$ref而关闭它，会有很大可能导致循环引用时发生StackOverflowError异常；这也是FastJson默认开启引用检测的原因；

真正要解决的应该是如何避免重复引用/循环引用；

（3）合理的使用 @JSONField(serialize=false) 来关闭对部分字段的序列化

如果前端用不到实体中的某个属性，建议在该属性的get方法上加上注解属性@JSONField(serialize=false)，这样该属性就不会被序列化出来；这个可以解决重复引用问题，并且本文出现的问题就是这么解决的；

（4）避免在实体中定义以 "get" 开头的public方法；

通过上述的FastJson源码分析，可知FastJson是通过getter来解析对象中的属性的；当自己定义了一个以 "get" 开头的方法，如上面提到的StrategyVO#getAllTicketList方法，那么FastJson就会"误算"出一个StrategyVO#allTicketList属性；

FastJson引发问题的原因解释及解决方法

条件1：StrategyVO类中定义了 "get" 开头的方法StrategyVO#getAllTicketList；

导致的结果就是对象转成JSON字符串时多了个"预料之外的allTicketList属性"；

条件2：getAllTicketList方法中的逻辑是返回了子属性中的引用，即触发了"FastJson重复引用"的条件；

导致的结果就是在JSON中打出了allTicketList属性的值后，对于StrategyVO的子属性，直接使用了$ref引用符——"$ref": "$.allTicketList[0]"；

条件3："allTicketList属性"的顺序在StrategyVO#loginStrategy#rangeVOList#ticketsInRange前面；

FastJson默认按照属性名排序，如果StrategyVO#loginStrategy的属性值先解析，那么打出来JSON字符串中，"allTicketList属性"的属性值应该是带"$ref"的引用；

条件4：环境中有2个版本的代码，版本A代码中StrategyVO类有getAllTicketList方法，而版本B代码中StrategyVO类没有getAllTicketList方法；

尽管触发"FastJson重复引用"检测时，JSON字符串会出现"$ref"符号，这样的JSON字符串其实是可以被FastJson正确的解析恢复成对象的；但是这段JSON字符串如果作用到上面描述的代码B中，由于没有getAllTicketList方法，因此没有"多余的allTicketList属性"，从而B代码中FastJson反序列化时会出错；

解决方案

（1）如果都部署版本A代码，以上问题不会出现；

（2）如果allTicketList属性后于StrategyVO#loginStrategy解析，如使用 @JSONField(ordinal = 1) 注解属性，以上问题不会出现；

（3）如果不将getAllTicketList计入JSON序列化的getter，如使 @JSONField(serialize=false) 注解属性，以上问题不会出现；

最优的解决方案是修改实体中的getAllTicketList方法名，让其不要以 "get" 开头；此外，尽管领域模型的思想是把跟实体领域相关的能力方法封装到实体本身，但是在定义方法的时候最好自觉地加上 @JSONField(serialize=false) 注解属性以避免上述问题；

测试代码

1. 实体类定义，包含：目标类StrategyVO、属性类LoginStrategyVO、属性类LoginRangeVO、属性类TicketVO，以及与目标类具有相同成员属性的StrategyVOClone类（不带getter方法）；

@Data
class StrategyVO {

    private String strategy;
    private LoginStrategyVO loginStrategy;

    // 额外的getter方法
    public List<TicketVO> getAllTicketList() {
        final List<TicketVO> allTickets = this.getLoginStrategy().getRangeVOList()
                .stream()
                .map(LoginRangeVO::getTicketsInRange)
                .flatMap(Collection::stream)
                .collect(Collectors.toList());
        return allTickets;
    }
}

@Data
class LoginStrategyVO {
    private String loginActName;
    private List<LoginRangeVO> rangeVOList;
}

@Data
class LoginRangeVO {
    private Integer days;
    private List<TicketVO> ticketsInRange;
}

@Data
class TicketVO {
    private Long ticketId;
    private Long ticketAmount;
}

/**
 * 与StrategyVO属性值一致，但不带getAllTicketList方法
 */
@Data
class StrategyVOClone {
    private String strategy;
    private LoginStrategyVO loginStrategy;
}

2. 构建目标类对象的测试方法buildStrategyVO；

    /**
     * 构造StrategyVO测试数据
     */
    private static StrategyVO buildStrategyVO() {
        final StrategyVO strategyVO = new StrategyVO();
        strategyVO.setStrategy("A");

        final LoginStrategyVO loginStrategyVO = new LoginStrategyVO();
        loginStrategyVO.setLoginActName("loginStrategyA");

        final LoginRangeVO loginRangeVO = new LoginRangeVO();
        loginRangeVO.setDays(7);

        final TicketVO ticketVO = new TicketVO();
        ticketVO.setTicketId(119L);
        ticketVO.setTicketAmount(5000L);

        loginRangeVO.setTicketsInRange(Lists.newArrayList(ticketVO));
        loginStrategyVO.setRangeVOList(Lists.newArrayList(loginRangeVO));
        strategyVO.setLoginStrategy(loginStrategyVO);

        return strategyVO;
    }

3. 测试方法；

（1）测试getter导致JSON字符串出现额外的字段；以及使用SerializerFeature.DisableCircularReferenceDetect临时关闭引用检测从而不会出现"$ref"；

    /**
     * 由于getter方法StrategyVO#getAllTicketList()，导致json中有预期之外的字段allTicketList
     * 临时关闭引用检测时不会出现"$ref"；
     */
    @Test
    public void testGetter() {
        final StrategyVO strategyVO = buildStrategyVO();
        System.out.println(JSON.toJSONString(strategyVO));
        System.out.println("临时关闭引用检测:" + JSON.toJSONString(strategyVO, SerializerFeature.DisableCircularReferenceDetect));
    }

输出：

{"allTicketList":[{"ticketAmount":5000,"ticketId":119}],"loginStrategy":{"loginActName":"loginStrategyA","rangeVOList":[{"days":7,"ticketsInRange":[{"$ref":"$.allTicketList[0]"}]}]},"strategy":"A"}
临时关闭引用检测:{"allTicketList":[{"ticketAmount":5000,"ticketId":119}],"loginStrategy":{"loginActName":"loginStrategyA","rangeVOList":[{"days":7,"ticketsInRange":[{"ticketAmount":5000,"ticketId":119}]}]},"strategy":"A"}

（2）测试重复引用导致的"$ref"；

    /**
     * 重复引用导致的"$ref"；
     */
    @Test
    public void test$valueSameObject() {
        final StrategyVO strategyVO = buildStrategyVO();
        final ArrayList<StrategyVO> list = Lists.newArrayList();
        // 添加重复元素
        list.add(strategyVO);
        list.add(strategyVO);

        final String listJson = JSON.toJSONString(list);
        System.out.println(listJson);
    }

输出：

[{"allTicketList":[{"ticketAmount":5000,"ticketId":119}],"loginStrategy":{"loginActName":"loginStrategyA","rangeVOList":[{"days":7,"ticketsInRange":[{"$ref":"$[0].allTicketList[0]"}]}]},"strategy":"A"},{"$ref":"$[0]"}]

（3）测试带有"$ref"的JSONString，反序列化时使用原实体类型，是可以被fastjson正确解析并反序列化成对象的；

    /**
     * 带有"$ref"的JSONString，反序列化时使用原实体类型，是可以被fastjson正确解析并反序列化成对象的
     */
    @Test
    public void test$valueSameRefReverse() {
        final StrategyVO strategyVO = buildStrategyVO();
        final ArrayList<StrategyVO> list = Lists.newArrayList();
        // 添加重复元素
        list.add(strategyVO);
        list.add(strategyVO);

        System.out.println("序列化之前: " + list);
        // 带有"$ref"的JSONString
        final String jsonStrWith$Ref = JSON.toJSONString(list);
        System.out.println("序列化JSON字符串: " + jsonStrWith$Ref);
        // 使用JSON.parseArray(String, Class<T>)
        final List<StrategyVO> strategyVOS = JSON.parseArray(jsonStrWith$Ref, StrategyVO.class);
        System.out.println("反序列化后: " + strategyVOS);
    }

输出：

序列化之前: [StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])])), StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])]))]
序列化JSON字符串: [{"allTicketList":[{"ticketAmount":5000,"ticketId":119}],"loginStrategy":{"loginActName":"loginStrategyA","rangeVOList":[{"days":7,"ticketsInRange":[{"$ref":"$[0].allTicketList[0]"}]}]},"strategy":"A"},{"$ref":"$[0]"}]
反序列化后: [StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])])), StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])]))]

（4）测试带有"$ref"的JSONString，反序列化时如果使用不带getAllTicketList方法的实体接收，则会丢失字段，也就是本次出现的异常复现；

    /**
     * 带有"$ref"的JSONString，反序列化时如果使用不带getAllTicketList方法的实体接收，则会丢失字段
     */
    @Test
    public void test$valueSameRefReverse2() {
        final StrategyVO strategyVO = buildStrategyVO();
        System.out.println("strategyVO: " + strategyVO);
        String jsonString = JSON.toJSONString(strategyVO);
        System.out.println("jsonString: " + jsonString);
        final StrategyVO strategyVOFrJson = JSON.parseObject(jsonString, StrategyVO.class);
        System.out.println("strategyVOFrJson: " + strategyVOFrJson);
        final StrategyVOClone strategyVOClone = JSON.parseObject(jsonString, StrategyVOClone.class);
        System.out.println("strategyVOCloneFrJson(丢失字段): " + strategyVOClone);
    }

输出：

strategyVO: StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])]))
jsonString: {"allTicketList":[{"ticketAmount":5000,"ticketId":119}],"loginStrategy":{"loginActName":"loginStrategyA","rangeVOList":[{"days":7,"ticketsInRange":[{"$ref":"$.allTicketList[0]"}]}]},"strategy":"A"}
strategyVOFrJson: StrategyVO(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[TicketVO(ticketId=119, ticketAmount=5000)])]))
strategyVOCloneFrJson(丢失字段): StrategyVOClone(strategy=A, loginStrategy=LoginStrategyVO(loginActName=loginStrategyA, rangeVOList=[LoginRangeVO(days=7, ticketsInRange=[null])]))

（5）循环引用时，使用SerializerFeature.DisableCircularReferenceDetect临时关闭引用检测从而导致的StackOverflowError；

    /**
     * 循环引用时，使用SerializerFeature.DisableCircularReferenceDetect临时关闭引用检测从而导致的StackOverflowError
     */
    @Test
    public void testDisableCircularReference() {
        // map1引用了map2，而map2又引用map1，导致循环引用
        Map<String, Object> map1 = new HashMap<>();
        Map<String, Object> map2 = new HashMap<>();
        map1.put("map", map2);
        map2.put("map", map1);
        System.out.println("map1Json:" + JSON.toJSONString(map1) + " map1Json:" + JSON.toJSONString(map1));
        System.out.println("临时关闭引用检测 map1Json:" + JSON.toJSONString(map1, SerializerFeature.DisableCircularReferenceDetect) +
                "临时关闭引用检测 map2Json:" + JSON.toJSONString(map2, SerializerFeature.DisableCircularReferenceDetect));
    }

输出：

map1Json:{"map":{"map":{"$ref":".."}}} map1Json:{"map":{"map":{"$ref":".."}}}

java.lang.StackOverflowError
	at com.alibaba.fastjson.serializer.SerializeWriter.writeStringWithDoubleQuote(SerializeWriter.java:840)
	at com.alibaba.fastjson.serializer.SerializeWriter.writeFieldName(SerializeWriter.java:2384)
	at com.alibaba.fastjson.serializer.MapSerializer.write(MapSerializer.java:226)
	at com.alibaba.fastjson.serializer.MapSerializer.write(MapSerializer.java:44)
    ...

小结

本篇通过一个日常开发中遇到的fastjson序列化相关的问题，通过源码分析，知道了fastjson计算对象的属性值是基于getter方法而非成员变量列表；并且在序列化过程中getter方法会被执行，因此理论上存在反序列化攻击漏洞；

为了避免StackOverflowError异常，fastjson会对引用进行检测，如果检测到存在重复/循环引用的情况，FastJson默认会以"引用标识$ref"代替同一对象，从而避免继续循环解析变量的值导致StackOverflowError；

反序列化时，尽管触发"FastJson重复引用"检测时，JSON字符串会出现"$ref"符号，这样的JSON字符串如果使用对象所在的类解析，是可以被FastJson正确的解析恢复成原对象的；

建议：尽量避免触发触发"FastJson重复引用"检测从而导致JSON字符串中出现预期之外的"引用标识$ref"；

本文参考：

使用fastjson时出现$ref: "$.list[2]"的解决办法（重复引用） - 简书

【Fastjson】Fastjson反序列化由浅入深 - Aur0ra* - 博客园

fastjson反序列过程中getter 和 setter方法 - TT0TT - 博客园