release-v0.5.1

[0.5.1] - 2026-09-17

Changed

• 将 CLI 与新服务模板使用的 protoc-gen-grpc-gateway、protoc-gen-openapiv2 和 Docker include 源升级到 v2.30.0，生成项目的 grpc-gateway runtime 依赖同步升级到 v2.30.0 与 grpc-kit/pkg v0.5.1（含 OTel v1.45.0、gRPC v1.83.2）：v2.30.0 要求的 otelgrpc v0.70.0 删除了 pkg v0.5.0 仍使用的 StreamClientInterceptor，runtime 升级以 pkg v0.5.1 完成向 stats handler 的迁移为前提；CI 模板门禁的生成工具安装同步对齐 v2.30.0。

• grpc-kit/pkg v0.5.1：客户端 OpenTelemetry 接入从已被上游移除的 otelgrpc.StreamClientInterceptor() 迁移到 grpc.WithStatsHandler(otelgrpc.NewClientHandler(...))，装配点统一收敛到 LocalConfig.GetClientDialOption()；依赖对齐 grpc-gateway v2.30.0、otelgrpc/otelhttp v0.70.0 与 OpenTelemetry Go v1.45.0，并升级 google.golang.org/grpc v1.83.2 修复 GO-2026-6443 server panic（govulncheck 符号级命中 rpc.StartBackground 调用链）。

  1. 客户端遥测覆盖面扩大：普通客户端 unary RPC 与 grpc-gateway 到 gRPC Server 的内部调用新增 OTel client span/metric，streaming client 改由同一 stats handler 观测；unary/stream 共用 grpcTracingEnableFilter，HealthCheck 与配置命中的方法在 client 侧同样被过滤；observability 关闭时不装配框架 OTel client handler
  2. 调用方自定义 stats handler 与框架 handler 可共存（grpc v1.83.x 的 WithStatsHandler 为追加语义），应避免再注册另一个 otelgrpc.NewClientHandler() 产生重复 span/metric
  3. GetClientStreamInterceptor() 保留为通用流拦截器扩展入口且未废弃，但默认不再返回 OTel interceptor；只调用该方法、不使用 GetClientDialOption() 的外部项目在 otelgrpc v0.70.0 依赖图下无法编译，需改用 GetClientDialOption()
  4. OTel 依赖族对齐到 v1.45.0/v0.70.0 一代：contrib/instrumentation/runtime v0.70.0、otlp exporters（5 个）v1.45.0、stdoutmetric v1.45.0、exporters/prometheus v0.67.0（连带 prometheus/client_golang v1.24.1）；go 指令保持 1.25.13
  5. govulncheck 符号级漏洞清零；未调用级漏洞随间接依赖升级修复 x/mod v0.40.0（GO-2026-6180/6179）、oras-go v2.6.2（GO-2026-5880）、go-ntlmssp v0.1.1（GO-2026-5543），x/crypto（GO-2026-6355/6354，修复版要求 go 1.26）、etcd/client/pkg（GO-2026-6107，修复需 v3.5.33）与上游暂无修复版的 GO-2026-5932 留待后续版本处理

• project migrate 的迁移目标基线保持 pkg v0.5.0 不变：v0.5.1 被定义为 v0.5.0 的补丁兼容候选，CI 迁移门禁在 v0.5.0 基线之外增加 v0.5.1 候选验证，不改写历史迁移夹具与冻结兼容资产。

• project migrate 将存量项目的 scripts/generate.sh 纳入托管同步：服务模板自本版本起在该文件第二行携带 # Code generated by "grpc-kit-cli/...". DO NOT EDIT. 生成标记（首行保留 shebang）。存量副本没有该标记，迁移以"路径精确 + 全文 SHA-256 匹配冻结历史版本"的内容证据窄例外授权（与 public/embed.go 既有先例同规则），命中 v0.3.8 冻结摘要的副本被整文件改写为最新模板并补上标记；迁移产物与 0.5.1 起新脚手架的 generate.sh 从此携带 marker，后续版本可改用 marker 规则托管。本地修改过或内容不明的副本只输出 generate_script_modified 人工核对提示，不自动覆盖；文件缺失不创建。

Fixed

• 修复 d454cd6 工具链固化迁移遗漏：template/service/scripts/generate.sh.tmpl 第二个 protoc 调用仍单独引用旧安装位置 /usr/local/include，在新工具链（binaries.sh 安装到 ${GOPATH}/include）下第二个 protoc 调用找不到 well-known types。两个 protoc 调用现在统一按 -I "${GOPATH}"/include/（优先）+ -I /usr/local/include/（旧安装位置兜底）的顺序包含双路径，新旧工具链及存量外部 CI 工作流均无需改动；generate.sh 模板同时在第二行新增生成标记。

• 修复服务模板在 protoc-gen-openapiv2 v2.30.0 下生成的 4xx/5xx 公共 ErrorResponse $ref 无法解析的问题：生成脚本启用 allow_merge，显式输入 ${GOPATH}/src/github.com/grpc-kit/api/known/status/v1/response.proto，并将合并后的 microservice.swagger.json 直接输出到 public/openapi/；新增 $ref 完整性与关键公共 schema 回归门禁。

• 该问题的已知版本边界为 grpc-gateway v2.27.5 起；v2.27.4 仅用于说明问题边界，不作为实施或应急回滚方案，模板生成工具升级并固定使用当前 v2.30.0。

• HTTP 路由继续独立维护在 microservice.gateway.yaml，运行时错误响应契约不变；v2.30.0 重新生成的 gateway 代码仅包含上游请求体清理顺序调整，并已由生成项目与 gochat 测试覆盖。官方 protoc-gen-openapiv3 当前不读取该外部配置，因此 OpenAPI v3 条件生成延后，不随本次修复发布。