Spring MVC 路径匹配规则

前言

在 Spring MVC 中，路径匹配规则决定了 URL 请求如何映射到控制器方法。通过实现 WebMvcConfigurer 接口，可以灵活地自定义这些规则。

1. 自定义路径匹配配置

在路径匹配配置中，通常会涉及以下几个关键点：

• 后缀匹配（Suffix Pattern Match）：是否允许通过路径后缀进行模糊匹配，如 /user 是否匹配 /user.json。
• 尾部斜杠匹配（Trailing Slash Match）：是否将 /user 和 /user/ 视为相同路径。
• 统一路径前缀（Path Prefix）：为所有或部分控制器添加路径前缀，如 /api 或 /v1，用于 API 版本管理或模块化设计。

2. 路径匹配配置示例

@Configuration // 标识为Spring配置类
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configurePathMatch(PathMatchConfigurer configurer) {
        // 禁用后缀模式匹配，避免 URL 后缀被误认为路径的一部分
        configurer.setUseSuffixPatternMatch(false);
        
        // 启用尾部斜杠匹配，让 /user 和 /user/ 被视为相同路径
        configurer.setUseTrailingSlashMatch(true);
        
        // 为所有控制器的路径添加统一的 /api 前缀
        configurer.addPathPrefix("api", c -> true);
    }
}

3. 关键配置参数说明

3.1 禁用后缀模式匹配（setUseSuffixPatternMatch）

• 默认行为：Spring MVC 默认会对 URL 路径的后缀进行模糊匹配，例如 /user 可以匹配到 /user.json、/user.xml 等。
• 推荐配置：出于安全考虑以及避免路径匹配的歧义，通常建议禁用后缀模式匹配。

// 禁用后缀匹配，增强 URL 路径的安全性和明确性
configurer.setUseSuffixPatternMatch(false);

3.2 启用尾部斜杠匹配（setUseTrailingSlashMatch）

• 作用：启用后，/user 和 /user/ 会被视为相同的路径，增强了 URL 的容错性。
• 推荐配置：在大多数场景中，建议启用尾部斜杠匹配，以提高用户访问的灵活性。

// 启用尾部斜杠匹配，路径对斜杠不敏感
configurer.setUseTrailingSlashMatch(true);

3.3 为控制器添加路径前缀（addPathPrefix）

• 作用：通过为控制器添加路径前缀，可以轻松为应用中的所有或部分 API 统一添加前缀，如版本号 (/v1/) 或 /api/。这在构建具有清晰 URL 结构的 RESTful API 时特别有用。
• 注意事项：该配置仅影响控制器的路径，不影响静态资源路径。

// 为所有控制器添加 /api 前缀，通常用于 API 版本控制或模块化设计
configurer.addPathPrefix("api", c -> true);

4. 示例应用与测试

4.1 创建控制器

@RestController // 标识为 REST 控制器，返回 JSON 数据
@RequestMapping("/test") // 基础路径 /api/test
public class TestController {

    @GetMapping("/hello") // 实际访问路径为 /api/test/hello
    public String sayHello() {
        return "Hello, Spring MVC!";
    }
}

4.2 启动应用并测试

启动 Spring Boot 应用后，使用浏览器或 Postman 访问以下地址进行测试：

• 访问路径：http://localhost:8080/api/test/hello

预期结果：返回 "Hello, Spring MVC!"，表示路径匹配配置已生效。

5. 常见的路径前缀配置冲突

在 Spring Boot 中，有两种常见的路径前缀配置：

1. 上下文路径前缀（server.servlet.context-path）：影响应用中所有的 URL 路径，包括静态资源。

   • 配置示例：server.servlet.context-path=/app
   • 访问路径示例：http://localhost:8080/app/api/test/hello

2. 控制器路径前缀（addPathPrefix）：仅影响控制器的路径。

   • 配置示例：configurer.addPathPrefix("/api", c -> true)
   • 访问路径示例：http://localhost:8080/app/api/test/hello

注意：如果两者同时使用，路径会叠加。

总结

1. 路径匹配配置在 Spring MVC 中非常灵活，可以根据需求定制不同的匹配策略。
2. 推荐禁用后缀匹配和启用尾部斜杠匹配，以确保 URL 的清晰性和一致性。
3. 使用路径前缀配置可以帮助构建清晰的 API 路径结构，特别是在 RESTful API 开发中非常有用。