go 不在编译期报接口声明冲突错误，因其实行鸭子类型，仅检查实现而非接口定义一致性；问题源于不同包定义同名同签名接口导致运行时类型断言失败，需统一契约至 internal/contract 等唯一路径并彻底清理冗余定义。
为什么接口声明冲突不是 Go 编译器报错，而是运行时行为不一致
Go 不会在编译期报 interface conflict 错——它只管类型是否满足接口（duck typing），不管多个包里有没有同名、同签名的接口定义。真正出问题的是：两个包各自定义了 type Handler interface { Serve() }，然后 A 包传入一个实现了该接口的值给 B 包，B 包却用自己包里定义的同名接口去断言，结果 v.(B.Handler) 失败，panic 或静默失效。
这不是“语法错误”，而是隐式契约分裂：表面一样，实则不同类型，无法互相转换。
- 常见于微服务项目中，
user和order包各自定义Notifier接口用于发事件 - 测试文件里 mock 实现了 A 包的接口，但被 B 包的函数接收时因类型不匹配而断言失败
- 使用
go:generate工具生成 client 代码时，DTO 结构体字段 tag 或嵌套结构不一致，导致 JSON 序列化/反序列化错位
把接口声明统一到 internal/contract 或 pkg/contract
必须让所有用到该契约的地方，import 的是**同一个接口定义**，而不是“看起来一样”的多个副本。
-
internal/contract是首选：它天然阻止外部模块 import，适合仅限本项目内共享的 RPC 契约、事件回调约定 - 若需被其他模块（如 CLI 工具、SDK）复用，则用
pkg/contract或api/v1，并确保其go.mod独立、语义版本稳定 - 接口定义要极简：只含当前调用链真正需要的方法，不加
Close()、Init()等无关方法 - 避免在接口里嵌套非标准库类型（如自定义 error 类型），否则又会引发新一层依赖
示例：internal/contract/event.go
package contract
type EventPublisher interface {
Publish(ctx context.Context, e Event) error
}
type Event interface {
ID() string
Type() string
}
删掉所有分散在业务包里的重复接口定义
一旦契约集中，旧接口就成了技术债。不删干净，IDE 可能仍提示“实现接口”，但 runtime 会失败。
- 全局搜索
type.*interface.*{+ 包路径关键词（如user/notifier.go），定位所有冗余接口 - 检查
*_test.go文件——它们常偷偷定义 mock 接口，最容易漏删 - 删掉后若编译失败，说明某处还在用旧接口做类型断言，必须改成
contract.EventPublisher - 别用
//nolint忽略，那只是掩盖问题；运行go build ./...确保全量通过
用 go list -f '{{.ImportPath}}: {{.Imports}}' ./... 验证契约唯一性
光靠眼睛看 import 路径不可靠，尤其当有 replace 或 vendor 干扰时。得用 Go 自带工具确认物理路径一致性。
- 执行命令：
go list -f '{{.ImportPath}}: {{.Imports}}' ./... | grep contract - 输出里所有包都应只 import
your-module/internal/contract（或你定的唯一路径），不能出现user/contract或order/iface - 如果发现某个包 import 了两个不同路径的“类似”契约包，说明重构没到位，或者
go.mod replace指向了错误分支 - 配合
go mod graph | grep contract查看该包是否被意外拉进依赖环
真正麻烦的从来不是写代码，而是让所有人——包括三个月后的你自己——相信那个接口定义只能有一份，且永远在那里。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
