From 4f6f308d2376651181389320493b18d22b704df3 Mon Sep 17 00:00:00 2001 From: Table Date: Sat, 29 Nov 2025 20:13:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E5=92=8C?= =?UTF-8?q?=20PROJECT=5FSUMMARY=20=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md 更新： * 文档生成部分：添加详细的命令说明和使用方法 * 新增 SWAGGER_PORT 配置说明章节，包括变量定义、影响范围、修改方法 * 更新系统接口表格中的 Swagger 描述 * 说明应用内置 Swagger UI 的使用方法 - PROJECT_SUMMARY.md 更新： * 添加项目概述描述 * 更新 API 文档部分，反映已实现的功能 * 更新构建和部署部分，添加端口配置和进程管理功能 * 详细分类 Make 命令，添加所有新命令说明 * 更新系统接口说明，添加 Swagger UI 访问地址 * 更新下一步建议，使用新的文档生成命令 * 新增"最新优化功能"章节，详细说明端口配置和文档优化 --- PROJECT_SUMMARY.md | 86 +++++++++++++++++++++++++++++++++++++++++----- README.md | 85 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 160 insertions(+), 11 deletions(-) diff --git a/PROJECT_SUMMARY.md b/PROJECT_SUMMARY.md index 6631844..3f48390 100644 --- a/PROJECT_SUMMARY.md +++ b/PROJECT_SUMMARY.md @@ -1,6 +1,8 @@ # Yinli API 项目总结 -## 🎉 +## 🎉 项目概述 + +基于 Golang Gin 框架构建的高性能 RESTful API 服务，集成了 JWT 认证、Redis 缓存、频率限制、CORS 等安全特性，支持多环境部署和完整的 API 文档生成。 以下是项目的详细总结： @@ -45,6 +47,9 @@ - ✅ 支持多环境启动命令（`make dev`、`make stage`、`make prod`） - ✅ Docker 容器化支持 - ✅ 自动生成 Docker Compose 文件 +- ✅ 端口配置变量化（`SERVER_PORT`、`SWAGGER_PORT`） +- ✅ 端口占用检查和自动处理 +- ✅ 端口进程管理命令（`kill-port`、`kill-port-force`） ### 8. 测试框架 - ✅ 使用 Testify 测试框架 @@ -53,8 +58,13 @@ - ✅ 接口测试框架（需要数据库连接时可启用） ### 9. API 文档 -- ✅ Swagger 文档集成准备 -- ✅ 支持按环境分离文档生成 +- ✅ Swagger 文档自动生成（`make docs`） +- ✅ 自动安装 swag 工具（如果未安装） +- ✅ 自动过滤生成过程中的警告信息 +- ✅ 自动修复生成的 `docs.go` 文件兼容性问题 +- ✅ 支持按环境分离文档生成（dev/stage/prod） +- ✅ Docker Swagger UI 服务（`make docs-serve`） +- ✅ 应用内置 Swagger UI（`/swagger/index.html`） - ✅ 文档保存在 `doc/` 目录 ### 10. 详细文档 @@ -91,7 +101,7 @@ make docker-compose-dev make docker-up-dev # 查看日志 -make docker-logs +make docker-logs-dev # 停止服务 make docker-down-dev @@ -175,17 +185,51 @@ yinli-api/ ## 🛠️ 可用的 Make 命令 +### 开发命令 ```bash make help # 显示所有可用命令 make dev # 启动开发环境 make stage # 启动预发布环境 make prod # 启动生产环境 +``` + +### 构建命令 +```bash make build # 构建应用程序 -make test # 运行测试 -make docker-up-dev # 启动 Docker 开发环境 +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 接口列表 ### 认证接口 @@ -204,7 +248,9 @@ make clean # 清理构建文件 ### 系统接口 - `GET /health` - 健康检查 -- `GET /swagger/*` - API 文档 +- `GET /swagger/*` - API 文档（Swagger UI） + - 访问地址：`http://localhost:$(SERVER_PORT)/swagger/index.html` + - 需要先执行 `make docs` 生成文档 ## 🔒 安全特性 @@ -258,7 +304,31 @@ make docker-logs-prod 3. **环境变量**: 在生产环境中设置敏感配置的环境变量 4. **SSL 证书**: 在生产环境中配置 HTTPS 5. **监控日志**: 添加应用监控和日志收集 -6. **API 文档**: 运行 `make install-tools` 安装 Swagger 工具并生成文档 +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 权限问题 ## 🎯 项目特色 diff --git a/README.md b/README.md index 5845188..0a65b81 100644 --- a/README.md +++ b/README.md @@ -290,10 +290,42 @@ make check # 执行所有检查 ### 文档生成 ```bash -make docs # 生成 API 文档 -make docs-serve # 启动文档服务器 +make docs # 生成 API 文档（自动安装 swag 工具） +make docs-serve # 启动 Swagger UI 文档服务器（使用 Docker） +make docs-stop # 停止 Swagger UI 文档服务器 ``` +**文档生成说明**： + +1. **生成 API 文档**： + ```bash + make docs + ``` + - 自动检查并安装 `swag` 工具（如果未安装） + - 自动过滤生成过程中的警告信息 + - 自动修复生成的 `docs.go` 文件中的兼容性问题 + - 文档生成到 `doc/dev/` 目录 + +2. **启动 Swagger UI 服务器**： + ```bash + make docs-serve + ``` + - 使用 Docker 运行 Swagger UI 容器 + - 提供完整的 Swagger UI 界面（非简单的文件列表） + - 默认端口：`8081`（可通过 `SWAGGER_PORT` 变量修改） + - 访问地址：`http://localhost:8081` + +3. **停止 Swagger UI 服务器**： + ```bash + make docs-stop + ``` + - 停止并移除 Swagger UI 容器 + +4. **应用内置 Swagger UI**： + - 启动应用后，访问：`http://localhost:$(SERVER_PORT)/swagger/index.html` + - 例如：`http://localhost:1234/swagger/index.html` + - 注意：需要先执行 `make docs` 生成文档，并在 `main.go` 中导入 docs 包 + ### Docker 操作 ```bash @@ -413,6 +445,53 @@ make dev curl http://localhost:1234/health ``` +### SWAGGER_PORT 配置 + +`SWAGGER_PORT` 是定义在 `Makefile` 中的变量，用于统一管理 Swagger UI 文档服务器的端口配置。 + +**变量定义位置**： +```makefile +# Makefile 第 23 行 +SWAGGER_PORT := 8081 +``` + +**影响范围**： + +1. **Docker Swagger UI 容器端口映射**： + - `make docs-serve` 启动 Swagger UI 容器时，使用 `-p $(SWAGGER_PORT):8080` 进行端口映射 + - 容器内部端口固定为 8080，外部访问端口为 `SWAGGER_PORT` 的值 + +2. **静态文件服务器端口**： + - 当 Docker 不可用时，`make docs-serve` 会使用 Python HTTP 服务器 + - 服务器监听在 `SWAGGER_PORT` 指定的端口 + +3. **访问地址**： + - Swagger UI 访问地址：`http://localhost:$(SWAGGER_PORT)` + - 默认访问地址：`http://localhost:8081` + +**修改方法**： + +1. **修改 Makefile**： + ```makefile + # 在 Makefile 第 23 行修改 + SWAGGER_PORT := 8081 # 改为你想要的端口 + ``` + +2. **注意事项**： + - 确保修改后的端口未被其他服务占用 + - 如果修改了端口，访问地址也需要相应更新 + - 修改后需要重新执行 `make docs-serve` 才能生效 + +**示例**： +```bash +# 将 SWAGGER_PORT 改为 9090 +# 1. 编辑 Makefile，修改 SWAGGER_PORT := 9090 +# 2. 启动 Swagger UI 服务器 +make docs-serve +# 3. 访问 Swagger UI +# 浏览器打开: http://localhost:9090 +``` + ## 📡 API 接口 ### 认证接口 @@ -443,7 +522,7 @@ curl http://localhost:1234/health | 方法 | 路径 | 描述 | 认证 | |------|------|------|------| | GET | `/health` | 健康检查 | ❌ | -| GET | `/swagger/*` | API 文档 | ❌ | +| GET | `/swagger/*` | API 文档（Swagger UI） | ❌ | ## 🧪 接口测试