ruoyunbai/compliance

Fork 0

gongwenxin fc2b64ccc4 add single page

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

5.9 KiB

Raw Permalink Blame History

DMS合规性测试工具 - FastAPI版本使用指南

概述

FastAPI版本提供了自动生成的交互式API文档，相比Flask版本具有以下优势：

🚀 自动API文档: 自动生成Swagger UI和ReDoc文档
📊 数据验证: 基于Pydantic的强类型数据验证
⚡ 高性能: 基于Starlette和Uvicorn的异步框架
🔧 类型提示: 完整的类型提示支持
📝 详细文档: 丰富的API描述和示例

快速开始

1. 安装依赖

# 安装FastAPI版本的依赖
pip install -r requirements_fastapi.txt

2. 启动服务器

# 使用启动脚本（推荐）
./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文档特性

自动生成的文档包含：

完整的API规范
- 所有端点的详细描述
- 请求/响应模型
- 参数说明和示例
交互式测试
- 直接在浏览器中测试API
- 自动填充示例数据
- 实时查看响应结果
数据模型文档
- 详细的数据结构说明
- 字段验证规则
- 示例值

主要API端点

1. 健康检查

GET /

检查服务器状态和基本信息。

2. 服务信息

GET /info

获取详细的服务器信息和功能列表。

3. 执行测试

POST /run

执行API合规性测试的主要端点。

请求体示例:

{
  "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
}

响应示例:

{
  "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. 构建镜像

docker build -f Dockerfile.fastapi -t dms-compliance-fastapi .

2. 使用Docker Compose

# 启动服务
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. 环境变量

# 在docker-compose.yml中配置
environment:
  - HOST=0.0.0.0
  - PORT=5050
  - WORKERS=4
  - PYTHONUNBUFFERED=1

性能优化

1. 生产部署

# 使用多个工作进程
python3 fastapi_server.py --workers 4

# 使用Gunicorn（推荐生产环境）
gunicorn fastapi_server:app -w 4 -k uvicorn.workers.UvicornWorker

2. 内存优化

# 使用较小的分页大小
{
  "page_size": 500,  # 减少内存使用
  "dms": "..."
}

3. 并发处理

FastAPI天然支持异步处理，可以同时处理多个请求。

开发和调试

1. 开发模式

# 启用自动重载
python3 fastapi_server.py --reload

# 或使用环境变量
RELOAD=true ./start_fastapi.sh

2. 日志配置

# 在代码中调整日志级别
logging.getLogger('ddms_compliance_suite').setLevel(logging.DEBUG)

3. 调试技巧

使用Swagger UI进行交互式测试
查看详细的错误信息和堆栈跟踪
利用Pydantic的数据验证错误信息

与Flask版本的对比

特性	Flask版本	FastAPI版本
API文档	无	自动生成
数据验证	手动	自动（Pydantic）
性能	中等	高（异步）
类型提示	部分	完整
交互测试	无	内置
学习曲线	低	中等

故障排除

常见问题

端口被占用

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

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

依赖缺失

# 重新安装依赖
pip install -r requirements_fastapi.txt

文档无法访问
- 检查服务器是否正常启动
- 确认端口配置正确
- 查看防火墙设置

调试命令

# 检查服务状态
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"}'

最佳实践

生产部署
- 使用多个工作进程
- 配置反向代理（Nginx）
- 启用HTTPS
- 设置适当的超时时间
安全考虑
- 限制CORS域名
- 使用环境变量存储敏感信息
- 定期更新依赖
监控和日志
- 配置结构化日志
- 监控API响应时间
- 设置健康检查
测试策略
- 使用小分页大小进行快速测试
- 利用交互式文档进行手动测试
- 编写自动化测试脚本

5.9 KiB Raw Permalink Blame History Unescape Escape