Bun ORM 中使用 MSSQL 实现插入后获取自增 ID 的最佳实践

在使用 Bun ORM 与 MSSQL 数据库交互时，开发者经常会遇到需要获取插入记录自增 ID 的场景。本文将深入探讨这一常见需求的技术实现方案。

问题背景

在 MSSQL 数据库中，传统获取自增 ID 的方式通常有两种：

1. 使用 SCOPE_IDENTITY() 函数
2. 使用 OUTPUT INSERTED.column_name 语法

当使用 Bun ORM 时，开发者可能会尝试以下方式：

type Person struct {
  bun.BaseModel `bun:"table:Person,alias:p"`
  PersonID int `bun:"PersonID,pk,autoincrement"`
  Name string `bun:"Name"`
}

entity := &Person{Name:"John Doe"}
personid := 0
err := db.NewInsert().Model(entity).Returning("SCOPE_IDENTITY()").Scan(context.Background(), &personid)

然而这种方法在 Bun 中并不适用，因为 Bun 的 Returning 方法设计初衷是处理列名而非函数调用。

正确解决方案

Bun ORM 针对 MSSQL 提供了专门的语法支持。正确的实现方式应该是：

err := db.NewInsert()
    .Model(entity)
    .Returning("INSERTED.PersonID")
    .Scan(context.Background(), &personid)

或者更简洁的版本（自动填充到结构体字段）：

err := db.NewInsert()
    .Model(entity)
    .Returning("PersonID")
    .Scan(context.Background())

技术原理

1. OUTPUT 子句机制： Bun 在处理 MSSQL 的 Returning 方法时，实际上会生成 OUTPUT INSERTED.column_name 语法 这是 MSSQL 特有的数据操作语法，允许在同一个语句中返回受影响行的数据

2. 自动映射特性： 当不指定接收变量时，Bun 会自动将返回的 ID 值映射到模型的主键字段 这种设计符合 ORM 的惯例，减少了样板代码

3. 事务安全性： 相比 SCOPE_IDENTITY()，使用 OUTPUT 子句在多语句事务中更加可靠 它能确保获取的就是当前插入操作生成的 ID

最佳实践建议

1. 对于简单的插入操作，推荐使用自动映射方式
2. 需要获取非主键字段时，可以扩展 Returning 参数
3. 在复杂事务中，优先使用 OUTPUT 语法而非函数调用
4. 注意字段名称的大小写敏感性，确保与数据库定义一致

通过理解这些技术细节，开发者可以更高效地使用 Bun ORM 处理 MSSQL 的自增 ID 场景，避免常见的陷阱和误区。