TiDB连接Go应用需配置DSN参数parseTime=true、clientFoundRows=true等，显式调用BeginTx并检查IsRetryableError，批量插入用多值语句，JSON/ENUM字段避免直接Scan到string。
TiDB 对 Go 应用完全兼容 MySQL 协议，所以你不需要特殊驱动或框架——直接用 github.com/go-sql-driver/mysql 就行，但必须注意几个关键配置项，否则连接会失败或行为异常。
连接 TiDB 时必须设置的 DSN 参数
TiDB 虽然兼容 MySQL 协议，但默认不支持旧版认证插件（如 mysql_native_password），且对连接初始化行为更严格。常见报错如 ERROR 1045 (28000): Access denied 或 invalid connection，往往源于 DSN 缺少必要参数。
- 强制指定认证方式：
?charset=utf8mb4&parseTime=True&loc=Asia%2FShanghai&timeout=30s&readTimeout=30s&writeTimeout=30s&clientFoundRows=true - 特别注意
clientFoundRows=true：TiDB 默认返回匹配行数而非影响行数，不加这个会导致sql.Result.RowsAffected()返回 0，即使 UPDATE 成功 - 避免使用
allowOldPasswords=1：TiDB 不支持该模式，设了反而触发拒绝连接
事务控制要显式调用 BeginTx 并检查 IsRetryableError
TiDB 是乐观事务模型，写冲突时不会阻塞，而是抛出可重试错误（如 ErrWriteConflict）。Go 标准 database/sql 的 Begin() 不带上下文，无法感知重试语义，容易导致数据不一致或 panic。
- 用
db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelRepeatableRead})替代db.Begin() - 捕获错误后，用 TiDB 提供的
github.com/pingcap/tidb/util/errors.IsRetryableError(err)判断是否应重试 - 不要依赖
err == sql.ErrTxDone来判断事务状态——TiDB 可能在 Commit 阶段才返回冲突错误
批量插入优先用 INSERT ... VALUES (...), (...) 而非循环 Exec
TiDB 的分布式架构下，单条 INSERT 会产生多次 RPC 和时间戳分配开销，吞吐量远低于合并后的多值插入。实测在 1000 行数据场景下，批量拼接比逐条快 8–12 倍。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 限制单次插入不超过 1000 行（受
tidb-max-batch-size和内存影响） - 避免用
ON DUPLICATE KEY UPDATE：TiDB 5.0+ 支持，但会退化为悲观锁行为，影响并发；推荐先SELECT FOR UPDATE再判存否 - 如果必须流式写入，启用
tidb_batch_insert=1（通过 DSN 添加&tidb-batch-insert=1）可自动分批，但仅对简单 INSERT 生效
sql.NullXXX 类型在 JSON/Enum 列上容易空值解析失败
TiDB 的 JSON 和 ENUM 类型在 Go 中不能直接 Scan 到 string，否则遇到 NULL 会报 sql: Scan error on column index X；而 sql.NullString 又无法正确反序列化 JSON 字段。
- JSON 列：定义字段为
json.RawMessage，再手动json.Unmarshal；NULL 时RawMessage为nil，无需额外判空 - ENUM 列：TiDB 实际存的是字符串，但协议可能返回空字节；建议统一 Scan 到
*string，再做非空校验 - 避免用
Scan(&struct{})自动映射含 JSON/ENUM 的结构体——反射无法处理协议层的类型歧义
最常被忽略的是事务重试逻辑和 DSN 中的 clientFoundRows——这两个点不配对，业务代码看似运行正常，实则影响行数统计和并发正确性，上线后才暴露问题。
