连接Couchbase需传节点地址（如"127.0.0.1"）而非URL，显式配置用户名密码，TLS需手动设；Bucket须预创建并授权；操作用Upsert非Insert；Get需手动解析JSON并判err。
连接 Couchbase 需要先配好集群地址和认证，不是填个 URL 就能通
Go 用 gocb 连 Couchbase，最常见错误是直接传 "http://localhost:8091" 或 "couchbase://127.0.0.1" 就以为连上了——其实 gocb 的 gocb.Connect() 接收的是集群地址列表（不带协议），且默认走二进制协议端口（11210），不是 HTTP 管理端口（8091）。
正确做法是只传节点 IP 或域名，多个用逗号分隔；认证必须显式提供，即使本地单节点没开鉴权，也要传空凭证：
cluster, err := gocb.Connect("127.0.0.1", gocb.ClusterOptions{
Username: "Administrator",
Password: "password",
})- 集群地址不能带
http://、couchbase://前缀，否则会解析失败或静默降级为 DNS SRV 查找 - 如果启用了 TLS（比如 Couchbase Capella 或自建集群开了加密），必须用
gocb.ClusterOptions.TLSConfig显式配置，否则连接超时无提示 - 单节点开发环境也建议设
Username/Password，避免因权限缺失导致后续Bucket打开失败
打开 Bucket 后才能操作文档，但 Bucket 名不是数据库名
Couchbase 里没有“数据库”概念，Bucket 是顶层数据容器，类似传统 DB 的 database。但 gocb 不支持运行时创建 Bucket，必须提前在 Web 控制台或 CLI 里建好；连接后调用 cluster.Bucket("my-bucket") 只是获取句柄，不触发网络请求。
容易踩的坑是：误以为 Bucket 名可以随便写，结果 bucket.DefaultCollection() 报 gocb.ErrBucketNotFound 或 gocb.ErrAuthenticationFailure（其实是权限不足，没被授权访问该 Bucket）。
立即学习“go语言免费学习笔记（深入）”；
- 确认 Bucket 已存在且当前用户有
Application Access权限（最小权限，别直接给 Admin） - 4.5+ 版本默认启用 Collections，推荐用
bucket.DefaultCollection()，而不是老式的bucket.Get()直接操作 - 如果 Bucket 启用了内存配额但已满，
Upsert()会返回gocb.ErrTemporaryFailure，不是代码问题，得扩配额或删旧数据
写文档用 Upsert 而不是 Insert，ID 冲突时行为完全不同
Insert() 要求文档 ID 必须不存在，否则报 gocb.ErrDocumentExists；而 Upsert() 总是成功，已存在就覆盖，不存在就新建——绝大多数业务场景该用 Upsert()，比如用户资料更新、订单状态变更。
示例：
_, err := collection.Upsert("user::123", map[string]interface{}{
"name": "Alice",
"email": "alice@example.com",
}, nil)- 第三个参数是
*gocb.UpsertOptions，常用设置包括Expiry（TTL）、DurabilityLevel（如gocb.DurabilityLevelMajority） - 不设
Expiry就是永不过期；设了负数会 panic，必须是time.Duration类型（比如time.Hour * 24） - 高并发写同一 ID 时，
Upsert是最终一致，不会锁行，但版本冲突靠 CAS 值控制，不是乐观锁那种自动重试
查文档用 Get 拿原始字节，JSON 解析得自己来
collection.Get("doc-id", nil) 返回的是 *gocb.GetResult，它的 Content() 方法把底层 []byte 直接解到传入的变量地址，不校验 JSON 结构是否匹配。如果字段名拼错或类型对不上，会静默忽略或赋零值，很难 debug。
更安全的做法是先用 ContentAs[byte] 拿原始数据，再用标准 json.Unmarshal 并检查 error：
res, err := collection.Get("user::123", nil)
if err != nil {
// 处理 not found 或 network error
}
var raw []byte
err = res.ContentAs(&raw)
if err != nil {
// 解包失败，说明服务端返回非 JSON 或损坏
}
var user map[string]interface{}
err = json.Unmarshal(raw, &user)- 不要依赖
ContentAs[T]自动解结构体，除非 T 字段名、tag、类型完全和文档一致；否则字段缺失时不会报错，而是留零值 - 如果文档很大（>1MB），
Get()默认一次拉全，没流式支持，可能 OOM；考虑用 N1QL 查询加 LIMIT 或拆成小文档 - 查不到文档时，
err是gocb.ErrDocumentNotFound，不是nil，必须显式判断，不能只看返回值是否为空
Couchbase 的连接生命周期、Bucket 权限粒度、CAS 值使用时机，这三处最容易在压测或上线后暴露——不是连不上，而是连得上却读不到、写不进、或并发时覆盖错。
