Gin + ScyllaDB 必须绕过 GORM，直连 gocql：因 ScyllaDB 兼容 Cassandra 协议而非关系型协议，gocql 未实现 database/sql 接口，且其分区键、LWT、TTL 等特性无法被 GORM 表达；需在 main 中单例初始化 *gocql.Session 并通过中间件注入 context，查询时严格匹配 CQL 列名、确保 WHERE 含分区键、用 BATCH 批量操作、用 IF EXISTS 实现轻量级事务。
Gin 本身不内置数据库驱动，ScyllaDB 又不是 MySQL/PostgreSQL 那类传统关系型数据库，直接套用 GORM 或 database/sql 会失败——它用的是 Cassandra 协议，得走 CQL（Cassandra Query Language）和对应的 Go 客户端。
结论很明确：Gin + ScyllaDB 的极简集成，必须绕过 ORM，直连 gocql，且不能复用 GORM 的 AutoMigrate、关联、预加载等惯用逻辑。
为什么不能用 GORM 连 ScyllaDB
ScyllaDB 兼容 Cassandra 协议，但 GORM 官方只支持 PostgreSQL、MySQL、SQLite、SQL Server 等关系型后端。gorm.io/gorm 底层依赖 database/sql 接口，而 gocql 并未实现该接口——它自己维护连接池、查询执行、类型映射和重试策略。
- 尝试注册
gocql为database/sql驱动会 panic，因为没实现driver.Driver - 强行包装一层适配器（如
cql-driver类项目）稳定性差、功能残缺、无维护 - ScyllaDB 的分区键、聚簇键、轻量级事务（LWT）、TTL 等特性，在 GORM 模型层无法自然表达
怎么用 gocql 在 Gin 中安全初始化连接
gocql 在 Gin 中安全初始化连接ScyllaDB 连接是长生命周期资源，必须单例复用，不能每次请求都 gocql.NewSession()。Gin 的 *gin.Engine 没有内置容器，得手动挂载到 gin.Context 或全局变量（推荐前者，便于测试隔离）。
- 在
main()初始化时创建*gocql.Session，用context.WithTimeout控制建连超时（ScyllaDB 启动慢时尤其关键） - 连接字符串用
host:port列表（如[]string{"127.0.0.1:9042", "192.168.1.10:9042"}），别只写一个节点 - 务必设置
Consistency（如gocql.One或gocql.Quorum），否则读写可能不一致 - 启用
DisableInitialHostLookup: true可跳过 DNS SRV 查找，加速启动
session, err := gocql.NewSession(gocql.ClusterConfig{
Hosts: []string{"127.0.0.1:9042"},
Keyspace: "myapp",
Consistency: gocql.Quorum,
Timeout: 5 * time.Second,
ConnectTimeout: 3 * time.Second,
DisableInitialHostLookup: true,
})
if err != nil {
log.Fatal("failed to connect to scylladb:", err)
}
defer session.Close() // 注意：这里只是示例，实际应长期持有
如何把 *gocql.Session 注入 Gin 请求处理链
*gocql.Session 注入 Gin 请求处理链Gin 没有 DI 容器，最轻量做法是用 gin.Context.Set() 在中间件里注入，后续 handler 用 c.MustGet() 取出。避免全局变量，方便单元测试 mock。
- 写一个中间件
scyllaMW(session *gocql.Session)，调用c.Set("scylla", session) - handler 里统一用
sess, ok := c.MustGet("scylla").(*gocql.Session)，加ok判断防 panic - 不要在 handler 里调
session.Query(...).Exec()后立刻Close()——gocql.Session是线程安全的，应长期复用 - 错误要检查
err != nil，特别是gocql.ErrNotFound和gocql.ErrUnavailable，它们含义不同，不该一概500
ScyllaDB 查询在 Gin handler 里怎么写才不踩坑
CQL 查询不是 SQL，没有 JOIN、没有外键约束、没有自动类型转换。结构体字段名和 CQL 列名必须严格对应（或显式用 json: tag 绑定），且 time.Time 要注意时区。
- 用
session.Query("SELECT id,name FROM users WHERE id = ?", id).Scan(&u.ID, &u.Name)，别依赖反射绑定 - 批量插入用
BATCH语句，而不是循环单条INSERT（性能差 10 倍以上） - WHERE 条件必须包含分区键，否则查全表（ScyllaDB 会拒绝或超时）
- 更新带条件用
IF EXISTS或IF col = ?实现轻量级事务（LWT），返回applied bool
var applied bool
err := session.Query(`INSERT INTO users (id, name) VALUES (?, ?) IF NOT EXISTS`, id, name).Scan(&applied)
if err != nil {
// 处理 error
}
if !applied {
// 并发冲突，已存在
}
ScyllaDB 的数据模型设计（比如宽列、反范式化、按查询路径建表）比代码集成更关键。连接配好了、查询跑通了，不代表读写高效——那得看你的 CREATE TABLE 语句有没有把分区键和聚簇键选对。
