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"));}
}
最佳實踐總結
- 版本控制：接口路徑包含版本號（如
/api/v1） - 統一響應：使用標準化的響應格式
- 參數校驗：結合Validation API進行嚴格校驗
- 文檔維護：集成Swagger等文檔工具
- 安全防護：添加JWT認證和接口限流
- 異常處理：全局異常捕獲與友好提示
- 測試覆蓋：編寫單元測試和集成測試
擴展學習：
- Spring官方REST文檔
- RESTful API設計規范
