在Spring Boot应用中，为多个控制器定义统一的API基础路径（如版本前缀`/api/v1`）是常见的需求。本文将详细阐述如何正确使用`@RequestMapping`注解在控制器类级别设置公共路径，而非错误地将其放置在主应用类上，从而确保API端点能够被正确映射和访问，避免404错误。
@RequestMapping注解：类与方法的组合使用
@RequestMapping是Spring框架中用于映射HTTP请求到特定处理方法或类的核心注解。它不仅可以用于方法级别，更常用于类级别，以定义该控制器所有处理方法的根路径。
当@RequestMapping应用于一个类时，它会为该类中所有处理请求的方法定义一个基础路径。方法级别的@GetMapping、@PostMapping等注解（或@RequestMapping本身）定义的路径将在此基础上进行拼接，形成完整的请求URI。
错误实践：将@RequestMapping置于主应用类
许多初学者在尝试为所有API定义一个统一前缀时，可能会尝试将@RequestMapping注解直接添加到@SpringBootApplication注解所在的主应用类上，尤其当该类也被标记为@RestController时。
例如，用户尝试的代码如下：
// CommonApplication.java
@SpringBootApplication
@RestController // 假设CommonApplication也作为控制器
@RequestMapping("/api/v1") // 尝试在此处定义全局基础路径
public class CommonApplication {
public static void main(String[] args) {
SpringApplication.run(CommonApplication.class, args);
}
}// ProductController.java
@RestController
@RequestMapping() // 此处为空，期望继承CommonApplication的/api/v1
public class ProductController {
@GetMapping("/products")
public String getProducts() {
return "Hello from getProducts 12";
}
}问题分析：
当尝试访问/api/v1/products时，会得到404错误。这是因为：
- @SpringBootApplication注解主要用于启动Spring Boot应用，它本身并不直接参与请求映射的全局路径定义。
- 即使CommonApplication类同时被标记为@RestController和@RequestMapping("/api/v1")，这个@RequestMapping也仅对CommonApplication类内部定义的所有请求处理方法有效。
- @RequestMapping注解不会自动“传播”或“继承”到其他独立的控制器类（如ProductController）。每个控制器类都需要独立定义其自身的根路径。因此，ProductController上的空@RequestMapping()（或不写）意味着它的基础路径是根路径/，而非/api/v1。当其内部的@GetMapping("/products")被调用时，它实际上映射的是/products，而不是/api/v1/products。
正确实践：在控制器类上定义基础路径
要实现为特定API组（如所有产品相关的API）定义统一的基础路径，正确的做法是将@RequestMapping注解直接应用于相应的控制器类。
修正后的代码示例：
首先，确保CommonApplication类专注于应用启动，移除不必要的@RestController和@RequestMapping（除非它本身确实需要作为控制器处理请求）。
// CommonApplication.java (仅用于启动应用)
package com.example.common; // 假设的包名
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class CommonApplication {
public static void main(String[] args) {
SpringApplication.run(CommonApplication.class, args);
}
}然后，在ProductController类上添加@RequestMapping("/api/v1")来定义其基础路径：
// ProductController.java
package com.example.common.controller; // 假设的包名
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
@RequestMapping("/api/v1") // 正确地将基础路径应用于控制器类
public class ProductController {
// private ProductService productService; // 假设有服务层依赖
@GetMapping("/products") // 此方法将映射到 /api/v1/products
public String getProducts() {
return "Hello from getProducts 12";
}
@GetMapping("/products/{id}") // 此方法将映射到 /api/v1/products/{id}
public String getProductById() {
return "Hello from getProductById";
}
}工作原理：
- 当ProductController被Spring扫描并注册为一个Bean时，它会识别到类级别的@RequestMapping("/api/v1")。
- ProductController内部的所有@GetMapping、@PostMapping等方法级别的路径注解，都会在/api/v1的基础上进行拼接。
- 因此，@GetMapping("/products")将正确映射到完整的URI：/api/v1/products。
现在，访问GET http://localhost:8080/api/v1/products将成功返回"Hello from getProducts 12"。
注意事项与最佳实践
职责分离： 保持主应用类@SpringBootApplication的简洁性，主要用于应用启动和配置。将具体的业务逻辑和请求处理放在独立的控制器类中。
明确性： 每个控制器类都应该明确地定义其自身的@RequestMapping基础路径，这有助于代码的可读性和维护性。
-
路径常量： 对于常用的API基础路径（如/api/v1），可以将其定义为常量，并在多个控制器中引用，以避免硬编码和潜在的拼写错误。
// ApiConstants.java public class ApiConstants { public static final String API_V1_BASE = "/api/v1"; public static final String PRODUCTS_PATH = "/products"; } // ProductController.java @RestController @RequestMapping(ApiConstants.API_V1_BASE) public class ProductController { @GetMapping(ApiConstants.PRODUCTS_PATH) public String getProducts() { /* ... */ } } -
全局上下文路径： 如果需要为整个Spring Boot应用设置一个全局的URL前缀（例如，使所有API都通过/my-app/api/v1/...访问），可以在application.properties或application.yml中配置server.servlet.context-path属性。但这与API版本化是不同层面的概念，context-path会应用于所有请求，而@RequestMapping仅应用于特定控制器。
# application.properties server.servlet.context-path=/my-app
此时，ProductController的/api/v1/products将通过/my-app/api/v1/products访问。
总结
在Spring Boot中为API定义统一的基础路径，如API版本前缀，应将@RequestMapping注解应用于各个相关的控制器类，而非主应用类。这种做法确保了路径映射的清晰性和正确性，使得控制器能够按照预期处理请求，并有效避免因路径配置不当导致的404错误。通过遵循这些最佳实践，可以构建出结构清晰、易于维护的RESTful API。
