Dapper如何与Dapper.SimpleCRUD结合使用 Dapper扩展库教程

Dapper.SimpleCRUD 是 Dapper 的轻量级增强包，需调用 InitializeSimpleCRUD() 初始化连接并遵循实体命名约定（如主键为 Id、表名复数化等），支持与原生 Dapper 混用。

Dapper.SimpleCRUD 是 Dapper 的轻量级扩展，不是替代品，而是“增强包”——它在 Dapper 原生能力基础上，封装了常用 CRUD 操作，省去手写 SQL 和映射逻辑。两者天然兼容，无需冲突配置，关键在于正确初始化和调用顺序。

安装与基础依赖关系

Dapper.SimpleCRUD 会自动拉取 Dapper 作为依赖，所以只需安装它一个包即可：

• 通过 NuGet 安装：Install-Package Dapper.SimpleCRUD
• 项目中引用命名空间：using Dapper; 和 using Dapper.SimpleCRUD;
• 不需单独安装 Dapper，但若已手动装过，版本建议保持一致（推荐 ≥2.1.0）

连接初始化必须调用 InitializeSimpleCRUD()

这是最容易忽略却最关键的一步：Dapper.SimpleCRUD 不会自动注册映射规则，必须显式初始化连接对象。

• 每次新建 SqlConnection（或其他 IDbConnection）后，在执行任何 SimpleCRUD 方法前，先调用 connection.InitializeSimpleCRUD()
• 示例： using (var conn = new SqlConnection(cs))
  {
    conn.Open();
    conn.InitializeSimpleCRUD(); // ⚠️ 缺少这句会报错或行为异常
    var user = conn.Get(1);
  }
• 该方法仅做一次映射注册（如主键识别、表名推导），不影响性能，也不需重复调用

实体类设计要点（自动映射靠它）

SimpleCRUD 默认按约定匹配数据库结构，不需要写 SQL，但实体类要满足基本规范：

• 主键字段名默认为 Id（大小写敏感），类型支持 int、long、Guid；如用其他名（如 UserId），需加 [Key] 属性（来自 System.ComponentModel.DataAnnotations）
• 表名默认取类名（如 User → Users），若不符，用 [Table("user_info")]
• 列名默认与属性名一致；若数据库列是 user_name，而属性叫 UserName，可用 [Column("user_name")]
• 不支持复杂导航属性（如 public List Orders { get; set; }），一对多需手动查或结合原生 Dapper 处理

混合使用场景：SimpleCRUD + 原生 Dapper

SimpleCRUD 覆盖不了所有需求时，可随时切回 Dapper 原生 API，共享同一连接实例：

• 增删改查用 SimpleCRUD，复杂查询用 Dapper：conn.Query("SELECT * FROM Users WHERE Age > @age", new { age = 18 })
• 事务中混用安全可靠：using var tx = conn.BeginTransaction();
  conn.Insert(new User { Name = "A" });
  conn.Execute("UPDATE Logs SET Status = 'done' WHERE UserId = @id", new { id = 1 }, tx);
  tx.Commit();
• 注意：SimpleCRUD 的 Insert 等方法默认不参与外部事务，除非你把 SqlTransaction 显式传入（部分重载支持）

基本上就这些。它不复杂，但初始化和命名约定这两处容易忽略，踩坑多集中在“为什么 Get 找不到数据”或“Insert 返回 0”。对齐好实体和表、记得调 InitializeSimpleCRUD()，就能稳稳跑起来。