Dapper中[Key]和[Table]特性有什么用 Dapper.Contrib特性详解

[table] 和 [Key] 是 Dapper.Contrib 中用于实体映射的核心特性：[Table] 标注类以指定对应数据库表名，避免默认复数推导错误；[Key] 标注自增主键属性，插入时忽略该字段并回填生成值；非自增主键须用[ExplicitKey]。

[Table] 和 [Key] 是 Dapper.Contrib 中用于实体类映射的核心特性，它们不参与 Dapper 本体（纯 sql 扩展）的运行，只在 Dapper.Contrib 提供的高级 CRUD 方法（如 Insert、Get、Update）中起作用。

Table 特性：告诉 Dapper.Contrib “这张表叫什么”

它标注在类上，明确指定该实体对应数据库中的哪张物理表。如果不加，Dapper.Contrib 会按约定自动推导：把类名变成复数形式（比如 User → Users），容易出错或不匹配。

• 必须是类级别，不能标在属性或方法上
• 值就是真实表名，支持带 schema，例如 [Table("dbo.Customers")]
• 如果数据库表名含特殊字符或大小写敏感，加 [Table] 是最稳妥的做法

Key 特性：声明“这个字段是自增主键”

它标注在某个属性上，表示该字段是数据库中自动增长（IDENTITY）类型的主键，比如 int 或 long 类型的 ID 列。

CreateWise AI

为播客创作者设计的AI创作工具，AI自动去口癖、提交亮点和生成Show notes、标题等

177

查看详情

• 插入时，Dapper.Contrib 会自动忽略该字段的值，不把它放进 INSERT 语句的列和参数列表里
• 插入成功后，会把数据库生成的新主键值回填到对象的该属性中（仅限数字类型）
• 不能和 [ExplicitKey] 同时用在一个属性上

对比 ExplicitKey：非自增主键的正确写法

如果你的主键是 Guid、字符串或由程序生成的值（比如雪花 ID），就得用 [ExplicitKey]，而不是 [Key]。

• [ExplicitKey] 表示“这个主键值我来提供”，插入时会包含该字段
• 比如 Guid ID { get; set; } = Guid.NewGuid();，加上 [ExplicitKey] 才能正确入库
• 误用 [Key] 会导致插入失败或主键为 0/空

常见搭配建议

• SQL Server 自增 int 主键 → [Key]
• postgresql 序列主键（SERIAL）→ 也适用 [Key]
• mysql 的 AUTO_INCREMENT int 主键 → [Key]
• 所有 GUID / 字符串 / 程序生成主键 → 必须用 [ExplicitKey]
• 表名与类名不一致（尤其大小写、下划线、前缀等）→ 一律加 [Table("xxx")]

基本上就这些。用对这两个特性，Dapper.Contrib 的增删改查才能按预期工作，否则很容易出现“插不进”“查不到”“主键丢失”之类的问题。