解析Golang中的适配器模式与Legacy代码重构 Go语言平滑迁移技巧

go中编写无感适配器的关键是：新适配器必须严格实现旧接口的全部方法签名（含名称、参数顺序、返回值个数与类型，Error类型精确匹配），补全空方法，复现全局变量，并通过shim包伪装成原包路径，同时内部用带超时的context兜底但不暴露。

Go 里怎么写一个不破坏原有接口的适配器

适配器不是加层包装就完事——关键在于让老代码 LegacyService 的调用方完全无感，连 import 都不用改。核心是：新适配器必须实现和旧类型**完全一致的接口签名**，包括方法名、参数顺序、返回值个数与类型，连 error 是指针还是值都不能错。

常见错误是直接套用新 SDK 的 DoRequest 方法，结果返回 (*http.Response, error)，而老接口定义的是 ([]byte, error)。这时候必须在适配器里做转换，而不是让上游去处理 http.Response.Body。

实操建议：

• 先用 go vet -v 检查接口实现是否完整，尤其注意 error 类型是否匹配（error 是 Interface，但底层实现可能是 *errors.errorString 或自定义 Struct）
• 不要在适配器里加新方法，哪怕只是 WithContext —— 调用方没声明依赖 context，加了反而引发 panic
• 如果 Legacy 接口有空接收器方法（比如 func (s *LegacyService) Close() {}），适配器也得补上空实现，否则 go test 会报 “missing method Close”

重构时怎么安全替换掉 legacy.NewClient()

直接全局搜 legacy.NewClient() 替换为 adapter.NewClient() 是高危操作——很多地方可能依赖了 legacy 包里的常量、错误变量或未导出字段。真正的平滑迁移，是让新客户端“假装自己是老包”。

立即学习“go语言免费学习笔记（深入）”；

典型场景：老代码 import 了 "github.com/oldcorp/legacy"，你不能要求所有团队立刻改 import 路径。解决方案是用 Go 的 vendor 机制 + 替换式 alias，但更稳妥的是在项目根目录建 legacy/ 目录，放一个仅含 NewClient 和接口定义的 shim 文件。

实操建议：

• 新建 legacy/legacy.go，只 export NewClient 和核心 interface，其他全删；内部用 import newclient "github.com/newcorp/sdk/v2"
• 确保新 client 构造函数签名和老的一致：比如老的是 func NewClient(addr string) *Client，你就不能改成 func NewClient(opts ...Option)
• 老包里如果有全局变量如 ErrTimeout，适配器里必须原样复现，类型和值都得一样（var ErrTimeout = errors.New("timeout")），否则 errors.Is(err, legacy.ErrTimeout) 会失败

适配器里要不要传 context？老代码根本没 context 怎么办

老代码没 context.Context 不代表你能忽略它——HTTP 超时、goroutine 泄漏、链路追踪都靠它。但硬塞进去会破坏调用契约。正确做法是：在适配器内部生成一个带默认 timeout 的 context.WithTimeout(context.background(), 30*time.Second)，而不是暴露 context 参数。

容易踩的坑是把超时逻辑写死在适配器里，结果线上发现某些接口要跑 2 分钟。这时候你没法动态调，只能发版。所以得留个后门：用可选配置项控制 timeout，但不暴露 context。

实操建议：

• 适配器构造函数支持 WithTimeout(d time.Duration) 选项，内部存为字段，每次调用时才生成子 context
• 避免在适配器方法里直接用 context.TODO() 或 context.Background() —— 它们无法被 cancel，一旦下游卡住，整个 goroutine 就挂死
• 如果老接口有重试逻辑（比如 DoWithRetry()），适配器里的 context 必须是每次重试都新建的，不能复用同一个，否则第一次 cancel 会影响后续重试

为什么 defer adapter.Close() 有时不生效

因为老代码压根没调 Close。适配器实现了 io.Closer，但 legacy 接口里没声明这个方法，调用方自然不会 defer。更麻烦的是，有些 legacy client 内部用了连接池或 goroutine，不 close 会导致 fd 耗尽或内存泄漏。

这不是代码风格问题，是资源生命周期错位。Go 没有析构函数，Close 必须显式调用，而适配器无法强制上游执行它。

实操建议：

• 在适配器 NewClient 里启动一个 watchdog goroutine，监听 runtime.SetFinalizer，当 client 被 GC 时打日志并尝试 close（仅作兜底，不保证时机）
• 把 Close 方法设计成幂等：多次调用不 panic，已关闭状态直接 return
• 如果 legacy 接口有 Shutdown() 这类生命周期方法，适配器必须同步 hook 进去，在那里触发真正的 Close

最麻烦的点往往不在代码怎么写，而在老系统里那些没文档的隐式依赖——比如某个定时任务每分钟调一次 legacy.Ping()，结果你把适配器的 Ping 改成走 HTTP，却忘了它底层复用了同一个 TCP 连接，而老代码没做连接保活，三分钟后连接被中间件断开，Ping 开始批量超时。这种问题，光看接口定义发现不了。