企业官网建设流程全解析

Python + Pytest +Requests+ Allure + Loguru + Apifox + AI Skills 的接口自动化测试平台

Claude免费使用（FreeModel AI）

该地址首月免费赠送300＄额度，内置claude模型。

一、项目目录结构

xxProject/ │ ├── run_test.py # 一键执行入口（清理→执行→生成报告） ├── conftest.py # Pytest 全局 fixture（登录初始化、token 管理、日志） ├── pytest.ini # Pytest 配置（markers 定义） │ ├── comm/ # 公共基础层 │ ├── base_api.py # 公共请求封装（yaml 路由 + requests + loguru 日志） │ └── assert_api.py # 公共断言封装（== / != 断言 + 日志） │ ├── configs/ # 配置层 │ ├── env.py # 环境配置（HOST、USER_INFO、TENANT_ID） │ ├── api_config.yaml # 接口字典（业务→接口→path/method/body_schema） │ ├── case_config.yaml # 用例配置模板 │ └── loguru.ini # 日志配置（轮转/级别/保留天数/压缩） │ ├── data/ # 测试数据层（YAML 数据驱动） │ ├── User/ # User 业务模块数据 │ │ ├── userLoginCase.yml # 登录接口测试数据 │ ├── libs/ # 业务接口调用封装层 │ ├── login.py # 旧接口登录封装（MD5 加密密码） │ └── User/ # User 业务模块封装 │ └── user.py # 新接口 User 封装（login/get） │ ├── testCases/ # 测试用例层（Pytest + Allure） │ └── User/ # User 业务模块用例 │ ├── test_user_login.py # 登录接口测试用例 │ ├── utils/ # 工具层 │ ├── handle_path.py # 路径常量（IOTPath） │ ├── handle_yaml.py # YAML 读取（get_yaml_data / get_case_data） │ ├── handle_loguru.py # Loguru 单例日志 │ ├── handle_decorator.py # 装饰器（@show_time 计时） │ ├── handle_excel.py # Excel 读取工具 │ ├── clean_outfiles.py # 过期产物清理（保留 7 天） │ ├── encrypt_md5.py # MD5 加密工具 │ ├── apifox_sync.py # Apifox 接口同步脚本 │ ├── apifox_list_tags.py # Apifox 标签列表 │ └── apifox_probe.py # Apifox 连接探测 │ ├── outFiles/ # 运行产物（自动生成） │ ├── logs/ # Loguru 日志文件（按时间戳命名） │ ├── report/ # Allure 原始结果（JSON） │ └── report_html/ # Allure HTML 报告 │ ── skills/ # AI 智能体 Skill 定义 ├── test-runner-master/ # Skill1：主控编排 ├── apifox-to-yaml/ # Skill2：接口同步 ├── testdata-generator/ # Skill3：测试数据生成 └── case-fullchain-generator/# Skill4：全链路生成

二、核心分层架构

项目采用6 层分层架构，每层职责清晰，层间单向依赖：

┌─────────────────────────────────────────────────────────────┐ │ 第 1 层：AI 编排层（skills/） │ │ 职责：AI 大模型通过 4 个 Skill 自动编排生成测试全链路文件 │ ──────────────────────┬──────────────────────────────────────┘ │ 生成 ┌──────────────────────▼──────────────────────────────────────┐ │ 第 2 层：测试用例层（testCases/） │ │ 职责：Pytest 测试类 + Allure 报告装饰 + 数据驱动参数化 │ └──────────────────────┬──────────────────────────────────────┘ │ 调用 ┌──────────────────────▼──────────────────────────────────────┐ │ 第 3 层：业务封装层（libs/） │ │ 职责：每个业务模块一个类，封装接口调用逻辑（鉴权/参数处理） │ └──────────────────────┬──────────────────────────────────────┘ │ 继承 ┌──────────────────────▼──────────────────────────────────────┐ │ 第 4 层：公共基础层（comm/） │ │ 职责：BaseAPI（字典式路由请求）+ AssertAPI（统一断言） │ └──────────────────────┬──────────────────────────────────────┘ │ 读取 ┌──────────────────────▼──────────────────────────────────────┐ │ 第 5 层：数据驱动层（data/） │ │ 职责：YAML 文件存储测试数据（detail/data/res 三件套） │ └──────────────────────┬──────────────────────────────────────┘ │ 读取 ┌──────────────────────▼──────────────────────────────────────┐ │ 第 6 层：配置层（configs/） │ │ 职责：接口字典（api_config.yaml）+ 环境配置（env.py） │ └─────────────────────────────────────────────────────────────┘

三、各层级详细说明

3.1 公共基础层（comm/）

base_api.py — 公共请求封装

核心机制：字典式路由

BaseAPI.__init__() │ ├── 读取 api_config.yaml └── self.api_data = yaml[self.__class__.__name__] # 按类名匹配业务节点 ​ BaseAPI.request_send() │ ├── inspect.stack()[1][3] # 获取调用者方法名 ├── self.api_data[方法名] # 按方法名匹配接口配置 ├── 拼接 HOST + path # 自动组装完整 URL ├── requests.request() # 发送请求 └── loguru 记录请求/响应详情 # 企业级日志

关键设计：

• 子类只需定义方法名（如login、get），无需写 URL

• 接口路径变更只需修改api_config.yaml，代码零改动

• 自动记录请求体、响应体、状态码、响应耗时

assert_api.py — 公共断言封装

支持==/!=两种断言条件，断言结果自动记录日志（通过/失败均记录详细信息）。

3.2 配置层（configs/）

env.py — 环境配置

HOST = 'xxx' # 服务地址 USER_INFO = { # 登录凭据 'username': 'xxx', 'password': 'xxx', 'other' : 'xxx' }

api_config.yaml — 接口字典

User: # 业务模块名 = libs 类名 login: # 接口键 = libs 方法名 path: /admin-api/system/auth/login method: POST summary: 用户登录 body_schema: # 请求体字段定义 username: string password: string get: path: /admin-api/system/tenant/get-id-by-name method: GET summary: params: name: string

调用方式：

• BaseAPI通过类名定位业务节点，通过方法名定位接口配置

• 自动拼接HOST + path形成完整请求 URL

3.3 数据驱动层（data/）

YAML 数据格式（detail/data/res 三件套）

- order: 1 # 执行顺序（控制 Allure #N 序号） detail: 01-正向-用户名密码正确登录成功 # 用例描述（Allure 标题） data: # 请求参数 username: password: "" res: # 预期响应 code: 0

排序规则：

• order字段从 1 递增，控制 pytest 执行顺序

• 用例按正向 → 逆向 → 边界值 → 安全升序排列

• Allure 报告的#N序号自然按执行顺序显示

3.4 业务封装层（libs/）

每个业务模块一个类，继承BaseAPI：

class User(BaseAPI): def login(self, in_data, **kwargs): # 注入 Tenant-Id 鉴权 Header self.headers['Tenant-Id'] = str(TENANT_ID) return self.request_send(json=in_data, **kwargs) ​ def get(self, in_data, **kwargs): params = in_data if isinstance(in_data, dict) else {} return self.request_send(params=params, **kwargs)

命名规范：

• 类名 =api_config.yaml中的业务键（如User）

• 方法名 =api_config.yaml中的接口键（如login、get）

3.5 测试用例层（testCases/）

@allure.epic('xxx管理系统') @allure.feature('用户模块') class TestUserLogin: ​ @allure.story('用户登录') @allure.title('{detail}') @pytest.mark.parametrize( 'order, detail, data, res', get_case_data(IOTPath.data_path / 'User' / 'userLoginCase.yml') ) def test_login(self, order, user_init, detail, data, res): with allure.step('1.准备请求数据'): allure.attach(json.dumps(data), name='请求体', attachment_type=JSON) ​ with allure.step('2.调用登录接口'): api = user_init or User() result = api.login(data) ​ with allure.step('3.断言响应'): AssertAPI.api_assert(result, '==', res, 'code', msg=detail)

关键设计：

• @allure.title('{detail}')— 动态标题，从 YAML 的detail字段取值

• get_case_data()— 读取 YAML 返回pytest.param列表，带pytest.mark.run(order=N)排序标记

• user_initfixture — session 级登录，避免每条用例重复登录

• 支持子目录直接运行（自动注入项目根目录到 sys.path）

3.6 全局 Fixture（conftest.py）

四、调用关系详解

4.1 单次请求的完整调用链

test_user_login.py::test_login │ ├── [Fixture] user_init │ └── [Fixture] user_token │ └── libs/User/user.py::User().login(USER_INFO) │ └── comm/base_api.py::request_send(json=in_data) │ ├── configs/api_config.yaml → 读取 User.login 配置 │ ├── configs/env.py → 读取 HOST │ ── requests.request() → 发送 HTTP 请求 │ ├── allure.step('1.准备请求数据') → attach 请求体 ├── allure.step('2.调用登录接口') → api.login(data) │ └── libs/User/user.py::User().login(data) │ └── comm/base_api.py::request_send(json=data) │ └── requests.request() → 发送 HTTP 请求 │ └── allure.step('3.断言响应') → AssertAPI.api_assert(result, '==', res, 'code') └── comm/assert_api.py → 断言 + 日志

4.2 数据流向

api_config.yaml（接口字典） │ ├──→ comm/base_api.py（读取 path/method） │ data/User/userLoginCase.yml（测试数据） │ ├──→ utils/handle_yaml.py::get_case_data() │ └── 返回 pytest.param 列表 │ └──→ testCases/User/test_user_login.py（参数化注入） │ ├──→ libs/User/user.py（业务调用） │ └──→ comm/base_api.py（发送请求） │ └──→ configs/api_config.yaml（路由匹配） │ └──→ comm/assert_api.py（断言验证）

4.3 一键执行流程（run_test.py）

python run_test.py │ ├── Step 1: clean_outfiles() → 清理 7 天前的日志和报告 │ ├── Step 2: pytest.main() │ ├── 收集 testCases/ 下所有 test_*.py │ ├── 执行 conftest.py 中的 session fixture（登录初始化） │ ├── 按 order 升序执行每条用例 │ └── 生成 Allure 原始结果 → outFiles/report/ │ ├── Step 3: allure generate → 生成 HTML 报告 → outFiles/report_html/ │ └── Step 4: allure serve（可选，--serve 参数）→ 自动打开浏览器

五、AI Skills 说明

5.1 Skill 总览

5.2 Skill 间调用关系

用户对话（自然语言） │ ▼ ──────────────────────────────────────────────────────────┐ │ Skill1: test-runner-master（主控编排） │ │ - 解析用户意图 │ │ - 调度 Skill2/3/4 执行 │ │ - 失败定位与反馈 │ │ - 运行 run_test.py 验证 │ ──────┬───────────────┬──────────────────┬────────────────┘ │ │ │ ▼ ▼ ▼ Skill2 Skill3 Skill4 apifox-to-yaml testdata- case-fullchain- 拉取接口定义 generator generator → api_config 生成测试数据 生成全链路文件 .yaml → data/ → libs/ + testCases/

5.3 各 Skill 详细功能

Skill1: test-runner-master（主控编排）

功能：

• 作为 AI 对话的主入口，解析用户意图

• 按需调用 Skill2/3/4 完成具体任务

• 执行run_test.py验证生成的用例

• 失败时进行定位分析，给出修复建议

调用方式：

用户：为 User 业务的 login 接口生成测试用例 AI：[Skill] test-runner-master 已启动 [Skill] testdata-generator 已启动 → data/User/userLoginCase.yml ✓ [Skill] case-fullchain-generator 已启动 → libs/User/user.py / testCases/test_user_login.py ✓

Skill2: apifox-to-yaml（接口同步）

功能：

• 通过 Apifox Open API 拉取项目接口定义

• 解析 OpenAPI 3.x 文档，提取 path/method/summary/body_schema/params

• 写入/合并到configs/api_config.yaml

• 支持中文 tag 映射为 PascalCase 英文模块名

调用方式：

用户：使用 token=xxx, project_id=xxx 拉取 Apifox 接口 AI：[Skill] apifox-to-yaml 已启动 → configs/api_config.yaml 已更新（xxx 个接口/xx 个业务模块）

Skill3: testdata-generator（测试数据生成）

功能：

• 读取api_config.yaml中指定接口的body_schema/params

• 自动生成四维测试数据：正向 / 逆向 / 边界值 / 安全

• 按order字段升序排列，确保 Allure 报告序号正确

• 生成detail/data/res三件套格式的 YAML 文件

调用方式：

用户：为 User.login 接口生成测试数据 AI：[Skill] testdata-generator 已启动 → data/User/userLoginCase.yml ✓（xx条用例）

Skill4: case-fullchain-generator（全链路生成）

功能：

• 为单个接口一次性生成 4 个文件：

  • data/<业务>/<业务>Case.yml— 测试数据

  • libs/<业务>/<业务>.py— 接口调用封装

  • testCases/<业务>/test_<业务>_<接口>.py— 测试用例

• 严格遵循命名规范和文件结构

• 每次只生成一个接口，跑通后再询问下一个

调用方式：

用户：为 User.get 接口生成全链路用例 AI：[Skill] case-fullchain-generator 已启动 → data/User/userTenantCase.yml ✓ → libs/User/user.py（新增 get 方法）✓ → testCases/User/test_user_tenant.py ✓

六、与大模型交互方法

标准五步流程

Step 1 · 拉取接口 用户：把 apifox 项目 ID=xxx 的接口同步过来 AI：[Skill] apifox-to-yaml 已启动 → configs/api_config.yaml 已更新 ​ Step 2 · 选定一个业务接口 用户：为 User 业务的 login 接口生成测试用例 AI：[Skill] testdata-generator 已启动 → data/User/userLoginCase.yml ✓ [Skill] case-fullchain-generator 已启动 → libs/User/user.py / testCases/test_user_login.py ✓ ​ Step 3 · 单接口调试 用户：运行验证 AI：执行 run_test.py → 20 passed ✓ ​ Step 4 · 失败定位（如有） AI：[失败定位] - 用例文件: testCases/User/test_user_login.py::TestUserLogin::test_login - 请求URL : http://192.168.1.69:8080/admin-api/system/auth/login - 响应体 : {"code": 500, "msg": "系统异常"} - 错误原因: 缺少 tenantName/captchaVerification/rememberMe 字段 [等待您的修复建议] ​ Step 5 · 继续下一个接口 用户：继续 AI：[Skill] case-fullchain-generator 已启动 → 下一个接口 User.get ...

关键约束

1. 一次只生成一个接口，跑通后才进入下一个

2. 参数确认：大模型不理解接口参数时必须向用户询问

3. 文件生成约束：运行产物全部存储在outFiles/下

4. Skill 调用提示：成功调用 skill 时明确告知用户

七、Allure 报告生成与查看

生成方式

查看方式

报告层级

Epic: xxx管理系统 └── Feature: 用户模块 └── Story: 用户登录 ├── #1 01-正向-用户名密码正确登录成功 ├── #2 02-正向-用户名正确密码正确登录成功 ├── #3 03-逆向-用户名为空登录失败 ├── ... └── #14 14-安全-XSS攻击登录 └── Story: 租户查询 ├── #1 01-正向-正确租户名获取租户ID成功 ├── ... ── #6 06-安全-XSS租户名查询

用例排序规则

• 执行顺序由 YAML 中的order字段控制（从 1 递增）

• 用例按正向 → 逆向 → 边界值 → 安全升序排列

• Allure 报告的#N序号自然按执行顺序显示

八、架构核心优势

8.1 数据驱动 — 用例维护零代码

8.2 字典式路由 — 接口变更零代码

• 接口路径/方法变更只需修改api_config.yaml

• BaseAPI通过类名 + 方法名自动匹配接口配置

• 代码层完全不需要改动

8.3 AI 编排 — 分钟级全链路生成

• 自然语言驱动，AI 自动调用 4 个 Skill 完成全链路文件生成

• 从接口同步到用例生成到运行验证，全流程自动化

• 失败自动定位，给出修复建议

8.4 四维覆盖 — 测试质量保障

• 正向用例：验证正常业务流程

• 逆向用例：空值/缺失/错误值/异常输入

• 边界值用例：超长/极值/临界条件

• 安全用例：SQL 注入/XSS/特殊字符

8.5 企业级日志 — 问题快速定位

• Loguru 结构化日志，记录每次请求的完整信息

• 日志包含：业务模块、接口方法、HTTP 方法、URL、状态码、响应耗时、请求体、响应体

• 自动轮转（10MB）、压缩（zip）、保留（2 天）

8.6 一键执行 — CI/CD 友好

python run_test.py # 一键执行 python run_test.py --serve # 执行 + 自动打开报告

• 自动清理过期产物（保留 7 天）

• 自动生成 Allure 报告

• 支持单业务/按标记/按关键字运行

8.7 新旧接口兼容

• 旧接口（libs/login.py、libs/pro.py）保留兼容

• 新接口（libs/User/user.py）独立封装

• conftest.py中分别管理两套 fixture