基于 go-zero 框架的微服务启动脚手架，开箱即用。
Client ──HTTP──> User API (REST) ──gRPC──> User RPC (gRPC) ──> MySQL / Redis
└──> Kafka
User MQ Consumer <──────────── Kafka
技术栈:
- 框架: go-zero v1.9+
- 数据库: MySQL 8.0 + GORM
- 缓存: Redis 7
- 服务发现: Etcd 3.5
- 消息队列: Kafka
- 监控: Prometheus + Grafana
- CI/CD: GitHub Actions
├── app/ # 应用服务
│ └── user/ # 用户服务
│ ├── api/ # HTTP API 网关 (端口 8888)
│ ├── rpc/ # gRPC 服务 (端口 8080)
│ └── mq/ # Kafka 消费者
├── common/ # 公共组件
│ ├── errorx/ # 统一错误码
│ ├── response/ # 统一响应格式
│ ├── middleware/ # HTTP 中间件 (CORS, 日志)
│ ├── interceptor/ # gRPC 拦截器
│ └── ctxdata/ # JWT 上下文工具
├── model/ # 数据模型 (GORM)
├── deploy/ # 部署配置
│ ├── docker-compose.yml # 本地基础设施
│ ├── mysql/ # 数据库初始化脚本
│ ├── prometheus/ # Prometheus 配置
│ ├── grafana/ # Grafana 数据源和仪表盘
│ └── Dockerfile # 多阶段构建
├── .github/workflows/ # CI/CD
├── doc/swagger/ # API 文档
└── Makefile # 构建脚本
- Go 1.24+
- Docker & Docker Compose
- protoc (Protocol Buffers 编译器)
- protoc-gen-go & protoc-gen-go-grpc
make docker-up这将启动以下服务:
| 服务 | 端口 | 说明 |
|---|---|---|
| MySQL | 3306 | 数据库 (root/123456) |
| Redis | 6379 | 缓存 |
| Etcd | 2379 | 服务发现 |
| Kafka | 9092 | 消息队列 |
| Prometheus | 9090 | 监控指标 |
| Grafana | 3000 | 监控面板 (admin/admin) |
在不同的终端中分别启动：
# 终端 1: 启动 RPC 服务 (需要先启动)
make rpc
# 终端 2: 启动 API 服务
make api
# 终端 3: 启动 MQ 消费者
make mq注册:
curl -X POST http://localhost:8888/api/v1/user/register \
-H "Content-Type: application/json" \
-d '{"username":"testuser","password":"123456","nickname":"Test","email":"test@example.com"}'登录:
curl -X POST http://localhost:8888/api/v1/user/login \
-H "Content-Type: application/json" \
-d '{"username":"testuser","password":"123456"}'获取用户信息 (需要 JWT Token):
curl http://localhost:8888/api/v1/user/info \
-H "Authorization: Bearer <your-token>"Swagger 文档位于 doc/swagger/user.json，可以通过以下方式查看:
- 导入到 Swagger Editor
- 使用 VS Code 的 Swagger Viewer 插件
- 重新生成:
make gen-swagger
make help # 查看所有可用命令
# 构建
make build # 构建所有服务
make build-api # 构建 API 服务
make build-rpc # 构建 RPC 服务
make build-mq # 构建 MQ 消费者
# 运行
make api # 启动 API 服务
make rpc # 启动 RPC 服务
make mq # 启动 MQ 消费者
# 代码生成
make gen-rpc # 从 proto 文件生成 gRPC 代码
make gen-swagger # 生成 Swagger 文档
# Docker
make docker-up # 启动基础设施
make docker-down # 停止基础设施
make docker-clean # 停止并清除所有数据
# 质量
make lint # 运行 golangci-lint
make test # 运行测试
make test-cover # 生成覆盖率报告配置文件位于各服务的 etc/ 目录:
app/user/api/etc/user-api.yaml- API 服务配置app/user/rpc/etc/user-rpc.yaml- RPC 服务配置app/user/mq/etc/user-mq.yaml- MQ 消费者配置
重要: 生产环境部署前，请务必修改以下配置:
- JWT Secret (
Auth.AccessSecret/JwtAuth.AccessSecret) - MySQL 密码 (
Mysql.DSN) - Redis 密码 (
RedisConf.Password)
- 访问 Grafana: http://localhost:3000 (admin/admin)
- 预配置的 Prometheus 数据源已自动加载
- 导入
deploy/grafana/dashboard.json获取预制仪表盘
- 在
app/下创建新的服务目录 (参考app/user/结构) - 定义 proto/api 文件
- 实现 config, svc, logic, handler/server
- 添加配置文件到
etc/ - 更新 Makefile 添加构建/运行目标
- 在 proto/api 文件中添加接口定义
- 重新生成代码 (
make gen-rpc) - 实现新的 logic 文件
- 更新 server/handler 注册新接口
MIT