Command API

Command API 명명

컨트롤러에 대해 다음 규칙으로 명명하기로 하였습니다.

	-Controller 접미사	-Api 접미사
설명	페이지 요청을 받는 컨트롤러에 대한 명명 규칙	API 요청을 받는 컨트롤러에 대한 명명 규칙
예시	BoardController	BoardCommandApi

프론트엔드 프로젝트가 구분되어 관리되기 때문에 페이지 요청은 이번 프로젝트 예시에 포함되지 않습니다.

API 컨트롤러 메서드 공통 규칙

• ResponseEntity<...>를 거의 사용하지 않습니다.
  • 정상 응답 상태 코드가 한 종류로 설계된 API라면, 응답 상태 코드는 @ResponseStatus(HttpStatus.상태_코드_이름)을 사용합니다.
  • 오류 응답 시, 상태 코드 및 내용은 GlobalExceptionHandler에서 처리합니다. (TODO: 이곳에 GlobalExceptionHandler 페이지 링크를 추가)
  • 다양한 응답 구조를 원한다면 @JsonInclude(Include.NON_NULL) 등을 사용하여 필요한 필드만 골라서 반환합니다.
    (ResponseEntity<?> 등을 대신합니다.)

Command API: Create

• 정상 응답 상태 코드: 201 CREATED
• 예외 응답: GlobalExceptionHandler에서 처리합니다. (TODO: 이곳에 GlobalExceptionHandler 페이지 링크를 추가)

@PostMapping
@ResponseStatus(HttpStatus.CREATED) // 201 CREATED
public BoardCreateResponse create(
        @RequestBody @Valid BoardCreateRequest dto
) {
    /* skipped */
}

Command API: Update & Delete

Update 요청 및 응답

• 권장 HTTP Method: PUT (대부분의 수정을 PUT으로 하고, 간혹 특수한 일부 필드를 지정할 때 PATCH 사용)
• 정상 응답
  • 반환 데이터가 있을 때: 200 OK
  • 반환 데이터가 없을 때: 204 NO_CONTENT (void)
• 예외 응답: GlobalExceptionHandler에서 처리합니다. (TODO: 이곳에 GlobalExceptionHandler 페이지 링크를 추가)

유효성 애노테이션의 정상적인 동작을 위해 컨트롤러에 @Validated 애노테이션이 필요합니다.

// simplified example

@PutMapping("{id}")
public BoardUpdateResponse update(
        @PathVariable("id")
        /* 필요하다면 유효성 애노테이션 추가 (나중을 위해 권장하지 않습니다.) */
        String id,

        @RequestBody
        @Valid
        BoardUpdateRequest dto
) {
    /* skipped */
}

Delete 요청 및 응답

• HTTP Method: DELETE (* 소프트딜리트더라도 사용자는 DELETE 메서드로 요청합니다. 소프트/하드 딜리트를 사용자가 아니라 서버가 선택합니다.)
• 정상 응답
  • 반환 데이터가 있을 때: 200 OK
  • 반환 데이터가 없을 때: 204 NO_CONTENT (void)
• 예외 응답: GlobalExceptionHandler에서 처리합니다. (TODO: 이곳에 GlobalExceptionHandler 페이지 링크를 추가)

// simplified example

@DeleteMapping("{id}")
@ResponseStatus(HttpStatus.NO_CONTENT)
public void delete(
        @PathVariable("id")
        Long id
) {
    /* skipped */
}