定位
go-zero 是国内的微服务框架，核心不是「写 HTTP 接口」，而是用代码生成把一套微服务骨架搭起来：.api 文件描述接口，goctl 生成 handler / logic / model 三层代码，配套限流、熔断、缓存、链路追踪。
它不是 Web 框架，是工程脚手架。
安装
# 安装 goctl（代码生成工具）
go install github.com/zeromicro/go-zero/tools/goctl@latest
1. 验证
goctl --version
从 .api 到可运行服务
1. 写接口描述
user.api：
syntax = "v1"
type UserReq {
Id int64 `path:"id"`
}
type UserResp {
Id int64 `json:"id"`
Name string `json:"name"`
}
service user-api {
@handler GetUser
get /users/:id (UserReq) returns (UserResp)
}
2. 生成代码
goctl api go -api user.api -dir .
生成的结构：
.
├── etc/user-api.yaml # 配置文件
├── internal/
│ ├── config/config.go # 配置结构体
│ ├── handler/getuserhandler.go # HTTP 层，只做参数解析
│ ├── logic/getuserlogic.go # 业务逻辑，你在这里写代码
│ ├── svc/servicecontext.go # 依赖注入容器
│ └── types/types.go # 请求响应结构
└── user.go # 入口
关键：handler 和 types 是生成物，重新生成会覆盖；logic 不会覆盖，业务代码安全。
3. 写业务逻辑
// internal/logic/getuserlogic.go
func (l *GetUserLogic) GetUser(req *types.UserReq) (*types.UserResp, error) {
user, err := l.svcCtx.UserModel.FindOne(l.ctx, req.Id)
if err != nil {
return nil, err
}
return &types.UserResp{Id: user.Id, Name: user.Name}, nil
}
4. 生成 Model
goctl model mysql datasource
-url "user:pass@tcp(127.0.0.1:3306)/demo"
-table "user" -dir ./internal/model
生成带缓存的 CRUD（FindOne 会自动走 Redis，如果配置了的话）。
核心概念
1. 三层结构强制分离
handler（协议转换）→ logic（业务）→ model（数据）。不许跨层调用，这是 go-zero 的硬约定。
好处是职责清晰、好测试。坏处是你不能按自己的方式组织代码。
2. 内置服务治理
配置里加上就能用：
Name: user-api
Host: 0.0.0.0
Port: 8888
1. 限流
Middlewares:
Breaker: true # 熔断
Shedding: true # 自适应降载
Timeout: true
1. 链路追踪
Telemetry:
Name: user-api
Endpoint: http://jaeger:14268/api/traces
这些在 Spring Cloud 里要装好几个组件，go-zero 是配置项。
3. RPC 与 API 分离
go-zero 区分两种服务：
api服务：对外 HTTPrpc服务：内部 gRPC（.proto描述，goctl rpc protoc生成）
微服务之间走 RPC，对外走 HTTP。这是它和 Gin/Echo 最本质的区别。
常见坑
① 单机项目别用
go-zero 的默认架构假设你有注册中心、配置中心。一个人写个小服务，会被 .api 文件、代码生成、目录约定拖慢。
② 生成的 model 缓存有默认行为
配置了 Redis 后，FindOne 会自动缓存。改了数据库但没清缓存，会读到旧数据——这不是 bug，但很坑。
③ 升级 goctl 要重新生成
模板会变。升级后重新生成的代码可能和之前差异很大，要 review。
什么时候选它
- 团队做微服务，需要统一的工程结构
- 需要快速产出大量服务（代码生成的效率优势明显）
- 国内团队，中文文档和社区能帮上忙
不选它的场景：单体应用、小项目、需要高度自定义架构。
一个现实判断
go-zero 的学习成本不低，但它的成本主要不在框架本身，而在微服务这套东西——服务拆分、注册发现、链路追踪、配置管理，这些不管你用哪个框架都要学。
如果项目根本不需要微服务，go-zero 带来的只有复杂度。