Couchbase 跨文档乐观锁与事务实现

Couchbase 本身不支持传统 RDBMS 的多文档 ACID 事务（尤其在早期版本），但可通过文档建模优化、模拟事务记录和多阶段状态追踪等方式，在 Go 应用中安全实现“全成功或全失败”的多文档更新语义。

在分布式键值存储如 Couchbase 中，原生的乐观锁（如 CAS 值校验）仅作用于单文档——这是其高性能与可扩展性的基础设计权衡。当你需要原子性地更新多个文档（例如：扣减库存 + 创建订单 + 更新用户积分），必须通过应用层策略模拟事务语义。以下是三种经过生产验证的可行方案，均适用于 Go 客户端（如官方 gocb/v2 或 gocbcore）：

✅ 方案一：重构文档模型，合并为单文档（推荐优先尝试）

将逻辑上强关联的多个实体聚合进一个“聚合根”文档。例如，将订单、商品库存快照、用户积分变更摘要统一存入一个 order:12345 文档：

type OrderAggregate struct {
    OrderID     string      `json:"orderId"`
    Status      string      `json:"status"` // "pending", "confirmed", "failed"
    Items       []Item      `json:"items"`
    InventorySnapshots map[string]int `json:"inventorySnapshots"` // sku → pre-update qty
    UserPointsDelta   int          `json:"userPointsDelta"`
    CAS         uint64      `json:"-"` // 用于乐观锁，不序列化
}

// 使用 CAS 执行原子更新
res, err := bucket.Replace("order:12345", &agg, &gocb.ReplaceOptions{
    Cas: agg.CAS, // 上次读取的 CAS 值
})

✅ 优势：真正原子、低延迟、无需额外协调；
⚠️ 注意：需评估单文档大小（Couchbase 默认最大 20MB）、更新热点（避免单 Key 成为瓶颈）、以及查询灵活性（可能需配合 N1QL 或索引优化）。

✅ 方案二：基于视图/索引的“效果模拟”

当业务允许最终一致性时，可将变更写入一个“事件文档”，再由后台服务（或 N1QL +定时任务）异步驱动下游更新，并通过 MapReduce 视图或 GSI 索引确保状态可观测。例如：

// 写入事务事件（带唯一 ID 和时间戳）
event := struct {
    TxID     string    `json:"txId"`
    Type     string    `json:"type"` // "stock_deduct_order_create"
    Payload  interface{} `json:"payload"`
    Created  time.Time `json:"created"`
}{TxID: uuid.New().String(), ...}

_, _ = bucket.Insert("tx:"+event.TxID, event, nil)

✅ 优势：解耦、可审计、天然支持重试与补偿；
⚠️ 注意：不满足强实时一致性要求；需额外运维消费者服务，并处理幂等与超时。

✅ 方案三：多阶段事务记录（Two-Phase Commit 模拟）

引入专用事务元文档（如 tx:abc123），按阶段持久化状态：

Go 示例关键逻辑：

func executeMultiDocTx(bucket *gocb.Bucket, txID string, ops []DocOp) error {
    // 1. 创建 prepared 事务记录
    txDoc := &TxRecord{TxID: txID, State: "prepared", Docs: extractKeys(ops)}
    _, err := bucket.Insert("tx:"+txID, txDoc, nil)
    if err != nil { return err }

    // 2. 并行执行各文档 CAS 更新（带重试）
    for _, op := range ops {
        if !tryUpdateWithCAS(bucket, op.Key, op.Value, op.ExpectedCAS) {
            // 3. 回滚：标记 aborted 并释放预占
            rollbackPreparedTx(bucket, txID)
            return errors.New("CAS failure at " + op.Key)
        }
    }

    // 4. 提交事务元文档
    txDoc.State = "committed"
    _, _ = bucket.Replace("tx:"+txID, txDoc, nil)
    return nil
}

✅ 优势：提供近似 ACID 的可控语义；
⚠️ 注意：复杂度高，需严格保证各阶段幂等性、超时清理机制（如 TTL + TTL-aware cleanup worker），且无法规避网络分区导致的“脑裂”。

? 总结建议

• 首选方案一：90% 的多文档更新需求可通过合理聚合建模解决，兼顾性能与正确性；
• 慎用方案三：仅在业务强依赖跨文档原子性且无法重构模型时采用，务必配套监控、告警与人工干预流程；
• 避免裸用方案二：若业务要求“下单即扣库存”，纯异步事件无法满足，需结合方案一或三兜底。

无论选择哪种方式，Go 应用中都应封装为可复用的 TxManager 接口，并统一处理 CAS 冲突重试、上下文超时、错误分类（临时性 vs 永久性）等细节。