go-zero 是骨架型框架而非可集成中间件，必须从项目初始化就采用其工具链构建服务结构。核心价值在于 goctl 生成的分层架构、配置驱动启动及自动装配能力，强行嵌入现有服务会导致配置冲突、中间件不兼容、功能失效等问题。
go-zero 不是“集成到现有微服务中”的框架，它是一套从项目初始化就决定技术栈走向的骨架型框架。你没法把 go-zero 像中间件一样“加进去”，而是得用它的工具链重写或新建服务结构。这点必须先说清楚。
为什么不能直接“集成”到已有 Golang 微服务？
因为 go-zero 的核心价值不在 runtime 库，而在 goctl 生成的整套分层结构（api/rpc/model）、配置驱动的启动逻辑、以及内置的限流/缓存/链路追踪等能力的自动装配机制。如果你已有服务是手写 net/http + 自定义路由 + 手动管理 Redis/DB 连接，强行塞入 go-zero 的 rest.Server 或 svc.Service 会导致：
- 配置项冲突（比如
rest.RestConf和你原来的yaml解析逻辑打架） - 中间件注册方式不兼容（
engine.Use()vs 你自定义的 handler chain） - 日志、监控、超时控制等能力无法自动生效，需手动桥接，失去“开箱即用”意义
正确做法：用 goctl 初始化新服务或渐进迁移
如果你已有服务需要升级为 go-zero 架构，推荐两种路径：
-
全新服务用
goctl api new xxx或goctl rpc new xxx：这是标准起点。生成的目录结构（internal/handler、internal/logic、internal/svc）强制分离关注点，业务代码只写在logic层，其余由框架接管。 -
老服务渐进替换：保留主入口，逐步将 handler 拆出为
go-zero风格的xxxHandler+xxxLogic，再用goctl生成配套的types和svc.Context。注意：老项目的main.go启动逻辑要替换成rest.NewServer(c.RestConf)，否则配置、限流、自动缓存等功能不会加载。
goctl 生成的代码里哪些必须保留？
不是所有生成文件都能删。以下三类是 go-zero 运行时依赖的关键部分：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
-
etc/xxx.yaml：必须存在，且字段要匹配rest.RestConf或rpc.RpcServerConf结构，否则conf.MustLoad会 panic -
internal/svc/servicecontext.go：所有logic层依赖的上下文对象来源，含 DB/Redis/Config 实例，不可删也不建议手动 new -
internal/handler/*.go中的RegisterHandlers调用：这是把你的 handler 绑定到rest.Engine的唯一入口，漏掉则路由不生效
常见错误：配置加载失败或限流失效
这两个问题几乎都源于同一原因：没走 conf.MustLoad + rest.NewServer 这条主干链路。典型表现：
-
panic: config file not found：说明你在main.go里用了flag或硬编码路径读配置，而不是用conf.MustLoad("etc/xxx.yaml", &c) -
@server(注解里的limit或cache不生效：因为这些注解只在goctl生成代码时解析并注入 middleware，运行时不会动态扫描 struct tag - Redis 缓存没命中：检查
internal/model/xxxmodel.go是否调用了s.cache.Set(...)，且svc.ServiceContext中的cachedConn是否已正确初始化（由etc/xxx.yaml中的Cache字段驱动）
真正麻烦的不是写代码，而是接受它“不让你自由发挥”的设计哲学——go-zero 的强约束，恰恰是它稳定和可维护的来源。一旦绕过 goctl 生成的骨架去手写，就等于放弃了它最核心的价值。
