agilelabs-fx-docs main topics/utility/json-converters.md

JSON 工具方法与 Converter

本页整理框架中和 JSON 序列化、长整型兼容、时间戳转换有关的工具方法。核心实现主要位于 agilelabs/AgileLabs/Json/Converters/，并辅以若干对象与缓存扩展方法。

设计目标

  • 兼容前后端对 bool、long、时间戳的不同表示方式。
  • 避免 JavaScript 对超大整数的精度丢失。
  • 统一对象、流、缓存中的 JSON 读写方式。

核心 Converter

BoolIntJsonConverter

源码：agilelabs/AgileLabs/Json/Converters/BoolIntJsonConverter.cs

  • 写出：true -> 1，false -> 0
  • 读入：兼容数字和字符串
  • 常见用途：历史接口把布尔值约定成 0/1

LongStringJsonConverter

源码：agilelabs/AgileLabs/Json/Converters/LongStringJsonConverter.cs

  • 写出时会检查是否超过 JavaScript 安全整数 9007199254740992
  • 超过安全值时改写成字符串，避免前端精度丢失
  • 读入时兼容数字和字符串

NullableLongStringJsonConverter

源码：agilelabs/AgileLabs/Json/Converters/NullableLongStringJsonConverter.cs

  • 行为与 LongStringJsonConverter 一致
  • 增加对 long? 的 null 处理

DateTimeToTimestampJsonConverter

源码：agilelabs/AgileLabs/Json/Converters/DateTimeToTimestampJsonConverter.cs

  • 写出：统一写成秒级 Unix 时间戳
  • 读入：
    • 兼容 10 位秒级时间戳
    • 兼容 13 位毫秒级时间戳
    • 兼容可解析的时间字符串
  • 读回后会转成本地时间

NullableDateTimeToTimestampJsonConverter

源码：agilelabs/AgileLabs/Json/Converters/NullableDateTimeToTimestampJsonConverter.cs

  • 处理 DateTime?
  • 写出：秒级时间戳或 null
  • 读入：支持秒级时间戳和时间字符串

典型注册方式

这些 converter 都暴露了单例 Instance，适合直接挂到 JsonSerializerSettings：

var settings = new JsonSerializerSettings();
settings.Converters.Add(BoolIntJsonConverter.Instance);
settings.Converters.Add(LongStringJsonConverter.Instance);
settings.Converters.Add(NullableLongStringJsonConverter.Instance);
settings.Converters.Add(DateTimeToTimestampJsonConverter.Instance);
settings.Converters.Add(NullableDateTimeToTimestampJsonConverter.Instance);

配套 JSON 工具方法

除了 converter，框架里还有一组围绕 JSON 读写的便捷扩展：

  • agilelabs/AgileLabs/ObjectExtensions.cs
    • CreateStreamFromObject()：对象直接转 JSON 流
    • SafeSeekToBegin()：流写完后安全回到开头
  • agilelabs/AgileLabs/ResponseExtensions.cs
    • WriteContent(Stream, string)
    • WriteContent(Stream, JObject, JsonSerializerSettings)
    • WriteContent(Stream, object, JsonSerializerSettings)
  • agilelabs.aspnet/src/AgileLabs.WebApp/Caching/DistributedCacheExtensions.cs
    • GetObject<T>() / SetObject<T>()
    • GetOrCreateObjectAsync()：对象按 JSON 方式读写分布式缓存

使用建议

  • 前端参与 ID 传输时，如果可能超出 JS 安全整数，优先给该字段挂 LongStringJsonConverter。
  • 老接口仍使用 0/1 表示布尔值时，统一收敛到 BoolIntJsonConverter，不要在业务代码里反复手写转换。
  • 时间字段的 JSON 语义要和接口文档保持一致；这里的默认实现是秒级时间戳，不是毫秒级。
  • 当前工具链主要基于 Newtonsoft.Json，如果项目切换到 System.Text.Json，需要补一套等价 converter。

注意事项

  • DateTimeToTimestampJsonConverter 与 NullableDateTimeToTimestampJsonConverter 的读入细节不完全一致，前者额外兼容 13 位毫秒时间戳。
  • DistributedCacheExtensions 内部使用 JsonConvert.SerializeObject/DeserializeObject，缓存对象结构升级时要考虑兼容性。
  • JSON 深拷贝也被框架内部用于 WorkContext 辅助逻辑，相关实现位于 agilelabs.aspnet/src/AgileLabs.WebApp/WorkContexts/Extensions/DeepCloneExtensions.cs。

相关页面