答案是go version和goproxy必须优先确认。需确保go version ≥ 1.21以支持泛型、embed等特性，并配置goproxy=https://goproxy.cn,direct避免国内依赖下载失败，否则后续go mod init、tidy及编译均会卡住。
go mod init 不是起点，go version 才是第一道门槛——没锁死 Go 1.21+ 和 GOPROXY，后续所有步骤都会卡在依赖下载或泛型编译上。
go version 和 GOPROXY 必须先敲定
很多人卡在第一步不是因为不会写代码，而是环境没“验明正身”。系统包管理器装的 Go（比如 Ubuntu 自带的 1.18）不支持 embed、泛型约束收敛、module checksum 稳定性，微服务一跑就报错 cannot use type parameter 或 checksum mismatch。
- 去 https://www.php.cn/link/81836b7cd16991abb7febfd7832927fd 下载
go1.21.6.linux-amd64.tar.gz（或对应 macOS/Windows 版本），解压到/usr/local/go - 把
/usr/local/go/bin加进$PATH，然后source ~/.zshrc（或~/.bashrc） - 立刻执行：
go env -w GOPROXY=https://goproxy.cn,direct—— 不加这句，go mod tidy在国内基本无限挂起 - 验证：
go version输出必须含go1.21.6或更高；go env GOPROXY应返回https://goproxy.cn,direct
目录结构不是“怎么好看”，而是“怎么不崩”
从空文件夹里 go mod init mysvc 然后扔个 main.go，等于给三个月后的自己埋雷。K8s 里健康检查失败、日志查不到 trace_id、CI 构建时找不到 internal/service 包——全因目录没按最小契约切分。
- 强制建立五层骨架：
cmd/（只放启动入口）、internal/（业务逻辑，禁止跨服务 import）、pkg/（可复用工具）、api/（.proto文件）、configs/（app.yaml） -
cmd/my-svc/main.go里只做三件事：加载viper配置、初始化zap日志、调用gin.New()或grpc.NewServer() - 别用
github.com/yourorg/backend/user这类路径——模块名必须是域名前缀，如yourcompany.com/authn，否则后期多服务联调时包冲突无法 resolve
HTTP server 启动方式决定你能不能上线
用 gin.Default().Run(":8080") 能跑通，但上线后会被 Kubernetes 的 livenessProbe 反复杀掉。根本原因是没控制连接生命周期，也没预留优雅退出入口。
- 必须显式构造
http.Server，设ReadTimeout（建议 5s）、WriteTimeout（建议 10s）、IdleTimeout（建议 30s） -
/healthz端点必须裸奔：不走任何中间件（包括 logger、recovery、auth）、不查 DB、不调下游，只返回200 OK+ 纯文本ok - 所有 handler 入口第一行写
ctx := r.Context()，后续 DB 查询用db.QueryContext(ctx, ...)，HTTP 调用用client.Do(req.WithContext(ctx))，否则请求取消后 goroutine 会继续跑
配置和日志不是“锦上添花”，是调试命脉
没 viper，你就得硬编码端口、DB 地址，开发/测试/生产环境切一次改十处；没 zap，K8s 里查个超时问题得翻三台机器的日志，字段还全是 log.Printf("user %v not found") 这种没法过滤的字符串。
-
viper必须同时支持configs/app.yaml+ 环境变量覆盖（如APP_ENV=prod），开发时开viper.WatchConfig()实现热重载 -
zap必须用zap.NewProduction()输出 JSON，字段至少含level、ts、caller、trace_id；别碰log.Printf，它没法对接 Loki 或 ELK - 错误包装必须用
fmt.Errorf("failed to get user: %w", err)，判空用errors.Is(err, sql.ErrNoRows)，别用strings.Contains(err.Error(), "no rows")
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
