look-forest

기본적인 마이크로서비스 구축해보기

studyHub — Mon, 16 Mar 2026 23:02:59 +0900

기본적인 마이크로서비스 구축

프로젝트 아키텍처

마이크로서비스마다 각각 다른 프레임워크(ex. Nest.js, Django), 각각 다른 DB(ex. MongoDB, PostgreSQL 등)를 써도 된다.

실무에서 쓸 MSA를 구축하려면 각 Service와 DB를 전부 독립적인 서버에 실행시켜야 한다.

하지만 프로젝트의 심플함을 위해 로컬 컴퓨터 한 대에서 포트 번호만 다르게 해서 실행시킬 것이다

DB설계

[모놀리식 아키텍처]

모놀리식 아키텍처에서는 위 그림과 같이 user_id를 참조한 채로 DB를 설계하게 된다.

[마이크로서비스 아키텍처]

하지만 마이크로서비스에서는 DB가 독립적으로 분리되어 있기 때문에 user_id를 참조할 수 없다.

하지만 특정 게시글이 어떤 사용자의 게시글인지 파악하기 위해 user_id에 대한 정보는 있어야 한다.

따라서 boards 테이블에서 user_id는 FK를 설정하지 않은 채로 컬럼을 생성하면 된다.

MSA에서는 DB를 독립적으로 분리시켜야하기 때문에 FK를 설정하지 않는 경우가 많다

참고 자료 & 이미지 출처
비전공자도 이해할 수 있는 MSA 입문/실전

MSA 기본 개념

studyHub — Fri, 13 Mar 2026 23:27:29 +0900

MSA(Microservice Architecture)란?

하나의 큰 애플리케이션을 여러 개의 작고 독립적인 서비스로 나누어 개발하고 배포하는 소프트웨어 개발 아키텍처.

프로젝트 하나에 모든 API(결제 관련 API, 인증 관련 API, 상품 관련 API)를 전부 구현하는 모놀리식 아키텍처 방식과 비교해보자.

이에 반해, 마이크로서비스 아키텍처(MSA)는 서비스에 필요한 API들을 하나의 프로젝트가 아닌 여러 개의 프로젝트로 나눠서 구현하는 방식이다. 아래 그림을 보면 결제 관련 API들끼리 모아놓은 프로젝트와, 인증 관련 API들끼리 모아놓은 프로젝트와, 상품 관련 API들끼리 모아놓은 프로젝트를 분리해서 구성했다. 그리고 MSA에서는 독립적으로 분리된 하나의 프로젝트를 서비스(service)라고 부른다.

보통 DB를 서비스마다 분리해서 쓴다.

MSA가 도대체 어떤 특징과 장점을 갖고 있길래 많은 회사에서 MSA를 도입하는 걸까?

MSA의 핵심 특징과 장점

MSA의 핵심적인 특징은 독립성이다. 각 기능을 독립적으로 분리해서 프로젝트를 구성함으로써, 다양한 장점이 생기게 된다.

1. 서비스 별 독립적인 배포 → 배포 사이클이 빨라짐

하나의 큰 프로젝트를 100명이 작업하는 것보다, 여러 개의 프로젝트로 나눠서 각 프로젝트를 관리하는 팀을 구성해 독립적으로 작업하는 게 훨씬 효율적이다. 그 이유는 다음과 같다.

서로 의사소통할 인원이 적기 때문에 프로젝트 진행이 빠르다.
팀이 독립적으로 개발/배포를 진행할 수 있다.
코드의 양이 비교적 작기 때문에 코드 작성, 테스트, 빌드 과정의 시간이 훨씬 적게 걸린다.

2. 데이터베이스의 독립적인 분리 → 대규모 트래픽 처리 용이

모놀리식 아키텍처에서는 단일 데이터베이스를 활용하는 구조를 많이 채택한다. 하지만 AWS의 단일 데이터베이스의 가장 좋은 성능의 데이터베이스로 셋팅을 한다고 하더라도 트래픽이 감당이 안 되는 순간이 온다.
읽기 전용 데이터베이스를 추가하거나 캐시를 활용해 트래픽을 줄이려는 시도를 하지만, 이런 셋팅을 다 해도 트래픽을 감당 못할 때가 있다. 이런 경우에 MSA 구조를 활용해 각 서비스 별로 데이터베이스를 따로따로 둠으로써 대규모 트래픽을 감당하기도 한다.

3. 서비스를 독립적으로 분리 → 장애 전파를 최소화

모놀리식 서비스에서는 단일 데이터베이스를 사용하고 있기 때문에, 결제 API로 인해 데이터베이스에 장애가 나면 결제와 관련되지 않은 다른 기능들도 100% 같이 장애가 난다.

반면, MSA 구조에서는 각 서비스 별로 데이터베이스도 독립적으로 분리해서 구축하기 때문에, 결제 서비스가 장애가 나더라도 다른 서비스에는 영향을 덜 끼친다.

언제 MSA를 도입하는게 적절할까?

글로벌 기업들의 사례를 보면 크게 3가지 이유 때문에 MSA로 전환을 했다.

신속한 배포
대규모 트래픽를 안정적으로 처리
시스템 안정성 확보

이는 MSA의 핵심적인 장점 3가지와 완전 일치한다.

따라서 모놀리식 아키텍처로 프로젝트를 관리하고 운영하면서 다음과 같은 문제를 만날 때 MSA 전환을 고민하면 된다.

프로젝트 규모가 크거나 또는 개발자 인원이 너무 많아서 배포 사이클이 느려진 경우
모놀리식 아키텍처에서는 도저히 감당할 수 없는 트래픽이 발생하는 경우
모놀리식 아키텍처로 인한 장애 전파의 횟수가 잦거나, 한 번의 장애 전파도 서비스에 치명적인 경우

MSA로 전환하는데는 모놀리식 구조보다 훨씬 복잡하고 많은 시간과 비용이 드므로, 득실을 신중히 따져야 한다.

MSA인지 아닌지 판단하는 기준

MSA인지 아닌지를 판단할 때 핵심 개념은 ‘독립성’이다.

많은 기업들이 MSA로 전환하는 이유는 독립성으로 인해 생기는 장점들 때문이다. 따라서 독립성을 적용시켰냐 여부가 MSA를 판단하는 데 중요한 기준점이 된다.

MSA에서 얘기하는 ‘독립성’

1. 각 서비스를 독립적으로 개발 및 배포 가능해야 한다.

각 서비스를 독립적으로 개발 및 배포가 가능해야만, MSA의 핵심적인 장점(’배포 사이클이 빠르다’)을 취할 수 있게 된다.

2. 서비스 간 API 통신 및 DB 분리

서비스는 간에는 API로만 통신해야 한다. 가령, 다른 서비스의 DB에 직접적으로 접근해서 데이터를 가져오면 안 된다.

그래야 API를 제외한 다른 부분에서 의존성이 안 생겨서 독립적인 개발/배포가 원할하게 가능해지고,

DB를 별도로 분리해서 써야 DB 장애로 인한 장애 전파를 예방할 수 있다.

참고 자료 & 이미지 출처
비전공자도 이해할 수 있는 MSA 입문/실전

DB 연동 메시지큐의 트랜잭션 처리(작성중)

studyHub — Fri, 13 Mar 2026 22:49:18 +0900

DB 연동 메시지큐의 트랜잭션 처리 개요

DB 연동 메시지큐의 트랜잭션 처리 실습

Publisher-confirms을 이용한 트랜잭션 처리

트랜잭션 처리의 확장 - TCC의 이해

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

Dead Letter Queue 재처리와 Retry

studyHub — Fri, 13 Mar 2026 22:47:19 +0900

Dead Letter Queue와 Dead Letter Exchange

DLQ (Dead Letter Queue)

실패한 메시지가 저장되는 큐. 메시지가 큐에서 제대로 처리 되지 못할 경우 DLQ로 이동됨.

DLQ로 이동하는 경우

NACK 처리나 거부: basic.reject 혹은 basic.nack
TTL 만료
Overflow: 큐에 설정된 최대 메시지 갯수를 초과하면 가장 오래된 메시지가 삭제되고 DLQ로 이동

DLX (Dead Letter Exchange)

실패한 메시지를 어디로 보낼지 라우팅하는 Exchange.

DLQ로 바로 보내는 것이 아니라 RabbitMQ는 Exchange를 통해 라우팅한다.

전체 구조

Producer
↓
Exchange
↓
OrderQueue
↓ (reject / nack / ttl)
DeadLetterExchange
↓
DeadLetterQueue

Dead Letter Queue를 활용한 실패 메시지 재처리

1. DLQ와 DLX 빈 선언

@Configuration
public class RabbitMQConfig {
	public static final String ORDER_COMPLETED_QUEUE = "order_completed_queue";
	public static final String ORDER_EXCHANGE = "order_completed_exchange";
	public static final String DLQ = "deadLetterQueue";
	public static final String DLX = "deadLetterExchange";

	@Bean
	public TopicExchange orderExchange() {
		return new TopicExchange(ORDER_EXCHANGE);
	}

	@Bean
	public TopicExchange deadLetterExchange() {
		return new TopicExchange(DLX);
	}

	// 메시지가 처리되지 못했을 경우 자동으로 Dead Letter Queue로 이동하도록 설정
	@Bean
	public Queue orderqueue() {
		// return new Queue(ORDER_COMPLETED_QUEUE, false);
		return QueueBuilder.durable(ORDER_COMPLETED_QUEUE)
			.withArgument("x-dead-letter-exchange", DLX) // Dead Letter Exchange 설정
			.withArgument("x-dead-letter-routing-key", DLQ) // Dead Letter Routing Key 설정
			.ttl(5000)
			.build();
	}

	@Bean
	public Queue deadLetterQueue() {
		return new Queue(DLQ);
	}

	@Bean
	public Binding orderComplededBinding() {
		return BindingBuilder.bind(orderqueue()).to(orderExchange()).with("order.completed.#"); //bindingKey를 넣는건데, Spring API에서는 routingKey 파라미터
	}
	// Binding도 routing key를 기준으로 정의되기 때문에, AMQP에는 “binding key”라는 독립된 개념이 없다.
	//우리가 흔히 말하는 “binding key”는 AMQP 공식 용어라기보다는 설명 편의를 위한 표현에 가깝다.


	@Bean
	public Binding deadLetterBinding() {
		return BindingBuilder.bind(deadLetterQueue()).to(deadLetterExchange()).with(DLQ);
	}
}

2. Ack/Nack 처리를 개발 시점에 직접 핸들링 하도록 설정

SimpleRabbitListenerContainerFactory를 이용하여 AcknowledgeMode 모드를 Manual로 설정.

AcknowledgeMode.MANUAL을 통해 메시지의 처리 결과를 RabbitMQ에 명시적으로 전달하고
basicAck , basicNack , basicReject 를 사용하여 메시지 재시도 및 DLQ 처리를 유연하게 구현할 수 있다.

/**
 * RabbitMQ 설정을 수동으로 하는 클래스
 */
@EnableRabbit //RabbitMQ 리스너(@RabbitListener)을 스캔하여 동작하게 만드는 활성화 어노테이션(스프링부트는 자동)
@Configuration
public class RabbitMQManualConfig {
	@Bean
	public SimpleRabbitListenerContainerFactory rabbitListenerContainerFactory(ConnectionFactory connectionFactory) {
		SimpleRabbitListenerContainerFactory factory = new SimpleRabbitListenerContainerFactory();
		factory.setConnectionFactory(connectionFactory);
		factory.setAcknowledgeMode(AcknowledgeMode.MANUAL);
		return factory;
	}
}

3. Producer 메시지 발행

@Component
@RequiredArgsConstructor
public class OrderProducer {

	private final RabbitTemplate rabbitTemplate;

	public void sendShipping(String message) {
		rabbitTemplate.convertAndSend(
			RabbitMQConfig.ORDER_EXCHANGE,
			"order.completed.shipping",
			message);
		System.out.println("[주문 완료. 배송 지시 메시지 생성 : " + message + "]");
	}
}

4. Consumer 에서 메시지 실패 건에 대해 3번의 재시도 후 DLQ 이동

@Component
public class OrderConsumer {

	private static final int MAX_RETRIES = 3; // 최대 재시도 횟수
	private int retryCount = 0; // 현재 재시도 횟수

	// containerFactory: 리스너 컨테이너의 설정(ACK 모드, 재시도, prefetch, concurrency 등)을 바꾸기 위해 지정
	// @Header("amqp_deliveryTag"): RabbitMQ가 메시지에 붙여주는 전달 식별자(ack/nack/reject에 필요)를 Spring이 꺼내서 주입해주는 것
	// Channel: RabbitMQ Java Client의 현재 연결/채널(프로토콜 세션) 객체로, basicAck/basicNack/basicReject 같은 저수준 AMQP 명령을 보내는 통로
	@RabbitListener(queues = RabbitMQConfig.ORDER_COMPLETED_QUEUE, containerFactory = "rabbitListenerContainerFactory")
	public void processOrder(String message, Channel channel, @Header("amqp_deliveryTag") long tag) {
		try {
			// 실패 유발
			if ("fail".equalsIgnoreCase(message)) {
				if (retryCount < MAX_RETRIES) {
					System.err.println("#### Fail & Retry: " + message + " (Retry Count: " + retryCount + ")");
					retryCount++;
					throw new RuntimeException(message);
				} else {
					System.err.println("#### 최대 횟수 초과, DLQ로 이동 시킴");
					retryCount = 0;
					// deliveryTag: 메시지 고유식별 태그, multiple: true면 deliveryTag 이하 메시지 전부, requeue: true면 다시 큐로, false면 DLQ or drop
					channel.basicNack(tag, false, false); // 메시지 거부, 재큐잉하지 않음 (DLQ로 이동)
					return;
				}
			}
			// 성공 처리
			System.out.println("# 성공: " + message);
			channel.basicAck(tag, false); // 메시지 수동 ACK
			retryCount = 0;
		} catch (Exception e) {
			System.err.println("# error 발생 : " + e.getMessage());
			try {
				// 실패 시 basicReject를 사용하여 메시지를 재처리 전송
				channel.basicReject(tag, true); //basicReject는 단일 메시지 거부 전용 (간단 버전), basicNack은 확장형 거부 (여러 메시지 가능)
			} catch (IOException ex) {
				System.err.println("# fail & reject message : " + ex.getMessage());
			}
		}
	}
}

5. DLQ 컨슈머에서 메시지 수정하여 큐잉

@Component
@RequiredArgsConstructor
public class OrderDLQConsumer {

	private final RabbitTemplate rabbitTemplate;

	@RabbitListener(queues = RabbitMQConfig.DLQ)
	public void process(String message) {
		System.out.println("DLQ Message Received: " + message);

		try {
			String fixedMessage = "success";

			rabbitTemplate.convertAndSend(RabbitMQConfig.ORDER_EXCHANGE,
				"order.completed.shipping",
				fixedMessage
			);
			System.out.println("DLQ Message Sent: " + fixedMessage);
		} catch (Exception e) {
			System.err.println("### [DLQ Consumer Error] " + e.getMessage());
		}
	}
}

channel.basicReject(deliveryTag, requeue);

channel.basicNack(deliveryTag, multiple, requeue); // DLQ로 메시지 이동

위와 같은 설정은 처리가 다소 복잡하고, 메서드 호출도 혼동되기 쉬우므로 이런 처리보다는

Spring AMQP에서 제공하는 RetryTemplate을 통해 좀더 명확하고 간단하게 기능을 구현할 수 있다.

[발전1] RetryTemplate을 통한 간편한 재처리 설정

Spring AMQP는 RetryTemplate 을 통해 재시도 로직을 지원한다.

이 경우 Spring AMQP에서 AcknowledgeMode가 AUTO로 기본 세팅되어 있기 때문에 별도의 SimpleRabbitListenerContainerFactory를 통하지 않고 자동으로 Ack/Nack 처리가 가능하다.

재시도 중 메시지가 성공적으로 처리되면 Spring AMQP가 자동으로 Ack를 전송
모든 재시도가 실패하면 Nack를 보내고 RabbitMQ가 메시지를 DLQ로 이동

※ build.gradle 에 retry dependency 추가 필요

RetryConfig 클래스에서 기본 설정 세팅하여 빈으로 선언

@Configuration
public class RetryConfig {

	@Bean
	public RetryTemplate retryTemplate() {
		RetryTemplate retryTemplate = new RetryTemplate();
		// 재시도 정책 설정
		SimpleRetryPolicy retryPolicy = new SimpleRetryPolicy();
		retryPolicy.setMaxAttempts(3); // 최대 재시도 횟수 설정
		// 백오프 정책 설정
		FixedBackOffPolicy backOffPolicy = new FixedBackOffPolicy();
		backOffPolicy.setBackOffPeriod(1000L); // 재시도 간격 설정 (1초)
		retryTemplate.setRetryPolicy(retryPolicy);
		retryTemplate.setBackOffPolicy(backOffPolicy);

		return retryTemplate;
	}
}

Consumer에서 retryTemplate으로 재시도 및 DLQ 이관

retryTemplate의 retryCount를 확인하여 세번 이하라면 throw e를 던짐으로써 (channel.basicReject(tag, true)) , RetryTemplate이 예외를 감지해서 BackOffPolicy에 따라 1초 후 네번까지 재실행(동일한 로직 실행)

@Component
@RequiredArgsConstructor
public class OrderConsumer {

	private final RabbitTemplate rabbitTemplate;
	private final RetryTemplate retryTemplate;

	@RabbitListener(queues = RabbitMQConfig.ORDER_COMPLETED_QUEUE)
	public void consume(String message) {
		retryTemplate.execute(context -> {
			try {
				System.out.println("# 리시브 메시지: " + message + " | 시도 횟수: " + (context.getRetryCount() + 1));

				if ("fail".equals(message)) {
					throw new RuntimeException(message);
				}
				System.out.println("# 메시지 처리 성공: " + message);
			} catch (Exception e) {
				if (context.getRetryCount() + 1 >= 3) {
					rabbitTemplate.convertAndSend(
						RabbitMQConfig.ORDER_TOPIC_DLX,
						RabbitMQConfig.DEAD_LETTER_ROUTING_KEY,
						message);
				} else {
					throw e; // RetryTemplate이 재시도를 수행하도록 예외를 다시 던짐
				}
			}
			return null;
		});
	}
}

ACK/NACK를 수동으로 던질 필요가 없어 훨씬 깔끔하다!

[발전2] Application.yml 설정을 통한 RetryTemplate 속성 정의

application.yml 에 rabbitmq listener retry 설정 추가

spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: guestuser
    password: guestuser
    listener:
      simple:
        retry:
          enabled: true # 재시도 활성화
          initial-interval: 1000 # 첫 재시도 간격 1초
          max-attempts: 3 # 최대 재시도 횟수
          max-interval: 10000 # 최대 재시도 간격 10초
        default-requeue-rejected: false # 재시도 실패 시 자동으로 DLQ로 이동

Consumer 로직 변경

대부분의 설정을 xml에 해두었기 때문에, execption만 던지면 retry 한다. 설정 횟수를 넘으면 DLQ로 간다.

@Component
public class OrderConsumer {
	private int retryCount;

	@RabbitListener(queues = RabbitMQConfig.ORDER_COMPLETED_QUEUE)
	public void consume(String message) {
		System.out.println("Received message: " + message + "count: " + retryCount++);
		if ("fail".equals(message)) {
			throw new RuntimeException("Processing failed. Retry: " + message);
		}
		System.out.println("Message processed successfully: " + message);
	}
}

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

Routing Model을 이용한 Log 수집

studyHub — Sun, 22 Feb 2026 21:16:46 +0900

Routing 모델

메시지를 Routing Key에 따라 특정 큐에 전달하는 기능.

Direct Exchange와 Topic Exchange 모두에서 사용 가능.

특징	Direct Exchange	Topic Exchange
라우팅 키 매칭 방식	정확히 일치	패턴 기반 (*, # 지원)
특징	매칭에 제한이 있음	매우 유연(다양한 패턴 매칭)
사용 사례	단순 명확한 목적의 라우팅	복잡하고 동적인 라우팅

Topic 의 경우 패턴 매칭 기반 라우팅으로 binding key와 매칭되는 메시지만 수신
- * : 한 단어에 해당하는 모든 단어 수신
- # : 0개 이상의 단어 (와일드 카드)

주요 특징

고성능
- 메시지를 필요한 곳에만 전달하기 때문에, 네트워크 부하 감소 효과가 있고 브로드캐스팅보다 자원 효율적 사용
라우팅 키 기반의 메시지 분배
- 각 큐는 하나 이상의 라우팅 키와 매칭
  (Direct Exchange의 경우 라우팅 키가 정확히 일치해야 해서 1:1 로 동작한다고 알고 있는데,
  동일한 라우팅 키로 여러 큐에 바인딩 할 수 있으므로 1:N으로 동작)
- Fanout 방식과 달리, 메시지가 특정 큐로만 전달됨
바인딩 설정
- Exchange와 큐 사이의 관계를 바인딩 키(binding key)를 통해 매핑하여 메시지가 전달
- 라우팅 키와 바인딩 키가 일치 하지 않을 경우 메시지가 전달이 안됨
- 다수의 큐와 라우팅을 관리할 경우 복잡성이 늘어남

메시지 흐름

Producer가 메시지와 함께 라우팅 키를 설정해 Exchange로 전송
Exchange는 바인딩 키를 확인하고, 해당 키와 매칭되는 큐로 메시지를 전달
Consumer는 해당 큐에서 메시지를 소비

Routing 모델의 활용 사례

로그 수집
- 각각 log.* 나 *.error으로 끝나는 모든 에러
주문 상태 전이 (주문 완료시 order.completed 를 키로 배송 지시, 재고 차감 지시, 이메일 마케팅 전송 큐 등에 분배)
- 주문의 완료(order.completed) 이후 배송지시(order.completed.shipped), 재고 차감(order.completed.inventory),
  마케팅 이메일 발송(order.completed.email) 등의 큐 전달
채팅의 방 개설 단위로 분류하여 메시지 전달
- chat.room1, chat.room2,,

Routing Model을 이용한 Log 수집

구현 기능

Exception이 발생했을 때, 해당 메시지를 송/수신하는 로직으로 메시지를 routing
에러 로그별 매칭되는 큐로 전달도 가능

로그를 수집하는 Routing 모델 예제 (using DirectExchange)

RabbitMQConfig

3개의 Queue Bean 선언(Error, Warn, Info), 3개의 Binding Bean 선언 (to DirectExchage)

@Configuration
public class RabbitMQConfig {
	public static final String ERROR_QUEUE = "error_queue";
	public static final String WARN_QUEUE = "warn_queue";
	public static final String INFO_QUEUE = "info_queue";

	public static final String DIRECT_EXCHANGE = "direct_exchange";

	@Bean
	public DirectExchange directExchange() {
		return new DirectExchange(DIRECT_EXCHANGE);
	}

	@Bean
	public Queue errorQueue() {
		return new Queue(ERROR_QUEUE, false);
	}

	@Bean
	public Queue warnQueue() {
		return new Queue(WARN_QUEUE, false);
	}

	@Bean
	public Queue infoQueue() {
		return new Queue(INFO_QUEUE, false);
	}

	@Bean
	public Binding errorBinding() {
		return BindingBuilder.bind(errorQueue()).to(directExchange()).with("error");
	}

	@Bean
	public Binding warnBinding() {
		return BindingBuilder.bind(warnQueue()).to(directExchange()).with("warn");
	}

	@Bean
	public Binding infoBinding() {
		return BindingBuilder.bind(infoQueue()).to(directExchange()).with("info");
	}
}

LogConsumer

@Component
public class LogConsumer {

	@RabbitListener(queues = RabbitMQConfig.ERROR_QUEUE)
	public void consumeError(String message) {
		System.out.println("[ERROR]를 받음 : " + message);
	}

	@RabbitListener(queues = RabbitMQConfig.WARN_QUEUE)
	public void consumeWarn(String message) {
		System.out.println("[WARN]를 받음 : " + message);
	}

	@RabbitListener(queues = RabbitMQConfig.INFO_QUEUE)
	public void consumeInfo(String message) {
		System.out.println("[INFO]를 받음 : " + message);
	}
}

LogPublisher

Exchange에 라우팅 키와 함께 메시지 전송

@Component
@RequiredArgsConstructor
public class LogPublisher {

	private final RabbitTemplate rabbitTemplate;

	public void publish(String routingKey, String message) {
		rabbitTemplate.convertAndSend(RabbitMQConfig.DIRECT_EXCHANGE, routingKey, message);
		System.out.println("[#] message published: " + routingKey + ":" + message);
	}
}

Exception 처리 로직(CustomExsceptionHandler → LogPublisher로 전송)

@Component
@RequiredArgsConstructor
public class CustomExceptionHandler {

	private final LogPublisher logPublisher;

	//에러 처리
	public void handleException(Exception e) {
		String routingKey = e instanceof IllegalArgumentException ? "warn" : "error";
		logPublisher.publish(routingKey, "Exception Log: " + e.getMessage());
	}

	// 메시지 처리
	public void handleMessage(String message) {
		String routingKey = "info";
		logPublisher.publish(routingKey, "Info Log: " + message);
	}
}

테스트

curl -X GET "http://localhost:8080/api/logs/error" 
curl -X GET "http://localhost:8080/api/logs/warn" 
curl -X POST "http://localhost:8080/api/logs/info" \
 -H "Content-Type: application/json" \
 -d "\"System initialized successfully.\""

패턴별 로그를 수집하는 Routing 모델 예제 (using TopicExchange)

개별 로그와 더불어 모든 로그를 수집하는 큐를 만들어보자.

패턴을 만들기 위해, Routing Key에 log.을 추가
각각의 로그에 대한 개별 큐에 추가하여, 모든 로그를 수집하는 큐 생성(all_log_queue)
all_log_queue에 대한 바인딩 키를 log.*로 설정

RabbitMQConfig 추가/변경 사항

@Configuration
public class RabbitMQConfig {
	...
	public static final String ALL_LOG_QUEUE = "all_log_queue";

	public static final String TOPIC_EXCHANGE = "topic_exchange";

	@Bean
	public TopicExchange topicExchange() {
		return new TopicExchange(TOPIC_EXCHANGE);
	}

	...

	@Bean
	public Queue allLogQueue() {
		return new Queue(ALL_LOG_QUEUE, false);
	}

	...

	@Bean
	public Binding allLogBinding() {
		return BindingBuilder.bind(allLogQueue()).to(topicExchange()).with("log.*");
	}
}

Exceptionhandler 변경 사항: 패턴을 만들기 위해 log. 추가

@Component
@RequiredArgsConstructor
public class CustomExceptionHandler {

	private final LogPublisher logPublisher;

	//에러 처리
	public void handleException(Exception e) {
		String routingKey = e instanceof IllegalArgumentException ? "log.warn" : "log.error";
		logPublisher.publish(routingKey, "Exception Log: " + e.getMessage());
	}

	// 메시지 처리
	public void handleMessage(String message) {
		String routingKey = "log.info";
		logPublisher.publish(routingKey, "Info Log: " + message);
	}
}

Consumer 추가 사항

@Component
public class LogConsumer {

	...

	@RabbitListener(queues = RabbitMQConfig.ALL_LOG_QUEUE)
	public void consumeAllLogs(String message) {
		System.out.println("[All LOGS]를 받음 : " + message);
	}
}

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

Pub/Sub 모델을 이용한 실시간 알림과 뉴스 구독 (WebSocket, STOMP 활용)

studyHub — Sun, 22 Feb 2026 15:12:40 +0900

Publish / Subscribe 모델

Pub/Sub은 메시지 발행(Publish)과 구독(Subscribe)의 개념을 기반으로 하는 메시징 패턴(메시지 전달 모델)으로,

하나의 메시지가 복제되어 여러 “독립적인 소비자 그룹”에 각각 전달되는 모델이다.

Publisher는 특정 대상이 아니라 주제(이벤트)에 메시지를 발행
여러 Subscriber가 동시에 메시지를 수신 (여러 독립 구독자에게 복제 전달)

하나의 Exchange에 여러 Queue가 바인딩되어 있으면 Pub/Sub

Fanout Exchange와의 차이

Pub/Sub = "신문을 여러 사람이 구독"
Fanout = "신문을 그냥 무조건 모든 우편함에 배달"

경쟁 소비자 모델과의 차이

큐가 여러 개에 각각의 컨슈머 / 메시지 복제 있음, 여러 구독자가 동일 메시지 수신 → Pub/Sub
큐가 하나에 컨슈머 여러개 / 메시지 복제 없음, 여러 소비자가 나눠 처리 → 경쟁 소비자

Pub/Sub vs 경쟁 소비자는 “큐 구조 차이”가 있다.

Pub/Sub 모델의 주요 특징

유연성과 확장성이 좋아 여러 subscriber를 쉽게 추가하여도 서로 독립적으로 동작이 가능하다.

다대다 메시징
- 하나의 메시지가 여러 Subscriber에게 전달
- 메시지 복사가 이뤄지므로 Subscriber는 동일한 메시지를 수신.
  동일한 메시지가 여러 큐에 처리되므로 중복 처리 로직이 필요할 수 있음.
구독자 독립성
- Publisher는 메시지가 어떤 Subscriber에게 전달될지 알 필요가 없음
- 메시지의 전달은 브로커가 처리
비동기 메시지
- Publisher와 Subscriber는 서로 독립적으로 동작하며, 동시에 실행될 필요가 없음
확장성
- 여러 Subscriber를 추가하거나 제거해도 시스템이 영향을 받지 않음
구독 제어
- 구독자는 특정 조건(ex.라우팅 키, 토픽)을 기반으로 메시지를 필터링하여 수신할 수도 있음
- Fanout Exchange는 모든 구독자에게 메시지를 브로드캐스트하는 반면(Routing Key는 필요하지 않음),
  Topic Exchange나 Direct Exchange는 메시지를 선택적으로 전달 가능
- 구독자가 많을수록 복잡도가 증가

WebSocket과 STOMP

먼저 WebSocket과 STOMP에 대해 알아보자.

RabbitMQ/Kafka = 서버 간 메시징
WebSocket/STOMP = 서버 → 브라우저 실시간 전송
- WebSocket = 서버가 먼저 말할 수 있게 만드는 기술
- STOMP = 그 말을 어떤 방에 보낼지 정하는 규칙

브라우저
↓ WebSocket + STOMP
Spring 서버
↓
Kafka / Redis / RabbitMQ

WebSocket

서버와 클라이언트가 한 번 연결하면, 끊기 전까지 서로 실시간으로 데이터를 주고 받을 수 있는 통신 방식

(실시간 통신이란, 이벤트가 발생하는 즉시 상대방에게 전달되는 통신 방식)

WebSocket은 HTTP 위에서 시작하지만, 연결 후에는 지속적인 양방향 실시간 통신을 제공하는 프로토콜.

※ 소켓: 네트워크에서 두 프로그램이 데이터를 주고받기 위한 통신의 endpoint . IP + Port + Protocol = Socket

HTTP는 요청/응답 1회성
WebSocket은 지속 연결 + 양방향 통신
- WebSocket은 TCP 커넥션을 끊지 않고 계속 유지한다.
  하지만 스레드를 계속 점유하지는 않는다. Spring은 소수의 워커 스레드가 여러 소켓 이벤트를 처리한다.
  TCP 소켓 자체가 세션이다. (Spring은 내부적으로 Map<sessionId, WebSocketSession> 형태로 관리)
- 클라이언트가 요청하지 않아도 서버가 먼저 보낼 수 있음
실시간 채팅 등에 사용
- 채팅을 HTTP로 하면 1초마다 서버에 물어봄 (polling) → 부하/지연 발생
매번 연결을 새로 만들지 않아도 되기 때문에 지연(latency)이 거의 없음
데이터를 프레임 단위로 전송하며, 오버헤드가 낮음
ws://호스트:포트/경로 형태로 작성 (ws://example.com/chat)

	HTTP	WebSocket
연결 방식	요청/응답	지속 연결
통신 방향	단방향	양방향
실시간성	낮음	높음
오버헤드	큼 (헤더 반복)	적음

STOMP (Simple Text Oriented Messaging Protocol)

WebSocket 위에서 사용하는 메시지 프로토콜로, 텍스트 기반의 단순한 메시지 규칙.

WebSocket = 통신 터널(네트워크 레벨)
STOMP = 그 터널 안에서 사용하는 메시지 형식/라우팅 규칙(프로토콜)

클라이언트
↓
WebSocket 연결
↓
그 위에서 STOMP 프로토콜 사용
↓
Spring Message Broker 처리

STOMP가 제공하는 기능

기능	설명
SUBSCRIBE	특정 topic 구독
SEND	메시지 전송
ACK	메시지 확인
destination	주소 개념

STOMP 메시지 형식

COMMAND
header1:value1
header2:value2
body
---
# 예시
SEND
destination:/topic/chat
{"message":"hello"}

STOMP를 쓰는 이유

WebSocket은 그냥 문자열 or byte[] 전송으로, 형식 규칙과 pub/sub 구독 등의 개념이 없다. 그래서 등장한 것이 STOMP 이다.

약속을 기반으로 API 등이 구현되어 있는 것이다.

STOMP를 안 쓰면: “WebSocket 통로”만 있고, 채팅방/구독/라우팅/세션관리/재전송 정책을 전부 직접 만들어야 한다.
STOMP를 쓰면: WebSocket 위에 목적지(destination) 기반 Pub/Sub 규칙이 올라가서,
클라이언트는 SUBSCRIBE/SEND만 하면 되고, 서버(Spring)가 구독자 목록 관리 + 라우팅 + 전송을 대신해준다.
Spring WebSocket(STOMP) 스택이 STOMP 프레임을 해석해서 구독을 “등록 테이블”에 저장하고, 메시지 전송 시 그 테이블을 조회해 해당 세션으로 push한다.
이를 쓰려면 WebSocket/STOMP 관련 의존성과 설정이 필요한데, Spring Boot 기준으로 spring-boot-starter-websocket만 추가하면 STOMP 메시징까지 같이 들어온다.
STOMP를 쓰면 Spring이 “destination(목적지) ↔ 구독 세션 목록”을 메모리(또는 외부 브로커)에서 관리하고,
메시지를 보내면 해당 destination을 구독한 세션들에게 자동으로 fan-out 해준다.
STOMP는 destination이라는 개념을 제공하고, 실제 라우팅은 SimpleBroker 사용
: Spring이 내부 메모리로 간단한 브로커 역할 수행(destination -> 세션 목록)
Client
   ↓
WebSocket
   ↓
STOMP
   ↓
Spring SimpleBroker (메모리 Map)
   ↓
다른 Client

채팅방 room1에 A가 메시지를 보내면 roo1에 있는 모든 사람(B,C,,)에게 즉시 전달되는 프로그램을 만든다고 가정해보자.

1) 클라이언트가 이런 STOMP 프레임을 보낸다고 치면:

SUBSCRIBE
destination:/topic/room1
id:sub-1

2) Spring이 프레임을 파싱하고 “구독 등록”을 한다. Spring 내부에서는 대략 아래와 같은 식의 매핑을 유지한다.

destination("/topic/room1") -> [sessionA, sessionB, ...]

sessionId(WebSocket 연결 단위)별로 어떤 destination을 구독했는지 저장
destination별로 어떤 세션들이 붙어있는지 인덱싱

3) 서버가 destination으로 메시지 발행

서버에서 아래를 호출하면

messagingTemplate.convertAndSend("/topic/room1", payload);

Spring은 "/topic/room1"을 구독한 세션 목록을 찾고, 그 세션들에게 WebSocket으로 메시지를 push한다.

즉, “누가 구독했는지”를 Spring이 이미 알고 있기 때문에 서버 코드는 “어디로 보낼지(destination)”만 말하면 끝이다.

이번에는 javascript와 java 코드로 살펴보자.

1. 서버에서 규칙(prefix)을 먼저 정한다.

Spring 설정에서 보통 아래와 같이 나눈다:

클라이언트가 서버로 보내는 목적지(prefix): /app
서버가 클라이언트에게 보내는 목적지(prefix): /topic, /queue

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {

  @Override
  public void configureMessageBroker(MessageBrokerRegistry registry) {
    // 서버 → 클라(구독 대상)
    // SimpleBroker: Spring이 내부 메모리로 간단한 브로커 역할을 하겠다 (RabbitMQ 아님)
    registry.enableSimpleBroker("/topic", "/queue");
    // 클라 → 서버(@MessageMapping으로 들어옴)
    registry.setApplicationDestinationPrefixes("/app");
  }
}

클라가 SEND /app/... 하면 → 서버의 @MessageMapping("...")로 라우팅
서버가 convertAndSend("/topic/...") 하면 → 그 destination 구독자에게 push

2. "어디로 보낼지"는 결국 2가지 중 하나로 결정한다.

A) 브로드캐스트(채팅방)로 보낼 때

클라이언트(구독)

stompClient.subscribe("/topic/room.1", onMessage);

서버(전송)

messagingTemplate.convertAndSend("/topic/room.1", payload);

둘이 destination 문자열이 같으니까 “room.1을 구독한 사람 모두”가 받는다.

B) 서버로 보내서(핸들러 타서) 처리한 뒤, 다시 뿌릴 때

클라이언트(서버로 SEND)

stompClient.send("/app/chat.send", {}, JSON.stringify({
  roomId: 1,
  text: "안녕"
}));

서버(받는 곳)

@MessageMapping("/chat.send") // 앞의 /app 은 설정에서 떼고 매핑됨
public void handle(ChatMessage msg) {
  messagingTemplate.convertAndSend("/topic/room." + msg.roomId(), msg);
}

여기서 “어디로 보낼지”는 서버 코드가 결정: "/topic/room." + roomId

WebSocket과 Pub/Sub을 통한 실시간 웹 알림 구현(Notification)

웹 페이지를 하나 만들고, WebSocket을 이용하여 API를 연동한 뒤,
서버에서 publish 한 메시지를 web 알림 영역에 실시간으로 표시하는 프로그램을 만들어보자.

구현

RabbitMQConfig : 3개의 Bean(Queue, Exchange, Binding)을 설정

@Configuration
public class RabbitMQConfig {
	// 큐 네임 설정
	public static final String QUEUE_NAME = "notificationQueue";
	public static final String FANOUT_EXCHANGE = "notificationExchange";

	//Spring이 시작될 때 RabbitMQ 서버에 “이 큐를 생성하라”라고 선언하기 위해
	@Bean
	public Queue queue() {
		//QUEUE_NAME은 메시지가 쌓이고 처리될 큐의 이름을 정의
		return new Queue(QUEUE_NAME, false); //영속화 여부
	}

	@Bean
	public FanoutExchange fanoutExchange() {
		//메시지를 수신하면 모든 큐로 브로드캐스트
		return new FanoutExchange(FANOUT_EXCHANGE);
	}

	@Bean
	public Binding bindingNotification(Queue notificationQueue, FanoutExchange fanoutExchange) {
		//큐와 익스체인지를 연결
		return BindingBuilder.bind(notificationQueue).to(fanoutExchange);
	}
}

Controller

두 가지 경로로 알림을 클라이언트에 브로드캐스트하므로 Controller도 두개이다.

A) StompController
STOMP 클라이언트가 /app/send로 보낸 메시지를 @MessageMapping이 받아 SimpMessagingTemplate.convertAndSend("/topic/notifications", ...)로 브로드캐스트

@Controller
@RequiredArgsConstructor
public class StompController {

	private final SimpMessagingTemplate simpMessagingTemplate;

	@MessageMapping("/send")
	public void sendMessage(NotificationMessage notificationMessage) {
		// 수신된 메시지를 브로드캐스팅
		String message = notificationMessage.message();
		System.out.println("[#] message = " + message);

		// 클라이언트에 메시지 브로드캐스트
		simpMessagingTemplate.convertAndSend("/topic/notifications", message);
	}
}

B) NotificationController
HTTP(REST)로 들어온 알림을 NotificationPublisher가 RabbitMQ Exchange에 publish
→ NotificationSubscriber가 큐에서 수신
→ SimpMessagingTemplate.convertAndSend("/topic/notifications", ...)로 브로드캐스트

* SimpMessagingTemplate은 Spring에서 WebSocket(STOMP) 클라이언트에게 메시지를 보내는 서버 측 유틸리티 클래스

curl -X POST 'http://localhost:8080/notifications' -H 'Content-Type: application/json' -d 'Hello! Subscriber!!'

@RestController
@RequestMapping("/notifications")
@RequiredArgsConstructor
public class NotificationController {

	private final NotificationPublisher publisher;

	@PostMapping
	public String sendNotification(@RequestBody String message) {
		publisher.publish(message);
		return "[#] Notification sent: " + message + "\n";
	}
}

Publisher: RabbitTemplate을 이용해 convertAndSend

@Component
@RequiredArgsConstructor
public class NotificationPublisher {

	private final RabbitTemplate rabbitTemplate;

	public void publish(String message) {
		rabbitTemplate.convertAndSend(RabbitMQConfig.FANOUT_EXCHANGE, "", message);
		System.out.println("[#] Published Notification: " + message);
	}
}

Subscriber

@RabbitListener로 큐 네임 지정
- Spring이 메시지 수신을 자동화하고, 비동기적으로 처리. 코드가 간결
- 내부적으로 Spring의 MessageListenerContainer를 사용하여 Queue를 지속적으로 모니터링
- 메시지 수신, 메서드 호출과 변환, Ack 전송 등의 역할
SimpMessageingTemplate을 통해 특정 경로에 메시지 전달
- Spring에서 WebSocket(STOMP) 메시지를 클라이언트에게 보내는 템플릿 클래스
  쉽게 말해 웹소켓용 RabbitTemplate/KafkaTemplate 같은 것
- WebSocket 메시지 브로커와 통신하며, 클라이언트가 구독하는 특정 경로로 메시지를 전송
- HTTP 응답이 아니라, 실시간 push 메시지 전송용
  Server (Spring)
     ↓
  SimpMessagingTemplate
     ↓
  WebSocket Broker
     ↓
  Client (브라우저)

@Component
@RequiredArgsConstructor
public class NotificationSubscriber {

	public static final String CLIENT_URL = "/topic/notifications";

	// WebSocket으로 메시지를 전달하기 위한 Spring의 템플릿 클래스
	private final SimpMessagingTemplate simpMessagingTemplate;

	// RabbitMQ Queue에서 메시지 수신
	// RabbitListener에 의해 QUEUE_NAME을 바라보다가 exchange에 메시지가 도착하면 Queue로 발행되고 이 Queue가 메시지를 수신
	// String message = (String) rabbitTemplate.receiveAndConvert(RabbitMQConfig.QUEUE_NAME); 과 같은 번거로운 코딩 생략
	@RabbitListener(queues = RabbitMQConfig.QUEUE_NAME)
	public void subscribe(String message) {
		System.out.println("[#] Received Notification: " + message);
		// WebSocket을 통해 클라이언트로 메시지를 전달
		simpMessagingTemplate.convertAndSend(CLIENT_URL, message); // 클라이언트에 브로드캐스트
	}
}

WebSocketConfig

WebSocketMessageBroker 활성화
WebSocketMessageBrokerConfigurer를 구현
Spring에서 WebSocket 메시지 브로커를 구성하기 위한 인터페이스.
웹소켓 연결, 메시지 브로커 설정 및 라우팅 등의 웹 소켓 관련 확장 기능 제공

@Configuration
@EnableWebSocketMessageBroker
public class WebSocketConfig implements WebSocketMessageBrokerConfigurer {
	@Override
	public void configureMessageBroker(MessageBrokerRegistry registry) {
		// SimpleBroker: Spring이 내부 메모리로 간단한 브로커 역할을 하겠다 (RabbitMQ 아님)
		// 서버 → 클라(구독 대상). 서버가 convertAndSend("/topic/...") 하면 → 그 destination 구독자에게 push(세션 뒤져서)
		registry.enableSimpleBroker("/topic"); // 클라이언트가 구독할 수 있는 경로 설정. SimpleBroker가 /topic/*에 대한 구독을 관리
		// 클라 → 서버(@MessageMapping으로 들어옴). 클라가 SEND /app/... 하면 → 서버의 @MessageMapping("...")로 라우팅
		registry.setApplicationDestinationPrefixes("/app"); // 클라이언트가 메시지를 보낼 때 사용할 접두사 설정
	}

	@Override
	public void registerStompEndpoints(StompEndpointRegistry registry) {
		registry.addEndpoint("/ws") // 클라이언트가 WebSocket 연결을 시도할 때 사용할 엔드포인트 설정
			.setAllowedOriginPatterns("*") // CORS 설정
			.withSockJS(); // SockJS 지원
	}
}

HTML 작성

필요 라이브러리
- sock.js : WebSocket 연결을 지원하지 않는 브라우저에서도 동작하도록 fallback 기능을 제공하는 라이브러리로 다음과 같은 전송 타입을 지원: WebSocket, HTTP Streaming, HTTP Long Polling
- stomp.js: STOMP 프로토콜을 지원하는 JavaScript 클라이언트 라이브러리.
  텍스트 기반 프로토콜로, 메시지의 유형, 내용을 정의하여 클라이언트와 서버 간 메시지를 주고 받음.
  RabbitMQ와 같은 브로커와 통신하는 데 사용.

<!-- html 생략 -->
<script>
    const socket = new SockJS('/ws'); // 서버의 WebSocket Endpoint 연결
    const stompClient = Stomp.over(socket); // SockJS 객체를 STOMP 클라이언트로 wrapping

    stompClient.connect({}, function () {
        console.log('Connected to WebSocket');
        // STOMP 연결 후 stompClient.subscribe('/topic/notifications', ...) 호출 → 서버의 SimpleBroker에 구독 등록
        // WebSocketConfig.configureMessageBroker(...)에서 registry.enableSimpleBroker("/topic") -> SimpleBroker가 /topic/*에 대한 구독을 관리
        // 서버가 /topic/notifications로 메시지 전송하면(서버 발행)
        // SimpleBroker가 해당 destination의 구독 목록을 찾아 세션별로 메시지를 전송 → 클라이언트의 subscribe 콜백으로 도달
        stompClient.subscribe('/topic/notifications', function (message) {
            const notificationsDiv = document.getElementById('notifications');
            const newNotification = document.createElement('div');
            newNotification.textContent = message.body;
            notificationsDiv.appendChild(newNotification);
        });
        // 서버로 전송도 가능
        const form = document.getElementById('notificationForm')
        form.addEventListener('submit', function (event) {
            event.preventDefault();
            const messageInput = document.getElementById('notificationMessage');
            const message = messageInput.value;

            stompClient.send('/app/send', {}, JSON.stringify({ message: message }));
            messageInput.value = '';
        })
    });
</script>

여러 큐를 소비하는 Fanout Exchange 예제 (관심사 기반의 뉴스 레터 발행/구독 모델)

뉴스 레터 구독 프로그램을 만들어보자.

각 사용자는 관심있는 개발 뉴스 레더를 체크하고 구독한다. (Java/Spring/Vue)

각각의 관심사별 Exchange 연결에 따른 메시지 발행과 구독을 구현하면 된다.

시퀀스 A: STOMP → 서버 → RabbitMQ → WebSocket 브로드캐스트
시퀀스 B: HTTP REST → RabbitMQ → WebSocket 브로드캐스트

구현

RabbitMQConfig

3개의 Queue Bean, 1개의 Exchange Bean, 3개의 큐 Binding에 대한 bind().to() 설정
(사실 해당 예제는 Topic Exchange가 적합하나, 아직 배우기 전이라 Fanout Exchange로 구현했다.)
매개변수 이름은 실제로 주입되는 빈 이름과 일치하지 않아도 동작하지만, 타입이 같은 여러개의 빈이 존재하면 @Qualifier를 사용해 이름으로 구분 지어야 함

@Configuration
public class RabbitMQConfig {
	// 큐 네임 설정
	public static final String JAVA_QUEUE = "javaQueue";
	public static final String SPRING_QUEUE = "springQueue";
	public static final String VUE_QUEUE = "vueQueue";

	public static final String FANOUT_EXCHANGE_FOR_NEWS = "newsExchange";

	//Spring이 시작될 때 RabbitMQ 서버에 “이 큐를 생성하라”라고 선언하기 위해
	@Bean
	public Queue javaQueue() {
		return new Queue(JAVA_QUEUE, false);
	}

	@Bean
	public Queue springQueue() {
		return new Queue(SPRING_QUEUE, false);
	}

	@Bean
	public Queue vueQueue() {
		return new Queue(VUE_QUEUE, false);
	}

	@Bean
	public FanoutExchange fanoutExchange() {
		// 메시지를 수신하면 연결된 모든 큐로 브로드캐스트
		return new FanoutExchange(FANOUT_EXCHANGE_FOR_NEWS);
	}

	@Bean
	public Binding javaBinding(Queue javaQueue, FanoutExchange fanoutExchange) {
		return BindingBuilder.bind(javaQueue).to(fanoutExchange);
	}

	@Bean
	public Binding springBinding(Queue springQueue, FanoutExchange fanoutExchange) {
		return BindingBuilder.bind(springQueue).to(fanoutExchange);
	}

	@Bean
	public Binding vueBinding(Queue vueQueue, FanoutExchange fanoutExchange) {
		return BindingBuilder.bind(vueQueue).to(fanoutExchange);
	}
}

컨트롤러

웹용(STOMP 기반) 컨트롤러와 API용 컨트롤러 모두 publisher를 호출해 메시지 발행

메시지발행(publisher)

fanout이므로 라우팅 키는 무시되고 모든 큐에 삽입됨

@Component
@RequiredArgsConstructor
public class NewsPublisher {

    private final RabbitTemplate rabbitTemplate;

    private String publishMessage(String news, String messageSuffix) {
       String message = news + messageSuffix;
       rabbitTemplate.convertAndSend(RabbitMQConfig.FANOUT_EXCHANGE_FOR_NEWS, news, message);
       System.out.println("News Published: " + message);
       return message;
    }

    public String publish(String news) {
       return publishMessage(news, " 관련 새 소식이 나왔습니다.");
    }

    public String publishAPI(String news) {
       return publishMessage(news, " 관련 새 소식이 나왔습니다. (API)");
    }
}

컨슈머(subscriber)

큐에서 메시지를 수신하면 웹 소켓으로 메시지를 전달한다. 이때, destination을 보고 구독한 클라이언트만 메시지를 수신한다.

즉, Fanout으로 모든 큐에 메시지를 브로드캐스트하지만 WebSocket을 이용해 특정 뉴스 타입만 선택적으로 구독하는 것이다.

@Component
@RequiredArgsConstructor
public class NewsSubscriber {

	// WebSocket으로 메시지를 전달하기 위한 Spring의 템플릿 클래스
	private final SimpMessagingTemplate simpMessagingTemplate;

	// RabbitListener에 의해 QUEUE_NAME을 바라보다가 exchange에 메시지가 도착하면 Queue로 발행되고 이 Queue가 메시지를 수신
	@RabbitListener(queues = RabbitMQConfig.JAVA_QUEUE)
	public void javaNews(String message) {
		// 해당 destination으로 구독한 세션들에게 메시지 push
		simpMessagingTemplate.convertAndSend("/topic/java", message);
	}

	@RabbitListener(queues = RabbitMQConfig.SPRING_QUEUE)
	public void springNews(String message) {
		simpMessagingTemplate.convertAndSend("/topic/spring", message);
	}

	@RabbitListener(queues = RabbitMQConfig.VUE_QUEUE)
	public void vueNews(String message) {
		simpMessagingTemplate.convertAndSend("/topic/vue", message);
	}
}

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

경쟁 소비자 패턴(Work Queue 모델)과 큐의 메시지 상태

studyHub — Tue, 17 Feb 2026 19:53:22 +0900

Consumer간 작업 분배 - WorkQueue

Work Queues : Competing Consumers Pattern

Work Queue 패턴에서는 여러 소비자가 하나의 큐에서 메시지를 가져가 경쟁적으로 처리한다.

작업 부하를 효율적으로 분산하고, 병렬 처리를 가능하게 만들어 처리량을 향상시키는 효과가 있다.

Round-Robin 방식(default)과 Fair Dispatch 방식을 사용하여 메시지를 Consumer 간에 분배
Fair Dispatch 방식은 개발자가 코드 레벨에서 컨슈머간 분배 조정.
메시지 수동 확인(Manual Acknowledgement) 모드로 설정해야함. (AMQP 기본 값 Auto)
메시지 처리 비중(Prefetch Count) 설정 등을 통해 조정 가능

주요 특징

경쟁적인 메시지 소비
여러 Consumer가 동일한 메시지 큐에서 메시지를 가져가 처리하나,
특정 메시지는 한 번에 하나의 Consumer에 의해 처리되므로 중복 처리는 되지 않는다.
작업 분산
메시지가 여러 Consumer 간에 분배되어 병렬로 처리되므로 작업 부하를 효율적으로 분산
확장성
Consumer를 추가하거나 제거함으로써 작업 처리 능력을 동적으로 확장하거나 축소
내결함성
Consumer 중 하나가 실패하더라도 다른 Consumer가 작업을 이어받아 처리할 수 있어 중단없이 작동

구성

Config는 별반 다를 바 없으나, 오류 확인을 위해 큐의 Duration을 true로 설정하여 서버를 내려도 데이터가 유지되도록 했다.

@Configuration
public class RabbitMQConfig {
	// 큐 네임 설정
	public static final String QUEUE_NAME = "WorkQueue";

	//Spring이 시작될 때 RabbitMQ 서버에 “이 큐를 생성하라”라고 선언하기 위해
	@Bean
	public Queue queue() {
		//QUEUE_NAME은 메시지가 쌓이고 처리될 큐의 이름을 정의
		return new Queue(QUEUE_NAME, true); //영속화 여부. true: 서버 셧다운 시 데이터 보관
	}


	//RabbitTemplate: 래빗엠큐로 메시지를 보내는 데 사용되는 템플릿 클래스
	@Bean
	public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
		return new RabbitTemplate(connectionFactory); //ConnectionFactory: 래빗엠큐의 연결 관리
	}

	//SimpleMessageListenerContainer: 래빗엠큐에서 메시지를 수신하고 처리하는 리스너 컨테이너
	@Bean
	public SimpleMessageListenerContainer container(ConnectionFactory connectionFactory,
		MessageListenerAdapter listenerAdapter) {
		SimpleMessageListenerContainer container = new SimpleMessageListenerContainer();
		container.setConnectionFactory(connectionFactory);
		container.setQueueNames(QUEUE_NAME);
		container.setMessageListener(listenerAdapter);
		container.setAcknowledgeMode(AcknowledgeMode.AUTO); //default이나 명시
		return container;
	}

	//MessageListenerAdapter: 메시지를 처리할 리스너 어댑터
	@Bean
	public MessageListenerAdapter listenerAdapter(WorkQueueConsumer workQueueTask) {
		return new MessageListenerAdapter(workQueueTask, "workQueueTask");
	}
}

그 외 Controller, Producer, Consumer는 역할이 별반 다를게 없다.

사실 Work Queue 전용 설정이 따로 있는 것이 아니고, 하나의 Queue를 여러 Consumer가 같이 소비하면 그게 곧 Work Queue 패턴이다. 같은 큐를 바라보는 @RabbitListener 인스터스가 여러 개 있으면 Work Queue 처럼 동작한다.

하나의 RabbitMQ 서버에 여러 Spring 서버를 띄워서 확인해보자.

실행

jar로 빌드하여 spring을 두대 띄워본 후 curl로 요청을 3번 보내보니, 아래와 같이 1,3 / 2 요청이 분산됨을 확인할 수 있었다.

8080 포트로 요청을 3개 보낸 후 8080 및 8081 포트의 Consumer에 메시지가 각각 분배되어 처리

메시지

어드민에서 메시지 확인하기

의도적으로 Consumer에서 오류를 발생하게 하고, 어드민에서 확인해보자.

큐의 상태를 보면 메시지가 상태에 따라 분류되는데,

ready
- 메시지가 큐에 있지만, 아직 컨슈머에게 전달되지 않은 상태
- 이 상태의 메시지는 대기 중이며, 컨슈머가 연결되면 전달될 준비가 됨
- 큐의 적재량이 많이지면 ready 메시지 수가 증가
unacked
- 메시지가 컨슈머에게 전달되었으나, 아직 확인되지 않은 상태
- 컨슈머가 메시지를 처리하고 확인(ACK)를 보내면, RabbitMQ는 해당 메시지를 삭제
- 컨슈머가 확인을 보내지 못하거나 연결이 끊어지면, 메시지는 다시 ready 상태로 돌아감(설정에 따라 다름)

메시지 삭제가 필요한 경우, admin에서 purge 버튼을 눌러서 삭제

purge 명령은 큐에 있는 ready 메시지를 삭제 (unacked 메시지는 purge로 삭제되지 않음)
삭제된 메시지는 복구되지 않으며, 데이터는 소실
unacked 메시지를 삭제하려면 컨슈머가 연결을 끊거나 RabbitMQ 큐를 재시작해야 함
(컨슈머가 연결을 끊으면 unacked 메시지는 다시 ready 상태로 돌아가므로)

일반적인 문제 해결 방법

ready가 많을 경우
- 컨슈머 수를 늘리거나 컨슈머의 메시지 처리 속도를 최적화해야 함.
unacked가 많을 경우
- 컨슈머 코드 수정 (프로그램 에러일 가능성이 높다)
  unacked 상태에서 consumer 를 제대로 소비하도록 프로그램을 수정하면 unacked 에서도 처리가 되어 삭제된다.
- 컨슈머 연결 상태를 확인 하여 재연결 혹은 재시작 필요

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

Exchange의 이해와 기본 비동기 메시지 전송

studyHub — Tue, 17 Feb 2026 17:57:43 +0900

Exchange 유형에 따른 처리 흐름

1. Direct Exchange

메시지를 발행할 때 사용하는 라우팅 키와 동일한 키로 익스체인지에 바인딩 된 모든 큐에 메세지를 전달.

해당 라우팅 키와 일치하는 큐에만 메시지가 전달되는 방식이기 때문에 Direct Exchange 라고 한다.

매핑이 정확하게 되는 한개의 키만 있으니까 1:1로 가능할거 같은데, 하나의 라우팅 키에 대해 여러 큐가 바인딩될 수 있기 때문에 1:N 매칭이 가능하다.

활용

메시지가 명확하게 특정 큐로 전달되어야 할 때
큐마다 고유한 라우팅 규칙을 적용하여 메시지를 분류해야 할 때
예시 업무: 주문 상태 처리, 결제 처리, 사용자 알림 시스템 등
- 주문 상태별로 라우팅 키를 정의하고, 각 상태에 해당하는 큐가 메시지를 받는다

2. Topic Exchange

라우팅 키를 패턴 기반으로 정의하여 메시지를 여러 큐에 유연하게 전달.

라우팅 키에 와일드카드(*, #) 매칭을 사용하여 더 복잡한 라우팅이 가능

와일드카드

* : 1개 단어 대체. log.info, log.warn, log.error -> log.*
# : 0개 이상의 단어를 대체: app.order.success, app.payment.success -> #.success

활용

동적이고 유연한 라우팅이 필요할 때(로그 수집 시스템, 이벤트 기반 모니터링 등)

3. Fanout Exchange

브로드캐스트 방식으로 메시지를 모든 바인딩된 큐에 전달.

한 번의 메시지 발행으로 모든 큐가 동일한 메시지를 받는다.

활용

이벤트가 발생하면 모든 서비스가 동일한 메시지를 받는 서비스에서 유용(시스템 점검 공지 등)

4. Headers Exchange

메시지의 속성(헤더)에 기반한 복잡한 라우팅이 필요할 때

활용

다국어 서비스, 고객의 등급별 혜택 알림
- 메시지 헤더에 language: "ko", language: "en" 등의 값을 설정하여 헤더 기반 라우팅을 수행
"ko"로 설정된 메시지는 한국어 이메일 서비스에서 처리, "en"으로 설정된 메시지는 영어 이메일 서비스에서 처리

메시지 전송 단계별 프로세스

메시지 송신 (Producer -> Broker)
- Producer가 RabbitMQ Broker로 메시지를 송신
- 이때 메시지는 큐에 저장되며, 익스체인지와 바인딩 설정에 따라 적절한 큐로 라우팅
메시지 전달 (Broker -> Consumer)
- Broker는 큐에 있는 메시지를 Consumer에게 전달
- Consumer는 큐에서 메시지를 가져가거나(Polling, 일정 주기로 계속 물어보는 Pull의 한 형태), 메시지를 푸시(Push) 받는 방식으로 수신
메시지 확인(ACK) 또는 거절(NACK)
- ACK: Consumer가 메시지를 성공적으로 처리한 후 Broker에 ACK(Acknowledgment) 전송.
  - 이 경우 Broker는 해당 메시지를 큐에서 제거하고 Producer에게 Message Acknowledged 응답
- NACK: Consumer가 메시지 처리에 실패하거나 메시지를 거절할 경우 NACK(Negative Acknowledgment) 전송.
  - Consumer가 메시지를 NACK하면 Broker는 Producer에게 Message Rejected 응답
  - NACK에는 메시지를 다시 큐로 보내야 할지(requeue) 또는 폐기해야 할지(discard) 설정 가능
Producer에 응답 (Message Acknowledged / Message Rejected)
- Producer가 Publisher Confirms를 활성화한 경우, Broker는 ACK 또는 NACK 결과를 Producer에게 전송
- ACK를 받은 경우 메시지가 성공적으로 소비된 것으로 간주되며,
  NACK를 받은 경우 Producer는 메시지 실패를 기록하거나 재전송

단순 메시지 전송 (Producer to Consume)

RabbitMQ는 아무 설정을 안 해도 동작하도록 이미 내부에 기본 Exchange(Default Exchange) + 자동 바인딩 구조가 존재한다.

rabbitTemplate.convertAndSend("myQueue", message);

위와 같이 메시지를 보냈다면, 실제 내부적으로는 아래와 같이 동작한다.

Producer
↓
Default Direct Exchange ("")
↓ (routingKey = myQueue)
Queue (myQueue)
↓
Consumer

구현

application.yml 작성

spring:
  rabbitmq:
    host: localhost
    port: 5672 # 기본 통신 포트, 15672는 주로 관리 및 모니터링(admin) 용
    username: guestuser
    password: guestuser
  application:
    name: HelloMessageQueue
server:
  port: 8080

설정 Bean 생성

implementation 'org.springframework.boot:spring-boot-starter-amqp'

Kafka 처럼 RabbitMQ를 사용하기 위해 위 의존성을 추가하면 자동으로 RabbitTemplate 등을 제공하지만,

AMQP 구조를 명확히 보기 위해 직접 Bean을 등록해보자.

Queue
- Queue 인스턴스를 생성하고, 애플리케이션이 사용할 큐를 정의, 메시지를 전달하고 처리하는 기본 큐 세팅
- Spring이 시작될 때 RabbitMQ 서버에 “이 큐를 생성하라”라고 선언하기 위해 빈으로 만든다.
  Queue Bean 발견
  ↓
  RabbitAdmin이 감지
  ↓
  애플리케이션 시작 시
  ↓
  RabbitMQ 서버에 queue.declare 실행
- Durable 속성을 True로 설정하면 RabbitMQ 서버가 예기치 않게 종료되거나 재시작될 경우에도 해당 Queue의 정의나 Queue에 있던 메시지가 손실되지 않고 보존. 영구적인 메시지 처리가 필요한 경우 중요.
.RabbitTemplate
- RabbitMQ와 통신하기 위한 템플릿 인스턴스 생성, 메시지 송수신용
- JdbcTemplate과 비슷하게, RabbitMQ와 상호작용하기 위한 간단한 API 제공. 주로 메시지 전송 담당.
  메시지를 전송하는 Sender가 rabbitTemplate.convertAndSend() 메서드를 사용해 큐에 메시지를 넣는데 사용.
  (convert는 메시지 변환(직렬화)을 해준다는 의미)
- ConnectionFactory는 RabbitMQ와의 연결을 관리하는 객체.
  rabbitTemplate에 주입하여 메시지를 전송할 때 사용할 연결을 제공
SimpleMessageListenerContainer
- RabbitMQ 메시지를 비동기적으로 수신하기 위한 리스너
- 이 컨테이너가 특정 큐를 지속적으로 모니터링하고 메시지를 수신하면 지정된 리스너(MessageListenerAdapter)를 통해 처리
- ConnectionFactory는 RabbitMQ와 연결을 유지하며, 수신하는 메시지를 이 연결을 통해 가져옴
- setQueueNames(QUEUE_NAME) 메서드는 특정 큐 이름을 설정. 이 컨테이너는 코드에서 설정한 큐에서 수신되는 메시지를 모니터링
- setMessageListener(listenerAdapter)는 listenerAdapter를 설정하여, 메시지가 수신될 때 호출할 리스너를 지정
MessageListenerAdapter
- 수신한 메시지를 특정 클래스의 특정 메서드로 전달하는 어댑터, 인자로 전달된 메서드를 자동으로 호출
- receiver 객체는 메시지를 처리하는 역할을 하는 빈이며, receiveMessage 메서드를 호출

@Configuration
public class RabbitMQConfig {
	// 큐 네임 설정
	public static final String QUEUE_NAME = "hello-queue";

	//Spring이 시작될 때 RabbitMQ 서버에 “이 큐를 생성하라”라고 선언하기 위해
	@Bean
	public Queue queue() {
		//QUEUE_NAME은 메시지가 쌓이고 처리될 큐의 이름을 정의
		return new Queue(QUEUE_NAME, false); //영속화 여부
	}


	//RabbitTemplate: 래빗엠큐로 메시지를 보내는 데 사용되는 템플릿 클래스
	@Bean
	public RabbitTemplate rabbitTemplate(ConnectionFactory connectionFactory) {
		return new RabbitTemplate(connectionFactory); //ConnectionFactory: 래빗엠큐의 연결 관리
	}

	//SimpleMessageListenerContainer: 래빗엠큐에서 메시지를 수신하고 처리하는 리스너 컨테이너
	@Bean
	public SimpleMessageListenerContainer container(ConnectionFactory connectionFactory,
		MessageListenerAdapter listenerAdapter) { 
		SimpleMessageListenerContainer container = new SimpleMessageListenerContainer();
		container.setConnectionFactory(connectionFactory);
		container.setQueueNames(QUEUE_NAME);
		container.setMessageListener(listenerAdapter);
		return container;
	}

	//MessageListenerAdapter: 메시지를 처리할 리스너 어댑터
	@Bean
	public MessageListenerAdapter listenerAdapter(Receiver receiver) {
		return new MessageListenerAdapter(receiver, "receiveMessage");
	}
}

메시지 Sender와 Receiver 구현

//consumer 역할
@Component
public class Receiver {
	public void receiveMessage(String message) {
		System.out.println("[#] Received: " + message);
	}
}

@Component
@RequiredArgsConstructor
public class Sender {

	private final RabbitTemplate rabbitTemplate;

	public void send(String message) {
		rabbitTemplate.convertAndSend(RabbitMQConfig.QUEUE_NAME, message);
		System.out.println("[#] Sent: " + message);
	}
}

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

RabbitMQ 개요와 주요 용어

studyHub — Tue, 17 Feb 2026 00:40:59 +0900

개요

RabbitMQ는 메시지 브로커이다.

애플리케이션 사이에서 메시지를 받아서 적절한 Queue로 라우팅하고 Consumer에게 전달하는 중간 서버이다.

시스템 간 비동기 메시징을 가능하게 하여 서비스 간 통신을 안정적이고 효율적으로 처리할 수 있게 해준다.

최근 MSA 환경에서 가장 일반적으로 쓰이는 기술 중 하나이며, 대량의 데이터 전송 시 발생할 수 있는 과부화를 분산시키며

비동기 처리와 지연이 필요한 작업을 효과적으로 관리해 줄 수 있다.

클러스터를 설정할 때 큐를 HA(High Available)로 설정하여 여러 노드에 저정함으로써 메시지 손실을 방지하고, Federation 플러그인을 통해 데이터 동기화와 다중 마스터 복제를 구성할 수도 있다.

메세지큐를 사용하는 이유

비동기 메시지를 사용하여 다른 응용프로그램 사이에 데이터를 송수신하기 위해
클라이언트에 대한 동기 처리는 병목의 요인이므로, 비동기로 처리해도 될 영역에 대해서는 큐를 통해 분리해서 처리한다.
요청에 대한 응답을 기다릴 필요가 없기 때문에 각 영역의 역할만 신경쓰면 된다
결국 분산환경에서 응용프로그램들을 분리하고 독립적으로 확장하기 위해서 사용, 기능 별로 모듈 구성이 용이

대표적인 도메인 활용 사례

EDA(Event-Driven Architecture) : 주문/결제/배송 등의 비즈니스 도메인을 이벤트 기반의 독립적인 도메인 모듈로 구성
로그 및 모니터링 : 로그 수집 및 준 실시간 처리 모니터링 시스템 구축
채팅 및 알람 등 Notification 시스템
비동기 데이터 처리 : 대용량의 이미지나 비디오 처리에 효율적인 분산 시스템 구축 가능
여러 디바이스의 요청 처리 : IoT와 같은 멀티 디바이스 환경에서의 요청 처리

Kafka와 RabbitMQ의 차이

설계 철학 자체가 다르고, 적용 영역이 다르다.

Kafka는 “대량 데이터 스트리밍”에 최적화된 구조 (고속 로그 저장 + 병렬 소비가 목표)
RabbitMQ는 “정교한 라우팅”에 최적화된 구조 (메시지 분기가 목표)

Kafka는 대규모 이벤트 스트리밍 플랫폼에 적합하고, RabbitMQ는 정교한 메시지 브로커 역할에 적합하다.

모든 문제가 “대용량 이벤트 스트리밍”은 아니다.

이메일 발송 작업 분배
주문 처리 비동기화
이미지 변환 작업 큐
RPC 기반 요청-응답 처리

이런 건 RabbitMQ가 더 직관적이고 단순하다.

Kafka와의 비교

	RabbitMQ	Kafka
설계 목표	메시지 전달	로그 저장
메시지 모델	큐 기반	로그 스트림 기반(메시지를 지우지않고 로그에 쌓음)
메시지 삭제	소비 후 삭제	보관 기간 유지
실시간 스트리밍	약함 (메시지 단위 관리 오버헤드)	강함 (파티션 단위 병렬 확장)
복잡한 라우팅	강함 (Exchange 기반 강력)	약함 (Routing key 없음)

AMQP의 이해

AMQP(Advanced Message Queuing Protocol)

AMQP는 RabbitMQ가 대표적으로 사용하는 프로토콜로, (Kafka는 자체 프로토콜 사용)

메시지 브로커와 애플리케이션이 통신하기 위한 표준 메시징 프로토콜이다.

AMQP는 통신 규약이고, RabbitMQ는 그 약속을 구현한 제품이다.

AMQP의 목적은 서로 다른 시스템 간에 (비용/기술/시간적인 측면에서) 최대한 효율적인 방법으로 메시지를 교환하기 위한 MQ 프로토콜이기 때문에 아래와 같은 특징이 있다.

모든 broker들은 똑같은 방식으로 동작할 것
모든 client들은 똑같은 방식으로 동작할 것
네트웍상으로 전송되는 명령어들의 표준화
프로그래밍 언어 중립적

Routing Model Components

AMQP의 라우팅 모델은 3개의 중요한 component 들로 구성된다.

Exchange : Publisher로부터 수신한 메시지를 적절한 큐 또는 다른 exchange로 분배하는 라우터의 기능을 한다.
Queue : 일반적으로 알고 있는 큐이다. 메모리나 디스크에 메시지를 저장하고, 그것을 consumer에게 전달하는 역할을 한다.
Binding : exchange와 큐와의 관계를 정의한 일종의 라우팅 테이블이다.
같은 큐가 여러 개의 exchange에 bind 될 수도 있고, 하나의 exchange에 여러 개의 큐가 binding 될 수 도 있다.

주요 용어 정리

주요 개념

1. Producer

메시지를 생성하고 RabbitMQ에 전송하는 애플리케이션
Producer는 특정 Exchange에 메시지를 전송하고 Exchange는 메시지를 라우팅하여 큐에 배치

2. Exchange

Producer로부터 받은 메시지를 큐에 전달
Exchange 유형
- Direct: 특정 라우팅 키와 정확히 일치하는 큐에 메시지를 전송
- Fanout: 모든 큐에 메시지를 브로드캐스트
- Topic: 라우팅 키 패턴을 기반으로 메시지를 특정 큐에 전달
- Headers: 메시지 헤더 속성에 따라 메시지를 라우팅

3. Routing Key

메시지를 전송할 때 Producer가 Exchange에 전달하는 키
Exchange는 이 Routing Key를 참고하여 어떤 큐에 메시지를 전달할지 결정

4. Queue

메시지를 일시적으로 저장하는 버퍼 역할
RabbitMQ의 큐는 FIFO(First In, First Out) 방식으로 동작하며, 메시지가 소비자에게 전달될 때까지 보관
각 큐는 여러 Consumer가 구독(수신)할 수 있으며, 메시지는 큐에 들어온 순서대로 전달
비동기적으로 동작하며, 여러 컨슈머가 동시에 메시지를 소비할 수 있다.
단, 하나의 메시지가 여러 소비자에게 중복으로 전달될수는 없다.
(동일한 메시지를 수신하려면 Fanout Exchange 방식으로 동작해야 함)

5. Binding

Exchange와 큐간의 관계를 정의, 일종의 라우팅 테이블
바인딩은 메시지를 라우팅할 때 어떤 조건으로 큐에 보낼지 정의하고 이를 위해 Binding key가 사용됨
Binding Key와 Routing Key가 일치하면 해당 큐로 메시지가 전달 (패턴 매칭 가능)

6. Consumer

큐에서 메시지를 가져와 처리하는 애플리케이션
RabbitMQ는 여러 소비자에게 메시지를 로드 밸런싱 할 수 있다
Consumer는 큐에서 메시지를 받아 처리하면 메시지에 대한 확인(ACK, acknowledgment)을 브로커에 전송
확인을 보내지 않으면, 브로커는 메시지를 재전송하거나 설정한 다른 Consumer에게 전달할 수 있다

7. Message Acknowledgment (메시지 확인)

메시지가 성공적으로 처리되었음을 RabbitMQ에 알리는 과정
만약 소비자가 메시지를 성공적으로 처리하지 못했다면, 메시지를 다시 큐에 넣어 다른 소비자가 처리하도록 할 수 있다.

주요 프로세스

Producer가 메시지와 Routing Key를 Exchange에 전송
Exchange가 Routing Key를 이용해 Binding Key가 일치하는 큐에 메시지 라우팅
Consumer가 큐에서 메시지를 가져와 처리하고, 성공적으로 처리되었음음 acknowledgment로 RabbitMQ에게 알림

추가로 알아야 할 용어

1. Prefetch Count

소비자가 받을 수 있는 최대 메시지 수를 설정
한 번에 많은 양의 메시지를 처리하지 않도록 하여 소비자의 성능 최적화

2. Virtual Host

RabbitMQ 서버 내의 논리적인 구획으로, 사용자 권한 관리와 리소스를 격리하는데 사용.
여러 애플리케이션이 독립적으로 RabbitMQ를 이용할 수 있게 해준다. (멀티태넌시 전략처럼)
하나의 RabbitMQ 서버 내에 여러 개의 가상 호스트를 설정하여 서로 다른 애플리케이션의 메시지를 격리할 수 있다.

3. Dead Letter Queue (DLQ)

메시지가 처리되지 못하거나 유효 기간이 지난 경우 별도의 큐로 이동하는 구조도 설정할 수 있다

참고 자료 & 이미지 출처
RabbitMQ를 이용한 비동기 아키텍처 한방에 해결하기

Kafka 장애 대비하기 (고가용성)

studyHub — Mon, 16 Feb 2026 20:58:22 +0900

kafka의 고가용성(시스템이 장애 상황에서도 멈추지 않고 정상적으로 서비스를 제공할 수 있는 능력)을 확보하는 방법을 이해하려면 아래 용어들을 먼저 알고있어야 한다.

노드, 브로커, 컨트롤러, 클러스터, 레플리케이션

노드(node)와 클러스터(cluster)란?

Node는 서버 1대라는 의미이고, Cluster는 여러 대의 서버가 연결되어 하나의 시스템처럼 동작하는 서버들의 집합이라는 뜻으로 널리 쓰인다. kafka에서 Node는 카프카가 설치되어 있는 서버를 의미하고, 클러스터는 노드들의 묶음이다.

노드(node)가 고장나게 되면 메시지를 전달하는 것 자체가 막히기 때문에, 서비스 장애가 일어나게 된다. 그래서 실무에서는 최소 3대의 노드(node)를 구성한다.

3대의 노드로 클러스터를 구성하면, 3대의 노드들이 서로 유기적으로 작동한다. 서로 들어오는 메시지를 나눠 저장하고, 서로의 복제본을 생성해 유지할 수도 있으며, 장애 시 시스템 전체가 중단없이 작동되게 만든다.

브로커(broker), 컨트롤러(controller)란?

kafka 서버는 크게 컨트롤러(controller)와 브로커(broker)로 구성되어 있다.

브로커(broker)란, 메시지를 저장하고 클라이언트의 요청을 처리하는 역할을 한다. (직원)

컨트롤러(controller)란, 브로커들간의 연동과 전반적인 클러스터의 상태를 총괄한다. (총관리자)

기본적으로 kafka 노드에서 broker는 9092번 포트에서 실행되고, controller는 9093번 포트에서 별개의 프로세스로 실행된다.

레플리케이션(replication)이란?

kafka에서의 replication은, 데이터의 안정성과 가용성을 높이기 위해 토픽의 파티션을 여러 노드에 복제하는 걸 의미한다.

레플리케이션 개수는 kafka 서버 수만큼 설정할 수 있지만, 실무에서는 레플리케이션 개수를 2나 3으로 설정해서 활용하는 편이다.

(한 클러스터의 노드가 7개여도 레플리케이션 개수는 2-3대 정도이다)

레플리케이션 설정을 하면 email.send 의 파티션 #0 을 다른 노드에도 복사해서 저장해둔다.

복제된 파티션들은 리더 파티션(원본)과 팔로워 파티션(복제본)으로 구분된다.

리더 파티션은 프로듀서나 컨슈머가 직접적으로 메시지를 쓰고 읽는 파티션이다.
반면 팔로워 파티션은 프로듀서나 컨슈머가 직접적으로 메시지를 쓰고 읽지 않는다.
팔로워 파티션은 리더 파티션의 메시지를 실시간으로 복제하며 유지한다.
리더 파티션에 장애가 발생하면 팔로워 파티션이 리더 역할로 승격한다.
이미 팔로워 파티션은 리더 파티션 내부의 메시지까지 복제해서 가지고 있으므로 정상적으로 이어서 처리할 수 있다.

실습

3대의 노드로 클러스터 구성하기

현업의 구성처럼 구축하려면 각각의 EC2 인스턴스에 kafka 노드를 따로따로 설치해야 하지만, 비용 절감과 실습의 편의를 위해 하나의 EC2 인스턴스에 3개의 kafka 노드를 한꺼번에 셋팅할 것이다.

1. Kafka 설정 수정하기

server.propertie를 수정하고, server2.properties, server3.properties로 복제하여 설정을 수정해준다.

2번 서버의 포트는 19092, 19093, 3번 서버는 29092, 29093으로 설정한다.

...

# kafka 노드를 식별하는 ID
node.id=1

# 클러스터를 구성할 컨트롤러의 노드 주소 목록을 설정
# (추가적인 노드의 컨트롤러를 19093, 29093번 포트에 실행시킬 예정)
controller.quorum.bootstrap.servers={EC2 Public IP}:9093,{EC2 Public IP}:19093,{EC2 Public IP}:29093

# 브로커, 컨트롤러 프로세스를 실행시킬 포트를 지정
# (브로커를 PLAINTEXT, 컨트롤러를 CONTROLLER라고 지칭)
listeners=PLAINTEXT://:9092,CONTROLLER://:9093

# 외부에서 접근할 수 있는 주소
advertised.listeners=PLAINTEXT://{EC2 Public IP}:9092,CONTROLLER://{EC2 Public IP}:9093

# kafka가 데이터(kafka 설정, 브로커가 받은 메시지, 로그 등)를 저장할 디렉터리 경로 설정
log.dirs=/tmp/kafka-logs-1

...

2. 첫 노드는 클러스터를 초기화하고, 나머지 노드는 해당 클러스터에 연결하기

cd .. # kafka 디렉터리로 이동

# kafka 종료하기
$ bin/kafka-server-stop.sh

# 처음 실행하는 kafka 노드는 아래 명령어로 실행
$ KAFKA_CLUSTER_ID="$(bin/kafka-storage.sh random-uuid)"
$ KAFKA_CONTROLLER_ID="$(bin/kafka-storage.sh random-uuid)"
$ bin/kafka-storage.sh format \
  -t $KAFKA_CLUSTER_ID \
	-c config/server.properties \
	--initial-controllers "1@localhost:9093:$KAFKA_CONTROLLER_ID"

# 추가로 연동시킬 kafka 노드는 아래 명령어로 실행 
# 주의 : server.properties가 아니라 server2.properties를 사용해야 한다.
$ bin/kafka-storage.sh format \
  -t $KAFKA_CLUSTER_ID \
	-c config/server2.properties \
	--no-initial-controllers

# 추가로 연동시킬 kafka 노드는 아래 명령어로 실행 
# 주의 : server.properties가 아니라 server3.properties를 사용해야 한다.
$ bin/kafka-storage.sh format \
  -t $KAFKA_CLUSTER_ID \
	-c config/server3.properties \
	--no-initial-controllers

3. kafka 노드 3대 전부 실행하기

로그 확인을 쉽게 하기 위해 EC2 창을 각각 띄워서 포그라운드로 kafka 노드를 실행시키자.

# kafka 노드 3대 실행하기
$ bin/kafka-server-start.sh config/server.properties 
$ bin/kafka-server-start.sh config/server2.properties 
$ bin/kafka-server-start.sh config/server3.properties

kafka 노드 3대가 전부 잘 실행됐는 지 확인하기 위해 EC2 창을 새로 띄워서 아래 명령어를 입력해보자.

# kafka 노드들의 브로커 실행 확인
$ lsof -i:9092 # 노드 1의 브로커
$ lsof -i:19092 # 노드 2의 브로커
$ lsof -i:29092 # 노드 3의 브로커

# kafka 노드들의 컨트롤러 실행 확인
$ lsof -i:9093 # 노드 1의 컨트롤러
$ lsof -i:19093 # 노드 2의 컨트롤러
$ lsof -i:29093 # 노드 3의 컨트롤러

4. 클러스터에 컨트롤러 등록하기

$ bin/kafka-metadata-quorum.sh \
	--command-config config/server2.properties \
	--bootstrap-server localhost:9092 \
	add-controller
	
$ bin/kafka-metadata-quorum.sh \
	--command-config config/server3.properties \
	--bootstrap-server localhost:9092 \
	add-controller

5. 컨트롤러끼리 잘 연동됐는 지 확인하기

$ bin/kafka-metadata-quorum.sh \
	--bootstrap-server localhost:9092 describe \
	--status

위 명령어를 입력했을 때 CurrentVoters 에 3개의 컨트롤러 정보가 찍히면 클러스터에 3개의 컨트롤러가 정상적으로 잘 등록된 것이다.

Kafka 서버 3대가 서로 잘 연동됐는 지 확인하기

Kafka 서버 3대가 서로 잘 연동됐는 지 확인하는 확실한 방법은, 아래와 같이 Kafka의 서버 개수만큼 토픽의 레플리케이션을 만들어보는 것이다.

토픽을 생성하면서 레플리케이션을 생성해보자.

$ bin/kafka-topics.sh --bootstrap-server localhost:9092 \
    --create --topic email.send \
    --partitions 1 \
    --replication-factor 3

그리고 토픽의 세부 정보를 조회했을 때, Replicas와 Isr에 3개의 숫자(1, 2, 3)가 다 있다면 3개의 Kafka 서버가 정상적으로 잘 연동되고 있다는 뜻이다.

# 토픽 세부 정보 조회하기
$ bin/kafka-topics.sh --bootstrap-server localhost:9092 \
  --describe --topic email.send

포트 번호를 바꿔 다른 kafka 서버에도 토픽의 파티션이 잘 복제됐는 지 확인해보면 동일한 결과가 출력된다.

PartitionCount : 해당 토픽의 파티션 수
ReplicationFactor : 해당 토픽의 레플리케이션 수 (원본 포함)
Partition : 파티션 번호
Leader : 해당 토픽의 리더 파티션을 가지고 있는 노드 id
Replicas : 해당 토픽의 파티션을 복제하기로 설정된 노드들의 id
Isr(In-Sync Replicas) : 리더 파티션과 똑같은 상태로 복제(동기화)가 완료된 노드들의 id (복제가 안됐으면 여기서 빠진다)

팔로워 파티션에 메시지를 넣으면 어떻게 될까?

리더 파티션은 프로듀서나 컨슈머가 직접적으로 메시지를 쓰고 읽는 파티션이다. 반면에 팔로워 파티션은 프로듀서나 컨슈머가 직접적으로 메시지를 쓰고 읽지 않는다.

라고 했는데, 실제로 팔로워 파티션에는 직접 메시지를 넣을 수 없는지 확인해보자.

토픽 상세 정보를 조회해서 리더 노드의 id를 알아낸후, 팔로워 파티션에 메시지를 넣어봤다.

$ bin/kafka-console-producer.sh --bootstrap-server localhost:19092 --topic email.send
  
# 위 명령어 입력 후 넣을 메시지 내용 입력하고 Enter 누르기
follower-message-1

그리고 각 노드에서 메시지를 조회해봤는데.. 모든 노드에서 삽입한 메시지가 잘 조회된다.

메시지가 모든 노드에 잘 복제된 것이다. 왜 그럴까?

사실은 Kafka 프로듀서는 메시지를 보내기 전에 해당 파티션의 리더가 누구인지 확인하고, 자동으로 리더 파티션에 메시지를 전송해준다. 이게 가능한 이유는 kafka 노드들끼리 서로 연동되어 있어서, 리더 파티션을 가진 Kafka 노드가 누군지에 대한 정보를 주고 받을 수 있기 때문이다.

리더 파티션에 장애가 발생하면 어떻게 될까?

리더 파티션에 장애가 발생하면 팔로워 파티션이 리더 역할(프로듀서로부터 메시지를 받고, 컨슈머가 메시지를 처리)을 대신 수행한다.

라고 했는데, 정말 그런지 확인해보자.

1번 노드가 리더 파티션을 가지고 있다. 그럼 1번 노드에 장애가 발생했다는 걸 가정하기 위해 1번 노드를 종료시켜보자.

포그라운드에서 실행 중이던 1번 노드 서버를 Ctrl + c로 종료시키면 된다.

다른 노드의 주소로 다시 토픽 정보를 조회해보면, Leader의 값이 2로 바뀐 것을 볼 수 있다.

리더 파티션에 장애가 발생해서 팔로워 파티션이 리더 역할을 대신 수행하게끔 리더 파티션으로 승격된 것이다.

리더 파티션이 2번 노드로 바뀌었다그

그리고 Isr 값을 보니 1번 노드가 빠져있고 2, 3번 노드만 있는 걸 확인할 수 있다. 1번 노드가 ISR에 빠졌다는 것은 1번 노드의 네트워크가 끊겼거나, 서버에 장애가 생겼거나, 아직 리더 파티션의 데이터와 동기화가 되지 않았다는 뜻이다.

메시지를 입력해보면 정상적으로 push가 된다.

그리고 죽인 1번 서버를 재기동하면, ISR에 1번이 다시 추가가 되어있고 새로 추가한 메시지도 동기화되어 누락없이 조회가 된다.

지금까지 레플리카로 Kafka 서버 3대를 운용함으로써, 특정 kafka 서버에 장애가 발생하더라도 시스템 전체가 중단되지 않고 지속적으로 서비스를 제공할 수 있다는 점을 알아봤다. 이러한 구성은 Kafka의 고가용성(시스템이 장애 상황에서도 멈추지 않고 정상적으로 서비스를 제공할 수 있는 능력)을 확보하기 위한 대표적인 방법으로, 브로커 간 복제를 통해 데이터 손실을 방지하고, 리더 파티션 장애 시에도 다른 팔로워 파티션이 자동으로 리더로 승격되며 kafka 서버가 지속적으로 운영될 수 있게 만든다.

※ Kafka 서버는 몇 대를 운용하는 게 좋을까?
kafka 서버를 1대로 운용한다고 해서 서비스를 아예 운영하지 못할 정도의 치명적인 장애가 발생하는 건 아니다.
초기 스타트업, 초기 단계 서비스, 개발/테스트 단계에서는 비용 절감이 중요하므로 1대를 추천한다.
서비스의 안정성이 중요한 중견 기업 또는 대기업은 장애 발생 시 손실이 크므로 최소 3대 이상을 추천한다.

Spring Boot에 Kafka 서버 3대를 연결해서 사용하는 방법

Producer와 Consumer의 `application.yaml` 파일에 모든 Kafka 브로커의 주소를 등록하면 된다.

이렇게 하면 특정 브로커에 장애가 발생해도, 애플리케이션은 다른 사용 가능한 브로커에 연결하여 연속적으로 메시지를 처리한다.

server:
  port: 0

spring:
  kafka:
    bootstrap-servers:
      - {Kafka 서버 IP 주소}:9092
      - {Kafka 서버 IP 주소}:19092
      - {Kafka 서버 IP 주소}:29092
    consumer:
      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      value-deserializer: org.apache.kafka.common.serialization.StringDeserializer
      auto-offset-reset: earliest

참고 자료 & 이미지 출처
실전에서 바로 써먹는 kafka 입문