ubuntu/debian下必须手动安装go 1.21.6+并配置goproxy=https://goproxy.cn,direct，因apt默认安装的go 1.18过旧，会导致go mod失败、泛型和embed不可用；需从https://go.dev/dl/下载二进制包解压至/usr/local/go，配置path和goroot，并验证go version与go mod init/test下载速度。
Go 版本和 GOPROXY 必须手动装，别信系统包管理器
Ubuntu/Debian 的 apt install golang 默认装的是 Go 1.18 或更旧版本，go mod 校验会失败，泛型语法报错，embed 不可用——这不是你的代码问题，是环境不达标。
直接去 https://go.dev/dl/ 下载 go1.21.6.linux-amd64.tar.gz（或对应平台版本），解压到 /usr/local/go；把 /usr/local/go/bin 加进 $PATH，并 source ~/.zshrc（或 ~/.bashrc）；运行 go version 确认输出含 go1.21.6。
go env -w GOPROXY=https://goproxy.cn,direct 这句必须执行，否则 go mod download 在国内基本卡死。验证方式：随便建个空目录，跑 go mod init test && go get github.com/spf13/viper，5 秒内完成才算通。
go mod init 后立刻建 Standard Layout 目录结构
别在 go mod init yourcompany.com/order-svc 后直接写 main.go。微服务启动就依赖配置加载、日志初始化、服务注册，这些逻辑塞进单文件里，后期改一个字段就要动三处。
强制建立以下骨架：
-
cmd/order-svc/main.go：只做三件事——viper.ReadInConfig()、zap.NewProduction()、grpc.NewServer()或gin.Default()启动 -
internal/service/和internal/handler/：放所有业务逻辑，禁止跨层引用（比如handler不能直接 importmodel） -
configs/app.yaml：定义http.port、db.host等，配合viper.AutomaticEnv()读取环境变量时注意键名转小写加点（DB_PORT→db.port） -
api/：放.proto文件，后续用protoc生成 stub，别手写 gRPC 接口
Dockerfile 多阶段构建必须关 CGO_ENABLED=0 且用 linux GOOS
本地 macOS 或 Windows 构建时漏设 GOOS=linux，镜像一跑就报 exec format error；不设 CGO_ENABLED=0，Alpine 镜像里缺 libc，启动直接 no such file or directory。
Go语言（Golang）1.26.0版本提供 Go 官方 Windows amd64 MSI 安装包下载入口，版本号 1.26.0，可用于旧项目维护、兼容性测试和指定版本开发环境配置。
标准写法：
FROM golang:1.22-alpine AS builder WORKDIR /app COPY go.mod go.sum ./ RUN go mod download COPY . . RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" -o main ./cmd/order-svc FROM alpine:latest RUN apk --no-cache add ca-certificates WORKDIR /root/ COPY --from=builder /app/main . EXPOSE 8080 CMD ["./main"]
关键点：
- 第二阶段不要用
golang:alpine运行，那会带上几百 MB 编译环境 -
EXPOSE 8080只是文档声明，真正生效靠 Go 程序监听0.0.0.0:8080（不是127.0.0.1） - 健康检查探针要用
wget而非curl，Alpine 默认没装curl
docker-compose.yml 里中间件要显式放开绑定地址
Consul 默认只监听 127.0.0.1，Go 客户端连不上；Redis 开着 protected-mode yes，报 NOAUTH Authentication required；PostgreSQL 没改 pg_hba.conf，连接超时但日志只写 database system is shut down。
正确配置片段：
version: '3.8'
services:
consul:
image: consul:1.16
command: agent -dev -client=0.0.0.0 -bind=0.0.0.0 -ui -log-level=warn
ports: ["8500:8500"]
redis:
image: redis:7-alpine
command: ["redis-server", "--protected-mode", "no"]
ports: ["6379:6379"]
postgres:
image: postgres:15
environment: POSTGRES_PASSWORD=devpass
ports: ["5432:5432"]
Go 服务本身别塞进 docker-compose —— 本地开发用主机进程跑，方便 delve 断点、热重载、改 .env 立即生效；Docker 只管中间件，职责清晰。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
