ValueConverter 类型转换工具

ValueConverter 提供统一的类型转换接口，使用注册表模式管理转换器，支持内置和自定义转换器。

命名空间

using MiCake.Util.Convert;

基本用法

Convert 方法

// 字符串转整数
int intValue = ValueConverter.Convert<string, int>("123");

// 字符串转日期
DateTime dateValue = ValueConverter.Convert<string, DateTime>("2024-01-01");

// Guid 转换
Guid guid = ValueConverter.Convert<string, Guid>("550e8400-e29b-41d4-a716-446655440000");

// Version 转换
Version? version = ValueConverter.Convert<string, Version>("1.2.3");

Convert 方法行为

null 值处理: 源值为 null 时会抛出 ArgumentNullException
转换失败: 失败时返回目标类型的默认值（如 0、null、Guid.Empty）而不抛出异常
转换顺序:
1. 查询注册表中的自定义转换器（按注册顺序）
2. 使用内置的 SystemValueConverter 作为后备

自定义转换器

创建转换器

public class MoneyConverter : IValueConverter<string, Money>
{
    public bool CanConvert(string value)
    {
        return !string.IsNullOrEmpty(value) && value.Contains(' ');
    }

    public Money? Convert(string value)
    {
        var parts = value.Split(' ');
        if (parts.Length != 2)
            return null;

        if (!decimal.TryParse(parts[0], out var amount))
            return null;

        return new Money(amount, parts[1]);
    }
}

注册转换器

// 使用工厂方法注册
ValueConverter.RegisterConverter(() => new MoneyConverter());

// 使用实例注册
ValueConverter.RegisterConverter(new MoneyConverter());

// 泛型注册
ValueConverter.RegisterConverter<string, Money>(() => new MoneyConverter());

使用自定义转换器

// 注册后直接使用
var money = ValueConverter.Convert<string, Money>("99.99 USD");
Console.WriteLine($"{money.Amount} {money.Currency}"); // 99.99 USD

注册表管理

HasConverter - 检查转换器

if (ValueConverter.HasConverter<string, Money>())
{
    Console.WriteLine("转换器已注册");
}

ClearConverters - 清除指定转换器

// 清除 string 到 Money 的所有转换器
ValueConverter.ClearConverters<string, Money>();

ClearAll - 清空所有转换器

// 清空所有自定义转换器（内置转换器也会被清除）
ValueConverter.ClearAll();

SetRegistry - 设置自定义注册表

// 创建自定义注册表
var customRegistry = new DefaultConverterRegistry();
customRegistry.Register<string, MyType>(() => new MyTypeConverter());

// 应用自定义注册表
ValueConverter.SetRegistry(customRegistry);

ResetRegistry - 重置为默认注册表

// 重置为默认注册表并重新注册内置转换器
ValueConverter.ResetRegistry();

内置转换器

MiCake 预注册了以下内置转换器：

GuidValueConverter

// 字符串转 Guid
Guid guid1 = ValueConverter.Convert<string, Guid>("550e8400-e29b-41d4-a716-446655440000");

// Guid 转 Guid（直接返回）
Guid guid2 = ValueConverter.Convert<Guid, Guid>(guid1);

// 失败时返回 Guid.Empty
Guid empty = ValueConverter.Convert<string, Guid>("invalid"); // Guid.Empty

VersionValueConverter

// 字符串转 Version
Version? version1 = ValueConverter.Convert<string, Version>("1.2.3");
Console.WriteLine(version1); // 1.2.3

// Version 转 Version（直接返回）
Version? version2 = ValueConverter.Convert<Version, Version>(version1);

// 失败时返回 null
Version? nullVersion = ValueConverter.Convert<string, Version>("invalid"); // null

SystemValueConverter

作为后备转换器，使用 System.Convert.ChangeType：

// 支持大多数基本类型转换
int intVal = ValueConverter.Convert<string, int>("42");
double doubleVal = ValueConverter.Convert<string, double>("3.14");
bool boolVal = ValueConverter.Convert<string, bool>("true");
DateTime dateVal = ValueConverter.Convert<string, DateTime>("2024-01-01");

注册表与线程安全

DefaultConverterRegistry 使用锁保护读写操作，确保线程安全：

// 多线程环境下安全注册
Parallel.For(0, 100, i =>
{
    ValueConverter.RegisterConverter<string, int>(() => new MyIntConverter());
});

使用示例

复杂类型转换

public class ProductDto
{
    public string Id { get; set; }
    public string Price { get; set; }
    public string Category { get; set; }
}

// 注册转换器
ValueConverter.RegisterConverter<string, int>(() => new StringToIntConverter());
ValueConverter.RegisterConverter<string, decimal>(() => new StringToDecimalConverter());

// 使用
var dto = new ProductDto
{
    Id = "123",
    Price = "99.99",
    Category = "1"
};

int id = ValueConverter.Convert<string, int>(dto.Id);
decimal price = ValueConverter.Convert<string, decimal>(dto.Price);
int categoryId = ValueConverter.Convert<string, int>(dto.Category);

在服务中使用

public class DataImportService : IScopedService
{
    public Product ParseProduct(Dictionary<string, string> data)
    {
        return new Product
        {
            Id = ValueConverter.Convert<string, int>(data["Id"]),
            Name = data["Name"],
            Price = ValueConverter.Convert<string, decimal>(data["Price"]),
            CreatedAt = ValueConverter.Convert<string, DateTime>(data["CreatedAt"])
        };
    }
}

链式转换

// 注册多个转换器实现链式转换
ValueConverter.RegisterConverter<string, Guid>(() => new StringToGuidConverter());
ValueConverter.RegisterConverter<Guid, int>(() => new GuidToIntConverter());

// 分步转换
string guidString = "550e8400-e29b-41d4-a716-446655440000";
Guid guid = ValueConverter.Convert<string, Guid>(guidString);
int hashCode = ValueConverter.Convert<Guid, int>(guid);

最佳实践

1. 注册特定转换器

// ✅ 正确：注册专用转换器覆盖默认行为
ValueConverter.RegisterConverter<string, Money>(() => new MoneyConverter());

// ❌ 不推荐：依赖 SystemValueConverter 处理复杂类型
var money = ValueConverter.Convert<string, Money>("99.99 USD"); // 可能失败

2. 处理转换失败

// ✅ 正确：检查返回值
int? value = ValueConverter.Convert<string, int?>("invalid");
if (value == null)
{
    Console.WriteLine("转换失败");
}

// ⚠️ 注意：非可空类型返回默认值
int defaultValue = ValueConverter.Convert<string, int>("invalid"); // 返回 0

3. 线程安全注册

// ✅ 正确：在应用启动时注册
public class MyModule : MiCakeModule
{
    public override void ConfigureServices(ModuleConfigServiceContext context)
    {
        ValueConverter.RegisterConverter<string, Money>(() => new MoneyConverter());
        base.ConfigureServices(context);
    }
}

// ❌ 不推荐：在运行时频繁注册/清除
ValueConverter.RegisterConverter<string, int>(() => new MyConverter());
ValueConverter.ClearConverters<string, int>();

4. 转换器顺序

// ✅ 正确：按优先级注册
ValueConverter.RegisterConverter<string, int>(() => new SpecialIntConverter()); // 优先
ValueConverter.RegisterConverter<string, int>(() => new GeneralIntConverter()); // 后备

// Convert 会按注册顺序尝试
int value = ValueConverter.Convert<string, int>("123"); // 使用 SpecialIntConverter

5. 实现幂等转换器

// ✅ 正确：幂等转换器
public class SafeIntConverter : IValueConverter<string, int>
{
    public bool CanConvert(string value)
    {
        return int.TryParse(value, out _);
    }

    public int? Convert(string value)
    {
        return int.TryParse(value, out var result) ? result : null;
    }
}

// ❌ 错误：非幂等转换器
public class CountingConverter : IValueConverter<string, int>
{
    private int _count = 0;

    public int? Convert(string value)
    {
        return _count++; // 每次调用返回不同结果
    }
}

管理方法总结

方法	说明
`Convert<TSource, TDest>(source)`	转换值，失败返回默认值
`RegisterConverter<TSource, TDest>(factory)`	注册转换器工厂
`RegisterConverter(converter)`	注册转换器实例
`HasConverter<TSource, TDest>()`	检查是否存在转换器
`ClearConverters<TSource, TDest>()`	清除指定类型的转换器
`ClearAll()`	清除所有转换器
`SetRegistry(registry)`	设置自定义注册表
`ResetRegistry()`	重置为默认注册表

注意事项

转换失败返回默认值：Convert 方法不会抛出异常
null 值抛出异常：源值为 null 时抛出 ArgumentNullException
转换器顺序：按注册顺序尝试转换器
线程安全：DefaultConverterRegistry 支持线程安全操作
内置后备：SystemValueConverter 作为最后的后备转换器