# Go API Lite **Repository Path**: a-intelligence-project/go-api-lite ## Basic Information - **Project Name**: Go API Lite - **Description**: golang 基础框架， 基于 gin + gorm 带.env 的配置管理的后端服务程序，支持 grpc+http 协议 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-06 - **Last Updated**: 2026-01-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Demo - 生产级Golang gRPC/HTTP双服务项目模板 这是一个生产级的Golang项目模板，同时支持gRPC和HTTP服务，采用分层架构（Handler、Service、Repository），集成了JWT认证、GORM数据库操作、Logrus日志记录等功能。 ## 项目特性 - ✅ **双服务支持**: 同时支持gRPC和HTTP服务，在同一个应用中并发运行 - ✅ **分层架构**: 清晰的Handler、Service、Repository三层架构 - ✅ **JWT认证**: 完整的JWT Token生成和验证中间件 - ✅ **GORM集成**: 使用GORM进行数据库操作，支持MySQL - ✅ **结构化日志**: 使用Logrus实现结构化日志记录 - ✅ **配置管理**: 通过`.env`文件管理环境变量配置 - ✅ **错误处理**: 统一的全局错误处理机制 - ✅ **容器化支持**: 提供Dockerfile和docker-compose.yml - ✅ **依赖注入**: 清晰的依赖注入模式 ## 项目结构 ``` demo/ ├── api/ │ └── proto/ # Protobuf定义文件 │ ├── user.proto │ ├── user.pb.go # 生成的protobuf代码 │ └── user_grpc.pb.go # 生成的gRPC服务代码 ├── cmd/ │ └── server/ │ └── main.go # 应用入口 ├── internal/ │ ├── config/ # 配置管理 │ │ └── config.go │ ├── handler/ # HTTP处理器层 │ │ └── user.go │ ├── logger/ # 日志初始化 │ │ └── logger.go │ ├── middleware/ # 中间件 │ │ ├── error_handler.go │ │ └── jwt.go │ ├── model/ # 数据模型 │ │ └── user.go │ ├── repository/ # 数据访问层 │ │ └── user.go │ ├── server/ # 服务器启动逻辑 │ │ ├── grpc.go │ │ └── http.go │ └── service/ # 业务逻辑层 │ └── user.go ├── pkg/ │ ├── e/ # 错误定义 │ │ └── errors.go │ └── util/ # 工具函数 │ └── jwt.go ├── .env # 环境变量配置（需要创建） ├── Dockerfile # Docker镜像构建文件 ├── docker-compose.yml # Docker Compose配置 ├── go.mod # Go模块依赖 ├── Makefile # Make命令 └── README.md # 项目说明文档 ``` ## 快速开始 ### 前置要求 - Go 1.21 或更高版本 - MySQL 8.0 或更高版本 - Docker 和 Docker Compose（可选，用于容器化部署） - protoc 编译器（用于生成protobuf代码，可选） ### 1. 配置环境变量 项目支持多环境配置，通过 `APP_ENV` 环境变量区分不同环境（dev/test/prod）。 #### 方式一：使用环境特定配置文件（推荐） 1. 复制配置模板： ```bash cp .env.sample .env.dev cp .env.sample .env.test cp .env.sample .env.prod ``` 2. 根据实际环境修改对应的配置文件（`.env.dev`, `.env.test`, `.env.prod`） 3. 设置环境变量指定使用的环境： ```bash # 开发环境 export APP_ENV=dev go run cmd/server/main.go # 测试环境 export APP_ENV=test go run cmd/server/main.go # 生产环境 export APP_ENV=prod go run cmd/server/main.go ``` #### 方式二：使用统一的 .env 文件 创建`.env`文件（参考项目根目录的`.env.sample`）： ```bash # 应用环境配置（可选，默认为 dev） APP_ENV=dev # Server Configuration HTTP_PORT=8080 GRPC_PORT=9090 # Database Configuration DB_HOST=localhost DB_USER=root DB_PASSWORD=your_password DB_NAME=demo_db DB_PORT=3306 # JWT Configuration JWT_SECRET=your-very-secret-key-change-in-production JWT_TIMEOUT=3600 # Log Configuration LOG_LEVEL=info ``` #### 配置加载顺序 配置加载遵循以下优先级（后面的会覆盖前面的）： 1. 系统环境变量（最高优先级） 2. `.env.{APP_ENV}` 文件（如 `.env.dev`, `.env.prod`） 3. `.env` 文件（基础配置） 4. 代码中的默认值（最低优先级） **重要说明**： - `.env.sample` 是配置模板文件，已提交到代码库 - `.env` 和 `.env.*` 文件包含敏感信息，不会被提交到代码库 - 生产环境请务必修改`JWT_SECRET`为强密钥，否则应用启动会失败 ### 2. 安装依赖 ```bash go mod download go mod tidy ``` ### 3. 生成Protobuf代码（如果需要） 如果修改了`.proto`文件，需要重新生成代码： ```bash make proto ``` 或者手动执行： ```bash protoc --go_out=. --go_opt=paths=source_relative \ --go-grpc_out=. --go-grpc_opt=paths=source_relative \ api/proto/user.proto ``` ### 4. 准备数据库 确保MySQL服务正在运行，并创建数据库： ```sql CREATE DATABASE demo_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ``` ### 5. 运行应用 #### 方式一：直接运行 ```bash go run cmd/server/main.go ``` 或者使用Make： ```bash make run ``` #### 方式二：构建后运行 ```bash make build ./bin/server ``` ### 6. 使用Docker运行（推荐） ```bash # 构建并启动所有服务（包括MySQL） docker-compose up --build # 后台运行 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down ``` ## API使用示例 ### HTTP接口 #### 1. 健康检查 ```bash curl http://localhost:8080/health ``` #### 2. 用户登录 ```bash curl -X POST http://localhost:8080/api/v1/login \ -H "Content-Type: application/json" \ -d '{ "username": "testuser", "password": "testpass" }' ``` 响应示例： ```json { "code": 0, "message": "Login successful", "data": { "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_at": 1699123456 } } ``` #### 3. 获取用户信息（需要JWT认证） ```bash curl http://localhost:8080/api/v1/users/1 \ -H "Authorization: Bearer YOUR_JWT_TOKEN" ``` 响应示例： ```json { "code": 0, "message": "Success", "data": { "id": 1, "username": "testuser", "email": "test@example.com", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } } ``` ### gRPC接口 使用gRPC客户端工具（如`grpcurl`）调用： ```bash # 安装grpcurl go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest # 调用Login方法 grpcurl -plaintext -d '{"username":"testuser","password":"testpass"}' \ localhost:9090 proto.UserService/Login # 调用GetUser方法 grpcurl -plaintext -d '{"id":1}' \ localhost:9090 proto.UserService/GetUser ``` ## 开发指南 ### 添加新的API接口 1. **定义Protobuf接口**（如果是gRPC）: - 编辑`api/proto/user.proto` - 运行`make proto`生成代码 2. **实现Repository层**: - 在`internal/repository/`中添加数据访问方法 3. **实现Service层**: - 在`internal/service/`中添加业务逻辑 4. **实现Handler层**: - 在`internal/handler/`中添加HTTP处理器 - 在`internal/server/grpc.go`中添加gRPC服务实现 5. **注册路由**: - HTTP路由：在`internal/server/http.go`中注册 - gRPC服务：已在`internal/server/grpc.go`中自动注册 ### 测试 运行测试： ```bash make test ``` 或： ```bash go test -v ./... ``` ## 生产环境部署建议 1. **安全性**: - 修改默认的JWT密钥 - 使用HTTPS/TLS - 配置数据库连接池 - 启用数据库SSL连接 2. **性能优化**: - 配置适当的数据库连接池大小 - 使用Redis缓存（如需要） - 启用Gin的Release模式 3. **监控和日志**: - 集成APM工具（如Prometheus、Jaeger） - 配置日志聚合系统 - 设置健康检查端点监控 4. **数据库迁移**: - 使用专业的数据库迁移工具（如golang-migrate） - 避免在生产环境使用`AutoMigrate` ## Make命令说明 - `make proto` - 生成protobuf代码 - `make build` - 构建应用 - `make run` - 运行应用 - `make test` - 运行测试 - `make clean` - 清理生成的文件 - `make docker-build` - 构建Docker镜像 - `make docker-up` - 启动Docker容器 - `make docker-down` - 停止Docker容器 - `make deps` - 安装依赖 - `make help` - 显示帮助信息 ## 许可证 MIT License ## 贡献 欢迎提交Issue和Pull Request！