用泛型结构体+类型参数约束配合嵌入基础服务，可避免为APIv1/v2/v3重复定义结构体；核心是将版本差异抽象为类型参数T，公共行为抽至嵌入字段，T需加字段或方法约束以支持访问，构造函数按版本显式初始化，方法调用需确保接收者为指针且Response等类型已泛型化。
直接说结论：用泛型结构体 + 类型参数约束，配合嵌入基础服务结构体，能彻底避免为 APIv1、APIv2、APIv3 各写一套几乎相同的结构体和方法。
泛型结构体怎么封装多版本 API 公共字段
核心是把「版本差异」抽象成类型参数，把「公共行为」抽到嵌入字段里。比如所有 API 版本都依赖同一个 *Service 实例，但各自有专属配置或响应结构体：
- 不要为每个版本定义独立结构体：
type APIv1 struct { svc *Service; cfg ConfigV1 }、type APIv2 struct { svc *Service; cfg ConfigV2 } - 改用泛型结构体：
type APIService[T any] struct { svc *Service; config T }，其中T代表各版本的配置类型 -
T可以是具体类型（ConfigV1、ConfigV2），也可以是带方法约束的接口（如interface{ Validate() error }）
为什么不能直接用 any 而要用约束
如果泛型参数只用 [T any]，虽然能编译通过，但后续调用 T 的字段或方法时会报错——编译器不知道 T 有没有那个字段。常见错误现象是：cannot select field or method xxx from type T。
- 需要字段访问？加结构体约束：
[T interface{ Endpoint string; Timeout time.Duration }] - 需要调用方法？加接口约束：
[T interface{ Validate() error }] - 想同时支持多种配置类型且保证可比较？用
comparable或自定义约束包（如constraints.Ordered） - 标准库中
golang.org/x/exp/constraints已归档，Go 1.22+ 推荐直接用comparable或写内联接口
构造函数如何适配不同版本的初始化逻辑
泛型结构体本身不带初始化能力，必须靠构造函数补足。关键点在于：构造函数名要体现语义，参数要显式传递版本相关配置，而不是靠全局变量或 init 函数暗中塞值。
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
- 写法正确：
func NewAPIv1(svc *Service, cfg ConfigV1) *APIService[ConfigV1] { return &APIService[ConfigV1]{svc: svc, config: cfg} } - 避免陷阱：不要在泛型结构体内写
func (a *APIService[T]) Init()这类方法——它无法访问T的具体字段，除非你给T加了足够强的约束 - 如果不同版本初始化逻辑差异大（比如 v2 需要额外注册回调），就拆成不同构造函数，别硬塞进一个泛型函数里
- 测试友好性：每个
NewAPIvX都能单独 mocksvc和传入任意cfg，没有全局状态干扰
泛型嵌入后方法调用容易忽略的兼容性问题
当多个 API 版本结构体都嵌入同一个泛型结构体时，看似能复用方法，但实际调用链可能断裂。典型表现是：方法签名里用了 T，但调用方传的是具体类型，编译器无法自动推导。
- 例如：
func (a *APIService[T]) DoRequest(ctx context.Context) (Response[T], error)—— 这里Response[T]必须是已定义的泛型类型，不能是map[string]T这种未约束的组合 - 嵌入时若想让方法“透出”，得确保接收者类型一致：用
*APIService[T]而不是APIService[T]（指针才能绑定方法） - Go 不支持泛型方法重载，所以不要试图在一个泛型结构体里定义
DoRequestV1和DoRequestV2两个同名方法 - 最稳妥的做法：泛型结构体只管状态和基础能力，版本特有逻辑全交给外部函数或独立方法，保持职责清晰
真正难的不是写泛型，而是判断哪些差异该放进类型参数、哪些该留在值层面；一不留神就把约束写得太宽（失去类型安全）或太窄（没法复用）。动手前先列清楚各版本间字段、方法、生命周期的异同点，再决定约束边界。
