SqlSugar 中自定义 Ulid 类型处理的实践指南

问题背景

在使用 ORM 框架 SqlSugar 时，开发者经常会遇到需要处理自定义数据类型的情况。本文以 Ulid 类型为例，探讨如何在 SqlSugar 中正确处理这种特殊数据类型。

Ulid 类型简介

Ulid (Universally Unique Lexicographically Sortable Identifier) 是一种比传统 GUID 更具优势的唯一标识符类型。它具有以下特点：

• 按时间排序
• 128位兼容性
• 比 UUID 更友好的格式
• 跨平台兼容性

常见问题分析

在 SqlSugar 中使用 Ulid 类型时，开发者可能会遇到 Object of type 'System.String' cannot be converted to type 'System.Ulid' 这样的错误。这主要是因为：

1. 数据库本身不直接支持 Ulid 类型
2. ORM 框架需要进行类型转换
3. 查询和参数处理需要特殊处理

解决方案

1. 使用类型转换器

SqlSugar 提供了 ISugarDataConverter 接口来处理自定义类型的转换。对于 Ulid 类型，我们可以实现如下转换器：

public class UlidToStringConverter : ISugarDataConverter
{
    public SugarParameter ParameterConverter<T>(object columnValue, int columnIndex)
    {
        var name = "@Ulid" + columnIndex;
        if (columnValue == null) return new SugarParameter(name, null);
        return new SugarParameter(name, columnValue.ToString());
    }

    public T QueryConverter<T>(IDataRecord dataRecord, int dataRecordIndex)
    {
        var str = dataRecord.GetValue(dataRecordIndex).ToString();
        var ulid = Ulid.Parse(str);
        if (ulid is T result) return result;
        throw new NotImplementedException();
    }
}

2. 实体类配置

在实体类中，需要通过 SugarColumn 特性指定转换器：

[SugarColumn(IsPrimaryKey = true, SqlParameterDbType = typeof(UlidToStringConverter))]
public Ulid PageId { get; set; } = Ulid.NewUlid();

3. 版本兼容性

从 SqlSugarCore 5.1.4.167-preview06 版本开始，框架已原生支持 Ulid 扩展类型，开发者可以直接使用而无需自定义转换器。

最佳实践

1. 版本检查：确保使用支持 Ulid 的最新版本 SqlSugar
2. 类型安全：在转换器中添加 null 检查
3. 错误处理：为转换失败的情况提供有意义的异常信息
4. 性能考虑：对于高频操作，考虑缓存转换结果

总结

处理自定义数据类型是 ORM 使用中的常见需求。通过 SqlSugar 的类型转换器机制，开发者可以灵活地支持各种特殊数据类型。对于 Ulid 这种常用类型，新版本已提供原生支持，简化了开发流程。理解这一机制有助于开发者更好地处理其他自定义类型的映射需求。