FreeSql仓储层更新操作中NULL值处理的陷阱与解决方案

2025-06-15 20:22:03作者：蔡丛锟

在使用FreeSql进行数据库操作时，开发人员可能会遇到一个隐蔽但危险的问题：当使用仓储层进行"先缓存后更新"操作时，如果实体字段值为NULL，可能导致数据库原有值被意外清空。本文将深入分析这一问题的成因，并提供有效的解决方案。

问题现象

许多开发者在进行统计数值更新时，会采用以下典型流程：

从数据库查询出原始数据
将待更新数据附加(Attach)到仓储模块缓存
修改需要更新的统计字段
执行更新操作

然而，当待更新实体中存在NULL值的字符串字段时，最终执行结果可能导致数据库中对应记录的非NULL字段被意外清空，造成数据丢失。

问题根源分析

1. 实体定义与数据库约束

问题的核心在于实体属性定义与数据库约束的不匹配。例如以下实体定义：

[JsonProperty, Column(StringLength = 100, IsNullable = false)]
public string Code { get; set; }

这里IsNullable = false表示数据库字段不允许NULL值，但C#属性并未使用可空类型(string?)，这种不一致性埋下了隐患。

2. FreeSql的NULL值处理机制

FreeSql在内部处理更新操作时，会对NULL值进行特殊处理：

当检测到IsNullable = false的字段值为NULL时，会自动将其转换为空字符串("")
这种转换原本是为了避免NULL值插入到不允许NULL的数据库字段中

3. 仓储层变更追踪的冲突

当使用仓储层的Attach方法时，问题变得更加复杂：

Attach方法会记录实体当前状态作为"原始值"
如果实体字段初始为NULL，Attach会记录NULL
后续更新时，NULL被转换为""，导致仓储层认为字段值发生了变化
最终生成的SQL会包含本不应更新的字段

复现案例

以下代码可以复现该问题：

var t1 = new ProjectItem { ID = 53, MaxQuantity = 0 }; // 其他字段默认为null
var repo = fsql.GetRepository<ProjectItem>();
repo.Attach(t1);
t1.MaxQuantity = 111;
repo.Update(t1);

预期生成的SQL应该只更新MaxQuantity字段，但实际上会生成类似以下的SQL：

UPDATE "ProjectItem" SET "Code" = '', "MaxQuantity" = 111, "Name" = '' WHERE ("ID" = 53)

解决方案

1. 使用可空类型声明

确保实体属性与数据库约束一致：

[JsonProperty, Column(StringLength = 100, IsNullable = false)]
public string? Code { get; set; } // 使用可空类型

2. 避免NULL值传递

在构造更新实体时，为所有非可空字段提供默认值：

var updateItem = new ProjectItem {
    ID = 53,
    Code = "", // 显式设置默认值
    Name = "", // 显式设置默认值
    MaxQuantity = 111
};

3. 使用直接更新方式

对于简单更新操作，可以不使用仓储层，直接使用Update方法：

fsql.Update<ProjectItem>()
    .Set(x => x.MaxQuantity, 111)
    .Where(x => x.ID == 53)
    .ExecuteAffrows();

4. 谨慎使用AuditValue事件

如果确实需要使用AuditValue事件，确保不会干扰NULL值的正常处理：

fsql.Aop.AuditValue += (s, e) => {
    // 避免对NULL值的不必要处理
    if (e.Value == null && e.Property.GetCustomAttribute<ColumnAttribute>()?.IsNullable == false) {
        // 可以在这里做特殊处理或记录日志
    }
};