当前位置：首页 > news >正文

SpringBoot RESTful API设计指南

news 2025/7/26 16:58:10

配套工具：Swagger UI + Postman Collection

一、统一响应体设计（基础规范）

1. 标准响应结构

public class Result<T> {private long code;    // 业务状态码private String message; // 提示信息private T data;       // 响应数据private long timestamp = System.currentTimeMillis();// 成功响应public static <T> Result<T> success(T data) {return new Result<>(200, "success", data);}// 错误响应public static <T> Result<T> fail(long code, String message) {return new Result<>(code, message, null);}
}

2. 全局封装处理

@RestControllerAdvice
public class GlobalResponseHandler implements ResponseBodyAdvice<Object> {@Overridepublic boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {// 排除已包装的响应和特殊类型return !returnType.getParameterType().equals(Result.class) && !returnType.hasMethodAnnotation(IgnoreWrapper.class);}@Overridepublic Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType,Class<? extends HttpMessageConverter<?>> selectedConverterType, ServerHttpRequest request, ServerHttpResponse response) {return Result.success(body);}
}

二、智能参数校验（防御性编程）

1. 声明式校验

@PostMapping("/users")
public Result<User> createUser(@Valid @RequestBody UserCreateDTO dto) { // 自动触发校验// 业务逻辑...
}

// DTO定义

@Data
public class UserCreateDTO {@NotBlank(message = "用户名不能为空")@Size(min = 4, max = 20, message = "用户名长度4-20字符")private String username;@Email(message = "邮箱格式不正确")private String email;@Pattern(regexp = "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d]{8,}$", message = "密码必须包含字母和数字，且长度至少8位")private String password;
}

2. 全局异常处理

@ExceptionHandler(MethodArgumentNotValidException.class)
public Result<?> handleValidException(MethodArgumentNotValidException e) {// 提取校验错误信息List<String> errors = e.getBindingResult().getFieldErrors().stream().map(FieldError::getDefaultMessage).collect(Collectors.toList());return Result.fail(400, String.join("; ", errors));
}

三、API版本控制（演进策略）

1. 三种版本控制方案对比
在这里插入图片描述

2. 推荐实现（URL路径版）

@RestController
@RequestMapping("/v1/users")
public class UserControllerV1 {// 版本1的实现
}@RestController
@RequestMapping("/v2/users")
public class UserControllerV2 {// 版本2的实现
}

四、文档自动化（Swagger3集成）

1. 基础配置

@Configuration
@OpenAPIDefinition(info = @Info(title = "电商平台API文档",version = "1.0",description = "基于SpringBoot3的RESTful API")
)
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().components(new Components()).addSecurityItem(new SecurityRequirement().addList("JWT"));}
}

2. 接口注释示例

@Operation(summary = "获取用户详情")
@ApiResponses({@ApiResponse(responseCode = "200", description = "成功返回"),@ApiResponse(responseCode = "404", description = "用户不存在")
})
@GetMapping("/{id}")
public Result<User> getUser(@Parameter(description = "用户ID") @PathVariable Long id) {// ...
}

五、安全防护（纵深防御）

1. 基础安全措施

# application.yml
security:basic:enabled: false # 禁用Basic Authcsrf:enabled: false # REST API通常禁用CSRF

2. JWT认证集成

@Configuration
@EnableWebSecurity
public class SecurityConfig {@Beanpublic SecurityFilterChain filterChain(HttpSecurity http) throws Exception {http.authorizeRequests().antMatchers("/auth/**").permitAll().anyRequest().authenticated().and().addFilterBefore(jwtFilter(), UsernamePasswordAuthenticationFilter.class).sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS);return http.build();}private JwtAuthFilter jwtFilter() {return new JwtAuthFilter();}
}

六、高阶设计模式

1. HATEOAS实现

@GetMapping("/{id}")
public EntityModel<User> getUser(@PathVariable Long id) {User user = userService.findById(id);return EntityModel.of(user,linkTo(methodOn(UserController.class).getUser(id)).withSelfRel(),linkTo(methodOn(UserController.class).getUserOrders(id)).withRel("orders"));
}

2. 异步API设计

@GetMapping("/async")
public DeferredResult<Result<List<User>>> getUsersAsync() {DeferredResult<Result<List<User>>> result = new DeferredResult<>();CompletableFuture.runAsync(() -> {try {result.setResult(userService.findAll());} catch (Exception e) {result.setErrorResult(e);}});return result;
}