基于BDD的API测试：寻求Java+Maven+Cucumber环境下Rest API测试框架

Hey there! 既然你已经在用Java + Maven + Cucumber，想搭一个BDD风格的Rest API测试框架，我给你分享几个成熟的参考方案和核心组件搭配，都是业内常用的，你可以按需调整：

一、核心依赖选型 #

首先在pom.xml中引入必要的依赖，这里推荐业内主流的组合：

<dependencies>
    <!-- Cucumber核心依赖 -->
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-java</artifactId>
        <version>7.14.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.cucumber</groupId>
        <artifactId>cucumber-junit</artifactId>
        <version>7.14.0</version>
        <scope>test</scope>
    </dependency>
    
    <!-- Rest API客户端：RestAssured（简洁易用，和Cucumber适配性好） -->
    <dependency>
        <groupId>io.rest-assured</groupId>
        <artifactId>rest-assured</artifactId>
        <version>5.3.0</version>
        <scope>test</scope>
    </dependency>
    
    <!-- JSON处理：Jackson（Java生态主流） -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.15.2</version>
        <scope>test</scope>
    </dependency>
    
    <!-- 断言库：AssertJ（比原生断言更灵活可读） -->
    <dependency>
        <groupId>org.assertj</groupId>
        <artifactId>assertj-core</artifactId>
        <version>3.24.2</version>
        <scope>test</scope>
    </dependency>
    
    <!-- JUnit测试运行器 -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

二、分层架构设计 #

为了保证框架的可维护性和复用性，建议采用四层架构：

• Feature层：用Gherkin语法编写业务场景，放在src/test/resources/features下，让非技术人员也能看懂测试逻辑
• Step Definitions层：将Gherkin步骤映射到Java代码，处理场景的流程逻辑，调用底层API服务
• API服务层：封装Rest API的请求细节（URL、请求方法、请求体、认证等），实现代码复用
• 工具/数据层：包含配置读取、JSON处理、测试数据管理等工具类，以及环境配置、测试用例数据文件

三、典型项目结构 #

your-api-test-framework/
├── src/
│   ├── test/
│   │   ├── java/
│   │   │   ├── com/yourcompany/
│   │   │   │   ├── stepdefinitions/  # Cucumber步骤定义类
│   │   │   │   │   ├── UserApiSteps.java
│   │   │   │   │   └── OrderApiSteps.java
│   │   │   │   ├── apiservices/       # API服务封装类
│   │   │   │   │   ├── UserService.java
│   │   │   │   │   └── OrderService.java
│   │   │   │   ├── utils/             # 通用工具类
│   │   │   │   │   ├── JsonUtils.java
│   │   │   │   │   └── ConfigReader.java
│   │   │   │   └── runners/           # Cucumber测试运行器
│   │   │   │       └── TestRunner.java
│   │   └── resources/
│   │       ├── features/              # Gherkin特性文件
│   │       │   ├── UserManagement.feature
│   │       │   └── OrderProcessing.feature
│   │       ├── testdata/              # 测试数据文件（JSON/CSV等）
│   │       │   ├── create_user_payload.json
│   │       │   └── update_order_payload.json
│   │       └── config.properties      # 环境配置文件（API地址、密钥等）
└── pom.xml

四、关键代码示例 #

1. Gherkin特性文件示例（UserManagement.feature） #

Feature: User Management API
  As a tester
  I want to test the User API endpoints
  So that I can ensure user creation and retrieval works correctly

  Scenario: Create a new user and verify retrieval
    Given the User API base URL is configured
    When I send a POST request to "/users" with payload from "create_user_payload.json"
    Then the response status code should be 201
    And the response body should contain the user's "email" as "test@example.com"
    And I store the "id" from response as "userId"
    When I send a GET request to "/users/{userId}"
    Then the response status code should be 200
    And the response body's "name" should be "Test User"

2. Step Definitions类示例（UserApiSteps.java） #

package com.yourcompany.stepdefinitions;

import com.yourcompany.apiservices.UserService;
import com.yourcompany.utils.ConfigReader;
import com.yourcompany.utils.JsonUtils;
import io.cucumber.java.en.Given;
import io.cucumber.java.en.Then;
import io.cucumber.java.en.When;
import io.restassured.response.Response;
import static org.assertj.core.api.Assertions.assertThat;

public class UserApiSteps {
    private final UserService userService = new UserService();
    private Response response;
    private String userId;

    @Given("the User API base URL is configured")
    public void configureBaseUrl() {
        userService.setBaseUrl(ConfigReader.getProperty("api.base.url"));
    }

    @When("I send a POST request to {string} with payload from {string}")
    public void sendPostRequest(String endpoint, String payloadFile) {
        String payload = JsonUtils.readJsonFile("testdata/" + payloadFile);
        response = userService.createUser(payload);
    }

    @Then("the response status code should be {int}")
    public void verifyStatusCode(int expectedCode) {
        assertThat(response.getStatusCode()).isEqualTo(expectedCode);
    }

    @Then("the response body should contain the user's {string} as {string}")
    public void verifyResponseBodyField(String field, String expectedValue) {
        assertThat(response.jsonPath().getString(field)).isEqualTo(expectedValue);
    }

    @And("I store the {string} from response as {string}")
    public void storeResponseField(String field, String variableName) {
        if ("userId".equals(variableName)) {
            userId = response.jsonPath().getString(field);
        }
    }

    @When("I send a GET request to {string}")
    public void sendGetRequest(String endpoint) {
        String resolvedEndpoint = endpoint.replace("{userId}", userId);
        response = userService.getUser(resolvedEndpoint);
    }
}

3. API服务封装类示例（UserService.java） #

package com.yourcompany.apiservices;

import io.restassured.RestAssured;
import io.restassured.response.Response;

public class UserService {
    private String baseUrl;

    public void setBaseUrl(String baseUrl) {
        this.baseUrl = baseUrl;
    }

    public Response createUser(String payload) {
        return RestAssured.given()
                .contentType("application/json")
                .body(payload)
                .when()
                .post(baseUrl + "/users")
                .then()
                .extract()
                .response();
    }

    public Response getUser(String endpoint) {
        return RestAssured.given()
                .contentType("application/json")
                .when()
                .get(baseUrl + endpoint)
                .then()
                .extract()
                .response();
    }
}

4. Cucumber测试运行器示例（TestRunner.java） #

package com.yourcompany.runners;

import io.cucumber.junit.Cucumber;
import io.cucumber.junit.CucumberOptions;
import org.junit.runner.RunWith;

@RunWith(Cucumber.class)
@CucumberOptions(
        features = "src/test/resources/features",
        glue = "com.yourcompany.stepdefinitions",
        plugin = {"pretty", "html:target/cucumber-reports.html", "json:target/cucumber.json"},
        monochrome = true
)
public class TestRunner {
}

五、框架扩展建议 #

• 环境切换：利用Maven Profiles或者配置文件，快速切换dev/test/prod等不同环境的API地址
• 认证处理：将OAuth2、API Key等认证逻辑封装到工具类或服务层，避免重复代码
• 报告增强：集成Allure Reports生成更直观的测试报告，支持截图、日志关联
• 数据驱动：使用Cucumber的Scenario Outline+Examples，或者结合Excel/CSV管理批量测试数据
• 重试机制：对不稳定的API接口添加重试逻辑，提升测试稳定性
• 日志记录：集成SLF4J+Logback记录请求和响应的详细信息，方便问题排查

内容的提问来源于stack exchange，提问作者VVS