// Package clickhouse ClickHouse 存储层(Day 14): // 历史明细/统计的批量写入(native 协议,阶段 5 历史库依赖)。 package clickhouse import ( "context" "fmt" "time" ch "github.com/ClickHouse/clickhouse-go/v2" ) // Config 连接配置(对应 config.ClickHouse)。 type Config struct { Addrs []string Database string Username string Password string DialTimeout time.Duration } // Conn 存储连接抽象(测试可注入 mock)。 type Conn interface { Ping(ctx context.Context) error // BatchInsert 批量插入:INSERT INTO table (columns...) VALUES 每行一行。 // 空行返回 nil;类型由调用方保证与表结构一致。 BatchInsert(ctx context.Context, table string, columns []string, rows [][]any) error // Query 只读查询(S4·D3 冷查;游标语义 Next/Scan/Close,args 走原生 bind)。 Query(ctx context.Context, query string, args ...any) (Rows, error) // Exec DDL/管理语句(建表/DROP PARTITION;args 走原生 bind)。 Exec(ctx context.Context, query string, args ...any) error Close() error } // Rows 查询游标抽象(驱动行集满足该接口即可)。 type Rows interface { Next() bool Scan(dest ...any) error Close() error } // Open 建立 native 协议连接(lazy,首次命令时建立)。 func Open(cfg Config) (Conn, error) { if len(cfg.Addrs) == 0 { return nil, fmt.Errorf("clickhouse: addrs 不能为空") } if cfg.DialTimeout <= 0 { cfg.DialTimeout = 10 * time.Second } conn, err := ch.Open(&ch.Options{ Addr: cfg.Addrs, Auth: ch.Auth{Database: cfg.Database, Username: cfg.Username, Password: cfg.Password}, DialTimeout: cfg.DialTimeout, Compression: &ch.Compression{Method: ch.CompressionLZ4}, }) if err != nil { return nil, fmt.Errorf("clickhouse: 打开连接失败: %w", err) } return &nativeConn{conn: conn}, nil } // nativeConn clickhouse-go 实现。 type nativeConn struct{ conn ch.Conn } func (c *nativeConn) Ping(ctx context.Context) error { return c.conn.Ping(ctx) } func (c *nativeConn) Close() error { return c.conn.Close() } // Query 只读查询透传(*ch.Rows 实现 Rows 接口)。 func (c *nativeConn) Query(ctx context.Context, query string, args ...any) (Rows, error) { rows, err := c.conn.Query(ctx, query, args...) if err != nil { return nil, fmt.Errorf("clickhouse: 查询失败: %w", err) } return rows, nil } // Exec DDL/管理语句透传。 func (c *nativeConn) Exec(ctx context.Context, query string, args ...any) error { if err := c.conn.Exec(ctx, query, args...); err != nil { return fmt.Errorf("clickhouse: 执行失败: %w", err) } return nil } func (c *nativeConn) BatchInsert(ctx context.Context, table string, columns []string, rows [][]any) error { if table == "" || len(columns) == 0 { return fmt.Errorf("clickhouse: table/columns 不能为空") } if len(rows) == 0 { return nil } batch, err := c.conn.PrepareBatch(ctx, insertSQL(table, columns)) if err != nil { return fmt.Errorf("clickhouse: 准备批次失败: %w", err) } for _, row := range rows { if len(row) != len(columns) { return fmt.Errorf("clickhouse: 行列数 %d 与列定义 %d 不一致", len(row), len(columns)) } if err := batch.Append(row...); err != nil { return fmt.Errorf("clickhouse: Append 失败: %w", err) } } if err := batch.Send(); err != nil { return fmt.Errorf("clickhouse: 批次发送失败: %w", err) } return nil } // insertSQL 构造 INSERT 语句(表名/列名由调用方白名单控制,防注入)。 func insertSQL(table string, columns []string) string { // S1-B:标识符反引号化——模块名含连字符(go-sms_*)的表名裸拼会语法错误。 sql := "INSERT INTO `" + table + "` (" for i, c := range columns { if i > 0 { sql += "," } sql += "`" + c + "`" } return sql + ")" }