Spring RESTful API 开发注解详解

作为一个经常从事 Spring 开发的开发者，我会基于实际项目经验，向大家详细介绍 Spring 中常用的 RESTful API 注解及其使用方法。

1. @Controller 注解

@Controller 是 Spring 的一个核心注解，用于标注处理 HTTP 请求的控制器类。它的作用是将 HTTP 请求映射到具体的方法上。

package org.springframework.stereotype;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component
public @interface Controller {
    String value() default "";
}

使用场景：可以用在类上，用于标注处理 HTTP 请求的控制器类。

默认方法：@Controller 默认没有具体的方法，通常需要手动定义处理方法。

2. @ResponseBody 注解

@RequestBody 是一个常用的注解，用于将 HTTP 请求的正文绑定到一个对象上。它主要用于处理 POST、PUT 等请求，适用于数据插入场景。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestBody {
    String value() default "";
}

使用场景：可以用在类上或方法上，用于将 HTTP 请求正文绑定到对象上。

默认方法：@RequestBody 默认没有具体的方法，需要手动定义如何处理请求正文。

3. @RestController 注解

@RestController 是 @Controller 和 @ResponseBody 的综合注解，用于标注处理 RESTful API 请求的控制器类。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.stereotype.Controller;
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Controller
@ResponseBody
public @interface RestController {
    String value() default "";
}

使用场景：用于标注处理 RESTful API 请求的控制器类。

默认方法：和 @Controller 一样，需要手动定义具体的处理方法。

4. @RequestMapping 注解

@RequestMapping 是 Spring 用于配置 URL 映射的注解，既可以用在类上，也可以用在方法上。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.core.annotation.AliasFor;
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
public @interface RequestMapping {
    String name() default "";
    @AliasFor("path")
    String[] value() default {};
    @AliasFor("value")
    String[] path() default {};
    RequestMethod[] method() default {};
    String[] params() default {};
    String[] headers() default {};
    String[] consumes() default {};
    String[] produces() default {};
}

使用场景：可以用在类上或方法上，用于配置 URL 映射。

常用属性：
- name()：用于指定请求映射的名称。
- value()：用于指定请求路径。
- method()：用于指定请求方法（如 GET、POST 等）。
- produces()：用于指定请求内容类型。

5. @GetMapping 注解

@GetMapping 是 @RequestMapping method = RequestMethod.GET 的缩写，用于将 HTTP GET 请求映射到特定的处理方法上。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.core.annotation.AliasFor;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RequestMapping(method = {RequestMethod.GET})
public @interface GetMapping {
    @AliasFor(annotation = RequestMapping.class)
    String name() default "";
    @AliasFor(annotation = RequestMapping.class)
    String[] value() default {};
    @AliasFor(annotation = RequestMapping.class)
    String[] path() default {};
    @AliasFor(annotation = RequestMapping.class)
    String[] params() default {};
    @AliasFor(annotation = RequestMapping.class)
    String[] headers() default {};
    @AliasFor(annotation = RequestMapping.class)
    String[] consumes() default {};
    @AliasFor(annotation = RequestMapping.class)
    String[] produces() default {};
}

使用场景：用于将 HTTP GET 请求映射到特定的处理方法上。

默认方法：和 @RequestMapping 一样，可以手动定义具体的处理逻辑。

6. @RequestBody 注解

@RequestBody 注解用于将 HTTP 请求的正文绑定到一个对象上，常用于处理 POST 请求中的数据插入。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestBody {
    String value() default "";
}

使用场景：可以用在类上或方法上，用于将 HTTP 请求正文绑定到对象上。

默认方法：@RequestBody 默认没有具体的方法，需要手动定义如何处理请求正文。

7. @RequestParam 注解

@RequestParam 是从 HTTP 请求的请求参数中获取值的注解，常用于 GET 请求中的参数获取。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface RequestParam {
    String name() default "";
    String value() default "";
}

使用场景：可以用在类上或方法上，用于从请求参数中获取值。

默认方法：@RequestParam 默认没有具体的方法，需要手动定义如何获取参数值。

8. @PathVariable 注解

@PathVariable 是从 URI 模板中获取值的注解，常用于 RESTful API 中的 URI 模板参数获取。

package org.springframework.web.bind.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface PathVariable {
    String name() default "";
    String value() default "";
}

使用场景：可以用在类上或方法上，用于从 URI 模板中获取值。

默认方法：@PathVariable 默认没有具体的方法，需要手动定义如何获取参数值。

9. @RestController vs @Controller + @ResponseBody

@RestController 是一个组合注解，它等同于 @Controller + @ResponseBody。两者的主要区别在于 @RestController 更简洁，通常用于 RESTful API 的控制器类。

@RestController
public class MyRestController {
    @GetMapping("/api/test")
    public String test() {
        return "hello world";
    }
}

和

@Controller
@ResponseBody
public class MyController {
    @GetMapping("/api/test")
    public String test() {
        return "hello world";
    }
}

在功能上是等价的，建议在项目中统一使用 @RestController，以保持代码简洁。

10. RequestMapping 的一些常用属性

@RequestMapping("/")：将所有请求都映射到根路径。

@RequestMapping(method = RequestMethod.POST, path = "/api/users")：将 POST 请求映射到 /api/users 路径。

@RequestMapping(name = "user", path = "/api", method = RequestMethod.GET)：使用 name 属性给请求映射起名，方便在日志或调试中使用。

11. 综合注解的使用

在实际项目中，可以将多个注解组合使用，例如：

@RestController
@RequestMapping("/api")
public class UserController {
    @GetMapping("/users")
    @RequestBody List
   
     users;
    @GetMapping("/{id}")
    @RequestBody User user(@PathVariable Long id);
    @PostMapping
    @RequestBody User user(@RequestBody User userDetails) {
        // 处理用户数据
    }
}