模块路径改名后旧依赖如何平滑迁移而不制造双份包

Go 模块路径不是仓库的备注字段，而是模块及其包路径的身份前缀。把 corp.example/old/sdk 改成 corp.example/platform/sdk 后，即使两边暂时指向相似源码，Go 仍会把它们视为不同包。旧新路径一旦同时进入构建图，就可能出现两份包级状态、重复注册，以及命名类型不能直接互换的问题。

模块路径改名到底改变了什么

Go 官方模块参考把 module path 定义为模块的规范名称，同时它也是模块内所有 package path 的前缀。因此，改名不是“同一个包换了下载地址”，而是创建了新的导入身份。官方参考还明确说明，带不同主版本后缀的模块会被当作独立模块，它们的包也是不同的；任意路径改名同样会产生这种身份分离。

风险不只体现在编译错误。如果旧包和新包都含有注册表、连接池、指标收集器或 init 注册逻辑，它们可能各自初始化一次。两个路径下名字相同的命名类型也不是同一类型，接口断言和泛型约束可能在边界处暴露问题。

最小可用方案：单实现、双入口

假设新模块已经发布为 corp.example/platform/sdk。旧模块不要继续复制实现文件，而是声明对新模块的依赖，并在旧 import 路径下提供兼容包。

// Deprecated: use corp.example/platform/sdk instead.
module corp.example/old/sdk

go 1.22

require corp.example/platform/sdk v1.6.0

Go 模块参考支持在 module 指令附近使用以 Deprecated: 开头的注释标记整个模块弃用。兼容包内优先用类型别名复用新模块的导出类型，再用薄函数包装保持旧调用方式：

// Deprecated: use corp.example/platform/sdk.
package sdk

import newsdk "corp.example/platform/sdk"

// Client 与 Option 直接复用新模块中的类型身份。
type Client = newsdk.Client
type Option = newsdk.Option

// New 保持旧入口，同时只创建新模块的实现对象。
func New(opts ...Option) *Client {
    return newsdk.New(opts...)
}

类型别名表示旧名字和新名字指向同一个类型，这对结构体、接口参数和方法集迁移非常有用。函数、变量和常量则按 API 语义选择包装或转发。兼容层应当尽量无状态：不要再维护第二份注册表、缓存或后台任务，也不要把新功能继续加回旧路径。

下游如何分批迁移

先发布新模块及稳定版本，再发布依赖该版本的旧模块兼容版本。下游可以逐个包替换 import，并在每次变更后运行 go mod tidy。迁移不要求所有仓库同一天完成，但同一个应用的边界类型应优先统一，避免一边仍暴露旧路径、另一边已经改成新路径。

# 检查构建列表里是否同时存在旧、新模块
go list -m all | grep -E 'corp\.example/(old|platform)/sdk'

# 查看哪个模块仍然把旧路径带进依赖图
go mod graph | grep 'corp.example/old/sdk'

# 搜索源码中尚未迁移的旧 import
go list -deps ./... | grep 'corp.example/old/sdk'

如果旧路径仍然存在，先确定它来自当前模块的源码还是传递依赖。对于可控仓库，直接升级并改 import；对于暂时不可控的第三方依赖，保留兼容层，等待其发布新版本。不要因为一个间接依赖未迁移就删除旧模块版本，否则会把平滑迁移变成集中故障。

为什么长期 replace 不是迁移方案

replace 很适合本地开发、故障验证或主模块中的临时救火，但它只由执行构建的主模块决定。依赖模块自己 go.mod 里的 replace 不会替所有下游生效，而且 replace 也不会自动重写源码中的 import。把旧模块替换到新代码仓库，并不能消除旧新 package path 的身份差异。

更危险的做法是让旧、新路径分别发布一份相同源码。短期看似兼容，长期却会同时修两套实现，并把安全更新、全局状态和类型边界分叉。兼容层的价值正是把“两个入口”压缩为“一个实现”。

不要把任意改名和 /v2 混为一谈

从 v2 开始，Go 要求模块路径带有匹配主版本的后缀，例如 example.com/mod/v2。这是语义导入版本设计的一部分，目的就是允许不兼容主版本在同一构建中共存。域名或组织路径改名不是主版本升级；若 API 仍要兼容，应使用兼容层和弃用计划，而不是仅仅把版本号升到 v2 来掩盖路径迁移。

兼容层什么时候可以删除

至少满足三项再退场：主要下游都已改用新路径；组织内的模块图扫描不再发现旧路径；弃用窗口已经跨过约定的发布周期。最后发布一版清晰的迁移说明，而不是删除历史标签。已经进入模块代理的版本是不可变快照，迁移计划要尊重已发布版本仍可能被旧项目解析的事实。

常见问题

仓库换了组织名，module 行必须跟着改吗？

不一定。只要原模块路径仍能稳定解析并下载，保留路径通常能避免整个生态修改 import。是否改 module 应由公共身份需求决定，而不是由仓库目录名自动决定。

类型别名能解决所有兼容问题吗？

不能。它适合复用类型身份，但包级变量、注册行为、不可导出符号和发生语义变化的函数仍需单独设计。兼容层应保持薄、无状态，并通过新模块完成真实工作。

能不能在旧模块 go.mod 里写 replace 指向新模块？

不应把它当成发布方案。下游作为主模块时不会继承依赖模块的 replace，而且源码 import 仍保留旧身份。正式迁移应发布可下载的新模块和显式兼容包。

如何判断已经没有双份包风险？

同时检查 go list -m all、go mod graph 和源码 import。构建列表中只剩新模块、依赖图没有旧路径、应用边界不再暴露旧路径类型，才算完成主体迁移。