[Spring] 실무에서의 Best Practices #1

디렉토리 구조와 @Controller를 잘 개발하는 방법

---

디렉토리 구조

Spring 애플리케이셩늘 개발할 때, 클래스명은 도메인 기반 명칭과 3계층 아키텍처 명칭을 조합하여 작성된다. 예를 들어, PaymentService는 도메인인 Payment와 역할인 Service를 조합한 클래스명이다. 이와 같이 각 클래스는 일반적으로 도메인과 계층 구조에따라 명명된다.

• 도메인 기반 명칭 + 3계층 아키텍처 기반 명칭
  • PaymentService = Payment(도메인) + Service(3계층 아키텍처 중 서비스 계층)
  • UserRepository = User + Repositorry
  • JobpostController = Jobpost + Controller

클래스를 배치할 디렉토리 구조에 대해서는 두 가지 방식이 있다.

 

1. 도메인 기반 디렉토리 → 3계층 아키첵처 기반 디렉토리

클래스를 도메인별로 나누고, 그 안에서 3계층 아키텍처(Controller, Service, Repository)로 구분하는 방식이다.

 

2. 3계층 아키텍처 기반 디렉토리 → 도메인 기반 디렉토리

3계층 아키텍처 기준으로 디렉토리를 나눈 후, 각 계층에서 도메인별로 클래스를 배치하는 방식이다.

• 도메인 기반 디렉토리는 도메인 간의 응집도가 높고 클래스가 간단한 학생 프로젝트나 작은 규모의 프로젝트에서 자주 사용된다.
• 3계층 아키텍처 기반 디렉토리는 수많은 도메인을 다루는 대규모 시스템에서 유지보수와 계층간 역할을 명확히 하기 위해 현업에서 많이 사용된다.

3-Layered Architecture 기반 디렉토리

• /exception/
• /advisor/
• /controller/ ← 예시 디렉토리 구조
  •  /user/
  •  /payment/
  •   /cart/
  •    /jobpost/
  •    /delivery/
• /service/
• /repository/
• /configuration/

Domain 기반 디렉토리

• /user/
• /payment/ ← 예시 디렉토리 구조
  • /controller/
  • /service/
  • /repository/
• /cart/
• /jobpost/
• /delivery

---

@Controller를 잘 개발하는 방법

@Controller에서 클라이언트로부터 파라미터를 받는 방법 4가지

ℹ️ https://1000sang-dev.tistory.com/60 해당 포스팅을 참고하자 !

 

1. @PathVariable: URI 경로에서 가변 인자를 받는 방식. 예: `/api/users/{id}`

2. @RequestParam: 쿼리 파라미터로 단일 값을 받는 방식. 예: `?key=value`

3. @ModelAttribute: 쿼리 파라미터에서 여러 값을 DTO 객체로 받을 때 사용.예: `?key1=value&key2=value2`

4. @RequestBody: JSON 또는 XML로 요청 바디에 담긴 데이터를 DTO 객체로 받는 방식. 예: `{ "property : "value" }`

---

@RestCotroller = @Controller + @ResponseBody

ℹ️ https://1000sang-dev.tistory.com/57 해당 포스팅을 참고하자 ! 

• @RestController는 @Controller에 @ResponseBody를 결합한 것으로, 메서드마다 @ResponseBody를 붙이지 않고도 JSON 응답을 처리할 수 있다.

---

표준  HTTP Status Code를 활용하여 결과 반환을 위한 Wrapper Class

• Spring에서 단순한 API를 개발할 때, 정상 응답은 200OK를 반호나하고, 오류 발생 시 500 Internal Server Error 같은 기본 에러 페이지가 반환된다.
• 그러나 실무에서는 상황별로 다양한 상태코드를 세밀하게 설계하여 API의 성공/실패를 관리하는것이 중요하다.
  • 예를 들어, 외부 API와의 통신 시 발생하는 에러나 프론트엔드에서 요청한 데이터를 잘못 처리한 경우를 상태코드로 명확하게 구분해야한다.

HTTP Response 상태코드 종류

• HTTP 상태코드 : 200 OK, 404 Not Found, 500 Internal Server Error 등
  • HTTP Response Status
    • 10X : 정보성 응답 ← Informational Response
    • 20X : 성공 (응답 완료) ← Successful Response
    • 30X : 리다이렉션 ← Redirection
    • 40X : 권한 혹은 잘못된 접근 (유저의 잘못) ← Client Error
    • 50X : 서버 내부 문제 ← Server Error

  ---

  • 200 OK : 요청 성공
  • 201 Created : 새로운 자원이 성공적으로 생성
  • 400 Bad Request : 잘못된 요청
  • 401 Unauthorized : 인증 실패
  • 404 Not Found : 요청한 자원을 찾을 수 없음
  • 500 Internal Server Error : 서버 내부 오류
• 커스텀 상태코드 : A01 타입 에러, A02 입력 에러, B01 외부 서버 통신 에러 등
  • 기획자보다는 기술 리드나 개발자들이 모인 기술팀에서 결정하는 에러 코드

• ResponseEntity<T>: POST 생성 완료 시 HTTP 상태코드(201, CREATED) 포함 결과 반환

@PostMapping("")
@ResponseBody
public ResponseEntity<UserResponseDto> save(@RequestBody @Valid UserCreateRequestDto request) {
    UserResponseDto user = userService.save(request.getName(), request.getAge(), request.getJob(), request.getSpecialty());
    return ResponseEntity
//          .status(HttpStatusCode.valueOf(201))  // 1. HttpStatusCode.valueOf(201) 사용 가능하지만 아래와 동일한 결과
            .status(HttpStatus.CREATED)          // 1. HTTP 201 상태 코드 반환: 새로운 자원(User)이 성공적으로 생성됨을 나타냄
            .body(user);                         // 2. 결과 객체(User) 반환
}

HttpStatus.CREATED: HTTP 상태 코드 201은 새로운 리소스가 성공적으로 생성되었음을 나타낸다. 여기서 user라는 새로운 유저가 생성되었기 때문에, 201 Created 상태 코드가 반환된다.

 

• ResponseEntity<T>: GET 조회 완료 시 HTTP 상태코드(200, OK) 포함 결과(JSON) 반환

@GetMapping("/data") 
@ResponseBody 
public ResponseEntity<UserResponseDto> detailData(@RequestParam Integer id) {
    UserResponseDto user = userService.findById(id); 
    return ResponseEntity
            .status(HttpStatus.OK)      // 1. HTTP 200 상태 코드 반환
            .body(user);                // 2. 조회된 UserResponseDto 객체 반환
}

HttpStatus.OK: HTTP 상태 코드 200은 요청이 성공적으로 처리되었음을 의미한다. 여기서 유저 데이터를 정상적으로 조회한 후에, 200OK 상태코드가 반환된다.

 

• ResponseEntity<T>: 내부 RuntimeException 발생 시 HTTP 상태코드(404, Not Found)

@GetMapping("/data")
@ResponseBody
public ResponseEntity<UserResponseDto> detailData(@RequestParam Integer id) {
    try {
        UserResponseDto user = userService.findById(id); 
        return ResponseEntity
                .status(HttpStatus.OK)      // 1. 성공 시, HTTP 200 상태 코드 반환
                .body(user);                // 2. 조회된 유저 객체(UserResponseDto) 반환
    } catch (RuntimeException e) {
        return ResponseEntity
                .status(HttpStatus.NOT_FOUND) // 3. 유저를 찾지 못한 경우, HTTP 404 상태 코드 반환
                .body(null);                  // 4. 에러 상황에서는 body에 null 반환
    }
}

조회에 실패하거나 해당 유저가 존재하지 않으면 HTTP 404(NOT FOUND) 상태 코드와 함께 null을 응답에 담아 반환한다.

 

• Optional: Optional.ofNullable(user).orElseThrow(...) = Null에 대한 예외 처리

ℹ️ https://1000sang-dev.tistory.com/52 해당 포스팅을 참고하자  !

public User findById(Integer id) {
    Optional<User> retrieved = Optional.ofNullable(users.get(id)); 
    // users.get(id)로 유저를 검색하고, 결과가 null일 수 있으므로 Optional로 감싸준다.
    // Optional.ofNullable()은 null일 수 있는 객체를 안전하게 처리할 수 있도록 해준다.

    return retrieved.orElseThrow(() -> new RuntimeException("유저가 존재하지 않습니다. id : " + id)); 
    // Optional에 값이 존재하면 해당 값을 반환하고, 값이 없으면 예외를 던진다.
    // orElseThrow()는 값이 없을 때 RuntimeException을 발생시켜 유저가 없다는 오류 메시지를 전달다.
}

 

---

JSON 반환 시 세부 설정: Jackson 직렬화 / 역직렬화

@JsonInclude: JSON 노출 여부에 대한 조건

ℹ️ https://1000sang-dev.tistory.com/60 해당 포스팅을 참고하자 !

• @JsonInclude: JSON에서 특정 필드를 노출할 조건을 설정. 예를 들어, NULL 값인 필드를 제외하고 노출 가능.

@JsonProperty: 프론트엔드 개발자가 계속 Key를 바꿔달라고 하는 경우

@JsonProperty("userId")
private Integer id;
// JSON 응답 시 "id" 필드를 "userId"로 변경하여 반환한다.
// 즉, 클라이언트에게 "id" 대신 "userId"라는 이름으로 이 필드를 노출시킨다.

@JsonProperty("username")
private String name;
// JSON 응답 시 "name" 필드를 "username"으로 변경하여 반환한다.
// 클라이언트는 "name" 대신 "username"이라는 이름으로 이 필드를 받는다.

 

• @JsonProperty는 필드가 JSON으로 직렬화될 때, JSON에서 사용할 키 값을 지정하는 데 사용된다.
• 위 예시는 id는 userId로, name은 username으로 JSON에 반환될 떄 노출된다.
• 즉, 클래스의 필드명과 JSON에서 사용되는 이름이 다를 때 @JsonProperty를 통해 원하는 이름을 지정할 수 있다.

@JsonNaming: 스네이크 케이스 등 반환할 때 JSON 내 Key 네이밍 컨벤션을 한번에 변경할 수 있다.

@Data
@JsonNaming(value = PropertyNamingStrategy.SnakeCaseStrategy.class)
public class Student {
    private String myName;
    private String myAge;
    private String myCountry;
}

---

@JsonPropertyOrder: JSON 반환 시 보기 편하게 프로퍼티 순서 정렬

@JsonPropertyOrder({"userId", "username"})
// JSON 직렬화 시, 응답으로 반환되는 JSON 객체의 필드 순서를 지정한다.
// 이 예시에서는 "userId"와 "username" 필드가 가장 먼저 출력되도록 설정한다.

• @JsonPropertyOrder는 JSON 직렬화 시 필드가 출력되는 순서를 정의하는 데 사용된다.
• 지정된 필드 순서대로 JSON 객체 내에 필드가 노출된다.
• 위 코드에서는 "userId" 필드가 먼저, 그 다음에 "username" 필드가 JSON 응답에 나타나도록 설정된다.

"userId"가 먼저 노출된다.

---

@JsonIgnore: JSON 반환 시 미노출 프로퍼티

@JsonIgnore
private Integer age;

• @JsonIgnore는 해당 필드를 JSON 응답에서 제외하는 데 사용된다.
• 이 경우 age 필드는 직렬화 되지 않으며, JSON 응답에서 나타나지 않는다.
• 즉, UserResponseDto 객체가 JSON으로 변환될 때, age 값은 숨겨지고, 클라이언트로 전달되지 않는다.

"age":10 결과가 JSON 내 보이지 않는다.

---

@JsonFormat: JSOn 내 날짜 표기 시 포맷 지정

• DataTimeFormat: Spring에서 지원하는 데이터 포맷 어노테이션이기에 JSON 외에 XML 에도 적용된다.
• @JsonFormat: 일반적으로 JSON을 사용하기에 본 Jackson 어노테이션을 사용하면 된다.

private LocalDateTime createdAt;

• LocalDataeTime 타입은 Java 8에서 도입된 날짜 및 시간 관련 클래스 중 하나로, 날짜와 시간을 모두 포함한 데이터를 다룬다.
• createAt 필드는 엔티티가 생성된 시간을 나타내며, 이를 통해 데이터가 언제 생성되었는지를 기록할 수 있다.
• LocalDateTime 타입은 기본적으로 년, 월, 일, 시, 분, 초 정보를 포함한다.
• JSON 직렬화 시 이 필드도 자동으로 날짜와 시간 형식으로 변환되어 클라이언트에 전달된다.

@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss")
private LocalDateTime createdAt;

• @JsonFormat 어노테이션은 Jackson 라이브러리를 통해 날짜와 시간 형식을 지정할 때 사용된다.
• shape = JsonFormat.Shape.STRING는 LocalDateTime 필드를 문자열 형태로 직렬화하도록 설정한다. 기본적으로 LocalDateTime은 복잡한 객체 형태로 직렬화되지만, 이 옵션을 사용하면 String 형태로 날짜를 표현한다
• pattern = "yyyy-MM-dd HH:mm:ss"는 날짜와 시간의 포맷을 설정한다. 이 예제에서는 다음과 같은 형식으로 데이터를 변환한다:
  • "년-월-일-시:분:초" 형식으로 변환된다.
  • 예시: "2024-10-07 00:29:30"

---

@JacksonAnnotationsInside + @interface: 커스텀 JSON 변환 어노테이션

• @JacksonAnnotationsInside: Jackson 관련 어노테이션을 상속하여 사용하겠다는 의미.
  • 이것을 붙이지 않는다면 인터페이스 자체에 어노테이션이 적용되어 원치 않는 결과가 발생한다.

@JacksonAnnotationsInside  // 이 어노테이션은 해당 어노테이션이 Jackson 관련 어노테이션을 상속하여 사용할 수 있도록 함.
// 즉, 이 어노테이션을 사용하면 내부적으로 @JsonFormat과 같은 Jackson 어노테이션이 적용된 것과 동일한 효과를 제공.
@Retention(RetentionPolicy.RUNTIME)  // 이 어노테이션은 커스텀 어노테이션이 런타임 동안 유지되도록 설정, 런타임에서 리플렉션 가능.
@JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "yyyy-MM-dd HH:mm:ss", timezone = "Asia/Seoul")  
// 이 부분은 @JsonFormat을 포함하는 것으로, 날짜/시간 형식을 지정함.
public @interface DateFormat {  // @interface는 커스텀 어노테이션을 생성할 때 사용됨.
// DateFormat이라는 어노테이션을 새로 만들고, 이 안에 JsonFormat을 포함시켜 커스텀 어노테이션으로 만듦.
}

---

Enum 직렬화 / 역직렬화: @JsonFormat, @JsonValue, @JsonCreator

1. Enum 직렬화 시

1. @JsonFormat(OBJECT)
   • Enum의 모든 필드를 출력할 때 사용된다. 즉, 특정 필드만이 아니라 Enum 객체 전체를 JSON으로 직렬화한다.
   • 예시: { "id":1, "name": "CHEONSANG" } 처럼 전체 Enum 객체를 표현한다
2. @JsonValue 필드
   • 특정 필드 값만 JSON으로 직렬화할 때 사용된다.
   • 예시: { "name": "CHEONSANG" } 처럼 원하는 필드만 선택해서 출력할 수 있다.
3. @JsonValue 메서드
   • 특정 메서드의 결과값을 JSON으로 직렬화할 떄 사용된다. Enum 클래스에 정의된 메서드의 반환 값을 JSON으로 출력할 수 있다.
   • 예시: Enum 내에서 특정 로직을 적용한 후 그 값을 출력.
4. @JsonProperty
   • JSON으로 반환되는 Enum 필드의 이름을 지정할 때 사용된다. 필드명을 원하는 대로 커스텀해서 출력 가능하다.
   • 예시: "user_id": 1과 같이 필드명을 커스텀할 수 있다.
5. 기본 Key 값
   • 아무 설정도 하지 않으면, Enum은 그 기본 이름(Key 값) 으로 직렬화된다.
   • 예시: CHEONSANG과 같은 Enum 자체의 값이 출력된다.

2. Enum 역직렬화 시

1. @JsonCreator
   • 클라이언트로부터 받은 요청을 역직렬화할 때 사용된다. Enum을 지정할 때 필드 이름과 값이 일치해야만 매핑이 가능하다.
   • 예시: 요청으로 들어온 "name": "CHEONSANG"과 같은 값이 Enum의 필드명과 일치해야 정상적으로 매핑된다.
2. @JsonCreator(DELEGATING)
   • 더 간단하게 특정 필드 값으로 Enum을 매핑할 수 있다. 이 방식은 필드명이 아니라 특정 값에 집중하여 요청을 처리하기 때문에 더 유연하다.
   • 예시: "CHEONSANG"이라는 값만으로도 Enum을 매핑할 수 있다.(필드명과 상관없이 처리)

---

ℹ️ 참고

[ASAC 6기 강의자료]