AI+Yapi：构建接口自动化测试用例生成引擎的实践与架构解析

1. 从“人肉”到“智能”：为什么我们需要AI来生成测试用例？

大家好，我是文哥，一个在测试和研发效能领域摸爬滚打了十几年的老兵。这些年，我待过不少公司，从大厂到创业团队都经历过。我见过测试同学最头疼的事情之一，就是面对成百上千个新接口，吭哧吭哧地写测试用例。尤其是现在微服务架构盛行，一个需求动辄涉及五六个服务，每个服务又新增三五个接口，这测试用例的工作量，光想想就让人头皮发麻。

传统的做法是什么？测试工程师盯着Yapi（或者其他接口管理平台）上的文档，一个字段一个字段地看，然后在脑子里构思各种正常、异常的测试场景，再手动敲进Excel或者测试管理工具里。这个过程不仅枯燥重复，而且极其容易出错。比如，文档里明明写着某个字段是“字符串类型，最大长度10”，但写用例时可能就漏掉了边界值“长度为11”的异常case。更别提那些复杂的业务逻辑校验，比如订单状态流转、支付金额计算等，全靠人工理解和设计，对测试人员的业务熟悉度和细心程度要求非常高。

我去年在主导一个研发效能提升项目时，就深刻感受到了这个痛点。团队里几个测试同学，超过60%的时间都花在了设计、编写和维护接口测试用例上，真正去做探索性测试、性能压测、安全测试这些更有价值工作的时间反而被挤压了。这显然不是我们想要的状态。于是我就想，能不能让机器来干这些重复、规则明确但又需要一定“智力”的活儿？能不能让AI来当我们的“初级测试用例设计员”？

这就是我们启动“AI+Yapi自动化用例生成引擎”项目的初衷。我们不是要取代测试工程师，而是要把他们从繁琐的重复劳动中解放出来，让他们去做更核心、更有创造性的工作，比如设计更复杂的业务场景、进行更深度的质量风险分析。经过几个月的实践，在我们已经落地的单接口用例生成场景里，效率提升普遍在80%以上，有些结构清晰的查询类接口，甚至能做到“秒出”高质量的测试用例。这不仅仅是快，更重要的是，AI不知疲倦，不会因为加班而遗漏边界条件，它能严格按照我们设定的规则和提示，一丝不苟地生成覆盖全面的用例。

2. 引擎核心架构：一个“智能体”协作的流水线

要把想法落地，光靠调用一两次大模型的API是远远不够的。我们需要一个稳定、可扩展、易维护的系统。我们的引擎架构，你可以把它想象成一个由多个“智能体”组成的虚拟团队，它们各司其职，在一条流水线上协同工作，最终产出我们想要的测试用例。

整个系统的核心流程是这样的：获取Yapi接口文档 -> 解析并结构化文档数据 -> 根据不同类型接口选择“智能体” -> 智能体调用大模型生成用例 -> 格式化输出用例文件。下面这张简化的架构图能帮你快速理解：

[用户/定时任务] 触发 | v [任务调度中心] | v [Yapi文档获取与解析器] --> [数据缓存层] | v [智能体调度器] | v +-----------------------+ | [智能体服务集群] | | | | - 单接口用例生成器 | | - 场景流用例生成器 | | - 数据构造器 | | - 断言生成器 | +-----------------------+ | v [提示词工程模块] <--> [大模型API] | v [用例后处理器] --> [用例存储层] | v [结果反馈与日志]

我来拆解一下几个关键模块：

数据缓存层：这是我们的“记忆中枢”。每次从Yapi拉取和解析的接口文档（包括接口路径、方法、请求头、请求参数、返回参数等），都会以结构化的JSON格式存到这里。为什么需要缓存？第一，避免频繁调用Yapi的API，给人家服务器造成压力；第二，当我们需要基于同一个接口反复调试提示词或生成规则时，直接从缓存读取，速度飞快；第三，可以作为历史数据，用于后续分析接口变更对测试用例的影响。

智能体服务集群：这是系统的“大脑”和“执行者”。我们采用了“单一职责”的设计原则，每个智能体只负责一件事，做精做专。

• 单接口用例生成器：这是我们最先投产、也是最成熟的智能体。它专门处理一个独立的HTTP接口，根据其输入输出，生成包括正向用例、边界值用例、异常用例、参数组合用例等。
• 场景流用例生成器（开发中）：这是我们的进阶目标，负责将多个有业务顺序的接口串联起来，生成业务流程用例。比如“用户登录 -> 查询商品 -> 加入购物车 -> 下单支付”这一整套流程。
• 数据构造器：这是一个辅助智能体。当接口参数需要特定格式的数据（如符合某正则表达式的手机号、特定范围内的金额、未来的日期等）时，由它来负责生成符合要求的测试数据。
• 断言生成器：另一个辅助智能体。它专门分析接口的响应结构，自动生成断言语句。比如，对于返回的JSON，它会自动添加对code、message字段的断言，并对data中的关键业务字段建议断言类型。

提示词工程模块：这是决定AI产出质量的“灵魂”。我们绝不是简单地把接口文档扔给大模型说“生成测试用例”。我们为不同类型的智能体、不同业务特性的接口，精心设计了多套“提示词模板”。这些模板就像是给AI下达的详细工作指令单。一个基础的提示词模板通常包含：

1. 角色定义：明确告诉AI“你现在是一名资深的测试开发工程师”。
2. 任务目标：清晰说明“请根据以下接口文档，生成详尽的功能测试用例”。
3. 输入信息：结构化地提供接口的所有信息。
4. 输出要求：规定用例的格式（如Excel、JSON、YAML）、必须包含的字段（用例ID、标题、请求参数、预期响应等）。
5. 规则与约束：这是关键！我们会明确写出测试设计的原则，比如“必须包含等价类划分和边界值分析的用例”、“对于字符串类型字段，必须设计为空、超长、特殊字符的异常用例”、“对于枚举类型字段，必须遍历所有枚举值”等。
6. 示例（Few-Shot Learning）：提供一两个高质量的例子，让AI更好地理解我们的期望。

用例后处理器：AI生成的内容是“毛坯房”，后处理器负责“精装修”。它会做一些标准化的工作，比如统一用例标题的命名规范、校验生成的测试数据是否符合预设规则、将用例转换成团队指定的格式（如pytest的测试脚本、Postman的Collection、或直接导入TestLink/飞蛾等平台的格式）。

3. 手把手搭建：从零开始部署你的智能引擎

理论讲完了，咱们来点实在的。如果你也想在团队里试试这套东西，可以跟着我的步骤来。我们的技术栈以Python为主，因为它生态丰富，搞AI集成和自动化脚本都很方便。

3.1 基础环境与依赖准备

首先，确保你的机器上有Python 3.8或以上的版本。然后，创建一个独立的虚拟环境是个好习惯，能避免包冲突。

# 创建项目目录 mkdir ai-yapi-test-engine cd ai-yapi-test-engine # 创建虚拟环境（以venv为例） python3 -m venv venv # 激活虚拟环境 # Linux/Mac source venv/bin/activate # Windows venv\Scripts\activate # 安装核心依赖 pip install requests==2.32.3 # 用于调用Yapi和AI的API pip install openpyxl==3.1.5 # 用于读写Excel格式的用例 pip install tenacity==9.0.0 # 用于API调用的重试机制，增强稳定性 pip install pydantic==2.5.0 # 用于数据验证和设置管理，让代码更健壮

接下来是重头戏：大模型平台。你可以选择国内外的任何提供API服务的大模型，比如文心一言、通义千问、ChatGPT等。你需要去对应的平台注册账号，创建一个API Key，并确保账户里有足够的额度。把API Key和Base URL（API端点地址）保存好，我们稍后会用到。

3.2 项目结构与核心配置

按照我们架构的设计，初始化你的项目文件夹。这个结构清晰明了，未来加功能也容易。

ai-yapi-test-engine/ ├── config/ │ ├── __init__.py │ └── settings.py # 存放所有配置，如API密钥、Yapi项目Token等 ├── core/ │ ├── __init__.py │ ├── yapi_client.py # 封装Yapi API调用 │ ├── llm_client.py # 封装大模型API调用 │ └── cache_manager.py # 缓存管理逻辑 ├── agents/ # 智能体们住在这里 │ ├── __init__.py │ ├── base_agent.py # 智能体基类 │ └── single_interface_agent.py # 单接口用例生成智能体 ├── prompts/ # 提示词模板库 │ ├── __init__.py │ └── single_interface_test.j2 # Jinja2模板，方便变量插入 ├── processors/ │ ├── __init__.py │ └── case_post_processor.py # 用例后处理器 ├── outputs/ │ ├── cases/ # 生成的用例文件 │ └── logs/ # 系统运行日志 └── main.py # 程序入口

现在，我们来填充最关键的配置文件config/settings.py。我强烈建议使用pydantic的BaseSettings来管理配置，它能自动从环境变量读取，安全又方便。

# config/settings.py from pydantic_settings import BaseSettings from typing import Optional class Settings(BaseSettings): # Yapi配置 YAPI_BASE_URL: str = "https://your-yapi-server.com" # 你的Yapi地址 YAPI_PROJECT_TOKEN: str = "your_project_token_here" # 在Yapi项目设置里获取 YAPI_CACHE_EXPIRE: int = 3600 # 接口文档缓存时间（秒） # 大模型配置 (以某国内平台为例，变量名请根据实际修改) LLM_API_BASE: str = "https://dashscope.aliyuncs.com/api/v1" LLM_API_KEY: str = "sk-your-api-key-here" LLM_MODEL: str = "qwen-max" # 使用的模型名称 # 生成规则配置 CASE_OUTPUT_FORMAT: str = "excel" # 可选：excel, json, pytest class Config: env_file = ".env" # 可以从.env文件加载配置，避免硬编码 settings = Settings()

记得创建一个.env文件（不要提交到Git！）来存放你的敏感信息：

YAPI_PROJECT_TOKEN=xxxx LLM_API_KEY=sk-xxxx

3.3 编写第一个智能体：单接口用例生成器

让我们实现最核心的single_interface_agent。它继承自一个基础智能体类，主要工作是组装提示词、调用大模型、解析结果。

# agents/single_interface_agent.py import json import logging from typing import Dict, Any from .base_agent import BaseAgent from core.llm_client import LLMClient from core.cache_manager import CacheManager logger = logging.getLogger(__name__) class SingleInterfaceTestAgent(BaseAgent): def __init__(self, llm_client: LLMClient, cache_manager: CacheManager): self.llm_client = llm_client self.cache = cache_manager self.prompt_template = self._load_prompt_template("prompts/single_interface_test.j2") def run(self, interface_id: int) -> Dict[str, Any]: """为指定ID的接口生成测试用例""" logger.info(f"开始为接口 {interface_id} 生成测试用例") # 1. 获取接口数据（优先从缓存） interface_data = self._get_interface_data(interface_id) # 2. 渲染提示词 prompt = self._render_prompt(interface_data) # 3. 调用大模型 logger.debug(f"调用大模型，提示词长度：{len(prompt)}") raw_response = self.llm_client.chat_completion(prompt) # 4. 解析模型返回 test_cases = self._parse_response(raw_response) # 5. 后处理 processed_cases = self._post_process(test_cases, interface_data) logger.info(f"接口 {interface_id} 用例生成完成，共 {len(processed_cases)} 条") return { "interface_id": interface_id, "interface_name": interface_data.get("title"), "cases": processed_cases } def _get_interface_data(self, interface_id: int) -> Dict: """从缓存或Yapi获取接口数据""" cache_key = f"interface_{interface_id}" data = self.cache.get(cache_key) if not data: # 这里需要调用你的Yapi客户端获取数据 # data = yapi_client.get_interface_detail(interface_id) # self.cache.set(cache_key, data) data = {} # 示例 return data def _render_prompt(self, data: Dict) -> str: """使用Jinja2模板渲染提示词""" from jinja2 import Template template = Template(self.prompt_template) # 把接口的请求参数、返回参数、描述等信息填入模板 rendered = template.render( path=data.get('path'), method=data.get('method'), req_body_type=data.get('req_body_type'), req_body_json=data.get('req_body_other', {}), res_body=data.get('res_body', ''), title=data.get('title'), description=data.get('desc', '') ) return rendered def _parse_response(self, response: str) -> list: """解析大模型返回的JSON字符串""" try: # 模型返回可能包含markdown代码块，需要提取 if "```json" in response: json_str = response.split("```json")[1].split("```")[0].strip() elif "```" in response: json_str = response.split("```")[1].split("```")[0].strip() else: json_str = response.strip() return json.loads(json_str) except json.JSONDecodeError as e: logger.error(f"解析模型响应失败: {e}, 原始响应: {response[:200]}...") # 可以在这里加入一些启发式清洗逻辑，或者返回空列表/默认用例 return [] def _post_process(self, cases: list, interface_data: Dict) -> list: """对生成的用例进行后处理，比如添加默认断言、格式化数据""" processed = [] for i, case in enumerate(cases, 1): # 确保每个用例都有唯一ID case.setdefault('case_id', f"{interface_data.get('id')}_{i}") # 确保有请求方法 case.setdefault('method', interface_data.get('method', 'GET')) # 可以在这里调用专门的断言生成器来补充断言 processed.append(case) return processed

而对应的提示词模板prompts/single_interface_test.j2则是成败的关键。下面是一个经过我们多次迭代优化的版本：

你是一名经验丰富的测试开发工程师，擅长设计覆盖全面、边界清晰的接口测试用例。 ## 任务 请根据下方提供的接口文档信息，为该接口设计功能测试用例。最终结果请以 **一个合法的JSON数组** 格式输出，数组中的每个元素是一个测试用例对象。 ## 接口信息 - **接口名称**: {{ title }} - **接口描述**: {{ description }} - **请求路径**: {{ path }} - **请求方法**: {{ method }} - **请求体格式**: {{ req_body_type }} {% if req_body_type == 'json' %} - **请求参数(JSON Schema)**: ```json {{ req_body_json | tojson(indent=2) }}

{% endif %}

• 成功响应示例:

{{ res_body | tojson(indent=2) }}

测试用例设计规则（必须严格遵守）

1. 用例结构：每个用例必须是包含以下字段的JSON对象：

   • case_title: (string) 用例标题，简明扼要。
   • description: (string) 用例描述，说明测试目的。
   • request_params: (object) 请求参数键值对。如果是GET，参数放在query中；如果是POST/PUT，参数放在body中。
   • expected_status_code: (number) 期望的HTTP状态码，如200、400、401等。
   • expected_response: (object) 期望的响应体关键字段验证（可选，但重要字段必须包含）。
   • test_type: (string) 测试类型，如positive（正向）、boundary（边界值）、negative（异常）等。

2. 设计原则：

   • 正向用例：至少设计1条，使用合法的、典型的参数，验证接口基本功能正常。
   • 边界值分析：对所有数值型、字符串长度限制的参数，必须设计边界值用例（如最小值、最大值、略小于最小值、略大于最大值）。
   • 异常用例：必须包含参数缺失、参数类型错误、参数格式错误（如邮箱格式）、业务逻辑不允许的值等场景。
   • 参数组合：对于多个可选参数，考虑设计组合测试用例（如同时提供A和B，只提供A，只提供B，都不提供）。
   • 鉴权与安全：如果接口需要Token等鉴权信息，设计Token缺失、Token无效的用例。

输出要求

• 最终输出仅包含一个JSON数组，不要有任何额外的解释、说明或markdown格式。
• JSON数组必须能直接被json.loads()解析。
• 至少生成8条以上的测试用例，确保覆盖上述所有设计原则。

开始设计

这个模板把角色、任务、输入、规则、输出格式交代得清清楚楚，极大地约束了AI的发挥方向，使其产出标准化、高质量的结果。 ## 4. 关键决策与避坑指南：我们踩过的那些“坑” 在实际构建和投产这个引擎的过程中，我们遇到了不少挑战，也做了一些关键的技术决策。分享出来，希望能帮你少走弯路。 **决策一：为什么选择“智能体”架构而非单一函数？** 最早期的原型，我们就是一个大函数：获取数据 -> 拼提示词 -> 调API -> 解析结果。很快问题就来了：代码臃肿难以维护；想加一个新功能（比如生成场景流用例）就要把整个函数重写一遍；不同的接口类型（如文件上传、WebSocket）需要完全不同的处理逻辑。引入“智能体”模式后，每个智能体独立负责，通过基类定义统一接口（`run`方法），调度器根据需要调用不同的智能体。系统变得非常灵活，扩展新能力就像添加一个新的智能体类一样简单，符合开闭原则。 **决策二：提示词工程是“调教”AI的关键，必须版本化。** 我们曾经以为写一个通用的提示词就够了，结果发现对于“查询列表”和“创建订单”这两种业务接口，AI生成的用例侧重点完全不同。列表查询更需要关注分页、排序、过滤条件，而创建订单则更关注金额计算、库存校验、状态流转。所以，我们建立了提示词模板库，并像管理代码一样用Git进行版本控制。我们会为不同的业务域（用户中心、支付、商品）甚至不同的接口类型（CRUD）准备不同的模板，并在模板中注入具体的业务规则。这是一个持续迭代的过程，每次发现AI生成的用例有遗漏，我们不是去改代码，而是去优化对应的提示词模板。 **决策三：必须建立“缓存-回源”机制，并设置合理的过期策略。** 直接频繁调用Yapi的API有两大风险：一是可能触发Yapi的限流，导致整个引擎瘫痪；二是如果Yapi临时不可用，我们的引擎也会挂掉。因此，我们设计了缓存层。首次请求接口数据后，会缓存至少1小时。在这1小时内，所有针对该接口的生成请求都读缓存，速度极快。同时，我们设置了一个异步任务，定期刷新热门接口的缓存。这样既保护了上游系统，又提升了引擎自身的性能和稳定性。 **决策四：对AI的输出必须做“后处理”和“校验”，不能全盘接收。** 大模型有“幻觉”，可能会生成一些不合规的用例，比如请求参数里多出一些不存在的字段，或者期望响应里包含一些接口根本不会返回的字段。完全信任AI的输出是危险的。我们的后处理器会做几件事：1）用JSON Schema或Pydantic模型校验生成的用例结构是否合规；2）将用例中的测试数据（如手机号）与规则库进行匹配校验；3）调用一个轻量级的“用例合理性检查器”（其实是一组规则引擎），过滤掉明显矛盾的用例（比如期望状态码是200，但描述里写的是“参数错误”）。 **踩过的坑：** * **API限流与降级**：大模型平台的API通常有每分钟/每秒的调用次数限制。高峰期集中生成用例时容易触发限流。我们的解决方案是引入队列和限流器，将生成请求排队处理，并为非关键接口设置降级策略（如使用稍弱但免费的模型，或延后生成）。 * **长文档上下文溢出**：有些接口的响应数据结构非常深、非常大，拼接到提示词里可能会超出大模型的上下文窗口。我们不得不开发一个“文档摘要器”，只提取最关键的结构和字段描述喂给AI，而不是全量文档。 * **成本控制**：刚开始没注意，生成的用例描述写得过于详细，导致每次调用消耗的Token数很高，成本飙升。后来我们在提示词里明确要求“用例描述简洁，不超过20个字”，并优化了模板，有效控制了成本。 ## 5. 效果评估与未来展望：不止于单接口 这个引擎上线后，我们做了一个月的效果跟踪。在一个包含50个新增接口的中型项目中，传统手工设计用例平均每个接口耗时约25分钟（包括理解、设计、录入）。使用AI引擎后，从触发到生成可用的用例文件，平均时间缩短到5分钟以内，其中大部分时间是AI生成和工程师做最终复核。**效率提升确实超过了80%**。更重要的是，AI生成的用例在边界值和异常场景的覆盖度上，普遍比初级工程师更全面，减少了因用例遗漏导致的线上问题。 当然，它目前还不是全能的。正如我开头所说，现在的版本主要精于**单接口**的功能测试用例生成。对于更复杂的、涉及多个接口状态流转的**业务场景用例**，我们还在探索中。这里的挑战更大，需要AI理解业务逻辑而不仅仅是接口契约。我们下一步的计划是引入“场景流智能体”，它会尝试分析用户操作序列（比如从产品需求文档或用户故事中提取），然后自动编排多个接口调用，并生成数据依赖和状态断言。 另一个方向是让引擎变得更“主动”。我们正在尝试将它和CI/CD流水线集成，当开发同学在Yapi上更新了接口文档并标记为“已完成”时，自动触发测试用例的生成和基线化，推送给对应的测试同学进行确认。让质量保障的流程再往前移一步。 这条路走下来，我的切身感受是，AI不是来取代测试工程师的，而是来武装我们的。它就像一把锋利的“瑞士军刀”，帮我们处理那些重复、繁琐、规则明确的任务。而测试工程师的价值，则进一步向**质量分析、风险洞察、复杂场景建模和工具链建设**等高阶领域迁移。这个过程里，最关键的还是我们这些从业者，要主动去学习、去驾驭这些新技术，思考如何用它来解决实际工作中最痛的问题。如果你也在做类似的尝试，或者有更好的想法，欢迎随时交流。