微服务必须从go mod init authn起按限界上下文建模，服务名即模块路径；目录严格分handler/service/model/internal；内部通信强制grpc+consul服务发现；禁止跨服务import internal/；可观测性需上线即具备。
微服务不是“先写代码再拆服务”，而是从 go mod init 那一刻起，就该按服务边界建模——名字不对、目录不隔离、通信协议混用，后面八成要返工。
服务命名与模块初始化必须对应限界上下文
服务名不是随便起的，它直接决定模块路径、包引用和后续运维标识。用 go mod init authn 而不是 go mod init userservice，是因为 “authn” 明确表达了「认证鉴权」这一限界上下文，而 “userservice” 是模糊的业务容器，容易把登录、头像、权限全塞进去。
- 错误现象：
import github.com/yourorg/backend/users—— 路径暴露了未隔离的单体思维，后续加 Redis 缓存或换 gRPC 协议时，handler 层会直接耦合 DB 和网络细节 - 正确做法：每个服务独立仓库，
go mod init github.com/yourorg/authn，所有内部 import 都以该 module 为根 - 兼容性影响：模块名一旦发布到私有 proxy 或 CI 流水线，改名成本极高；Consul 注册的服务名、Docker 镜像 tag、K8s Service 名都应与 module 名对齐
目录结构必须按职责物理隔离，禁止跨服务 import internal/
internal/ 不是“放工具函数的地方”，它是 Go 的编译级访问控制机制——任何跨服务 import internal/xxx 都会在 go build 时报错，这是你防止架构腐化的第一道防线。
- 标准分层：
handler/（只做 HTTP/gRPC 请求/响应转换）、service/（纯业务逻辑，无框架依赖）、model/（带json:和db:tag 的结构体）、internal/（仅本服务可用的加密、重试策略等） - 常见错误：在
handler/里直接调database/sql或 newhttp.Client，导致无法统一注入 context 超时、无法替换为 mock client 做单元测试 - 性能影响：
service/层若不抽象数据访问接口（如UserRepo），就无法在测试时快速切换为内存实现，CI 中集成测试会卡在数据库连接池耗尽
服务间通信必须用 gRPC，HTTP 只留作对外网关
用 net/http + JSON 做内部调用，三个月后你会被三类问题反复打脸：字段类型丢失（前端传 "123"，后端解析成 float64）、错误语义模糊（404 到底是资源不存在还是下游超时？）、连接管理失控（没默认连接池，每次都要手写 &http.Client{Transport: ...}）。
- gRPC 的实际收益：
status.Code(err)直接区分CodeNotFound和CodeDeadlineExceeded；.proto文件强制字段类型和必选约束；grpc.DialContext默认启用连接复用、健康探测和 DNS 式服务发现 - 落地要点：对外 REST 接口不要手写两套逻辑，用
grpc-gateway自动生成反向代理；客户端初始化必须加超时：ctx, cancel := context.WithTimeout(ctx, 500*time.Millisecond) - 容易踩的坑：没配
grpc.WithResolvers，硬编码http://authn:8080，导致服务扩缩容后请求失败；忽略WithBlock()在启动期阻塞等待注册中心就绪，造成 K8s Readiness Probe 失败
服务发现必须与启动生命周期绑定，不能靠配置文件硬写地址
Consul 或 etcd 不是“可选项”，而是服务数量 ≥3 时的生存底线。手动维护 authn.host=10.0.1.12 这类配置，在滚动更新或蓝绿发布时必然出错。
- 关键动作：服务启动时，自动向 Consul 注册自身（含健康检查端点）；调用方通过
resolver动态解析目标服务地址，而非读配置文件 - 参数差异：
grpc.WithResolvers(consul.NewBuilder("authn"))比grpc.WithInsecure()多做的不只是安全，而是让 gRPC 连接池能感知实例上下线，自动剔除不可用节点 - 调试线索：如果
grpc.DialContext返回context deadline exceeded，优先查 Consul UI 确认服务是否注册成功、健康检查是否通过，而不是翻日志找网络超时
最常被跳过的其实是可观测性埋点——没有 trace ID 的日志、没指标的 Prometheus Exporter、没 span 的 OpenTelemetry，等于把服务扔进黑盒。等线上出问题再补，连哪个服务挂了都得靠 curl 猜。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
