Go-Zero 不是可插拔库，而是需从初始化即采用的骨架框架；其核心在于 goctl 基于 .api 文件驱动的分层结构（api/rpc/model）、配置驱动开发及自动生成路由/Handler/Logic/Service 全流程，无法在 Gin/Beego 等现有项目中无缝接入。
Go-Zero 不是“集成进来”的库，而是从项目初始化就决定的骨架——你得用 goctl 生成整个结构，而不是后期往现有项目里塞。
为什么不能在已有 Gin/Beego 项目中“接入” Go-Zero
Go-Zero 的核心价值不在某个中间件或组件，而在它强制的分层结构（api/rpc/model）、配置驱动开发模式、以及 goctl 对 API 定义文件（.api）的全程代码生成能力。你如果已有路由和 handler，再想套 Go-Zero 的 handler + logic + svc 分离逻辑，等于重写一半业务。
- 所有 HTTP 路由、参数绑定、响应封装都由
goctl根据.api文件生成，不手写http.HandleFunc -
logic层默认依赖svc.ServiceContext，而该上下文由框架在启动时注入，Gin 中没有等价生命周期管理 - 限流、熔断、JWT 鉴权等能力是通过
middleware链在生成的handler中自动插入的，不是独立可拔插的包
正确起步：用 goctl api new 初始化服务
这是唯一被官方支持且稳定的工作流。别跳过这步，哪怕只是试跑。
- 确保已安装
goctl：go install github.com/zeromicro/go-zero/tools/goctl@latest - 新建目录并初始化：
goctl api new user-api—— 这会生成完整骨架，含etc/配置、internal/分层、user-api.api定义文件 - 编辑
user-api.api，定义第一个接口，例如：type LoginReq { Username string `json:"username"` Password string `json:"password"` } type LoginResp { Token string `json:"token"` } service UserApi { @handler LoginHandler post /login (LoginReq) returns (LoginResp) } - 重新生成代码：
goctl api go -api user-api.api -dir .，它会覆盖internal下对应文件，但保留你手动改过的logic内容（只要没动函数签名）
RPC 服务与 API 网关如何通信：ETCD + gRPC + WithInsecure()
本地开发时最常卡在这一步：API 服务起得起来，但一调 RPC 就报 connection refused 或 transport: authentication handshake failed。
立即学习“go语言免费学习笔记（深入）”；
- 客户端初始化必须显式禁用 TLS：
client := NewUserClient("user-rpc", etcdConf, client.WithNonBlock(), client.WithInsecure()) - 服务端
server.NewServer也得加server.WithInsecure()，否则 gRPC 握手失败 - 注册中心地址别写
localhost—— Docker 容器内解析不了，改用宿主机 IP（如192.168.1.100:2379）或host.docker.internal:2379（macOS/Windows Docker Desktop 支持，Linux 需手动加--add-host） - RPC 服务启动后，先检查 ETCD 是否真有 key：
etcdctl get --prefix "" | grep user-rpc，没输出说明注册失败
缓存、数据库、配置这些“开箱即用”能力怎么启用
它们不是自动生效的，得在生成的代码里显式调用，且依赖配置项开关。
- Redis 缓存需在
etc/user-api.yaml中配置Cache:段，并在logic层用c.svc.Redis调用；若没配，c.svc.Redis是 nil，直接 panic - MySQL 查询走缓存的前提是：model 层用了
sqlx.NewMysql+cache.NewNode组合，且 SQL 语句带/*+ cache */注释（goctl model生成的代码默认已加） - JWT 鉴权由
jwt.Middleware自动注入，但密钥必须在etc/user-api.yaml的Auth.Secret字段填对，否则所有带@handler的路由返回 401 - 限流开关在
etc/user-api.yaml的RateLimit:下，设为true后，每个路由会按MaxQps限制，不配或配错会导致请求被静默丢弃
最容易被忽略的是：所有这些能力都绑定在 svc.ServiceContext 上，而它只在 internal/server.go 的 svc.NewServiceContext 中初始化一次。如果你在 logic 里绕过它自己 new 一个 Redis 客户端，就脱离了框架的连接池和错误统计体系。
