不是跑通一个 demo 就算完。这是一篇从目录结构到 CI/CD 集成、从数据驱动到报告展示的完整实战指南。读完你能搭出一个生产可用的接口自动化测试框架。
写在前面
市面上关于"接口自动化测试"的文章很多，但大多数只停留在"用 requests 发一个请求、用 assert 判断状态码"的层面。真正能用于生产环境的接口测试框架，需要解决的是系统工程问题：
- 用例多了怎么管理？散落的 .py 文件只会变成新的维护噩梦
- 环境切换怎么处理？开发/测试/预发布/生产四套环境，不能每次改代码
- 测试数据怎么维护？硬编码的测试数据 = 脆弱的测试
- 报告怎么让非技术人员看懂？控制台输出对产品经理毫无意义
- 怎么融入 CI/CD？每次提交自动跑，失败自动通知
这篇文章会带你从零开始，一步步解决上述所有问题。最终你会得到一个可以直接用于生产项目的接口自动化测试框架。
技术栈：Python 3.11+ / Pytest / Requests / PyYAML / Allure / GitHub Actions
第一部分：项目初始化
1.1 创建项目
mkdirapi-test-frameworkcdapi-test-framework python-mvenv venvsourcevenv/bin/activate# Windows: venv\Scripts\activate1.2 安装依赖
pipinstallpytest requests pyyaml allure-pytest pytest-xdist pytest-rerunfailures --break-system-packages各依赖的作用：
| 依赖 | 作用 |
|---|---|
| pytest | 测试框架核心，用例发现、执行、fixture 管理 |
| requests | HTTP 客户端，发送接口请求 |
| PyYAML | 解析 YAML，用于配置文件和测试数据 |
| allure-pytest | Allure 报告集成，生成可视化测试报告 |
| pytest-xdist | 并发执行测试用例，提升执行效率 |
| pytest-rerunfailures | 失败用例自动重试，应对网络抖动等偶发问题 |
1.3 目录结构
api-test-framework/ ├── config/ # 配置文件目录 │ ├── settings.yaml # 全局配置 │ └── env/ # 多环境配置 │ ├── dev.yaml │ ├── test.yaml │ └── prod.yaml ├── core/ # 框架核心层 │ ├── __init__.py │ ├── http_client.py # HTTP 请求封装 │ ├── config_loader.py # 配置加载器 │ └── logger.py # 日志模块 ├── api/ # 接口封装层（按模块拆分） │ ├── __init__.py │ ├── base_api.py # 接口基类 │ ├── user_api.py # 用户模块接口 │ └── order_api.py # 订单模块接口 ├── testcases/ # 测试用例目录 │ ├── __init__.py │ ├── conftest.py # 全局 fixture │ ├── user/ # 按模块组织用例 │ │ ├── test_login.py │ │ └── test_register.py │ └── order/ │ └── test_create_order.py ├── testdata/ # 测试数据目录 │ ├── user_data.yaml │ └── order_data.yaml ├── utils/ # 工具类 │ ├── __init__.py │ ├── assert_utils.py # 断言工具 │ └── data_utils.py # 数据处理工具 ├── reports/ # 测试报告输出目录 ├── logs/ # 日志输出目录 ├── conftest.py # 项目根级 fixture ├── pytest.ini # pytest 配置文件 ├── run.py # 一键执行入口 └── requirements.txt # 依赖清单为什么要这样拆分？
core/——框架基础设施，与具体业务无关，换项目可以直接复用api/——接口封装层，一个接口一个方法，让测试用例不直接操作 HTTPtestcases/——纯业务逻辑，用例只关心"调什么接口、传什么参数、期望什么结果"testdata/——数据与代码分离，换测试数据不需要改代码config/——环境与代码分离，切环境只需改命令行参数
第二部分：核心基础设施
2.1 配置管理
多环境配置是团队协作的基础。每个环境一个 YAML 文件，启动时动态加载。
config/env/dev.yaml（开发环境）：
base_url:"https://dev-api.example.com"timeout:30db:host:"dev-db.example.com"port:5432user:"test_user"password:"dev_password_123"database:"dev_db"log:level:"DEBUG"file:"logs/dev.log"config/env/test.yaml（测试环境）：
base_url:"https://test-api.example.com"timeout:30db:host:"test-db.example.com"port:5432user:"test_user"password:"test_password_456"database:"test_db"log:level:"INFO"file:"logs/test.log"config/env/prod.yaml（生产环境——只读操作）：
base_url:"https://api.example.com"timeout:15db:host:"prod-db-readonly.example.com"port:5432user:"readonly_user"password:"readonly_pass_789"database:"prod_db"log:level:"WARNING"file:"logs/prod.log"core/config_loader.py——配置加载器：
importosimportyamlfrompathlibimportPathfromtypingimportAnyclassConfigLoader:"""配置加载器，支持多环境切换"""_instance=None_config:dict={}def__new__(cls):ifcls._instanceisNone:cls._instance=super().__new__(cls)returncls._instancedefload(self,env:str=None)->dict:"""加载指定环境的配置"""ifenvisNone:env=os.getenv("TEST_ENV","dev")# 加载全局配置project_root=Path(__file__).parent.parent global_config_path=project_root/"config"/"settings.yaml"ifglobal_config_path.exists():withopen(global_config_path,"r",encoding="utf-8")asf:self._config=yaml.safe_load(f)or{}# 加载环境配置（覆盖全局配置）env_config_path=project_root/"config"/"env"/f"{env}.yaml"ifnotenv_config_path.exists():raiseFileNotFoundError(f"环境配置文件不存在:{env_config_path}")withopen(env_config_path,"r",encoding="utf-8")asf:env_config=yaml.safe_load(f)self._config=self._deep_merge(self._config,env_config)self._config["current_env"]=envreturnself._configdefget(self,key:str,default:Any=None)->Any:"""通过点号分隔的 key 获取配置值，如 'db.host'"""keys=key.split(".")value=self._configforkinkeys:ifisinstance(value,dict):value=value.get(k)else:returndefaultreturnvalueifvalueisnotNoneelsedefault@staticmethoddef_deep_merge(base:dict,override:dict)->dict:"""深度合并两个字典"""result=base.copy()forkey,valueinoverride.items():ifkeyinresultandisinstance(result[key],dict)andisinstance(value,dict):result[key]=ConfigLoader._deep_merge(result[key],value)else:result[key]=valuereturnresult# 全局单例config=ConfigLoader()使用时：
fromcore.config_loaderimportconfig# 通过环境变量切换，默认 devconfig.load()# 或 config.load("test")# 获取配置base_url=config.get("base_url")db_host=config.get("db.host")2.2 HTTP 客户端封装
直接使用requests的问题是：每次请求都要重复写 URL 拼接、超时设置、异常处理。把这些通用逻辑封装起来。
core/http_client.py：
importjsonimporttimeimportrequestsfromtypingimportOptional,Anyfromurllib.parseimporturljoinfromcore.config_loaderimportconfigfromcore.loggerimportloggerclassHttpClient:"""HTTP 请求客户端封装"""def__init__(self):self._session=requests.Session()self._base_url=config.get("base_url","")self._timeout=config.get("timeout",30)# 默认请求头self._session.headers.update({"Content-Type":"application/json","Accept":"application/json",})def_build_url(self,path:str)->str:"""拼接完整 URL"""returnurljoin(self._base_url,path)def_log_request(self,method:str,url:str,**kwargs):"""记录请求日志"""logger.info(f">>>{method}{url}")if"json"inkwargs:logger.debug(f"Request Body:{json.dumps(kwargs['json'],ensure_ascii=False)}")if"params"inkwargs:logger.debug(f"Request Params:{kwargs['params']}")def_log_response(self,response:requests.Response,elapsed:float):"""记录响应日志"""logger.info(f"<<<{response.status_code}[{elapsed:.2f}s]")ifresponse.text:try:
