Spring Boot 接口开发实战指南

一、基础接口开发步骤

1.1 添加必要依赖

<!-- pom.xml -->
<dependencies><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
</dependencies>

1.2 创建第一个REST接口

@RestController
@RequestMapping("/api/v1")
public class HelloController {// 简单GET请求@GetMapping("/hello")public String sayHello() {return "Hello Spring Boot!";}// 带路径参数的GET请求@GetMapping("/users/{id}")public ResponseEntity<User> getUser(@PathVariable Long id) {User user = userService.findById(id);return ResponseEntity.ok(user);}
}

二、核心注解详解

2.1 常用注解对照表

注解	作用	示例场景
`@RestController`	组合注解（@Controller + @ResponseBody）	REST接口类声明
`@RequestMapping`	定义请求映射基础路径	类级别路径定义
`@GetMapping`	处理GET请求	查询操作
`@PostMapping`	处理POST请求	新增操作
`@PutMapping`	处理PUT请求	更新操作
`@DeleteMapping`	处理DELETE请求	删除操作
`@RequestBody`	绑定请求体到方法参数	接收JSON请求体
`@RequestParam`	绑定查询参数到方法参数	分页参数接收

2.2 参数接收方式对比

// 路径参数
@GetMapping("/products/{productId}")
public Product getProduct(@PathVariable String productId) { ... }// 查询参数
@GetMapping("/search")
public List<Product> searchProducts(@RequestParam String keyword,@RequestParam(defaultValue = "0") int page,@RequestParam(defaultValue = "10") int size) { ... }// 请求体参数
@PostMapping("/orders")
public Order createOrder(@Valid @RequestBody OrderDTO orderDTO) { ... }// 文件上传
@PostMapping("/upload")
public String handleFileUpload(@RequestParam("file") MultipartFile file) { ... }

三、接口响应规范

3.1 统一响应格式

public class ApiResponse<T> {private int code;private String message;private T data;private long timestamp = System.currentTimeMillis();// 成功响应工厂方法public static <T> ApiResponse<T> success(T data) {return new ApiResponse<>(200, "Success", data);}// 构造器、Getter/Setter省略
}

3.2 响应状态码处理

@PostMapping("/users")
public ResponseEntity<ApiResponse<User>> createUser(@Valid @RequestBody User user) {User createdUser = userService.create(user);return ResponseEntity.status(HttpStatus.CREATED).body(ApiResponse.success(createdUser));
}

四、接口验证与异常处理

4.1 参数校验示例

public class UserDTO {@NotBlank(message = "用户名不能为空")@Size(min = 3, max = 20, message = "用户名长度3-20个字符")private String username;@Email(message = "邮箱格式不正确")private String email;// Getter/Setter
}@PostMapping("/register")
public ApiResponse<User> register(@Valid @RequestBody UserDTO userDTO) {// 业务处理
}

4.2 全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(MethodArgumentNotValidException.class)public ApiResponse<Map<String, String>> handleValidationExceptions(MethodArgumentNotValidException ex) {Map<String, String> errors = new HashMap<>();ex.getBindingResult().getAllErrors().forEach(error -> {String fieldName = ((FieldError) error).getField();String errorMessage = error.getDefaultMessage();errors.put(fieldName, errorMessage);});return ApiResponse.error(400, "参数校验失败", errors);}@ExceptionHandler(Exception.class)public ApiResponse<String> handleAllExceptions(Exception ex) {return ApiResponse.error(500, "服务器内部错误", ex.getMessage());}
}

五、接口安全增强

5.1 JWT认证集成

@PostMapping("/login")
public ApiResponse<String> login(@RequestBody LoginRequest request) {if (authService.authenticate(request)) {String token = JwtUtil.generateToken(request.getUsername());return ApiResponse.success(token);}return ApiResponse.error(401, "认证失败");
}@GetMapping("/profile")
public ApiResponse<UserProfile> getProfile(@RequestHeader("Authorization") String token) {String username = JwtUtil.validateToken(token);UserProfile profile = userService.getProfile(username);return ApiResponse.success(profile);
}

5.2 接口限流配置

@Configuration
public class RateLimitConfig {@Beanpublic FilterRegistrationBean<RateLimitFilter> rateLimitFilter() {FilterRegistrationBean<RateLimitFilter> registration = new FilterRegistrationBean<>();registration.setFilter(new RateLimitFilter(100)); // 100请求/秒registration.addUrlPatterns("/api/*");return registration;}
}

六、接口文档生成

6.1 Swagger集成配置

@Configuration
@OpenAPIDefinition(info = @Info(title = "电商平台API文档",version = "1.0",description = "电商平台接口文档"
))
public class SwaggerConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().components(new Components()).info(new Info().title("电商平台API文档"));}
}

6.2 接口注解示例

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

七、接口测试方法

7.1 Postman测试示例

POST http://localhost:8080/api/v1/login
Content-Type: application/json{"username": "testuser","password": "Test123!"
}

7.2 单元测试示例

@SpringBootTest
@AutoConfigureMockMvc
class UserControllerTest {@Autowiredprivate MockMvc mockMvc;@Testvoid testGetUser() throws Exception {mockMvc.perform(get("/api/v1/users/1").header("Authorization", "Bearer valid_token")).andExpect(status().isOk()).andExpect(jsonPath("$.data.username").value("testuser"));}
}