syngenta/diffy

Diffy镜像文档

镜像概述

Diffy是一款专注于API差异化测试的工具，旨在通过对比多个环境（如生产、候选、基线）的API请求与响应，自动识别接口行为差异，帮助开发与测试团队验证API变更的正确性。本镜像特别支持接入外部数据库，解决了内置数据库的数据存储限制问题，便于测试数据持久化管理、多实例数据共享及大规模测试场景的数据扩展，提升测试环境的灵活性与可维护性。

核心功能与特性

• 多环境API响应对比：支持同时对比三个环境（基线、候选、生产）的API请求参数、响应状态码、响应头及响应体，精准识别差异点；
• 外部数据库集成：兼容主流关系型数据库（MySQL、PostgreSQL等），支持通过配置接入外部数据库，实现测试记录、差异结果的持久化存储；
• 差异可视化与分类：提供Web界面直观展示差异详情，支持按差异类型（内容差异、性能差异、结构差异等）分类，便于问题定位；
• 灵活的测试配置：支持自定义比较规则（如忽略特定字段、设置响应超时阈值），适配RESTful API、GraphQL等多种接口类型；
• 数据持久化与共享：通过外部数据库实现测试数据跨实例共享，避免容器重启导致的数据丢失，支持历史测试结果回溯与分析。

使用场景

• API变更验证：在API接口升级、重构或参数调整后，对比变更环境（候选）与稳定环境（基线）的响应差异，验证变更是否符合预期；
• 回归测试：在系统迭代过程中，定期运行Diffy对比当前环境与历史稳定版本，检测是否引入未预期的API行为退化；
• 多版本兼容性测试：对比不同版本API服务（如v1与v2）的响应，确保新版本对旧版本接口的兼容性；
• 分布式系统接口监控：持续监控多节点部署的API服务，识别节点间因配置或部署差异导致的接口行为不一致问题。

使用方法与配置说明

基本部署命令

通过docker run快速启动Diffy容器，需指定外部数据库连接参数及必要端口映射：

bash
docker run -d \
  --name diffy \
  -p 8888:8888 \  # Web界面端口
  -e DB_TYPE=mysql \  # 数据库类型，支持mysql/postgresql
  -e DB_HOST=your-db-host \  # 外部数据库主机地址
  -e DB_PORT=3306 \  # 数据库端口
  -e DB_USER=diffy_user \  # 数据库用户名
  -e DB_PASS=diffy_password \  # 数据库密码
  -e DB_NAME=diffy_db \  # 数据库名称（需提前创建）
  -v /local/path/to/config:/app/config \  # 挂载自定义配置文件（可选）
  diffy:latest

环境变量配置

配置文件挂载（可选）

如需更复杂的测试配置（如自定义比较规则、API路径过滤），可通过挂载配置文件实现。创建本地配置文件（如diffy.config），内容示例：

json
{
  "comparison": {
    "ignoreFields": ["timestamp", "requestId"],  // 比较时忽略的字段
    "timeoutMillis": 5000  // 响应超时阈值（毫秒）
  },
  "endpoints": {
    "includePatterns": ["/api/v1/.*"],  // 包含的API路径正则
    "excludePatterns": ["/api/v1/health"]  // 排除的API路径正则
  }
}

挂载配置文件到容器内/app/config目录：

bash
-v /local/path/to/diffy.config:/app/config/diffy.config

访问与使用

容器启动后，通过http://<主机IP>:8888访问Diffy Web界面，配置测试环境、发起测试任务并查看差异结果。测试数据将自动存储至指定的外部数据库，可通过数据库工具直接查询历史记录。

注意事项

• 外部数据库需提前创建，Diffy将自动初始化所需表结构；
• 数据库连接参数需确保容器网络可访问目标数据库；
• 生产环境建议配合docker-compose管理，并配置数据库备份策略，确保测试数据安全。