Go bbolt 怎么用 Cursor 按前缀扫描键

我在 bbolt 里做按租户读取时，最容易写错的地方不是 Cursor 本身，而是把“从某个键开始”误当成“只读取这个前缀”。正确做法是让 Seek 负责定位起点，再用 bytes.HasPrefix 负责停止边界。bbolt 的键按字节序排列，所以同一前缀的键会连续出现，遇到第一个不匹配的键就可以结束扫描。

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

先把前缀边界定义成字节契约

假设键采用 tenant/{租户}/user/{用户ID} 的形式，本次只读取 tenant/acme/user/ 下的键。这里的前缀不是 SQL 的模糊匹配，也不是字符串比较，而是一段参与 bbolt 字节序排序的 []byte。前缀生成规则一旦改变，扫描范围也会随之改变，生产代码最好把它封装成一个小函数。

用 View、Bucket 和 Cursor 组成最小扫描接口

我更愿意把扫描写成返回错误的函数：bucket 不存在时直接报错，没有匹配项时返回空切片，而不是把两种情况混在一起。View 给整个回调提供一致视图，游标也只在这个回调里使用。

package store

import (
    "bytes"
    "errors"

    bolt "go.etcd.io/bbolt"
)

var ErrBucketMissing = errors.New("bbolt bucket is missing")

// ScanPrefix 只读取指定 bucket 中属于 prefix 的键。
func ScanPrefix(db *bolt.DB, bucketName, prefix []byte) (map[string][]byte, error) {
    result := make(map[string][]byte)

    err := db.View(func(tx *bolt.Tx) error {
        bucket := tx.Bucket(bucketName)
        if bucket == nil {
            return ErrBucketMissing
        }

        cursor := bucket.Cursor()
        // Seek 只负责找到起点，HasPrefix 才负责确认扫描仍在范围内。
        for key, value := cursor.Seek(prefix); key != nil && bytes.HasPrefix(key, prefix); key, value = cursor.Next() {
            // value 为 nil 时代表子 bucket，这里跳过它而不是误当成空值。
            if value == nil {
                continue
            }
            // Get/Cursor 返回的字节只保证在事务存活期间有效，带出事务前要复制。
            result[string(key)] = bytes.Clone(value)
        }
        return nil
    })
    return result, err
}

这个接口有三个刻意的决定：前缀只用一次 Seek，不对每个键重复定位；循环体不修改 bucket，避免边遍历边删除带来的游标跳跃；复制 value 后，调用方可以在事务返回后继续解码。若只在回调内立即处理数据，也可以省略复制，但不能把原切片长期缓存。

循环停止点决定了扫描是否准确

常见错误是写成 for key, value := cursor.Seek(prefix); key != nil; key, value = cursor.Next()，这样会继续读取后续业务空间的键。正确的停止点是前缀判断，而不是仅判断 key 是否为空。比如前缀是 tenant/acme/user/，当游标走到 tenant/acme/workspace/ 时，虽然它仍然是合法键，扫描也必须结束。

还要留意空结果：如果 Seek 返回 nil，说明没有不小于该前缀的键；如果返回了键但 HasPrefix 为假，说明排序空间里存在更近的键，但没有这个前缀。两者对调用方通常都可以表示为空列表，但排障日志可以分别记录，便于发现键编码不一致。

几个实际边界不要混在一个问题里

前缀扫描适合键已经按业务维度编码、并且调用方需要顺序读取一段范围的场景。它不等于全文搜索，也不替代复杂条件过滤。前缀中的分隔符要稳定，例如把用户 ID 直接拼接到路径后可能造成 user/1 与 user/10 的语义混淆；可以统一使用固定分隔符或长度前缀。

此外，Cursor 属于当前事务，不能跨 goroutine 共享。读写事务也不要互相嵌套持有，否则可能出现阻塞。扫描期间如果需要把 value 解码成结构体，建议在事务内完成解码，或者明确复制后的字节所有权。

常见问题

为什么只调用 Seek 还会读到其他键？

因为 Seek 只把游标移动到不小于目标的第一个位置，不会自动建立过滤条件。必须在循环条件里继续判断 bytes.HasPrefix。

value 为 nil 是不是代表空字符串？

不是。bbolt 用非 nil 的 key 加 nil 的 value 表示该项是子 bucket；真正的空字节值仍然可以是非 nil 切片，业务代码应分开处理。

为什么查询结果不能直接保存到缓存？

游标返回的键和值受事务生命周期约束。要在 View 结束后使用，至少要复制需要保留的字节，不能只保存原切片引用。