go mod init 必须指定完整模块路径（如 github.com/yourorg/yourservice），否则导致 import 失败、依赖解析错乱；立即运行 go mod tidy 补全依赖并标记间接依赖，禁止手动编辑 go.sum。
用 go mod 初始化项目并约束依赖版本
云原生项目必须保证构建可重现，go.mod 是唯一可信的依赖锚点。不加 go mod init 直接写代码，后续在 CI 或 Kubernetes 中构建会因隐式依赖失败。
实操建议：
- 初始化时明确指定模块路径，例如
go mod init github.com/yourorg/yourservice，避免后期改名导致 import 路径断裂 - 立即运行
go mod tidy，它会自动补全缺失依赖、剔除未使用项，并把间接依赖（// indirect）显式写入go.mod - 禁止手动编辑
go.sum；若校验失败，先确认是否被篡改，再用go mod download重拉 - 微服务间共用工具包（如
pkg/logger）时，务必用相对路径 import，不要用本地replace指向../common—— 这在 Docker 构建多阶段中会失效
分层目录结构要体现服务边界而非技术类型
常见错误是照搬 Java 的 src/main/java/com/example/controller 套路，把 handler、service、dao 全塞进同一层。Go 项目里，真正的边界是业务域（domain）或服务能力（如 auth、payment），不是 MVC 角色。
推荐结构示例（精简版）：
立即学习“go语言免费学习笔记（深入）”；
├── cmd/ │ └── apiserver/ # 主程序入口，只含 main.go 和 flag 解析 ├── internal/ │ ├── auth/ # 独立业务模块，含 handler + usecase + repo 接口 │ ├── payment/ │ └── pkg/ # 当前服务私有工具，不导出给外部 ├── api/ # protobuf 定义或 OpenAPI spec，供 gRPC/HTTP 共用 ├── config/ # 加载配置（支持 env / file / k8s configmap） └── go.mod
关键点：
-
internal/下的包无法被外部 module import，天然防止耦合泄露 - 每个子目录（如
auth/）应能独立测试、独立部署（未来拆成单独服务时成本最低） - 不要建
models/目录放所有 struct —— 结构体应随使用场景定义：HTTP 请求体放auth/handler/request.go，数据库实体放auth/repo/entity.go，领域模型放auth/domain/user.go
Docker 构建必须用多阶段且禁用 CGO
云原生镜像的核心要求是小、快、确定。用 FROM golang:1.21-alpine 直接跑 go run 是最常见反模式 —— 镜像含完整编译器和调试工具，体积超 300MB，且存在安全风险。
正确做法：
- 第一阶段用
golang:1.21-alpine编译，第二阶段用alpine:latest或scratch运行 - 编译时加
CGO_ENABLED=0，否则二进制会动态链接 libc，在scratch镜像中直接报no such file or directory - 使用
ldflags去除调试符号：go build -a -ldflags '-s -w' -o /app/main . - 暴露端口用
EXPOSE 8080，但别在 Dockerfile 里写HEALTHCHECK—— 应由 Kubernetes 的 livenessProbe 控制，避免容器内嵌健康检查逻辑污染应用职责
启动时必须加载配置并验证必要字段
云原生环境里，配置来自多个源头（环境变量、ConfigMap、Secret、命令行参数），靠硬编码或空指针 panic 是不可接受的。服务启动失败必须在 main() 就暴露，不能等到第一个 HTTP 请求才 panic。
实操要点：
- 用
github.com/spf13/viper或更轻量的github.com/mitchellh/mapstructure统一解析，优先级设为：flag > env > file - 对必填字段（如
DB_URL、JWT_SECRET）做非空校验，失败时打印清晰错误并os.Exit(1)，不要用log.Fatal（它不 flush buffer） - 数据库连接、Redis 客户端等资源初始化必须带超时（例如 5 秒），超时后直接退出，让 Kubernetes 重启容器，而不是卡住等待网络恢复
- 避免在
init()函数里做任何 I/O 操作 —— 它无法被 context 控制，会导致测试难、启动慢、错误难定位
云原生架构里最易被忽略的不是并发或性能，而是“启动即确定性”：从 go run 到容器启动、从本地开发到 K8s rollout，每一步的输入（代码、配置、环境）都必须可追溯、可验证、可中断。一旦某个环节靠“运气”通过（比如本地有 .env 文件而 CI 没有），后面所有可观测性和弹性设计都会失准。
