Java 注解篇：@RequestMapping

前言

        @RequestMapping 是 Spring Framework 中用于处理 Web 请求的核心注解之一。它用于将 HTTP 请求映射到具体的处理方法上，构成了 Spring MVC 的基础。本文将从注解的基本用法、进阶功能、底层原理、源码解析以及实战案例五个方面，系统地剖析 @RequestMapping 的工作机制和使用方式。

一、@RequestMapping 的基本概念

        @RequestMapping 是 Spring Web 中提供的注解，用于将请求 URL 与控制器方法进行映射。它可以注解在类或方法上。

注解定义如下：

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestMapping {
    String name() default "";
    String[] value() default {};
    RequestMethod[] method() default {};
    String[] params() default {};
    String[] headers() default {};
    String[] consumes() default {};
    String[] produces() default {};
}

二、基本用法

2.1 映射路径

@RequestMapping("/hello")
public String hello() {
    return "Hello, World!";
}

2.2 指定 HTTP 方法

@RequestMapping(value = "/users", method = RequestMethod.GET)
public List<User> getUsers() {
    return userService.findAll();
}

2.3 类级别与方法级别组合使用

@RestController
@RequestMapping("/api")
public class UserController {

    @RequestMapping("/users")
    public List<User> getUsers() {
        return userService.findAll();
    }
}

2.4 使用 @GetMapping 等快捷注解

@GetMapping("/users")
public List<User> getUsers() {
    return userService.findAll();
}

这些快捷注解本质上是 @RequestMapping 的组合注解：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@RequestMapping(method = RequestMethod.GET)
public @interface GetMapping {
    String[] value() default {};
}

三、进阶用法

3.1 路径参数

@RequestMapping("/user/{id}")
public User getUser(@PathVariable("id") Long id) {
    return userService.findById(id);
}

3.2 请求参数限制

@RequestMapping(value = "/users", params = "role=admin")
public List<User> getAdmins() {
    return userService.findAdmins();
}

3.3 请求头限制

@RequestMapping(value = "/users", headers = "X-API-KEY=abc123")
public List<User> getUsersWithHeader() {
    return userService.findAll();
}

3.4 消费和生产类型

@RequestMapping(value = "/users", consumes = "application/json", produces = "application/json")
public ResponseEntity<User> addUser(@RequestBody User user) {
    userService.save(user);
    return ResponseEntity.ok(user);
}

四、实现原理与源码解析

4.1 注解解析过程

@RequestMapping 是由 Spring MVC 的 RequestMappingHandlerMapping 进行处理的。

在初始化阶段，Spring 会扫描所有的 @Controller 或 @RestController 类，并将其方法上标注了 @RequestMapping 的方法注册到 HandlerMapping 中。

核心类包括：

• RequestMappingHandlerMapping：处理请求映射注册

• HandlerMethod：封装 Controller 方法信息

• RequestMappingInfo：封装请求路径、请求方法等信息

4.2 注册过程源码示意

protected void detectHandlerMethods(Object handler) {
    Class<?> handlerType = (handler instanceof String ? obtainApplicationContext().getType((String) handler) : handler.getClass());
    for (Method method : handlerType.getDeclaredMethods()) {
        RequestMappingInfo mapping = getMappingForMethod(method, handlerType);
        if (mapping != null) {
            registerHandlerMethod(handler, method, mapping);
        }
    }
}

4.3 请求匹配过程

当请求到达时，DispatcherServlet 将请求委托给 HandlerMapping 查找匹配的 Handler。

匹配的依据包括：

• URL 路径（支持通配符、正则）

• 请求方法（GET、POST）

• 请求参数

• 请求头

若匹配成功，则调用对应的 HandlerAdapter 执行目标方法。

五、常见问题与解决方案

5.1 请求方法不匹配

报错：Request method 'POST' not supported

• 原因：方法未指定或未支持 POST

• 解决：检查 @RequestMapping 的 method 属性

5.2 路径冲突

• 原因：类与方法级别重复定义相同路径

• 解决：路径应唯一组合

5.3 请求内容类型不匹配

• 报错：Content type 'application/json' not supported

• 解决：添加 consumes 属性，或者添加 HttpMessageConverter

六、实战案例

6.1 RESTful API

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping
    public List<User> list() {
        return userService.findAll();
    }

    @PostMapping
    public User add(@RequestBody User user) {
        return userService.save(user);
    }

    @GetMapping("/{id}")
    public User get(@PathVariable Long id) {
        return userService.findById(id);
    }

    @PutMapping("/{id}")
    public User update(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userService.update(user);
    }

    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        userService.delete(id);
    }
}

七、总结

        @RequestMapping 是 Spring MVC 提供的核心注解，支持强大的请求映射能力。它与 DispatcherServlet、HandlerMapping 等组件密切配合，实现了灵活的 Web 请求分发机制。在实际开发中，掌握其用法和实现机制，不仅能提高开发效率，还能更好地排查问题，构建清晰、高效的接口体系。

        随着 Spring Boot 的发展，@GetMapping、@PostMapping 等组合注解的出现，进一步简化了使用方式。但无论形式如何变化，其核心原理仍然依托于 @RequestMapping 的底层机制。

        掌握 @RequestMapping，不仅是精通 Spring MVC 的基础，更是深入理解 Spring Web 体系的第一步。