1. 项目概述
最近在团队内部推动接口自动化测试落地,目标是让API测试成为CI/CD流水线中不可分割的一环。经过技术选型,最终确定使用Apifox CLI+GitLab CI的方案。这套组合有几个显著优势:
- Apifox提供了从接口定义到测试的全流程支持
- CLI工具可以无缝集成到CI环境
- GitLab Runner的Docker执行器能提供干净的测试环境
- 测试报告可以直接集成到GitLab的Pipeline结果中
整个实施过程涉及到GitLab Runner部署、Apifox项目配置、测试场景设计、本地验证和CI集成等多个环节。下面我会详细记录每个环节的关键步骤和注意事项。
2. 环境准备
2.1 基础设施清单
在开始前需要确保以下基础设施就位:
| 类别 | 要求 | 验证方式 |
|---|---|---|
| 代码仓库 | GitLab 15.0+ | 访问/help页面查看版本 |
| 构建服务器 | 至少4核CPU/8GB内存 | lscpu和free -h命令 |
| Docker环境 | Docker 20.10+和Docker Compose | docker version和docker compose version |
| 网络连通性 | 能访问Apifox API和npm仓库 | curl -I https://api.apifox.com |
2.2 账号权限准备
需要提前申请好以下账号权限:
-
GitLab账号:
- 需要项目Maintainer权限
- CI/CD Variables的配置权限
- 新Runner的注册权限
-
Apifox账号:
- 专业版账号(CLI功能需要)
- 项目的管理员权限
- 能创建API访问令牌
权限申请小技巧:提前准备好项目说明文档,列出需要权限的具体用途,这样审批会更快。
3. GitLab Runner部署
3.1 Runner选型考量
我们选择使用Docker执行器部署专用Runner,主要基于以下考虑:
- 环境隔离:每个Job都在独立容器中运行,避免污染主机环境
- 资源控制:可以通过Docker限制CPU和内存使用
- 快速启动:利用Docker镜像缓存,比虚拟机启动更快
- 可移植性:配置可以快速迁移到其他主机
3.2 详细部署步骤
3.2.1 目录结构规划
建议采用以下目录结构,方便后续管理:
code复制~/runner/
├── config/ # 存放Runner配置文件
├── docker-compose.yml
├── register.sh # Runner注册脚本
└── env.sh # 环境变量配置
3.2.2 Docker Compose配置
docker-compose.yml关键配置:
yaml复制version: '3.8'
services:
gitlab-runner:
image: gitlab/gitlab-runner:alpine
container_name: api-test-runner
restart: unless-stopped
volumes:
- ./config:/etc/gitlab-runner
- /var/run/docker.sock:/var/run/docker.sock
environment:
- TZ=Asia/Shanghai
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
注意:必须挂载docker.sock文件,这样Runner才能在容器内启动其他容器
3.2.3 Runner注册脚本
register.sh主要内容:
bash复制#!/bin/bash
docker exec -it api-test-runner gitlab-runner register \
--non-interactive \
--url "https://gitlab.example.com" \
--registration-token "PROJECT_REGISTRATION_TOKEN" \
--executor "docker" \
--docker-image "maven:3.9-eclipse-temurin-17" \
--description "API Test Runner" \
--tag-list "api-test,docker" \
--run-untagged="true" \
--locked="false" \
--docker-volumes /var/run/docker.sock:/var/run/docker.sock
注册后可以在GitLab项目的CI/CD设置中看到新注册的Runner。
3.3 运维管理技巧
-
日志查看:
bash复制
docker logs -f api-test-runner -
配置备份:
bash复制cp -r config config.bak -
性能监控:
bash复制
docker stats api-test-runner -
常用命令:
- 重启Runner:
docker restart api-test-runner - 暂停服务:
docker stop api-test-runner - 升级版本:修改
docker-compose.yml中的镜像版本后重新up
- 重启Runner:
4. Apifox项目配置
4.1 测试场景设计原则
设计测试场景时遵循以下原则:
- 原子性:每个测试场景只验证一个业务功能
- 独立性:场景之间不依赖执行顺序
- 可重复性:每次执行结果应该一致
- 自描述性:通过命名就能知道测试目的
4.2 用户CRUD场景实现
4.2.1 创建用户接口
请求示例:
json复制{
"name": "测试用户",
"email": "test@example.com",
"age": 25
}
关键断言:
- 状态码=200
- 响应包含生成的用户ID
- 返回的用户名与请求一致
变量提取:
javascript复制// 后置脚本
pm.environment.set("userId", pm.response.json().data.id);
4.2.2 获取用户列表
分页参数处理:
json复制{
"page": 1,
"size": 10
}
断言设计:
- 返回的分页数据格式符合规范
- 总条数大于0
- 列表中的用户数据包含完整字段
4.2.3 用户详情校验
URL参数:
code复制/api/v1/users/{{userId}}
特殊断言:
javascript复制pm.test("用户ID匹配", function() {
var jsonData = pm.response.json();
pm.expect(jsonData.data.id).to.eql(pm.environment.get("userId"));
});
4.3 环境变量管理
建议将环境相关配置统一管理:
| 变量名 | 示例值 | 说明 |
|---|---|---|
| baseUrl | http://localhost:8080 | 服务基础地址 |
| apiPrefix | /api/v1 | API前缀 |
| dbTimeout | 5000 | 数据库查询超时(毫秒) |
技巧:为不同环境(dev/test/prod)创建不同的环境配置,运行时通过
--environment参数指定
5. 本地验证流程
5.1 Apifox CLI安装
推荐使用npm全局安装:
bash复制npm install -g apifox-cli --registry=https://registry.npmmirror.com
验证安装:
bash复制apifox --version
5.2 测试执行命令
完整测试命令示例:
bash复制apifox run \
--access-token $APIFOX_TOKEN \
--project-id $PROJECT_ID \
--environment dev \
-r cli,html,json,junit \
--reporter-html-export ./reports/report.html \
--reporter-json-export ./reports/report.json \
--reporter-junit-export ./reports/junit.xml
5.3 报告解读技巧
-
HTML报告:
- 查看可视化测试结果
- 分析请求/响应详情
- 检查断言失败原因
-
JUnit报告:
- 可以被Jenkins/GitLab等CI工具解析
- 提供标准的测试结果格式
- 方便集成到现有系统
-
JSON报告:
- 包含完整的测试元数据
- 适合进一步自动化处理
- 可以用于自定义报表生成
6. GitLab CI集成
6.1 完整CI配置
.gitlab-ci.yml关键部分:
yaml复制stages:
- build
- test
- api-test
- report
variables:
MAVEN_OPTS: "-Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository"
cache:
key: $CI_COMMIT_REF_SLUG
paths:
- .m2/repository/
- node_modules/
api-test:
stage: api-test
image: node:18-bullseye
services:
- name: maven:3.9-eclipse-temurin-17
alias: app-server
script:
- npm install -g apifox-cli
- apifox run --config apifox/apifox-cli.json
artifacts:
paths:
- reports/
expire_in: 1 week
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_COMMIT_BRANCH == "main"'
6.2 优化技巧
-
镜像选择:
- 使用node镜像而不是maven镜像作为主镜像
- 通过services启动Java服务容器
- 减少不必要的依赖下载
-
缓存策略:
- 缓存Maven本地仓库
- 缓存node_modules
- 根据分支设置缓存key
-
触发规则:
- MR时自动执行
- 主干提交时执行
- 避免在特性分支上浪费资源
7. 常见问题解决
7.1 网络问题
症状:npm install超时或失败
解决方案:
bash复制npm config set registry https://registry.npmmirror.com
npm config set disturl https://npmmirror.com/dist
npm config set sass_binary_site https://npmmirror.com/mirrors/node-sass
7.2 环境变量问题
症状:CI中获取不到环境变量
检查点:
- 变量是否设置为Protected
- 是否在正确的分支上运行
- 变量名是否拼写正确
7.3 测试稳定性问题
提升稳定性方法:
- 增加重试机制
- 添加合理的等待时间
- 确保测试数据独立性
- 清理测试产生的数据
8. 进阶优化方向
8.1 测试数据管理
建议方案:
- 使用专门的测试数据服务
- 每个测试场景有独立的数据集
- 实现自动清理机制
8.2 性能测试集成
可以在API测试后增加性能测试阶段:
yaml复制performance-test:
stage: test
script:
- apifox run --config apifox/performance-config.json
8.3 安全测试
集成OWASP ZAP等安全测试工具:
yaml复制security-test:
image: owasp/zap2docker-stable
script:
- zap-baseline.py -t http://app-server:8080
这套方案实施后,我们的API测试效率提升了60%以上,问题发现阶段从生产环境提前到了开发阶段。最大的收获是建立了可靠的API质量门禁,任何不达标的代码都无法进入主干分支。