ruoyunbai/compliance

Fork 0

gongwenxin 6d0b70fe11 v0-json-schema

2025-05-16 15:18:02 +08:00

14 KiB

Raw Blame History

规则库增强设计与用法指南

概述

DDMS合规性验证软件的规则库是整个系统的核心组件，用于存储、管理和执行各种验证规则。本文档介绍了规则库的增强设计，包括新增的规则类型、生命周期和作用域支持、YAML规则格式等特性，以及如何使用这些新功能。

增强特性

1. 规则生命周期

规则生命周期定义了规则在API测试流程中的适用阶段，使规则执行更加精确和高效。规则生命周期包括以下几个阶段：

请求准备阶段 (RequestPreparation): 在构建和发送API请求之前执行的规则，用于验证请求URL、请求头、请求参数等是否符合要求。
请求执行阶段 (RequestExecution): 在发送API请求过程中执行的规则，用于监控请求的执行过程。
响应验证阶段 (ResponseValidation): 在接收到API响应后执行的规则，用于验证响应状态码、响应头、响应体等是否符合要求。
后处理阶段 (PostValidation): 在完成响应验证后执行的规则，用于执行一些清理或记录工作。
任意阶段 (AnyStage): 不关注具体执行阶段的通用规则。

2. 规则作用域

规则作用域定义了规则针对的具体对象，使规则的应用更加精确。规则作用域包括以下几个类型：

请求URL (RequestURL): 规则验证请求的URL是否符合要求，如是否符合RESTful设计规范等。
请求头 (RequestHeaders): 规则验证请求头是否符合要求，如是否包含必要的认证信息等。
请求参数 (RequestParams): 规则验证请求参数是否符合要求，如参数格式、必填项等。
请求体 (RequestBody): 规则验证请求体是否符合要求，如必要的字段、格式等。
响应状态码 (ResponseStatus): 规则验证响应状态码是否符合要求，如是否为200、404等特定状态码。
响应头 (ResponseHeaders): 规则验证响应头是否符合要求，如是否包含跨域头等。
响应体 (ResponseBody): 规则验证响应体是否符合要求，如必要的字段、格式等。
响应时间 (ResponseTime): 规则验证API响应时间是否在允许的范围内。
安全性 (Security): 规则验证API安全相关的要求，如是否使用HTTPS、是否包含认证信息等。
性能 (Performance): 规则验证API性能相关的要求，如响应时间、资源消耗等。
任意作用域 (AnyScope): 不关注具体作用域的通用规则。

3. 新增规则类型

为了满足不同场景的验证需求，增强了以下规则类型：

性能规则 (PerformanceRule): 用于验证API性能相关的指标，如响应时间、吞吐量等。
安全规则 (SecurityRule): 用于验证API安全相关的要求，如HTTPS强制、认证授权等。
RESTful设计规则 (RESTfulDesignRule): 用于验证API URL设计是否符合RESTful规范。
错误处理规则 (ErrorHandlingRule): 用于验证API错误响应是否符合标准格式和处理方式。

4. YAML规则格式

为了提高规则的可读性和可维护性，增加了对YAML格式规则的支持。YAML格式的规则可以直接嵌入Python代码，实现更灵活的验证逻辑。

规则示例

性能规则示例

id: response-time-threshold
name: 响应时间阈值规则
description: 验证API响应时间是否在允许的范围内
category: Performance
version: 1.0.0
severity: warning
is_enabled: true
tags:
  - performance
  - response-time
target_type: APIResponse
lifecycle: ResponseValidation
scope: ResponseTime
threshold: 500  # 毫秒
metric: response_time
unit: ms
code: |
  def validate(context):
      response = context.get('api_response')
      if not response:
          return {'is_valid': False, 'message': '缺少API响应对象'}
          
      response_time = response.elapsed_time * 1000  # 转换为毫秒
      threshold = context.get('threshold', 500)  # 默认500毫秒
      
      if response_time > threshold:
          return {
              'is_valid': False, 
              'message': f'响应时间 {response_time:.2f}ms 超过阈值 {threshold}ms',
              'details': {
                  'actual_time': response_time,
                  'threshold': threshold,
                  'unit': 'ms'
              }
          }
      
      return {
          'is_valid': True,
          'message': f'响应时间 {response_time:.2f}ms 在阈值 {threshold}ms 内',
          'details': {
              'actual_time': response_time,
              'threshold': threshold,
              'unit': 'ms'
          }
      }

安全规则示例

id: https-only-rule
name: HTTPS强制使用规则
description: 验证API是否只使用HTTPS协议，确保通信安全
category: Security
version: 1.0.0
severity: error
is_enabled: true
tags:
  - security
  - https
  - encryption
target_type: APIRequest
lifecycle: RequestPreparation
scope: Security
check_type: transport_security
expected_value: https
code: |
  def validate(context):
      request = context.get('api_request')
      if not request:
          return {'is_valid': False, 'message': '缺少API请求对象'}
          
      url = str(request.url)
      
      if not url.startswith('https://'):
          return {
              'is_valid': False, 
              'message': 'API请求必须使用HTTPS协议',
              'details': {
                  'current_url': url,
                  'expected_protocol': 'https'
              }
          }
      
      return {
          'is_valid': True,
          'message': 'API请求使用了HTTPS协议',
          'details': {
              'url': url
          }
      }

RESTful设计规则示例

id: restful-url-pattern
name: RESTful URL设计规则
description: 验证API URL是否符合RESTful设计规范
category: APIDesign
version: 1.0.0
severity: warning
is_enabled: true
tags:
  - restful
  - api-design
  - url-pattern
target_type: APIRequest
lifecycle: RequestPreparation
scope: RequestURL
design_aspect: URL设计
pattern: "^/api/v\\d+/[a-z0-9-]+(/[a-z0-9-]+)*$"
code: |
  import re
  
  def validate(context):
      request = context.get('api_request')
      if not request:
          return {'is_valid': False, 'message': '缺少API请求对象'}
          
      url = str(request.url)
      
      # 解析URL，获取路径部分
      from urllib.parse import urlparse
      parsed_url = urlparse(url)
      path = parsed_url.path
      
      # 使用正则表达式验证路径
      pattern = context.get('pattern', "^/api/v\\d+/[a-z0-9-]+(/[a-z0-9-]+)*$")
      if not re.match(pattern, path):
          return {
              'is_valid': False, 
              'message': 'API URL不符合RESTful设计规范',
              'details': {
                  'current_path': path,
                  'expected_pattern': pattern,
                  'suggestion': '路径应该遵循 /api/v{version}/{资源}[/{id}] 格式'
              }
          }
      
      return {
          'is_valid': True,
          'message': 'API URL符合RESTful设计规范',
          'details': {
              'path': path
          }
      }

错误处理规则示例

id: standard-error-response
name: 标准错误响应格式规则
description: 验证API错误响应是否符合标准格式
category: ErrorHandling
version: 1.0.0
severity: warning
is_enabled: true
tags:
  - error-handling
  - response-format
target_type: APIResponse
lifecycle: ResponseValidation
scope: ResponseBody
error_code: "*"  # 匹配所有错误码
expected_status: -1  # 不验证状态码
code: |
  def validate(context):
      response = context.get('api_response')
      if not response:
          return {'is_valid': False, 'message': '缺少API响应对象'}
          
      # 只检查4xx和5xx状态码的响应
      if response.status_code < 400:
          return {'is_valid': True, 'message': '非错误响应，跳过验证'}
          
      # 确保响应包含JSON内容
      if not response.json_content:
          return {
              'is_valid': False, 
              'message': '错误响应不是有效的JSON格式',
              'details': {
                  'status_code': response.status_code,
                  'content_type': response.headers.get('Content-Type', '未知')
              }
          }
      
      # 检查错误响应的必要字段
      required_fields = ['code', 'message']
      missing_fields = [field for field in required_fields if field not in response.json_content]
      
      if missing_fields:
          return {
              'is_valid': False, 
              'message': '错误响应缺少必要字段',
              'details': {
                  'missing_fields': missing_fields,
                  'required_fields': required_fields,
                  'response': response.json_content
              }
          }
      
      return {
          'is_valid': True,
          'message': '错误响应符合标准格式',
          'details': {
              'status_code': response.status_code,
              'error_code': response.json_content.get('code'),
              'error_message': response.json_content.get('message')
          }
      }

使用方法

1. 创建规则

可以通过以下两种方式创建规则：

编程方式创建：通过实例化规则类来创建规则对象，然后使用规则库的save_rule方法保存。

from ddms_compliance_suite.models.rule_models import PerformanceRule, RuleCategory, TargetType, RuleLifecycle, RuleScope

# 创建性能规则
performance_rule = PerformanceRule(
    id="response-time-max-500ms",
    name="响应时间不超过500毫秒",
    description="验证API响应时间不超过500毫秒",
    category=RuleCategory.PERFORMANCE,
    severity="warning",
    target_type=TargetType.API_RESPONSE,
    lifecycle=RuleLifecycle.RESPONSE_VALIDATION,
    scope=RuleScope.RESPONSE_TIME,
    threshold=500,
    metric="response_time",
    unit="ms"
)

# 保存规则
rule_repository.save_rule(performance_rule)

YAML文件创建：将规则定义为YAML文件，存放在规则库的目录结构中。

YAML规则文件存放路径: rules/yaml_rules/{category}/{rule_id}/{version}.yaml

2. 查询规则

可以使用规则库的query_rules方法查询规则，支持按规则类别、目标类型、生命周期、作用域等条件筛选。

from ddms_compliance_suite.models.rule_models import RuleQuery, RuleCategory, TargetType, RuleLifecycle, RuleScope

# 查询所有API响应验证阶段的性能规则
query = RuleQuery(
    category=RuleCategory.PERFORMANCE,
    target_type=TargetType.API_RESPONSE,
    lifecycle=RuleLifecycle.RESPONSE_VALIDATION,
    scope=RuleScope.RESPONSE_TIME,
    is_enabled=True
)

rules = rule_repository.query_rules(query)
print(f"找到 {len(rules)} 条规则")

3. 执行规则

可以使用规则执行引擎的execute_rule方法执行单个规则，或使用execute_rules_for_lifecycle方法执行特定生命周期阶段的所有规则。

from ddms_compliance_suite.rule_executor.executor import RuleExecutor

# 创建规则执行引擎
executor = RuleExecutor(rule_repository)

# 执行单个规则
result = executor.execute_rule(rule, context)
print(f"规则 '{result.rule_name}' 结果: {'通过' if result.is_valid else '失败'} - {result.message}")

# 执行特定生命周期阶段的所有规则
results = executor.execute_rules_for_lifecycle(RuleLifecycle.RESPONSE_VALIDATION, context)
for result in results:
    print(f"规则 '{result.rule_name}' 结果: {'通过' if result.is_valid else '失败'} - {result.message}")

4. 在测试中使用规则

可以在API测试流程中集成规则验证，以确保API请求和响应符合规范要求。

from ddms_compliance_suite.api_caller.caller import APICaller, APIRequest
from ddms_compliance_suite.rule_executor.executor import RuleExecutor

# 创建API调用器
api_caller = APICaller()

# 创建API请求
request = APIRequest(
    method="GET",
    url="https://api.example.com/api/v1/users/123",
    headers={"Content-Type": "application/json"}
)

# 执行请求准备阶段的规则
context = {"api_request": request}
prep_results = executor.execute_rules_for_lifecycle(RuleLifecycle.REQUEST_PREPARATION, context)
for result in prep_results:
    print(f"规则 '{result.rule_name}' 结果: {'通过' if result.is_valid else '失败'} - {result.message}")

# 发送API请求
response = api_caller.call_api(request)

# 执行响应验证阶段的规则
context["api_response"] = response
resp_results = executor.execute_rules_for_lifecycle(RuleLifecycle.RESPONSE_VALIDATION, context)
for result in resp_results:
    print(f"规则 '{result.rule_name}' 结果: {'通过' if result.is_valid else '失败'} - {result.message}")

最佳实践

合理组织规则：按照规则类别、生命周期和作用域组织规则，使规则库结构清晰。
使用标签：为规则添加标签，方便按照特定主题或功能筛选规则。
合理设置优先级：为规则设置合理的严重性级别，以便于区分重要规则和次要规则。
编写清晰的规则描述：为规则提供清晰的描述，使其他开发者能够理解规则的用途和行为。
使用YAML格式：对于复杂的验证逻辑，优先使用YAML格式的规则，便于维护和调试。
避免硬编码：在规则中避免硬编码具体的验证标准，而是通过规则属性来配置。
定期维护规则库：随着API的演进，定期更新和维护规则库，确保规则始终有效。

结论

规则库的增强设计为API测试提供了更强大、更灵活的验证能力，使得DDMS合规性验证软件能够更精确地验证API接口的行为，确保其符合平台定义的数据共享标准和技术规范。通过合理组织和使用规则，可以显著提高API测试的效率和质量。

14 KiB Raw Blame History Unescape Escape