4f6f308d23
- README.md 更新： * 文档生成部分：添加详细的命令说明和使用方法 * 新增 SWAGGER_PORT 配置说明章节，包括变量定义、影响范围、修改方法 * 更新系统接口表格中的 Swagger 描述 * 说明应用内置 Swagger UI 的使用方法 - PROJECT_SUMMARY.md 更新： * 添加项目概述描述 * 更新 API 文档部分，反映已实现的功能 * 更新构建和部署部分，添加端口配置和进程管理功能 * 详细分类 Make 命令，添加所有新命令说明 * 更新系统接口说明，添加 Swagger UI 访问地址 * 更新下一步建议，使用新的文档生成命令 * 新增"最新优化功能"章节，详细说明端口配置和文档优化
349 lines
10 KiB
Markdown
349 lines
10 KiB
Markdown
# 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)
|