DaLi.Utils.Core.CSharp 3.24.12.2101

以下是项目的说明文档：

DaLi.Utils.Core.CSharp JSON 转换器文档

概述

本项目提供了一系列用于 System.Text.Json 的自定义 JSON 转换器，主要用于处理特殊的数据类型转换场景。

主要组件

1. JsonDateTimeConverter

处理 DateTime 类型的 JSON 序列化和反序列化。

using DaLi.Utils.Misc;

var options = new JsonSerializerOptions
{
    Converters = { new JsonDateTimeConverter() }
};

特性：

• 支持标准 ISO 8601 格式的日期时间字符串
• 处理空值和无效日期字符串
• 输出格式为 "yyyy-MM-ddTHH:mm:ss.fffffffK"

2. JsonConverterDefault

通用对象类型的 JSON 转换器，支持多种数据类型的智能转换。

using DaLi.Utils.Misc;

var options = new JsonSerializerOptions
{
    Converters = { new JsonConverterDefault(element => /* 自定义解析逻辑 */) }
};

支持的数据类型：

• 数值类型：Int64、Int32、Double、Int16、Byte、Single、Decimal
• 字符串类型
• DateTime
• DateTimeOffset
• Guid
• 布尔值
• 自定义对象（通过委托处理）

特殊处理：

• NaN 转换为 "NaN" 字符串
• Infinity 转换为 "Infinity" 或 "-Infinity" 字符串
• 空字符串转换为 string.Empty
• Null 值处理

使用示例

var options = new JsonSerializerOptions
{
    Converters = 
    {
        new JsonDateTimeConverter(),
        new JsonConverterDefault(element => 
        {
            // 自定义复杂对象的解析逻辑
            return element.ValueKind switch
            {
                JsonValueKind.Object => /* 处理对象 */,
                JsonValueKind.Array => /* 处理数组 */,
                _ => element.GetRawText()
            };
        })
    }
};

// 序列化
string json = JsonSerializer.Serialize(obj, options);

// 反序列化
var result = JsonSerializer.Deserialize<T>(json, options);

注意事项

1. 日期时间处理

   • 输入的日期字符串必须符合可解析的格式
   • 无效日期将返回默认值
   • Null 值将返回默认日期时间

2. 数值类型转换

   • 按照从大到小的顺序尝试转换数值类型
   • 超出范围的数值将尝试转换为下一个更大的类型
   • 最终都无法转换时使用 Decimal

3. 字符串处理

   • 空字符串返回 string.Empty
   • 自动尝试转换为 DateTime、DateTimeOffset 和 Guid

性能考虑

• JsonConverterDefault 中的数值类型判断按照使用频率排序，优化常见场景的性能
• 使用 Clone() 方法确保 JsonElement 的独立性
• 避免不必要的字符串分配

扩展性

可以通过继承 JsonConverter<T> 类创建新的转换器来支持其他类型：

public class CustomTypeConverter : JsonConverter<CustomType>
{
    public override CustomType Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 实现自定义类型的读取逻辑
    }

    public override void Write(Utf8JsonWriter writer, CustomType value, JsonSerializerOptions options)
    {
        // 实现自定义类型的写入逻辑
    }
}