kratos v2 升级到 v3 需修改模块路径、接口命名、中间件实现、idl 生成、应用初始化、配置加载及日志格式，否则将导致编译失败或运行时 panic。
将 Kratos v2 项目升级到 v3 需要处理接口契约变更、插件注册方式重构、IDL 生成逻辑调整及默认中间件行为变化，直接替换依赖会导致编译失败或运行时 panic。
核心接口与模块命名空间变更
kratos v3 将原 github.com/go-kratos/kratos/v2 下的大部分核心包移至 v3 路径，且部分接口签名被精简或重命名。
打开 go.mod，将所有 github.com/go-kratos/kratos/v2 替换为 github.com/go-kratos/kratos/v3；注意保留 /v3 后缀，否则 Go 模块解析会失败。
全局搜索 transport.GRPCServerOption → 替换为 grpc.ServerOption；v3 中 transport 层抽象被下沉，transport 包仅保留通用类型定义，具体实现归入 grpc、http 等子包。
【必须同步更新】 所有自定义中间件若实现了 transport.Middleware 接口，需改为实现 middleware.Handler（位于 github.com/go-kratos/kratos/v3/middleware），旧接口已删除，不改则编译报错。
IDL 生成器与 Protobuf 插件升级
v3 使用新版 protoc-gen-go-kratos，不再兼容 v2 的生成逻辑。旧版生成的 xxx.pb.go 和 xxx_http.pb.go 文件必须全部删除，重新生成。
方法一：使用新 CLI 工具链
执行 go install github.com/go-kratos/kratos/cmd/kratos@latest 安装 v3 版本 kratos CLI；确认 kratos -v 输出含 v3 字样。
执行 kratos proto client api/api.proto → 生成 v3 兼容的 Go 客户端代码；该命令会自动调用适配的 protoc 插件，无需手动配置 protoc-gen-go-kratos 路径。
方法二：手动调用 protoc（适合 CI 或定制化流程）
下载 v3 对应的插件：go install github.com/go-kratos/kratos/cmd/protoc-gen-go-kratos@latest；
运行：protoc --go-kratos_out=paths=source_relative:. --go-kratos_opt=mode=server api/api.proto；注意 --go-kratos_opt=mode=server 是必需参数，缺失会导致 HTTP 路由注册失败。
服务启动与中间件注册方式重构
v3 废弃了 v2 中基于 app.New 的链式配置方式，改为显式构建 App 实例并传入生命周期钩子。
第一步：替换应用初始化代码
将原 v2 写法：
app := kratos.New( kratos.Name("user"), kratos.Version("v1.0.0"), kratos.Server(grpcServer, httpServer),)
改为 v3 写法：
app := kratos.New( kratos.Name("user"), kratos.Version("v1.0.0"), kratos.Server(grpcServer, httpServer), kratos.BeforeStart(func(ctx context.Context) error { return initDB(ctx) }),)
第二步：中间件注册位置前移
v2 中可在 http.Server 构建时通过 http.WithMiddleware 注册；v3 要求所有中间件必须在 http.NewServer 之前完成注册，否则不会生效。
错误写法：http.NewServer(http.WithMiddleware(m1, m2)) → 中间件未绑定到路由树；
正确写法：srv := http.NewServer() → srv.Use(m1, m2) → srv.Handle("/users", userHandler)；
【关键差异】 v3 的 Use 方法是实例方法而非选项函数，必须在 Handle 前调用，顺序错误将导致中间件静默失效。
配置中心与日志默认行为调整
v3 移除了对 conf 包中 Source 接口的隐式依赖，所有配置加载必须显式调用 conf.Load 并传入解析器。
将原 v2 的 c := conf.New(conf.WithSource(source)) 改为：
c := conf.New(conf.WithSource(source))if err := c.Load(); err != nil { log.Fatal(err)}
v3 默认启用结构化日志输出（JSON 格式），若项目依赖文本日志做日志采集，需显式覆盖：
logger := log.With(log.NewStdLogger(os.Stdout), "ts", log.DefaultTimestamp)log.SetLogger(logger)
这一步不做会导致日志字段无法被 Filebeat 或 Fluent Bit 正确解析。
