企业官网建设流程全解析

如果你所在的团队既有基于 Java 的 UI 自动化框架，又有用 Python 写的接口自动化脚本，那你大概率经历过这种拧巴：平时开一个 IDEA 写 Java 用例，跑 Python 脚本还要切到 PyCharm，两个项目各存一份环境配置，CI 上也是各跑各的，报表风格完全对不上，新同学接手时更是连“该开哪个 IDE”都要问一圈。这篇用 IDEA 搭建 Python 与 Java 自动化框架的保姆级教程，就是围绕这个痛点，把两个技术栈揉进同一个工程，从插件安装、模块结构、依赖管理到报告合并、CI 执行，一步步说清楚，顺便把我踩过的坑也一起交代了。

我自己的体会是：多语言测试框架最怕的不是写不出来，而是“分开维护”。Java 负责浏览器端、Python 负责接口层，听起来分工清晰，一旦 IDE、依赖、报告、脚本全部分开，光切换上下文的时间和心智成本就够喝一壶。下面这套方案适合正在搭建自动化框架、或者想把手头两套东一块西一块的脚本整合起来的测试开发，也适合刚入门、想知道“为什么这样搭”的后端自动化新人。

1. 先想明白：这套框架到底要解决什么

1.1 多语言测试资产的三种拆法

动手前先别急着建目录，多语言框架最常见的失败原因，是把 Java 和 Python 硬塞进同一个“大锅”里，结果两边互踩配置，看起来统一了，实际谁都跑不顺。我推荐的拆法是：源码放同一个仓库，运行时各自独立，依赖互相隔离，只在报告、配置、执行入口这三个层面做合并。

三种常见拆法你可以在项目里选：

• 全 Java：UI、接口都用 Java 写，优点是语言统一，但对接口测试来说，Python 生态处理数据、校验 JSON、写脚本明显更轻快，硬用 Java 只会增加维护成本。
• 全 Python：接口和 UI 都用 Selenium + Pytest，上手快，但大型 UI 用例在类型约束、依赖管理和并行执行上，Java 侧还是更稳。
• Java + Python 混合：UI 走 Java + Maven，接口走 Python + venv，各用各的强项，最后用同一套报告和执行入口收拢。

这套教程走的是第三种。核心设计原则很简单：Java 部分定位浏览器层，负责页面元素、页面对象、操作流程和端到端断言；Python 部分定位 API 层，负责接口请求、参数化、数据校验和契约检查。两边互不直接调用，代码层不互相 import，信息和结果通过配置文件、结果文件来交换。

1.2 为什么不能再“两个 IDE 双开”

我自己有一段非常痛苦的经历：Java 的 UI 用例跑挂了，切到 PyCharm 去查接口数据，再来回对比浏览器的日志和接口响应，两边快捷键不一致，索引各占一份内存，环境变量也经常忘记同步。时间一长，大家宁愿把接口测试也硬写在 Java 里，恶性循环。

把两个模块放进同一个 IDEA 工程后，哪怕只是让源码在一个窗口里浏览，检索符号、全局搜索、快速打开测试文件，效率都完全不一样。而且 Maven 的模块管理和 Python 的虚拟环境可以各管各的，互不污染。这个“看得见但分得开”的状态，才是我要的效果。

提示：如果你把 Java 和 Python 放进同一个目录树却共享同一个 target 或 venv，最后一定会在依赖清理时把两边都搞坏。正确的做法是模块平级、环境分区、报告合并，而不是代码互融。

2. 为什么用 IDEA 而不直接上 PyCharm

2.1 IDEA、PyCharm、VSCode 的取舍

先给结论：如果你手里已经有一个成熟的 Java + Maven 自动化项目，并且团队主力 IDE 是 IDEA，那么为了 Python 接口测试再去单独维护一个 PyCharm，边际成本很高。IDEA 旗舰版里安装官方 Python 插件后，写 pytest、调试脚本、跑 requests 用例，日常绝对够用。如果你主要工作已经转向纯 Python 开发，那 PyCharm 依然是最稳的选择，没必要为了“一把梭”强行换。

我用过几个组合，列个对比：

这里要特别提醒：IDEA 社区版对 Python 的支持非常有限，官方 Python 插件基本只随旗舰版提供。使用社区版的话，要么升级到旗舰版，要么干脆继续用 PyCharm 跑 Python，别在中途硬折腾第三方插件，稳定性和调试体验都不理想。

2.2 统一 IDE 真正省下的是上下文切换

双开的隐藏成本，不是那几百兆内存，而是“上下文切换”。你在 IDEA 里刚写好一个 Java 页面对象，想确认它调用的接口返回什么，就得切到 PyCharm，重新打开脚本，等到解释器和索引都就绪，再跑一次请求，中间过手的心态成本极大。测试代码本身已经够琐碎了，不应该再让工具切换再来一层损耗。

统一到 IDEA 之后，虽然 Python 侧的代码补全和调试体验和 PyCharm 相比还是有一些差距，但换来的是源码仓库、执行入口、报告目录的绝对统一。这对团队协作的价值，尤其在人数超过两三个之后，远高于 IDE 本身的补全手感。

3. 项目初始化和多模块结构搭建

3.1 安装 Python 插件并准备基础环境

如果你用的是 IDEA Ultimate，操作路径是：进入 Settings，找到 Plugins，搜索 Python，点击 Install，重启 IDEA。这一步不复杂，但很多人会漏掉一个前置条件：本机必须已经装好能用的 Python 解释器，并且版本要和团队约定一致，不要指望 IDEA 帮你装一个标准 Python。

我建议统一用 Python 3.11 或 3.12，选一个长期维护版本，并在团队文档里写死。接口自动化用到的新语法特性、第三方库兼容性，这两个版本都支持得很好。JDK 侧建议 17 或 21，Maven 用 3.9 及以上。兼容性组合如下：

• Python 3.11 / 3.12，虚拟环境使用 venv。
• JDK 17 或 21，编译级别和 Maven 插件版本保持一致。
• Maven 3.9.x，IDEA 内置的也可以，但使用独立 Maven 更可控。
• Selenium 4.x，搭配 WebDriverManager 5.x。
• Pytest 8.x，搭配 requests。

这些组合我在项目里实测过，稳定性没问题。版本号不建议追最新，最新往往意味着插件、Allure 适配器还没跟上。

3.2 创建父目录，用模块区隔两类项目

打开 IDEA，新建一个 Empty Project，名字建议叫 automation-framework，然后在这个工程下创建两个平级模块。第一个选 Maven，ArtiFactId 我习惯叫 java-ui；第二个选 Python Module，名字叫 python-api。如果你用的 IDEA 版本里没有 Python Module 选项，可以先建一个普通模块，再去 Project Structure 里把这块目录的 SDK 指定为 Python，并把源码根目录标记好。

目录结构我建议长这样：

automation-framework/ ├── config/ │ └── env.json ├── java-ui/ │ ├── pom.xml │ ├── src/main/java/... │ ├── src/test/java/... │ └── target/ ├── python-api/ │ ├── .venv/ │ ├── requirements.txt │ ├── pytest.ini │ ├── tests/ │ ├── utils/ │ └── allure-results/ ├── reports/ │ └── allure-report/ ├── runner/ │ └── run_all.sh ├── .gitignore └── README.md

这里最重要的一条：python-api 绝不能放到 java-ui/src 底下。IDEA 在处理 Maven 模块时会把 src 目录按 Java 编译逻辑扫描，Python 文件夹放进去会导致大量误报，甚至影响 Java 编译。两个模块必须是兄弟关系，而不是父子关系。

3.3 给 python-api 配置虚拟环境

选中 python-api 模块，右键打开 Module Settings，在 SDK 一栏选择新建虚拟环境。IDEA 会调用本机的 Python 解释器帮你创建 .venv。创建完成之后，打开终端执行：

cd python-api python -m venv .venv

但更推荐用 IDEA 的界面操作，因为它会把虚拟环境自动关联到当前模块，省去很多手动激活和设置解释器的步骤。虚拟环境创建好之后，把项目依赖写进 requirements.txt，不要图省事直接装到系统 Python 里，不然换一台机器或者换个人，环境就彻底不可控。

pytest.ini 建议一开始就配好，告诉 Pytest 测试路径和报告参数：

[pytest] testpaths = tests addopts = -q --tb=short

3.4 配置 Maven 和 Java 编译参数

Java 模块的父 pom 可以只做一个聚合模块，把 java-ui 作为子模块收录。父 pom 大致长这样：

<project> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>automation-framework</artifactId> <version>1.0.0</version> <packaging>pom</packaging> <modules> <module>java-ui</module> </modules> </project>

子模块 pom 里设置 Java 编译版本为 17，并加上 Selenium、WebDriverManager、JUnit 5、Allure JUnit 5 适配器依赖。Maven 的依赖解析走默认中央仓库即可，但如果团队在内网，需要提前配好 settings.xml 里的镜像地址，否则 WebDriverManager 下载驱动也会因为网络策略失败。

3.5 Git 忽略清单一定要提前写

这个细节很多人后悔晚知道。python-api/.venv 动不动几百 MB，java-ui/target 每次编译都会生成大量临时文件，如果一开始没加 .gitignore，仓库很快就会被撑爆，合并代码时冲突也多到想哭。

.idea/ *.iml **/target/ **/.venv/ __pycache__/ *.pyc .pytest_cache/ allure-results/ reports/

这里我建议 reports 目录整体忽略，Allure 报告是生成物，不需要提交；但 config/env.json 建议提交一个不带真实账号密码的模板文件，具体环境变量由使用者各自覆盖。

4. Java + Selenium 做 UI 自动化层

4.1 为什么 Java 侧用 Selenium 加 WebDriverManager

Java 侧我首选 Selenium 4.x，原因比较实在：生态成熟、资料多、Page Object 模式在 Java 里表达得最直观。更难搞的是浏览器驱动版本匹配，早期用 Selenium 的人基本都经历过手动下载 ChromeDriver，然后因为浏览器自动升级导致驱动全部失效。WebDriverManager 这个库就是用来解决这个痛点的，它会在运行前自动匹配当前浏览器版本，下载或复用对应驱动。

pom.xml 里和 UI 自动化相关的核心依赖大致是这些：

<dependencies> <dependency> <groupId>org.seleniumhq.selenium</groupId> <artifactId>selenium-java</artifactId> <version>4.27.0</version> </dependency> <dependency> <groupId>io.github.bonigarcia</groupId> <artifactId>webdrivermanager</artifactId> <version>5.9.2</version> </dependency> <dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter</artifactId> <version>5.11.4</version> <scope>test</scope> </dependency> <dependency> <groupId>io.qameta.allure</groupId> <artifactId>allure-junit5</artifactId> <version>2.29.1</version> <scope>test</scope> </dependency> </dependencies>

版本号不用死记，核心思路是 Selenium 4.x + WebDriverManager 5.x + JUnit 5 + Allure 2.x 这一套能互相兼容就行。如果你公司内网限制下载，记得提前把 Maven 镜像和 WebDriverManager 的下载源都配到内网服务器上。

4.2 Page Object 和 BasePage 封装

Java 写 UI 自动化的核心不是“能点”，而是“经得起改”。我强烈建议用 Page Object 模式，把页面上所有元素定位都收敛到页面类里，测试类只描述业务操作。接下来你需要一个 BasePage，把显示等待、点击、输入这些通用操作做掉。

public class BasePage { protected WebDriver driver; protected WebDriverWait wait; public BasePage(WebDriver driver) { this.driver = driver; this.wait = new WebDriverWait(driver, Duration.ofSeconds(10)); } protected void click(By locator) { wait.until(ExpectedConditions.elementToBeClickable(locator)).click(); } protected void input(By locator, String text) { wait.until(ExpectedConditions.visibilityOfElementLocated(locator)).sendKeys(text); } }

登录页可以继承它：

public class LoginPage extends BasePage { private By username = By.id("username"); private By password = By.id("password"); private By loginButton = By.id("loginBtn"); public LoginPage(WebDriver driver) { super(driver); } public void login(String user, String pwd) { input(username, user); input(password, pwd); click(loginButton); } }

要注意一点：等待时间不能写死太长，超过 10 秒的隐式等待对失败定位毫无帮助，反而会让用例在页面卡住时白等。我一般把默认超时控制在 10 到 15 秒，并且只在关键步骤上加显式等待，而不是每个元素都等。

4.3 用例编写与 Maven 运行

测试类只需要关心业务流程：

public class LoginTest { private WebDriver driver; @BeforeEach void setUp() { WebDriverManager.chromedriver().setup(); ChromeOptions options = new ChromeOptions(); options.addArguments("--headless=new"); driver = new ChromeDriver(options); } @Test void shouldLoginSuccessWithValidUser() { LoginPage loginPage = new LoginPage(driver); loginPage.login("test_user", "test_password"); String currentUrl = driver.getCurrentUrl(); Assertions.assertTrue(currentUrl.contains("/home")); } @AfterEach void tearDown() { if (driver != null) { driver.quit(); } } }

命令行运行方式：

mvn clean test -Dtest=LoginTest

跑完之后，Allure 结果默认生成在 target/allure-results 目录。这里我想强调一个细节：ChromeOptions 里加不加 headless 要看你跑在本地还是 CI。本地调试加 headless 会看不到页面，反而难排查；CI 上不加 headless 又会因为没图形界面报错，所以最好把它做成环境变量控制。

5. Python + Pytest + Requests 做接口自动化层

5.1 创建虚拟环境并安装依赖

Python 侧的依赖很轻，requests 管 HTTP、pytest 管用例、allure-pytest 管报告。在 python-api 目录下创建并激活虚拟环境：

cd python-api python -m venv .venv source .venv/bin/activate pip install requests pytest allure-pytest

然后把固定版本写进 requirements.txt：

requests==2.32.3 pytest==8.3.4 allure-pytest==2.13.5

这里为什么不直接用最新版？接口测试框架的依赖升级往往带出很多不兼容的小问题，比如 Pytest 8.x 对旧插件的改动。团队合作时，requirements.txt 必须锁定版本，CI 才能复现出和本地一模一样的环境。

5.2 conftest 中准备公共请求会话

接口测试通常要处理登录、token、公共请求头这些事。conftest.py 里放一个 session fixture，让所有测试共用同一个 requests.Session，避免每个用例都重新登录一次。

import json import requests import pytest @pytest.fixture(scope="session") def api_session(): env = json.load(open("../config/env.json", encoding="utf-8")) session = requests.Session() session.base_url = env["api_base_url"] resp = session.post(f"{session.base_url}/login", json={"username": "test", "password": "test"}) token = resp.json()["token"] session.headers.update({"Authorization": f"Bearer {token}"}) yield session

session 用 scope="session" 而不是默认的 function，能明显减少登录次数，接口用例越多收益越明显。但要注意 token 过期时间，如果接口系统的 token 有效期很短，session 级 fixture 反而会埋雷。

5.3 参数化用例和 pytest 数据驱动

接口测试最大的优势是数据驱动的表达非常自然。用 pytest.mark.parametrize 可以一口气覆盖多个输入组合：

import pytest @pytest.mark.parametrize("username,password,expected_code", [ ("valid", "valid", 200), ("valid", "wrong", 401), ("", "", 400), ]) def test_login_cases(api_session, username, password, expected_code): resp = api_session.post(f"{api_session.base_url}/login", json={ "username": username, "password": password, }) assert resp.status_code == expected_code

这里我建议把“预期结果”也作为一个参数，而不是在用例里写一堆 if 判断。接口测试最忌讳的是把用例代码写成流程分支，一旦分支多起来，阅读成本会迅速超过业务价值。你要维护的是一张“输入-预期输出”表，不是一段复杂的校验逻辑。

5.4 运行接口测试并输出 Allure 报告

运行方式：

cd python-api .venv/bin/python -m pytest tests --alluredir=allure-results

这里有个很关键的坑：务必使用 .venv/bin/python -m pytest，而不是直接敲 pytest。如果 IDEA 的终端没激活虚拟环境，你敲 pytest 很可能会调到一个全局环境，然后报 ModuleNotFoundError。使用 python -m 的方式，能确保解释器和当前虚拟环境绑定。

allure-pytest 会在 python-api/allure-results 下生成 JSON 结果文件，这些文件就是给后续报告合并用的。

6. 把 Java 和 Python 的框架真正打通

6.1 公共配置与动态数据交换

既然已经放进同一个工程，最应该统一的不是代码，而是配置。我在 config/env.json 里放环境相关的内容：

{ "env": "test", "api_base_url": "https://api.test.example.com", "ui_base_url": "https://web.test.example.com", "browser": "chrome", "headless": true }

Java 侧可以用 Jackson 把它读成对象，Python 侧用 json.load 直接读取。两边不再各自维护一套 properties 和 .env，环境切换时只需要改一个文件。需要注意路径问题，不同模块启动时工作目录可能不同，我建议在读取时基于仓库根目录计算，而不是基于当前工作目录。

6.2 Allure 报告合并与生成

Java 侧跑完生成 java-ui/target/allure-results，Python 侧跑完生成 python-api/allure-results，最后一条命令把它们合并成一份报告：

allure generate java-ui/target/allure-results python-api/allure-results -o reports/allure-report --clean

合并的时候记得加 --clean，否则多次执行后旧数据会残留，报告里的统计会越来越离谱。还有一点，本机需要安装 Allure 命令行工具，版本最好和 Java、Python 的适配器保持一致，否则会出现“用例跑了但没有显示在报告里”的诡异问题。

6.3 一键执行脚本和 CI 接入

本地开发时，你当然可以分别跑两个框架，但到了 CI 上一定要有一个统一的执行入口。我在 runner 目录放了一个 run_all.sh：

#!/usr/bin/env bash set -e cd "$(dirname "$0")/.." echo "1/3 执行 Java UI 自动化" cd java-ui && mvn clean test echo "2/3 执行 Python 接口自动化" cd ../python-api && .venv/bin/python -m pytest tests --alluredir=allure-results echo "3/3 合并生成 Allure 报告" allure generate java-ui/target/allure-results python-api/allure-results -o reports/allure-report --clean

脚本开头一定要 set -e，意思是任何一步失败，后续步骤直接停止，避免“Java 已经挂了但 Python 还在跑”的假成功情况。CI 上只需要拉仓库、执行 run_all.sh、最后把 reports 目录归档，一套流程就通了。

统一执行入口带来的感受是质变：以前是两套命令、两套日志、两套报告，现在任何人跑一次脚本就能拿到整体质量结果。

7. 常见问题与排查技巧实录

7.1 高频报错速查表

这些问题都是我实际运行中遇到过的，可以直接收藏。

7.2 比官方文档更值钱的几个心得

第一个心得是：一开始就把 Python 版本和 Java 版本在 README 里写死。团队中有人用 3.9、有人用 3.13，最后合出来一堆“本地好好的、CI 就挂”的问题，全部都是版本差异搞的鬼。统一版本可比统一 IDE 重要得多。

第二个心得是：两个框架之间不要做代码级互相调用。有人说可以写 Java 进程调用 Python 脚本，或者反过来，短期内能跑通，但长期维护会变成噩梦。你只需要通过文件、配置、报告来交换情报，让两边保持松弛耦合，这比任何“技术炫技”都重要。

第三个心得：报告统一比代码统一更重要。测试框架的本质是团队的质量视图，如果你的 Java、Python、接口、UI 各自输出格式完全不同的报告，管理者只会看到一堆数据碎片，价值大打折扣。Allure 恰好提供了比较好的承载方式，既然用了就把它合并彻底。

8. 什么时候适合抄这套方案

8.1 强烈推荐的场景

如果你的团队已经有长期运行的 Java UI 自动化资产，同时接口测试用 Python 明显更顺手，那就非常适合把这套 IDEA 多模块方案落下来。源码在一个仓库里打开，模块之间边界清楚，CI 执行一条命令出整体报告，这种体验对刚开始搞自动化的团队尤其重要。

8.2 不推荐的场景

如果你本来就是一个纯 Python 团队，所有工作都在 PyCharm 里，完全没必要为了“我用 IDEA”而硬上。工具永远是为人服务的，不要让工具成为新的负担。同理，如果你还在用 IDEA 社区版，又不想升级，那我还是建议 Python 侧继续用 PyCharm，不要硬在社区版里折腾 Python 插件。

最后再分享一个自己踩过的坑：两个框架虽然都在一个仓库里，但要记得它们运行时的依赖、解释器、产物是完全隔离的。真正把它们绑在一起的，不是代码，而是项目根目录下那一份 env.json，以及 runner 脚本里那几条顺序明确的命令。只要这两个“接口”稳定，Java 和 Python 各自怎么拆、怎么升级，都不会相互拖后腿。按照这套思路搭起来之后，最直观的感受是：团队里不再有人问“这个用例该用哪个 IDE 跑”，因为打开同一个工程，所有东西都在那儿了。