SqlSugar插入数据时主键冲突如何解决？

Question

在使用SqlSugar进行数据插入时，若表主键为数据库自增字段，但实体类未正确配置自增属性，调用`Insertable().ExecuteCommand()`会引发主键冲突。常见问题是开发者手动赋值主键或未在实体类中通过`[SugarColumn(IsIdentity = true, IsPrimaryKey = true)]`标记自增主键，导致数据库生成的自增值被忽略。如何正确配置实体以避免主键冲突？

Answer 1

1. 问题背景与现象分析

在使用 SqlSugar 进行数据库操作时，若目标表的主键字段为数据库自增（IDENTITY），但对应的实体类未正确配置自增属性，则调用 Insertable().ExecuteCommand() 方法将可能导致主键冲突异常。典型表现为：系统尝试插入一个显式指定的主键值（如0或重复值），而该值违反了数据库的唯一性约束。

常见错误场景包括：

• 开发者手动为实体主键赋值，例如设置 Id = 0 或其他固定值；
• 未在实体类中使用 [SugarColumn(IsIdentity = true, IsPrimaryKey = true)] 标记自增主键；
• 忽略 ORM 映射配置，导致 SqlSugar 无法识别数据库层面的自增行为。

这种问题在迁移旧项目、快速原型开发或团队协作中尤为常见，尤其当数据库设计与代码模型不同步时。

2. 原理剖析：SqlSugar 如何处理主键生成策略

SqlSugar 在执行插入操作时，会根据实体类上的特性（Attribute）判断主键是否由数据库自动生成。其核心逻辑如下：

1. 检查字段是否标记为 IsPrimaryKey；
2. 若同时标记 IsIdentity = true，则认为该字段由数据库生成，插入时自动排除该字段；
3. 否则，即使数据库是自增字段，SqlSugar 仍会尝试写入此列，从而引发冲突。

这意味着，仅依赖数据库结构定义是不够的——必须在实体层明确声明自增语义。

3. 正确配置实体类以支持自增主键

为避免主键冲突，需确保实体类中的主键字段具备正确的映射属性。以下是一个标准示例：

[SugarTable("User")]
public class User
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public int Id { get; set; }

    public string Name { get; set; }

    public DateTime CreateTime { get; set; }
}
    

关键点说明：

属性	作用
IsPrimaryKey = true	标识为主键字段
IsIdentity = true	告知 SqlSugar 该字段由数据库自动生成
无 setter 赋值或赋为 0	运行时不应手动设置此值

4. 常见误区与调试建议

尽管配置看似简单，但在实际开发中仍存在多个易错点：

• 误以为数据库自增即自动生效：ORM 框架不会自动探测数据库元数据来决定行为，必须通过特性显式声明；
• 使用默认构造函数初始化主键：某些序列化机制可能将 Id 初始化为 0，并被一同插入；
• 混合使用多种 ORM 配置方式：如 Fluent API 与 Attribute 冲突，造成预期外行为。

调试建议：

1. 启用 SqlSugar 的 SQL 日志输出，观察生成的 INSERT 语句是否包含主键列；
2. 检查实体实例化过程，避免在创建对象时显式赋值主键；
3. 使用 AsInsertable(entity).ExcludeExpression(x => x.Id) 临时规避问题（非长久之计）。

5. 架构级解决方案与最佳实践

为从根本上减少此类问题，可从架构层面引入统一规范：

// 定义基类，适用于所有具有自增主键的实体
public abstract class EntityBase<T> where T : struct
{
    [SugarColumn(IsPrimaryKey = true, IsIdentity = true)]
    public virtual T Id { get; set; }
}
    

结合泛型基类与约定优于配置原则，能有效降低出错概率。此外，可通过以下流程图展示插入流程中的关键决策点：

graph TD
            A[准备实体对象] --> B{主键是否标记IsIdentity?}
            B -- 是 --> C[生成不含主键的INSERT语句]
            B -- 否 --> D[尝试插入主键值]
            D --> E{值是否存在且非默认?}
            E -- 是 --> F[可能引发主键冲突]
            E -- 否 --> G[插入成功但风险高]
            C --> H[数据库生成新ID并返回]
            H --> I[插入成功]

6. 扩展思考：分布式场景下的主键策略演进

虽然本文聚焦于单机数据库自增主键，但随着系统规模扩大，应考虑更高级的主键生成方案：

• GUID 主键：牺牲排序性换取分布一致性；
• 雪花算法（Snowflake）：全局唯一、有序递增，适合高并发环境；
• 数据库序列（Sequence）：跨表共享的自增机制，支持多租户架构。

在这些模式下，IsIdentity 应设为 false，并配合 IsGenerated 或业务层生成逻辑协同工作。