真正可插拔的认证器接口应定义为Authenticate(context.Context, map[string]string) (string, error)，仅接收原始输入、返回统一用户ID和错误，不绑定协议、不依赖具体HTTP结构、不暴露实现细节，所有解析与验证逻辑封装在各独立子模块实现中。
认证器接口怎么定义才真正可插拔
关键不是写个 Authenticator 接口，而是让它不绑定具体协议、不依赖上下文结构、不泄露实现细节。接口方法必须只接收原始输入（比如 map[string]string 或 http.Header），返回统一的 user.ID 和错误，绝不返回 *jwt.Token 或 oauth2.Token 这类具体类型。
常见错误是把 VerifyToken(string) (*User, error) 写进接口——这等于把 JWT 解析逻辑硬编码进契约里，后续想换成 API Key 或 WebAuthn 就得改接口，破坏兼容性。
- 接口只暴露
Authenticate(context.Context, map[string]string) (string, error)—— 用户 ID 是唯一稳定输出 - 所有解析、签名验证、缓存、刷新逻辑都藏在实现里，接口层看不见
- 避免传入
*http.Request：它耦合了 net/http，换成 gin 或 echo 就得适配器包装
模块如何隔离认证器实现
每个认证器（如 basic、jwt、oidc）应放在独立子模块下，比如 github.com/your/app/auth/basic，且不 import 其他认证器代码。主程序通过接口变量注入，而不是用 init() 注册或全局 map 维护。
容易踩的坑是让多个认证器共享一个 config.Config 结构体——一旦加字段，所有实现都得同步改。正确做法是每个实现只解析自己关心的键：
立即学习“go语言免费学习笔记（深入）”；
-
basic.New(cfg map[string]string)只读cfg["username"]和cfg["password_hash"] -
jwt.New(cfg map[string]string)只读cfg["issuer"]、cfg["jwks_url"]，忽略其他字段 - 主程序启动时按配置加载对应模块，不编译未启用的认证器
运行时如何安全切换认证器
不能靠 if-else 判断类型再调用不同逻辑——那等于把插拔逻辑写死在业务代码里。要用依赖注入容器或工厂函数，让调用方完全感知不到实现变化。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
示例：主服务初始化时从环境变量读取 AUTH_TYPE=jwt，然后调用 auth.New("jwt", cfg)。这个 New 函数是注册表驱动的，内部用 map[string]func(map[string]string) auth.Authenticator 注册各实现，但 map 本身在 auth 模块内，外部不可见。
- 禁止在 handler 里写
if authType == "jwt" { ... } else if authType == "basic" { ... } - 所有认证器实现必须满足同一份单元测试（例如用 table-driven test 验证空输入、无效 token、有效凭据等场景）
- 切换认证器后，中间件
auth.Middleware不需要任何修改，它只依赖接口
为什么 go.mod 里不能直接 replace 认证器模块
开发时想临时替换 github.com/your/app/auth/jwt 为本地调试版？别用 replace。这会让所有依赖该模块的包（包括测试）都看到你的修改，可能意外触发未提交的逻辑，CI 构建也会失败。
真正可控的做法是：让主模块通过 _ 空导入启用特定实现，并用构建标签控制：
import (
_ "github.com/your/app/auth/jwt"
_ "github.com/your/app/auth/basic"
)
然后在 auth/factory.go 里用 //go:build jwt 分条件注册，编译时指定 go build -tags jwt 即可只包含 JWT 实现。
模块版本冲突往往就出在这里——某个第三方库间接依赖旧版 auth/jwt，而你用 replace 强制升级，结果它的 init() 函数行为变了，但没人发现。
