sy_develop_note

REST vs gRPC, MSA에서 어떻게 고를까?

누구세연 — Sun, 28 Dec 2025 19:34:37 +0900

실무에서 MSA 환경을 운영하다 보니,

일관성 있는 데이터 동기화와 안정적인 운영을 위해 서비스 간 통신 방식을 정확히 정리하고 선택해야겠다는 생각이 들었습니다.

이 글에서는 REST와 gRPC를 비교해 언제 어떤 걸 쓰면 좋을지, 기준을 잡아보려 합니다.

REST vs gRPC 한눈에 비교

REST와 gRPC는 모두 서비스 간 통신을 위한 기술이지만, 출발점이 다르고, 잘 맞는 사용 시나리오도 다릅니다.

REST는 HTTP를 기반으로 한 리소스 중심의 통신 방식이고,

gRPC는 원격 메서드를 호출하는 RPC(Remote Procedure Call) 모델에 가깝습니다.

이 차이가 설계 방식, 성능, 운영 경험 전반에 영향을 줍니다.

항목	REST	gRPC
통신 모델	리소스 중심 (URL + HTTP Method)	메서드 호출 중심 (RPC)
전송 프로토콜	HTTP/1.1 (주로)	HTTP/2
데이터 포맷	JSON (사람 친화적)	Protobuf (바이너리, 경량)
요청/응답	요청 1 ↔ 응답 1	Unary + Streaming
스트리밍	기본 미지원 (SSE/WebSocket 필요)	서버/클라이언트/양방향 기본 지원
스키마 관리	느슨함 (OpenAPI 등 별도 문서)	.proto로 강한 계약
코드 생성	수동 구현	클라이언트/서버 Stub 자동 생성
브라우저 접근	매우 쉬움	직접 호출 어려움 (프록시 필요)
디버깅	curl, 브라우저로 즉시 가능	grpcurl 등 전용 도구 필요
주 사용처	외부 API, BFF, CRUD	내부 서비스 통신, 고성능 RPC

한 줄로 정리하면

REST는 사람이 읽기 쉽고, 브라우저와 잘 맞으며, 외부에 공개하기 좋은 범용 API에 적합합니다.
gRPC는 서비스 간 계약이 명확하고, 호출이 많거나 지연에 민감한 내부 통신에 적합합니다.

그래서 MSA 환경에서는 “외부는 REST, 내부는 gRPC” 같은 혼합 패턴이 자주 사용됩니다.

REST와 gRPC의 근본적인 차이: RPC 관점에서 보기

REST는 리소스를 중심으로 한 통신 방식입니다.
URL과 HTTP 메서드로 “무엇을 한다”를 표현하고, 응답은 상태 코드와 JSON으로 돌려받습니다.
사람이 읽기 쉽고, 브라우저와 궁합이 좋다는 점이 가장 큰 장점입니다.

반면 gRPC는 “원격 메서드를 호출한다”는 RPC 모델에 가깝습니다.
URL보다 메서드 시그니처가 중요하고, 요청과 응답은 .proto로 정의된 메시지를 그대로 주고받습니다.
그래서 gRPC를 쓰다 보면 API를 만든다기보다 인터페이스를 정의한다는 느낌에 더 가깝습니다.

아래 그림은 gRPC가 내부적으로 어떻게 RPC 호출을 처리하는지 보여줍니다.

클라이언트는 메서드를 호출하지만, 실제로는 Stub과 Runtime이 직렬화와 네트워크 전송을 담당합니다.

API 설계 방식의 차이

REST와 gRPC의 가장 큰 차이는 API를 바라보는 관점에서 드러납니다.
REST가 리소스를 중심으로 설계된다면, gRPC는 서비스가 제공하는 동작(행위) 을 중심으로 설계됩니다.

REST: 리소스를 기준으로 설계하기

REST에서는 URL이 곧 리소스를 의미합니다.
HTTP 메서드를 조합해 “이 리소스에 대해 무엇을 할 것인지”를 표현합니다.

GET    /users/{userId}
POST   /users
DELETE /users/{userId}

이 구조에서는

URL = 리소스의 위치
HTTP 메서드 = 행위
라는 역할 분담이 명확합니다.

그래서 CRUD 위주의 API나 외부 공개 API에서는 REST 방식이 직관적이고 문서화도 쉽습니다.
브라우저나 curl로 바로 호출해 볼 수 있다는 점 역시 큰 장점입니다.

gRPC: 동작(메서드)을 기준으로 설계하기

gRPC에서는 URL보다 메서드 시그니처가 중심이 됩니다.
어떤 리소스를 다루는 지보다, “이 서비스가 어떤 기능을 제공하는가”가 먼저 정의됩니다.

service VacationService {
  rpc GetUserVacations(GetUserVacationsRequest)
      returns (GetUserVacationsResponse);

  rpc CreateVacation(CreateVacationRequest)
      returns (CreateVacationResponse);
}

여기서 중요한 점은:

API가 아니라 인터페이스를 정의한다는 느낌
요청/응답 구조가 .proto로 강하게 고정된다는 점입니다.

REST처럼 “이 URL이 무슨 의미지?”를 고민하기보다, 메서드 이름과 시그니처만 봐도 서비스의 책임이 드러납니다.

설계할 때 고민 포인트

REST와 gRPC를 각각 설계해보니, 자연스럽게 고민의 출발점이 달라졌습니다.

REST를 설계할 때는
→ “이 리소스를 어떻게 쪼갤까?”
→ “URL을 어떻게 표현하면 REST스럽지?”
gRPC를 설계할 때는
→ “이 서비스가 외부에 제공해야 할 기능은 무엇일까?”
→ “이 메서드의 입력과 출력은 어디까지가 책임일까?”

그래서 gRPC에서는 API 설계보다는 서비스 인터페이스 설계에 더 가까운 사고가 필요했습니다.

같은 기능을 REST와 gRPC로 표현하면

같은 “사용자의 휴가 목록 조회” 기능이라도 표현 방식은 확연히 달라집니다.

REST

GET /users/{userId}/vacations

gRPC

rpc GetUserVacations(GetUserVacationsRequest)
    returns (GetUserVacationsResponse);

REST는 리소스 구조가 먼저 보이고,
gRPC는 행위와 계약이 먼저 보입니다.

이 차이 때문에, 외부 공개 API나 BFF에서는 REST가 자연스럽고 내부 서비스 간 통신에서는 gRPC가 더 명확하게 느껴졌습니다.

설계 관점에서의 정리

REST는
→ 리소스 모델링이 중요하고
→ HTTP 스펙과 잘 어울리는 설계가 핵심입니다.
gRPC는
→ 서비스의 책임과 기능 경계를 명확히 정의하는 것이 중요하고
→ 강한 스키마 계약을 기반으로 한 통신에 적합합니다.

그래서 MSA 환경에서는 “어떤 기능을 어디에 노출할 것인가”를 먼저 정한 뒤,
그 성격에 맞춰 REST와 gRPC를 선택하는 편이 가장 안정적인 것이라고 생각합니다.

성능과 스트리밍에서의 차이

REST와 gRPC의 성능 차이는 어디서 나올까?

REST와 gRPC의 성능 차이는 단순히 구현체의 문제가 아니라, 기반이 되는 프로토콜과 데이터 전송 방식의 차이에서 비롯됩니다.

REST는 주로 HTTP/1.1과 JSON을 사용합니다.
요청과 응답이 텍스트 기반이고, 호출이 늘어날수록 헤더 크기와 JSON 파싱 비용이 반복적으로 발생합니다.

반면 gRPC는 HTTP/2를 기반으로 동작하며, Protobuf라는 바이너리 포맷을 사용해 전송 데이터가 작고 처리 비용이 낮습니다.

HTTP/1.1

Client ---[Req1: HTML]---> Server
Client <---[Resp1: HTML]-- Server
Client ---[Req2: CSS]---> Server
Client <---[Resp2: CSS]-- Server
Client ---[Req3: JS]----> Server
Client <---[Resp3: JS]--- Server

HTTP/2

Client ---[Stream 1: Req HTML]---> Server ---[Stream 2: Req CSS]---> [Stream 3: Req JS]--->
         <---[Stream 3: Resp JS]--- <---[Stream 2: Resp CSS]--- <---[Stream 1: Resp HTML]---

호출이 많아질수록 체감되는 차이

단건 요청에서는 REST와 gRPC의 차이가 크게 느껴지지 않을 수 있습니다.
하지만 MSA 환경처럼 서비스 간 호출이 빈번해질수록
작은 지연과 오버헤드가 쌓여 전체 응답 시간에 영향을 주게 됩니다.

이런 상황에서는

요청·응답 크기가 작고
연결 재사용과 헤더 압축이 기본으로 제공되는

gRPC 쪽이 더 안정적으로 느껴졌습니다.

스트리밍 방식의 차이

스트리밍 지원 여부는 REST와 gRPC를 가르는 또 하나의 중요한 기준이었습니다.

REST는 기본적으로 요청 → 응답 구조이기 때문에, 연속적인 데이터 전송이 필요할 경우 SSE나 WebSocket 같은 별도의 방식을 추가로 고려해야 합니다.

반면 gRPC는 서버 스트리밍, 클라이언트 스트리밍, 그리고 양방향 스트리밍을 통신 모델 자체로 제공합니다.

운영 / 디버깅 / 현실적인 제약

REST와 gRPC의 차이는 성능보다, 운영하면서 겪는 경험에서 더 분명해졌습니다.

REST는 문제가 생겼을 때 상황을 재현하기가 쉽습니다.
curl이나 브라우저로 바로 호출해 볼 수 있고, JSON 기반 응답이라 로그만 봐도 흐름을 빠르게 파악할 수 있었습니다.

반면 gRPC는 바이너리 통신이라 전용 도구(grpcurl 등)가 없으면 디버깅이 쉽지 않았습니다.
초기에는 운영 난이도가 더 높게 느껴졌습니다.

에러 처리 방식도 달랐습니다.

REST는 HTTP 상태 코드와 메시지를 비교적 자유롭게 표현할 수 있었지만, gRPC는 Status Code 체계를 잘 정하지 않으면 모든 에러가 비슷하게 보이기 쉬웠습니다.
대신 인터셉터를 통해 로깅이나 트레이싱을 공통으로 적용하기는 수월했습니다.

또 하나는 인프라 제약입니다.
gRPC는 HTTP/2 지원이 필요하고, 브라우저에서 직접 호출하기 어렵기 때문에 외부 공개 API보다는 내부 서비스 간 통신에 더 잘 맞았습니다.

이런 점들 때문에, REST와 gRPC는 우열보다는 역할이 다른 기술로 느껴졌습니다.

MSA에서의 혼합 운용 패턴

REST와 gRPC를 모두 써보니, MSA 환경에서는 둘 중 하나를 고르기보다 역할에 따라 나눠 쓰는 방식이 가장 자연스럽게 느껴졌습니다.

가장 흔했던 패턴은 외부는 REST, 내부는 gRPC였습니다.
브라우저나 모바일, 외부 파트너가 직접 호출하는 구간에서는 접근성과 디버깅이 쉬운 REST가 훨씬 편했습니다.
반대로 내부 서비스 간 호출에서는 지연과 호출 빈도가 중요해지면서 gRPC의 장점이 분명해졌습니다.

이 구조에서는 보통 API Gateway나 프록시가 경계 역할을 합니다.
외부 요청은 REST로 받고, 내부로 들어갈 때 gRPC로 변환해 전달하는 방식입니다.
덕분에 클라이언트는 기존 REST API를 그대로 사용하면서도, 내부 통신은 성능과 계약 측면에서 더 안정적으로 가져갈 수 있었습니다.

또 다른 패턴은 BFF + 내부 gRPC 구조였습니다.
BFF는 REST나 GraphQL로 클라이언트 요구에 맞게 응답을 구성하고, 실제 데이터 조회나 처리는 내부 gRPC 서비스에 위임합니다.
이렇게 나누니 클라이언트 변화와 내부 서비스 변경을 서로 독립적으로 가져갈 수 있었습니다.

실제로는 기존 REST API를 한 번에 바꾸기보다, 병목이 되는 구간부터 gRPC로 점진 전환하는 경우가 많았습니다.
외부 계약을 깨지 않으면서 내부 성능만 개선할 수 있어 리스크도 상대적으로 적었습니다.

이런 경험을 거치면서, REST와 gRPC는 경쟁 관계라기보다 MSA 안에서 서로 다른 역할을 맡는 도구에 가깝다는 생각이 들었습니다.
경계에 가까울수록 REST가, 내부로 깊어질수록 gRPC가 자연스럽게 자리 잡았습니다.

정리 및 선택 기준

REST와 gRPC를 비교해 보면, 결국 둘 중 하나가 더 좋다기보다는 어떤 위치에서, 어떤 역할을 맡기느냐의 문제에 가까웠습니다.

브라우저나 모바일, 외부 파트너처럼 사람과 맞닿아 있는 지점에서는 읽기 쉽고 디버깅이 쉬운 REST가 훨씬 편했습니다.
URL과 HTTP 메서드만으로도 의도가 드러나고, 문제가 생겼을 때 빠르게 확인할 수 있다는 점이 컸습니다.

반대로 서비스 안쪽으로 들어갈수록 호출 빈도, 지연, 계약 관리 같은 요소들이 중요해졌고, 이 지점에서는 gRPC의 장점이 분명하게 느껴졌습니다.

강한 스키마와 코드 생성, 스트리밍 지원 덕분에 내부 통신을 더 안정적으로 가져갈 수 있었습니다.

그래서 REST와 gRPC를 고를 때는 기술 자체보다 먼저 이런 질문을 던지게 됐습니다.

이 API를 누가 호출하는가
호출이 얼마나 자주, 얼마나 민감한가
이 경계가 외부 계약에 가까운가, 내부 구현에 가까운가

이 질문에 대한 답이 정해지면, REST와 gRPC 중 무엇을 써야 할지도 자연스럽게 따라왔습니다.
MSA 환경에서는 하나를 고집하기보다, 각각이 잘 어울리는 자리에 두는 것이 결국 가장 안전하고 현실적인 선택이었습니다

어떤 메시지 큐를 선택할까? (Kafka · RabbitMQ · Redis)

누구세연 — Wed, 17 Dec 2025 22:00:12 +0900

최근에 비동기 처리를 추가할 일이 생겼는데, 막상 시작하려니 “그래서 나는 어떤 큐를 써야 하지?”라는 고민이 제일 먼저 들었습니다.

Kafka도 흔히 큐처럼 사용되고, RabbitMQ는 이름부터 Message Queue이고, Redis로도 큐를 만들어 쓸 수 있다 보니 더 헷갈리더라고요.
정리해 보니 결국 중요한 건 이름이 아니라, 내가 원하는 동작이었습니다.
메시지를 다시 처리해야 하는지, 작업을 어떻게 나눌 건지, 유실을 어디까지 허용할 수 있는지, 운영 복잡도는 감당 가능한지 같은 부분이 중요했습니다.
그래서 이 글에서는 먼저 선택해 보고(선택표) → 기준을 세운 뒤(질문) → 각 큐를 이해하는(설명) 순서로 정리해보려 합니다.

먼저 선택표부터

상황/요구	추천
이벤트 로그, CDC, 재처리·재생 가능해야 함	Kafka
작업 큐, 라우팅/재시도/DLQ가 필요함	RabbitMQ (혹은 SQS/ActiveMQ)
초경량 비동기, 매우 낮은 지연, 이미 Redis 보유	Redis Queue/Streams
기록용 + 즉시 처리 병행	Kafka로 기록, Redis로 즉시 작업

여기서 끝내도 되고, “왜?”가 궁금하면 아래 “4가지 질문”으로 한 번 더 체크해 보면 좋습니다.

선택을 결정짓는 4가지 질문

표가 애매하게 느껴지는 경우에는 이 질문 4개만 답해보면 방향이 잡힙니다.

메시지를 다시 읽어야 하나? (과거 재생, 리플레이)
여러 Consumer가 각각 처리해야 하나? 아니면 하나만 처리하면 되나?
장애 시 유실을 허용할 수 있는가?
운영 복잡도(클러스터, 모니터링, 튜닝)를 감당할 수 있는가?

용어만 정리..!

• Producer: 메시지를 생성해 큐/토픽으로 보내는 주체.
• Consumer: 메시지를 받아 실제 작업을 수행하는 주체.
• Queue/Topic: 메시지가 소비되기 전까지 머무는 논리적 단위.
  Kafka는 Topic이라는 로그 구조를 사용하고, RabbitMQ와 Redis는 Queue나 Stream/List 같은 구조로 메시지를 분배한다.
• Offset/Ack: 메시지 처리 진행 상황을 표시하는 방식.
  Kafka는 Offset으로 읽은 위치를 기록하고, RabbitMQ/Redis Streams는 Ack를 통해 처리 완료를 확정한다.

큐별로 뭐가 다를까?

이제부터는 Kafka/RabbitMQ/Redis가 각각 어떤 상황에 강한지, “쓰임새 기준”으로 정리해 보겠습니다.

Kafka (이벤트 스트리밍)

한마디로: 이벤트를 길게 쌓아두고, 필요하면 과거까지 되감아 보는 로그 창고.
디스크 기반 로그, Offset으로 재처리·재생 가능.
매우 높은 처리량, 다수 Consumer가 각자 읽어감.
운영 난이도 높음(클러스터/모니터링/스키마 관리 필요).
주 용도: 도메인 이벤트, CDC, 로그 파이프라인.

Kafka 아키텍처 개요

Producer가 메시지를 Topic/Partition에 push(실제로는 브로커에 append)합니다.
다수의 Broker가 Topic을 Partition 단위로 분산 저장해 확장성과 내결함성을 확보합니다.
Consumer가 pull 방식으로 읽으며, Consumer Group을 사용해 스케일아웃합니다.

Topic/Partition/Consumer Group 동작

하나의 Topic은 여러 Partition으로 나뉘어 병렬 처리·저장이 가능합니다.
Producer는 특정 Partition에 레코드를 보냅니다(키 기반 파티셔닝 등).
Consumer Group은 Partition을 나눠 맡아 읽고, 그룹 내에서 메시지가 중복 처리되지 않도록 조정합니다.

Offset으로 재생·재처리

각 Partition은 순차적인 Offset을 갖습니다. Consumer Group은 자신이 어디까지 읽었는지 Offset으로 기록합니다.
Offset을 되돌리면 과거 메시지를 다시 읽어 재처리·재생이 가능합니다.
로그가 디스크에 일정 기간 보관되므로, 재처리/분석/장애 복구 시 유용합니다.

RabbitMQ (메시지 브로커)

한마디로: 작업 분배기. 들어온 일을 큐에 넣고 여러 작업자가 나눠 처리.
메시지를 큐에 넣고 한 Consumer가 처리(워크 큐 모델).
Exchange/Binding으로 라우팅 유연, Ack/Retry/DLQ 기본 제공.
처리량·운영 복잡도 중간, 작업 큐에 최적.
주 용도: 주문 처리, 백그라운드 잡, 워크플로 분기.

RabbitMQ 라우팅 개요

Publisher가 메시지를 Exchange에 발행하면, Binding 규칙에 따라 하나 혹은 여러 Queue로 복사·분기됩니다(Direct/Topic/Fanout/Headers).
각 Queue는 소비자에게 분배되며, 소비자는 Ack로 처리 완료를 알립니다. Ack가 없으면 재전송되거나 DLQ로 보낼 수 있습니다.
“한 메시지 = 한 작업” 모델에 강해 주문·티켓 처리 같은 워크 큐, 라우팅이 많은 워크플로에 적합합니다.

Redis Queue/Streams (인메모리 큐)

한마디로: 가벼운 전달자. 메모리에 잠깐 올려두고 바로 소비.
In-memory라 매우 빠름, 설정·운영이 단순.
기본 List/PubSub/Streams로 큐 구현. Streams는 Consumer Group/Offset 지원.
내구성·장기 보관은 약함, 재처리·Retry 로직은 직접 설계 필요.
주 용도: 알림 트리거, 캐시 갱신, 단기·경량 백그라운드 작업.

Redis Streams: Consumer Group 처리

Producer가 XADD로 스트림에 메시지를 append합니다(시간순 로그).
Consumer Group이 XREADGROUP으로 메시지를 가져가고, 처리 후 XACK으로 완료를 알립니다.
각 메시지는 그룹 내에서 한 번만 할당되며, Ack 되지 않은 메시지는 Pending List에 남아 재전달이 가능합니다.
여러 Consumer 인스턴스가 병렬로 처리하되, 같은 메시지가 중복 소비되지 않게 조정되는 점이 핵심입니다.

Redis Pub/Sub: 실시간 브로드캐스트

Publisher가 채널에 메시지를 Publish 하면, 구독 중인 Subscriber가 곧바로 수신합니다.
메시지가 Redis에 남지 않으므로 Subscriber가 없거나 잠시 끊겨 있으면 유실됩니다.
“실시간 알림”처럼 즉시 전달이 중요하고 유실이 치명적이지 않은 경우에 적합합니다.

Redis List Queue: 단순 FIFO

LPUSH로 넣고 RPOP 또는 BLPOP으로 빼는 단순 FIFO 큐입니다.
별도 Ack 개념이 없어 소비자가 실패하면 재처리를 직접 구현해야 합니다.
간단한 백그라운드 작업이나 일시적 큐잉에 적합하지만, 안정적 재처리나 DLQ가 필요하면 Streams나 별도 로직이 필요합니다.

큐별 동작 원리 요약

위 내용을 “동작 방식” 기준으로 한 번에 요약하면 이렇게 정리됩니다.

Kafka: Producer가 Topic/Partition에 로그를 append(디스크). Consumer Group이 Offset을 기준으로 읽고 commit 합니다. 메시지는 보관 기간 동안 남아 여러 Consumer가 각자 읽을 수 있고, 과거 재생도 가능합니다.
RabbitMQ: Producer → Exchange → Binding 규칙으로 Queue에 라우팅. Consumer가 메시지를 받아 Ack 하며, Ack가 없으면 재전송(DLQ로 이동 가능)됩니다. 1개 큐의 메시지를 여러 Consumer가 “나눠 처리”하는 워크 큐에 강점이 있습니다.
Redis Queue/Streams: List는 LPUSH/RPOP의 단순 FIFO(ack 없음). Pub/Sub은 저장 없이 즉시 전달(수신자가 없으면 유실). Streams는 append-only 로그 + Consumer Group/Offset으로 기본 ack/재전송을 지원해 Redis 내에서 가장 브로커스러운 모델입니다.

패턴별 추천

로그/이벤트 파이프라인: Kafka (재생·다중 소비 필요).
업무/배치 작업 큐: RabbitMQ/SQS (Ack/Retry/DLQ, 라우팅 필요).
알림/캐시/짧은 잡: Redis Queue/Streams (지연 최소, 단순 운영).
기록 + 즉시 처리 분리: Kafka로 기록, Redis로 알림·캐시 등 즉시 처리.

메시지 큐를 고를 때 성능 지표부터 보기보다는, 이 메시지가 다시 처리되어야 하는지, 여러 소비자가 각각 처리해야 하는지, 유실을 어디까지 허용할 수 있는지를 먼저 정하는 게 더 중요하다고 느꼈습니다.
그 기준으로 보면 Kafka, RabbitMQ, Redis는 경쟁 관계라기보다 각자 잘 맞는 자리가 분명한 도구들입니다.
저는 이 기준을 세운 뒤로 “어떤 큐를 써야 하지?”라는 고민이 많이 줄었습니다.

애매한 HTTP Method, PATCH 메서드

누구세연 — Fri, 12 Dec 2025 16:24:16 +0900

REST API를 설계하다 보면 잠깐 멈칫하게 되는 메서드가 있는 것 같습니다.
바로 PATCH인데요.
GET/POST/PUT/DELETE와 달리 “부분 수정”이라는 설명만으로는 실제 사용 기준이 모호하고, 여러 표준이 공존해 선택지가 많습니다.
이 글에서는 PATCH가 왜 애매하게 느껴지는지, PUT과 무엇이 다른지, 그리고 실무에서 어떤 방식으로 선택해 사용했는지까지 정리해 보려고 합니다.

PATCH가 애매한 이유

PATCH는 HTTP/1.1(RFC 5789)에 정의된 부분 수정(partial update) 용 메서드입니다.
“부분 수정”이라는 말이 열려 있어 다음과 같은 질문이 생깁니다.
- 어떤 필드까지 수정 가능해야 하는가?
- 없는 필드가 오면 어떻게 처리해야 하는가? null은 변경인가 삭제인가?
- PUT과의 경계는 어디까지로 볼 것인가?
스펙이 구현 방법을 강제하지 않아 팀마다 사용 방식이 달라지기 쉽습니다.
특히 다음 세 가지가 애매함을 키웁니다.
- 표현 방식의 다중 표준: JSON Merge Patch, JSON Patch 등 Content-Type별 규칙이 달라 어떤 포맷을 선택할 지부터 정해야 합니다.
- 부분 수정 범위의 불명확성: 누락 필드는 유지인지 삭제인지, null은 값 설정인지 제거인지 같은 해석을 팀이 합의해야 합니다.
- 멱등성/원자성 해석 차이: PATCH는 멱등성이 구현에 따라 달라지고, 여러 연산을 한 요청에 묶을 때 실패 시 롤백 여부 등 원자성 정책도 명확히 정해야 합니다.

PUT vs PATCH

구분	PUT	PATCH
목적	리소스 전체 교체	리소스 부분 수정
요청 바디	전체 리소스 표현	변경하려는 필드만
누락 필드	제거될 수 있음	그대로 유지
멱등성	O	구현에 따라 다름

PUT은 “이 리소스를 이 상태로 만들어라” 라는 의미에 가깝습니다.
PATCH는 “이 리소스에 이 변경을 적용해라” 라는 의미에 가깝습니다.
PATCH에서 변경을 어떻게 표현할지에 대한 명확한 기준이 없다는 점이 애매함의 핵심이라고 생각합니다.

PATCH 표현 방식 두 가지

(표현 방식에 맞춰 Content-Type을 명시하는 게 헷갈림을 줄입니다. 대부분 application/json으로 받기도 하지만, 표준은 merge patch → application/merge-patch+json, json patch → application/json-patch+json입니다.)

1) JSON Merge Patch (`application/merge-patch+json`)

{
  "name": "new-name",
  "email": null
}

동작: 요청에 포함된 필드만 기존 리소스에 병합합니다.
포함되지 않은 필드는 그대로 유지합니다.
null은 보통 해당 필드를 제거(또는 비활성화)로 해석합니다.
강점: 구조가 단순하고 DTO 기반으로 쉽게 구현할 수 있어 애플리케이션 레벨에서 빠르게 적용 가능합니다.
한계: 깊은 중첩/배열을 세밀하게 조작하기엔 표현력이 부족합니다.
```
    `null`의 의미를 팀이 명확히 합의해야 합니다.
```

2) JSON Patch (`application/json-patch+json`)

[
  { "op": "replace", "path": "/name", "value": "new-name" },
  { "op": "remove", "path": "/email" }
]

동작: op/path/value로 변경 작업을 순서대로 명시합니다.
add, remove, replace, move, copy, test 등의 연산을 지원합니다.
강점: 배열·중첩 구조까지 세밀하게 지정할 수 있고, 한 요청에 여러 연산을 묶어 순차 적용할 수 있습니다.
한계: path 검증, 파싱, 예외 처리, 실패 시 롤백 정책 등을 별도로 설계해야 하며, 클라이언트·서버 모두 동일한 규칙을 이해해야 합니다.

주로 사용하게 된 Merge Patch

실무에서는 요구사항이 단순했기 때문에 Merge Patch로 충분했습니다.
주요 패턴은 필드 값 변경, on/off, null을 통한 비활성화였습니다.

일반 DTO로 처리할 수 있어 구현과 유지보수 비용이 낮았습니다.

@PatchMapping("/users/{id}")
public void updateUser(@RequestBody UpdateUserRequest request) {
  ...
}

JSON Patch는 별도의 파서, path 유효성 검증, 실패 시 에러 규칙을 설계해야 해서 팀 단위 유지보수 비용이 커집니다.
표준을 모두 아는 것과 서비스에 맞게 선택하는 것은 다릅니다. 우리는 “명확하고 예측 가능한 API”를 우선해 Merge Patch를 채택했습니다.
다만 팀 컨벤션과 요구사항 복잡도에 따라 달라질 수 있습니다. 깊은 중첩/배열을 세밀하게 다루거나 여러 연산을 한 번에 표현해야 하면 JSON Patch가 더 적합할 수 있습니다.

언제 JSON Patch를 고려할까?

배열이나 중첩 구조를 정밀하게 조작해야 하는 경우: 특정 index 삽입/삭제, 깊은 path 수정 등.
ex) TODO 리스트에서 3번째 항목을 1번째로 이동, 중첩 설정 객체의 일부만 제거.
한 요청에 여러 연산을 순서대로 묶어야 하는 경우: add → replace → remove처럼 순차적 패치를 명시해야 할 때.
(Merge Patch에서도 add/modify 필드를 나눠 흉내 낼 수 있지만, JSON Patch는 그 흐름이 표준화되어 있고 클라이언트·서버가 동일한 표현을 공유하기 쉽습니다.)
변경 전 상태를 확인하는 조건부 업데이트가 필요한 경우: test 연산으로 사전 검증 후 적용.
ex) 특정 버전/etag일 때만 replace, 값이 X일 때만 remove.
외부에 공개되는 범용/플러그인형 API처럼 표준화된 패치 포맷을 요구하는 경우.
문서 기반 리소스(설정/정책 문서 등)처럼 구조가 자주 변하고 호환성을 유지해야 하는 경우.
ex) 사용자 정의 스키마를 가진 설정 문서, 정책 JSON을 여러 클라이언트가 패치해야 하는 경우.

PATCH가 애매한 이유는 메서드가 모호해서라기보다, 구현 방식이 너무 열려 있기 때문입니다.
결국 팀이 무엇을 우선순위로 두느냐가 선택을 가릅니다.
우리처럼 단순한 요구라면 Merge Patch 하나로 충분히 깔끔하게 갈 수 있고, 구조가 복잡하거나 표준화된 패치 표현을 외부에 열어야 한다면 JSON Patch가 힘을 발휘합니다.
중요한 건 두 표준을 모두 아는 것보다, 서비스에 맞춰 고르게 쓸 수 있어야 할 것 같습니다!

프록시 DB란? 읽기·쓰기 분리

누구세연 — Wed, 19 Nov 2025 22:29:27 +0900

대규모 서비스를 운영하다 보면, 트래픽이 늘어날수록 DB 부하가 병목이 되는 순간이 찾아옵니다.
트래픽 스파이크나 정기 리포트 배치처럼 단순 조회성 쿼리가 몰리면 “운영 데이터베이스의 안정성”이 흔들리기 시작하죠.

이럴 때 자주 등장하는 해결책 중 하나가 바로 프록시 DB(Proxy DB) 입니다.
단순히 DB 앞단에 장비를 하나 더 세우는 것이 아니라, 읽기/쓰기 특성을 분리하고 운영 전략을 명시적으로 가져가겠다는 선언에 가깝습니다.

이번 글에서는 프록시 DB의 기본 개념부터, 운영 중 겪는 실전 이슈, 그리고 개발자 입장에서의 사용 패턴까지 정리해보려 합니다.

프록시 DB란 무엇일까?

말 그대로 본 DB(Primary) 앞단에 서서 요청을 중계하는 “중간 계층”입니다. 애플리케이션은 Proxy 하나만 바라보고, Proxy가 알아서 Primary/Replica를 골라주는 구조입니다.
여기서 Primary는 “쓰기 전용 DB”, Replica는 “Primary를 복제한 읽기 전용 DB”라고 이해하면 쉽습니다.

아키텍처 다이어그램은 아래와 같습니다.

Application: 클라이언트 요청을 받아 SQL을 Proxy로 던집니다. DB가 하나인 것처럼 느끼죠.
DB Proxy / Router: SQL을 파싱하고 커넥션 풀, 트랜잭션 스티키니스를 관리합니다.
Primary DB (Writer): INSERT/UPDATE/DELETE를 처리하고 binlog를 생성합니다.
Replica DB (Readers): Primary의 binlog를 비동기로 따라가며 읽기 트래픽을 분산합니다.

MySQL 진영에서 ProxySQL, MaxScale, MySQL Router가 대표적이고, 클라우드에서는 RDS Proxy나 Aurora Router, 그리고 Vitess VTGate 같은 도구도 자주 언급됩니다.

어떻게 동작할까?

애플리케이션이 Proxy 엔드포인트로 SQL을 보냅니다.
Proxy는 SQL 타입, 세션 힌트, 트랜잭션 상태를 보고 “이건 Primary”, “이건 Replica”라고 결정합니다.
Primary는 쓰기 트랜잭션을 처리하고 binlog를 남깁니다.
Replica는 binlog를 적용해 최신 상태를 따라잡고, SELECT 요청을 받습니다.
Proxy는 커넥션 수, Replica lag, 헬스 상태를 감시하며 Failover 전략을 실행합니다.
필요하다면 Proxy가 자체 커넥션 풀과 캐시 정책을 적용해 애플리케이션의 DB 커넥션 개수를 간접적으로 조절합니다.

예를 들어 사용자가 “새 글 작성” 버튼을 눌러 POST /items 를 호출하면, Proxy는 INSERT 쿼리를 Primary로 보냅니다.
곧바로 GET /items/{id} 요청이 들어오면 Proxy는 “방금 쓴 글을 바로 보여줘야 한다”는 조건을 보고 Primary로 라우팅 하지만, “전체 글 목록” 같은 리스트 조회는 Replica로 분산합니다.
이 흐름이 읽기/쓰기 분리의 기본 골격입니다.

핵심은 쓰기 쿼리는 반드시 Primary, 읽기 쿼리는 Replica로 분산. 그리고 “쓰기 직후 조회”처럼 정합성이 민감한 흐름은 Proxy가 Primary를 고정시켜 준다는 점입니다.

왜 도입할까?

읽기/쓰기 분리: SELECT를 Replica로 보내 Primary 부하를 줄입니다.
트래픽 분산: 리포트, 리스트 API 같은 읽기를 Replica에서 처리해 전체 응답 시간을 안정화합니다.
장애 대비: Primary 장애 시 Replica를 임시 조회 노드로 쓰고, Proxy가 커넥션을 차단해 장애 범위를 제한합니다.
보안/정책 분리: 외부에서는 Proxy만 노출하고, 내부 정책을 Proxy에서 통제할 수 있습니다.

결국 프록시 DB는 “DB를 더 많이 장만하는 것”이 아니라, 읽기와 쓰기의 속성을 나눠 다루는 운영 방식입니다.

⚠️ 도입 전에 생각할 것

운영 복잡도 증가: Proxy 자체도 장애 포인트이므로 이중화, 패치, 모니터링 계획이 선행돼야 합니다.
SQL 파싱 한계: Stored Procedure나 복잡한 커스텀 함수는 Proxy가 읽기/쓰기를 잘못 판단할 수 있습니다.
정합성 정책 수립: “eventual consistency를 허용하는 범위”를 UX 관점에서 합의하지 않으면 도입 효과가 반감됩니다.

운영 중 자주 맞닥뜨리는 이슈

Proxy를 세우면 마치 모든 것이 자동화될 것 같지만, 실제 운영에서는 다음과 같은 함정이 반복해서 등장합니다.
각 이슈가 왜 생기는지, 현장에서 즉시 적용할 수 있는 대응법을 함께 정리했습니다.

1) 복제 지연(Replication Lag)

Replica는 Primary의 binlog를 따라가는데, 트래픽이 쏠리거나 대량 쓰기가 붙으면 지연이 발생합니다.

증상: “방금 저장한 데이터가 조회되지 않는다”, 빈 리스트, 오래된 캐시 갱신.
왜 생길까?: Primary → Replica 동기화는 네트워크와 I/O에 의존하므로, 초당 수천 건의 INSERT가 들어오면 Replica가 그 속도를 따라잡지 못합니다.
팁: CloudWatch나 PMM처럼 Replica_Lag 지표에 알람을 걸고, 허용 지연(예: 1초 이상) 시 Proxy가 해당 Replica를 읽기 대상에서 제외하도록 설정합니다.
대응: 쓰기 직후 조회는 반드시 Primary, Replica lag가 일정 기준 초과하면 Proxy에서 제외, 도메인별로 “읽기라도 Primary 강제” 정책을 두는 것도 방법입니다.

2) 스키마 불일치(DDL 타이밍)

Primary에는 새로운 컬럼이 있는데 Replica에는 없어 Unknown column 에러가 나는 상황입니다.

왜 생길까?: Replica는 binlog를 순차적으로 따라가기 때문에, Primary에서 ALTER TABLE 을 실행한 직후 Replica는 아직 예전 스키마로 SELECT를 처리합니다.
팁: pt-online-schema-change, Liquibase 같은 도구로 DDL 계획을 코드화하고, 배포 일정과 Proxy 라우팅 정책을 한 문서에서 관리합니다.
대응: DDL 적용 순서를 Primary → Replica로 명확히 하고, 마이그레이션 동안 해당 도메인의 읽기는 Primary로 고정합니다. 호환 스키마(old/new 필드 동시 지원)를 설계하는 것도 안전합니다.

3) Failover(장애 전환) 복잡성

Primary 장애 시 Replica를 Primary로 승격해야 하는데, 비동기 복제라면 binlog가 다 적용되지 않았을 수 있습니다.

왜 생길까?: 장애는 대개 새벽이나 주말에 오고, 운영자가 직접 커넥션을 끊고 호스트를 바꾸는 동안 수천 개 커넥션이 타임아웃 나 버립니다.
팁: ProxySQL의 scheduler, RDS Proxy의 자동 failover 같은 기능을 미리 테스트하고, “누가 어떤 명령을 실행할지”까지 체크리스트로 만들어 두면 당황하지 않습니다.
대응: 세미동기 복제를 고려하고, Proxy의 자동 Failover 기능을 적극 활용합니다. 장애 시 어떤 순서로 hostgroup 업데이트, DNS 변경, 애플리케이션 재연결을 할지 문서화해 두는 것이 정말 중요합니다.

4) ⚙️ 트랜잭션 스티키니스

BEGIN; SELECT ...; UPDATE ...; 가 서로 다른 노드로 라우팅되면 정합성이 깨집니다.

왜 생길까?: Proxy가 각 SQL을 독립적으로 판단하면, 트랜잭션 중간 SELECT를 Replica로 보내 버릴 수 있기 때문입니다.
팁: ProxySQL은 hostgroup “stickiness” 옵션이 있고, RDS Proxy는 트랜잭션 단위로 Primary에 붙어 있게 만들 수 있습니다. 프레임워크 단에서도 @Transactional 에 readOnly=false 같은 속성을 명시합니다.
대응: 트랜잭션 시작 시 Proxy가 세션을 Primary에 고정하고, SELECT ... FOR UPDATE 는 무조건 Primary로 보내도록 설정합니다.

5) 관측과 모니터링

Proxy, Primary, Replica 각각의 지표를 보지 않으면 장애 원인을 Primary 탓으로만 돌리게 됩니다.

무엇을 볼까?: Replica lag, Proxy 커넥션 풀 사용률, hostgroup 별 큐 길이, 라우팅 실패율, Primary CPU/IO, slow query 비율이 기본 세트입니다.
팁: 한 대시보드에서 Proxy 지표와 DB 지표를 함께 보고, 월 1회라도 장애 리허설을 하면 “Proxy 설정은 잘돼 있는데 Primary가 버티지 못했다” 같은 오해를 줄일 수 있습니다.
대응: Replica lag, Proxy 큐 길이, 라우팅 실패율 등을 모니터링하고, 주기적으로 Failover 리허설을 합니다.

‍ 개발자 입장에서의 사용 패턴

프록시 DB를 도입한다고 애플리케이션 코드가 모두 바뀌는 것은 아닙니다..!

현실적으로는 (찾아보며) 아래 두 패턴을 가장 많이 보았습니다.

핵심은 “Proxy가 자동으로 판단하게 둘 것인가”, “애플리케이션이 읽기/쓰기를 명시할 것인가”의 선택입니다.
도입한 뒤에도 “어떤 쿼리가 왜 특정 노드로 가는지”를 전제와 함께 문서화해야 지속적으로 운용할 수 있습니다.

️ 패턴 A — 프록시가 모든 라우팅 담당

프록시가 “SELECT는 Replica, INSERT/UPDATE는 Primary”를 자동으로 결정합니다. 모놀리식이나 레거시 시스템에서 도입하기 쉽습니다.
개발자는 기존 커넥션 문자열만 Proxy 주소로 바꾸면 되기 때문에 “비침투적”인 방식입니다.

정합성 규칙

INSERT 직후 데이터는 이미 알고 있다
Primary에서 INSERT를 했으므로 PK, 입력 값, default 값, trigger 결과까지 애플리케이션이 보유하고 있습니다. ⇒ POST 응답은 Replica 지연과 무관하게 정확합니다.
문제는 그다음 GET이 Replica로 갈 수 있다는 점
POST /items 다음 바로 GET /items/{id} 를 호출하면 Replica에서 아직 복제가 안 끝났을 수 있습니다.
쓰기 직후 조회는 Primary로 강제
Proxy 세션 스티키니스(read-your-writes), SQL 힌트(/* read_from_primary */), hostgroup routing을 사용합니다.
POST 응답을 풍부하게
생성된 리소스 정보를 충분히 내려주면 클라이언트가 즉시 GET을 호출할 이유가 줄어듭니다.
리스트 조회는 Replica 기반으로
“조금 늦게 보여도 되는 데이터”는 Replica에서, 단건 상세 조회는 Primary로 분리합니다.

️ 패턴 B — 애플리케이션이 R/W 의도 명시

Spring+JPA 환경에서 많이 쓰는 방식으로 DataSource/Port를 나눕니다.

writerDataSource → Primary
readerDataSource → Replica

즉, 코드 레벨에서 “이 쿼리는 읽기용, 저 쿼리는 쓰기용”을 분리해 Proxy에게 명확한 신호를 줍니다.
MSA 구조나 이벤트 기반 시스템처럼 서비스별 특성을 살리고 싶을 때 유리합니다.

정합성 규칙

쓰기와 조회를 같은 트랜잭션 안에서 처리

@Transactional
public ItemResponse createItem(CreateItemReq req) {
    Item item = itemWriteRepo.save(...);    // INSERT → Primary
    return ItemResponse.from(item);         // 엔티티로 바로 응답
}

별도 SELECT 없이도 정확한 응답을 만들 수 있어 가장 안전합니다.

상세 조회는 필요에 따라 Primary 강제
force_primary=true 같은 파라미터로 Primary를 선택하거나, 쓰기 직후 상세 API는 writerDataSource를 사용합니다.
리스트/통계는 Replica 전용
eventual consistency를 UX로 허용하고, 읽기 부하 대부분을 Replica로 넘깁니다.
Reader/Writer 혼용 금지
readOnly 트랜잭션에서 write 호출 금지, reader 포트에서 INSERT/UPDATE 금지 등 규칙을 코드로 강제합니다.

✍️ 마무리 & 체크리스트

프록시 DB는 “읽기/쓰기 분리를 자동으로 해 주는 중간 계층”이라는 단순한 정의 뒤에, 운영 디테일과 정합성 전략이 숨어 있습니다.
아래 체크리스트만 꾸준히 확인해도 Proxy 도입 효과를 확실히 체감할 수 있었습니다.

질문	체크 포인트
어느 API가 최신성을 요구하는가?	라우팅 힌트나 Primary 강제가 필요한 API를 목록화합니다.
Proxy가 SQL을 정확히 분류할 수 있는가?	Prepared statement, 세션 변수, Stored Procedure 사용 여부를 점검합니다.
Replica lag와 Failover 상태를 모니터링하는가?	Proxy/DB 지표를 한 대시보드로 묶고 알람을 정의합니다.
장애 시나리오는 문서화되어 있는가?	Primary 승격, hostgroup 업데이트, 애플리케이션 재연결 순서를 정리합니다.

프록시 DB를 도입하면 단순히 “DB를 분산했다”가 아니라, 쓰기 직후 조회는 Primary로, eventual consistency를 허용할 영역은 Replica로, 장애 시나리오를 미리 연습한다는 습관을 가지게 됩니다.

이 세 가지 원칙만 실천해도 트래픽 폭증 순간마다 Proxy가 든든한 방패가 되어 줄 거라는 생각이 듭니다.

nGrinder로 시작하는 부하 테스트 가이드

누구세연 — Mon, 20 Oct 2025 23:20:20 +0900

JMeter는 다양한 부하 테스트를 수행할 수 있는 강력한 도구지만, 팀 단위 운영이나 리포트 공유 측면에서는 한계가 있습니다.

이런 불편함을 해소하기 위해 등장한 도구가 바로 nGrinder입니다. nGrinder는 분산 부하 테스트, 웹 기반 시나리오 관리, 자동 리포트 생성 등 팀 단위 테스트 환경에 필요한 기능을 기본으로 제공합니다.

특히 JMeter에서 직접 설정해야 했던 분산 실행이나 리포팅 작업을 nGrinder에서는 웹 UI에서 클릭 몇 번으로 간단히 처리할 수 있죠. 이번 글에서는 JMeter에서는 다소 번거로웠던 부분들을 nGrinder에서는 어떻게 더 쉽게 해결할 수 있는지 함께 살펴보겠습니다.

nGrinder란?

nGrinder는 네이버에서 진행한 오픈 소스 프로젝트로 서버의 부하 테스트를 위한 도구입니다.
쉽게 말해, 여러 대의 컴퓨터(Agent)를 동시에 이용해서 대규모 트래픽을 한꺼번에 발생시켜 서버의 성능을 테스트할 수 있는 도구예요. ⚒️

JMeter가 개인용 테스트 툴이라면, nGrinder는 팀이나 조직이 함께 사용하는 부하 테스트 플랫폼이라고 볼 수 있습니다.

nGrinder 구조

nGrinder는 크게 두 가지 역할로 나뉩니다.

Controller: 테스트를 관리하는 중앙 서버예요.
웹 UI를 통해 테스트를 만들고, 실행하고, 결과를 확인할 수 있습니다.
Agent: 실제로 요청을 보내 부하를 발생시키는 역할이에요.
Controller의 지시에 따라 동시에 트래픽을 발생시키고, 결과 데이터를 다시 전달합니다.

Controller가 언제, 몇 명이, 어떤 요청을 보낼지를 정하면 Agent들이 동시에 실행해 서버를 몰아붙입니다.

아래 그림은 이런 구조를 시각적으로 보여주는 nGrinder 시스템 아키텍처입니다

1️⃣ 사용자가 Controller에 테스트 실행을 요청
2️⃣ Controller가 테스트 환경을 세팅하고 Agent들을 연결
3️⃣ Agent들이 실제로 타깃 서버(Target Server)에 트래픽을 발생
(이때 각 Agent는 Controller와 통신하며 상태를 유지하고)
4️⃣ 실행 결과와 서버의 모니터링 데이터를 다시 Controller로 보내 리포트가 생성

설치 및 환경 구성

이제 nGrinder의 개념과 구조를 이해했으니, 직접 설치해서 Controller와 Agent가 어떻게 동작하는지 확인해 보겠습니다!

1️⃣ 사전 준비

설치를 시작하기 전에 아래 환경을 준비해 주세요.

구분	요구사항
Java	JDK 8 이상 (JDK 17 권장)
OS	Windows, macOS, Linux 모두 가능
메모리	Controller 최소 2GB, Agent는 부하 크기에 따라 4GB 이상 권장
네트워크	Controller ↔ Agent 간 통신 가능해야 함 (기본 포트 16001, 16002)

Controller와 Agent는 같은 서버에 설치해도 되지만,
실제 대규모 테스트를 위해서는 별도의 서버(혹은 VM, Docker 컨테이너)에 분리하는 게 좋습니다.

2️⃣ Controller 설치

nGrinder Controller는 웹 UI를 제공하는 중앙 서버입니다.
여기서 테스트를 만들고, Agent를 등록하며, 실행 결과를 확인할 수 있습니다.

방법 1. WAR 파일로 직접 실행

https://github.com/naver/ngrinder/releases

Releases · naver/ngrinder

enterprise level performance testing solution. Contribute to naver/ngrinder development by creating an account on GitHub.

github.com

위의 공식 릴리즈 페이지에서 최신 버전을 다운로드합니다.

다운로드한 후에 아래 명령어로 실행합니다.

java -jar ngrinder-controller-3.5.9-p1.war

기본 포트는 8080이나 저는 이미 사용 중이어서 포트를 지정하여 실행하였습니다.

(--port=8081)

브라우저로 http://localhost:8081 접속하면 nGrinder 로그인 화면이 나타납니다.

초기 로그인 정보
ID: admin
PW: admin

방법 2. Docker로 실행

Docker 환경이라면 훨씬 간단히 실행할 수 있습니다.

docker run -d --name ngrinder-controller \
  --platform linux/amd64 \
  -p 8080:80 \                 # UI
  -p 16001:16001 \             # Agent 제어포트
  -p 12000-12009:12000-12009 \ # ✅ 콘솔 포트(동시 테스트용 범위)
  ngrinder/controller:3.5.9-p1

✅ 실행 확인
브라우저에서 http://localhost:8080으로 접속했을 때
nGrinder Console 화면이 보이면 Controller 설치가 완료된 것입니다.

3️⃣ Agent 설치

Agent는 실제로 부하를 발생시키는 역할을 합니다.
Controller에서 테스트 명령을 받아 요청을 보내고, 결과를 다시 전달합니다.

1. Controller 웹 UI → 상단 메뉴 “Agent Download” 클릭

2. 다운로드한 파일(ngrinder-agent-3.5.9-p1-localhost.tar) 압축 해제

3. 아래 명령으로 실행

./run_agent.sh

4. 콘솔 로그에 아래와 같은 메시지가 뜨면 성공입니다.

Controller UI의 Agent Management 탭에서 Agent 상태가 Active로 표시되는지 확인합니다.

여러 대의 Agent를 동시에 등록할 수도 있습니다.
테스트 규모가 클수록 Agent 수를 늘리면 분산 부하를 효율적으로 발생시킬 수 있습니다

첫 테스트 실행 (Hello nGrinder)

Controller와 Agent가 모두 준비되었으니, 실제로 nGrinder에서 부하 테스트를 만들어 실행해 볼 차례입니다.

nGrinder는 웹 UI에서 바로 스크립트를 작성하고, 실행 후 결과를 시각적으로 확인할 수 있습니다.

1️⃣ 로그인 및 기본 화면 살펴보기

브라우저에서 Controller 주소로 접속합니다.

기본 계정으로 로그인합니다.

ID: admin
PW: admin

테스트 작성과 실행을 빠르게 할 수 있는 “Quick Start” 영역을 중심으로 구성돼 있습니다.

메뉴	설명
Performance Test	실제 부하 테스트를 설정하고 실행하는 메인 메뉴
Script	테스트 스크립트를 작성하고 관리하는 공간
admin ▼	사용자 계정 설정, Agent 관리, 시스템 설정 등
Help	공식 문서 및 Q&A 링크

Quick Start 영역

Type URL: 부하를 걸고 싶은 대상 URL을 입력하는 곳이에요.
예를 들어 https://localhost:8080/get 입력 후 Start Test 클릭하면,
자동으로 간단한 부하 테스트가 실행됩니다.
Groovy / Jython 선택: 사용할 스크립트 언어를 선택할 수 있어요.
(기본은 Groovy, Python 스타일을 원하면 Jython 선택)

하단 영역

Q&A: 자주 묻는 질문과 커뮤니티 문서 링크
Developer Resources: API 문서, GitHub 링크 등 개발 참고자료

2️⃣ 샘플 스크립트 생성

처음 사용하는 경우라면,
nGrinder는 기본 HTTP 테스트 스크립트 샘플을 자동으로 제공합니다.

상단 메뉴 → Scripts 클릭
“Create Script” 버튼 클릭
Script Name 입력 (예: get-test)
“Create” 클릭

생성 후 확인

스크립트 편집 화면에는 기본 템플릿 코드가 자동으로 생성됩니다.

보통 이런 형태로 시작해요

import static net.grinder.script.Grinder.grinder
import static org.hamcrest.Matchers.*
import static org.junit.Assert.*

import net.grinder.script.GTest
import net.grinder.scriptengine.groovy.junit.GrinderRunner
import net.grinder.scriptengine.groovy.junit.annotation.BeforeProcess
import net.grinder.scriptengine.groovy.junit.annotation.BeforeThread
import org.junit.Before
import org.junit.Test
import org.junit.runner.RunWith

import org.ngrinder.http.HTTPRequest
import org.ngrinder.http.HTTPRequestControl
import org.ngrinder.http.HTTPResponse
import org.ngrinder.http.cookie.Cookie
import org.ngrinder.http.cookie.CookieManager

@RunWith(GrinderRunner)
class TestRunner {

    public static GTest test
    public static HTTPRequest request

    // 필요 시 헤더/쿠키 넣고 싶을 때 여기 채워쓰면 됩니다.
    public static Map<String, String> headers = [:]
    public static List<Cookie> cookies = []

    @BeforeProcess
    public static void beforeProcess() {
        // ⚠️ setUseCookies(), getCookieManager() 같은 호출 넣지 말 것!
        HTTPRequestControl.setConnectionTimeout(300000)
        test = new GTest(1, "Sample HTTP Test")
        request = new HTTPRequest()
        grinder.logger.info("before process.")
    }

    @BeforeThread
    public void beforeThread() {
        test.record(this, "test")
        grinder.statistics.delayReports = true
    }

    @Before
    public void before() {
        // 공통 헤더/쿠키가 있으면 여기서 적용 (비어있으면 아무 일도 안 함)
        request.setHeaders(headers)
        CookieManager.addCookies(cookies)
    }

    @Test
    public void test() {
        String targetUrl = "https://httpbin.org/get"  // 필요 시 수정
        HTTPResponse res = request.GET(targetUrl)

        grinder.logger.info("GET {}", targetUrl)
        grinder.logger.info("status={}", res.statusCode)

        assertThat("Response code should be 200", res.statusCode, is(200))
    }
}

@BeforeProcess → 테스트 전 초기 설정 (전역, 1회)
@BeforeThread → 각 쓰레드 시작 전 1회
@Before → 매 요청 전에 실행 (쿠키, 헤더 초기화 등)
@Test → 실제 요청과 검증 수행

3️⃣ 테스트 설정

상단 메뉴에서 Performance Test로 이동하여 Create Test 버튼을 클릭합니다.

이 한 화면에서 “얼마나 많은 사용자(Vuser)”가 “어떤 스크립트”를 “얼마 동안” 돌릴지를 전부 지정하게 됩니다.

Performance Test

항목	설정 값	설명
Agent	1	컨트롤러에 연결된 에이전트 1개
Vuser per Agent	10	각 Agent가 10명 시뮬레이션
Processes × Threads	1 × 10	10명의 가상 사용자
Script	get-test.groovy	실행할 테스트 스크립트
Duration	0:01:00	1분 동안 테스트 실행
Ramp-Up	비활성	모든 사용자 즉시 시작

➡️ 이 설정으로 “총 10명의 가상 사용자”가 “1분 동안” get-test.groovy 스크립트를 계속 실행하게 됩니다.

기본 정보 (상단)

Test Name: 테스트 이름. 리포트에 표시됩니다. (예: Get Test)
Description: 테스트 목적이나 메모를 남기는 곳.
→ “nGrinder GET 요청 테스트”처럼 기록용으로 사용.
Tags: 리포트 필터링용 태그. 여러 테스트를 구분할 때 유용

Test Configuration (중앙)

여기가 핵심 설정 구간이에요.

Agent

Agent (Max:1)
→ 현재 연결된 부하 발생기(Agent) 수.
→ 지금은 1개가 연결되어 있으니 1로 지정해야 함.
→ 여러 개 연결되어 있다면 2~3개 이상 선택 가능.

Agent 1개 = 실제 테스트를 실행하는 서버 1대.

Vuser per agent (가상 사용자 수)

Agent 한 대가 동시에 시뮬레이션할 가상 사용자(Virtual User) 수
→ 예시 설정: 10
→ 즉, Agent 1개 × 10명 = 총 10명의 가상 사용자가 동시에 API 호출을 반복.
Processes: JVM 프로세스 수 (부하 발생 프로세스 단위)
Threads: 프로세스당 쓰레드 수
→ 실제 Vuser 수 = Processes × Threads
→ 지금은 1 × 10 = 10명.

대부분의 경우 프로세스 1개, 쓰레드 수로 사용자 수 조절이 효율적입니다.

Script

실행할 테스트 스크립트를 선택하는 부분.
→ 방금 작성한 get-test.groovy 선택!
(파일명은 Script > List 탭에서 관리됩니다.)

Script Resources

외부 리소스(예: CSV 데이터, 이미지, JSON 파일)를 같이 업로드할 때 사용.
→ 일반적인 API 테스트에는 비워둬도 OK.

Target Host

테스트 대상 호스트의 공통 prefix URL을 지정하는 곳.
→ 예: http://wiremock:8080
→ 스크립트 안에서 상대 경로(/api/customers)로 호출할 수 있게 됩니다.

스크립트에서 이미 전체 URL을 쓴다면 이 필드는 비워도 됩니다.

Duration / Run Count (하단)

부하 테스트의 “지속 시간” 또는 “반복 횟수”를 결정하는 부분입니다.

Duration
→ 테스트를 정해진 시간 동안 반복 실행
→ 예시: 0시간 1분 0초 → 1분 동안 테스트 실행
Run Count
→ 시간 대신 “몇 번 반복할지” 설정
→ 예: 1000 → 각 Vuser가 1000번 요청 보냄

Duration과 Run Count 중 하나만 선택합니다.
보통은 Duration(시간 기반) 이 더 많이 쓰입니다.

Ramp-Up (점진적 부하 증가)

체크하면 부하를 천천히 늘릴 수 있습니다.
(모든 Vuser를 한 번에 실행하지 않고, 일정 간격으로 추가)
Initial Count: 처음 실행할 Vuser 수
Incremental Step: 한 번에 늘릴 Vuser 수
Interval: Vuser 증가 간격(ms 단위)

예: Initial 0, Step 1, Interval 1000 → 1초마다 1명씩 추가
즉, 점진 부하 테스트(Gradual Ramp-Up) 용도입니다.

설정 후 “Save & Start Test” 버튼을 클릭합니다.

4️⃣ 테스트 실행 및 모니터링

테스트가 실행되면 다음과 같은 화면이 나타납니다:

그래프(Throughput, TPS, Response Time 등)가 실시간 갱신
왼쪽 하단 로그 영역에서는 Agent 상태 확인 가능
우측 상단에서는 현재 진행률과 실패율을 모니터링할 수 있습니다.

팁: 테스트 도중 “Stop” 버튼을 눌러 중단할 수 있으며, 테스트 로그는 자동으로 압축되어 결과 리포트에 포함됩니다.

5️⃣ 결과 리포트 확인

테스트가 완료되면 자동으로 결과 리포트가 생성됩니다.
리포트는 다음 3가지 주요 섹션으로 나뉘어 있어요.

Summary
- 테스트 이름, 실행 시간, Vuser 수, TPS(초당 트랜잭션 수), 평균 응답 시간 등
- 실패율 및 에러 코드 비율 확인 가능
Charts (그래프)
- TPS(Time Per Second): 초당 요청 처리량
- Mean Response Time: 평균 응답 시간
- Peak TPS: 시스템이 감당 가능한 최대 처리 속도
- Errors: HTTP 오류(4xx, 5xx) 발생 비율
Details (상세 데이터)
- 스크립트별, 요청별 세부 응답 시간
- 분당 요청 수, 응답 분포(Percentile 90, 95, 99)
- 개별 스레드의 지연 시간까지 확인 가능

리포트는 .zip 형태로 다운로드 가능하며, 팀 단위로 공유하거나 이전 테스트와 비교 분석할 수 있습니다.

6️⃣ 테스트 결과 해석 팁

nGrinder 리포트는 단순한 수치 이상의 정보를 제공합니다.

아래는 결과를 해석할 때 도움이 되는 핵심 포인트입니다

항목	의미	해석 포인트
TPS (Transaction Per Second)	초당 요청 처리량	높을수록 처리 효율이 좋지만, 응답시간과 함께 봐야 함
Mean Response Time (평균 응답시간)	요청에 대한 평균 처리 시간	급격히 상승하면 서버 부하 또는 병목 가능성 있음
Error %	실패한 요청 비율	1% 이상이면 네트워크, 코드 예외, 타임아웃 등을 점검 필요
Vuser Stability	가상 유저의 응답 일관성	일부 유저만 느려진다면 특정 세션 또는 DB 락 이슈 가능
95% Line	상위 5% 요청의 응답시간	SLA 기준을 판단할 때 자주 활용 (예: 95% 응답이 2초 이내)

예시 해석

TPS가 일정 수준 이상에서 평탄해지고 Response Time이 급상승한다면, 해당 시점이 시스템의 처리 한계 지점(Throughput Bottleneck)입니다.
Error가 특정 시점부터 증가한다면, DB 커넥션 부족 또는 Thread Pool 한계일 수 있습니다.

nGrinder는 단순한 부하 테스트 도구를 넘어, 테스트를 운영 프로세스에 자연스럽게 녹일 수 있는 플랫폼입니다.

한 번 환경만 세팅해 두면, 클릭 몇 번으로 팀 전체가 동일한 테스트를 재사용하고 결과를 한눈에 비교할 수 있죠.

앞으로는 Jenkins나 GitLab CI와 연동해 정기적인 성능 테스트 자동화까지 진행해 볼 계획입니다.

Apache JMeter: 설치부터 부하 테스트까지

누구세연 — Sat, 4 Oct 2025 13:10:39 +0900

안정적이고 확장 가능한 서비스를 운영하기 위해서는 기능 구현뿐 아니라 성능 및 부하 테스트가 필수적입니다.

특히 API가 동시에 많은 요청을 받을 때 잘 버텨주는지 확인하지 않으면, 실제 운영 환경에서 큰 장애로 이어질 수 있죠.
대표적인 오픈소스 부하 테스트 도구로는 Apache JMeter와 nGrinder가 있으며, 본 글에서는 상대적으로 단순하고 접근성이 높은 JMeter를 먼저 살펴보고 간단한 실습을 진행하겠습니다.

JMeter란?

Apache JMeter는 아파치 소프트웨어 재단에서 개발한 오픈소스 부하·성능 테스트 툴입니다.
웹 애플리케이션뿐 아니라 다양한 네트워크 서비스의 응답 성능, 처리량, 안정성을 점검할 수 있도록 설계되어 있어요.

원래는 웹 애플리케이션 테스트용으로 시작했지만, 지금은 훨씬 더 범용적으로 진화했습니다.
HTTP/HTTPS 요청은 물론이고, JDBC, FTP, LDAP, SOAP, JMS, SMTP/POP3/IMAP 메일 프로토콜까지 지원하기 때문에
“웹 서버 성능 측정 도구”를 넘어 “범용 성능 테스트 프레임워크”라고 할 수 있습니다.

주요 특징

1) 100% Java 기반

JMeter는 Java로 구현되어 있어 운영체제에 구애받지 않고 JVM만 있으면 실행 가능합니다.
Windows, macOS, Linux 모두 지원되며, 설치도 단순히 압축을 풀고 실행 스크립트를 돌리면 됩니다.
Java 기반이라 멀티플랫폼 호환성이 뛰어나고, 라이브러리 확장성도 높습니다.

2) GUI 환경 제공

jmeter.sh 또는 jmeter.bat을 실행하면 Swing 기반의 GUI가 뜹니다.
시나리오 구성을 드래그 앤 드롭으로 할 수 있어 비개발자도 직관적으로 학습 가능합니다.
예: “Thread Group” → “HTTP Request” → “Listener(결과보기)”를 추가하는 것만으로도 간단히 테스트 가능.
GUI뿐만 아니라 CLI(커맨드라인) 모드도 지원하여, CI/CD 파이프라인이나 서버 환경에서도 자동화 가능.

3) 스레드 기반 가상 사용자 (Virtual User)

JMeter의 부하 발생 원리는 스레드(Thread)를 이용한 가상 사용자 시뮬레이션이에요.
Thread Group 설정에서 가상 사용자의 수(스레드 수), Ramp-up 시간(얼마나 점진적으로 늘릴지), Loop 횟수(몇 번 반복할지)를 지정할 수 있습니다.
이를 통해 “100명이 동시에 로그인하면 서버가 어떻게 버틸까?” 같은 시나리오를 손쉽게 구현할 수 있습니다.

4) 플러그인 에코시스템

JMeter는 풍부한 플러그인 생태계를 갖추고 있어, 기본 기능 이상으로 확장 가능합니다.
예시:
- 다양한 리포트/그래프 뷰어 (Response Times Over Time, Throughput Shaping Timer 등)
- 고급 제어기(Controller), 추가 샘플러(Sampler), 모니터링 플러그인
덕분에 단순히 TPS/응답시간만 보는 게 아니라, 부하 패턴 제어, 응답 본문 검증, 실시간 시각화까지 가능해집니다.

5) 다양한 프로토콜 지원

가장 많이 쓰이는 건 HTTP/HTTPS 기반 API 테스트지만,
DB 연결(JDBC), 메시징(JMS), 메일(SMTP/POP3/IMAP), FTP 업로드/다운로드, LDAP 인증 등도 지원합니다.
즉, 엔드투엔드(End-to-End) 시나리오를 하나의 툴에서 구성할 수 있습니다.

한마디로 JMeter는 쉽게 시작할 수 있는 GUI 도구이면서 멀티프로토콜 지원 & 플러그인 확장성으로 범용 성능 테스트 플랫폼으로 자리 잡은 툴이에요.

JMeter 설치 & 실행

요구 사항

Java Development Kit(JDK): 최소 JDK 8 이상, 권장 JDK 11 이상
→ JMeter는 100% Java 기반이라 JDK 필수. java -version으로 버전 확인 가능
운영체제: Windows, macOS, Linux 모두 지원 (JVM만 있으면 OK)

다운로드

공식 사이트 접속 https://jmeter.apache.org/download_jmeter.cgi

최신 버전의 Binary zip (압축 파일) 다운로드 ( 저는 apache-jmeter-5.6.3.zip로 다운로드하였습니다! )
원하는 위치에 압축을 해제합니다.

~/tools/apache-jmeter-5.6.3/

실행 방법

GUI 모드 실행로 실행해보겠습니다.

cd ~/tools/apache-jmeter-5.6.3/bin
./jmeter.sh

위와 같은 명령어를 실행하면 Swing 기반 GUI가 열리면서 Test Plan 화면이 나타납니다.

서버 환경이나 CI/CD 파이프라인에서 자동화할 때는 CLI 모드를 사용할 수도 있습니다.

./jmeter.sh -n -t test-plan.jmx -l result.jtl -e -o ./report

-n: Non-GUI 모드 실행
-t: 실행할 테스트 플랜 파일 (.jmx)
-l: 결과 저장 파일 (.jtl)
-e: 테스트 종료 후 HTML 리포트 생성
-o: 리포트 출력 디렉토리

실행 완료 후 ./report/index.html을 열면 브라우저에서 결과 대시보드 확인 가능!

부하 테스트 시나리오 만들기

이제 실제 API를 대상으로 부하를 걸어보는 테스트를 만들어볼 차례입니다!_!

Thread Group(스레드 그룹) 추가

부하를 발생시킬 “가상 사용자”를 정의하는 단계입니다.

좌측 트리에서 Test Plan → Add → Threads (Users) → Thread Group 클릭
아래와 같이 주요 옵션을 설정합니다.

옵션	설명	예시
Number of Threads (users)	동시에 접속할 가상 사용자 수	50
Ramp-up period (seconds)	사용자를 몇 초에 걸쳐 늘릴지	10
Loop Count	각 사용자가 요청을 반복할 횟수	5

예: 50명의 사용자가 10초 동안 점진적으로 늘어나면서 총 5번씩 요청 → 총 250회 요청 발생

HTTP Request(요청) 샘플러 추가

테스트할 API를 지정하는 단계예요.

Thread Group → Add → Sampler → HTTP Request
아래처럼 설정합니다.

옵션	설명	예시
Server Name or IP	테스트 대상 도메인	sy-develop-note.tistory.com
Path	API 경로	/get
Method	요청 방식	GET

(저는 로컬에서 실행 중인 Spring Boot API를 대상으로 테스트를 진행했기 때문에 `Server Name`에 `localhost`, `Port Number`에는 애플리케이션이 실행 중인 포트인 `8080`을 입력했습니다. )

Listener(리스너) 추가 – 결과 확인용

테스트 결과를 눈으로 확인하려면 리스너를 추가해야 합니다.

Thread Group → Add → Listener
추천 리스너:
- ✅ View Results Tree – 요청/응답 상세 로그 확인
- Summary Report – 평균 응답 시간, TPS, 에러율 확인
- View Results in Graph – 실시간 성능 그래프

실행 및 결과 해석

이제 상단의 ▶ 버튼을 눌러 테스트를 실행해 봅시다.
테스트가 끝나면 Summary Report에서 다음과 같은 지표를 확인할 수 있습니다.

항목	설명
Samples	총 요청 수
Average	평균 응답 시간(ms)
Throughput	초당 처리 요청 수 (TPS)
Error %	실패율

테스트를 실행한 결과, 아래와 같은 성능 지표를 확인할 수 있었습니다.

✅ 테스트 설정

50 Threads × 5 Loop → 총 250개의 요청 수행

✅ 결과 요약

항목	값	해석
Samples	250	총 250회의 요청이 실행되었음을 의미합니다. (50명의 가상 사용자가 각각 5번 요청)
Average (평균 응답 시간)	2 ms	서버가 요청에 응답하는 데 걸린 평균 시간이 약 2ms로 매우 빠릅니다. 즉, 요청을 거의 즉시 처리하고 있다는 뜻이에요.
Min / Max (최소·최대 응답 시간)	1 ms / 18 ms	가장 빠른 응답은 1ms, 가장 느린 응답도 18ms 수준으로 전체적으로 안정적입니다. 큰 편차 없이 일관된 속도를 유지하고 있어요.
Std. Dev (표준편차)	1.97	응답 시간 변동폭이 작다는 뜻으로, 성능이 일정하게 유지되고 있습니다.
Error % (오류율)	0.00%	250건 요청 모두 성공했으며 실패한 요청이 없습니다. 서버가 모든 요청을 정상적으로 처리했다는 뜻이에요.
Throughput (TPS)	25.4/sec	초당 약 25.4건의 요청을 처리했습니다. 이 수치는 서버의 기본 처리 능력을 보여주며, 현재 설정에서 서버가 초당 약 25건의 요청을 안정적으로 소화 가능하다는 뜻이에요.
Received KB/sec / Sent KB/sec	20.61 / 3.10	초당 약 20.61KB를 수신하고 3.10KB를 전송하고 있다는 뜻으로, 네트워크 사용량이 크지 않은 테스트 시나리오임을 알 수 있습니다.
Avg. Bytes (평균 바이트 수)	830	응답 본문의 평균 크기가 약 830바이트라는 뜻이에요.

TPS(Throughput Per Second)는 서버가 초당 처리할 수 있는 요청 수를 의미합니다. 이 수치를 기준으로 서버의 최대 처리량(capacity)을 가늠할 수 있으며, 실제 운영 환경에서 예상되는 트래픽과 비교하여 여유가 있는지 판단하는 지표로 활용할 수 있습니다.

✏️ 마무리

이렇게 JMeter를 활용하면 별다른 설정 없이도 간단하게 API 부하 테스트를 진행할 수 있습니다.
특히 GUI 환경에서 몇 가지 옵션만 지정하면 가상의 사용자를 만들어 실제 트래픽 상황을 손쉽게 시뮬레이션할 수 있다는 점이 큰 장점이에요.
“성능 테스트”라고 하면 어렵고 복잡할 것 같지만, JMeter는 입문자도 금방 익힐 수 있을 만큼 직관적이라 빠르게 성능 테스트를 시작해 보기 좋은 툴이라고 느꼈습니다.

다만 JMeter는 단일 머신에서 실행된다는 특성상 대규모 트래픽 테스트나 분산 환경 테스트에는 한계가 있어요.
실제 운영 환경과 가까운 조건에서 테스트하려면 더 강력한 도구가 필요하죠.
그래서 다음 글에서는 분산 부하 테스트에 특화된 오픈소스 툴인 “nGrinder”를 활용해 더 발전된 부하 테스트를 진행하는 방법을 다뤄보려 합니다. ‍

공식 문서 기반으로 이해하는 n8n 핵심 개념

누구세연 — Sat, 30 Aug 2025 15:11:09 +0900

n8n

n8n이란?

n8n은 다양한 서비스와 시스템을 서로 연결해 주는 워크플로우 자동화 툴입니다.
쉽게 말해, “특정 이벤트가 발생하면 정해둔 작업들을 순서대로 실행해 주는 자동화 엔진”이에요.

대표적인 SaaS 자동화 툴로는 Zapier가 있지만, n8n은 몇 가지 큰 차별점을 가지고 있습니다.

개발자 친화적인 노코드/로우코드 자동화 플랫폼

n8n의 특징

오픈소스 & 셀프호스팅
- Zapier, Make 같은 툴은 클라우드 서비스 기반이라 사용량이 늘어나면 요금이 빠르게 올라갑니다.
- n8n은 완전히 오픈소스이고, 직접 서버(Docker, Kubernetes 등)에 설치해서 운영할 수 있어 비용과 보안 측면에서 자유도가 높습니다.
Node.js 기반 아키텍처
- n8n은 Node.js 위에서 돌아가며, JavaScript/TypeScript 친화적인 확장성을 제공합니다.
- 필요하다면 직접 커스텀 노드(Node)를 만들어 기능을 추가할 수도 있습니다.
풍부한 통합 지원 (300+ 노드)
- Slack, Discord, Telegram 같은 메신저
- PostgreSQL, MySQL, MongoDB 같은 DB
- AWS, GCP, GitHub, Jira, Sentry 등 다양한 SaaS/DevOps 툴
  → 이미 준비된 노드만 연결하면 바로 자동화 워크플로우를 만들 수 있습니다.
노코드/로우코드 방식
- UI에서 노드를 끌어다 놓고 연결하면 워크플로우가 완성됩니다.
- 필요할 때는 Expression(자바스크립트 문법)이나 Function Node를 활용해서 직접 로직을 추가할 수도 있습니다.
- 즉, 비개발자도 쉽게 쓰되, 개발자가 쓰면 훨씬 강력해지는 툴이에요.

n8n 핵심 개념

Workflow - https://docs.n8n.io/workflows/
- 정의: n8n에서 가장 기본 단위. 여러 Node들이 연결되어 만들어진 자동화 프로세스.
- 역할: 특정 이벤트를 트리거로 시작해서, 조건 분기 → 데이터 가공 → 외부 서비스 호출 → 결과 저장 같은 단계들을 순서대로 실행.
- 특징:
  - GUI 기반으로 시각적으로 구성 가능
  - 재사용 가능 (Export/Import)
  - 실행 이력 관리 가능
Node - https://docs.n8n.io/integrations/builtin/core-nodes/
- 정의: Workflow를 구성하는 “작업 단위”.
- 종류:
  - Action Node: 실제 작업 실행 (DB 쿼리, HTTP 요청, Slack 전송 등)
  - Trigger Node: Workflow 시작 조건 담당
  - Function Node: JavaScript로 데이터 가공
- 특징:
  - 입력 → 처리 → 출력 구조
  - 서로 연결되어 데이터가 흐름
Trigger Node
- 정의: Workflow를 실행하게 만드는 시작점.
- 예시:
  - Manual Trigger – 수동 실행, 개발/디버깅에 자주 사용
  - Schedule Trigger – 시간 기반 자동 실행; cron 표현식도 지원
  - Form Trigger – n8n이 제공하는 간단한 웹 폼 제출을 통해 워크플로우 실행
  - Local File Trigger – 파일 시스템 변화를 감지해 자동 실행 (자체 호스팅에서 유용)
- 특징:
  - Workflow는 반드시 Trigger Node에서 시작
  - 여러 Trigger Node를 한 Workflow에 둘 수도 있음
Expression - https://docs.n8n.io/code/expressions/
- 정의: Node 간 데이터 전달 시 동적으로 값을 생성하는 방식.
- 사용법: {{ $json["fieldName"] }} 같은 JavaScript 문법을 활용.
- 예시:
  - API 응답의 특정 필드만 다음 Node에 넘기기
  - "Hello {{ $json["username"] }}" → Hello 세연
- 특징:
  - 단순 변수 치환부터, JS 코드로 가공까지 가능
  - Function Node를 쓰지 않아도 간단한 로직은 Expression으로 처리 가능
Credentials - https://docs.n8n.io/credentials/
- 정의: 외부 서비스(API, DB 등)와 연결할 때 필요한 인증 정보를 안전하게 저장하는 기능.
- 예시:
  - Slack OAuth Token
  - PostgreSQL DB 계정 정보
  - GitHub Personal Access Token
- 특징:
  - 암호화되어 저장
  - 여러 Workflow에서 재사용 가능
  - 보안상 노드에 직접 입력하지 않고 Credentials에 등록 후 선택
Execution - https://docs.n8n.io/workflows/executions/
- 정의: Workflow가 실행된 기록. 어떤 Trigger로 시작되었고, 각 Node가 어떤 입력/출력을 가졌는지 확인 가능.
- 특징:
  - 성공/실패 여부 확인
  - 실패 시 Error Workflow 연결 가능
  - Debug 모드에서 단계별 데이터 확인 가능
- 예시:
  - Cron Trigger → DB Query → Slack 메시지 → 성공 로그
  - Webhook Trigger → API 오류 발생 → 실패 로그

⚙️ 설치 (Self-host 기준)

Docker를 이용하면 가장 쉽게 설치할 수 있습니다.

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e N8N_BASIC_AUTH_USER=user \
  -e N8N_BASIC_AUTH_PASSWORD=pass \
  n8nio/n8n

실행 후 http://localhost:5678 로 접속하면 n8n 에디터를 사용할 수 있습니다.
N8N_BASIC_AUTH_USER / N8N_BASIC_AUTH_PASSWORD 를 설정해 두면 기본 인증 로그인 화면이 뜹니다. (보안상 권장)

Docker 실행 시 주요 환경변수

n8n은 다양한 환경변수 설정을 지원합니다. 실무에서는 최소한 아래 정도는 지정해두면 좋아요.

1. 기본 보안

-e N8N_BASIC_AUTH_USER=user \
-e N8N_BASIC_AUTH_PASSWORD=pass

관리자 로그인 계정/비밀번호 설정
기본 인증을 켜지 않으면 누구나 접속 가능하므로 꼭 설정 권장

2. 실행 환경(Workflow 저장 위치)

-v ~/.n8n:/home/node/.n8n

워크플로우와 설정을 호스트 볼륨에 저장
--rm 옵션으로 실행하면 컨테이너 종료 시 데이터가 사라지므로, 실제 운영에서는 반드시 볼륨을 마운트해야 합니다.

3. 외부 접속용 설정

-e N8N_HOST=example.com \
-e N8N_PORT=5678 \
-e N8N_PROTOCOL=https

`N8N_HOST`: 서비스 도메인/호스트명
`N8N_PORT`: 포트 (기본 5678)
`N8N_PROTOCOL`: http 또는 https

프록시/리버스 프록시(Nginx, Traefik)와 함께 HTTPS 설정 시 필요합니다.

4. Webhook 관련

-e WEBHOOK_URL=https://example.com/

외부 서비스에서 n8n Webhook Node를 호출할 때 사용할 URL
클라우드 환경이나 도메인 기반 서비스에 필수

5. 실행/큐 모드 (고급)

-e EXECUTIONS_PROCESS=main

`main`: 단일 프로세스 (기본)
`queue`: BullMQ 기반 큐 모드 (여러 워커에서 병렬 실행 가능)
대량 데이터/고성능 환경에서는 queue 모드와 Redis 연동을 사용

6. 실행 이력 보관

-e EXECUTIONS_DATA_SAVE_ON_SUCCESS=none \ -e EXECUTIONS_DATA_SAVE_ON_ERROR=all

성공한 실행은 기록하지 않고, 실패한 실행만 기록하도록 설정
DB 공간 절약에 유용

7. SQLite 대신 Postgres 쓰기(운영/협업 권장)

  -e DB_POSTGRESDB_HOST=localhost \
  -e DB_POSTGRESDB_PORT=5432 \
  -e DB_POSTGRESDB_DATABASE=n8n \
  -e DB_POSTGRESDB_USER=n8n \
  -e DB_POSTGRESDB_PASSWORD=비밀번호 \

기본 DB는 SQLite지만, PostgreSQL을 공식 지원합니다( MySQL/MariaDB는 v1.0에서 deprecated ).
스키마, SSL 등도 환경변수로 세밀하게 설정 가능합니다.
`DB_POSTGRESDB_SCHEMA`(기본 public), `DB_POSTGRESDB_SSL_ENABLED`, ..._CA/CERT/KEY 등.
“기본은 SQLite, Postgres 지원, MySQL/MariaDB deprecated”도 공식 문서에 명시되어 있습니다.
https://docs.n8n.io/hosting/configuration/environment-variables/database/

주요 기능 (실무에서 많이 쓰는 것)

1. Webhook Node → 외부 이벤트 받아서 워크플로우 실행

역할: 외부 서비스가 n8n의 엔드포인트를 호출하면 워크플로우를 시작합니다. 테스트/운영 2개의 URL을 제공하고, 응답 타이밍(즉시/마지막 노드 완료/Respond to Webhook 노드 사용)도 선택 가능.
인증 방식(Basic/Header/JWT)과 CORS, IP 화이트리스트, 바이너리 수신도 지원합니다. 최대 페이로드는 기본 16MB(환경변수 `N8N_PAYLOAD_SIZE_MAX`로 조정)
Tip
- 테스트 중엔 Test URL로 “Listen for Test Event”, 운영 전환 시 Production URL.
- HTML을 응답으로 보낼 때는 n8n이 보안을 위해 <iframe>로 감쌀 수 있어요(1.103.0+)

2. If / Switch / Function(Code) Node — 분기와 가공의 3종 세트

If Node

역할: 단일 조건으로 true/false 두 갈래 분기. v1.0 이후 실행 순서가 바뀌면서(레거시 v0와 다름) If+Merge 조합의 동작이 정리되었습니다(레거시 주의 섹션 참고).
https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.if/
예시(표현식): {{$json.total > 100}}

Switch Node

역할: 여러 케이스로 라우팅(If의 멀티버전). Rules 모드(출력별 규칙) 또는 Expression 모드(인덱스 반환) 지원.
https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.switch/
예시: 상태값이 pending/shipped/cancelled일 때 1·2·3번 출력으로 분기

Function / Code Node

역할: JS/파이썬으로 자유로운 가공. v0.198.0+부터는 Code Node가 Function/Function Item을 대체.
모드: “Run once for all items”(배치 처리) vs “Run once for each item”(아이템별).
외부 모듈: Self-host에선 외부 npm 모듈 사용 가능(설정 필요). Cloud에선 crypto, moment만 제공. 파일시스템/직접 HTTP 접근은 불가(전용 노드 사용). 데이터 구조/아이템 링크 규칙도 문서에 정리돼 있습니다.
https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.code/
자주 쓰는 패턴(JS)

// 모든 입력 아이템을 가져와 가공 후 반환
const items = $input.all();
return items.map(item => ({ json: { ...item.json, ok: true }}));

3. Wait Node → 승인/이벤트/시간까지 “잠시 멈춤

역할: 실행을 DB로 오프로딩하고 조건을 기다린 뒤 재개. 대기 조건은 시간 간격, 특정 시각, 웹훅 호출, 폼 제출 4가지. On Webhook Call에서는 실행마다 고유한 $execution.resumeUrl 이 생성돼 외부에 전달해 재개를 트리거합니다.
65초 미만 대기는 오프로딩 없이 같은 프로세스에서 이어집니다(서버 시간 기준).
https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.wait/
실무 예시:
- “검토 대기” 이메일 발송 → 승인자가 resumeUrl 클릭 시 이어서 진행
- “내일 09:00에 다시 실행” 스케줄링

4. Error Workflow → 실패 시 알림/Slack 연동

역할: 워크플로우 실패 시 Error Trigger 노드가 있는 별도 워크플로우를 실행해 슬랙/메일 알림, 롤백, 재시도 큐 적재 등을 수행. Workflow Settings에서 Error Workflow를 지정하면 됩니다.
https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.errortrigger/
구성 팁: 실패 로그를 Executions에서 열람하고, Error Workflow에서 `{{$json.error.message}}`, `{{$json.workflow.id}}` 같은 정보를 슬랙 메시지에 포함.
https://docs.n8n.io/flow-logic/error-handling/

5. Looping — 대용량/페이지네이션/레이트리밋

기본 철학: 대부분의 노드는 리스트 입력을 자동으로 순회하므로 별도 루프가 필요 없습니다. 그래도 페이지네이션, 레이트 리밋 회피, 특정 예외 노드 처리에는 Loop Over Items(Split in Batches) 노드를 씁니다. Reset 옵션으로 반복 시 입력을 새로 초기화하며 종료 조건(If)과 함께 사용
https://docs.n8n.io/flow-logic/looping
패턴: “다음 페이지가 있으면 If로 루프 계속 → 없으면 종료”, “API 100건씩 배치 전송”

6. Version Control(이력/롤백) — 안전한 변경 관리

Workflow History: Enterprise(Cloud Pro는 제한적)에서 이전 버전 열람/로딩이 가능합니다.
https://docs.n8n.io/release-notes
Git 기반 환경 분리(소스 컨트롤): 엔터프라이즈에서 Git 리포지토리와 연결해 브랜치별 환경(dev/stage/prod)과 Diff 비교를 제공합니다. 권한 요건과 사용법은 문서 참고.
https://docs.n8n.io/source-control-environments/
커뮤니티/셀프호스트 백업 팁: CLI로 워크플로우/자격증명 Export/Import 자동화(예: n8n export:workflow --all). 정기 백업 + Git에 JSON 저장을 추천합니다.
https://docs.n8n.io/hosting/cli-commands

n8n은 단순히 자동화를 넘어, 팀 생산성을 높여주는 오픈소스 플랫폼입니다.
이번 글에서 정리한 기본 개념을 바탕으로, 이후에는 실제 예제와 함께 더 깊이 다뤄보겠습니다.

PostgreSQL 시작하기: Docker 설치부터 DBeaver로 데이터 다루기

누구세연 — Sun, 24 Aug 2025 20:54:20 +0900

PostgreSQL

PostgreSQL이란?

PostgreSQL은 데이터를 안전하게 저장하고 꺼내 쓰게 해주는 데이터베이스(DB)입니다.
하지만 단순히 데이터를 넣고 빼는 수준을 넘어, 복잡한 데이터까지 똑똑하게 다룰 수 있는 고급 데이터베이스라고 볼 수 있습니다.

즉, PostgreSQL은 일반적인 관계형 데이터베이스(RDBMS) 가 가진 기능을 모두 제공하면서도,
그 이상으로 더 다양한 기능과 확장성을 지원합니다.

✅ PostgreSQL의 특징

1. 더 다양한 데이터 타입 지원

일반적인 RDBMS(MySQL 등)는 INT, VARCHAR, DATE 같은 기본 타입 위주로 데이터를 저장합니다.
반면 PostgreSQL은 훨씬 다양한 타입을 기본으로 지원합니다.

JSON / JSONB → JSON 데이터를 효율적으로 저장하고 검색
ARRAY → 배열 형태 데이터 저장 가능
UUID → 고유 식별자 저장용 타입
RANGE → 범위(예: 1~10, 날짜 구간) 타입
HSTORE → Key-Value 형태 데이터 저장

즉, PostgreSQL은 단순한 테이블 구조뿐 아니라, 반정형/비정형 데이터까지 쉽게 다룰 수 있는 장점이 있습니다.

2. 안정성과 신뢰성 (ACID 보장)

PostgreSQL은 트랜잭션 안전성을 엄격히 보장합니다.
은행 이체 같은 작업에서 “중간에 실패하면 자동으로 취소(ROLLBACK)”되는 구조라, 데이터 정합성이 매우 높습니다.

3. 동시성 처리 (MVCC)

여러 사용자가 동시에 데이터를 읽고 쓰는 상황에서도 충돌이 최소화됩니다.
이는 PostgreSQL의 MVCC(Multi-Version Concurrency Control) 덕분인데,
읽는 쿼리는 잠금(Lock) 없이 진행되어 읽기 성능이 뛰어납니다.

MySQL(InnoDB)에서의 MVCC

InnoDB는 Undo Log(Undo 영역) 를 이용해 MVCC를 구현합니다.
즉, 데이터를 수정할 때 원본 값을 Undo 영역에 기록해 두고, 다른 트랜잭션이 과거 데이터를 필요로 하면 Undo Log를 참조합니다.
주요 특징
- 읽기(SELECT) 는 Undo Log를 참조 → REPEATABLE READ 수준에서 동일한 스냅샷 보장
- 쓰기(UPDATE, DELETE) 는 레코드에 잠금(Lock) 을 걸어야 함
- 따라서 읽기와 쓰기는 동시에 가능하지만, 충돌 가능성은 여전히 존재

PostgreSQL에서의 MVCC

PostgreSQL은 각 행(Row)에 버전 정보(xmin/xmax) 를 저장합니다.
데이터를 업데이트하면 → 기존 행을 지우지 않고 새 버전의 행을 추가합니다.
트랜잭션은 자신이 시작한 시점에 유효한 버전만 보게 됩니다.
주요 특징
- Undo 영역이 아니라 테이블 자체에서 버전 관리
- SELECT는 절대 Lock을 걸지 않음 → 읽기 성능이 매우 뛰어남
- 단점: 오래된 버전이 계속 쌓이므로 VACUUM(청소 작업) 필요

4. 고급 SQL 기능

Window 함수: 순위 매기기, 누적 합계, 이동 평균 등
CTE (WITH 구문): 복잡한 쿼리를 보기 좋게 분리
JSON 쿼리: JSON 데이터를 SQL로 직접 검색

덕분에 단순 저장소가 아니라, 데이터 분석·집계까지 PostgreSQL에서 가능해집니다.

PostgreSQL 간단 실습

1️⃣ 환경 준비하기

가장 간단한 방법은 Docker를 이용하는 것입니다.

docker run --name pg-test -e POSTGRES_PASSWORD=pass -p 5432:5432 -d postgres

실행 후, localhost:5432 포트에 PostgreSQL이 실행됩니다.
기본 계정: postgres / 비밀번호: pass

2️⃣ PostgreSQL 접속하기

컨테이너 안에서 바로 psql을 실행해봅니다.

docker exec -it pg-test psql -U postgres

정상 접속되면 아래와 같은 프롬프트가 뜹니다.

3️⃣ 데이터베이스와 사용자 생성

실습을 위해 새로운 DB와 유저를 만들어봅시다.

CREATE DATABASE test_db;
CREATE USER test_user WITH PASSWORD 'testpass';
GRANT ALL PRIVILEGES ON DATABASE test_db TO test_user;

이제 앞으로는 test_user 계정으로 test_db를 사용할 수 있습니다.

4️⃣ 테이블 만들고 CRUD 실습

테이블 생성

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(100) UNIQUE,
    created_at TIMESTAMP DEFAULT NOW()
);

데이터 삽입

INSERT INTO users (name, email) VALUES ('홍길동', 'hong@test.com');
INSERT INTO users (name, email) VALUES ('강감찬', 'kang@test.com');

데이터 조회

SELECT * FROM users;

아래처럼 결과가 나옵니다.

데이터 수정/삭제

UPDATE users SET name = '이순신' WHERE id = 1;
DELETE FROM users WHERE id = 2;

5️⃣ PostgreSQL만의 특징 – JSONB 실습

PostgreSQL은 JSON 데이터를 효율적으로 다룰 수 있는 JSONB 타입을 지원합니다.

CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    details JSONB
);

INSERT INTO products (name, details)
VALUES ('노트북', '{"brand":"Apple","spec":{"cpu":"M1","ram":"16GB"}}');

SELECT name, details->'spec'->>'cpu' AS cpu_spec
FROM products;

결과

6️⃣ 뷰(View) 만들기

자주 쓰는 쿼리를 뷰(View)로 저장할 수 있습니다.

CREATE VIEW recent_users AS
SELECT id, name, email, created_at
FROM users
ORDER BY created_at DESC
LIMIT 5;

SELECT * FROM recent_users;

테이블처럼 recent_users에서 데이터를 조회할 수 있습니다.

7️⃣ 트랜잭션 체험

트랜잭션은 데이터 정합성을 보장하는 핵심 기능입니다.

BEGIN;
UPDATE users SET name = '세종대왕' WHERE id = 1;

-- 취소하고 싶을 때
ROLLBACK;

-- 확정하고 싶을 때
COMMIT;

DBeaver로 PostgreSQL 접속하기

CLI(psql) 환경도 좋지만, GUI 툴을 쓰면 데이터베이스 구조와 데이터를 직관적으로 확인할 수 있습니다.
여기서는 많이 사용하는 무료 툴인 DBeaver를 이용해 PostgreSQL에 연결해보겠습니다.

1️⃣ DBeaver 설치

DBeaver 공식 사이트에서 다운로드 및 설치
Mac, Windows, Linux 모두 지원

2️⃣ 새로운 연결 만들기

1. 상단 메뉴에서 Database > New Database Connection 클릭

2. 데이터베이스 목록에서 PostgreSQL 선택

3. 연결 정보 입력

Host: localhost
Port: 5432
Database: postgres
User: test_user
Password: testpass

“Test Connection” 버튼 클릭 → 성공 메시지가 뜨면 Finish

3️⃣ 데이터 확인하기

좌측 패널에 test_db가 나타납니다. (public 하위에서 확인할 수 있음)

users 테이블을 더블클릭 → Data 탭에서 GUI로 데이터 확인 가능
SQL Editor에서 직접 쿼리를 실행할 수도 있습니다.

4️⃣ JSONB 데이터도 쉽게

앞서 만든 products 테이블도 확인해봅시다.

JSON 컬럼은 DBeaver에서 계층 구조(Tree) 로 확인할 수 있어 가독성이 좋습니다.
PostgreSQL의 장점인 JSONB 쿼리도 GUI에서 실행 가능

마무리

PostgreSQL은 관계형 DB의 안정성 + NoSQL의 유연성을 동시에 제공
Docker로 손쉽게 환경 구성 가능
CRUD, JSONB, View, 트랜잭션 등 기본 기능을 실습하며 특징을 체감할 수 있음
DBeaver 같은 GUI 툴을 이용하면 더욱 편리하게 학습 가능

방화벽 인바운드(Inbound), 아웃바운드(Outbound) 이해하기

누구세연 — Sun, 17 Aug 2025 22:30:56 +0900

방화벽이란?

서비스를 운영하다 보면 항상 고민하게 되는 질문이 하나 있습니다.
"우리 서버는 외부 공격으로부터 안전할까?"

이 질문에 가장 기본적이면서도 강력한 답을 주는 것이 바로 방화벽(Firewall)입니다.

방화벽은 네트워크의 문지기 역할을 하며, 외부에서 들어오는 트래픽과 내부에서 나가는 트래픽을 감시하고 필터링합니다.

쉽게 말해, 방화벽은 “네트워크의 문지기”입니다.
어떤 손님(트래픽)을 들이고, 어떤 손님은 돌려보낼지를 규칙(Rule)에 따라 결정됩니다!

인바운드(Inbound) vs 아웃바운드(Outbound)

두 방화벽 규칙은 트래픽이 오가는 방향을 기준으로 두 가지로 나뉩니다.

구분	방향	예시	비유
인바운드	외부 → 내부	사용자가 서버 웹페이지 접속, SSH 접속 요청	집 문을 두드리는 손님
아웃바운드	내부 → 외부	서버에서 외부 API 호출, 업데이트 다운로드	내가 집 밖으로 나가는 상황

인바운드(Inbound)

외부 사용자가 내 서버/PC로 접속하려고 할 때 발생
예: 웹서버에 HTTP(80번 포트) 요청, SSH(22번 포트) 접속 시도
보안 포인트: 꼭 필요한 포트만 허용, 나머지는 차단
인바운드(Inbound) 예시
- 클라이언트가 브라우저에서 `https://example.com` 접속
  → 443 포트로 서버에 요청 (인바운드 트래픽)
- 외부 개발자가 SSH로 원격 접속 시도 (`22번 포트` 사용)

아웃바운드(Outbound)

내가 외부 서버에 요청을 보낼 때 발생
예: 서버에서 외부 API 호출, 패키지 업데이트 다운로드
보안 포인트: 악성코드·랜섬웨어가 외부로 데이터를 빼돌리지 않도록 제한 가능
아웃바운드(Outbound) 예시
- 백엔드 서버가 외부 날씨 API(`api.weather.com`)로 요청 보냄
- 서버가 npm install이나 apt update로 패키지를 내려받음

네트워크 흐름 예시

[외부 사용자] --(인바운드)--> [내부 서버]
[내부 서버] --(아웃바운드)--> [외부 API 서버]

인바운드 규칙: 외부에서 내 서버로 들어오는 요청을 필터링
아웃바운드 규칙: 내 서버에서 외부로 나가는 요청을 필터링

실무에서 자주 겪는 방화벽 이슈

인바운드 포트 차단 → 외부에서 서버 접근 불가
아웃바운드 차단 → 서버에서 외부 API 호출 실패
SSH 포트를 전체 IP에 열어둠 → 보안 취약점 발생
방화벽 설정 실수로 실서버 트래픽 끊김 → 장애 발생

방화벽 설정 시 꼭 기억할 점

1. 기본은 차단, 필요한 것만 허용
   - 보안의 기본 원칙은 "Deny All, Allow Some"
   - 예: HTTP(80), HTTPS(443), SSH(22)만 열고 나머지는 닫기

2. 인바운드는 최대한 좁게 열기
   - 외부에서 접근 가능한 포트는 해커 입장에선 진입 지점
   - 웹서버라면 80, 443만 허용

3. 아웃바운드도 통제가 필요함
   - 보통은 다 열어두지만, 이 경로로 데이터 유출이 가능
   - 기업 보안에선 아웃바운드도 허용 목록 기반 관리함

4. UDP보다 TCP가 일반적으로 더 안전
   - TCP는 연결 기반이라 추적·제어가 쉬움
   - DNS 같은 UDP 트래픽은 따로 주의 필요

방화벽은 단순히 외부 트래픽을 막는 게 아니라, 서비스의 생명줄을 지키는 중요한 보안 도구입니다.
무조건 막는 것도, 무조건 여는 것도 위험합니다.
반드시 필요한 포트만 허용하고, 변경 시에는 이중 체크가 필요합니다.
네트워크 문제 발생 시, 방화벽 설정을 의심해 보는 습관을 들이면 디버깅 속도가 훨씬 빨라질 수 있습니다.

MapStruct와 ObjectMapper, 언제 어떤 걸 써야 할까?

누구세연 — Wed, 23 Jul 2025 22:29:02 +0900

DTO ↔ Entity 변환, 여러분은 어떻게 처리하고 계신가요?

많은 개발자들이 처음에는 직접 생성자나 Builder를 사용해서 매핑합니다.
필드가 몇 개 없을 때는 괜찮지만, 점점 DTO/Entity 구조가 복잡해지고, 중복 코드가 많아지면서 유지보수가 어려워지는 것 같습니다.

이럴 때 보통 두 가지 대안이 있습니다.

ObjectMapper: 빠르고 간편하게 쓸 수 있는 JSON 매핑 도구
MapStruct: 컴파일 타임에 타입 안전하게 매핑 코드를 생성해 주는 프레임워크

이번 글에서는 두 방식의 차이점과 실무에서 어떤 상황에 어떤 방식을 선택하는 것이 좋은지 정리해 보겠습니다.

ObjectMapper란?

ObjectMapper는 Jackson 라이브러리에서 제공하는 객체-JSON 변환 도구입니다.
(사실 JSON 직렬화/역직렬화가 주목적이지만, 내부적으로 필드 기반 매핑도 지원해요.)

ObjectMapper objectMapper = new ObjectMapper();
UserDto dto = objectMapper.convertValue(userEntity, UserDto.class);

✅ 장점

개발이 빠름 (코드 1줄로 매핑 가능)
유연한 타입 변환 지원 (JSON과 궁합이 좋음)

❌ 단점

리플렉션 기반이라 성능이 느림
런타임 오류 발생 가능 (컴파일 타임에 안전하지 않음)
필드명이 다르면 동작 안 하거나 에러

MapStruct란?

MapStruct는 Java Annotation 기반의 정적 매핑 코드 생성기입니다.
런타임이 아니라 컴파일 타임에 매핑 코드를 만들어주는 게 핵심입니다.

@Mapper(componentModel = "spring")
public interface UserMapper {
    UserDto toDto(User user);
    User toEntity(UserDto dto);
}

→ 위처럼 인터페이스만 정의하면,
UserMapperImpl 클래스가 자동으로 생성됩니다.

✅ 장점

빠른 성능 (리플렉션 없음)
타입 안정성 보장 (컴파일 에러로 알려줌)
코드 자동 생성, 유지보수 쉬움

❌ 단점

복잡한 매핑은 추가 설정 필요 (@Mapping, custom method 등)
사용 초기 진입장벽이 약간 있음 (라이브러리 설정, Gradle, lombok 등)

성능 비교 – 실제 코드 예시로 보기

다음은 UserDto ↔ User 간 변환을 100만 번 반복하여 실행 시간을 측정한 코드입니다.

1️⃣ 테스트 대상 클래스

User class

UserDto class

2️⃣ MapStruct 매퍼 정의

UserMapper class

3️⃣ 성능 측정 테스트 코드

Test class

⏱️ 결과

console log

리플렉션을 사용하는 ObjectMapper는 상대적으로 느리고, MapStruct는 단순 메서드 호출 수준이기 때문에 훨씬 빠릅니다.

실시간 트래픽이 많은 시스템이나 대용량 데이터 처리 시에는 MapStruct가 유리합니다.

언제 어떤 걸 써야 할까?

상황	추천 방식	이유
개발 초기, 필드 적음	수동 Builder	빠르고 직관적
빠르게 프로토타이핑	ObjectMapper	코드 1~2줄로 끝
성능/안정성 중요	MapStruct	정적 코드, 빠름
필드명이 다름	MapStruct (@Mapping)	명시적 매핑 가능
커스텀 로직 포함	MapStruct + default method	로직 분리 깔끔
JSON ↔ 객체 변환	ObjectMapper	원래 목적에 딱 맞음

실무에서는 대부분 아래와 같은 흐름을 거칩니다.
Builder로 수동 매핑 → 코드 많아짐 → ObjectMapper 써봄 → 성능 이슈 발생 → MapStruct 도입!

복잡한 매핑이 많아질수록, 그리고 성능이 중요할수록 MapStruct를 일찍 도입하는 게 장기적으로 이득이에요.
ObjectMapper는 여전히 JSON 변환이나 간단한 DTO 테스트용으로는 아주 훌륭합니다.
핵심은 “상황에 맞는 도구를 쓰는 것”이라는 점을 기억하면 좋을 것 같습니다!

https://mapstruct.org/

MapStruct – Java bean mappings, the easy way!

MapStruct Spring Extensions 1.1.3 released March 14, 2025 It is my pleasure to announce the next official release of MapStruct Spring Extensions. What started out as a StackOverflow question turned into its own (sub-)project within the MapStruct organizati

mapstruct.org

https://github.com/FasterXML/jackson

GitHub - FasterXML/jackson: Main Portal page for the Jackson project

Main Portal page for the Jackson project. Contribute to FasterXML/jackson development by creating an account on GitHub.

github.com

sy_develop_note

REST vs gRPC, MSA에서 어떻게 고를까?

REST vs gRPC 한눈에 비교

REST와 gRPC의 근본적인 차이: RPC 관점에서 보기

API 설계 방식의 차이

REST: 리소스를 기준으로 설계하기

gRPC: 동작(메서드)을 기준으로 설계하기

설계할 때 고민 포인트

같은 기능을 REST와 gRPC로 표현하면

설계 관점에서의 정리

성능과 스트리밍에서의 차이

REST와 gRPC의 성능 차이는 어디서 나올까?

호출이 많아질수록 체감되는 차이

스트리밍 방식의 차이

운영 / 디버깅 / 현실적인 제약

MSA에서의 혼합 운용 패턴

정리 및 선택 기준

어떤 메시지 큐를 선택할까? (Kafka · RabbitMQ · Redis)

먼저 선택표부터

선택을 결정짓는 4가지 질문

용어만 정리..!

큐별로 뭐가 다를까?

Kafka (이벤트 스트리밍)

Kafka 아키텍처 개요

Topic/Partition/Consumer Group 동작

Offset으로 재생·재처리

RabbitMQ (메시지 브로커)

RabbitMQ 라우팅 개요

Redis Queue/Streams (인메모리 큐)

Redis Streams: Consumer Group 처리

Redis Pub/Sub: 실시간 브로드캐스트

Redis List Queue: 단순 FIFO

큐별 동작 원리 요약

패턴별 추천

애매한 HTTP Method, PATCH 메서드

PATCH가 애매한 이유

PUT vs PATCH

PATCH 표현 방식 두 가지

1) JSON Merge Patch (application/merge-patch+json)

2) JSON Patch (application/json-patch+json)

주로 사용하게 된 Merge Patch

언제 JSON Patch를 고려할까?

프록시 DB란? 읽기·쓰기 분리

프록시 DB란 무엇일까?

어떻게 동작할까?

왜 도입할까?

⚠️ 도입 전에 생각할 것

운영 중 자주 맞닥뜨리는 이슈

1) 복제 지연(Replication Lag)

2) 스키마 불일치(DDL 타이밍)

3) Failover(장애 전환) 복잡성

4) ⚙️ 트랜잭션 스티키니스

5) 관측과 모니터링

‍ 개발자 입장에서의 사용 패턴

️ 패턴 A — 프록시가 모든 라우팅 담당

️ 패턴 B — 애플리케이션이 R/W 의도 명시

✍️ 마무리 & 체크리스트

nGrinder로 시작하는 부하 테스트 가이드

nGrinder란?

nGrinder 구조

설치 및 환경 구성

1️⃣ 사전 준비

2️⃣ Controller 설치

3️⃣ Agent 설치

첫 테스트 실행 (Hello nGrinder)

1️⃣ 로그인 및 기본 화면 살펴보기

하단 영역

2️⃣ 샘플 스크립트 생성

3️⃣ 테스트 설정

4️⃣ 테스트 실행 및 모니터링

5️⃣ 결과 리포트 확인

6️⃣ 테스트 결과 해석 팁

Apache JMeter: 설치부터 부하 테스트까지

JMeter란?

주요 특징

JMeter 설치 & 실행

부하 테스트 시나리오 만들기

Thread Group(스레드 그룹) 추가

HTTP Request(요청) 샘플러 추가

Listener(리스너) 추가 – 결과 확인용

1) JSON Merge Patch (`application/merge-patch+json`)

2) JSON Patch (`application/json-patch+json`)