RestController 표준
-
어노테이션: 반드시
@RestController를 사용해야 합니다. -
라우팅: 클래스 수준에서
@RequestMapping("/api/v1/resource")와 메서드 수준에서 HTTP 매핑 어노테이션(@GetMapping,@PostMapping등)을 사용하세요. -
의존성 주입: 서비스를 위해 반드시 생성자 주입을 사용해야 합니다.
-
반환 타입: 메서드는 반드시
ResponseEntity<ApiResponse<T>>를 반환해야 합니다. -
오류 처리: 예외 처리를 중앙 집중식
GlobalExceptionHandler(@RestControllerAdvice)에 위임하세요. 표준 오류 흐름에try-catch블록을 사용하지 마세요.@Valid를 사용하여 입력 유효성 검사를 처리하세요.
예시 코드
@RestController
@RequestMapping("/api/v1/users")
public class UserController {
private final UserService userService;
// 생성자 주입
public UserController(UserService userService) {
this.userService = userService;
}
@GetMapping
public ResponseEntity<ApiResponse<List<UserSummaryDto>>> getAllUsers() {
List<UserSummaryDto> users = userService.getAllUsers();
return ResponseEntity.ok(ApiResponse.success(users, "Users retrieved successfully"));
}
@GetMapping("/{id}")
public ResponseEntity<ApiResponse<UserDto>> getUserById(@PathVariable Long id) {
UserDto user = userService.getUserById(id);
return ResponseEntity.ok(ApiResponse.success(user, "User retrieved successfully"));
}
@PostMapping
public ResponseEntity<ApiResponse<UserDto>> createUser(
@Valid @RequestBody CreateUserRequest request) {
UserDto createdUser = userService.createUser(request);
return ResponseEntity
.status(HttpStatus.CREATED)
.body(ApiResponse.success(createdUser, "User created successfully"));
}
@PutMapping("/{id}")
public ResponseEntity<ApiResponse<UserDto>> updateUser(
@PathVariable Long id,
@Valid @RequestBody UpdateUserRequest request) {
UserDto updatedUser = userService.updateUser(id, request);
return ResponseEntity.ok(ApiResponse.success(updatedUser, "User updated successfully"));
}
@DeleteMapping("/{id}")
public ResponseEntity<ApiResponse<Void>> deleteUser(@PathVariable Long id) {
userService.deleteUser(id);
return ResponseEntity.ok(ApiResponse.success(null, "User deleted successfully"));
}
}
중요 사항:
- 컨트롤러 메서드는 간결하게 유지하고 비즈니스 로직을 직접 포함하지 마세요. 대신 서비스 레이어로 위임하세요.
- HTTP 상태 코드를 적절하게 사용하세요 (200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found 등).
@Valid어노테이션으로 요청 DTO의 유효성을 검사하세요.- API 계약을 나타내기 위해 표준화된 응답 구조(
ApiResponse<T>)를 사용하세요.