Bun：高性能 Go ORM 与 SQL 构建工具

一、核心特性
二、安装与快速上手
三、使用场景
四、最佳实践
五、与其他 ORM 对比

在 Go 生态中，传统的 ORM 往往要么“魔法”过多（如 GORM），要么过于模板化（如 SQLBoiler）。bun 则以 SQL-first 的设计理念，为开发者提供了轻量、高性能且灵活可控的 ORM 和查询构建器。它同时支持 PostgreSQL、MySQL（包括MariaDB）、SQLite、MSSQL、Oracle，并与分布式追踪平台 Uptrace 深度集成，让你在享受 ORM 便捷性的同时，依然对底层 SQL 保有完全掌控权。

一、核心特性

轻量级 ORM

结构体与表映射，通过标签定义主键、自增等属性。

type User struct {
    bun.BaseModel `bun:"table:users"`
    ID   int64    `bun:",pk,autoincrement"`
    Name string
    Email string
}

db.NewSelect().Model(&users) 一行代码即可完成查询。

SQL 构建器

链式 API 构建复杂查询（JOIN、子查询、窗口函数等），自动参数化，杜绝注入风险：

err := db.NewSelect().
    ColumnExpr("u.id, u.name").
    TableExpr("users AS u").
    Where("u.age > ?", 18).
    Join("LEFT JOIN profiles p ON p.user_id = u.id").
    Scan(ctx, &results)

关系映射

支持 has one、has many、belongs to、many to many：

type Author struct {
    ID    int64
    Name  string
    Books []Book `bun:"rel:has-many"`
}
type Book struct {
    ID       int64
    Title    string
    AuthorID int64
}
// 加载作者和其所有书籍
var author Author
db.NewSelect().
    Model(&author).
    Relation("Books").
    Where("author.id = ?", 1).
    Scan(ctx)

生命周期钩子（Hooks）
- 在模型创建、查询、更新、删除前后注入自定义逻辑，如审计、缓存失效等：
```
func (u *User) BeforeCreate(ctx context.Context) error {
    u.CreatedAt = time.Now()
    return nil
}
```
迁移工具（Migrations）
- 类似 Rails 的迁移机制，用 Go 代码管理数据库变更，支持事务和回滚：
```
migrator := migrate.NewMigrator(db, migrations.Migrations)
migrator.Init(ctx)
migrator.Migrate(ctx)
```
与 Uptrace 分布式追踪集成
- 自动上报每次 SQL 调用的耗时、参数和错误，帮助定位慢查询、性能瓶颈。

二、安装与快速上手

go get github.com/uptrace/bun
go get github.com/uptrace/bun/driver/pgdriver   # PostgreSQL 驱动

import (
    "context"
    "database/sql"
    "github.com/uptrace/bun"
    "github.com/uptrace/bun/driver/pgdriver"
    "github.com/uptrace/bun/dialect/pgdialect"
)

func NewDB() *bun.DB {
    dsn := "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
    sqldb := sql.OpenDB(pgdriver.NewConnector(pgdriver.WithDSN(dsn)))
    return bun.NewDB(sqldb, pgdialect.New())
}

func main() {
    ctx := context.Background()
    db := NewDB()

    // 创建记录
    user := &User{Name: "Alice", Email: "alice@example.com"}
    _, _ = db.NewInsert().Model(user).Exec(ctx)

    // 查询记录
    var users []User
    _ = db.NewSelect().
        Model(&users).
        Where("age > ?", 21).
        Order("name ASC").
        Scan(ctx)
}

三、使用场景

微服务架构
轻量级、启动迅速，适合高并发的点对点服务，配合 Uptrace 实现全链路可观测。
报表与数据分析系统
动态生成复杂 SQL，Bun 的链式构建器比原生拼接更安全、可维护。
性能敏感型应用
代码生成模型、预编译查询，最大程度减小反射开销，与原生 SQL 性能相当。
数据迁移与 ETL 工具
Go 语言编写迁移脚本、后台任务十分自然，Bun 的迁移支持事务回滚。

四、最佳实践

日志与错误处理
- 在业务层（Controller）统一捕获并记录错误，附带请求 ID、用户信息。
- 使用 Bun 提供的结构化日志接口或自己集成 Zap/Logrus。
安全与参数化
- 始终使用链式 API 或 bun.SafeQuery，避免手写拼接字符串。
- 日志中剔除敏感字段（如密码、Token）。
数据库连接池调优
- 根据业务特性设置 SetMaxOpenConns, SetMaxIdleConns, SetConnMaxLifetime，避免连接泄漏。
索引与查询优化
- 结合 Uptrace 的慢查询分析，补充合适索引，避免全表扫描。
- 对大批量写入，可考虑分批提交或使用 COPY。

五、与其他 ORM 对比

特性	Bun (SQL-first)	GORM (Active Record)
SQL 可控性	极高	较弱
性能	接近原生 SQL	反射+DSL 带来开销
关系映射	完善	完善
链式构建器	安全、灵活	基础
文档与社区	发展迅速	成熟、大量资源
分布式追踪集成	原生支持 Uptrace	需第三方适配

声明：本作品采用署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)进行许可，使用时请注明出处。
Author: mengbin
blog: mengbin
Github: mengbin92
cnblogs: 恋水无意
腾讯云开发者社区：孟斯特
—