gocql是go生态中唯一成熟可用的cassandra客户端，直接对接native cql二进制协议v4+，不依赖java/python或http中间层；thrift已被官方弃用。
gocql 是当前 Go 生态中唯一成熟可用的 Cassandra 客户端
别折腾 Thrift 或自己封装二进制协议——gocql 是事实标准，不是“可选方案”，而是唯一经过大规模生产验证的实现。它直接对接 Cassandra 的 native CQL binary protocol v4+，不依赖 Java 或 Python 运行时，也不走 HTTP 中间层。Thrift 方式早已被官方弃用（Cassandra 4.0+ 默认禁用 Thrift 服务），且生成代码维护成本高、类型映射僵硬、无法利用现代 CQL 特性（如轻量级事务、UDT、集合操作符）。如果你看到还在推 Thrift 的教程，基本是 2020 年前的老资料。
连接配置里最容易漏掉的三个关键项
光写 gocql.NewCluster("127.0.0.1") 能连上，但一上线就出问题。必须显式设置：
-
cluster.Timeout：默认 600ms，对跨机房或高延迟链路明显不够，建议设为2 * time.Second -
cluster.Consistency：别用默认gocql.One，读写都设为gocql.Quorum才能兼顾可用性与数据一致性 -
cluster.ReconnectInterval：节点临时失联时重连间隔，默认 60s 太长，设为5 * time.Second更及时
另外，cluster.ProtoVersion 必须显式指定为 4（Cassandra 3.0+）或 5（Cassandra 4.0+），否则可能协商失败静默降级。
处理 Set/Map/List 类型时，别直接扫 struct 字段
gocql 对集合类型有默认映射规则，但容易踩坑：
- 定义字段为
[]string可接收set<text></text>，但顺序不保证（Cassandra set 无序），别依赖扫描后切片顺序 - 不能用
map[string]bool直接接收set<text></text>——gocql.Scan()不支持 map 类型自动解包，会 panic - 若需去重+有序语义，得手动转：
sort.Strings(productList); dedup := deduplicate(productList) - 写入时，传
[]string{"a","b"}没问题；但传nil表示空集合，传[]string{}会被当 null 写入（Cassandra 中为 NULL 值，非空集合）
时间戳字段务必用 time.Time，别 string 或 int64
Cassandra timestamp 列在 gocql 中自动映射为 time.Time，这是设计使然，不是巧合：
- 读取时直接扫进
time.Time字段，时区信息完整保留（Cassandra 存毫秒时间戳，gocql 解析时按 UTC 构造time.Time） - 写入时传
time.Now()即可，gocql 自动转成 Cassandra 所需格式，不用手动UnixMilli() - 如果扫成
string或int64，等于绕过类型安全，后续格式化、比较、时区转换全得自己手撸，还容易出错 - 注意：CQL 查询里用
toTimestamp(now())或dateOf(now())返回的仍是 timestamp 类型，照样能被time.Time接住
真正麻烦的是混合了纳秒精度需求或需要和旧系统对齐毫秒值的场景——这时才考虑用 UnixMilli() 显式提取，而不是默认放弃 time.Time。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
