Spring Boot接口开发全注解手册

前言

在Spring Boot开发中，注解驱动的方式极大简化了RESTful接口的开发流程。本文将深入剖析10个核心注解的用法，结合代码示例与实战经验，助您快速掌握接口开发精髓。

---

一、基础接口开发三剑客

1. 控制器声明

@RestController // = @Controller + @ResponseBody
@RequestMapping("/api/v1/users") // 路径前缀统一管理
public class UserController {
    
    @Autowired
    private UserService userService;
}

2. 方法注解全家桶

注解	等效写法
@GetMapping	@RequestMapping(method=GET)
@PostMapping	@RequestMapping(method=POST)
@PutMapping	-
@DeleteMapping	-

请求映射示例

@GetMapping("/{userId}")  // 替代@RequestMapping(method=GET)
public UserVO getUser(@PathVariable Long userId) {
    return userService.getUserById(userId);
}

@PostMapping
@ResponseStatus(HttpStatus.CREATED) // 指定201状态码
public Long createUser(@RequestBody UserDTO dto) {
    return userService.createUser(dto);
}

3. 参数接收全方案

注解名称	接收位置	示例场景
@PathVariable	URL路径	/users/{id}
@RequestParam	查询参数	/users?name=Jack
@RequestBody	请求体	JSON/XML格式数据
@RequestHeader	请求头	获取Authorization头
@CookieValue	Cookie	读取登录凭证

---

二、高级参数处理技巧

1. 参数校验黄金组合

@PostMapping("/register")
public Result<String> register(
    @Validated @RequestBody RegisterDTO dto, // 触发校验
    BindingResult result) { // 接收校验结果
    
    if(result.hasErrors()){
        return Result.fail(result.getFieldError().getDefaultMessage());
    }
    // 业务逻辑...
}

// DTO校验规则示例
public class RegisterDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 5, max = 20)
    private String username;
    
    @Pattern(regexp = "^(?=.*[A-Z])(?=.*\\d).{8,}$", 
             message = "密码必须包含大写字母和数字")
    private String password;
}

2. 自定义参数解析器

@GetMapping("/search")
public PageResult<UserVO> search(
    @PageQueryParam PageQuery pageQuery) { // 自定义分页参数
    return userService.searchUsers(pageQuery);
}

// 自定义参数解析器
public class PageQueryArgumentResolver 
    implements HandlerMethodArgumentResolver {
    
    @Override
    public boolean supportsParameter(MethodParameter param) {
        return param.getParameterType().equals(PageQuery.class);
    }

    @Override
    public Object resolveArgument(...) {
        HttpServletRequest request = webRequest.getNativeRequest(HttpServletRequest.class);
        return PageQuery.from(request);
    }
}

三、响应处理最佳实践

1. 统一响应模板

// 统一响应体
public class Result<T> {
    private int code;
    private String message;
    private T data;
    
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data);
    }
}

// 使用示例
@GetMapping("/{id}")
public Result<UserVO> getUser(@PathVariable Long id) {
    return Result.success(userService.getUser(id));
}

2. 异常处理全局方案

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Result<Void> handleBusinessEx(BusinessException ex) {
        return Result.fail(ex.getErrorCode(), ex.getMessage());
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public Result<Map<String, String>> handleValidEx(MethodArgumentNotValidException ex) {
        Map<String, String> errors = ex.getBindingResult().getFieldErrors()
            .stream().collect(Collectors.toMap(
                FieldError::getField,
                FieldError::getDefaultMessage
            ));
        return Result.fail(400, "参数校验失败", errors);
    }
}

---

四、接口文档自动化

1. OpenAPI集成配置

@Configuration
@OpenAPIDefinition(info = @Info(title = "用户服务API文档"))
public class OpenApiConfig {
    
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
            .components(new Components()
                .addSecuritySchemes("JWT", 
                    new SecurityScheme().type(SecurityScheme.Type.HTTP)
                        .scheme("bearer").bearerFormat("JWT")))
            .addSecurityItem(new SecurityRequirement().addList("JWT"));
    }
}

2. 接口描述增强

@Operation(summary = "获取用户详情", description = "根据用户ID查询完整信息")
@ApiResponses({
    @ApiResponse(responseCode = "200", description = "成功返回用户对象"),
    @ApiResponse(responseCode = "404", description = "用户不存在")
})
@GetMapping("/{id}")
public UserVO getUser(
    @Parameter(description = "用户ID", example = "1001") 
    @PathVariable Long id) {
    //...
}

---

五、性能优化关键注解

1. 缓存加速

@Cacheable(value = "userCache", key = "#userId", 
           unless = "#result == null")
@GetMapping("/{userId}")
public UserVO getUser(@PathVariable Long userId) {
    return userService.getUser(userId);
}

2. 异步处理

@Async("taskExecutor")
@PostMapping("/batch-import")
public CompletableFuture<ImportResult> batchImport(
    @RequestParam MultipartFile file) {
    return CompletableFuture.completedFuture(
        importService.process(file)
    );
}

六、高级应用场景

1. @ExceptionHandler

‌异常统一处理‌：

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ErrorResponse handleNotFound(ResourceNotFoundException ex) {
        return new ErrorResponse(ex.getMessage());
    }
}

2. @CrossOrigin

跨域解决方案‌：

@CrossOrigin(origins = "https://example.com", maxAge = 3600)
@RestController
public class ApiController {
    // 允许特定域名的跨域请求
}

---

六、最佳实践与常见陷阱

1. URL设计规范‌
   • 使用RESTful风格：/api/版本/资源名
   • 动词用HTTP方法表示（GET/POST/PUT/DELETE）
   • 参数处理原则‌
2. 路径参数用@PathVariable
   • 可选参数用@RequestParam(required=false)
   • 复杂对象用@RequestBody
   • ‌响应统一管理‌
3. 全局异常处理@RestControllerAdvice
   • 统一包装Result对象
   • 正确使用HTTP状态码
   • ‌文档自动化‌
4. Swagger注解增强可读性
   • 接口版本管理
   • 在线测试支持

---

总结

掌握这些核心注解后，您已经能够应对90%的接口开发场景。建议结合Swagger UI（@ApiOperation）进行接口测试，并通过Postman验证接口行为。持续关注Spring Boot的版本更新，及时了解新注解的加入（如Spring Boot 3.x的@HttpExchange）。