避坑指南！Spring Boot 3.4 REST API 開發常見的七大錯誤
作者：編程疏影
避免這些錯誤不僅能提升 API 的健壯性，還能讓你的代碼更具可讀性、擴展性和安全性。在實際開發中，建議結合具體業務場景，遵循 RESTful 設計原則，使用 Spring Boot 提供的最佳實踐和工具，提高 API 質量。
Spring Boot 是目前最受歡迎的 Java 框架之一，以其簡單易用、開箱即用的特性深受開發者青睞。在構建 REST API 時，Spring Boot 提供了豐富的功能支持，使得開發變得高效便捷。然而，在實際開發過程中，開發者往往會因經驗不足或疏忽，導致代碼存在一些隱患，從而影響 API 的可維護性、安全性及性能。
本篇文章將深入探討 7 大 Spring Boot REST API 開發中常見的錯誤，并提供最佳實踐和優化方案，幫助開發者規避這些坑，提高 API 質量。無論是初學者還是經驗豐富的開發人員，都可以從本文中找到改進 REST API 設計的關鍵點。
錯誤一：HTTP 方法使用不當
在創建 REST API 時，不正確地使用 HTTP 方法是一個常見錯誤。RESTful 設計原則要求 API 使用 HTTP 方法來表達不同的操作語義，若方法使用不當，會影響 API 的可讀性和一致性。
錯誤的做法
@PostMapping("/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.updateUser(id, user);
}
@GetMapping("/users/create")
public User createUser(@RequestBody User user) {
return userService.createUser(user);
}正確的做法
@PutMapping("/users/{id}")
public User updateUser(@PathVariable Long id, @RequestBody User user) {
return userService.updateUser(id, user);
}
@PostMapping("/users")
public User createUser(@RequestBody User user) {
return userService.createUser(user);
}HTTP 方法使用規范：
- GET 用于獲取數據
- POST 用于創建資源
- PUT 用于更新現有資源
- DELETE 用于刪除資源
- PATCH 用于部分更新資源
錯誤二：異常處理不當
不當或缺乏異常處理會導致很多問題，對組織和客戶造成困擾。錯誤信息不明確會讓問題的調試變得非常困難，還可能帶來潛在的安全漏洞。
錯誤的做法
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
try {
return userService.getUser(id);
} catch (Exception e) {
return null; // 不推薦的做法
}
}正確的做法
@ControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleUserNotFoundException(UserNotFoundException ex) {
ErrorResponse error = new ErrorResponse(
HttpStatus.NOT_FOUND.value(),
ex.getMessage(),
LocalDateTime.now()
);
return new ResponseEntity<>(error, HttpStatus.NOT_FOUND);
}
@ExceptionHandler(ValidationException.class)
public ResponseEntity<ErrorResponse> handleValidationException(ValidationException ex) {
ErrorResponse error = new ErrorResponse(
HttpStatus.BAD_REQUEST.value(),
ex.getMessage(),
LocalDateTime.now()
);
return new ResponseEntity<>(error, HttpStatus.BAD_REQUEST);
}
}
@Getter
@AllArgsConstructor
public class ErrorResponse {
private int status;
private String message;
private LocalDateTime timestamp;
}錯誤三：輸入驗證失敗
沒有驗證輸入會導致數據損壞，并可能引發安全漏洞。
錯誤的做法
@PostMapping("/users")
public User createUser(@RequestBody User user) {
return userService.createUser(user);
}
public class User {
private String email;
private String password;
private String phoneNumber;
}正確的做法
@PostMapping("/users")
public User createUser(@Valid @RequestBody User user) {
return userService.createUser(user);
}
public class User {
@Email(message = "郵箱格式不正確")
@NotNull(message = "郵箱不能為空")
private String email;
@Size(min = 8, message = "密碼必須至少包含8個字符")
@Pattern(regexp = "^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[@#$%^&+=]).*$",
message = "密碼必須包含至少一個數字、一個大寫字母、一個小寫字母和一個特殊字符")
private String password;
@Pattern(regexp = "^\\+?[1-9]\\d{1,14}$", message = "電話號碼格式不正確")
private String phoneNumber;
}錯誤四：命名規范不一致
API 設計時，命名不一致會降低可讀性，增加維護成本。
錯誤的做法
@RestController
public class UserController {
@GetMapping("/getUsers")
public List<User> getUsers() { ... }
@PostMapping("/createNewUser")
public User createNewUser(@RequestBody User user) { ... }
@PutMapping("/updateUserDetails/{userId}")
public User updateUserDetails(@PathVariable Long userId) { ... }
}正確的做法
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
@GetMapping
public List<User> getUsers() { ... }
@PostMapping
public User createUser(@RequestBody User user) { ... }
@PutMapping("/{id}")
public User updateUser(@PathVariable Long id) { ... }
}錯誤五：沒有實現分頁功能
當 API 返回大量數據時，分頁非常重要。不使用分頁可能會導致性能問題并影響用戶體驗。
錯誤的做法
@GetMapping("/users")
public List<User> getAllUsers() {
return userRepository.findAll(); // 可能返回成千上萬條記錄
}正確的做法
@GetMapping("/users")
public Page<User> getUsers(
@RequestParam(defaultValue = "0") int page,
@RequestParam(defaultValue = "20") int size,
@RequestParam(defaultValue = "id") String sortBy
) {
Pageable pageable = PageRequest.of(page, size, Sort.by(sortBy));
return userRepository.findAll(pageable);
}
// Repository
public interface UserRepository extends PagingAndSortingRepository<User, Long> {
Page<User> findByLastName(String lastName, Pageable pageable);
}錯誤六：暴露敏感信息
在代碼中序列化和日志記錄數據時，必須隱藏敏感信息，以防止安全漏洞。
錯誤的做法
@Entity
public class User {
private Long id;
private String username;
private String password; // 在 API 響應中暴露
private String ssn; // 在 API 響應中暴露
// Getter 和 Setter 方法
}正確的做法
@Entity
public class User {
private Long id;
private String username;
@JsonIgnore
private String password;
@JsonIgnore
private String ssn;
// Getter 和 Setter 方法
}
// 使用 DTO 進行響應
@Data
public class UserDTO {
private Long id;
private String username;
private LocalDateTime createdAt;
public static UserDTO fromEntity(User user) {
UserDTO dto = new UserDTO();
dto.setId(user.getId());
dto.setUsername(user.getUsername());
dto.setCreatedAt(user.getCreatedAt());
return dto;
}
}錯誤七：響應狀態碼不正確
使用不正確的響應狀態碼非常常見，這會讓 API 使用者感到困惑。
錯誤的做法
@PostMapping("/users")
public User createUser(@RequestBody User user) {
// 用 200 OK 作為創建成功的返回碼
return userService.createUser(user);
}
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) {
User user = userService.findById(id);
if (user == null) {
return new User(); // 返回空對象而不是 404
}
return user;
}正確的做法
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
User createdUser = userService.createUser(user);
return new ResponseEntity<>(createdUser, HttpStatus.CREATED);
}
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
return userService.findById(id)
.map(user -> ResponseEntity.ok(user))
.orElse(ResponseEntity.notFound().build());
}總結
Spring Boot 3.4 為開發 REST API 提供了豐富的支持，但如果不遵循最佳實踐，很容易出現影響代碼質量和可維護性的錯誤。本文列舉了 7 個常見的錯誤，并提供了優化方案，涵蓋了 HTTP 方法使用、異常處理、輸入驗證、命名規范、分頁、敏感信息保護以及狀態碼管理等方面。
避免這些錯誤不僅能提升 API 的健壯性，還能讓你的代碼更具可讀性、擴展性和安全性。在實際開發中，建議結合具體業務場景，遵循 RESTful 設計原則，使用 Spring Boot 提供的最佳實踐和工具，提高 API 質量。
希望本文能幫助你規避 REST API 開發中的常見陷阱，打造高質量、可維護的 Spring Boot 項目。
責任編輯：武曉燕
來源：
路程編程
