Go微服务本地开发需分离容器与主机进程：Docker仅运行Consul/Redis/PostgreSQL等中间件，Go服务用主机进程运行；Consul需配置-bind/-client为0.0.0.0，Redis关protected-mode，PostgreSQL开放远程连接；go.mod须显式require所有通信依赖；服务注册地址用127.0.0.1而非localhost；日志与链路ID须在HTTP/gRPC入口注入；调试需加-gcflags="all=-N -l"并配合dlv。
Go 微服务本地开发环境不是搭一个“能跑就行”的容器集合，而是要让 go run、grpcurl、curl、配置热加载、服务发现模拟、日志链路追踪这些环节彼此不打架——否则你花三天调通依赖注入，结果发现 consul agent 没开健康检查，服务根本没注册进去。
用 docker-compose 启动基础中间件，但别让它管 Go 服务本身
本地开发时，把 Go 服务也塞进 docker-compose.yml 会导致编译慢、调试断点失效、环境变量混乱。正确做法是：只用 Docker 跑 consul、redis、postgresql 这类有状态或协议复杂的服务；Go 服务用主机进程运行。
-
consul必须加-client=0.0.0.0和-bind=0.0.0.0，否则 Go 客户端连不上（默认只监听127.0.0.1） -
redis配置里关掉protected-mode yes，否则 Go 的redis.Client会报NOAUTH Authentication required - PostgreSQL 的
pg_hba.conf要加一行：host all all 0.0.0.0/0 md5，不然 Go 的sql.Open("postgres", ...)连接超时
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"
- "8600:8600/udp"
<p>redis:
image: redis:7-alpine
command: ["redis-server", "--protected-mode", "no"]
ports:</p>
- "6379:6379"
postgres: image: postgres:15 environment: POSTGRES_PASSWORD: devpass volumes:
- ./init.sql:/docker-entrypoint-initdb.d/init.sql ports:
- "5432:5432"
go.mod 里必须显式 require 所有微服务间通信依赖
Go 的模块懒加载机制会让 go build 成功，但运行时报 panic: interface conversion: interface {} is nil, not *xxx.ServiceClient——本质是 grpc、kit、fx 等框架的插件未被导入，类型注册缺失。
- 如果你用
go-kit，go.mod里得有：github.com/go-kit/kit v0.12.0（注意不是go-kit/kit/vx，v1 已废弃） - 如果用
gRPC+protoc-gen-go-grpc，必须同时 require：google.golang.org/grpc/cmd/protoc-gen-go-grpc和google.golang.org/grpc，版本需严格对齐（如都用v1.60.0） - 用
uber-go/fx做 DI 时，fx.New()启动失败却无日志？加fx.NopLogger或确保fx.WithLogger传入了非 nil 的 logger 实例
本地服务注册/发现必须绕过 DNS，直连 127.0.0.1:8500
Consul 官方文档建议用 DNS 查询服务地址，但在本地开发中，dig @127.0.0.1 -p 8600 user.service.consul 极易失败——因为 Docker 网络和宿主机 DNS 解析不一致，且 Consul Agent 的 DNS 服务默认不开启健康检查过滤。
- 所有 Go 服务的注册代码里，
Address字段填"127.0.0.1"，不是"localhost"（某些 Linux 发行版下localhost解析到::1，IPv6 会失败） - 服务发现客户端不要用
consul.NewClient(&consul.Config{Address: "localhost:8500"})，改用：consul.NewClient(&consul.Config{Address: "http://127.0.0.1:8500"}) - Consul UI 访问不到？确认启动命令含
-ui，且浏览器访问的是http://127.0.0.1:8500，不是https或带端口重定向
日志与链路 ID 必须在 HTTP/gRPC 入口就注入，不能靠中间件“补”
很多团队在 middleware.Logging 里生成 request_id，结果发现 gRPC 流式响应中日志 ID 错乱、HTTP 重定向后丢失上下文——因为 Go 的 context.Context 是单次传递的，跨 goroutine 不自动继承。
- HTTP 服务：在
http.ServeMux或gin.Engine的最外层 handler 里用req = req.WithContext(context.WithValue(req.Context(), "request_id", uuid.New().String())) - gRPC 服务：实现
grpc.UnaryServerInterceptor，在handler(ctx, req)前注入ctx = context.WithValue(ctx, "trace_id", traceIDFromMetadata(ctx)) - 别用
log.Printf打日志，统一用zerolog.Ctx(ctx).Info().Str("event", "user_created").Send()，否则context.Value里的字段不会输出
最常被忽略的一点：所有服务的 go run main.go 命令必须加 -gcflags="all=-N -l" 才能支持 Delve 断点；而一旦加了这个参数，fx.Invoke 里的函数如果 panic，错误堆栈会丢失原始文件名——这时候得靠 dlv --headless --api-version=2 --accept-multiclient exec ./main -- -debug 启动调试器，并手动设置 configurations 中的 dlvLoadConfig 来展开结构体字段。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
