go-zero微服务迁移需分阶段解耦渐进替换，核心是业务不中断、风险可回滚、团队能承接；先用DDD识别限界上下文，从读多写少模块入手；对外保持HTTP/JSON兼容，内部逐步切gRPC；数据库须双写+校验，禁用一次性导入；依赖地址须环境变量注入，容器内localhost非宿主机。
go-zero 是目前落地最稳、工具链最全的 Go 微服务框架，但直接“把旧系统重写成 go-zero”是最大误区。迁移不是推倒重来，而是分阶段解耦+渐进替换，核心目标是**业务不中断、风险可回滚、团队能承接**。
先做服务拆分，别急着写代码
旧系统（尤其是 Java 单体或 Spring Cloud 架构）往往边界模糊，硬拆会引发大量跨库事务和循环依赖。必须先用 DDD 方法识别限界上下文：UserContext、OrderContext、PaymentContext 等，每个上下文对应一个未来独立部署的微服务。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 从读多写少、依赖最少的模块入手（如用户资料页、文章列表），这类服务迁移风险低、验证快
- 禁止在初期就拆「订单创建」这类强一致性场景——先保留原单体处理，只把查询能力抽成新服务
- 用
goctl api new user生成骨架后，先空跑注册/健康检查，再接入真实逻辑，避免一上来就卡在数据库或鉴权
API 兼容优先于技术炫技
前端、App、第三方调用方不会因为你用了 gRPC 就改 SDK。老系统对外暴露的是 HTTP/JSON，新服务必须先兼容它，否则上线即故障。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用
go-zero的api项目类型（非rpc）启动，保持原有 endpoint 路径、请求/响应结构、HTTP 状态码 - 鉴权层复用旧系统的 JWT 解析逻辑，别急着换
oauth2或自研 token 体系 - 内部调用才逐步切到 gRPC：
user.rpc→auth.rpc，对外仍走 HTTP，用api层做协议转换
数据库迁移必须双写+校验，不能信“一次性导入”
旧系统数据库往往是 MySQL 主从 + 分库分表，直接 dump 导入新服务的单库会丢数据、乱主键、崩索引。更危险的是，迁移脚本跑完你以为 OK，其实关联字段没同步、时间戳时区错位、text 字段被截断。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 启用双写：新服务写入自身 DB 的同时，通过消息队列（如 Kafka）或本地 binlog 同步关键字段到旧库（仅限读场景）
- 用
golang-migrate/migrate管理新服务的 schema 变更，但绝不用于“从旧库迁移历史数据”——那是 ETL 工具（如gh-ost或自研批量导出程序）的事 - 上线前必跑数据比对：抽样对比
SELECT id, name, updated_at FROM users LIMIT 1000在新旧库的结果是否完全一致（注意时区、NULL 处理）
本地调试通了，Docker 里十有八九连不上注册中心
这是 90% 的新手卡点：代码里写死 http://localhost:8500，本地跑得飞起，一进容器就报 connection refused。容器里的 localhost 指的是自己，不是宿主机。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有外部依赖地址（Consul、MySQL、Redis）必须通过环境变量注入，如
CONSUL_ADDR=consul:8500 - Docker Compose 中定义
consulservice，并确保 Go 服务与它在同一 network 下 - 加一行健康检查：启动时 ping
CONSUL_ADDR的 HTTP 接口，失败则 sleep 重试，别让服务因注册失败直接 exit
time.Now().UTC() vs time.Now().Local()）、空值语义（NULL vs "" vs 0）、以及那些藏在 Java @Transactional 注解下的隐式事务边界。这些细节不会报错，但会让线上数据慢慢歪掉。 
