Spring Boot에서 쿼리 파라미터의 Enum 값을 어떻게 읽나요?

Source: Dev.to

소개

Imagine you’re filtering products on an e-commerce site. You select ORDER=ASC or ORDER=DESC from a dropdown. Behind the scenes, your backend needs to understand those values exactly as defined, not as random strings.

이것이 enums가 빛을 발하는 곳입니다. Enums는 API에 구조, 안전성, 명확성을 제공합니다. 임의의 문자열을 받아들이는 대신 허용된 값만 받아들입니다. 많은 초보자들이 궁금해합니다:

Spring Boot에서 쿼리 파라미터의 enum 값을 어떻게 읽나요?

In this article you’ll learn how to read enum values from query parameters in Spring Boot, with clean architecture and working Java 21 examples.

이 글에서는 Spring Boot에서 쿼리 파라미터의 enum 값을 읽는 방법을, 클린 아키텍처와 실제 동작하는 Java 21 예제와 함께 배웁니다.

핵심 개념

Enum이란?

Enum은 고정된 상수 집합입니다.

public enum OrderType {
    ASC,
    DESC
}

비유: Enum은 레스토랑의 메뉴 옵션과 같으며, 메뉴에 없는 것을 주문할 수 없습니다.

쿼리 파라미터에서 Enum을 사용하는 이유

문자열 대신 Enum을 사용하면 다음과 같은 장점이 있습니다:

• ✅ 컴파일 시점 안전성
• ✅ 자동 검증
• ✅ 깔끔한 코드
• ✅ 향상된 API 문서
• ✅ 오타로 인한 버그 감소

Spring Boot가 Enum을 자동으로 처리하는 방법

Spring Boot는 다음을 수행할 수 있습니다:

• 쿼리 파라미터 문자열 → Enum 값 변환
• 잘못된 값은 400 BAD_REQUEST 로 거부
• @RequestParam과 함께 바로 사용 가능

대부분의 경우 별도의 컨버터가 필요하지 않습니다.

코드 예제 (엔드‑투‑엔드)

✅ 예제 1: 쿼리 파라미터에서 Enum 읽기 (기본 및 깔끔)

사용 사례: 주문 유형에 따라 사용자를 정렬합니다.

단계 1: Enum 정의

package com.example.demo.enums;

public enum SortOrder {
    ASC,
    DESC
}

단계 2: REST 컨트롤러

package com.example.demo.controller;

import com.example.demo.enums.SortOrder;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {

    /**
     * 예시 URL:
     *   /users?order=ASC
     *   /users?order=DESC
     */
    @GetMapping
    public String getUsers(@RequestParam SortOrder order) {
        return "Fetching users in " + order + " order";
    }
}

API 동작

Spring은 유효한 값은 자동으로 변환하고, 잘못된 값은 거부합니다.

✅ 예제 2: 기본값이 있는 선택적 Enum (프로덕션 준비)

사용 사례: 선택적 정렬을 사용하여 제품을 검색합니다.

단계 1: Enum

package com.example.demo.enums;

public enum SortType {
    PRICE,
    RATING,
    NAME
}

단계 2: 선택적 Enum이 있는 REST 컨트롤러

package com.example.demo.controller;

import com.example.demo.enums.SortType;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/products")
public class ProductController {

    /**
     * 예시 URL:
     *   /products
     *   /products?sort=PRICE
     *   /products?sort=RATING
     */
    @GetMapping
    public String getProducts(
            @RequestParam(required = false, defaultValue = "NAME") SortType sort) {
        return "Fetching products sorted by " + sort;
    }
}

동작 설명

안전한 기본값, 깔끔한 API, 클라이언트 친화적.

🧠 보너스: 대소문자 구분 없는 Enum 처리 (선택 사항)

기본적으로 Enum은 대소문자 구분입니다:

• ❌ asc → 오류
• ✅ ASC → 정상 작동

대소문자 구분 없는 지원이 필요하면 커스텀 Converter를 추가하세요. Enum은 엄격하게 동작하도록 설계되었으므로 필요할 때만 사용하십시오.

Best Practices

• 항상 고정값에는 enum을 사용하세요 – 원시 문자열을 피하세요.
• 선택적 enum에 기본값을 제공하세요 – 불필요한 클라이언트 오류를 방지합니다.
• enum 이름을 API‑친화적으로 유지하세요 (예: ASC 대신 ASCENDING_ORDER_TYPE).
• 내부 enum을 무작정 노출하지 마세요 – 공개 API의 일부가 됩니다.
• 허용되는 enum 값을 문서화하세요 – API 사용 및 테스트가 쉬워집니다.

피해야 할 일반적인 실수

• 알려진 옵션에 대해 String 대신 enum을 사용합니다.
• enum 값을 너무 많이 정의하여 API가 부풀어 오릅니다.
• API 버전 관리 없이 enum 값을 변경합니다.
• 컨트롤러 내부에서 enum 변환 오류를 잡아냅니다 (Spring이 처리하도록 합니다).
• enum을 발전시킬 때 이전 호환성을 무시합니다.

결론

쿼리 매개변수에서 enum 값을 읽는 것은 Spring Boot에서 가장 깔끔하고 안전한 패턴 중 하나입니다. Spring Boot의 내장 변환을 활용하면:

• 코드를 적게 작성할 수 있습니다
• 검증을 자동으로 받을 수 있습니다
• API를 더 표현력 있고 견고하게 만들 수 있습니다

이 기술을 마스터하면 Java 프로그래밍 실력이 향상되고 Java를 올바르게 배우는 데 도움이 됩니다—실제 현장에 적용 가능한 프로덕션 수준의 관행을 사용하여.

행동 요청

💬 열거형(enum), 검증, 혹은 API 설계에 대해 궁금한 점이 있나요?
👇 아래 댓글에 남겨 주세요!

다음 주제 제안

• 사용자 정의 오류 메시지를 활용한 열거형 검증
• @Validated를 이용한 열거형 매핑
• 열거형을 활용한 API 버전 관리

그냥 물어보세요—도와드릴게요 🚀

유용한 자료

• Spring @RequestParam 문서
• Oracle Java Enum 문서 (Java 21)
• Spring Boot REST API 가이드