# proxima **Repository Path**: junjun_com/proxima ## Basic Information - **Project Name**: proxima - **Description**: 比邻英语本是 GoFrame 中级实战教程。与初级教程星辰英语本不同，微服务开发是本书的主旋律。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-01 - **Last Updated**: 2026-04-01 ## Categories & Tags **Categories**: Uncategorized **Tags**: Go语言, GoFrame ## README # 比邻英语本 - GoFrame 中级实战教程 基于 GoFrame v2 的微服务架构实战项目，实现用户服务的完整功能，包括 gRPC 服务、Etcd 服务注册发现等。 ## 📚 项目简介 本项目是 GoFrame 中级实战教程，与初级教程"星辰英语本"不同，**微服务开发是本书的主旋律**。项目实现了用户微服务的核心功能，包括： - ✅ gRPC 服务通信 - ✅ Etcd 服务注册与发现 - ✅ Protocol Buffers 接口定义 - ✅ 分层架构设计 - ✅ 数据库操作（MySQL） - ✅ 服务健康检查 ## 🏗️ 项目结构 ``` proxima/ ├── app/ # 应用目录（MonoRepo 结构） │ └── user/ # 用户微服务 │ ├── api/ # gRPC API 定义（自动生成） │ │ ├── account/v1/ # 账户服务 API │ │ └── pbentity/ # 实体定义 │ ├── internal/ # 内部实现 │ │ ├── cmd/ # 命令行入口 │ │ ├── controller/ # 控制器层 │ │ ├── dao/ # 数据访问层 │ │ ├── logic/ # 业务逻辑层 │ │ │ ├── account/ # 账户业务逻辑 │ │ │ └── logic_test.go # 测试文件 │ │ ├── model/ # 数据模型 │ │ │ ├── do/ # Data Object │ │ │ └── entity/ # 实体对象 │ │ ├── packed/ # 打包资源 │ │ └── consts/ # 常量定义 │ ├── manifest/ # 部署配置 │ │ ├── config/ # 配置文件 │ │ │ ├── config.yaml # 主配置 │ │ │ └── etcd.yaml # Etcd 配置 │ │ ├── deploy/ # K8s 部署配置 │ │ ├── docker/ # Docker 配置 │ │ └── protobuf/ # Proto 定义文件 │ ├── main.go # 程序入口 │ ├── Makefile # 构建脚本 │ └── go.mod # 模块依赖 ├── hack/ # 构建脚本 ├── go.mod # 根模块定义 └── README.MD # 项目说明 ``` ## 🚀 快速开始 ### 环境要求 - Go 1.25.0+ - MySQL 5.7+ - Etcd 3.5+ - GoFrame CLI (`go install github.com/gogf/gf/cmd/gf/v2@latest`) ### 安装依赖 ```bash # 安装 Go 模块依赖 cd D:\go_code\proxima go mod tidy # 安装 Protobuf 代码生成插件 go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest ``` ### 配置说明 #### 1. 数据库配置 (`app/user/manifest/config/config.yaml`) ```yaml database: default: link: "mysql:账号：密码@tcp(127.0.0.1:3306)/proxima" debug: true ``` > ⚠️ **注意**: 请将配置中的账号密码替换为你自己的数据库凭证。 #### 2. Etcd 配置 (`app/user/manifest/config/etcd.yaml`) ```yaml etcd: address: "srv.com:2379" ``` #### 3. gRPC 服务配置 (`app/user/manifest/config/config.yaml`) ```yaml grpc: name: "user" address: ":32001" ``` ### 启动服务 ```bash cd D:\go_code\proxima\app\user # 方式 1: 使用 gf 工具（支持热重载） gf run .\main.go # 方式 2: 直接运行 go run main.go # 方式 3: 编译后运行 go build -o user.exe .\user.exe ``` 启动成功后会看到： ``` grpc server started listening on [:32001] ``` ### 运行测试 确保 gRPC 服务已启动，然后运行： ```bash cd D:\go_code\proxima\app\user # 运行所有测试 go test -v ./internal/logic # 运行单个测试 go test -v ./internal/logic -run TestUserRegister go test -v ./internal/logic -run TestUserLogin go test -v ./internal/logic -run TestUserInfo go test -v ./internal/logic -run TestAccountFlow ``` ## 📡 API 接口 ### 服务地址 - **gRPC**: `127.0.0.1:32001` - **服务名**: `account.v1.Account` ### 接口定义 #### 1. 用户注册 (`UserRegister`) ```protobuf rpc UserRegister(UserRegisterReq) returns (UserRegisterRes) ``` **请求参数**: ```json { "username": "oldme", "password": "123456", "email": "tyyn1022@gmail.com" } ``` **响应结果**: ```json { "id": 1 } ``` #### 2. 用户登录 (`UserLogin`) ```protobuf rpc UserLogin(UserLoginReq) returns (UserLoginRes) ``` **请求参数**: ```json { "username": "oldme", "password": "123456" } ``` **响应结果**: ```json { "token": "I am token" } ``` #### 3. 获取用户信息 (`UserInfo`) ```protobuf rpc UserInfo(UserInfoReq) returns (UserInfoRes) ``` **请求参数**: ```json { "token": "I am token" } ``` **响应结果**: ```json { "user": { "Id": 1, "Username": "oldme", "Password": "123456", "Email": "tyyn1022@gmail.com", "CreatedAt": { "seconds": "1733407200", "nanos": 0 }, "UpdatedAt": { "seconds": "1733407200", "nanos": 0 } } } ``` ## 🛠️ 开发指南 ### 代码生成 ```bash # 生成 Protobuf 代码 cd D:\go_code\proxima\app\user gf gen pb # 生成 DAO 层代码 gf gen dao ``` ### 添加新的 gRPC 接口 1. 在 `manifest/protobuf/account/v1/account.proto` 添加接口定义 2. 运行 `gf gen pb` 生成代码 3. 在 `internal/logic/account/account.go` 实现业务逻辑 4. 在 `internal/controller/account/account.go` 注册服务 ### 项目分层说明 - **Controller 层**: 接收 gRPC 请求，参数验证 - **Logic 层**: 业务逻辑处理 - **DAO 层**: 数据库访问操作 - **Model 层**: 数据模型定义（DO、Entity） ## 📦 技术栈 | 技术 | 版本 | 说明 | |------|------|------| | Go | 1.25.0 | 编程语言 | | GoFrame | v2.10.0 | Web 框架 | | gRPC | v1.79.3 | RPC 框架 | | Protobuf | v3.20.3 | 接口定义 | | Etcd | v3.5.17 | 服务注册发现 | | MySQL | 5.7+ | 数据库 | | OpenTelemetry | v1.42.0 | 链路追踪 | ## 🔍 核心知识点 ### 1. gRPC 服务启动 ```go // main.go func main() { var ctx = gctx.New() // 从配置文件读取 etcd 地址 conf, err := g.Cfg("etcd").Get(ctx, "etcd.address") if err != nil { panic(err) } // 注册到 etcd grpcx.Resolver.Register(etcd.New(conf.String())) // 启动服务 cmd.Main.Run(ctx) } ``` ### 2. 服务注册到 Etcd 服务启动时会自动注册到 Etcd，其他服务可以通过服务名发现该服务。 ### 3. 配置管理 使用 GoFrame 的多配置文件机制： - `config.yaml`: 主配置 - `etcd.yaml`: Etcd 配置（通过 `g.Cfg("etcd")` 加载） ### 4. 测试编写 使用 Go 原生 testing 包，通过 gRPC 客户端调用服务： ```go func TestUserRegister(t *testing.T) { ctx := gctx.New() client := getGrpcClient(ctx) req := &v1.UserRegisterReq{ Username: "oldme", Password: "123456", Email: "tyyn1022@gmail.com", } res, err := client.UserRegister(ctx, req) // ... 验证结果 } ``` ## 📝 常见问题 ### 1. 端口被占用 **错误**: `listen tcp :32001: bind: Only one usage of each socket address` **解决**: ```powershell # 查找占用端口的进程 netstat -ano | findstr :32001 # 终止进程 taskkill /F /PID <进程 ID> ``` ### 2. Protobuf 编译失败 **错误**: `protoc-gen-go: Plugin failed with status code 1` **解决**: 安装 Protobuf 插件 ```bash go install google.golang.org/protobuf/cmd/protoc-gen-go@latest go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest ``` ### 3. Etcd 连接失败 确保 Etcd 服务正常运行，并检查 `etcd.yaml` 配置是否正确。 ## 📚 学习资源 - [GoFrame 官方文档](https://goframe.org/) - [GoFrame 微服务设计](https://goframe.org/docs/design/microservice) - [gRPC 官方文档](https://grpc.io/docs/) - [Etcd 官方文档](https://etcd.io/docs/) ## 🤝 贡献指南 本项目为学习性质，欢迎提出改进建议。 ## 📄 许可证 MIT License ## 👤 作者 GoFrame 中级实战教程 - 比邻英语本 --- **最后更新**: 2026-04-01