Fastjson Pitfalls: Date Formatting Glitch and Circular Reference Chaos Explained

In this article the author shares a personal debugging journey with Alibaba’s Fastjson library, describing two main problems encountered when migrating a Spring Boot project from Gson to Fastjson.

DateFormat Priority

The project set a global date format yyyy-MM-dd HH:mmss but a field‑level annotation @JSONField(format="yyyy-MM-dd") was expected to override it. The change worked on a Windows development machine but failed on a Linux test server, where the global format still applied.

After trying to simulate Linux via VM options and remote debugging, the root cause was traced to the Fastjson version: the test environment used an old 1.2.53 jar, while the development environment used a newer version (≥1.2.72) where the bug had already been fixed (see issue #1868 and PR #2706).

$ref Circular Reference Issue

A sample endpoint returns two lists, young and children, where both contain references to the same Person object. Fastjson serialises the second reference as {"$ref":"$.result.young[1]"}, triggering a circular‑reference detection.

public ResultBody test() {
    List<Person> list = new ArrayList<>();
    Person obj1 = new Person("张三", 48);
    list.add(obj1);
    Person obj2 = new Person("李四", 23);
    list.add(obj2);
    Person obj3 = new Person("王麻子", 17);
    list.add(obj3);
    List<Person> young = list.stream().filter(e -> e.getAge() <= 45).collect(Collectors.toList());
    List<Person> children = list.stream().filter(e -> e.getAge() < 18).collect(Collectors.toList());
    HashMap map = new HashMap();
    map.put("young", young);
    map.put("children", children);
    return ResultBody.success(map);
}

{
  "code":"200",
  "message":"成功!",
  "result":{
    "young":[
      {"age":23,"name":"李四"},
      {"age":17,"name":"王麻子"}
    ],
    "children":[
      {"$ref":"$.result.young[1]"}
    ]
  }
}

Searching Fastjson’s issue tracker revealed that this behaviour is controlled by the feature SerializerFeature.DisableCircularReferenceDetect. Disabling the feature removes the $ref output, but the author notes that the library treats simple shared references as circular references, which may be undesirable.

Other serializer features such as WriteMapNullValue and WriteNullListAsEmpty also have significant impact on API contracts, and the author recommends that defaults be conservative to avoid unexpected production failures.

Conclusion

The investigation shows that many Fastjson quirks stem from outdated versions and default serializer settings. Upgrading to a version ≥ 1.2.72 resolves the date‑format bug, while careful configuration of serializer features mitigates circular‑reference and null‑handling surprises. The author ultimately decided to blacklist Fastjson 1 for new projects and consider Fastjson 2 or alternative libraries.