ScyllaDB能直接复用Cassandra生态，gocql是事实标准客户端，开箱即用但需精细配置连接参数、键空间建模和错误处理，否则微服务中易沦为“伪高性能”。
ScyllaDB 能直接复用 Cassandra 生态，gocql 客户端开箱即用，但连接配置、键空间建模和错误处理不调好，很容易在微服务里变成“伪高性能”。
为什么用 gocql 而不是自己写驱动
ScyllaDB 完全兼容 Cassandra CQL 协议，gocql 是事实标准，维护活跃、支持连接池、重试策略和 TLS。自己封装协议既没必要，也容易踩坑——比如忽略 consistency 级别导致读写不一致，或没设 Timeout 导致 Goroutine 泄漏。
-
gocql默认启用连接池，单个*gocql.Session可安全并发使用，无需每个请求 new 一个 - 它内置了
HostSelectionPolicy，能自动剔除不可达节点；但默认不开启RoundRobinHostPolicy，需显式配置才能均匀打散请求 - 不支持原生
INSERT ... IF NOT EXISTS的轻量级条件写入（LWT），要用IF NOT EXISTS显式拼写，否则并发插入可能覆盖
Session 初始化时必须控制连接参数
微服务启动时初始化一次 *gocql.Session，全局复用。别在 handler 里反复 gocql.NewSession()，否则连接数爆炸，ScyllaDB 侧会触发 TooManyConnections 拒绝新连接。
-
Timeout和ConnectTimeout必须设，建议都设为3s，避免慢节点拖垮整个服务 -
NumConns（每节点连接数）别盲目调高，默认2够用；超过4反而增加 ScyllaDB 的调度压力 - 务必设置
Consistency，微服务场景推荐gocql.One（读写都只要 1 副本确认），比Quorum低延迟，且 ScyllaDB 的hinted handoff能兜住临时节点故障 - 如果用 Docker Compose 启动 ScyllaDB，
Hosts列表要填容器名（如["scylla-node-1"]），不是localhost—— 容器内localhost指向自己，连不上其他节点
键空间（Keyspace）和表结构设计直接影响查询性能
ScyllaDB 不是“换个驱动就能跑”，它的分区键（PARTITION KEY）决定数据物理分布，一旦建错，后续无法修改，只能重建表 + 迁移数据。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 避免用业务 ID（如
user_id）当唯一分区键，热点集中在单个分片；应组合时间戳或哈希后缀，例如(user_id % 100)或toDayOfYear(created_at) - WHERE 条件只能用分区键 + 集群键（
CLUSTERING KEY）做范围查询；想按非主键字段查，必须建二级索引（CREATE INDEX）或物化视图（MATERIALIZED VIEW），但二者都牺牲写性能 - 微服务间共享的实体（如订单），建议用
service_name:entity_id作主键，避免不同服务写冲突，也方便按服务隔离清理数据 - 慎用
counter类型字段——它不支持原子增减以外的操作，且在多 DC 场景下最终一致性难保障
超时与重试必须结合 Context 控制
ScyllaDB 查询失败不等于数据丢失，可能是网络抖动或节点 GC 暂停。简单 return err 会让上游重试放大压力，而无限制重试又拖死服务。
- 所有
session.Query(...).Exec()或.Scan()都要传带 Deadline 的context.Context，例如ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond) -
gocql自带重试策略（SimpleRetryPolicy），但默认只重试幂等操作（SELECT,INSERT）；对UPDATE和DELETE不重试，需自行包装逻辑 - 遇到
gocql.ErrNotFound或gocql.ErrUnavailable时，别直接 panic，应记录 metric 并返回 HTTP 503，让网关做熔断 - 批量写入（
BATCH）要限制大小，ScyllaDB 推荐单个 BATCH 不超过 5KB，否则触发RequestTimedOut
真正卡住人的不是怎么连上，而是分区键选错后发现 QPS 掉一半、GC 时间飙升，或者某次上线后 gocql 报 no hosts available 却查不出哪个节点掉线——这时候得翻 system.peers 表，而不是只看日志。
