连接Cassandra时gocql.ClusterConfig.Keyspace必须显式设置非空值，否则Session.Query会报“no keyspace specified”；ProtoVersion需匹配服务端版本；参数绑定严格按?位置顺序；struct字段gocql tag须全小写且与列名完全一致；Batch须同keyspace且单批≤65536条。
连接 Cassandra 集群时 gocql.ClusterConfig 必须显式设 Keyspace
不设 Keyspace 会导致后续所有 Session.Query 执行时返回 gocql: no keyspace specified 错误，哪怕 SQL 里写了 USE mykeyspace 或表名带前缀（如 mykeyspace.users）也不行——gocql 不解析 USE 语句，也不自动提取 keyspace 前缀。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
ClusterConfig.Keyspace是连接级默认 keyspace，必须非空字符串，哪怕你后续总用全限定名（keyspace.table）也得设一个占位值（比如"system"），否则session := cluster.CreateSession()就会失败 - 若应用需跨 keyspace 操作，别靠改
ClusterConfig.Keyspace重连，而是保持连接时设一个固定 keyspace（如"default"），查询时统一用"other_ks.table_name"写全名 - 注意
ProtoVersion要匹配服务端：Cassandra 4.x 推荐设gocql.V4，Cassandra 3.x 一般用V3；设错会卡在连接握手，日志只显示超时，没具体错误提示
执行 INSERT/UPDATE 时，Query.Bind 的参数顺序必须严格对应 ? 占位符位置
gocql 不支持命名参数（如 :name），只认位置。一旦传参顺序和 SQL 中 ? 出现顺序不一致，数据就写错字段，且不会报错——它默默按序绑定，直到类型不匹配才在执行时报 cannot unmarshal 类错误。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- INSERT 语句里字段顺序要和
Bind(...)参数顺序完全一致，例如INSERT INTO users (id, name, age) VALUES (?, ?, ?)，就必须按q.Bind(id, name, age)传 - 避免手写长参数列表，把结构体转为
[]interface{}时用反射或工具函数确保顺序稳定，比如用structs.Map不可靠（字段顺序不保证），推荐手动展开：[]interface{}{u.ID, u.Name, u.Age} - UPDATE 语句同理，
SET name = ?, age = ? WHERE id = ?对应Bind(newName, newAge, id)，WHERE 条件参数永远放最后
查询结果扫描到 struct 时，字段标签 gocql 必须小写且与列名完全一致
gocql.ScanCAS 或 Iter.Scan 直接扫 struct 时，依赖字段上的 gocql tag 匹配列名。大小写不一致（如列是 user_id，tag 写成 "user_ID"）、多空格、下划线位置错，都会导致该字段始终为零值，且无任何警告。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- tag 值必须全小写，且和 CQL 中实际列名（case-sensitive）一模一样，包括下划线：
UserID int `gocql:"user_id"`✅，UserID int `gocql:"USER_ID"`❌ - 如果列名含大写字母（如启用
quoted identifiers的"UserId"），tag 也必须带引号并大小写精确：UserID int `gocql:"\"UserId\""` - 别依赖 struct 字段名自动映射（如
UserID→user_id），gocql默认不推导，不设 tag 就跳过该字段
批量写入用 Batch 时，单个 batch 最多 65536 条语句，且所有语句必须在同一 keyspace
超出数量限制会触发 gocql: batch size too large；跨 keyspace（比如一个 batch 里混了 ks1.t1 和 ks2.t2）则静默失败——session.ExecuteBatch 返回 nil 错误，但数据一条都没写进去。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
session.NewBatch(gocql.UnloggedBatch)创建 batch，不要用LoggedBatch（性能差，且要求所有语句同 keyspace + 同 consistency） - 每批控制在 50–200 条较稳：太多易触发 coordinator 超时；太少则网络开销占比高
- 提前按 keyspace + 表名分组，每个 batch 只塞同一张表的语句；不同表必须拆 batch
gocql 的错误掩盖很常见：比如 WriteTimeoutError 可能已写入部分副本，而驱动默认不重试。这事得自己在业务层判断是否幂等、要不要查证，不能只看 error 是否为 nil。 
