293 lines
5.9 KiB
Markdown
293 lines
5.9 KiB
Markdown
# 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. **测试策略**
|
||
- 使用小分页大小进行快速测试
|
||
- 利用交互式文档进行手动测试
|
||
- 编写自动化测试脚本
|