gRPC是Go微服务跨模块调用的默认选择，因其通过.proto契约强制类型校验，天然支持context透传、流控、metadata携带traceID等生产必备能力。
gRPC 是跨模块调用的默认选择，不是因为简单，而是因为必须
Go 微服务里两个模块（比如 order 和 user）之间要通信，直接用 http.Get 或手写 JSON 请求，短期能跑通，长期必出问题：字段名大小写错、int64 被截断、错误码无法统一识别、超时控制失效。gRPC 用 .proto 定义契约，生成代码强制类型校验，天然支持 context 透传、流控、metadata 携带 traceID——这些不是“加分项”，是生产环境存活的基本条件。
实操建议：
- 所有服务共用一个
api/目录存放*.proto文件，由 CI 执行protoc --go_out=. --go-grpc_out=. api/*.proto生成 stub - 服务端必须显式配置
grpc.KeepaliveParams，否则在 Kubernetes + Istio 环境下连接会被静默断开 - 客户端不要复用
grpc.Dial返回的*grpc.ClientConn跨 goroutine 写入；应封装为单例或通过依赖注入传递 - 错误必须用
status.Errorf(code, msg)构造，禁止用errors.New，否则下游无法用status.Code(err)解析
HTTP 调用只适用于对外暴露或临时桥接，内部模块间慎用
如果你的 payment 模块要调 user 模块，且两者都是 Go 编写的内部服务，走 HTTP 就等于主动放弃编译期检查、取消能力、链路追踪起点。常见静默失败场景包括：json.Unmarshal 把空字符串解析成 struct 零值、int64 字段被 JavaScript 安全整数范围截断、没设 timeout 导致 goroutine 泄漏。
如果非用不可：
立即学习“go语言免费学习笔记（深入）”；
- 始终基于
http.DefaultClient改写，设置Timeout，且该值不能超过上游context.Deadline - 用
jsoniter.ConfigCompatibleWithStandardLibrary替代标准encoding/json，它对空字符串、NaN 更鲁棒 - 禁止在请求体中传
map[string]interface{}；必须定义明确 struct，并导出字段（首字母大写） - 若需 OpenAPI 兼容，用
oapi-codegen从openapi.yaml生成 client，别手写http.NewRequest
Context 必须贯穿整个调用链，否则链路就断了
很多团队在 gateway 层加了 X-Request-ID，却没把该 ID 注入到下游 gRPC 的 metadata 里，结果 Jaeger 里只看到第一个 span。跨模块调用不是发个请求就完事，context 是唯一能携带 traceID、deadline、cancel signal 的载体。
正确做法：
- 服务 A 在调用服务 B 前，用
metadata.AppendToOutgoingContext(ctx, "trace-id", traceID)注入 - 服务 B 的 handler 中用
metadata.FromIncomingContext(ctx)提取并写入日志或传递给下游 - 所有中间件、重试逻辑、超时包装都必须接收并透传
context.Context，不能新建空 context - 网关层若做鉴权或限流，也要把必要 metadata（如
user-id、tenant-id）一并透传
本地模块调用别硬编码路径，用 go.mod replace 管理
开发阶段，order 模块想直接引用本地修改中的 user 模块代码，但又不想发布新版本或 push 到远程仓库。硬改 import 路径（比如改成 ../user）会导致构建失败或 VSCode 无法跳转。
标准解法是在 order/go.mod 中加：
replace github.com/your-org/user => ../user
这样既能保持 import 路径一致（import "github.com/your-org/user"），又能实时使用本地代码。注意：
-
replace只影响当前模块，不影响其他依赖项 - CI 构建时应禁用 replace（通过
GOFLAGS="-mod=readonly"）防止误用本地路径 - VSCode 需要重启 Go language server 才能识别 replace 后的符号跳转
