ruoyunbai/compliance

Fork 0

gongwenxin fc2b64ccc4 add single page

2025-08-19 14:44:57 +08:00

6.0 KiB

Raw Blame History

FastAPI版本分页功能实现总结

🎯 实现概述

我们成功实现了FastAPI版本的DMS合规性测试工具，并添加了完整的分页支持，包括 page_size 和 page_no 参数。

🔧 主要改进

1. 添加 `page_no` 参数支持

新增功能:

page_no: 起始页码，从1开始
支持断点续传和跳过前面的页面
详细的分页统计信息

API参数:

{
  "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. 分页信息增强

返回的分页信息:

{
  "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. 基本分页测试

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页开始）

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. 小批量处理（减少内存使用）

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版本打包脚本

# 创建FastAPI版本部署包
./create-compose-package-fastapi.sh

# 特点：
# - 使用5051端口（与历史查看器一致）
# - 自动生成API文档
# - 支持完整的分页功能

2. 部署包特性

端口: 5051 (避免与Flask版本冲突)
文档: 自动生成交互式API文档
架构: 自动检测当前平台
大小: 约350MB (包含FastAPI依赖)

3. 部署后访问

# 主服务
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. 内存优化

{
  "page_size": 100,    // 小分页减少内存
  "page_no": 1,        // 从需要的页面开始
  "verbose": false     // 减少日志输出
}

2. 网络优化

{
  "page_size": 1000,   // 大分页减少请求次数
  "page_no": 1,        // 一次性获取
  "ignore_ssl": true   // 跳过SSL验证（测试环境）
}

3. 断点续传

{
  "page_size": 500,    // 平衡大小
  "page_no": 10,       // 从中断点继续
  "strictness_level": "HIGH"
}

🛠️ 开发和调试

1. 启动开发服务器

# 自动重载模式
python3 fastapi_server.py --reload --port 5051

# 或使用启动脚本
RELOAD=true ./start_fastapi.sh

2. 测试分页功能

# 运行测试脚本
python3 test_fastapi.py

# 测试特定功能
python3 test_pagination.py --api-server

3. 调试技巧

使用Swagger UI进行交互式测试
查看详细的Pydantic验证错误
利用FastAPI的自动文档功能

🔍 故障排除

1. Pydantic版本问题

# 确保使用Pydantic V2
pip install "pydantic>=2.5.0"

# 检查版本
python3 -c "import pydantic; print(pydantic.__version__)"

2. 端口冲突

# 检查端口使用
lsof -i :5051

# 使用其他端口
python3 fastapi_server.py --port 8080

3. 依赖问题

# 重新安装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版本成功实现了：

✅ 完整的分页支持: page_size + page_no
✅ 自动API文档: Swagger UI + ReDoc
✅ 强类型验证: Pydantic V2模型
✅ 高性能处理: 异步框架
✅ Docker部署: 5051端口，避免冲突
✅ 向后兼容: 支持所有原有功能

这个实现完全解决了内存溢出问题，同时提供了更好的开发体验和API文档支持！

6.0 KiB Raw Blame History Unescape Escape