REST API 에서 Enum 직렬화 문제

 

REST API에서 Enum을 사용하다 보면 흔히 겪는 문제가 있다.
프론트에서는 보기 쉬운 값(예: "서류통과")을 보내고 싶은데,
백엔드는 Enum 이름(예: DOCUMENT_PASSED)을 기대해서 에러가 발생하는 상황이다.

 

이번 글에서는 이 문제를 @JsonCreator와 @JsonValue를 활용하여 해결한 방법과 함께,
직렬화/역직렬화 개념도 간단히 정리해보겠다.

 

---

 

문제 상황

public enum CurrentStatus {
    DOCUMENT_PASSED("서류통과"),
    INTERVIEW_WAITING("면접대기"),
    INTERVIEW_PASSED("면접통과"),
    FINAL_FAILED("최종탈락");

    private final String korean;
    CurrentStatus(String korean) {
        this.korean = korean;
    }
}

 

에러 메시지

"status": 500, "message":"Cannot construct instance of `CurrentStatus` from String value '서류통과'"

 

프론트에서는 "서류통과"를 보내지만,

Jackson은 DOCUMENT_PASSED처럼 Enum 이름을 기대하기 때문에 매핑에 실패한 것을 볼 수 있다.

 

---

 

직렬화&역직렬화

 

직렬화 : 자바 객체 → JSON 문자열로 변환

역직렬화 : JSON 문자열 → 자바 객체로 변환

 

즉 응답시에는 객체를 직렬화하고 요청시에는 JSON을 역직렬화한다.

 

 

그렇다면 왜 직렬화와 역직렬화가 중요할까?

→ 프론트엔드와 백엔드가 데이터를 주고받을 때 일관된 포맷이 필요하다.

→  기본 설정만으로는 Enum을 직관적인 문자열로 표현하기 어렵다.

 

---

 

시도했던 방법

1. 프론트엔드에서 Enum 이름(DOCUMENT_PASSED) 그대로 보내기
   • 직관성이 떨어져  사용자 UX가 저하될 우려가 있다.
2. DTO에서 String 타입으로 받고 수동 변환
   • 유지보수가 불편하고 로직 중복이 증가한다.

결국 가장 좋은 방법은 Enum 자체를 직렬화/역직렬화에 맞게 커스터마이징 하는 것이다.

 

 

 

---

 

해결방법

@Getter
public enum CurrentStatus {
    DOCUMENT_PASSED("서류통과"),
    INTERVIEW_WAITING("면접대기"),
    INTERVIEW_PASSED("면접통과"),
    FINAL_FAILED("최종탈락");

    private final String korean;

    CurrentStatus(String korean) {
        this.korean = korean;
    }

    // 직렬화: API 응답에서 Enum → 한글 문자열
    @JsonValue
    public String toKorean() {
        return korean;
    }

    // 역직렬화: API 요청에서 한글 문자열 → Enum
    @JsonCreator
    public static CurrentStatus fromKorean(String value) {
        for (CurrentStatus status : values()) {
            if (status.korean.equals(value)) return status;
        }
        throw new IllegalArgumentException("올바르지 않은 상태입니다: " + value);
    }
}

 

@JsonValue + @JsonCreator를 사용해 직렬화 & 역직렬화 한다.

결과적으로 API 응답/요청에 "서류통과", "면접대기"처럼 직관적 표현이 가능해졌다.

 

주의할점은,

역직렬화 실패 시 @JsonCreator 내부에서 예외 처리가 필요하다.

그리고 Enum 값 변경 시 한글 문자열도 함께 변경되어야 하므로 이중관리가 필요하다.

 

---

 

마무리

Enum은 코드의 안정성과 표현력을 동시에 잡을 수 있는 강력한 도구이다.
하지만 REST API에서 직렬화/역직렬화 시 기본 설정만으로는 사용자 경험(UX)을 저하시킬 수 있다.

이번에 다룬 @JsonValue와 @JsonCreator 조합은

Enum을 그대로 유지하면서도 사용자 친화적인 문자열 표현을 가능하게 만든다.