goos/goarch 是编译期硬约束，决定abi、系统调用和内存对齐；需禁用cgo、按平台选准arch、适配国产指令集；proto是服务契约唯一权威，字段变更须同步生成代码，流式接口严禁阻塞操作。
GOOS/GOARCH 不是“选配”，是交付前提
如果你还在用 Docker 多阶段构建来“模拟”跨平台，那你的交付链路已经落后了。Go 的 GOOS 和 GOARCH 是编译期硬约束，不是运行时兼容层——它直接决定生成文件的 ABI、系统调用入口和内存对齐方式。go build 一条命令就能产出 Windows 的 PE、Linux 的静态 ELF、macOS 的 Mach-O，甚至麒麟 V10 ARM64 上可直接执行的二进制。
常见错误现象：
-
build constraints exclude all Go files：源码里用了// +build linux或runtime.GOOS == "windows"，但没配合对应构建标签或条件编译文件 - 在 macOS 上交叉编译出的
linux/amd64二进制，在 CentOS 7 启动报version `GLIBC_2.25' not found：Go 默认静态链接，但若引入了 cgo 且未设CGO_ENABLED=0，就会动态依赖 glibc
实操建议：
- 强制关闭 cgo：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app-linux - ARM 设备部署前务必验证指令集：
GOARCH=arm64≠GOARCH=arm（后者默认为 armv6，树莓派 Zero 需要；Jetson Nano 必须用arm64） - 国产平台别硬套通用值：龙芯 LoongArch 要用
GOOS=linux GOARCH=loong64，申威 SW64 对应sw64，这些在 Go 1.21+ 原生支持
gRPC 接口定义必须早于代码，且不可 runtime 修改
Protocol Buffers 不是“序列化工具”，它是服务契约的唯一权威来源。一旦 .proto 文件发布，所有语言客户端和服务端都必须严格遵循——包括字段编号、是否 optional、default 值语义。你不能靠 Go struct tag 来绕过它。
容易踩的坑：
- 在
.proto中把string name = 1;改成optional string name = 1;，但没升级客户端生成代码：旧版 Go client 解析会 panic，因为name字段从非指针变成指针类型 - 用
oneof定义消息变体，却在服务端逻辑里用switch v.(type)判断，结果 runtime 类型断言失败——protobuf 生成的 Go 代码不导出具体子类型，必须用 generated 的XXX_MessageName方法
实操建议：
- 所有 proto 文件纳入 Git，并与 API 版本号绑定（如
v1/user.proto），禁止在 master 分支直接修改已发布版本 - 生成代码必须走 CI 自动化：
protoc --go_out=. --go-grpc_out=. proto/v1/*.proto，且go mod vendor前校验生成文件哈希 - 流式接口（
stream）不要在 handler 里做阻塞操作：gRPC 流的 context 取消是瞬时的，time.Sleep或数据库慢查询会导致整个 stream 卡死，必须用select { case 主动监听
go-zero 的 goctl 不是代码生成器，是架构约束引擎
goctl 生成的目录结构（api/、internal/handler/、internal/logic/）不是模板套路，而是强制分层边界。它把 HTTP 路由、参数绑定、中间件注入全部收口到 handler 层，业务逻辑只能写在 logic，而 svc 层只允许注入依赖（DB、Redis、RPC client），不允许任何业务判断。
典型误用场景：
- 在
handler里直接调用db.QueryRow：违反分层，导致无法统一加 trace、metrics、panic recover - 把 JWT 解析逻辑写进
logic：认证是 transport 层职责，logic应只接收已校验的uid和role - 用
goctl api new初始化后，手动删掉etc/目录改用 viper 加载配置：go-zero 的conf.MustLoad依赖固定路径和结构，破坏后会导致svc.NewService初始化失败
实操建议：
- 所有外部依赖（MySQL、Redis、gRPC client）必须通过
svc.ServiceContext注入，禁止在logic里 new 实例 - API 定义（
.api文件）要写清楚@handler名称和@server路径，否则goctl生成的路由注册会漏掉 endpoint - 热重载用
air时，必须配置.air.toml忽略gen/和proto/目录，否则每次 proto 修改都会触发全量 rebuild，卡住开发流
日志和指标不是“上线后补”，必须嵌入服务骨架
微服务没有单体那种全局日志文件。每个服务输出的日志必须自带 trace_id、service_name、host、http_status 等维度，否则在 50+ 个服务组成的调用链里，你连哪条请求失败都定位不到。
现实问题：
- 用
log.Printf打日志，结果 ELK 里搜不到user_id字段：原始日志是纯文本，没结构化，字段无法提取和聚合 - 监控只看 CPU 和内存，但某次促销期间
http_server_req_duration_seconds_bucket的 99% 分位飙升到 8s，而 CPU 仍低于 30%：说明瓶颈在下游 RPC 超时或 DB 锁表，但没埋点就只能盲猜
实操建议：
- 初始化 logger 必须用结构化输出：
logx.WithContext(ctx).Infof("user login success, uid: %d", uid)，go-zero 的logx会自动注入 trace_id - HTTP handler 入口统一加 middleware 记录耗时：
promhttp.InstrumentHandlerDuration(...)，指标名必须含 service 和 endpoint，例如user_api_login_latency_seconds - 异常不要吞掉：
if err != nil { logx.WithError(err).Errorf("failed to query user") }，且 error 必须带上下文（比如fmt.Errorf("query user by id %d: %w", id, err)），否则堆栈丢失
真正的难点不在工具链，而在每个服务启动时，是否把 trace_id 注入 context 并贯穿全程；不在要不要打日志，而在每条日志是否能被下游系统按 service_name + status_code + duration 三个维度实时切片分析。这一步漏掉，后面所有监控、告警、压测都是空中楼阁。
