go微服务设计须以限界上下文命名服务（如authn）、用go mod init初始化、目录按handler/service/model/internal职责分离、http层优先用net/http而非框架、服务间通信强制grpc、结合consul实现带重试的服务发现，并通过context透传与错误包装保障链路可靠性。
别用 go-micro —— 它已归档，go get 直接失败，CI 环境静默崩；也别一上来就拉 go-zero 或 kitex 模板，你连服务边界都没想清，框架只会把你往耦合里拽。
go mod init 是微服务的第一道分水岭
不是写完代码再补模块，而是从第一行命令起就建立服务意识。执行 go mod init authn（不是 go mod init myproject），服务名必须对应限界上下文：比如登录鉴权就叫 authn，头像管理就叫 profile，而不是笼统的 userservice。
常见错误现象：import github.com/yourorg/backend/users 这种路径，暴露了模块未隔离；更糟的是在 handler 里直接调 database/sql，后续加 Redis 缓存或换 gRPC 协议时，得重写一半逻辑。
- 目录按职责切分：
handler/（只做 HTTP 请求/响应转换）、service/（纯业务逻辑，不碰 HTTP 或 DB）、model/（带json:tag 的结构体）、internal/（私有工具，禁止跨服务 import） - 国内务必配
GOPROXY=https://goproxy.cn，否则go mod tidy卡死是常态 -
GO111MODULE=on必须显式开启，避免依赖被 GOPATH 污染
HTTP 层用 net/http 跑通最小闭环，别急着上 Gin
原生 net/http 能让你看清请求生命周期、context 透传和错误链路——这些恰恰是微服务最易出问题的地方。Gin 的中间件和反射隐藏了太多细节，等你发现 ctx.Done() 不触发、日志错乱、超时失效时，已经深陷框架绑定。
使用场景：对外网关、健康检查接口、调试阶段的快速验证。
- 所有 handler 入口统一加
ctx := r.Context()，后续 DB 查询、HTTP client 调用都传这个ctx，才能支持超时控制和链路取消 - 返回错误别直接
http.Error(w, err.Error(), http.StatusInternalServerError)，至少区分http.StatusBadRequest和http.StatusNotFound - 错误包装用
fmt.Errorf("failed to query user: %w", err)，判空用errors.Is(err, sql.ErrNoRows)，别用字符串匹配
服务间通信必须用 gRPC，HTTP 只留作对外入口
用 net/http + JSON 做内部调用，三个月后你会遇到三类硬伤：前端传来的 user_id 是 string，后端解析成 float64；错误码全挤在 HTTP 状态码里，404 到底是资源不存在还是下游超时；没默认连接池，每次都要手写 &http.Client{Transport: ...}。
gRPC 不是“为了高大上”，它是解决这些实际痛点的最小可行方案：字段类型编译期校验、status.Code(err) 直接区分 CodeNotFound 和 CodeDeadlineExceeded、grpc.DialContext 默认带连接复用和健康探测。
- 客户端初始化必须加超时：
ctx, cancel := context.WithTimeout(ctx, 500*time.Millisecond)，否则一个卡死的下游会拖垮整条链路 - 别手动拼
http://service-name:8080，用grpc.WithResolvers配合 Consul resolver，让 DNS 式服务发现生效 - metadata 传 trace-id 必须用
metadata.AppendToOutgoingContext(ctx, "trace-id", id)，不是往 request struct 里塞字段
Docker 里连不上 Consul？90% 是因为写了 localhost
本地跑通的服务，一丢进 Docker 就报 connection refused 或 no route to host，根本原因：容器里 localhost 指自己，不是宿主机。
实操建议：
- 用环境变量注入地址：
CONSUL_ADDR=host.docker.internal:8500（Mac/Win）或CONSUL_ADDR=172.17.0.1:8500（Linux Docker 默认 bridge 网关） - Consul 启动用
consul agent -dev -client=0.0.0.0，开放外部访问 - 注册逻辑里加重试：失败后 sleep 1s 再试，最多 3 次，避免 Consul 没 ready 就注册失败
真正麻烦的从来不是“怎么连上”，而是“连上之后，当 Consul 重启、网络抖动、实例闪退时，你的重试逻辑有没有覆盖所有超时分支”——这点几乎没人提前写。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
