go微服务需严守契约、可观测性与容错规范：openapi文档须用swag从注释生成并覆盖参数与响应；grpc必须显式声明go_package和json_name；健康探针应分离依赖检查；日志链路指标须统一trace_id透传；避免共享状态实现真隔离。
Go 本身不强制微服务规范，但用 net/http、grpc-go、go-kit 或 kratos 直接写服务，很容易偏离契约、可观测性、容错等关键要求——核心问题不在“能不能跑”，而在“上线后扛不扛得住”。
如何定义和暴露符合 OpenAPI 3.0 的 HTTP 接口
手写 Swagger 注释或靠生成工具倒推文档，常导致代码与文档脱节。真正稳定的方案是：用 swag init 从 Go 源码注释生成 docs/swagger.json，且注释必须覆盖 @Param、@Success、@Failure 三类。
-
@Param要写清in: path还是in: query，否则前端调用时 400 错误难定位 - 所有
@Success和@Failure必须对应真实返回结构体，不能只写{} - 启动时加
http.Handle("/swagger/", http.StripPrefix("/swagger/", swagger.Handler))，别用内存文件服务，否则 k8s Ingress 无法缓存
为什么 gRPC 接口必须用 proto3 + go_package 显式声明
不写 go_package 会导致生成的 Go 文件包路径混乱，跨服务引用时 import 失败；更严重的是，proto 中字段未加 json_name 会导致 REST 网关（如 grpc-gateway）解析失败。
- 每个
.proto文件顶部必须有option go_package = "github.com/yourorg/service/user/pb"; - 所有 message 字段加
json_name，例如string user_id = 1 [json_name = "user_id"]; - 不要用
optional（proto3 默认就是 optional），否则 gRPC-Web 客户端解析异常
健康检查与就绪探针怎么写才不被 k8s 反复重启
k8s 的 livenessProbe 和 readinessProbe 如果共用一个 handler，会掩盖真实依赖故障。正确做法是拆开：就绪检查只查本地状态（如监听端口是否 bind 成功），存活检查必须包含下游依赖（如 DB 连接、Redis ping）。
- 就绪接口
/readyz返回 200 即可，不查外部依赖 - 存活接口
/healthz必须执行db.PingContext()和redis.Ping()，超时设为 2s，失败立即返回 503 - 两者都加
context.WithTimeout，避免阻塞 probe 导致容器被 kill
日志、链路、指标三者如何对齐 trace_id
用 logrus 或 zap 单独打日志，再用 jaeger 埋点，trace_id 很容易不一致。必须在 HTTP middleware 或 gRPC interceptor 中统一注入上下文，并透传到所有日志和 metric 标签中。
- HTTP 中间件里用
req.Context()提取uber-trace-idheader，存入 context；gRPC 用metadata.FromIncomingContext - 所有
zap.Logger实例通过logger.With(zap.String("trace_id", tid))派生，禁止全局 logger 直接写 - prometheus counter/histogram 的
Labels里必须含trace_id，否则排查慢请求时无法关联日志
微服务不是堆技术栈，而是让每个服务能独立发布、独立扩缩、独立故障隔离。Go 的轻量反而是陷阱——太容易写出“单体拆分假微服务”，比如共享数据库连接池、共用 config struct、没做 circuit breaker 就直连下游。这些细节不落地，服务越拆越难运维。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
