简介：基于 Python 语言构建的接口自动化测试框架资料包，围绕 pytest、allure、log、yaml、mysql 与钉钉/企微通知串联完整测试链路，面向测试开发工程师、自动化测试学习者及需要快速建立接口回归体系的团队，用于搭建可复用、可监控、可扩展的测试基础设施。压缩包共 167 个文件，整体大小仅 2.79MB；其中 py 脚本为核心测试逻辑与公共方法，pyc 为编译产物，yaml、ini 和 xml 承担配置管理，png 截图与 xlsx 表格用于结果记录和统计，说明文档与日志文件则辅助上手调试。目前已有 1162 人学习下载。资料内含日志记录、覆盖率输出、pytest 运行配置、说明文档、典型页面截图及数据库相关示例，能帮助读者理解框架分层、配置驱动和消息通知集成方式，并据此快速改造为符合自身业务的自动化测试方案，减少从零搭建的时间成本。
1. 这套接口自动化框架，解决的是“脚本堆成山后没人愿意跑”的问题
接口自动化做久了会撞上一堵墙：用例越写越多，散落在各种脚本文件里；跑完看不了报告，定位问题全靠翻控制台；测试数据和账号密码硬编码在代码里，换套环境就改半天；断言失败后想知道数据库里当时的数据，还得手动连库查。这套Python+pytest+allure+log+yaml+mysql+钉钉企微通知接口自动化框架，就是把上面这些零散的诉求收拢成一个能稳定运行的工程方案——pytest 管用例组织和执行，allure 出可视化报告，yaml 管环境配置和测试数据，mysql 做数据准备与结果校验，log 把运行过程留痕，最后把执行结果推到钉钉或企微群。适合正在搭建接口自动化体系的测试开发，也适合想把手头脚本工程化的人参考。
2. 先搭目录骨架：一个能跑通的 yaml+log+mysql 最小接口框架
2.1 分层设计：为什么这六个组件摆在一起不打架
这套框架的目录结构通常是按“配置、核心、用例、报告”四层来分的。配置指 yaml 文件，核心是 pytest 的 fixture、log 封装、mysql 读写封装、钉钉企微通知封装，用例是业务测试代码，报告是 allure 输出目录。这样分的好处是两个：一是各层只依赖下一层，二是环境切换只改 yaml，不用动代码。
我一般会把目录结构搭成这样：
api_test_framework/ ├── common/ # 公共封装 │ ├── __init__.py │ ├── log.py # 日志封装 │ ├── mysql_db.py # mysql 读写封装 │ ├── read_yaml.py # yaml 加载 │ ├── notify.py # 钉钉企微通知 │ └── assert_utils.py # 断言辅助（时间、排序等） ├── config/ │ └── config.yaml # 环境、数据库、通知配置 ├── testcases/ │ ├── __init__.py │ ├── conftest.py # pytest fixture 定义 │ └── test_user_api.py # 业务用例 ├── allure_result/ # allure 原始结果目录 ├── allure_report/ # allure 生成的 html 报告 ├── logs/ # 运行日志 ├── pytest.ini # pytest 配置，注册 mark 与 allure 参数 └── requirements.txtpytest 拿到这个结构后，能自动从 testcases 下收集用例，conftest.py 里的 fixture 会自动对所有用例生效。log 和 mysql 封装放在 common 层，避免每个用例文件重复造轮子。配置文件集中在 config 里，yaml 的好处是缩进即结构，比 ini 能表达更复杂的嵌套，比 json 能写注释，测试环境里维护起来压力小很多。
2.2 第一步：yaml 配置加载，先让框架能读“环境变量”
很多框架里的 yaml 不只存环境地址，还会存数据库连接串、通知机器人的 token、超时时间、以及每个接口的入参模板。加载层要做的，是把它读成一个字典并支持嵌套取值，这样既能当设置用，也能当测试数据仓库用。下面是最小可用的加载类：
import yaml import os import json class ReadYaml: def __init__(self, yaml_path="config/config.yaml"): # 打开后按 utf-8 读，避免中文注释在 windows 下乱码 with open(yaml_path, encoding="utf-8") as f: self.data = yaml.safe_load(f) def get(self, key_path: str, default=None): # 支持用点号取嵌套值，例如 "mysql.host" keys = key_path.split(".") node = self.data try: for k in keys: if isinstance(node, dict): node = node.get(k) else: return default return node if node is not None else default except Exception: return default这个类不复杂，但注意两点：一是encoding="utf-8"，windows 终端和文件编码不一致时极易踩坑；二是yaml.safe_load，不要用yaml.load，避免任意对象反序列化导致的执行风险。取嵌套值用点号路径，比到处config["a"]["b"]["c"]要稳，配置结构一调整，只改 key_path 字符串，不用动业务代码。
config.yaml 的大致内容，我会把环境、数据库、通知放三段：
env: base_url: "https://api.example.com" timeout: 10 mysql: host: "127.0.0.1" port: 3306 user: "root" password: "your_password" database: "test_data" charset: "utf8mb4" notify: dingtalk: webhook: "https://oapi.dingtalk.com/robot/send?access_token=xxx" secret: "SECxxx" wecom: webhook: "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"为什么把数据库也放 yaml？因为接口断言经常要查库确认落库结果，测试环境、预发环境、生产环境的库地址都不一样，写死在代码里是给自己埋雷。后面所有需要环境信息的模块，都从这个配置对象取。
2.3 日志封装：黑匣子能不能拆开，取决于 log 打得细不细
接口测试跑挂了，最痛苦的是不知道断言失败那一刻请求体、响应体和数据库状态是什么。所以 log 不只是记录“执行到哪一步”，而是要在关键节点把入参、出参、耗时、数据库返回都打出来。python 标准库 logging 够用，不用引第三方。封装时核心是两件事：日志格式统一，以及文件和控制台双输出。
import logging import os import time class Logger: def __init__(self, name="api_test", log_path="logs"): os.makedirs(log_path, exist_ok=True) log_file = os.path.join(log_path, f"run_{time.strftime('%Y%m%d_%H%M%S')}.log") self.logger = logging.getLogger(name) self.logger.setLevel(logging.DEBUG) formatter = logging.Formatter( "%(asctime)s - %(levelname)s - %(name)s - %(filename)s:%(lineno)s - %(message)s" ) if not self.logger.handlers: file_handler = logging.FileHandler(log_file, encoding="utf-8") file_handler.setLevel(logging.INFO) file_handler.setFormatter(formatter) console_handler = logging.StreamHandler() console_handler.setLevel(logging.DEBUG) console_handler.setFormatter(formatter) self.logger.addHandler(file_handler) self.logger.addHandler(console_handler) def info(self, msg): self.logger.info(msg) def error(self, msg): self.logger.error(msg)每次运行生成一个带时间戳的新日志文件，好处是多轮执行不会互相覆盖，排查问题能定位到是“哪一次运行”出的错。日志里我习惯带上filename:lineno，这样报错时直接就能跳到对应代码行。文件 handler 用 INFO 级，控制台用 DEBUG 级，因为本地调试要看细节，跑了定时任务看文件只需要关键信息，这个分级能省不少磁盘。
2.4 conftest.py 里的两个核心 fixture：环境准备和接口请求
pytest 的 conftest.py 是所有用例的“基础设施”。接口自动化里，我一般会在 conftest 里定义三个 fixture：base_url、session（带会话的 requests 实例）、db（mysql 连接）。fixture 的一个关键点是 scope 参数，session 级别只初始化一次，function 级别每条用例都新建。请求连接用 session 级别的，数据库连接在用例级用 function 级别，防止一个用例改坏数据影响后面用例。
import pytest import requests from common.read_yaml import ReadYaml from common.log import Logger from common.mysql_db import MySqlDb @pytest.fixture(scope="session") def config(): return ReadYaml("config/config.yaml") @pytest.fixture(scope="session") def base_url(config): return config.get("env.base_url") @pytest.fixture(scope="session") def api_session(base_url): # 会话级连接复用，避免每个用例都经历 TCP 握手 s = requests.Session() s.headers.update({"Content-Type": "application/json"}) return s @pytest.fixture(scope="function") def db(config): mysql_conf = config.get("mysql") db = MySqlDb( host=mysql_conf["host"], port=mysql_conf["port"], user=mysql_conf["user"], password=mysql_conf["password"], database=mysql_conf["database"], charset=mysql_conf["charset"] ) yield db db.close()这里有个细节值得留意：dbfixture 用 yield 而不是 return，就是为了在用例结束后自动执行db.close()，保证连接不泄漏。mysql 连接泄漏是接口自动化框架跑久了变慢的头号原因，用 yield 把释放动作固定下来，后续新写用例的人不会漏掉清理动作。日志对象我通常在conftest.py顶部直接初始化一个全局实例，用例和封装模块都能from common.log import log拿到同一个实例，避免重复打印。
3. 用 pytest+allure 把用例组织起来：fixture、钩子与报告联动
3.1 用 allure 的 feature/story/title 重新定义测试报告的可读性
pytest 本身能出 junit 报告，但可读性很差。allure 的价值是把用例按业务模块、功能点、场景三层组织起来，生成带步骤、带响应体、带失败截图的 html 报告。它不是替代 pytest，而是给 pytest 的结果做了一层“装饰”。关键用法是三个装饰器：
import allure import pytest @allure.feature("用户模块") @allure.story("登录接口") @allure.title("正确账号密码登录成功") @allure.severity(allure.severity_level.BLOCKER) def test_login_success(api_session, base_url, config): with allure.step("准备登录数据"): payload = { "username": config.get("api_data.login.username"), "password": config.get("api_data.login.password") } with allure.step("发起请求"): resp = api_session.post(f"{base_url}/api/user/login", json=payload) with allure.step("断言响应结果"): assert resp.status_code == 200 assert resp.json()["code"] == 0feature是模块级，story是功能点级，title是具体场景。报告生成后，产品经理和开发都能直接看懂“哪个功能挂了”。with allure.step会把每一步的执行耗时和结果都留在报告里，方便按图索骥找到失败环节。severity 标记 BLOCKER 的一般是主链路，跑完看报告先看高优先级用例，而不是从头翻到尾。
3.2 pytest.ini 配置：mark、allure 参数、日志开关
pytest 的配置不要散在命令行里，写进 pytest.ini 才能让团队所有人都用同一套参数。下面这份是我的常用配置：
[pytest] testpaths = testcases python_files = test_*.py python_classes = Test* python_functions = test_* markers = smoke: 冒烟用例 full: 全量用例 addopts = -s -v --alluredir=allure_result --clean-alluredir--alluredir指定 allure 原始结果输出目录，--clean-alluredir会在每次运行前清空旧结果，避免报告把前后两轮数据混在一起。markers注册的是自定义标签，配合pytest -m smoke跑冒烟集，pytest -m "not full"排除某些慢用例。这里有个血泪教训：如果不在 pytest.ini 里注册 markers，运行时会甩一条 warning，虽说不致命，但 CI 日志会被刷得没法看，排错效率直线下降。
3.3 断言失败时把日志和 allure 串起来：request 与 response 的留痕
接口测试里最怕断言都写对了，但失败后看报告看不到“请求发了什么”。解决方法是把响应的关键信息在断言失败时主动打到日志和 allure 里。常见做法是在每一条用例的 finally 块里做转储，或者封装一个断言工具类统一处理。
import allure import json def assert_and_dump(resp, expected_code, logger): try: assert resp.status_code == 200, f"HTTP 状态码异常: {resp.status_code}" body = resp.json() assert body["code"] == expected_code, f"业务码异常: {body['code']}" except AssertionError as e: # 失败时把请求和响应体挂到 allure 报告上 allure.attach( f"请求URL: {resp.request.url}\n" f"请求体: {resp.request.body}\n" f"响应体: {json.dumps(body, ensure_ascii=False, indent=2)}", name="fatal_info", attachment_type=allure.attachment_type.TEXT ) logger.error(f"请求URL: {resp.request.url} | 响应体: {json.dumps(body, ensure_ascii=False)}") raiseresp.request是 requests 库里这次请求的完整快照，包括 url、headers、body。很多人在断言失败后只看响应体，不看请求体，结果漏掉了“请求参数拼对了没有”这个维度。封装了assert_and_dump后，失败自动把信息挂到 allure 报告上，省去手动补allure.attach的重复劳动。
3.4 生成 allure 报告的命令：装好环境后别再踩 PATH 的坑
allure 本体是 Java 写的命令行工具，需要先装 JDK 8+，再下载 allure commandline 解压，配好环境变量。装好后生成报告的流程分两步：先跑 pytest 收集结果，再渲染 html。
pytest -m smoke --alluredir=allure_result allure generate allure_result -o allure_report --clean allure open allure_report第三步会起一个本地 web 服务，在浏览器打开报告首页。如果allure命令找不到，多半是 PATH 没配，把解压目录的bin路径加进去。还有一个小坑：allure generate的--clean参数是必须的，不加的话旧报告文件和新的叠加，页面会异常。生成完可以顺手把 report 目录打包丢给开发看，或者直接由通知机器人把报告地址发群里。
4. 用 yaml 管配置、用 mysql 管数据：加载封装与读写边界
4.1 为什么测试数据也塞进 yaml：与代码解耦的取舍
有人会把测试数据全写在代码里的 dict 里，理由是“就近原则”。但数据一变就要改代码、提 MR、等 CI，这套流程成本在频繁变更的环境里扛不住。所以配置型的测试数据（登录账号、超时时间、基础入参）放 yaml，动态生成的数据（注册后的 user_id、订单号）由用例在运行时写进数据库或内存。我的习惯是 config.yaml 里再挂一段：
api_data: login: username: "test_user_01" password: "e10adc3949ba59abbe56e057f20f883e" register: email: "test_{time}@example.com"{time}是个占位符，用例里读取后替换成当前时间戳，这样重复跑不会被“唯一索引”卡住。yaml 里写的是模板，不是写死的值，运行时做变量替换。这种模式的好处是换环境、换数据集时不用碰用例代码，测试数据像配置文件一样受版本管理，但又没有把数据硬编码进逻辑里。
4.2 mysql 连接封装：查询结果要转成可断言的格式
接口测试里连 mysql 通常只有两种操作：准备数据（insert）和校验结果（select）。没必要时引入 ORM，pymysql 一个库足够。封装的重点在设计返回值——查询结果要么是单个值（比如 count(*)），要么是列表套字典（行转列），前者用字符串，后者用[{column: value}]。下面是一份可复用的封装：
import pymysql class MySqlDb: def __init__(self, host, port, user, password, database, charset="utf8mb4"): self.conn = pymysql.connect( host=host, port=port, user=user, password=password, database=database, charset=charset, cursorclass=pymysql.cursors.DictCursor # 结果以字典形式返回 ) self.cursor = self.conn.cursor() def query_one(self, sql): # 查一条，等价于 cursor.fetchone() self.cursor.execute(sql) return self.cursor.fetchone() def query_all(self, sql): self.cursor.execute(sql) return self.cursor.fetchall() def execute(self, sql, args=None): # insert/update/delete 统一走这里 affected = self.cursor.execute(sql, args) self.conn.commit() return affected def close(self): self.cursor.close() self.conn.close()cursorclass=DictCursor是刻意选的，取出来的数据直接就是{"user_id": 1}这种字典，断言时可以直接result["user_id"]，比result[0]可读性好太多。execute里每次执行完都 commit，接口测试里数据量不大，频繁 commit 对性能没什么影响，反而能避免“框架跑了半天，库里没数据”的诡异问题。需要留意的一点：pymysql 没有连接池，框架跑全量时如果每用例都新建连接，会带来不少握手开销，一般我会在 conftest 里按 function 级别建连接，但把执行密度高的用例集中到同一个测试类里减少切换。
4.3 用 mysql 做数据准备的典型套路：造号、造单、清理
接口测试里最常做的一件事是“造前置数据”。比如测试下单接口，先得有一个已注册用户、一个有效的商品 ID、一个可用优惠券。直接调前置接口造数据，慢且受上游波动影响；直接插库，快且稳定。具体做法是在用例里先确认数据不存在，再插入，提供一个“要么重跑要么跳过”的判断。
def prepare_user(db, username): # 先清掉历史残留，避免唯一索引冲突 db.execute("DELETE FROM t_user WHERE username = %s", (username,)) db.execute( "INSERT INTO t_user(username, status, created_at) VALUES (%s, %s, NOW())", (username, 1) ) user_id = db.query_one("SELECT LAST_INSERT_ID() AS id")["id"] return user_id注意一个参数化细节：pymysql 的占位符是%s，不是?，也不要把参数直接拼接进 sql。LAST_INSERT_ID()必须在 insert 之后的同一连接里查，中间不能随便做其他 commit，否则拿到的可能不是刚才那条记录。清数据用的是 delete 而不是 truncate，因为 truncate 会重置自增 ID，接口侧如果有“按 ID 范围查”的逻辑会受影响。
4.4 数据库断言：验证结果不能只看响应体
接口返回成功不代表落库成功，常见的坑是接口返回“处理中”，其实事务还没提交。数据库断言的思路一般分三类：查记录是否存在、查字段值是否符合预期、查状态字段是否推进到期望值。落库断言放在接口断言之后，但不要用同一个数据库连接——接口内部可能会改库，同一连接可能读到未提交事务的快照。
def assert_db_contains(db, table, condition, expected): sql = f"SELECT COUNT(*) AS cnt FROM {table} WHERE {condition}" result = db.query_one(sql) assert result["cnt"] == expected, f"数据库记录数不符: {result['cnt']} != {expected}"table和condition由用例传入，但不要传外部拼好的 sql，防止 sql 注入。count 断言做存在性检查，字段值断言再单独用query_one查询比对。做数据库断言时还有个习惯：尽量用不带*的字段列表查，只查需要的字段，减少结果集大小，在数据量大时能省一些连接开销。
5. 避坑排查：环境、编码和数据串用的 5 个真实教训
5.1 allure 报告生成时报错或页面空白：八成是环境变量和命令参数问题
现象：pytest 执行成功，allure generate也跑了，但生成的 index.html 打开一片空白，或者控制台报“allure: command not found”。
原因：分两层。命令找不到是 PATH 没配好。报告空白则是因为 allure 的渲染依赖 js 文件，如果直接用file://协议打开本地 html，浏览器会拦截跨域请求，导致页面空白。
解决：配好 PATH 后，用allure open allure_report启动本地服务，浏览器访问http://localhost:端口。如果想发给别人远程看，把报告目录放到测试服务器上用 nginx 或 python 起静态服务，不要直接丢 html 文件。另外allure generate前确认--alluredir目录里真的有 json 结果文件，若 pytest 因为用例收集失败根本没产出结果，generate 只是空转。
5.2 yaml 读取中文注释乱码或解析报错：文件编码与 safe_load 成对出现
现象：yaml 文件里写了中文注释，pytest 运行时直接抛UnicodeDecodeError，或者在 windows 终端里打印配置内容是乱码。
原因：python 在 windows 上默认按 GBK 读文件，而现代编辑器保存 yaml 默认 utf-8，两边对不上。
解决：加载 yaml 时强制encoding="utf-8"，配置文件头也可以顺手加上# -*- coding: utf-8 -*-。另外统一使用yaml.safe_load而不是yaml.load，后者在旧版本 pyyaml 里遇到某些结构会抛 warning 甚至执行任意代码。团队协作时，约定文件一律 utf-8 无 BOM 保存，能在源头上拦掉一半编码问题。
5.3 mysql 插入中文报错 or 写入后查询为乱码：charset 要精确到 utf8mb4
现象：insert 语句带中文，pymysql 抛Incorrect string value；或者插入不报错，但 select 出来是????。
原因：mysql 连接层和库表字符集不匹配。连接串只写了charset="utf8"，但 mysql 8.0 默认字符集是utf8mb4，emoji 和部分生僻字在 utf8 下存不了；另一种情况是表的 collation 是 latin1，连接层再努力也白搭。
解决：连接参数统一charset="utf8mb4"，同时建库建表时显式指定DEFAULT CHARSET=utf8mb4。如果老库已经是 latin1，跑一条ALTER TABLE t_user CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci也能救回来。框架里我在dbfixture 初始化时就把 charset 写死，不依赖外部配置文件，防止有人手滑配错。
5.4 用例之间数据串用：fixture 的 scope 没想清楚
现象：A 用例注册用户拿了 user_id，B 用例不知道怎么用到了 A 的 user_id；或者 A 改变了某条数据，影响了 B 的断言。
原因：fixture 的 scope 定义不当。session 级别的连接和数据共享，function 级别才是每用例独立。有些测试数据准备放 session 级没问题，但有状态的数据（比如订单状态流转）放 session 级就会串。
解决：无状态的基础数据（配置、环境地址）用 session 级；有状态的用例数据用 function 级，每条用例执行前重建。同类接口的用例放在同一个测试类里，保证 pytest 的执行顺序可控，不要依赖用例名排序来掩盖数据耦合。另外 MySQL 事务隔离级别默认是可重复读，同一连接里一条用例 commit 的数据，下一条用例在同一 session 连接里不一定立即可见——这也是为什么数据库操作和用例断言要区分连接上下文。
5.5 通知机器人发不出消息或消息被限流：关键字校验和签名顺序
现象：钉钉或企微群里的机器人静默，日志里也没有报错；偶尔第一条能发，后面连续失败。
原因：钉钉自定义机器人有安全设置，要么配“自定义关键字”，消息里必须包含该关键字；要么配“加签”，签名值计算有误也会被拒。企微机器人则是按频率限流，20 条/分钟，超了直接丢弃消息。很多人在发送函数里把关键字写错位置，或者 secret 拼接时加了多余换行。
解决：钉钉加签的逻辑是timestamp + "\n" + secret做 HMAC-SHA256，base64 编码后再 URL 编码，这个拼接顺序不能乱。消息体里额外带一个“接口自动化”关键字，绕过关键字校验。发送函数统一封装在common/notify.py里，重试一次但不要重试太多，否则会撞上频率限制。企微那边如果群内消息量大，可以在发送前 sleep 0.5 秒，把瞬时并发摊平。
6. 钉钉企微通知与流水线：多环境配置下让框架从“能跑”到“能值守”
通知模块是整个框架“最后一段路”。跑完用例没人看，等于白跑。钉钉和企微机器人基本都是 webhook 推送，http post 一个 json 即可，差异只在签名和消息结构。我会先做一个公共发送函数：
import time import hmac import hashlib import base64 import urllib.parse import requests def dingtalk_webhook(url, secret, content): timestamp = str(round(time.time() * 1000)) string_to_sign = f"{timestamp}\n{secret}" hmac_code = hmac.new( secret.encode("utf-8"), string_to_sign.encode("utf-8"), digestmod=hashlib.sha256 ).digest() sign = urllib.parse.quote_plus(base64.b64encode(hmac_code)) payload = { "msgtype": "text", "text": {"content": f"接口自动化 {content}"} } requests.post(f"{url}×tamp={timestamp}&sign={sign}", json=payload, timeout=5)构造 sign 的细节是：timestamp是毫秒级字符串，拼接的\n不能丢，也不能多。hmac 的 key 是 secret 本身，不是 secret 的 base64 值——这个顺序错了会一直报签名错误。 content 前面拼的“接口自动化”这五个字就是为了应对自定义关键字校验，如果不拼，机器人会静默。企微机器人不需要加签，直接把消息 post 到 webhook 即可，同时注意重试时 Timeout 要短，避免通知线程占住用例进程不放。
通知不只在全部跑完后发，我习惯在 pytest 的conftest.py里挂一个会话级 fixture，用yield包住整个测试会话，结束后拿统计结果组装通知：
@pytest.fixture(scope="session", autouse=True) def notify_when_done(config): yield passed = pytest.StashKey() # 用 pytest_terminal_summary hook 把统计结果写进来 content = f"通过 {passed_num} / 失败 {failed_num} / 报告链接待生成" dingtalk_webhook(config.get("notify.dingtalk.webhook"), config.get("notify.dingtalk.secret"), content)整体框架跑起来后，要验证的不只是“用例过了没有”，而是“这套东西能不能持续运转”。我的建议是先在本地把pytest -m smoke --alluredir=allure_result跑通，再套一层脚本把 alerts 生成的 html 报告压缩后丢到服务器静态目录，最后把通知推给研发群。跑一轮下来能稳定一周不出幺蛾子，再往 CI 里接。血的教训是启 CI 前先在本地模拟跑十遍，这个框架里最脆弱的两环是 allure 的环境变量和钉钉机器人签名，这两处配置错了，跑得再好看的消息也发不到群里。希望帮到你。
本文还有配套的精品资源，点击获取
