Go接口新增方法导致旧实现编译失败，因其契约式设计要求类型必须实现接口所有方法；正确做法是按调用方场景拆分小接口、用适配器隔离第三方依赖、通过errno.Coder统一error码保障兼容性。
接口新增方法时，为什么旧实现编译失败？
Go 接口是“契约式”的：只要类型没实现接口里所有方法，就无法赋值给该接口变量。所以一旦在已有公开接口中加新方法，所有已实现该接口的代码都会编译报错——does not implement xxx (missing Yyy method)。
这不是设计缺陷，而是 Go 强制你面对兼容性问题。真正的向下兼容，不是“不改旧代码”，而是“改了也不破调用方”。关键在于：接口演化必须由调用方驱动，而非实现方单方面决定。
- 新增方法前，先确认是否已有调用方明确需要该能力（比如日志上下文透传、超时控制）
- 若只是“可能有用”，别加；Go 允许后续随时新增，旧实现补上即可，但调用方得同步升级才能用
- 如果必须加，优先用组合方式暴露新能力，而不是往老接口里塞方法（例如定义
ReaderWithContext而非给io.Reader加ReadContext）
如何让 service 层接口既可扩展又不破坏 handler 调用？
常见错误是把 UserService 设计成一个大接口，含 Create、Update、Delete、GetByID、List、Count……结果一加搜索功能就得改接口，所有 handler 和 mock 都要动。
正确做法是按使用场景拆小接口，并让 handler 依赖最小集：
立即学习“go语言免费学习笔记（深入）”；
- HTTP handler 只依赖
UserGetter（含GetByID、List），不用管删或改 - 后台 job 只依赖
UserDeleter（含DeleteByID、SoftDelete） - 真实 service 实现可同时满足多个接口，但每个接口只对一类调用者负责
这样新增 UserSearcher 不会影响现有 handler 编译或运行，也无需修改任何已有实现。
第三方包接口不匹配时，适配器该放在哪一层？
比如你用了 github.com/go-redis/redis/v9，但它返回的是 *redis.Client，而你的 CacheStore 接口要求 Set(key, value string, ttl time.Duration) error ——直接用它实现会把 Redis 细节泄漏到 domain 或 internal。
适配器必须放在 internal/adapter 或 pkg/adapter，且只导出接口实现，不暴露第三方类型：
- 适配器结构体字段用
*redis.Client，但方法签名完全遵循CacheStore - 绝不把
redis.Client作为返回值或参数暴露给 service 层 - 测试时可轻松替换为内存版
memcache.Adapter，且不引入新 import 循环
如果把适配器逻辑写进 internal/user/cache.go，等于把基础设施耦合进业务模块，后续换缓存方案就得改 service 包，违反「依赖可控」原则。
error 类型变更为何比接口更危险？
接口方法增减至少能被编译器捕获，但 error 是值，errors.Is(err, pkg.ErrNotFound) 这种判断一旦跨包使用，就隐含了对具体 error 实例的强依赖。如果某天你把 pkg.ErrNotFound 改成 errno.New(40401)，而调用方还在用 errors.Is(err, pkg.ErrNotFound)，判断就会失效。
真正安全的向下兼容 error 方式只有一种：
- 所有业务 error 必须通过
errno.Coder接口统一构造，如errno.New(errno.ErrUserNotFound, "user not found") - 调用方只用
errors.Is(err, errno.ErrUserNotFound)或errno.CodeOf(err) == errno.ErrUserNotFound - 绝不在 error 上追加字段、嵌套结构或自定义方法——那会让 error 变成“类”，失去 Go 的轻量本质
这看起来多了一层封装，但它把兼容性从“类型一致性”降维到“整数码一致性”，这才是 Go 式的稳健。
