必须用接口定义适配层契约，而非结构体；因Go依赖隐式实现，仅通过最小化接口才能确保多后端自由实现且调用方无感，避免新增数据源时修改签名或暴露具体客户端引发耦合。
适配层必须用接口定义契约，而不是结构体
Go 里适配层失效的首要原因是把 Target 定义成 struct 或具体类型。适配的本质是“让 A 能被当作 B 用”，而 Go 的接口是隐式实现的——只有定义清晰、最小化的 interface，才能让不同后端自由实现，也才能让调用方完全不感知底层变化。
常见错误：用 type DataStore struct{...} 当作统一抽象，结果新增 Redis 适配时要改所有函数签名；或者把 PostgresClient 直接暴露给业务层，导致后续换 ClickHouse 时满屏报错。
- 正确做法：先写干净接口，例如
type DataStore interface { Get(key string) ([]byte, error); Put(key string, val []byte) error } - 接口方法越少越好，只包含当前业务真正需要的操作；多一个方法就多一分耦合风险
- 避免在接口里塞 context.Context——不是所有后端都支持 cancel，真需要时应由具体实现决定是否加 ctx 参数（Go 1.22+ 的
io.ReaderWithContext是例外）
注册表 + 工厂函数是多后端适配的唯一可持续方案
硬编码 if config.Driver == "mysql" 或反射取类型名，在接入第三个数据源时就会失控。注册表强制你在初始化阶段显式声明支持哪些后端，编译期可查、配置可驱动、运维可切换。
典型坑：注册表 map 未设为只读，或在多个 goroutine 中并发写入，导致 panic；还有人把键名写成 "github.com/xxx/mysql" 这类包路径，结果一升级包就断掉。
立即学习“go语言免费学习笔记（深入）”；
- 全局注册变量定义为
var adapters = make(map[string]func() DataStore)，并在init()或显式RegisterAdapters()中填充 - 键名必须与配置项一致，比如 YAML 里写
driver: postgres，注册时就用adapters["postgres"] = func() DataStore { return &PostgresAdapter{...} } - 使用时务必判空：
factory := adapters[config.Driver]; if factory == nil { panic("unknown driver: " + config.Driver) }
适配器 struct 必须显式字段，慎用嵌入
嵌入 *sql.DB 或 *pgxpool.Pool 看起来省事，但会把 Stats()、Close()、Ping() 等无关方法提升到 DataStore 接口上，破坏封装，还可能引发意外行为（比如业务代码误调 Close() 导致连接池提前销毁）。
另一个高频问题：嵌入的是值类型，但目标接口方法要求指针接收者；或者反过来，嵌入指针却依赖值接收者方法——编译器不会帮你自动转换方法集。
- 显式字段写法：
type PostgresAdapter struct { pool *pgxpool.Pool }，然后手动实现Get()和Put() - 只在被适配对象方法极少（≤2）、且全部需透传时才考虑嵌入，例如包装
http.HandlerFunc成http.Handler - 别用
type MyAdapter = ExistingType—— 类型别名不继承方法，毫无意义
函数适配器比 struct 更轻量，适合单方法接口
当目标接口只有一个方法（如 io.Writer.Write、http.Handler.ServeHTTP、json.Marshaler.MarshalJSON），用函数转接口比写 struct wrapper 干净得多。它没有额外内存分配、无字段管理负担、测试也更直接。
容易踩的坑：函数闭包捕获了大对象或未清理的资源；或者在函数体内做了本该由调用方控制的初始化（比如每次调用都 new 一个 logger）。
- 正确示例：
var handler http.Handler = http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { ... }) - 适配带参数的单方法接口时，优先用闭包注入依赖：
func NewLoggerWriter(l *zap.Logger) io.Writer { return io.WriterFunc(func(p []byte) (int, error) { l.Info(string(p)); return len(p), nil }) } - 避免在函数适配器里做阻塞操作、网络调用或锁竞争——它只是转发，不该承担业务逻辑
