Go微服务环境必须使用1.21+版本并配置GOPROXY，采用Standard Layout目录结构，集成gRPC/HTTP、Viper配置、Zap日志及Docker Compose联调；Serverless场景下需弃用http.ListenAndServe，仅实现http.Handler接口，禁用viper热重载与动态路径查找，且gRPC不可用，须改用带超时的HTTP客户端。
go 环境必须装 1.21+，否则 net/http 的 Server.ServeHTTP 行为、http.ServeMux 路由匹配逻辑、甚至 context.Context 超时传播都可能出隐性 bug；无服务器（Serverless）微服务接口不是“去掉 server”，而是把 http.Handler 交由平台托管——你只写 handler，不调 http.ListenAndServe。
Go 版本与 GOPROXY 必须手动配，不能依赖系统包管理器
Ubuntu/Debian 的 apt install golang 默认装的是 1.18 或更旧版本，go mod tidy 在 1.20+ 才稳定支持 //go:embed 和 io/fs 路径解析，而 Serverless 场景下常需嵌入静态资源或配置模板。
正确做法是：
• 去 https://go.dev/dl/ 下载 go1.21.6.linux-amd64.tar.gz（或对应平台包）
• sudo tar -C /usr/local -xzf go*.tar.gz
• 在 ~/.zshrc 中加 export PATH=$PATH:/usr/local/go/bin，然后 source ~/.zshrc
• 运行 go env -w GOPROXY=https://goproxy.cn,direct（国内不开这个，go get 会卡在 proxy.golang.org）
• 验证：go version 输出应含 go1.21.6 或更高
Serverless 微服务 ≠ 不写 HTTP server，而是不启动 ListenAndServe
你在本地调试时仍用 net/http，但部署到 AWS Lambda / Cloudflare Workers / Tencent SCF 时，入口函数接收的是平台封装的 Request 和 ResponseWriter，你只需实现 http.Handler 接口。
典型错误：
• 在 main() 里写 http.ListenAndServe(":8080", mux) → 本地能跑，上线就 panic（平台不允许监听端口）
• 把 gin.Engine 当普通对象传给平台 → 多数 Serverless 运行时只认标准 http.Handler，不兼容框架私有生命周期
正确结构：
• 定义一个全局 var Handler http.Handler
• 在 init() 或 main() 初始化路由（如 http.NewServeMux() 或 gin.New().Handler()），赋值给 Handler
• Serverless 入口函数直接调用 Handler.ServeHTTP(w, r)
示例（Cloudflare Workers Go）：
func main() {<br> mux := http.NewServeMux()<br> mux.HandleFunc("/api/users", usersHandler)<br> Handler = mux<br>}
Viper 配置加载必须禁用热重载，且路径要相对可执行文件
Serverless 环境中文件系统是只读的，viper.WatchConfig() 会失败并阻塞初始化；同时 viper.AddConfigPath("./configs") 在打包后很可能找不到目录——因为二进制里没有 ./configs，所有配置应内嵌或通过环境变量注入。
推荐做法：
• 用 os.Getenv("CONFIG_JSON") 读 JSON 字符串，再 viper.ReadConfig(bytes.NewReader([]byte(env)))
• 或用 //go:embed configs/*.yaml + embed.FS，再 viper.AddConfigPath("configs")（注意：embed 路径是编译时确定的，不是运行时路径）
• 绝对不要在 Serverless 函数里调 viper.SetConfigName("app") + viper.ReadInConfig()，它默认去 ./、$HOME/.app 等位置找，全失败
• viper.Get("database.url") 前务必检查 viper.IsSet("database.url")，否则返回空字符串而非 panic，容易埋雷
立即学习“go语言免费学习笔记（深入）”；
gRPC 在 Serverless 上基本不可用，HTTP handler 是唯一稳妥选择
gRPC 依赖长连接、HTTP/2、TLS 握手状态，而 Serverless 平台（Lambda、SCF、Workers）的 HTTP 入口全是 HTTP/1.1 单次 request-response 模型，grpc.DialContext 会立即报 connection refused 或 transport is closing。
如果你真需要跨服务调用：
• 内部服务间通信改用 REST over HTTP，用 &http.Client{Timeout: 5 * time.Second} 显式设超时
• 错误处理必须区分网络错误（errors.Is(err, context.DeadlineExceeded)）、状态码（resp.StatusCode == 404）、业务错误（json.Unmarshal(resp.Body, &errResp)）
• 别用 google.golang.org/grpc 的任何类型（如 status.Code），它们在 HTTP handler 里毫无意义
• 若已有 gRPC 接口，对外暴露时用 grpc-gateway 生成反向代理，但该 proxy 本身仍是 HTTP server —— 它不能直接跑在 Serverless 上，只能作为独立网关服务部署
真正卡住人的点不在代码怎么写，而在你是否意识到：Serverless 微服务的“微”，是指单个 handler 的职责粒度（比如 /api/users/{id} 一个 endpoint 对应一个函数），而不是服务拆分逻辑；所有 internal/、pkg/ 目录照常组织，但 cmd/ 下不再有 main.go 启动 server，只有 handler.go 导出 Handler 变量。
