跳转到正文
API 101
本文目录

第 86 篇

持续集成与 API 测试

构建可靠的 API,除了写好代码,还要在问题进入生产环境前发现它。持续集成(CI)把自动化测试放进日常交付流程,帮助团队更快发布,同时维持质量。本文从基本的健康检查讲起,介绍如何逐步把更全面的契约测试纳入流水线。

什么是 API 的持续集成?

持续集成指代码提交到版本控制后,自动触发构建、测试和验证。在 API 开发中,可以为每个拉取请求配置一套自动化测试,用来检查 API 是否仍按预期运行。

目标是及早发现破坏性变更,避免演变成客户能感知的故障。新增端点、修改响应结构或更新身份认证逻辑时,CI 流水线可以立即根据现有契约和预期行为验证这些改动。

成熟的 API CI 流水线通常包括:

  • 单元测试,验证单个函数和业务逻辑。
  • 集成测试,确认 API 端点能正确连接数据库和外部服务。
  • 契约测试,检查 API 是否履行已发布的约定。
  • 性能测试,发现响应时间或吞吐量退化。
  • 安全测试,检查漏洞和授权问题。

为什么要在 CI 中测试 API?

API 的破坏性变更往往代价不低。前端依赖的响应结构意外变化,应用可能崩溃;身份认证流程出错,用户可能无法登录;性能下降也会影响客户体验。

仅依赖人工测试或预发布验证,往往要等到多个改动累积后才能发现问题。这时很难定位究竟是哪次提交引入了缺陷。

在 CI 中测试可以把检测提前。提交后的几分钟内,团队就有机会收到反馈,此时上下文还清楚,修复也相对容易。这种反馈机制带来几项收益:

  • 迭代更快,开发者重构时可以依靠测试发现回归。
  • 协作更顺畅,前后端团队可依据稳定的 API 契约并行推进。
  • 发布更稳妥,上线前可完成数百项自动验证。
  • 文档与行为同步,测试用例也能作为描述预期行为的可执行规范。

搭建 API 测试流水线

流水线要在覆盖范围和反馈速度之间取舍。验证要足够全面,也要及时完成,让开发者能继续手头的工作。

API 测试金字塔

可以参考测试金字塔来组织用例。下面的比例用来说明各层的相对规模,具体比例按项目调整。

单元测试(底层,约 70%):快速、隔离地验证单个函数或方法,不访问数据库或外部服务,适合检查业务逻辑、数据转换和边界情况。这些用例通常可在毫秒级给出反馈。

集成测试(中间层,约 20%):使用真实依赖测试完整端点,验证 API 与数据库、消息队列和第三方服务的交互。这些用例通常按秒计,能发现单元测试覆盖不到的问题。

端到端测试(顶层,约 10%):跨多个端点模拟真实用户的完整流程,耗时相对最长,但有助于确认功能符合用户预期。

CI 流水线的主要阶段

典型的 API 测试流水线包含以下阶段。

阶段 1:构建和编译

  • 安装依赖。
  • 编译代码。
  • 运行代码检查与静态分析。
  • 检查代码格式。

阶段 2:单元测试

  • 执行单元测试套件。
  • 生成代码覆盖率报告。
  • 覆盖率低于项目阈值时让构建失败。例如,可以设为 80%;实际阈值应结合项目风险。

阶段 3:集成测试

  • 启动测试数据库和其他依赖,通常可使用 Docker 容器。
  • 对真实服务运行集成测试。
  • 验证数据库迁移。
  • 测试错误处理和边界情况。

阶段 4:契约测试

  • 验证 OpenAPI 或 Swagger 规范文件。
  • 对照规范运行契约测试。
  • 检查 API 结构是否有破坏性变更。
  • 验证向后兼容性。

阶段 5:性能测试

  • 运行性能基准测试。
  • 测量不同负载下的响应时间。
  • 响应时间超过阈值时让该阶段失败。
  • 检测内存泄漏或资源问题。

阶段 6:安全扫描

  • 使用 OWASP 相关工具检查依赖。
  • 扫描 SQL 注入和 XSS 等漏洞。
  • 验证身份认证与授权逻辑。
  • 检查是否暴露密钥或凭据。

API 测试策略与工具

不同方法对应不同目标。组合多种策略,可以扩大验证范围。

契约测试

契约测试用来检查实现是否符合已发布的规范。例如,OpenAPI 约定 user 对象包含 id、email 和 created_at,测试就应核对实际响应中的字段和类型,并按契约判断额外字段是否允许。

下面的 Bash 片段用 Prism 启动 OpenAPI 模拟服务,再用 Newman 验证测试集合能否请求该服务。运行前需安装 Prism 和 Newman,并让 ci.env.json 中的测试地址指向本地 4010 端口。要验证实现是否遵守契约,还需要测试实际服务,例如用 Prism 验证代理或 Pact 提供方验证。

1set -eu
2prism mock -h 127.0.0.1 -p 4010 openapi.yaml &
3prism_pid=$!
4trap 'kill "$prism_pid" 2>/dev/null || true' EXIT
5
6# Any HTTP response confirms that the mock is listening.
7curl --silent --show-error --output /dev/null --max-time 2 \
8  --retry 15 --retry-connrefused --retry-delay 1 http://127.0.0.1:4010/
9newman run api-tests.json --environment ci.env.json --reporters cli,json

Pact 支持消费者驱动的契约测试。前端团队可以定义后端需要满足的预期,便于在后端改动破坏前端假设时及时发现问题。

功能测试

功能测试用来验证端点在给定输入下是否产生正确输出。它请求实际端点,并对响应状态码、响应头和响应体进行断言。

1// Example functional test using Jest and Supertest
2describe('POST /api/users', () => {
3  it('creates a new user with valid data', async () => {
4    const response = await request(app)
5      .post('/api/users')
6      .send({
7        email: 'test@example.com',
8        name: 'Test User'
9      })
10      .expect(201);
11
12    expect(response.body).toHaveProperty('id');
13    expect(response.body.email).toBe('test@example.com');
14  });
15
16  it('returns 400 for invalid email', async () => {
17    await request(app)
18      .post('/api/users')
19      .send({
20        email: 'invalid-email',
21        name: 'Test User'
22      })
23      .expect(400);
24  });
25});

Postman/Newman、REST Assured、Supertest 和 Pytest 可用于编写和运行 API 功能测试,也可集成到 CI 流水线中输出失败信息。

负载与性能测试

性能测试用来检查 API 在预期负载下的响应时间是否可接受。由于消耗资源较多,这类测试通常安排在夜间等定时任务中。

1// Example k6 load test
2import http from 'k6/http';
3import { check, sleep } from 'k6';
4
5export let options = {
6  vus: 100, // 100 virtual users
7  duration: '30s',
8  thresholds: { checks: ['rate>0.99'] },
9};
10
11export default function() {
12  let res = http.get('https://api.example.com/users');
13  check(res, {
14    'status is 200': (r) => r.status === 200,
15    'response time < 200ms': (r) => r.timings.duration < 200,
16  });
17  sleep(1);
18}

示例检查状态码和 200 毫秒的响应时间目标。单独使用 check() 不会使测试失败。这里把全部检查的通过率作为阈值:通过率未超过 99% 时,k6 以非零状态退出。实际阈值应按服务目标设置。参见 k6 阈值文档。k6、Apache JMeter 和 Gatling 都可用来开展负载测试,获取吞吐量、响应时间和失败率等数据。

安全测试

安全测试可以帮助发现注入攻击、身份认证缺陷和敏感数据暴露等常见问题。适合按提交运行的检查应尽早加入流水线。

例如,可以把 OWASP ZAP 集成到 CI 中扫描 API。基线扫描与从 OpenAPI 描述导入端点的 API Scan 用途不同。下例是主动扫描,仅限已获授权的测试环境;替换占位地址,并确认规范中的服务器地址也指向该环境。请固定经审查的镜像版本。扫描不能代替对授权逻辑的专项测试。

1# Active scan against an authorized test deployment only
2docker run --rm -v "$PWD:/zap/wrk/:rw" \
3  ghcr.io/zaproxy/zaproxy:stable zap-api-scan.py \
4  -t https://api.example.com/openapi.json -f openapi \
5  -r zap-report.html

CI 中开展 API 测试的实践建议

1. 缩短反馈时间。 可把单元测试控制在 10 秒以内、集成测试控制在 2 分钟以内作为目标,结合并行执行和优化测试数据初始化来缩短等待。

2. 让测试可重复。 不稳定的用例会削弱团队信任。尽量避免依赖时钟的断言,准备可控的测试数据,并对不可靠的外部服务使用模拟。

3. 同时测试失败路径。 除了成功请求,还应检查 API 是否在适用场景返回 400、401、403、404 或 500,并附上有助于排查的错误信息。

4. 隔离测试数据。 让每个用例自行创建和清理数据,避免共享状态带来的依赖和排查困难。

5. 对 API 契约进行版本管理。 将 OpenAPI 文件和代码一同纳入版本控制,便于运行契约测试并追溯 API 的演变。

6. 跟踪覆盖率。 覆盖率无需追求 100%。优先覆盖关键业务逻辑、身份认证和数据校验路径。

7. 并行执行。 可以将测试套件分配到多个执行单元上,缩短流水线运行时间。

8. 在合适的环境中使用真实依赖。 模拟服务有其用途;集成测试也要用真实数据库和服务检查交互问题,例如在容器中启动测试依赖。

在 CI/CD 中验证 API 网关配置

使用 Apache APISIX 等 API 网关时,测试范围还包括网关配置。路由、插件、身份认证策略和限流规则的改动,都需要纳入验证。

下面的 GitHub Actions 片段展示了启动网关、配置路由、执行集成测试和检查限流的过程。实际使用时需要仓库中的 Compose 文件、路由定义、测试脚本和测试环境凭据。示例只在 main 分支收到推送时运行,使用专用测试密钥,不向外部 PR 暴露管理凭据。Compose 文件需用同一测试密钥配置 APISIX,仅在本机暴露 Admin API,并提供测试依赖。

1# Example GitHub Actions workflow for APISIX testing
2name: API Gateway Tests
3
4on:
5  push:
6    branches: [main]
7
8jobs:
9  test:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v6
13
14      - name: Start APISIX
15        env:
16          APISIX_ADMIN_KEY: ${{ secrets.APISIX_ADMIN_KEY }}
17        run: |
18          docker compose up -d apisix etcd
19
20      - name: Configure routes
21        env:
22          APISIX_ADMIN_KEY: ${{ secrets.APISIX_ADMIN_KEY }}
23        run: |
24          curl --fail --silent --show-error --retry 15 --retry-all-errors \
25            --retry-delay 1 --max-time 5 \
26            -H "X-API-KEY: $APISIX_ADMIN_KEY" \
27            http://127.0.0.1:9180/apisix/admin/routes > /dev/null
28          curl --fail-with-body --silent --show-error \
29            -H "X-API-KEY: $APISIX_ADMIN_KEY" \
30            -H "Content-Type: application/json" \
31            -X PUT -d @routes/user-service.json \
32            http://127.0.0.1:9180/apisix/admin/routes/1
33
34      - name: Run integration tests
35        run: |
36          pytest tests/integration/ -v
37
38      - name: Test rate limiting
39        run: |
40          python tests/load/test_rate_limits.py

这样可以在网关配置上线前检查路由、身份认证和限流行为是否发生回归。

总结

持续集成把 API 测试从一次人工检查变成持续运行的反馈机制。自动验证代码变更,有助于团队及早发现问题,更稳妥地部署和迭代。

可以先在 CI 中加入基本的端点测试,随后随着 API 成熟,逐步加入契约测试、性能基准和安全扫描。持续维护测试与生产代码同样重要。测试能够快速、可靠地反馈问题时,才能真正帮助团队加快交付。

编辑本篇文章

获取方案