mvp
This commit is contained in:
gongwenxin
@@ -0,0 +1,63 @@
|
||||
# 活动上下文
|
||||
|
||||
## 当前工作焦点
|
||||
|
||||
我们正在维护和改进DDMS合规性测试工具，该工具用于自动化API合规性测试。目前系统已经具备基本功能，支持通过Web界面和命令行方式使用。用户可以提供API规范文件（YAPI或Swagger格式），指定目标服务的Base URL，并配置自定义测试用例目录和报告输出位置等参数。
|
||||
|
||||
### 优先任务
|
||||
1. **功能完善**：确保所有核心功能正常工作，包括API规范解析、测试用例执行和报告生成。
|
||||
2. **Bug修复**：解决测试过程中可能出现的错误和异常情况。
|
||||
3. **性能优化**：提高测试执行效率，特别是对于大型API规范文件和复杂测试场景。
|
||||
4. **用户体验改进**：优化Web界面，提供更友好的操作流程和反馈。
|
||||
5. **文档更新**：确保用户手册和开发文档与最新代码保持同步。
|
||||
|
||||
## 最近变更
|
||||
|
||||
### 代码变更
|
||||
- 实现了用户认证系统，使用SQLite存储用户信息
|
||||
- 添加了LLM集成功能，支持使用大模型生成测试数据
|
||||
- 改进了测试报告格式，提供更详细的API调用信息
|
||||
- 优化了错误处理逻辑，提高了系统稳定性
|
||||
- 增强了Web界面的响应性和用户体验
|
||||
- 新增了数值越界错误处理测试用例 (TC-ERROR-4002)，用于验证API在接收到超出范围的数值参数时是否按预期返回特定业务错误码。
|
||||
|
||||
### 架构调整
|
||||
- 重构了测试编排器(APITestOrchestrator)，提高了代码可维护性
|
||||
- 引入了更灵活的插件机制，便于扩展测试用例和测试阶段
|
||||
- 改进了API规范解析器，增强了对不同格式的兼容性
|
||||
- 优化了测试用例注册表的设计，支持更精确的用例筛选
|
||||
- 在 `schema_utils.py` 中添加了可复用的辅助函数，用于从描述中解析数值范围，以简化相关测试用例的编写。
|
||||
|
||||
## 活动决策和考虑
|
||||
|
||||
### 当前决策
|
||||
1. **LLM集成策略**：决定使用兼容OpenAI API的通义千问大模型作为测试数据生成的后端，同时保留传统的基于Schema的数据生成方法作为备选。
|
||||
2. **测试报告格式**：采用JSON格式作为摘要报告，Markdown格式作为详细报告，平衡了机器可读性和人类可读性。
|
||||
3. **用户认证方案**：使用基于Flask session的简单认证系统，结合SQLite数据库存储用户信息，避免过度复杂化。
|
||||
4. **部署模式**：支持本地部署，使用简单的Python命令启动，不依赖复杂的容器或云服务。
|
||||
|
||||
### 开放问题
|
||||
1. **多线程执行**：是否应该支持并行执行测试用例以提高性能？需要权衡速度提升与稳定性风险。
|
||||
2. **测试用例覆盖度**：如何确保测试用例能全面覆盖各种API合规性要求？考虑引入测试覆盖率分析。
|
||||
3. **LLM依赖性**：如何处理LLM服务不可用或响应缓慢的情况？需要实现更强大的回退机制。
|
||||
4. **安全性增强**：当前的认证机制是否足够安全？考虑加入更多安全措施如CSRF保护和API密钥轮换。
|
||||
|
||||
## 下一步计划
|
||||
|
||||
### 短期目标 (1-2周)
|
||||
- 修复已知的bug和稳定性问题
|
||||
- 完善用户文档和开发指南
|
||||
- 优化Web界面的响应速度和用户体验
|
||||
- 增加更多预定义的测试用例
|
||||
|
||||
### 中期目标 (1-2个月)
|
||||
- 实现测试结果的历史记录和比较功能
|
||||
- 添加API端点的搜索和过滤功能
|
||||
- 改进LLM参数生成的质量和效率
|
||||
- 支持更复杂的测试场景和数据依赖
|
||||
|
||||
### 长期目标 (3+个月)
|
||||
- 开发更强大的测试报告分析工具
|
||||
- 支持团队协作和测试结果共享
|
||||
- 集成CI/CD流程，实现自动化测试
|
||||
- 开发更高级的测试用例编辑器，降低编写自定义测试用例的门槛
|
||||
@@ -0,0 +1,420 @@
|
||||
# API规范解析框架设计
|
||||
|
||||
## 背景与需求
|
||||
|
||||
当前系统需要处理多种API规范格式，包括YAPI、Swagger/OpenAPI 2.0和OpenAPI 3.0等。目前的实现在`BaseAPITestCase`类中包含了针对不同格式的特定处理逻辑，这导致：
|
||||
|
||||
1. 代码重复和维护困难
|
||||
2. 处理逻辑分散在多个地方
|
||||
3. 添加新格式支持需要修改多处代码
|
||||
4. 测试用例需要了解底层规范格式的细节
|
||||
|
||||
我们需要一个统一的解析框架，将不同格式的API规范转换为一致的内部表示，使测试用例能够以统一的方式访问API规范信息，而不必关心原始格式的差异。
|
||||
|
||||
## 设计目标
|
||||
|
||||
1. **统一接口**：提供一套统一的接口来访问API规范信息，无论原始格式如何
|
||||
2. **可扩展性**：易于添加新的API规范格式支持
|
||||
3. **完全解析**：在解析阶段处理所有的引用和格式特定的细节
|
||||
4. **一致性**：确保不同格式的规范被转换为相同的内部表示
|
||||
5. **性能优化**：减少重复解析和处理
|
||||
|
||||
## 架构设计
|
||||
|
||||
### 1. 核心组件
|
||||
|
||||
#### 1.1 统一解析器接口 (`APISpecParser`)
|
||||
|
||||
```python
|
||||
from abc import ABC, abstractmethod
|
||||
from typing import Dict, Any, Optional
|
||||
|
||||
class APISpecParser(ABC):
|
||||
"""API规范解析器的抽象基类"""
|
||||
|
||||
@abstractmethod
|
||||
def parse(self, spec_content: Dict[str, Any]) -> Dict[str, Any]:
|
||||
"""
|
||||
解析API规范内容，返回统一格式的内部表示
|
||||
|
||||
Args:
|
||||
spec_content: 原始API规范内容
|
||||
|
||||
Returns:
|
||||
统一格式的API规范内部表示
|
||||
"""
|
||||
pass
|
||||
|
||||
@abstractmethod
|
||||
def detect_format(self, spec_content: Dict[str, Any]) -> str:
|
||||
"""
|
||||
检测API规范的格式
|
||||
|
||||
Args:
|
||||
spec_content: 原始API规范内容
|
||||
|
||||
Returns:
|
||||
规范格式的标识符，如 'yapi', 'openapi2', 'openapi3'
|
||||
"""
|
||||
pass
|
||||
```
|
||||
|
||||
#### 1.2 格式特定的解析器实现
|
||||
|
||||
```python
|
||||
class YAPIParser(APISpecParser):
|
||||
"""YAPI格式解析器"""
|
||||
|
||||
def parse(self, spec_content: Dict[str, Any]) -> Dict[str, Any]:
|
||||
# YAPI特定的解析逻辑
|
||||
# 转换为统一的内部表示
|
||||
pass
|
||||
|
||||
def detect_format(self, spec_content: Dict[str, Any]) -> str:
|
||||
# 检测是否为YAPI格式
|
||||
if self._is_yapi_format(spec_content):
|
||||
return 'yapi'
|
||||
return ''
|
||||
|
||||
def _is_yapi_format(self, spec_content: Dict[str, Any]) -> bool:
|
||||
# 判断是否为YAPI格式的逻辑
|
||||
pass
|
||||
|
||||
class OpenAPI2Parser(APISpecParser):
|
||||
"""OpenAPI 2.0 (Swagger)格式解析器"""
|
||||
|
||||
def parse(self, spec_content: Dict[str, Any]) -> Dict[str, Any]:
|
||||
# OpenAPI 2.0特定的解析逻辑
|
||||
pass
|
||||
|
||||
def detect_format(self, spec_content: Dict[str, Any]) -> str:
|
||||
# 检测是否为OpenAPI 2.0格式
|
||||
if self._is_openapi2_format(spec_content):
|
||||
return 'openapi2'
|
||||
return ''
|
||||
|
||||
def _is_openapi2_format(self, spec_content: Dict[str, Any]) -> bool:
|
||||
# 判断是否为OpenAPI 2.0格式的逻辑
|
||||
pass
|
||||
|
||||
class OpenAPI3Parser(APISpecParser):
|
||||
"""OpenAPI 3.0格式解析器"""
|
||||
|
||||
def parse(self, spec_content: Dict[str, Any]) -> Dict[str, Any]:
|
||||
# OpenAPI 3.0特定的解析逻辑
|
||||
pass
|
||||
|
||||
def detect_format(self, spec_content: Dict[str, Any]) -> str:
|
||||
# 检测是否为OpenAPI 3.0格式
|
||||
if self._is_openapi3_format(spec_content):
|
||||
return 'openapi3'
|
||||
return ''
|
||||
|
||||
def _is_openapi3_format(self, spec_content: Dict[str, Any]) -> bool:
|
||||
# 判断是否为OpenAPI 3.0格式的逻辑
|
||||
pass
|
||||
```
|
||||
|
||||
#### 1.3 解析器工厂 (`APISpecParserFactory`)
|
||||
|
||||
```python
|
||||
class APISpecParserFactory:
|
||||
"""API规范解析器工厂，用于创建适合特定规范格式的解析器"""
|
||||
|
||||
def __init__(self):
|
||||
self.parsers = [
|
||||
YAPIParser(),
|
||||
OpenAPI2Parser(),
|
||||
OpenAPI3Parser()
|
||||
]
|
||||
|
||||
def get_parser(self, spec_content: Dict[str, Any]) -> Optional[APISpecParser]:
|
||||
"""
|
||||
根据规范内容自动选择合适的解析器
|
||||
|
||||
Args:
|
||||
spec_content: 原始API规范内容
|
||||
|
||||
Returns:
|
||||
适合处理该规范的解析器实例，如果没有找到则返回None
|
||||
"""
|
||||
for parser in self.parsers:
|
||||
format_type = parser.detect_format(spec_content)
|
||||
if format_type:
|
||||
return parser
|
||||
|
||||
return None
|
||||
|
||||
def register_parser(self, parser: APISpecParser):
|
||||
"""
|
||||
注册新的解析器
|
||||
|
||||
Args:
|
||||
parser: 解析器实例
|
||||
"""
|
||||
self.parsers.append(parser)
|
||||
```
|
||||
|
||||
#### 1.4 统一API规范管理器 (`UnifiedAPISpecManager`)
|
||||
|
||||
```python
|
||||
class UnifiedAPISpecManager:
|
||||
"""统一API规范管理器，负责解析和提供统一的API规范访问接口"""
|
||||
|
||||
def __init__(self):
|
||||
self.parser_factory = APISpecParserFactory()
|
||||
self.cached_specs = {} # 缓存已解析的规范
|
||||
|
||||
def parse_spec(self, spec_content: Dict[str, Any], spec_id: str = None) -> Dict[str, Any]:
|
||||
"""
|
||||
解析API规范，返回统一格式的内部表示
|
||||
|
||||
Args:
|
||||
spec_content: 原始API规范内容
|
||||
spec_id: 规范的唯一标识符，用于缓存
|
||||
|
||||
Returns:
|
||||
统一格式的API规范内部表示
|
||||
"""
|
||||
if spec_id and spec_id in self.cached_specs:
|
||||
return self.cached_specs[spec_id]
|
||||
|
||||
parser = self.parser_factory.get_parser(spec_content)
|
||||
if not parser:
|
||||
raise ValueError("无法识别的API规范格式")
|
||||
|
||||
parsed_spec = parser.parse(spec_content)
|
||||
|
||||
if spec_id:
|
||||
self.cached_specs[spec_id] = parsed_spec
|
||||
|
||||
return parsed_spec
|
||||
|
||||
def register_custom_parser(self, parser: APISpecParser):
|
||||
"""
|
||||
注册自定义解析器
|
||||
|
||||
Args:
|
||||
parser: 自定义解析器实例
|
||||
"""
|
||||
self.parser_factory.register_parser(parser)
|
||||
```
|
||||
|
||||
### 2. 统一内部表示格式
|
||||
|
||||
所有解析器都应该将原始规范转换为一个统一的内部表示格式，该格式应该包含以下核心元素：
|
||||
|
||||
```python
|
||||
{
|
||||
"info": {
|
||||
"title": "API标题",
|
||||
"version": "API版本",
|
||||
"description": "API描述"
|
||||
},
|
||||
"paths": {
|
||||
"/path/to/resource": {
|
||||
"get": {
|
||||
"summary": "操作摘要",
|
||||
"description": "操作描述",
|
||||
"parameters": [...], # 统一格式的参数列表
|
||||
"requestBody": {...}, # 统一格式的请求体定义
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "成功响应",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {...} # 统一格式的响应schema
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"schemas": {...}, # 统一格式的schema定义
|
||||
"parameters": {...}, # 统一格式的参数定义
|
||||
"responses": {...} # 统一格式的响应定义
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 解析过程中的标准化处理
|
||||
|
||||
在解析过程中，需要进行以下标准化处理：
|
||||
|
||||
1. **路径标准化**：确保所有路径格式一致
|
||||
2. **参数标准化**：将不同格式的参数定义转换为统一格式
|
||||
3. **响应标准化**：根据HTTP方法添加适当的默认状态码
|
||||
4. **Schema标准化**：解析所有的`$ref`引用
|
||||
5. **数据类型标准化**：确保数据类型表示一致
|
||||
|
||||
### 4. 与测试框架的集成
|
||||
|
||||
#### 4.1 更新 `BaseAPITestCase` 类
|
||||
|
||||
```python
|
||||
class BaseAPITestCase:
|
||||
# ... 现有代码 ...
|
||||
|
||||
def __init__(self, endpoint_spec: Dict[str, Any], global_api_spec: Dict[str, Any], json_schema_validator: Optional[Any] = None, llm_service: Optional[Any] = None):
|
||||
"""
|
||||
初始化测试用例。
|
||||
Args:
|
||||
endpoint_spec: 当前被测API端点的详细定义 (已转换为统一格式)。
|
||||
global_api_spec: 完整的API规范文档 (已转换为统一格式)。
|
||||
json_schema_validator: APITestOrchestrator 传入的 JSONSchemaValidator 实例 (可选)。
|
||||
llm_service: APITestOrchestrator 传入的 LLMService 实例 (可选)。
|
||||
"""
|
||||
self.endpoint_spec = endpoint_spec
|
||||
self.global_api_spec = global_api_spec
|
||||
self.logger = logging.getLogger(f"testcase.{self.id}")
|
||||
self.json_schema_validator = json_schema_validator
|
||||
self.llm_service = llm_service
|
||||
self.logger.debug(f"Test case '{self.id}' initialized for endpoint: {self.endpoint_spec.get('method', '')} {self.endpoint_spec.get('path', '')}")
|
||||
|
||||
# 简化的方法，不再需要处理不同格式的差异
|
||||
def _get_request_body_schema(self) -> Optional[Dict[str, Any]]:
|
||||
"""获取请求体schema"""
|
||||
request_body = self.endpoint_spec.get("requestBody", {})
|
||||
return request_body.get("schema")
|
||||
|
||||
def _get_response_schema(self, status_code: str) -> Optional[Dict[str, Any]]:
|
||||
"""获取指定状态码的响应schema"""
|
||||
responses = self.endpoint_spec.get("responses", {})
|
||||
response = responses.get(status_code)
|
||||
if response:
|
||||
return response.get("schema")
|
||||
return None
|
||||
```
|
||||
|
||||
#### 4.2 更新 `APITestOrchestrator` 类
|
||||
|
||||
```python
|
||||
class APITestOrchestrator:
|
||||
# ... 现有代码 ...
|
||||
|
||||
def __init__(self, config: Dict[str, Any]):
|
||||
# ... 现有代码 ...
|
||||
self.spec_manager = UnifiedAPISpecManager()
|
||||
|
||||
def load_api_spec(self, spec_file_path: str) -> Dict[str, Any]:
|
||||
"""
|
||||
加载并解析API规范文件
|
||||
|
||||
Args:
|
||||
spec_file_path: API规范文件路径
|
||||
|
||||
Returns:
|
||||
统一格式的API规范内部表示
|
||||
"""
|
||||
with open(spec_file_path, 'r', encoding='utf-8') as f:
|
||||
spec_content = json.load(f)
|
||||
|
||||
return self.spec_manager.parse_spec(spec_content, spec_id=spec_file_path)
|
||||
|
||||
def execute_tests(self, api_spec: Dict[str, Any], base_url: str):
|
||||
"""
|
||||
执行测试用例
|
||||
|
||||
Args:
|
||||
api_spec: 统一格式的API规范内部表示
|
||||
base_url: API基础URL
|
||||
"""
|
||||
# ... 现有代码 ...
|
||||
|
||||
for path, path_item in api_spec["paths"].items():
|
||||
for method, operation in path_item.items():
|
||||
# 使用统一格式的operation创建测试用例
|
||||
self._execute_tests_for_endpoint(operation, path, method, base_url)
|
||||
```
|
||||
|
||||
## 实现计划
|
||||
|
||||
### 阶段1：基础框架搭建
|
||||
|
||||
1. 创建核心接口和基类
|
||||
- `APISpecParser` 抽象基类
|
||||
- `APISpecParserFactory` 工厂类
|
||||
- `UnifiedAPISpecManager` 管理器类
|
||||
|
||||
2. 实现格式检测逻辑
|
||||
- 为YAPI、OpenAPI 2.0和OpenAPI 3.0实现格式检测方法
|
||||
|
||||
### 阶段2：解析器实现
|
||||
|
||||
1. 实现YAPI解析器
|
||||
- 分析YAPI特有的结构
|
||||
- 实现转换为统一格式的逻辑
|
||||
|
||||
2. 实现OpenAPI 2.0解析器
|
||||
- 分析Swagger特有的结构
|
||||
- 实现转换为统一格式的逻辑
|
||||
|
||||
3. 实现OpenAPI 3.0解析器
|
||||
- 分析OpenAPI 3.0特有的结构
|
||||
- 实现转换为统一格式的逻辑
|
||||
|
||||
### 阶段3：标准化处理
|
||||
|
||||
1. 实现路径标准化
|
||||
2. 实现参数标准化
|
||||
3. 实现响应标准化
|
||||
4. 实现Schema标准化
|
||||
5. 实现数据类型标准化
|
||||
|
||||
### 阶段4：框架集成
|
||||
|
||||
1. 更新`BaseAPITestCase`类
|
||||
- 简化API规范访问方法
|
||||
- 移除格式特定的处理逻辑
|
||||
|
||||
2. 更新`APITestOrchestrator`类
|
||||
- 集成`UnifiedAPISpecManager`
|
||||
- 使用统一格式的API规范
|
||||
|
||||
3. 更新测试用例
|
||||
- 修改现有测试用例以使用新的API
|
||||
|
||||
### 阶段5：测试与验证
|
||||
|
||||
1. 编写单元测试
|
||||
- 测试各个解析器
|
||||
- 测试标准化处理
|
||||
|
||||
2. 编写集成测试
|
||||
- 测试完整的解析流程
|
||||
- 测试与测试框架的集成
|
||||
|
||||
3. 性能测试
|
||||
- 测试解析大型API规范的性能
|
||||
- 测试缓存机制的有效性
|
||||
|
||||
## 扩展性考虑
|
||||
|
||||
### 添加新格式支持
|
||||
|
||||
要添加对新的API规范格式的支持，只需：
|
||||
|
||||
1. 创建一个新的解析器类，继承自`APISpecParser`
|
||||
2. 实现`parse`和`detect_format`方法
|
||||
3. 通过`UnifiedAPISpecManager.register_custom_parser`注册新的解析器
|
||||
|
||||
### 自定义处理逻辑
|
||||
|
||||
对于特定的标准化需求，可以：
|
||||
|
||||
1. 创建专门的处理器类
|
||||
2. 在解析过程中调用这些处理器
|
||||
3. 通过配置控制处理器的行为
|
||||
|
||||
## 结论
|
||||
|
||||
通过实现这个统一的API规范解析框架，我们可以：
|
||||
|
||||
1. 使测试用例代码更加简洁、可维护
|
||||
2. 轻松支持新的API规范格式
|
||||
3. 确保所有测试用例使用一致的API规范表示
|
||||
4. 提高解析性能和可靠性
|
||||
|
||||
这个框架将为DDMS合规性测试工具提供一个坚实的基础，使其能够适应各种API规范格式，并且易于扩展和维护。
|
||||
@@ -0,0 +1,54 @@
|
||||
# 已实现的测试用例列表
|
||||
|
||||
本文档列出了合规性测试工具中当前已实现的所有测试用例，按类别分组。
|
||||
|
||||
## 基本检查
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| ------------- | ------------------- | ---------------------------------- | -------- |
|
||||
| TC-STATUS-001 | 基本状态码 200 检查 | 验证 API 响应状态码是否为 200 OK。 | 严重 |
|
||||
|
||||
## 核心功能检查
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| ---------------- | ------------------------------------ | ------------------------------------------------- | -------- |
|
||||
| TC-CORE-FUNC-001 | Response Body JSON Schema Validation | 验证API响应体是否符合API规范中定义的JSON Schema。 | 严重 |
|
||||
|
||||
## 错误处理检查
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| ------------------- | ------------------------ | ----------------------------------------------------------------------------------------- | -------- |
|
||||
| TC-ERROR-4001-QUERY | 查询参数类型不匹配检查 | 测试当发送的查询参数数据类型与API规范定义不符时，API是否按预期返回code=4001的错误。 | 中 |
|
||||
| TC-ERROR-4001-BODY | 请求体字段类型不匹配检查 | 测试当发送的请求体中字段的数据类型与API规范定义不符时，API是否按预期返回code=4001的错误。 | 中 |
|
||||
| TC-ERROR-4002 | 数值参数越界检查 | 测试当发送的数值参数超出范围限制时，API是否按预期返回code=4002的错误。 | 中 |
|
||||
| TC-ERROR-4003-QUERY | 缺失必填查询参数检查 | 测试当请求中缺少API规范定义的必填查询参数时，API是否按预期返回code=4003的错误。 | 高 |
|
||||
| TC-ERROR-4003-BODY | 缺失必填请求体字段检查 | 测试当请求体中缺少API规范定义的必填字段时，API是否按预期返回code=4003的错误。 | 高 |
|
||||
| TC-ERROR-4006 | 非法枚举值检查 | 测试当发送的参数值不在指定的枚举范围内时，API是否按预期返回code=4006的错误。 | 中 |
|
||||
|
||||
## 安全检查
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| --------------- | ---------------- | ------------------------------------------------------------------ | -------- |
|
||||
| TC-SECURITY-001 | HTTPS强制检查 | 验证API端点是否通过HTTPS提供服务，以及HTTP请求是否被拒绝或重定向。 | 严重 |
|
||||
| TC-SECURITY-002 | 敏感字段加密检查 | 验证API响应中的敏感字段（如坐标、位置）是否已加密，而非明文。 | 高 |
|
||||
|
||||
## 规范性检查
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| -------------------------------------- | -------------------------------- | ------------------------------------------------------------------- | -------- |
|
||||
| TC-NORMATIVE-URL-LLM-COMPREHENSIVE-001 | 合URL规范与RESTful风格检查 (LLM) | 使用LLM统一评估API路径是否符合命名、结构、版本和RESTful风格等规范。 | 中 |
|
||||
| TC-NORMATIVE-001 | HTTP方法使用规范检查 | 验证API是否恰当使用HTTP方法（例如，GET用于检索，POST用于创建）。 | 中 |
|
||||
|
||||
## 设置与环境检查 (Setup Checks)
|
||||
|
||||
| ID | 名称 | 描述 | 严重程度 |
|
||||
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------- | -------- |
|
||||
| TC-HEADER-001 | 必需请求头Schema验证 | 验证API规范中是否包含必需的请求头 (X-Tenant-ID, X-Data-Domain, Authorization)。 | 严重 |
|
||||
|
||||
|
||||
## 注意事项
|
||||
|
||||
|
||||
1. 测试用例的严重程度级别包括：严重(CRITICAL)、高(HIGH)、中(MEDIUM)、低(LOW)和信息(INFO)。
|
||||
2. 所有测试用例都继承自 `BaseAPITestCase` 基类，可以通过自定义子类进行扩展。
|
||||
3. 测试用例通过 `TestCaseRegistry` 进行注册和发现，根据API端点特征自动选择适用的测试用例。
|
||||
@@ -0,0 +1,27 @@
|
||||
# 产品上下文
|
||||
|
||||
## 产品背景
|
||||
API合规性验证是确保API实现符合相关规范和标准的关键步骤。在DDMS（数据管理系统）这样的复杂系统中，确保API的一致性和合规性尤为重要。传统的手动测试方法往往耗时且容易出错，难以覆盖所有可能的测试场景。
|
||||
|
||||
## 问题陈述
|
||||
1. **手动测试效率低下**：手动验证API实现是否符合规范需要大量的时间和人力投入。
|
||||
2. **测试覆盖不全面**：人工测试难以覆盖所有边缘情况和错误处理路径。
|
||||
3. **测试结果不一致**：不同测试人员可能采用不同的测试方法和标准，导致结果不一致。
|
||||
4. **难以重复执行**：当API有更新时，需要重复执行所有测试，缺乏自动化机制。
|
||||
5. **测试数据准备困难**：为不同的API端点和测试场景准备有效的测试数据是一项挑战。
|
||||
|
||||
## 解决方案
|
||||
合规性测试工具通过自动化API测试流程，解决了上述问题：
|
||||
|
||||
1. **自动化测试执行**：根据API规范文件自动发现并执行测试用例，大幅提高测试效率。
|
||||
2. **全面的测试覆盖**：通过预定义和自定义测试用例，覆盖各种正常和异常场景。
|
||||
3. **标准化测试流程**：所有测试遵循统一的标准和流程，确保结果一致性。
|
||||
4. **易于重复执行**：API更新后，可以快速重新执行所有测试，确保持续符合规范。
|
||||
5. **智能测试数据生成**：利用大语言模型自动生成符合API规范的测试数据，减轻数据准备负担。
|
||||
|
||||
## 用户体验目标
|
||||
1. **简单易用**：提供直观的Web界面和命令行接口，降低使用门槛。
|
||||
2. **清晰的测试报告**：生成详细且易于理解的测试报告，帮助快速定位问题。
|
||||
3. **灵活可配置**：支持自定义测试用例和测试阶段，适应不同测试需求。
|
||||
4. **可扩展性**：框架设计支持添加新的测试类型和功能，以满足未来需求。
|
||||
5. **快速反馈**：测试过程中提供实时日志输出，让用户及时了解测试进展。
|
||||
@@ -0,0 +1,100 @@
|
||||
# 项目进度
|
||||
|
||||
## 已完成功能
|
||||
|
||||
### 核心功能
|
||||
- ✅ 命令行接口 (run_api_tests.py)
|
||||
- ✅ Web界面 (flask_app.py)
|
||||
- ✅ API规范解析器 (支持YAPI和Swagger/OpenAPI)
|
||||
- ✅ 测试用例注册表和发现机制
|
||||
- ✅ API调用器和请求/响应处理
|
||||
- ✅ 测试编排器 (APITestOrchestrator)
|
||||
- ✅ 基本测试报告生成 (JSON和Markdown格式)
|
||||
- ✅ 用户认证系统 (基于Flask和SQLite)
|
||||
|
||||
### 增强功能
|
||||
- ✅ LLM集成 (支持通过大模型生成测试数据)
|
||||
- ✅ 自定义测试用例支持 (基于BaseAPITestCase)
|
||||
- ✅ 自定义测试阶段支持 (基于BaseAPIStage)
|
||||
- ✅ 详细的API调用信息记录
|
||||
- ✅ Web界面的高级配置选项
|
||||
- ✅ 基于标签/分类的API端点筛选
|
||||
- ✅ 实现了多种错误处理场景的测试用例（如类型不匹配、缺失必填字段、数值越界等）
|
||||
|
||||
### 文档和支持
|
||||
- ✅ 用户手册 (MANUAL.md)
|
||||
- ✅ 框架和测试用例编写指南 (Framework_And_TestCase_Guide.md)
|
||||
- ✅ 命令行帮助文档
|
||||
- ✅ Web界面内置使用说明
|
||||
- ✅ 实现了项目中所有测试用例的列表和描述 (implemented_test_cases.md)
|
||||
|
||||
## 正在进行的工作
|
||||
|
||||
### 核心功能改进
|
||||
- 🔄 改进错误处理和异常恢复机制
|
||||
- 🔄 优化大型API规范文件的解析性能
|
||||
- 🔄 增强测试用例执行的稳定性
|
||||
- 🔄 改进测试报告的可视化展示
|
||||
|
||||
### 新功能开发
|
||||
- 🔄 测试结果历史记录和比较功能
|
||||
- 🔄 更多预定义测试用例的开发
|
||||
- 🔄 支持更复杂的测试场景和数据依赖
|
||||
- 🔄 API端点搜索和过滤功能
|
||||
|
||||
## 待完成工作
|
||||
|
||||
### 功能增强
|
||||
- ⏳ 多线程/并行测试执行支持
|
||||
- ⏳ 测试覆盖率分析工具
|
||||
- ⏳ 更强大的LLM回退和缓存机制
|
||||
- ⏳ 安全性增强 (CSRF保护, 更强的认证)
|
||||
- ⏳ API密钥管理和轮换机制
|
||||
|
||||
### 用户体验改进
|
||||
- ⏳ 更现代化的Web界面设计
|
||||
- ⏳ 实时测试进度可视化
|
||||
- ⏳ 交互式测试报告浏览器
|
||||
- ⏳ 测试用例编辑器
|
||||
- ⏳ 自定义仪表板和报告模板
|
||||
|
||||
### 集成和部署
|
||||
- ⏳ CI/CD集成支持
|
||||
- ⏳ Docker容器化部署
|
||||
- ⏳ 团队协作和结果共享功能
|
||||
- ⏳ 与常见API管理平台的集成
|
||||
|
||||
## 已知问题
|
||||
|
||||
### 严重问题
|
||||
- 🐛 大型API规范文件解析可能导致内存占用过高
|
||||
- 🐛 某些复杂的JSON Schema验证可能不准确
|
||||
|
||||
### 中等问题
|
||||
- 🐛 LLM服务不可用时缺乏足够友好的错误提示
|
||||
- 🐛 Web界面在处理大量并发请求时可能变慢
|
||||
- 🐛 测试报告可能变得过大，影响加载速度
|
||||
|
||||
### 轻微问题
|
||||
- 🐛 部分UI元素在移动设备上显示不佳
|
||||
- 🐛 某些错误消息不够明确
|
||||
- 🐛 文档中的少量拼写和格式问题
|
||||
|
||||
## 里程碑计划
|
||||
|
||||
### 里程碑1：稳定基础版本 (完成)
|
||||
- 实现所有核心功能
|
||||
- 发布基本用户文档
|
||||
- 完成初步测试和bug修复
|
||||
|
||||
### 里程碑2：增强功能版本 (进行中)
|
||||
- 添加LLM集成
|
||||
- 改进用户界面和体验
|
||||
- 增加更多预定义测试用例
|
||||
- 优化性能和稳定性
|
||||
|
||||
### 里程碑3：企业就绪版本 (计划中)
|
||||
- 实现高级安全特性
|
||||
- 添加团队协作功能
|
||||
- 支持CI/CD集成
|
||||
- 提供全面的部署选项
|
||||
@@ -0,0 +1,24 @@
|
||||
# 项目简介：合规性测试工具
|
||||
|
||||
## 项目概述
|
||||
这是一个用于测试API是否符合特定规范（如DDMS规范）的合规性测试工具。该工具能够根据API规范文件（YAPI或Swagger/OpenAPI格式）自动执行一系列测试用例，检查API的实现是否符合预期的标准和规范。
|
||||
|
||||
## 核心需求
|
||||
1. 支持通过YAPI或Swagger/OpenAPI规范文件解析API定义
|
||||
2. 自动执行预定义和自定义的测试用例
|
||||
3. 生成详细的测试报告，包括成功/失败统计和详细的API调用信息
|
||||
4. 提供Web界面和命令行两种使用方式
|
||||
5. 支持大语言模型(LLM)辅助生成测试参数
|
||||
|
||||
## 关键目标
|
||||
1. 提高API合规性测试的效率和全面性
|
||||
2. 降低手动测试的工作量和出错率
|
||||
3. 提供清晰的测试结果和报告，帮助开发团队快速定位问题
|
||||
4. 支持可扩展的测试用例编写，满足不同合规性测试需求
|
||||
|
||||
## 技术栈
|
||||
- Python Flask (Web界面)
|
||||
- Python测试框架
|
||||
- SQLite (用户认证)
|
||||
- 大语言模型API集成
|
||||
- Markdown和JSON格式的报告生成
|
||||
@@ -0,0 +1,89 @@
|
||||
# 系统架构与设计模式
|
||||
|
||||
## 系统架构概览
|
||||
|
||||
合规性测试工具采用了模块化的分层架构，主要由以下核心组件构成：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CLI[命令行接口\nrun_api_tests.py] --> Orch[测试编排器\nAPITestOrchestrator]
|
||||
Web[Web界面\nflask_app.py] --> Orch
|
||||
|
||||
Orch --> Parser[API规范解析器\nInputParser]
|
||||
Orch --> Registry[测试用例注册表\nTestCaseRegistry]
|
||||
Orch --> Caller[API调用器\nAPICaller]
|
||||
Orch --> LLM[LLM服务\nLLMService]
|
||||
|
||||
Registry --> TestCases[测试用例\nBaseAPITestCase子类]
|
||||
|
||||
Orch --> Reporter[测试报告生成器]
|
||||
```
|
||||
|
||||
## 关键技术决策
|
||||
|
||||
1. **模块化设计**：系统被分解为多个独立的模块，每个模块负责特定功能，便于维护和扩展。
|
||||
2. **插件式架构**：测试用例和测试阶段采用插件式设计，允许用户自定义和扩展。
|
||||
3. **配置驱动**：系统行为通过配置文件和命令行参数控制，无需修改代码即可调整。
|
||||
4. **双重接口**：同时提供Web界面和命令行接口，满足不同使用场景的需求。
|
||||
5. **LLM集成**：集成大语言模型API，实现智能测试数据生成。
|
||||
|
||||
## 设计模式应用
|
||||
|
||||
### 1. 工厂模式
|
||||
- **应用**：`InputParser`根据输入类型（YAPI/Swagger）创建对应的解析器。
|
||||
- **好处**：封装创建逻辑，客户端代码无需关心具体实现细节。
|
||||
|
||||
### 2. 策略模式
|
||||
- **应用**：不同的测试用例实现相同的接口（`BaseAPITestCase`），但有不同的验证逻辑。
|
||||
- **好处**：允许在运行时选择不同的算法，增强系统灵活性。
|
||||
|
||||
### 3. 观察者模式
|
||||
- **应用**：测试执行过程中的日志和进度更新通过事件通知机制传递给界面。
|
||||
- **好处**：解耦核心测试逻辑和界面展示，提高代码可维护性。
|
||||
|
||||
### 4. 模板方法模式
|
||||
- **应用**：`BaseAPITestCase`定义测试用例的基本流程和钩子方法，子类只需实现特定步骤。
|
||||
- **好处**：重用代码，确保所有测试用例遵循统一的执行流程。
|
||||
|
||||
### 5. 装饰器模式
|
||||
- **应用**：Web应用中的`@login_required`装饰器用于保护需要认证的路由。
|
||||
- **好处**：以非侵入方式为函数添加额外功能，如安全检查。
|
||||
|
||||
## 组件关系
|
||||
|
||||
### 测试编排器 (APITestOrchestrator)
|
||||
- **角色**：系统的核心控制器，协调各组件工作。
|
||||
- **职责**：初始化组件、解析API规范、筛选端点、执行测试用例、汇总结果。
|
||||
- **依赖**：依赖于`InputParser`、`TestCaseRegistry`、`APICaller`和可选的`LLMService`。
|
||||
|
||||
### 测试用例注册表 (TestCaseRegistry)
|
||||
- **角色**：发现和管理测试用例类。
|
||||
- **职责**：扫描指定目录、加载测试用例类、根据端点特征筛选适用的测试用例。
|
||||
- **依赖**：依赖于`BaseAPITestCase`的子类实现。
|
||||
|
||||
### API规范解析器 (InputParser)
|
||||
- **角色**：解析API定义文件。
|
||||
- **职责**：读取并解析YAPI或Swagger/OpenAPI格式的API规范文件，转换为内部数据结构。
|
||||
- **依赖**：无外部依赖。
|
||||
|
||||
### API调用器 (APICaller)
|
||||
- **角色**：执行HTTP请求。
|
||||
- **职责**：根据测试用例生成的请求数据发送HTTP请求，收集响应信息。
|
||||
- **依赖**：依赖于HTTP客户端库（如`requests`）。
|
||||
|
||||
### LLM服务 (LLMService)
|
||||
- **角色**：智能生成测试数据。
|
||||
- **职责**：根据API规范生成符合要求的请求参数和请求体。
|
||||
- **依赖**：依赖于外部LLM API服务。
|
||||
|
||||
## 数据流
|
||||
|
||||
1. 用户通过Web界面或命令行提供API规范文件和配置。
|
||||
2. 测试编排器使用InputParser解析API规范文件，获取API端点信息。
|
||||
3. 测试编排器根据配置筛选需要测试的端点。
|
||||
4. 对每个端点，测试编排器从TestCaseRegistry获取适用的测试用例。
|
||||
5. 测试用例生成请求数据（可能使用LLMService）。
|
||||
6. 测试编排器使用APICaller发送请求并收集响应。
|
||||
7. 测试用例验证响应是否符合预期。
|
||||
8. 测试编排器汇总所有测试结果，生成报告。
|
||||
9. 用户通过Web界面或输出文件查看测试结果。
|
||||
@@ -0,0 +1,88 @@
|
||||
# 技术上下文
|
||||
|
||||
## 技术栈概览
|
||||
|
||||
合规性测试工具基于以下技术栈构建：
|
||||
|
||||
| 类别 | 技术 | 版本 | 用途 |
|
||||
|------|------|------|------|
|
||||
| 核心语言 | Python | 3.8+ | 主要开发语言 |
|
||||
| Web框架 | Flask | 2.0+ | Web界面实现 |
|
||||
| 数据库 | SQLite | 3.0+ | 用户认证和会话管理 |
|
||||
| HTTP客户端 | Requests | 2.0+ | 发送API请求 |
|
||||
| AI集成 | LLM API (兼容OpenAI) | - | 智能测试数据生成 |
|
||||
| 前端 | HTML/CSS/JavaScript | - | Web界面展示 |
|
||||
| 报告格式 | JSON, Markdown | - | 测试报告生成 |
|
||||
|
||||
## 开发环境设置
|
||||
|
||||
### 必要组件
|
||||
- Python 3.8+
|
||||
- pip (Python包管理器)
|
||||
- 支持Python的IDE (如PyCharm, VS Code)
|
||||
- Git (版本控制)
|
||||
|
||||
### 项目安装步骤
|
||||
1. 克隆代码仓库：`git clone <仓库URL>`
|
||||
2. 安装依赖：`pip install -r requirements.txt`
|
||||
3. 初始化数据库：`flask --app flask_app init-db`
|
||||
4. 运行Web服务：`python flask_app.py`
|
||||
5. 运行命令行测试：`python run_api_tests.py [参数]`
|
||||
|
||||
### 关键依赖项
|
||||
项目的`requirements.txt`文件包含以下主要依赖：
|
||||
- Flask：Web框架
|
||||
- Werkzeug：WSGI实用工具库
|
||||
- requests：HTTP客户端
|
||||
- PyYAML：YAML解析
|
||||
- jsonschema：JSON Schema验证
|
||||
- pydantic：数据验证和设置管理
|
||||
- openai：OpenAI API客户端
|
||||
- Flask-Cors：处理跨域请求
|
||||
|
||||
## 技术约束
|
||||
|
||||
### 1. 性能考量
|
||||
- 测试执行过程可能涉及大量HTTP请求，需要考虑超时处理和重试机制
|
||||
- LLM API调用可能较慢，需要实现缓存机制避免重复生成
|
||||
- 测试报告可能很大，需要优化生成和展示方式
|
||||
|
||||
### 2. 安全考虑
|
||||
- 用户认证使用密码哈希存储，避免明文密码
|
||||
- API密钥等敏感信息需要安全存储
|
||||
- 上传的API规范文件需要验证格式和安全性
|
||||
|
||||
### 3. 兼容性要求
|
||||
- 支持解析YAPI和Swagger/OpenAPI规范（JSON/YAML格式）
|
||||
- 支持不同版本的OpenAPI规范（2.0/3.0）
|
||||
- 支持不同API认证方式（Basic, Bearer Token, API Key等）
|
||||
|
||||
### 4. 扩展性设计
|
||||
- 测试用例通过类继承机制支持自定义扩展
|
||||
- 测试阶段支持插件式扩展
|
||||
- LLM提供商可配置，支持不同模型
|
||||
|
||||
### 5. 网络依赖
|
||||
- 需要网络连接才能访问目标API服务
|
||||
- 使用LLM功能需要访问外部AI服务API
|
||||
|
||||
## 开发工作流
|
||||
|
||||
1. **代码组织**：
|
||||
- `flask_app.py`：Web界面入口
|
||||
- `run_api_tests.py`：命令行入口
|
||||
- `ddms_compliance_suite/`：核心测试框架
|
||||
- `custom_testcases/`：自定义测试用例
|
||||
- `custom_stages/`：自定义测试阶段
|
||||
- `test_reports/`：测试报告输出
|
||||
|
||||
2. **开发流程**：
|
||||
- 使用Git进行版本控制
|
||||
- 遵循PEP 8 Python编码规范
|
||||
- 编写单元测试验证核心功能
|
||||
- 文档驱动开发，保持代码和文档同步
|
||||
|
||||
3. **调试技巧**：
|
||||
- 使用日志记录关键信息
|
||||
- Flask调试模式提供详细错误信息
|
||||
- 测试用例可以单独运行进行调试
|
||||
Reference in New Issue
Block a user