企业官网建设流程全解析

我们上次把 pytest 的基础用法和接口测试的简单用例串了一遍，当时很多朋友留言说“不过瘾，还想看更深入的”。确实，光会写几个 test_ 开头的函数、跑一下 assert，那只是入了门。真正的接口测试框架，要解决的是用例组织、数据驱动、环境切换、报告集成、持续集成这一整套问题。这次我就接着往下写，把 pytest 在接口测试里的进阶玩法、项目落地经验和踩过的坑，一次性讲透。

这篇文章适合谁？已经会用 pytest 写简单用例、知道 requests 怎么发请求，但想把项目从“脚本”升级成“框架”的测试开发同学。内容会比较干，我尽量用实际项目里的代码片段来讲，而不是堆概念。

1. 接口测试框架的整体规划思路

1.1 为什么要从“脚本”走向“框架”

很多团队一开始做接口测试，都是 Postman 里调通了，然后复制成 Python 脚本，写个循环跑一遍。前期用例少还好，一旦接口数量上了百、参数组合多了，脚本维护成本会迅速失控。我见过最夸张的项目，一个 500 行的“接口测试总控脚本”，里面全是 if-else 分支，每次接口字段变动，改起来像拆炸弹。

pytest 真正厉害的地方不是“能跑测试”，而是它的插件生态和 fixture 机制，可以让用例代码和测试数据分离、让前置条件和后置清理变得规整、让报告可以直接给领导看。搭框架的意义在于：让测试逻辑可以复用，让数据改变不需要改代码，让新人接手时不用从头读一遍所有脚本。

1.2 适合 pytest 的接口测试项目结构

以我常用的一个项目模板为例，目录结构长这样：

api_test_project/ ├── api_pytest/ # 核心代码目录 │ ├── __init__.py │ ├── conftest.py # 全局 fixture │ ├── config.py # 环境配置、URL、超时等 │ ├── req/ # requests 封装的请求层 │ │ ├── __init__.py │ │ ├── base_req.py │ │ └── user_api.py │ ├── utils/ # 工具函数：日志、读取yaml、加解密等 │ ├── testcases/ # 测试用例目录 │ │ ├── test_login.py │ │ ├── test_order.py │ │ └── test_user.py │ └── test_data/ # 测试数据目录（yaml/json文件） │ ├── login_data.yaml │ └── order_data.yaml ├── reports/ # 测试报告输出目录 ├── pytest.ini # pytest 配置文件 └── requirements.txt

这里有几个关键设计点：

• apireq 目录放对接口的封装，一个接口一个函数或一个类。测试用例不直接调 requests.get()，而是调封装好的 user_api.get_user_info()。这样接口如果加了鉴权头、改了域名前缀，只改封装层，用例层不用动。
• test_data 用 yaml 而不是写死在代码里。用例里通过参数化读取，数据变更只需要改 yaml 文件。
• conftest.py 放全局 fixture，比如获取 token、数据库清理、日志初始化这些，不需要每个用例文件都 import。

注意：conftest.py 的文件名是固定的，pytest 会自动识别。它的作用域是目录级的：放在哪个目录，就对哪个目录下的用例生效。

1.3 pytest.ini 的配置技巧

pytest.ini 是 pytest 的配置文件，很多新手会忽略它。我建议至少配置这几个参数：

[pytest] testpaths = api_pytest/testcases addopts = -v -s --tb=short --maxfail=3 log_cli = true log_cli_level = INFO log_cli_format = %(asctime)s [%(levelname)s] %(message)s

• testpaths指定测试用例目录，这样在项目根目录直接敲 pytest 就能识别，不用每次 cd。
• addopts里加上--tb=short，失败的时候只看关键几行，不会刷满屏。
• --maxfail=3表示有 3 个用例失败就停，节省调试时间。真正跑全量回归的时候可以再临时去掉。

2. requests 封装与 pytest 的结合

2.1 封装 requests 的常见思路

requests 库本身封装得已经非常友好，但在项目里我还是建议做一层“会话封装”。它能解决接口测试中的三个共性问题：

1. 统一加鉴权头部：不需要每个用例手动带 token。
2. 统一日志输出：方便排查问题。
3. 统一响应断言入口：比如判断 status_code 和业务 code。

我来写一个基础封装，大家直接参考：

# api_pytest/req/base_req.py import requests import logging import json logger = logging.getLogger(__name__) class BaseReq: def __init__(self, base_url, token=None): self.base_url = base_url.rstrip("/") self.session = requests.Session() self.token = token self.default_headers = { "Content-Type": "application/json", "User-Agent": "api-test/1.0" } def _handle_headers(self, headers=None): h = dict(self.default_headers) if self.token: h["Authorization"] = f"Bearer {self.token}" if headers: h.update(headers) return h def request(self, method, url, **kwargs): full_url = f"{self.base_url}{url}" headers = self._handle_headers(kwargs.pop("headers", None)) logger.info(f"请求: {method.upper()} {full_url}, 参数: {kwargs}") resp = self.session.request(method, full_url, headers=headers, timeout=10, **kwargs) logger.info(f"响应: {resp.status_code} {resp.text[:500]}") return resp def get(self, url, **kwargs): return self.request("GET", url, **kwargs) def post(self, url, **kwargs): return self.request("POST", url, **kwargs)

有几个细节说明一下：

• 用requests.Session()而不是每次直接 requests.get()，能复用底层连接，跑大批量用例时性能更好；如果接口有 Cookie 态的保持，也会更省心。
• token 通过类属性传入，请求时自动加头，用例里完全不用关心鉴权这件事。
• timeout=10必须写。接口测试最怕的就是请求挂住不返回，白白等几十秒，超时能尽快暴露问题。
• 日志里只打resp.text[:500]，避免接口返回体过大时把日志文件撑爆。真实项目中大报文接口很常见，这个习惯建议从第一天就养成。

2.2 按模块拆分 API 封装

每类接口单独建一个文件，继承 BaseReq。比如用户模块：

# api_pytest/req/user_api.py from .base_req import BaseReq class UserApi(BaseReq): def get_user_info(self, user_id): return self.get(f"/api/v1/user/{user_id}") def update_user(self, user_id, payload): return self.post(f"/api/v1/user/{user_id}/update", json=payload)

这样的好处是：当一个接口变了，我只改这一个文件里的一个函数；用例层几乎不动。如果后端一次性改了 30 个接口，你去改 30 个 api 文件，总比在几百个用例里全局替换要清晰得多。

实际项目里，还可以用functools.lru_cache或类变量来存储 token，避免每个测试类都重新登录一遍。我一般是把BaseReq的实例做成 fixture 放在 conftest.py 里：

@pytest.fixture(scope="session") def req_obj(): token = get_token_from_login_api("admin", "123456") return UserApi(BASE_URL, token=token)

scope="session"意味着整个测试会话只创建一次实例，token 也只请求一次。几百个用例跑下来，登录接口只调一次，速度和资源占用都会好很多。

3. 数据驱动：用参数化代替重复代码

3.1 pytest 参数化的基础用法

pytest 的@pytest.mark.parametrize是接口测试里用得最多的装饰器。我来做个对比：

如果你有 5 组测试数据，最原始的写法是：

def test_login_success(): resp = api.login("admin", "123456") assert resp.json()["code"] == 0 def test_login_wrong_password(): resp = api.login("admin", "wrong") assert resp.json()["code"] == 1001

这种写 5 个用例可能存在两个问题：一是代码重复，二是数据混在代码里。用参数化改写：

import pytest from req.user_api import UserApi # 假设有这样一个实例 @pytest.mark.parametrize("username,password,expected_code", [ ("admin", "123456", 0), ("admin", "wrong", 1001), ("", "123456", 1002), ("normal_user", "password123", 0), ("admin", "", 1002), ]) def test_login(username, password, expected_code): resp = api.login(username, password) assert resp.json()["code"] == expected_code

这样数据一目了然，新增用例只需要在列表里加一行元组，不用再新增函数。用 pytest 跑的时候，每个参数组合都会显示为一个独立的用例，-v模式下可以清楚看到哪一组挂了。

3.2 从 yaml 文件读取测试数据

参数写死在代码里算是第二阶段的进步，但真实项目里测试数据的量往往很大，而且用例设计人员可能不会 Python，这时候就需要把数据挪到文件里。我的习惯是用 yaml，原因是它比 json 更可读，支持注释，层级缩进写起来很顺手。

下面是login_data.yaml的内容示例：

# 登录接口测试数据 test_login: - username: "admin" password: "123456" expected_code: 0 desc: "正确账号密码" - username: "admin" password: "wrong" expected_code: 1001 desc: "密码错误" - username: "" password: "123456" expected_code: 1002 desc: "用户名为空"

读取 yaml 并配合参数化的通用做法：

# api_pytest/utils/data_loader.py import yaml from pathlib import Path def load_yaml_data(file_name): file_path = Path(__file__).parent.parent / "test_data" / file_name with open(file_path, "r", encoding="utf-8") as f: return yaml.safe_load(f)

用例里这样写：

import pytest from utils.data_loader import load_yaml_data login_data = load_yaml_data("login_data.yaml")["test_login"] @pytest.mark.parametrize("data", login_data, ids=[d["desc"] for d in login_data]) def test_login_from_yaml(data): resp = api.login(data["username"], data["password"]) assert resp.json()["code"] == data["expected_code"]

ids参数的作用非常实用：跑 pytest 的时候，默认每个参数化用例显示为一长串数据值，你根本不知道挂的是哪组。加上ids后，用例 ID 就是 “正确账号密码”、“密码错误”这样一眼能看懂的名字。

提示：yaml 文件里放中文字段描述没有问题，但文件必须存成 UTF-8 编码，否则 Windows 上读取可能乱码。

3.3 数据驱动时如何做断言

接口测试的断言不能只断言 status_code。很多项目 HTTP 状态码永远是 200，真实业务结果在 body 的 code 字段里。我建议至少断言三个层级：

1. 网络层：status_code 等于期望值（一般接口约定 200 或 201）。
2. 业务层：body 里的 code、msg 或具体字段值。
3. 数据层：如果测试环境有数据库权限，关键的写操作可以把数据库里的真实落库数据也查出来比对。

对于复杂 JSON 结构，可以封装几个常用的断言工具函数：

def assert_json_value(resp_json, json_path, expected_value): """简单支持通过点号取深层字段，如 data.user.name""" obj = resp_json for key in json_path.split("."): obj = obj[key] assert obj == expected_value, f"JSON路径 {json_path} 期望 {expected_value}, 实际 {obj}"

实际用例里写assert_json_value(resp.json(), "data.order.status", "PAID")比写一长串的resp.json()["data"]["order"]["status"]可读性强得多。

4. conftest 与 fixture 的深度实战

4.1 fixture 的作用域和依赖

fixture 的 scope 常见的有四个：function（每个用例跑一次）、class（每个类跑一次）、module（每个模块跑一次）、session（整个 pytest 进程只跑一次）。

接口测试里我做这几个常用的：

# api_pytest/conftest.py import pytest import logging from req.user_api import UserApi from utils.config import BASE_URL, USERNAME, PASSWORD @pytest.fixture(scope="session") def api(): """整个测试会话共用的 API 对象""" return UserApi(BASE_URL) @pytest.fixture(scope="session") def auth_token(api): """登录获取 token，整个会话只登录一次""" resp = api.login(USERNAME, PASSWORD) assert resp.status_code == 200 token = resp.json()["data"]["token"] return token @pytest.fixture() def user_api(auth_token): """带 token 的 API 对象，每个用例单独一个实例""" return UserApi(BASE_URL, token=auth_token)

注意这里我故意把user_api的 scope 定义成默认的 function。因为虽然 token 是复用的，但有的用例会在请求时往 API 对象上挂临时状态，如果多个用例共享同一个对象，可能会互相污染。

4.2 用 fixture 做前置数据准备

接口测试不像单元测试，很多接口需要前置数据才能用。比如测试“取消订单”接口，你需要先有一个已创建的订单；测试“确认收货”，你需要先有已发货的订单。

传统做法是在用例里先调几个接口把数据准备出来，这会导致用例很长、且每条用例都在重复造数据。更好的做法是把“造数据”放进 fixture，并为不同场景设计不同的 fixture：

@pytest.fixture() def created_order(user_api, auth_token): """创建一个已支付订单，返回订单ID""" resp = user_api.create_order(payload={...}) order_id = resp.json()["data"]["order_id"] user_api.pay_order(order_id) yield order_id # 后置清理：将订单状态改为已取消或删除测试数据 user_api.cancel_order(order_id)

用例就变成了：

def test_cancel_created_order(created_order): resp = api.cancel_order(created_order) assert resp.json()["code"] == 0

这里yield之前的代码是前置准备，yield之后是后置清理。好处是：用例只关注自己要测的那一步，造数和清理逻辑被复用。

4.3 conftest 里写 hooks 做全局处理

除了 fixture，conftest 里还可以写 pytest 的钩子函数。比如我想在每个用例失败时自动截图（App 测试常用）或自动保存响应日志：

@pytest.hookimpl(hookwrapper=True) def pytest_runtest_makereport(item, call): outcome = yield report = outcome.get_result() if report.when == "call" and report.failed: # 这里可以记录失败时的请求和响应信息 logging.error(f"用例 {item.name} 执行失败") logging.error(f"失败信息: {report.longrepr}")

如果你在 conftest 里拿到当前测试用例的request或fixture缓存，还可以把关联的响应数据写到报告里。这属于锦上添花，但调试复杂接口时非常有用。

5. Allure 报告与 Jenkins 持续集成

5.1 Allure 报告的配置

pytest 自带的报告就是一段文本，适合开发者自己看。但你要把接口测试结果同步给产品、开发、领导，那就得用 Allure 或类似的可视化报告工具。

Allure 的配置步骤很简单：

pip install allure-pytest

运行时加参数：

pytest --alluredir=./allure-results # 生成报告页面 allure serve ./allure-results

如果希望用例有更好的报告展示效果，可以给用例加描述和 severity：

import allure @allure.title("取消已创建订单") @allure.severity(allure.severity_level.CRITICAL) @allure.description("验证已支付订单可以被取消，且取消后状态为CANCELLED") def test_cancel_created_order(created_order): resp = api.cancel_order(created_order) assert resp.json()["data"]["status"] == "CANCELLED"

运行之后，Allure 报告里就能看到每个用例的标题、描述、优先级，还能通过环境信息区分测试环境。

5.2 接口日志对接 Allure

我实际项目中会在 BaseReq 的 request 方法里把请求和响应信息 attach 到 Allure 上：

import allure def request(self, method, url, **kwargs): ... resp = self.session.request(method, full_url, headers=headers, timeout=10, **kwargs) # 写入 allure 报告 allure.attach( body=f"### 请求\n```\n{method.upper()} {full_url}\n请求头: {headers}\n请求体: {kwargs.get('json')}\n```\n### 响应\n```\n{resp.text[:1000]}\n```", name=f"{method.upper()} {url}", attachment_type=allure.attachment_type.MARKDOWN ) return resp

这样每个用例点开，都能看到完整的请求报文和响应报文，排查问题的时候不再需要去翻控制台日志。

5.3 Jenkins 任务配置要点

接口测试最终是要在 CI/CD 里跑的。我用 Jenkins 的 freestyle 项目加虚拟环境跑接口测试，关键配置点：

1. 构建步骤选“Execute shell”，内容：

   cd $WORKSPACE python3 -m venv venv source venv/bin/activate pip install -r requirements.txt pytest --alluredir=./allure-results --clean-alluredir

2. 构建后操作选 “Allure Report”，Report path 填allure-results。
3. 触发策略：可以定时跑（比如每天晚上 22 点）+ 代码变更时跑（webhook 触发）。

实测下来，一个中等规模项目的接口用例（300 条左右），在普通配置的 Jenkins slave 上跑大约 3~5 分钟，完全可以接受。

6. 接口测试里的常见问题与排错笔记

接口测试和单元测试最大的不同是：它测的系统是分布式的，出问题时原因可能不在被测代码本身，可能是数据问题、环境问题、上游依赖问题、甚至 DNS 问题。我把自己多年踩过的坑整理成一个速查表：

除了逐条排查，我还有一个习惯：每个用例都设计成“幂等可重跑”。测试跑一次和跑十次，结果必须一致。如果做不到幂等，大多是测试数据没有隔离好。最简单的解法是随机生成用户名、手机号、订单号，或使用 pytest 的 reset 机制定期清理测试库。

再分享一个经验：接口测试里，mock 很重要，但别滥用。团队里有专门的 mock 服务来模拟支付、短信、三方登录这类外部依赖，但大部分内部接口都建议打真实环境，因为集成问题是接口测试的核心价值所在。mock 用太多，测试报告一片绿，实际上掩盖了上下游的兼容性问题。

最后再分享一点实际工作中的体会：接口测试框架的建设是个持续演进的过程，不是一次搭完就一劳永逸。最开始可能是几十个用例的脚本，跑一次要人工看一下；跑了几百个用例，就要开始想怎么生成让业务方看得懂的报告；跑了一千个用例，才会意识到性能、稳定性、环境隔离才是最大的瓶颈。pytest 的灵活性给这些演进留了足够的空间，它不限制你怎么写，也不逼你用某一种模式。关键是，你要在项目逐步变大的过程中，持续重构你的 fixture、抽取公共逻辑、完善数据管理——别等到一团乱麻再动手，那时候改框架的成本是几倍的。