반복영역 건너뛰기
주메뉴 바로가기
본문 바로가기
제품/서비스
EMS Solution
Features
클라우드 관리
서버관리
데이터베이스 관리
네트워크 관리
트래픽 관리
설비 IoT 관리
무선 AP 관리
교환기 관리
운영자동화
실시간 관리
백업 관리
스토리지 관리
예방 점검
APM Solution
애플리케이션 관리
URL 관리
브라우저 관리
ITSM Solution
서비스데스크
IT 서비스 관리
Big Data Solution
SIEM
AI 인공지능
Dashboard
대시보드
Consulting Service
컨설팅 서비스
고객
레퍼런스
고객FAQ
문의하기
가격
자료실
카탈로그
사용자매뉴얼
회사소개
비전·미션
연혁
2016~현재
2000~2015
인증서·수상
투자정보
재무정보
전자공고
IR자료
새소식
공고
보도자료
오시는 길
채용
피플
컬처
공고
FAQ
블로그
열기
메인 페이지로 이동
블로그
기술이야기
블로그
최신이야기
사람이야기
회사이야기
기술이야기
다양한이야기
[브레인저가 알려주는 IT#1] 네트워크 관리, SNMP가 뭔가요?
카프카를 통한 로그 관리 방법
김채욱
2023.09.19
페이스북 공유하기
트위터 공유하기
링크드인 공유하기
블로그 공유하기
메모리 누수 위험있는 FinalReference 참조 분석하기
안녕하세요! 저는 개발4그룹에서 제니우스(Zenius) SIEM의 로그 관리 기능 개발을 담당하고 있는 김채욱 입니다. 제가 하고 있는 일은 실시간으로 대용량 로그 데이터를 수집하여 분석 후, 사용자에게 가치 있는 정보를 시각화하여 보여주는 일입니다.
이번 글에서 다룰 내용은
1) 그동안 로그(Log)에 대해 조사한 것과 2) 최근에 CCDAK 카프카 자격증을 딴 기념으로, 카프카(Kafka)를 이용하여 어떻게 로그 관리를 하는지
에 대해 이야기해 보겠습니다.
PART1. 로그
1. 로그의 표면적 형태
로그(Log)는 기본적으로 시스템의 일련된 동작이나 사건의 기록입니다. 시스템의 일기장과도 같죠. 로그를 통해 특정 시간에 시스템에서 ‘어떤 일’이 일어났는지 파악할 수도 있습니다. 이렇게 로그는 시간에 따른 시스템의 동작을 기록하고, 정보는 순차적으로 저장됩니다.
이처럼
로그의 핵심 개념은 ‘시간’
입니다. 순차적으로 발생된 로그를 통해 시스템의 동작을 이해하며, 일종의 생활기록부 역할을 하죠. 시스템 내에서 어떤 행동이 발생하였고, 어떤 문제가 일어났으며, 유저와의 어떤 교류가 일어났는지 모두 알 수 있습니다.
만약 시간의 개념이 없다면 어떻게 될까요? 발생한 모든 일들이 뒤섞이며, 로그 해석을 하는데 어려움이 생기겠죠.
이처럼 로그를 통해 시스템은 과거의 변화를 추적합니다. 똑같은 상황이 주어지면 항상 같은 결과를 내놓는 ‘결정론적’인 동작을 보장할 수 있죠. 로그의 중요성, 이제 조금 이해가 되실까요?
2. 로그와 카프카의 관계
자, 그렇다면! 로그(Log)와 카프카(Kafka)는 어떤 관계일까요? 우선 카프카는 분산 스트리밍 플랫폼으로서, 실시간으로 대용량의 데이터를 처리하고 전송하는데 탁월한 성능을 자랑합니다. 그 중심에는 바로 ‘로그’라는 개념이 있는데요. 좀 더 자세히 짚고 넘어가 보겠습니다.
3. 카프카에서의 로그 시스템
카프카에서의 로그 시스템은, 단순히 시스템의 에러나 이벤트를 기록하는 것만이 아닙니다. 연속된 데이터 레코드들의 스트림을 의미하며, 이를 ‘토픽(Topic)’이라는 카테고리로 구분하죠. 각 토픽은 다시 *파티션(Partition)으로 나누어, 단일 혹은 여러 서버에 분산 저장됩니다. 이렇게 분산 저장되는 로그 데이터는, 높은 내구성과 가용성을 보장합니다.
*파티션(Partition): 하드디스크를 논리적으로 나눈 구역
4. 카프카가 로그를 사용하는 이유
로그의 순차적인 특성은 카프카의 ‘핵심 아키텍처’와 깊게 연결되어 있습니다. 로그를 사용하면,
데이터의 순서를 보장할 수 있어 대용량의 데이터 스트림을 효율적
으로 처리할 수 있기 때문이죠. 데이터를 ‘영구적’으로 저장할 수 있어,
데이터 손실 위험 또한 크게 줄어
듭니다.
로그를 사용하는 또 다른 이유는 ‘장애 복구’
입니다. 서버가 장애로 인해 중단되었다가 다시 시작되면, 저장된 로그를 이용하여 이전 상태로 복구할 수 있게 되죠. 이는 ‘카프카가 높은 가용성’을 보장하는 데 중요한 요소입니다.
∴
로그 요약
로그는 단순한 시스템 메시지를 넘어 ‘데이터 스트림’의 핵심 요소로 활용됩니다. 카프카와 같은 현대의 데이터 처리 시스템은
로그의 이러한 특성을 극대화하여, 대용량의 실시간 데이터 스트림을 효율적으로 처리
할 수 있는 거죠. 로그의 중요성을 다시 한번 깨닫게 되는 순간이네요!
PART2. 카프카
로그에 이어 에 대해 설명하겠습니다. 들어가기에 앞서 가볍게 ‘구조’부터 알아가 볼까요?
1. 카프카 구조
· 브로커(Broker)
브로커는 *클러스터(Cluster) 안에 구성된 여러 서버 중 각 서버를 의미합니다. 이러한 브로커들은, 레코드 형태인 메시지 데이터의 저장과 검색 및 컨슈머에게 전달하고 관리합니다.
*클러스터(Cluster): 여러 대의 컴퓨터들이 연결되어 하나의 시스템처럼 동작하는 컴퓨터들의 집합
데이터 분배와 중복성도 촉진합니다. 브로커에 문제가 발생하면, 데이터가 여러 브로커에 데이터가 복제되어 데이터 손실이 되지 않죠.
·
프로듀서(Producer)
프로듀서는 토픽에 레코드를 전송 또는 생성하는 *엔터티(Entity)입니다. 카프카 생태계에서 ‘데이터의 진입점’ 역할도 함께 하고 있죠. 레코드가 전송될 토픽 및 파티션도 결정할 수 있습니다.
*엔터티(Entity): 업무에 필요한 정보를 저장하고 관리하는 집합적인 것
·
컨슈머(Consumer)
컨슈머는 토픽에서 레코드를 읽습니다. 하나 이상의 토픽을 구독하고, 브로커로부터 레코드를 소비합니다. 데이터의 출구점을 나타내기도 하며, 프로듀서에 의해 전송된 메시지를 최종적으로 읽히고 처리되도록 합니다.
·
토픽(Topic)
토픽은 프로듀서로부터 전송된 레코드 카테고리입니다. 각 토픽은 파티션으로 나뉘며, 이 파티션은 브로커 간에 복제됩니다.
카프카로 들어오는 데이터를 조직화하고, 분류하는 방법을 제공하기도 합니다. 파티션으로 나눔으로써 카프카는 ‘수평 확장성과 장애 허용성’을 보장합니다.
·
주키퍼(ZooKeeper)
주키퍼는 브로커를 관리하고 조정하는 데 도움을 주는 ‘중앙 관리소’입니다. 클러스터 노드의 상태, 토픽 *메타데이터(Metadata) 등의 상태를 추적합니다.
*메타데이터(Metadata): 데이터에 관한 구조화된 데이터로, 다른 데이터를 설명해 주는 데이터
카프카는 분산 조정을 위해 주키퍼에 의존합니다. 주키퍼는 브로커에 문제가 발생하면, 다른 브로커에 알리고 클러스터 전체에 일관된 데이터를 보장하죠.
∴
카프카 구조 요약
요약한다면 카프카는
1) 복잡하지만 견고한 아키텍처 2) 대규모 스트림 데이터를 실시간으로 처리하는 데 있어 안정적이고 장애 허용성이 있음 3) 고도로 확장 가능한 플랫폼을 제공
으로 정리할 수 있습니다.
이처럼 카프카가 큰 데이터 환경에서 ‘어떻게’ 정보 흐름을 관리하고 최적화하는지 5가지의 구조를 통해 살펴보았습니다. 이제 카프카에 대해 조금 더 명확한 그림이 그려지지 않나요?
2. 컨슈머 그룹과 성능을 위한 탐색
카프카의 가장 주목할 만한 특징 중 하나는
‘컨슈머 그룹의 구현’
입니다. 이는 카프카의 확장성과 성능 잠재력을 이해하는 데 중심적인 개념이죠.
컨슈머 그룹 이해하기
카프카의 핵심은
‘메시지를 생산하고 소비’
하는 것입니다. 그런데 수백만, 심지어 수십억의 메시지가 흐르고 있을 때 어떻게 효율적으로 소비될까요?
여기서 컨슈머 그룹(Consumer Group)이 등장합니다. 컨슈머 그룹은, 하나 또는 그 이상의 컨슈머로 구성되어 하나 또는 여러 토픽에서 메시지를 소비하는데 협력합니다. 그렇다면 왜 효율적인지 알아보겠습니다.
·
로드 밸런싱:
하나의 컨슈머가 모든 메시지를 처리하는 대신, 그룹이 부하를 분산할 수 있습니다. 토픽의 각 파티션은 그룹 내에서 정확히 하나의 컨슈머에 의해 소비됩니다. 이는 메시지가 더 빠르고 효율적으로 처리된다는 것을 보장합니다.
·
장애 허용성:
컨슈머에 문제가 발생하면, 그룹 내의 다른 컨슈머가 그 파티션을 인수하여 메시지 처리에 차질이 없도록 합니다.
·
유연성:
데이터 흐름이 변함에 따라 그룹에서 컨슈머를 쉽게 추가하거나 제거합니다. 이에 따라 증가하거나 감소하는 부하를 처리할 수 있습니다.
여기까지는 최적의 성능을 위한 ‘카프카 튜닝 컨슈머 그룹의 기본 사항’을 다루었으니, 이와 관련된 ‘성능 튜닝 전략’에 대해 알아볼까요?
성능 튜닝 전략
·
파티션 전략:
토픽의 파티션 수는, 얼마나 많은 컨슈머가 활성화되어 메시지를 소비할 수 있는지 영향을 줍니다. 더 많은 파티션은 더 많은 컨슈머가 병렬로 작동할 수 있음을 의미하는 거죠. 그러나 너무 많은 파티션은 *오버헤드를 야기할 수 있습니다.
*오버헤드: 어떤 처리를 하기 위해 간접적인 처리 시간
·
컨슈머 구성:
*fetch.min.bytes 및 *fetch.max.wait.ms와 같은 매개변수를 조정합니다. 그다음 한 번에 얼마나 많은 데이터를 컨슈머가 가져오는지 제어합니다. 이러한 최적화를 통해 브로커에게 요청하는 횟수를 줄이고, 처리량을 높입니다.
*fetch.min.bytes: 한 번에 가져올 수 있는 최소 데이터 사이즈 *fetch.max.wait.ms: 데이터가 최소 크기가 될 때까지 기다릴 시간
·
메시지 배치:
프로듀서는 메시지를 함께 배치하여 처리량을 높일 수 있게 구성됩니다. *batch.size 및 *linger.ms와 같은 매개변수를 조정하여, 대기 시간과 처리량 사이의 균형을 찾을 수 있게 되죠.
*batch.size: 한 번에 모델이 학습하는 데이터 샘플의 개수 *linger.ms: 전송 대기 시간
·
압축:
카프카는 메시지 압축을 지원하여 전송 및 저장되는 데이터의 양을 줄입니다. 이로 인해 전송 속도가 빨라지고 전체 성능이 향상될 수 있습니다.
·
로그 정리 정책:
카프카 토픽은, 설정된 기간 또는 크기 동안 메시지를 유지할 수 있습니다. 보존 정책을 조정하면, 브로커가 저장 공간이 부족해지는 점과 성능이 저하되는 점을 방지할 수 있습니다.
3. 컨슈머 그룹과 성능을 위한 실제 코드 예시
다음 그림과 같은 코드를 보며 조금 더 자세히 살펴보겠습니다. NodeJS 코드 중 일부를 발췌했습니다. 카프카 설치 시에 사용되는 설정 파일 *server.properties에서 파티션의 개수를 CPU 코어 수와 같게 설정하는 코드입니다. 이에 대한 장점들을 쭉 살펴볼까요?
*server.properties: 마인크래프트 서버 옵션을 설정할 수 있는 파일
CPU 코어 수에 파티션 수를 맞추었을 때의 장점
·
최적화된 리소스 활용:
카프카에서는 각 파티션이 읽기와 쓰기를 위한 자체 *I/O(입출력) 스레드를 종종 운영합니다. 사용 가능한 CPU 코어 수와 파티션 수를 일치시키면, 각 코어가 특정 파티션의 I/O 작업을 처리합니다. 이 동시성은 리소스에서 최대의 성능을 추출하는 데 도움 됩니다.
·
최대 병렬 처리:
카프카의 설계 철학은 ‘병렬 데이터 처리’를 중심으로 합니다. 코어 수와 파티션 수 사이의 일치는, 동시에 처리되어 처리량을 높일 수 있습니다.
·
간소화된 용량 계획:
이 접근 방식은, 리소스 계획에 대한 명확한 기준을 제공합니다. 성능 병목이 발생하면 CPU에 *바인딩(Binding)되어 있는지 명확하게 알 수 있습니다. 인프라를 정확하게 조정할 수도 있게 되죠.
*바인딩(Binding): 두 프로그래밍 언어를 이어주는 래퍼 라이브러리
·
오버헤드 감소:
병렬 처리와 오버헤드 사이의 균형은 미묘합니다. 파티션 증가는 병렬 처리를 촉진할 수 있습니다. 하지만 더 많은 주키퍼 부하, 브로커 시작 시간 연장, 리더 선거 빈도 증가와 같은 오버헤드도 가져올 수도 있습니다. 파티션을 CPU 코어에 맞추는 것은 균형을 이룰 수 있게 합니다.
다음은 프로세스 수를 CPU 코어 수만큼 생성하여, 토픽의 파티션 개수와 일치시킨 코드에 대한 장점입니다.
파티션 수와 컨슈머 프로세스 수 일치의 장점
·
최적의 병렬 처리:
카프카 파티션의 각각은 동시에 처리될 수 있습니다. 컨슈머 수가 파티션 수와 일치하면, 각 컨슈머는 특정 파티션에서 메시지를 독립적으로 소비할 수 있게 되죠. 따라서 병렬 처리가 향상됩니다.
·
리소스 효율성:
파티션 수와 컨슈머 수가 일치하면, 각 컨슈머가 처리하는 데이터의 양이 균등하게 분배됩니다. 이로 인해 전체 시스템의 리소스 사용이 균형을 이루게 되죠.
·
탄력성과 확장성:
트래픽이 증가하면, 추가적인 컨슈머를 컨슈머 그룹에 추가하여 처리 능력을 증가시킵니다. 동일한 방식으로 트래픽이 감소하면 컨슈머를 줄여 리소스를 절약할 수 있습니다.
·
고가용성과 오류 회복:
컨슈머 중 하나가 실패하면, 해당 컨슈머가 처리하던 파티션은 다른 컨슈머에게 자동 재분배됩니다. 이를 통해 시스템 내의 다른 컨슈머가 실패한 컨슈머의 작업을 빠르게 인수하여, 메시지 처리가 중단되지 않습니다.
마지막으로 각 프로세스별 컨슈머를 생성해서 토픽에 구독 후, 소비하는 과정을 나타낸 소스코드입니다.
∴
컨슈머 그룹 요약
컨슈머 그룹은 높은 처리량과 장애 허용성 있는 메시지 소비를 제공하는 능력이 핵심입니다. 카프카가 어떤 식으로 운영되는지에 대한 상세한 부분을 이해하고 다양한 매개변수를 신중하게 조정한다면, 어떠한 상황에서도 카프카의 최대 성능을 이끌어낼 수 있습니다!
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
©
참고 자료
· Jay Kreps, “I Hearts Logs”, Confluent
· 위키피디아, “Logging(computing)”
· Confluent, “https://docs.confluent.io/kafka/overview.html”
· Neha Narkhede, Gwen Shapira, Todd Palino, “Kafka: The Definitive Guide”
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
#LOG
#로그
#카프카
#컨슈머
#KAFKA
#SIEM
#제니우스
김채욱
개발4그룹
실시간 대용량 로그 데이터의 수집 및 가공에 관심을 가지고 있습니다. 함께 발전해 나가는 개발을 추구합니다.
필진 글 더보기
목록으로
추천 콘텐츠
이전 슬라이드 보기
IT 인프라 모니터링 시스템의 컨트롤러 개선기, ArgumentResolver를 통한 중복 제거
IT 인프라 모니터링 시스템의 컨트롤러 개선기, ArgumentResolver를 통한 중복 제거
대규모 IT 인프라를 모니터링하는 도메인에서는 서버나 네트워크 장비와 같은 관리 대상을 통칭하여 타겟(Target)이라고 부릅니다. 이에 따라 대다수의 API는 리소스 식별을 위해 URL 경로(Path Variable)나 쿼리 스트링(Query Parameter)을 통해 targetId를 필수적으로 전달받는 구조를 가지고 있습니다. 이 targetId는 단순한 문자열 식별자가 아니라, 실제 비즈니스 로직이 수행되기 전 반드시 선행되어야 하는 일련의 검증 절차를 요구합니다. 구체적으로는 클라이언트 입력값에 대한 유효성 검사, 해당 ID를 기반으로 한 DB 조회 및 도메인 객체(TargetInfoRecord)로의 매핑, 그리고 해당 타겟에 대한 사용자 접근 권한(Authorization) 확인 과정이 포함됩니다. 프로젝트 초기 구현 단계에서는 이러한 전처리 로직을 각 컨트롤러 메서드 바디 상단에 직접 구현하는 방식을 취했습니다. 하지만 API 엔드포인트가 수십 개로 늘어남에 따라, 동일한 검증 코드가 여러 컨트롤러에 산재하게 되는 구조적 문제가 발생했습니다. 이는 단순한 코드 중복(Boilerplate Code)을 넘어, 타겟 검증 정책이 변경될 때마다 관련된 모든 API를 수정해야 하는 유지보수의 취약점으로 이어졌습니다. 또한 비즈니스 로직과 검증 로직이 한 곳에 혼재됨에 따라 코드의 가독성이 저하되고, 수정 과정에서 누락이 발생할 경우 장애로 직결될 위험이 높습니다. 반복되는 검증 로직과 분산된 수정 포인트(N개의 지점) 문제를 근본적으로 해결하기 위해, 다음과 같은 명확한 엔지니어링 목표를 수립했습니다. “타겟 검증, 변환을 메서드 파라미터 주입 시점에 끝낸다.” Spring MVC는 이미 @PathVariable, @RequestParam, @AuthenticationPrincipal과 같이 요청 데이터를 가공하여 컨트롤러 메서드 파라미터에 바인딩하는 표준화된 메커니즘을 제공하고 있습니다. 이 아키텍처 패턴에 착안하여, [ URL에서 타겟 ID 추출 → 유효성 검증 → 도메인 객체 변환 ]으로 이어지는 일련의 과정을 비즈니스 로직 진입 전인 '파라미터 주입 단계'에서 완결짓도록 HandlerMethodArgumentResolver를 적용했습니다. 이 아키텍처를 실제 코드로 구현하기 위해, 프로세스를 크게 세 가지 단계로 나누어 진행했습니다. 메타데이터 정의 (Annotation): 어떤 파라미터를 검증할지 식별하고 정책을 부여 로직 구현 (Resolver & Helper): 실제 값을 추출하고 도메인 객체로 변환하는 바인딩 로직 작성 설정 등록 (Configuration): Spring MVC가 해당 리졸버를 인식하도록 설정 가장 먼저, 컨트롤러 파라미터에 검증 요구사항을 명시할 커스텀 어노테이션을 정의합니다. 1. 커스텀 어노테이션 정의 - @ToTargetInfoRecords 구현의 첫 단계로, 파라미터에 메타데이터를 부여할 커스텀 어노테이션을 정의합니다. 타겟에 대한 모든 정보를 TargetInfoRecord라는 도메인 객체로 캡슐화하여 관리하고 있습니다. 따라서 '해당 파라미터를 TargetInfoRecord 객체로 변환하라'는 명시적인 의미를 담아 @ToTargetInfoRecords라는 어노테이션을 설계했습니다. 이 어노테이션은 런타임 시점에 Resolver가 식별할 수 있어야 하므로 RUNTIME 정책을 사용하며, 파라미터 레벨에 적용되도록 타겟을 한정했습니다. - VALUE_PARAMETER로 메서드 파라미터에서만 사용하도록 제한합니다. - RUNTIME 보존으로 요청 처리 시점에 리졸버가 어노테이션 값을 읽습니다. 2. ArgumentResolver 구현 다음으로 Spring MVC의 HandlerMethodArgumentResolver 인터페이스를 구현하여 실질적인 바인딩 로직을 처리하는 ToTargetInfoRecordResolver를 작성합니다. HandlerMethodArgumentResolver를 상속한 ToTargetInfoRecordsResolver를 생성합니다. 3. 리졸버 등록 방법 구현한 리졸버가 실제로 동작하기 위해서는 Spring MVC의 Argument Resolver 체인에 등록해야 합니다. WebMvcConfigurer를 구현하여 우리가 만든 리졸버를 추가해주면, 이후 들어오는 요청에 대해 Spring이 자동으로 개입하게 됩니다. 이 리졸버를 등록한 후에 클라이언트로부터 요청이 들어오면, 컨트롤러 메서드 호출 직전에 파라미터 단위로 다음 순서가 진행됩니다. 1. Spring이 컨트롤러 메서드의 각 파라미터에 대해 등록된 리졸버 리스트를 순서대로 확인합니다. 2. supportsParameter(...)가 true인 첫 번째 리졸버를 선택합니다. 3. 선택된 리졸버의 resolveArgument(...)를 호출하여 값을 만들고, 그 반환값을 해당 파라미터에 주입합니다. 자세한 구현은 다음과 같습니다. 1) 어떤 파라미터를 내가 담당하는가 — supportsParameter 파라미터에 @ToTargetInfoRecords가 붙어 있으면 자신의 책임으로 판단합니다. 2) 값을 어떻게 만들고 주입하는가 — resolveArgument 3) URL에서 값은 어떻게 추출하는가 — 쿼리 vs 경로 - 쿼리스트링은 webRequest.getParameterValues()로, 경로 변수 HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE로 추출합니다. - 메서드 파라미터 타입이 List인지도 구분하고 검증합니다. 이렇게 헬퍼 클래스를 통해 요청 위치나 데이터 타입에 구애받지 않고 무결성이 검증된 데이터가 준비되면, 변환된 객체가 마침내 컨트롤러 메소드의 파라미터에 주입됩니다. 결과적으로 컨트롤러는 HTTP 요청의 복잡한 세부 사항을 전혀 모른 채, 안전하게 가공된 도메인 객체를 즉시 사용할 수 있게 됩니다. 실제 적용 사례 가장 눈에 띄는 변화는 컨트롤러의 간결함입니다. 기존에는 비즈니스 로직과 섞여 있던 '타겟 ID 추출', '유효성 검사', '도메인 변환', '권한 체크' 등의 횡단 관심사(Cross-cutting Concerns)가 완벽하게 분리되었습니다. 덕분에 개발자는 신규 API를 작성할 때 불필요한 반복 코드(Boilerplate)를 작성하는 수고를 덜고, 핵심 비즈니스 로직 구현에만 온전히 집중할 수 있게 되었습니다. 또한, 유지보수 측면에서도 강력한 이점을 가집니다. 만약 타겟 검증 정책이 변경되더라도 수십 개의 컨트롤러를 일일이 수정할 필요 없이, ArgumentResolver의 로직 한 곳만 수정하면 전사적으로 변경 사항이 반영됩니다. 다수의 API에서 [URL로부터 값 추출 → 검증 → 도메인 객체 변환]의 패턴이 반복되는 프로젝트라면, HandlerMethodArgumentResolver를 적극적으로 도입하여 코드의 품질과 생산성을 높여보시는 것을 권장합니다.
2026.02.06
Spring MVC: 반복되는 검증 로직 한 번에 끝내기
Spring MVC: 반복되는 검증 로직 한 번에 끝내기
인프라 관리 도메인에서 API 설계 시 가장 빈번하게 등장하는 파라미터는 단연 targetId입니다. 하지만 이 식별자는 비즈니스 로직이 실행되기 전, 반드시 통과해야 하는 '삼중 관문'을 가지고 있습니다. 유효성 검사, 도메인 객체 변환, 그리고 권한 확인이 그것입니다. 초기 구현 단계에서는 이 관문들을 각 컨트롤러 메서드 내부에서 직접 제어하는 방식을 택했습니다. 하지만 인프라 규모가 커지고 API 엔드포인트가 늘어날수록, 이 직관적인 방식은 코드 중복과 유지보수 효율성 저하라는 아키텍처적 부채로 돌아오기 시작했습니다. API 엔드포인트가 수십 개로 늘어남에 따라, 동일한 검증 코드가 여러 컨트롤러에 산재하게 되는 구조적 문제가 발생했습니다. 이는 단순한 코드 중복(Boilerplate Code)을 넘어, 타겟 검증 정책이 변경될 때마다 관련된 모든 API를 수정해야 하는 유지보수의 취약점으로 이어졌습니다. 또한 비즈니스 로직과 검증 로직이 한 곳에 혼재됨에 따라 코드의 가독성이 저하되고, 수정 과정에서 누락이 발생할 경우 장애로 직결될 위험이 높습니다. 반복되는 검증 로직과 분산된 수정 포인트(N개의 지점) 문제를 근본적으로 해결하기 위해, 다음과 같은 명확한 엔지니어링 목표를 수립했습니다. “타겟 검증, 변환을 메서드 파라미터 주입 시점에 끝낸다” Spring MVC는 이미 @PathVariable, @RequestParam, @AuthenticationPrincipal과 같이 요청 데이터를 가공하여 컨트롤러 메서드 파라미터에 바인딩하는 표준화된 메커니즘을 제공하고 있습니다. 이 아키텍처 패턴에 착안하여, [ URL에서 타겟 ID 추출 → 유효성 검증 → 도메인 객체 변환 ]으로 이어지는 일련의 과정을 비즈니스 로직 진입 전인 '파라미터 주입 단계'에서 완결짓도록 HandlerMethodArgumentResolver를 적용했습니다. 이 아키텍처를 실제 코드로 구현하기 위해, 프로세스를 크게 세 가지 단계로 나누어 진행했습니다. 1. 메타데이터 정의 (Annotation): 어떤 파라미터를 검증할지 식별하고 정책을 부여 2. 로직 구현 (Resolver & Helper): 실제 값을 추출하고 도메인 객체로 변환하는 바인딩 로직 작성 3. 설정 등록 (Configuration): Spring MVC가 해당 리졸버를 인식하도록 설정 가장 먼저, 컨트롤러 파라미터에 검증 요구사항을 명시할 커스텀 어노테이션을 정의합니다. 1. 커스텀 어노테이션 정의 - @ToTargetInfoRecords 구현의 첫 단계로, 파라미터에 메타데이터를 부여할 커스텀 어노테이션을 정의합니다. 타겟에 대한 모든 정보를 TargetInfoRecord라는 도메인 객체로 캡슐화하여 관리하고 있습니다. 따라서 '해당 파라미터를 TargetInfoRecord 객체로 변환하라'는 명시적인 의미를 담아 @ToTargetInfoRecords라는 어노테이션을 설계했습니다. 이 어노테이션은 런타임 시점에 Resolver가 식별할 수 있어야 하므로 RUNTIME 정책을 사용하며, 파라미터 레벨에 적용되도록 타겟을 한정했습니다. - VALUE_PARAMETER로 메서드 파라미터에서만 사용하도록 제한합니다. - RUNTIME 보존으로 요청 처리 시점에 리졸버가 어노테이션 값을 읽습니다. 2. ArgumentResolver 구현 다음으로 Spring MVC의 HandlerMethodArgumentResolver 인터페이스를 구현하여 실질적인 바인딩 로직을 처리하는 ToTargetInfoRecordResolver를 작성합니다. HandlerMethodArgumentResolver를 상속한 ToTargetInfoRecordsResolver를 생성합니다. 3. 리졸버 등록 방법 구현한 리졸버가 실제로 동작하기 위해서는 Spring MVC의 Argument Resolver 체인에 등록해야 합니다. WebMvcConfigurer를 구현하여 우리가 만든 리졸버를 추가해주면, 이후 들어오는 요청에 대해 Spring이 자동으로 개입하게 됩니다. 이 리졸버를 등록한 후에 클라이언트로부터 요청이 들어오면, 컨트롤러 메서드 호출 직전에 파라미터 단위로 다음 순서가 진행됩니다. 1. Spring이 컨트롤러 메서드의 각 파라미터에 대해 등록된 리졸버 리스트를 순서대로 확인합니다. 2. supportsParameter(...)가 true인 첫 번째 리졸버를 선택합니다. 3. 선택된 리졸버의 resolveArgument(...)를 호출하여 값을 만들고, 그 반환값을 해당 파라미터에 주입합니다. 자세한 구현은 다음과 같습니다. 1) 어떤 파라미터를 내가 담당하는가 — supportsParameter 파라미터에 @ToTargetInfoRecords가 붙어 있으면 자신의 책임으로 판단합니다. 2) 값을 어떻게 만들고 주입하는가 — resolveArgument 3) URL에서 값은 어떻게 추출하는가 — 쿼리 vs 경로 - 쿼리스트링은 webRequest.getParameterValues()로, 경로 변수는HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE로 추출합니다. - 메서드 파라미터 타입이 List인지도 구분하고 검증합니다. 이렇게 헬퍼 클래스를 통해 요청 위치나 데이터 타입에 구애받지 않고 무결성이 검증된 데이터가 준비되면, 변환된 객체가 마침내 컨트롤러 메소드의 파라미터에 주입됩니다. 결과적으로 컨트롤러는 HTTP 요청의 복잡한 세부 사항을 전혀 모른 채, 안전하게 가공된 도메인 객체를 즉시 사용할 수 있게 됩니다. 실제 적용 사례 가장 눈에 띄는 변화는 컨트롤러의 간결함입니다. 기존에는 비즈니스 로직과 섞여 있던 '타겟 ID 추출', '유효성 검사', '도메인 변환', '권한 체크' 등의 횡단 관심사(Cross-cutting Concerns)가 완벽하게 분리되었습니다. 덕분에 개발자는 신규 API를 작성할 때 불필요한 반복 코드(Boilerplate)를 작성하는 수고를 덜고, 핵심 비즈니스 로직 구현에만 온전히 집중할 수 있게 되었습니다. 또한, 유지보수 측면에서도 강력한 이점을 가집니다. 만약 타겟 검증 정책이 변경되더라도 수십 개의 컨트롤러를 일일이 수정할 필요 없이, ArgumentResolver의 로직 한 곳만 수정하면 전사적으로 변경 사항이 반영됩니다. 다수의 API에서 [URL로부터 값 추출 → 검증 → 도메인 객체 변환]의 패턴이 반복되는 프로젝트라면, HandlerMethodArgumentResolver를 적극적으로 도입하여 코드의 품질과 생산성을 높여보시는 것을 권장합니다.
2026.03.06
다음 슬라이드 보기