Spring Boot配置Profile实现Mock外部API时遇404问题排查

需求与问题 #

想要配置Spring Boot应用实现：

• 运行mvn spring-boot:run，访问localhost:9099/api/resources调用真实接口；
• 运行mvn spring-boot:run -Pmock，访问同一地址返回Mock资源列表。

当前不加-Pmock参数可正常访问真实接口，但添加参数后出现404错误，以下是实现代码：

代码片段 #

pom.xml #

...
    <profiles>
        <profile>
            <id>macos-m1</id>
            <activation>
                <os>
                    <family>mac</family>
                    <arch>aarch64</arch>
                </os>
            </activation>
            <dependencies>
                <dependency>
                    // mac m1 specific dependency - needed on dev machine only
                </dependency>
            </dependencies>
        </profile>
        <profile>
            <id>mock</id>
            <properties>
                <spring.profiles.active>mock</spring.profiles.active>
            </properties>
        </profile> -->
    </profiles>
...

ResourceController.java（真实接口） #

@RestController
@Profile("!mock")
public final class ResourceController {

    @GetMapping("/api/resources")
    public ResponseEntity<List<Resource>> getAll() {
        List<Resource> payload = // call service to get all resources
        return ResponseEntity
            .status(HttpStatus.OK)
            .contentType(MediaType.APPLICATION_JSON)
            .body(payload);
    }
}

ResourceControllerMock.java（Mock接口） #

@RestController
@Profile("mock")
public final class ResourceController {

    @GetMapping("/api/resources")
    public ResponseEntity<List<Resource>> getAll() {
        List<Resource> payload = List.of(new Resource(x,y,z));
        return ResponseEntity
            .status(HttpStatus.OK)
            .contentType(MediaType.APPLICATION_JSON)
            .body(payload);
    }
}

问题根源与修复方案 #

1. 类名冲突 #

两个控制器类同名（都是ResourceController），Java不允许同一包下存在同名类。启用mock profile时，Spring无法正确加载Mock版本的控制器，导致无对应请求映射，出现404。

修复：修改Mock控制器类名，比如改为ResourceControllerMock：

@RestController
@Profile("mock")
public final class ResourceControllerMock { // 修改类名

    @GetMapping("/api/resources")
    public ResponseEntity<List<Resource>> getAll() {
        List<Resource> payload = List.of(new Resource(x,y,z));
        return ResponseEntity
            .status(HttpStatus.OK)
            .contentType(MediaType.APPLICATION_JSON)
            .body(payload);
    }
}

2. pom.xml语法错误 #

mock profile的结束标签</profile>后多了-->，导致XML解析异常，mock profile未被正确激活，Spring无法识别mock环境，进而不加载Mock控制器。

修复：去掉多余的-->，确保XML结构正确：

...
        <profile>
            <id>mock</id>
            <properties>
                <spring.profiles.active>mock</spring.profiles.active>
            </properties>
        </profile> <!-- 移除末尾的--> -->
    </profiles>
...

3. 验证配置 #

运行mvn spring-boot:run -Pmock后，查看控制台日志，确认是否有类似以下加载记录：

Mapping GET "/api/resources" to public org.springframework.http.ResponseEntity<java.util.List<xxx.Resource>> xxx.ResourceControllerMock.getAll()

若存在该日志，说明配置生效，此时访问localhost:9099/api/resources即可获取Mock数据。

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