高效模拟动态 URL 请求，requests-mock多阶段响应指南

引言：测试外部API的挑战与模拟需求

在开发过程中，我们的应用程序常常需要与外部服务（如 RESTful API）进行交互。然而，直接在测试环境中调用真实外部 API 会带来一系列问题：

• 不稳定性： 外部服务可能不稳定、响应慢或暂时不可用。
• 依赖性： 测试结果依赖于外部服务的状态和数据，导致测试不可重复。
• 成本： 某些 API 调用可能涉及费用或有调用频率限制。
• 安全性： 在测试中暴露敏感的 API 密钥或数据。

为了解决这些问题，我们通常会采用“模拟”（Mocking）技术。通过模拟外部 API 的行为，我们可以在受控的环境中执行测试，确保测试的独立性、可靠性和快速性。对于 Python 的 requests 库发起的 HTTP 请求，requests-mock 是一个功能强大且易于使用的模拟工具。

requests-mock 简介与基本用法

requests-mock 是一个用于模拟 requests 库请求的适配器。它允许你拦截 HTTP 请求并返回预定义的响应，而无需实际的网络连接。

安装：

pip install requests-mock

基本用法：requests-mock 通常作为上下文管理器使用，确保模拟行为仅在特定代码块内生效。

import requests
import requests_mock

def fetch_data(url):
    response = requests.get(url)
    response.raise_for_status() # Raise an exception for bad status codes
    return response.json()

# 测试示例
with requests_mock.Mocker() as m:
    m.get('http://test.com/api/data', json={'key': 'value'}, status_code=200)
    data = fetch_data('http://test.com/api/data')
    assert data == {'key': 'value'}

模拟动态 URL：正则表达式匹配

在许多场景中，我们请求的 URL 包含动态部分，例如分页参数、ID 或搜索关键词。直接匹配完整 URL 变得不切实际。requests-mock 支持使用正则表达式来匹配这类动态 URL。

假设我们有一个函数 consuming_api_swapi_index_page，它会循环请求 SWAPI 的分页接口，直到遇到非 200 状态码为止，并收集所有请求的 URL。

import requests
from http import HTTPStatus

def consuming_api_swapi_index_page(initial_page: int = 1):
    """Swapi index page."""
    check = HTTPStatus.OK
    results = []
    while check == HTTPStatus.OK:
        response = requests.get(
            f'https://swapi.dev/api/people/?page={initial_page}'
        )
        results.append(url := response.url) # response.url 会自动反映请求的真实URL
        check = response.status_code
        initial_page += 1
    return results

为了模拟 https://swapi.dev/api/people/?page=X 这种模式的 URL，我们可以使用 re.compile 创建一个正则表达式对象。

import requests_mock
import re
from http import HTTPStatus

# ... (consuming_api_swapi_index_page 函数定义同上) ...

def test_consuming_api_swapi_index_page_regex_mock() -> None:
    expected_urls = [
        'https://swapi.dev/api/people/?page=1',
        'https://swapi.dev/api/people/?page=2',
        # ... up to page 10
        'https://swapi.dev/api/people/?page=10',
    ]

    # 定义一个正则表达式来匹配所有分页 URL
    matcher = re.compile(r"https://swapi.dev/api/people/\?page=\d+")

    with requests_mock.Mocker() as m:
        # 注册一个 GET 请求的模拟，匹配上述正则表达式
        # 对于所有匹配的请求，都返回 HTTPStatus.OK (200) 和一个空的 JSON 对象
        # 注意：requests-mock 会自动将 response.url 设置为实际匹配到的请求 URL
        m.get(matcher, status_code=HTTPStatus.OK, json={})

        # 为了让循环在第11页停止，我们需要模拟第11页返回非200状态码
        # 精确匹配第11页的URL，并返回404
        m.get('https://swapi.dev/api/people/?page=11', status_code=HTTPStatus.NOT_FOUND)

        actual_urls = consuming_api_swapi_index_page()
        assert actual_urls == expected_urls

在这个例子中，m.get(matcher, ...) 会拦截所有匹配 matcher 正则表达式的 GET 请求。requests-mock 的一个便利之处在于，即使你使用正则表达式进行匹配，response.url 属性也会被设置为实际发起的请求 URL，这正是我们测试 results.append(url := response.url) 所需要的。

模拟多阶段响应：自定义回调函数

在更复杂的场景中，我们可能需要根据请求的具体内容（如 URL 参数、请求体）来返回不同的响应，或者模拟一系列按顺序发生的响应（例如分页数据、资源创建后的状态变化）。requests-mock 提供了 response_callback 参数，允许你定义一个函数来动态生成响应。

response_callback 函数接收两个参数：request (一个 requests.Request 对象，包含请求的所有信息) 和 context (一个 requests_mock.Mocker 内部的上下文对象，你可以设置 status_code, headers 等)。这个函数需要返回一个字典，其中包含 text、json 或 content 等响应数据。

让我们使用 response_callback 来更精确地模拟 SWAPI 的分页行为，包括在特定页数后终止循环。

import requests
import requests_mock
import re
from http import HTTPStatus

# ... (consuming_api_swapi_index_page 函数定义同上) ...

def test_consuming_api_swapi_index_page_with_callback() -> None:
    expected_urls = [
        'https://swapi.dev/api/people/?page=1',
        'https://swapi.dev/api/people/?page=2',
        'https://swapi.dev/api/people/?page=3',
        'https://swapi.dev/api/people/?page=4',
        'https://swapi.dev/api/people/?page=5',
        'https://swapi.dev/api/people/?page=6',
        'https://swapi.dev/api/people/?page=7',
        'https://swapi.dev/api/people/?page=8',
        'https://swapi.dev/api/people/?page=9',
        'https://swapi.dev/api/people/?page=10',
    ]

    # 定义正则表达式匹配分页URL，并捕获页码
    matcher = re.compile(r"https://swapi.dev/api/people/\?page=(\d+)")

    def swapi_pagination_callback(request, context):
        """
        根据请求的页码动态生成响应。
        当页码在1到10之间时，返回200 OK。
        当页码大于10时，返回404 Not Found以终止循环。
        """
        # 从请求URL中解析页码
        match = re.search(r'page=(\d+)', request.url)
        page_num = int(match.group(1)) if match else 1

        if 1 <= page_num <= 10:
            context.status_code = HTTPStatus.OK
            # 返回一个模拟的SWAPI响应体，虽然本例中不使用其内容，但保持API一致性
            # 真实的SWAPI在最后一页会返回 "next": null
            # 这里我们只关注status_code来控制循环
            return {
                'count': 82,
                'next': f'https://swapi.dev/api/people/?page={page_num + 1}' if page_num < 10 else None,
                'previous': None if page_num == 1 else f'https://swapi.dev/api/people/?page={page_num - 1}',
                'results': [] # 简化结果，实际测试中可能需要模拟具体数据
            }
        else:
            # 当请求的页码超出预期范围时，返回非200状态码，终止循环
            context.status_code = HTTPStatus.NOT_FOUND
            return {'detail': 'Not found'}

    with requests_mock.Mocker() as m:
        # 注册 GET 请求，使用回调函数动态生成 JSON 响应
        m.get(matcher, json=swapi_pagination_callback)

        actual_urls = consuming_api_swapi_index_page()
        assert actual_urls == expected_urls

在这个增强的例子中，swapi_pagination_callback 函数能够检查 request.url 来确定当前请求的页码。根据页码，它会设置 context.status_code 并返回相应的 JSON 响应。这种方式极大地提高了模拟的灵活性和真实性。

注意事项与最佳实践

• 模拟的粒度： 尽量只模拟你代码中实际使用的外部 API 部分。过度模拟会使测试变得脆弱，难以维护。
• 上下文管理器： 始终使用 with requests_mock.Mocker() as m: 形式，确保模拟只在测试函数或测试方法的作用域内生效，避免对其他测试产生副作用。
• 匹配的特异性： 当有多个模拟规则时，requests-mock 会尝试找到最具体的匹配。如果存在通用正则表达式匹配和精确 URL 匹配，精确匹配会优先。在需要终止循环的场景中，精确匹配一个“结束”URL（如 page=11）并返回非 200 状态码，是控制循环的好方法。
• 断言 response.url： 如示例所示，requests-mock 会自动将模拟响应的 url 属性设置为发起请求的 URL，这使得测试依赖 response.url 的逻辑变得简单。
• 模拟响应内容： 根据需要使用 text、json 或 content 参数来提供模拟的响应体。对于 JSON API，推荐使用 json 参数，它会自动设置 Content-Type 头部。
• 模拟状态码和头部： 使用 status_code 和 headers 参数来模拟不同的 HTTP 状态码和响应头部，以测试错误处理、重定向等场景。

总结

requests-mock 是一个强大的工具，可以极大地简化涉及 requests 库的网络请求的单元测试。通过掌握正则表达式匹配和自定义回调函数，你可以灵活地模拟各种复杂的 API 交互场景，包括动态 URL、多阶段响应和错误条件。这不仅能提高测试的效率和可靠性，还能加速开发进程，让你能够专注于业务逻辑的实现，而无需担心外部依赖的干扰。