Go bbolt 怎么用嵌套 Bucket 隔离业务数据

Go bbolt 的嵌套 Bucket 适合把“业务域 → 租户 → 业务键值”组织成稳定路径。做法是：在一个 Update 事务里用 CreateBucketIfNotExists 幂等创建每一级 Bucket，写入时从根 Bucket 逐层进入，读取时沿着同一条路径查找。这样同名的 settings 或 profile 可以分别属于不同租户，不会挤在一个扁平命名空间里。

嵌套 Bucket 解决的是存储命名空间隔离，不是权限系统。Bucket 对象和 Get 返回的字节切片都只在当前事务有效；应用层仍需自己校验租户身份、键名和数据格式。

官方地址：https://github.com/etcd-io/bbolt/

先把业务层级映射成 Bucket 路径

假设一个应用同时保存订单和用户设置，可以把顶层 Bucket 取名为 orders、settings，再在其中按租户创建子 Bucket。本文只讨论一条明确路径：settings//。其中顶层 Bucket 表示业务域，第二层表示隔离边界，最后的键和值才是实际数据。

这个映射有两个好处。第一，不同业务域可以出现相同的键名；第二，删除一个租户时可以定位到对应子 Bucket，而不是扫描所有键再依赖字符串前缀猜范围。Bucket 名称应保持稳定、短小并由应用层统一编码，不能把未经校验的用户输入直接当成结构定义。

在 Update 中幂等初始化嵌套 Bucket

CreateBucket 在名称已存在时会返回错误，适合你明确要求“必须是第一次创建”的场景。服务启动或每次写入前需要保证结构存在时，通常用 CreateBucketIfNotExists。它既能创建不存在的 Bucket，也能返回已经存在的 Bucket，后续代码可以继续向下创建。

package main

import (
    "fmt"

    bbolt "go.etcd.io/bbolt"
)

// ensureTenantBucket 在同一个写事务内保证业务域和租户两级结构存在。
func ensureTenantBucket(tx *bbolt.Tx, tenantID string) (*bbolt.Bucket, error) {
    // 顶层 Bucket 表示业务域，避免把所有业务键混在 root 中。
    settings, err := tx.CreateBucketIfNotExists([]byte("settings"))
    if err != nil {
        return nil, fmt.Errorf("创建 settings Bucket: %w", err)
    }

    // 租户标识来自调用方，实际项目应先做非空和字符集校验。
    if tenantID == "" {
        return nil, fmt.Errorf("tenantID 不能为空")
    }
    tenant, err := settings.CreateBucketIfNotExists([]byte(tenantID))
    if err != nil {
        return nil, fmt.Errorf("创建租户 Bucket: %w", err)
    }
    return tenant, nil
}

这里的返回值属于当前 Update 事务。不要把 *bbolt.Bucket 存到全局变量中，在下一个事务里继续使用；下一次事务应重新通过 tx.Bucket 或父 Bucket 的 Bucket 方法定位。

按相同路径写入和读取数据

初始化结构后，写入和读取只需要遵守同一条路径。写入使用 Update，读取使用 View；读事务不应调用 Put 或创建 Bucket。下面的函数把租户设置写到 settings/ 下的普通键值中。

// saveSetting 只修改指定租户的设置，不触碰其他租户的同名键。
func saveSetting(db *bbolt.DB, tenantID, key, value string) error {
    return db.Update(func(tx *bbolt.Tx) error {
        tenant, err := ensureTenantBucket(tx, tenantID)
        if err != nil {
            return err
        }
        // Put 会覆盖同一租户下同名键；是否允许覆盖由业务规则决定。
        if err := tenant.Put([]byte(key), []byte(value)); err != nil {
            return fmt.Errorf("保存设置 %q: %w", key, err)
        }
        return nil
    })
}

// loadSetting 在读事务内复制结果，避免返回失效的 mmap 字节切片。
func loadSetting(db *bbolt.DB, tenantID, key string) ([]byte, error) {
    var result []byte
    err := db.View(func(tx *bbolt.Tx) error {
        settings := tx.Bucket([]byte("settings"))
        if settings == nil {
            return fmt.Errorf("settings Bucket 不存在")
        }
        tenant := settings.Bucket([]byte(tenantID))
        if tenant == nil {
            return fmt.Errorf("租户 Bucket 不存在")
        }
        value := tenant.Get([]byte(key))
        if value == nil {
            return fmt.Errorf("设置 %q 不存在", key)
        }
        // Get 的返回值只保证在事务打开期间有效，这里复制给调用方。
        result = append([]byte(nil), value...)
        return nil
    })
    return result, err
}

如果两个租户都写入 theme，它们的完整路径不同：settings/acme/theme 与 settings/zephyr/theme。隔离来自 Bucket 层级，而不是把租户 ID 拼到业务键前面后再由应用层手动过滤。

处理删除、空路径和事务生命周期

删除租户结构时，应该在写事务中从父 Bucket 调用 DeleteBucket。它删除的是该父 Bucket 下指定名称的子 Bucket 及其嵌套内容，不是普通键的删除替代品。调用前应根据业务规则确认租户已经停用，避免把“清空配置”误写成“删除整个隔离域”。

// deleteTenant 删除一个租户的整棵设置子树，必须由写事务执行。
func deleteTenant(db *bbolt.DB, tenantID string) error {
    return db.Update(func(tx *bbolt.Tx) error {
        settings := tx.Bucket([]byte("settings"))
        if settings == nil {
            return fmt.Errorf("settings Bucket 不存在")
        }
        // DeleteBucket 只针对子 Bucket；普通键应使用 Delete。
        if err := settings.DeleteBucket([]byte(tenantID)); err != nil {
            return fmt.Errorf("删除租户 Bucket: %w", err)
        }
        return nil
    })
}

还有三个容易混淆的边界：

• 空的 Bucket 名称会导致创建失败，租户 ID 不能直接跳过校验。
• 在 View 中创建或修改 Bucket 会返回事务不可写错误，读写职责要分开。
• Bucket、Cursor 以及 Get 返回的字节切片不能跨事务长期持有，需要重新定位或复制。

按场景选择隔离层级

嵌套层级不是越深越好。只有当某一级需要独立列举、整体删除或表达清楚的生命周期时，才值得创建 Bucket。两级通常足够表达“业务域 + 租户”；如果只是一个很小的字段集合，直接使用带前缀的普通键可能更简单，但要把前缀规范、删除范围和冲突规则写清楚。

可以用下面的接口决策表收敛选择：

相关问题

嵌套 Bucket 能代替租户权限校验吗？ 不能。它只提供数据组织和命名空间隔离，租户身份、授权和审计仍由应用层负责。

为什么不能把 Bucket 保存起来复用？ bbolt 的 Bucket 实例绑定当前事务，事务结束后不应继续使用。下一次访问要重新打开事务并按路径定位。

什么时候用普通键前缀更合适？ 当数据不需要按组列举或整体删除、层级也不会承担生命周期职责时，普通键前缀可能更轻量；但必须统一编码和删除策略。

因此，Go bbolt 的嵌套 Bucket 关键不在于把目录做深，而在于把业务域、隔离边界和事务职责映射成稳定路径：写事务幂等初始化，读事务按路径定位，返回值及时复制，删除动作明确范围。