add single page
This commit is contained in:
gongwenxin
@@ -0,0 +1,278 @@
|
||||
# FastAPI版本分页功能实现总结
|
||||
|
||||
## 🎯 实现概述
|
||||
|
||||
我们成功实现了FastAPI版本的DMS合规性测试工具，并添加了完整的分页支持，包括 `page_size` 和 `page_no` 参数。
|
||||
|
||||
## 🔧 主要改进
|
||||
|
||||
### 1. 添加 `page_no` 参数支持
|
||||
|
||||
**新增功能**:
|
||||
- `page_no`: 起始页码，从1开始
|
||||
- 支持断点续传和跳过前面的页面
|
||||
- 详细的分页统计信息
|
||||
|
||||
**API参数**:
|
||||
```json
|
||||
{
|
||||
"dms": "./assets/doc/dms/domain.json",
|
||||
"base_url": "https://api.example.com",
|
||||
"page_size": 500,
|
||||
"page_no": 3,
|
||||
"strictness_level": "CRITICAL"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. FastAPI版本特性
|
||||
|
||||
**自动API文档**:
|
||||
- Swagger UI: `http://localhost:5051/docs`
|
||||
- ReDoc: `http://localhost:5051/redoc`
|
||||
- OpenAPI规范: `http://localhost:5051/openapi.json`
|
||||
|
||||
**强类型验证**:
|
||||
- 基于Pydantic V2的数据模型
|
||||
- 自动参数验证和错误提示
|
||||
- 详细的字段描述和示例
|
||||
|
||||
**高性能**:
|
||||
- 异步处理支持
|
||||
- 更高的并发性能
|
||||
- 优化的JSON序列化
|
||||
|
||||
### 3. 分页信息增强
|
||||
|
||||
**返回的分页信息**:
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"page_size": 500,
|
||||
"page_no_start": 3,
|
||||
"total_pages": 20,
|
||||
"total_records": 9876,
|
||||
"pages_fetched": 18,
|
||||
"current_page": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 分页参数详解
|
||||
|
||||
### page_size (分页大小)
|
||||
- **范围**: 1-10000
|
||||
- **默认值**: 1000
|
||||
- **用途**: 控制每页获取的API数量
|
||||
- **建议**:
|
||||
- 内存受限: 100-500
|
||||
- 平衡性能: 500-1000
|
||||
- 高性能: 1000-5000
|
||||
|
||||
### page_no (起始页码)
|
||||
- **范围**: ≥1
|
||||
- **默认值**: 1
|
||||
- **用途**: 指定从哪一页开始获取
|
||||
- **应用场景**:
|
||||
- 断点续传: 从中断的页面继续
|
||||
- 跳过数据: 跳过前面不需要的页面
|
||||
- 分批处理: 分多次处理大量数据
|
||||
|
||||
## 🚀 使用示例
|
||||
|
||||
### 1. 基本分页测试
|
||||
```bash
|
||||
curl -X POST http://localhost:5051/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"dms": "./assets/doc/dms/domain.json",
|
||||
"base_url": "https://api.example.com",
|
||||
"page_size": 1000,
|
||||
"page_no": 1
|
||||
}'
|
||||
```
|
||||
|
||||
### 2. 断点续传（从第5页开始）
|
||||
```bash
|
||||
curl -X POST http://localhost:5051/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"dms": "./assets/doc/dms/domain.json",
|
||||
"base_url": "https://api.example.com",
|
||||
"page_size": 500,
|
||||
"page_no": 5
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. 小批量处理（减少内存使用）
|
||||
```bash
|
||||
curl -X POST http://localhost:5051/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"dms": "./assets/doc/dms/domain.json",
|
||||
"base_url": "https://api.example.com",
|
||||
"page_size": 100,
|
||||
"page_no": 1,
|
||||
"ignore_ssl": true
|
||||
}'
|
||||
```
|
||||
|
||||
## 🐳 Docker部署
|
||||
|
||||
### 1. FastAPI版本打包脚本
|
||||
```bash
|
||||
# 创建FastAPI版本部署包
|
||||
./create-compose-package-fastapi.sh
|
||||
|
||||
# 特点：
|
||||
# - 使用5051端口（与历史查看器一致）
|
||||
# - 自动生成API文档
|
||||
# - 支持完整的分页功能
|
||||
```
|
||||
|
||||
### 2. 部署包特性
|
||||
- **端口**: 5051 (避免与Flask版本冲突)
|
||||
- **文档**: 自动生成交互式API文档
|
||||
- **架构**: 自动检测当前平台
|
||||
- **大小**: 约350MB (包含FastAPI依赖)
|
||||
|
||||
### 3. 部署后访问
|
||||
```bash
|
||||
# 主服务
|
||||
http://localhost:5051/
|
||||
|
||||
# API文档 (Swagger UI)
|
||||
http://localhost:5051/docs
|
||||
|
||||
# API文档 (ReDoc)
|
||||
http://localhost:5051/redoc
|
||||
|
||||
# 服务信息
|
||||
http://localhost:5051/info
|
||||
```
|
||||
|
||||
## 🔄 版本对比
|
||||
|
||||
| 特性 | Flask版本 | FastAPI版本 |
|
||||
|------|-----------|-------------|
|
||||
| **端口** | 5050 | 5051 |
|
||||
| **API文档** | 无 | 自动生成 |
|
||||
| **分页参数** | page_size | page_size + page_no |
|
||||
| **数据验证** | 手动 | 自动 (Pydantic) |
|
||||
| **性能** | 同步 | 异步 |
|
||||
| **交互测试** | 无 | 内置 |
|
||||
| **类型提示** | 部分 | 完整 |
|
||||
| **错误信息** | 基本 | 详细 |
|
||||
|
||||
## 📈 性能优化建议
|
||||
|
||||
### 1. 内存优化
|
||||
```json
|
||||
{
|
||||
"page_size": 100, // 小分页减少内存
|
||||
"page_no": 1, // 从需要的页面开始
|
||||
"verbose": false // 减少日志输出
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 网络优化
|
||||
```json
|
||||
{
|
||||
"page_size": 1000, // 大分页减少请求次数
|
||||
"page_no": 1, // 一次性获取
|
||||
"ignore_ssl": true // 跳过SSL验证（测试环境）
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 断点续传
|
||||
```json
|
||||
{
|
||||
"page_size": 500, // 平衡大小
|
||||
"page_no": 10, // 从中断点继续
|
||||
"strictness_level": "HIGH"
|
||||
}
|
||||
```
|
||||
|
||||
## 🛠️ 开发和调试
|
||||
|
||||
### 1. 启动开发服务器
|
||||
```bash
|
||||
# 自动重载模式
|
||||
python3 fastapi_server.py --reload --port 5051
|
||||
|
||||
# 或使用启动脚本
|
||||
RELOAD=true ./start_fastapi.sh
|
||||
```
|
||||
|
||||
### 2. 测试分页功能
|
||||
```bash
|
||||
# 运行测试脚本
|
||||
python3 test_fastapi.py
|
||||
|
||||
# 测试特定功能
|
||||
python3 test_pagination.py --api-server
|
||||
```
|
||||
|
||||
### 3. 调试技巧
|
||||
- 使用Swagger UI进行交互式测试
|
||||
- 查看详细的Pydantic验证错误
|
||||
- 利用FastAPI的自动文档功能
|
||||
|
||||
## 🔍 故障排除
|
||||
|
||||
### 1. Pydantic版本问题
|
||||
```bash
|
||||
# 确保使用Pydantic V2
|
||||
pip install "pydantic>=2.5.0"
|
||||
|
||||
# 检查版本
|
||||
python3 -c "import pydantic; print(pydantic.__version__)"
|
||||
```
|
||||
|
||||
### 2. 端口冲突
|
||||
```bash
|
||||
# 检查端口使用
|
||||
lsof -i :5051
|
||||
|
||||
# 使用其他端口
|
||||
python3 fastapi_server.py --port 8080
|
||||
```
|
||||
|
||||
### 3. 依赖问题
|
||||
```bash
|
||||
# 重新安装FastAPI依赖
|
||||
pip install -r requirements_fastapi.txt
|
||||
|
||||
# 检查关键依赖
|
||||
python3 -c "import fastapi, uvicorn, pydantic"
|
||||
```
|
||||
|
||||
## 🎯 最佳实践
|
||||
|
||||
### 1. 生产部署
|
||||
- 使用多个工作进程: `--workers 4`
|
||||
- 配置反向代理 (Nginx)
|
||||
- 启用HTTPS和安全头
|
||||
- 监控API性能和错误率
|
||||
|
||||
### 2. 分页策略
|
||||
- **大数据集**: 使用小分页 (100-500)
|
||||
- **快速测试**: 使用中等分页 (500-1000)
|
||||
- **生产环境**: 根据内存和网络条件调整
|
||||
|
||||
### 3. 错误处理
|
||||
- 利用FastAPI的自动错误响应
|
||||
- 监控分页统计信息
|
||||
- 实现重试机制处理网络异常
|
||||
|
||||
## 📝 总结
|
||||
|
||||
FastAPI版本成功实现了：
|
||||
|
||||
1. ✅ **完整的分页支持**: `page_size` + `page_no`
|
||||
2. ✅ **自动API文档**: Swagger UI + ReDoc
|
||||
3. ✅ **强类型验证**: Pydantic V2模型
|
||||
4. ✅ **高性能处理**: 异步框架
|
||||
5. ✅ **Docker部署**: 5051端口，避免冲突
|
||||
6. ✅ **向后兼容**: 支持所有原有功能
|
||||
|
||||
这个实现完全解决了内存溢出问题，同时提供了更好的开发体验和API文档支持！
|
||||
@@ -0,0 +1,292 @@
|
||||
# DMS合规性测试工具 - FastAPI版本使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
FastAPI版本提供了自动生成的交互式API文档，相比Flask版本具有以下优势：
|
||||
|
||||
- 🚀 **自动API文档**: 自动生成Swagger UI和ReDoc文档
|
||||
- 📊 **数据验证**: 基于Pydantic的强类型数据验证
|
||||
- ⚡ **高性能**: 基于Starlette和Uvicorn的异步框架
|
||||
- 🔧 **类型提示**: 完整的类型提示支持
|
||||
- 📝 **详细文档**: 丰富的API描述和示例
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 1. 安装依赖
|
||||
|
||||
```bash
|
||||
# 安装FastAPI版本的依赖
|
||||
pip install -r requirements_fastapi.txt
|
||||
```
|
||||
|
||||
### 2. 启动服务器
|
||||
|
||||
```bash
|
||||
# 使用启动脚本（推荐）
|
||||
./start_fastapi.sh
|
||||
|
||||
# 或直接运行
|
||||
python3 fastapi_server.py
|
||||
|
||||
# 开发模式（自动重载）
|
||||
python3 fastapi_server.py --reload
|
||||
|
||||
# 自定义配置
|
||||
python3 fastapi_server.py --host 0.0.0.0 --port 8080 --workers 4
|
||||
```
|
||||
|
||||
### 3. 访问API文档
|
||||
|
||||
启动后可以访问以下地址：
|
||||
|
||||
- **Swagger UI**: http://localhost:5050/docs
|
||||
- **ReDoc**: http://localhost:5050/redoc
|
||||
- **健康检查**: http://localhost:5050/
|
||||
|
||||
## API文档特性
|
||||
|
||||
### 自动生成的文档包含：
|
||||
|
||||
1. **完整的API规范**
|
||||
- 所有端点的详细描述
|
||||
- 请求/响应模型
|
||||
- 参数说明和示例
|
||||
|
||||
2. **交互式测试**
|
||||
- 直接在浏览器中测试API
|
||||
- 自动填充示例数据
|
||||
- 实时查看响应结果
|
||||
|
||||
3. **数据模型文档**
|
||||
- 详细的数据结构说明
|
||||
- 字段验证规则
|
||||
- 示例值
|
||||
|
||||
## 主要API端点
|
||||
|
||||
### 1. 健康检查
|
||||
```
|
||||
GET /
|
||||
```
|
||||
检查服务器状态和基本信息。
|
||||
|
||||
### 2. 服务信息
|
||||
```
|
||||
GET /info
|
||||
```
|
||||
获取详细的服务器信息和功能列表。
|
||||
|
||||
### 3. 执行测试
|
||||
```
|
||||
POST /run
|
||||
```
|
||||
执行API合规性测试的主要端点。
|
||||
|
||||
**请求体示例**:
|
||||
```json
|
||||
{
|
||||
"dms": "./assets/doc/dms/domain.json",
|
||||
"base_url": "https://api.example.com",
|
||||
"page_size": 1000,
|
||||
"strictness_level": "CRITICAL",
|
||||
"ignore_ssl": false,
|
||||
"generate_pdf": true,
|
||||
"verbose": false
|
||||
}
|
||||
```
|
||||
|
||||
**响应示例**:
|
||||
```json
|
||||
{
|
||||
"status": "completed",
|
||||
"message": "Tests finished.",
|
||||
"report_directory": "/path/to/reports/2024-01-15_10-30-45",
|
||||
"summary": {
|
||||
"endpoints_total": 150,
|
||||
"endpoints_passed": 145,
|
||||
"endpoints_failed": 5,
|
||||
"test_cases_total": 750
|
||||
},
|
||||
"pagination": {
|
||||
"page_size": 1000,
|
||||
"total_records": 150,
|
||||
"total_pages": 1,
|
||||
"pages_fetched": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 报告管理
|
||||
```
|
||||
GET /reports # 列出所有报告
|
||||
GET /reports/{id} # 下载特定报告
|
||||
```
|
||||
|
||||
## 配置参数详解
|
||||
|
||||
### API定义源（三选一）
|
||||
- `yapi`: YAPI定义文件路径
|
||||
- `swagger`: Swagger/OpenAPI定义文件路径
|
||||
- `dms`: DMS服务发现的domain mapping文件路径
|
||||
|
||||
### 基本配置
|
||||
- `base_url`: API基础URL（必填）
|
||||
- `page_size`: DMS分页大小（1-10000，默认1000）
|
||||
- `strictness_level`: 严格等级（CRITICAL/HIGH/MEDIUM/LOW）
|
||||
|
||||
### 过滤选项
|
||||
- `categories`: YAPI分类列表
|
||||
- `tags`: Swagger标签列表
|
||||
- `ignore_ssl`: 忽略SSL证书验证
|
||||
|
||||
### LLM配置
|
||||
- `llm_api_key`: LLM API密钥
|
||||
- `llm_base_url`: LLM API基础URL
|
||||
- `llm_model_name`: LLM模型名称
|
||||
- `use_llm_for_*`: 各种LLM使用选项
|
||||
|
||||
## Docker部署
|
||||
|
||||
### 1. 构建镜像
|
||||
```bash
|
||||
docker build -f Dockerfile.fastapi -t dms-compliance-fastapi .
|
||||
```
|
||||
|
||||
### 2. 使用Docker Compose
|
||||
```bash
|
||||
# 启动服务
|
||||
docker-compose -f docker-compose.fastapi.yml up -d
|
||||
|
||||
# 查看日志
|
||||
docker-compose -f docker-compose.fastapi.yml logs -f
|
||||
|
||||
# 停止服务
|
||||
docker-compose -f docker-compose.fastapi.yml down
|
||||
```
|
||||
|
||||
### 3. 环境变量
|
||||
```bash
|
||||
# 在docker-compose.yml中配置
|
||||
environment:
|
||||
- HOST=0.0.0.0
|
||||
- PORT=5050
|
||||
- WORKERS=4
|
||||
- PYTHONUNBUFFERED=1
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
### 1. 生产部署
|
||||
```bash
|
||||
# 使用多个工作进程
|
||||
python3 fastapi_server.py --workers 4
|
||||
|
||||
# 使用Gunicorn（推荐生产环境）
|
||||
gunicorn fastapi_server:app -w 4 -k uvicorn.workers.UvicornWorker
|
||||
```
|
||||
|
||||
### 2. 内存优化
|
||||
```bash
|
||||
# 使用较小的分页大小
|
||||
{
|
||||
"page_size": 500, # 减少内存使用
|
||||
"dms": "..."
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 并发处理
|
||||
FastAPI天然支持异步处理，可以同时处理多个请求。
|
||||
|
||||
## 开发和调试
|
||||
|
||||
### 1. 开发模式
|
||||
```bash
|
||||
# 启用自动重载
|
||||
python3 fastapi_server.py --reload
|
||||
|
||||
# 或使用环境变量
|
||||
RELOAD=true ./start_fastapi.sh
|
||||
```
|
||||
|
||||
### 2. 日志配置
|
||||
```python
|
||||
# 在代码中调整日志级别
|
||||
logging.getLogger('ddms_compliance_suite').setLevel(logging.DEBUG)
|
||||
```
|
||||
|
||||
### 3. 调试技巧
|
||||
- 使用Swagger UI进行交互式测试
|
||||
- 查看详细的错误信息和堆栈跟踪
|
||||
- 利用Pydantic的数据验证错误信息
|
||||
|
||||
## 与Flask版本的对比
|
||||
|
||||
| 特性 | Flask版本 | FastAPI版本 |
|
||||
|------|-----------|-------------|
|
||||
| API文档 | 无 | 自动生成 |
|
||||
| 数据验证 | 手动 | 自动（Pydantic） |
|
||||
| 性能 | 中等 | 高（异步） |
|
||||
| 类型提示 | 部分 | 完整 |
|
||||
| 交互测试 | 无 | 内置 |
|
||||
| 学习曲线 | 低 | 中等 |
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **端口被占用**
|
||||
```bash
|
||||
# 检查端口使用
|
||||
lsof -i :5050
|
||||
|
||||
# 使用其他端口
|
||||
python3 fastapi_server.py --port 8080
|
||||
```
|
||||
|
||||
2. **依赖缺失**
|
||||
```bash
|
||||
# 重新安装依赖
|
||||
pip install -r requirements_fastapi.txt
|
||||
```
|
||||
|
||||
3. **文档无法访问**
|
||||
- 检查服务器是否正常启动
|
||||
- 确认端口配置正确
|
||||
- 查看防火墙设置
|
||||
|
||||
### 调试命令
|
||||
```bash
|
||||
# 检查服务状态
|
||||
curl http://localhost:5050/
|
||||
|
||||
# 查看服务信息
|
||||
curl http://localhost:5050/info
|
||||
|
||||
# 测试API端点
|
||||
curl -X POST http://localhost:5050/run \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"dms": "./test.json", "base_url": "https://api.test.com"}'
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
1. **生产部署**
|
||||
- 使用多个工作进程
|
||||
- 配置反向代理（Nginx）
|
||||
- 启用HTTPS
|
||||
- 设置适当的超时时间
|
||||
|
||||
2. **安全考虑**
|
||||
- 限制CORS域名
|
||||
- 使用环境变量存储敏感信息
|
||||
- 定期更新依赖
|
||||
|
||||
3. **监控和日志**
|
||||
- 配置结构化日志
|
||||
- 监控API响应时间
|
||||
- 设置健康检查
|
||||
|
||||
4. **测试策略**
|
||||
- 使用小分页大小进行快速测试
|
||||
- 利用交互式文档进行手动测试
|
||||
- 编写自动化测试脚本
|
||||
Reference in New Issue
Block a user