docs: 更新 README 和 PROJECT_SUMMARY 文档
- README.md 更新： * 文档生成部分：添加详细的命令说明和使用方法 * 新增 SWAGGER_PORT 配置说明章节，包括变量定义、影响范围、修改方法 * 更新系统接口表格中的 Swagger 描述 * 说明应用内置 Swagger UI 的使用方法 - PROJECT_SUMMARY.md 更新： * 添加项目概述描述 * 更新 API 文档部分，反映已实现的功能 * 更新构建和部署部分，添加端口配置和进程管理功能 * 详细分类 Make 命令，添加所有新命令说明 * 更新系统接口说明，添加 Swagger UI 访问地址 * 更新下一步建议，使用新的文档生成命令 * 新增"最新优化功能"章节，详细说明端口配置和文档优化
This commit is contained in:
Table
parent
84055fecfe
commit
4f6f308d23
@ -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 权限问题
|
||||
|
||||
## 🎯 项目特色
|
||||
|
||||
|
||||
85
README.md
85
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） | ❌ |
|
||||
|
||||
## 🧪 接口测试
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user