Fastjson2 全局日期格式设置优化指南

背景介绍

Fastjson2 是阿里巴巴开源的高性能 JSON 处理库，广泛应用于 Java 生态系统中。在实际开发中，日期格式的处理是一个常见需求，开发者通常需要统一项目中所有日期类型的序列化格式。

问题发现

在 Fastjson2 的早期版本中，即使用户通过 JSON.configWriterDateFormat 方法设置了全局的日期格式，在序列化 Timestamp 类型时，如果不额外在 Context 中设置日期格式，仍然会输出整数时间戳而非格式化后的字符串。这种行为与开发者的预期不符，增加了不必要的配置负担。

解决方案

Fastjson2 团队在最新版本中优化了这一行为，现在全局日期格式设置会正确应用到所有日期类型的序列化中，包括 java.util.Date 和 java.sql.Timestamp。

关键代码示例

@Test
public void testDateFormat() {
    // 保存原始格式以便测试后恢复
    String defaultWriterFormat = JSONFactory.getDefaultWriterFormat();
    
    try {
        // 设置全局日期格式
        String dateFormat = "yyyy-MM-dd'T'HH:mm:ss";
        JSON.configWriterDateFormat(dateFormat);

        // 创建上下文时会自动继承全局设置
        JSONWriter.Context writeContext = JSONFactory.createWriteContext();
        
        // 验证日期格式是否正确应用
        Date date = new Date(1712988987882L);
        String json = JSON.toJSONString(date, writeContext);
        assertEquals("\"2024-04-13T14:16:27\"", json);

        // 验证Timestamp类型也能正确格式化
        java.sql.Timestamp ts = new Timestamp(date.getTime());
        String json1 = JSON.toJSONString(ts, writeContext);
        assertEquals("\"2024-04-13T14:16:27\"", json1);
    } finally {
        // 恢复原始设置
        JSON.configWriterDateFormat(defaultWriterFormat);
    }
}

使用注意事项

1. 上下文创建时机：确保在设置全局日期格式后再创建 JSONWriter.Context 实例，否则新设置可能不会生效。

2. 线程安全：全局日期格式设置会影响所有后续创建的上下文，在多线程环境下需要注意设置操作的线程安全性。

3. 格式恢复：在修改全局设置后，特别是测试场景中，建议使用 try-finally 块确保恢复原始设置。

最佳实践

对于大多数项目，推荐在应用启动时统一配置日期格式：

public class AppConfig {
    @PostConstruct
    public void init() {
        // 设置全局日期格式
        JSON.configWriterDateFormat("yyyy-MM-dd HH:mm:ss");
        
        // 其他初始化配置...
    }
}

这样在整个应用中，所有日期类型的序列化都会使用统一的格式，无需在每个序列化操作中单独配置。

技术原理

Fastjson2 内部维护了一个默认的日期格式设置，当创建新的 JSONWriter.Context 时，会自动继承这个全局设置。这种设计既保证了灵活性（允许特定场景覆盖全局设置），又减少了重复配置的工作量。

总结

Fastjson2 对全局日期格式处理的优化，显著提升了开发体验。开发者现在可以通过一次配置实现全应用统一的日期序列化格式，减少了样板代码，提高了代码的可维护性。这一改进体现了 Fastjson2 团队对开发者友好性的持续关注，使得这个高性能 JSON 库在实际项目中更加易用。