# Yinli API 项目总结 ## 🎉 项目概述 基于 Golang Gin 框架构建的高性能 RESTful API 服务，集成了 JWT 认证、Redis 缓存、频率限制、CORS 等安全特性，支持多环境部署和完整的 API 文档生成。 以下是项目的详细总结： ## ✅ 已完成的功能 ### 1. 项目基础架构 - ✅ 基于 Gin 框架的 RESTful API 服务 - ✅ 清晰的项目目录结构（src 目录统一管理源代码） - ✅ Go 模块依赖管理 ### 2. 配置管理系统 - ✅ 使用 Viper 库进行配置管理 - ✅ 支持三种环境配置：dev（开发）、stage（预发布）、prod（生产） - ✅ 配置文件保存在 `config/` 目录 ### 3. 数据库集成 - ✅ MySQL 数据库连接和管理 - ✅ GORM ORM 库集成 - ✅ 用户模型和数据访问层 - ✅ 数据库初始化脚本（`sql/init.sql`） ### 4. 缓存系统 - ✅ Redis 缓存集成 - ✅ 完整的 Redis 操作封装 - ✅ 用于频率限制和会话管理 ### 5. 安全特性 - ✅ JWT 认证系统 - ✅ CORS 跨域支持 - ✅ 基于 Redis 的 API 频率限制 - ✅ bcrypt 密码加密 - ✅ 多层中间件安全防护 ### 6. 用户认证接口 - ✅ 用户注册接口 (`POST /api/auth/register`) - ✅ 用户登录接口 (`POST /api/auth/login`) - ✅ 用户资料管理接口 - ✅ 管理员权限接口 ### 7. 构建和部署 - ✅ 完整的 Makefile 构建脚本 - ✅ 支持多环境启动命令（`make dev`、`make stage`、`make prod`） - ✅ Docker 容器化支持 - ✅ 自动生成 Docker Compose 文件 - ✅ 端口配置变量化（`SERVER_PORT`、`SWAGGER_PORT`） - ✅ 端口占用检查和自动处理 - ✅ 端口进程管理命令（`kill-port`、`kill-port-force`） ### 8. 测试框架 - ✅ 使用 Testify 测试框架 - ✅ 配置系统测试 - ✅ 中间件测试 - ✅ 接口测试框架（需要数据库连接时可启用） ### 9. API 文档 - ✅ Swagger 文档自动生成（`make docs`） - ✅ 自动安装 swag 工具（如果未安装） - ✅ 自动过滤生成过程中的警告信息 - ✅ 自动修复生成的 `docs.go` 文件兼容性问题 - ✅ 支持按环境分离文档生成（dev/stage/prod） - ✅ Docker Swagger UI 服务（`make docs-serve`） - ✅ 应用内置 Swagger UI（`/swagger/index.html`） - ✅ 文档保存在 `doc/` 目录 ### 10. 详细文档 - ✅ 完整的 README.md 说明文档 - ✅ 技术架构说明 - ✅ 开发调试指南 - ✅ 部署说明 ## 🚀 快速启动指南 ### 1. 基本启动 ```bash # 进入项目目录 cd /home/table/Workspace/go/src/yinli-api # 查看所有可用命令 make help # 下载依赖 make deps # 启动开发环境 make dev ``` ### 2. Docker 启动 #### 开发环境 ```bash # 生成 Docker Compose 文件（可选，文件已存在） make docker-compose-dev # 启动开发环境容器 make docker-up-dev # 查看日志 make docker-logs-dev # 停止服务 make docker-down-dev ``` #### 预发布环境 ```bash # 启动预发布环境容器 make docker-up-stage # 查看日志 make docker-logs-stage # 停止服务 make docker-down-stage ``` #### 生产环境 ```bash # 设置环境变量（重要！） export MYSQL_ROOT_PASSWORD=your_secure_password export REDIS_PASSWORD=your_redis_password # 启动生产环境容器 make docker-up-prod # 查看日志 make docker-logs-prod # 停止服务 make docker-down-prod ``` ### 3. 运行测试 ```bash # 运行所有测试 make test # 生成测试覆盖率报告 make test-coverage ``` ## 📁 项目结构概览 ``` yinli-api/ ├── src/ # 源代码目录 │ ├── main.go # 应用程序入口 │ ├── handler/ # HTTP 处理器 │ ├── middleware/ # 中间件 │ ├── model/ # 数据模型 │ ├── repository/ # 数据访问层 │ ├── service/ # 业务逻辑层 │ └── pkg/ # 可复用包 │ ├── auth/ # JWT 认证 │ ├── cache/ # Redis 缓存 │ ├── config/ # 配置管理 │ └── database/ # 数据库连接 ├── config/ # 配置文件目录 │ ├── dev.yaml # 开发环境配置 │ ├── stage.yaml # 预发布环境配置 │ └── prod.yaml # 生产环境配置 ├── docker/ # Docker 相关文件 ├── sql/ # 数据库脚本 ├── test/ # 测试文件 ├── Dockerfile # Docker 镜像构建 ├── Makefile # 构建脚本 └── README.md # 项目说明 ``` ## 🔧 主要技术栈 - **Web 框架**: Gin v1.11.0 - **数据库**: MySQL 8.0 + GORM - **缓存**: Redis 7 - **认证**: JWT (golang-jwt/jwt/v5) - **配置**: Viper v1.21.0 - **测试**: Testify v1.11.1 - **文档**: Swagger (gin-swagger) - **容器**: Docker + Docker Compose ## 🛠️ 可用的 Make 命令 ### 开发命令 ```bash make help # 显示所有可用命令 make dev # 启动开发环境 make stage # 启动预发布环境 make prod # 启动生产环境 ``` ### 构建命令 ```bash make build # 构建应用程序 make build-all # 构建所有平台版本 make clean # 清理构建文件 ``` ### 测试命令 ```bash make test # 运行测试 make test-coverage # 运行测试并生成覆盖率报告 ``` ### 文档命令 ```bash make docs # 生成 API 文档（自动安装 swag） make docs-serve # 启动 Swagger UI 服务器（Docker） make docs-stop # 停止 Swagger UI 服务器 ``` ### Docker 命令 ```bash make docker-up-dev # 启动 Docker 开发环境 make docker-up-stage # 启动 Docker 预发布环境 make docker-up-prod # 启动 Docker 生产环境 make docker-down-dev # 停止开发环境容器 make docker-logs-dev # 查看开发环境日志 make docker-ps # 查看所有容器状态 ``` ### 端口管理命令 ```bash make kill-port PORT=1234 # 终止指定端口的进程 make kill-port-force PORT=1234 # 强制终止指定端口的进程 make kill-1234 # 终止默认端口 1234 的进程 ``` ## 📡 API 接口列表 ### 认证接口 - `POST /api/auth/register` - 用户注册 - `POST /api/auth/login` - 用户登录 ### 用户接口（需要 JWT 认证） - `GET /api/user/profile` - 获取用户资料 - `PUT /api/user/profile` - 更新用户资料 - `PUT /api/user/password` - 修改密码 ### 管理员接口（需要管理员权限） - `GET /api/admin/users` - 获取用户列表 - `DELETE /api/admin/users/{id}` - 删除用户 - `PUT /api/admin/users/{id}/status` - 更新用户状态 ### 系统接口 - `GET /health` - 健康检查 - `GET /swagger/*` - API 文档（Swagger UI） - 访问地址：`http://localhost:$(SERVER_PORT)/swagger/index.html` - 需要先执行 `make docs` 生成文档 ## 🔒 安全特性 1. **JWT 认证**: 基于 JSON Web Token 的用户认证 2. **CORS 保护**: 可配置的跨域资源共享 3. **频率限制**: 基于 Redis 的 API 调用频率限制 4. **密码加密**: 使用 bcrypt 加密用户密码 5. **中间件保护**: 多层安全中间件防护 ## 🌍 环境配置 项目支持三种环境配置，每种环境都有独立的配置文件： - **dev**: 开发环境，详细日志，宽松的安全设置 - **stage**: 预发布环境，生产级配置，用于测试 - **prod**: 生产环境，最严格的安全设置 ## 📊 测试覆盖 项目包含以下测试： - 配置系统测试 - JWT 认证中间件测试 - CORS 中间件测试 - 请求 ID 中间件测试 - 基础 API 接口测试 ## 🚀 部署建议 ### 开发环境 ```bash make dev ``` ### 生产环境 ```bash # 设置环境变量 export MYSQL_ROOT_PASSWORD=your_secure_password export REDIS_PASSWORD=your_redis_password # 使用 Docker 部署 make docker-up-prod # 查看日志 make docker-logs-prod ``` ## 📝 下一步建议 1. **数据库设置**: 确保 MySQL 数据库运行并执行 `sql/init.sql` 2. **Redis 设置**: 确保 Redis 服务运行 3. **环境变量**: 在生产环境中设置敏感配置的环境变量 4. **SSL 证书**: 在生产环境中配置 HTTPS 5. **监控日志**: 添加应用监控和日志收集 6. **API 文档**: 运行 `make docs` 自动生成 Swagger 文档，使用 `make docs-serve` 启动 Swagger UI 服务器 ## 🔧 最新优化功能 ### 端口配置管理 - **SERVER_PORT 变量**：统一管理应用服务器端口（默认 1234） - 自动更新配置文件中的 `server.port` - 自动更新 Docker Compose 端口映射 - 支持端口占用检查和自动处理 - **SWAGGER_PORT 变量**：统一管理 Swagger UI 端口（默认 8081） - Docker Swagger UI 容器端口映射 - 静态文件服务器端口 ### API 文档生成优化 - **自动安装工具**：`make docs` 自动检查并安装 swag 工具 - **警告过滤**：自动过滤生成过程中的警告信息 - **兼容性修复**：自动修复生成的 `docs.go` 文件兼容性问题 - **Docker Swagger UI**：使用 Docker 运行完整的 Swagger UI 界面 - **应用内置 UI**：支持通过 `/swagger/index.html` 访问文档 ### Docker 命令优化 - **命令命名统一**：`docker-logs` → `docker-logs-dev`，保持命名一致性 - **自动重试机制**：Docker 容器停止失败时自动重试 - **权限错误处理**：自动检测并处理 rootless Docker 权限问题 ## 🎯 项目特色 - **完整的企业级架构**: 分层清晰，易于维护 - **高度可配置**: 支持多环境配置 - **安全性强**: 多重安全防护机制 - **易于部署**: Docker 容器化支持 - **测试完备**: 完整的测试框架 - **文档齐全**: 详细的开发和部署文档 ## 🔗 相关链接 - [Gin 框架文档](https://gin-gonic.com/) - [GORM 文档](https://gorm.io/) - [Viper 配置库](https://github.com/spf13/viper) - [JWT Go 库](https://github.com/golang-jwt/jwt) - [Redis Go 客户端](https://github.com/go-redis/redis)