CUSUMlog

Etherium의 상태 저장 - Trie에서 Merkle Patricia Trie까지

cusum26 — Tue, 2 Jun 2026 17:53:43 +0900

텍스트 기반 검색을 공부하다 보면 유독 Trie라는 자료구조를 자주 만나게 된다. 특히 문자열 검색, 자동완성, 사전 검색 같은 기능에서 Trie는 빠지지 않는다.

RedisSearch나 ElasticSearch 같은 대형 검색 엔진에서도 term lookup, prefix matching 최적화에 Trie를 활용하고 있다고 한다.

서비스/엔진	Trie 활용 방식
Redis Stack / RediSearch	autocomplete suggestion을 trie 기반 자료구조에 저장. prefix 입력에 대한 추천어 검색에 사용
Elasticsearch / Apache Lucene	전문 검색은 기본적으로 inverted index 기반이지만, term dictionary나 prefix 탐색에 FST 같은 Trie 계열 압축 구조를 사용
Solr / Apache Lucene	Lucene 기반이라 Elasticsearch와 비슷하게 term lookup, prefix 검색 등에 FST/term dictionary 구조 활용
검색 자동완성 시스템	검색어 추천, command completion, prefix matching에 Trie 또는 compressed Trie 활용
라우팅/네트워크 시스템	IP prefix matching에 Patricia Trie/Radix Tree 계열 활용

뿐만 아니라 블록체인, 이더리움에서도 Merkle Patricia Trie라는 자료구조가 핵심적으로 사용된다.

텍스트 검색부터 블록체인 주소 검색까지 대용량의 데이터를 빠르게 접근하는 Trie 구조와 이를 기반으로 한 Patricia Trie, Merkle Tree, Merkle Patricia Trie에 대해 알아보자.

1. Trie란 무엇인가?

Trie는 문자열을 저장하기 위한 트리 기반 자료구조다. 핵심 아이디어는 간단하다.

여러 문자열이 공통으로 가지는 접두사(prefix)를 한 번만 저장한다.

예를 들어 다음과 같은 단어들이 있다고 하자.

car
cat
can
dog

일반적인 방식으로 저장하면 각 문자열을 따로 저장한다.

car
cat
can
dog

이 경우 car, cat, can은 모두 앞의 ca를 공유하지만, 각각의 문자열 안에 c, a가 반복해서 저장된다.

Trie는 이를 다음과 같이 저장한다.

(root)
 ├─ c
 │  └─ a
 │     ├─ r  → car
 │     ├─ t  → cat
 │     └─ n  → can
 └─ d
    └─ o
       └─ g  → dog

car, cat, can이 공유하는 c → a 경로를 한 번만 저장하고, 이후 달라지는 문자부터 가지를 나눈다.

즉, Trie의 핵심은 다음과 같다.

공통 접두사는 공유하고, 달라지는 부분부터 분기한다.

2. Trie가 효율적인 이유

Trie의 장점은 크게 두 가지다.

첫째, 공통 접두사를 공유하기 때문에 중복 저장을 줄일 수 있다. 특히 비슷한 접두사를 가진 문자열이 많을수록 효과가 크다.

둘째, 검색 시간이 문자열의 개수보다 검색하려는 문자열의 길이에 비례한다.

예를 들어 cat을 찾는다고 하면, Trie에서는 다음 경로만 따라가면 된다.

c → a → t

단어가 10개 있든 100만 개 있든, cat을 검색할 때 확인하는 문자는 3개다. 따라서 검색 시간복잡도는 보통 O(L) 같이 표현된다. 여기서 L은 검색하려는 문자열의 길이다.

이러한 특성 때문에 Trie는 자동완성 기능에 적합하다. 예를 들어 ca로 시작하는 단어를 찾고 싶다면, 먼저 c → a 노드까지 이동한 뒤 그 아래에 있는 단어들을 모두 탐색하면 된다.

ca
├─ r → car
├─ t → cat
└─ n → can

따라서 prefix 검색을 빠르게 수행할 수 있다.

3. Trie의 단점

Trie가 항상 메모리 효율적인 것은 아니다. 일반 Trie는 문자 하나마다 노드를 만든다. 그래서 문자열들이 공통 접두사를 많이 공유하지 않거나, 각 노드가 많은 포인터 또는 map 구조를 가진다면 오히려 메모리 사용량이 커질 수 있다.

예를 들어 다음과 같은 단어들이 있다고 해보자.

apple
banana
coffee
dragon

이 단어들은 앞부분이 거의 겹치지 않는다. 이 경우 Trie의 접두사 공유 이점은 줄어든다.

또한 일반 Trie에서는 중간에 갈림길이 없는 경로도 문자 단위로 노드를 계속 만든다.

i → n → t → e → r → n → a → l

만약 중간에 분기점이 없다면, 굳이 문자 하나마다 노드를 둘 필요가 있을까? 이런 문제의식에서 Patricia Trie가 등장한다.

4. Patricia Trie란 무엇인가?

Patricia Trie는 일반 Trie를 압축한 구조다. 보통 압축 Trie 또는 Radix Tree 계열로 설명된다. 핵심 아이디어는 다음과 같다.

자식이 하나뿐인 연속 경로를 하나로 압축한다.

예를 들어 다음 단어들이 있다고 하자.

bear
bell
bid
bull
buy

일반 Trie에서는 문자 하나마다 노드를 만든다.

(root)
 └─ b
    ├─ e
    │  ├─ a
    │  │  └─ r
    │  └─ l
    │     └─ l
    ├─ i
    │  └─ d
    └─ u
       ├─ l
       │  └─ l
       └─ y

그런데 a → r, l → l, i → d처럼 중간에 갈림길이 없는 경로들이 있다. Patricia Trie는 이런 부분을 압축한다.

(root)
 └─ b
    ├─ e
    │  ├─ ar → bear
    │  └─ ll → bell
    ├─ id → bid
    └─ u
       ├─ ll → bull
       └─ y  → buy

즉, 일반 Trie가 문자 단위로 노드를 만든다면, Patricia Trie는 분기가 없는 문자열 구간을 하나의 간선 또는 노드로 저장한다.

정리하면 다음과 같다.

일반 Trie:
문자 하나마다 노드를 만든다.

Patricia Trie:
갈림길이 없는 연속 경로를 압축한다.

5. Patricia Trie의 장단점

Patricia Trie의 가장 큰 장점은 노드 수를 줄일 수 있다는 점이다.

예를 들어 다음 문자열들이 있다고 하자.

international
internet
internal

이 단어들은 inter라는 공통 prefix를 가진다. Patricia Trie에서는 다음과 같이 압축해서 표현할 수 있다.

(root)
 └─ inter
    ├─ national
    ├─ net
    └─ nal

이렇게 하면 일반 Trie보다 불필요한 중간 노드를 줄일 수 있고, 메모리 사용량도 줄일 수 있다.

하지만 단점도 있다. 구현이 일반 Trie보다 복잡하다. 일반 Trie는 문자 하나씩 따라가면 되지만, Patricia Trie는 압축된 문자열 조각을 비교해야 한다. 또한 삽입 과정에서 기존 경로와 새 문자열이 중간에서 갈라지면 노드를 쪼개야 한다.

예를 들어 기존에 internet이 있고 새로 internal을 삽입한다고 하자.

internet
internal

두 단어는 inter까지 같고, 그 뒤부터 net, nal로 갈라진다. Patricia Trie는 이 공통 지점을 찾아 노드를 분리해야 한다.

따라서 Patricia Trie는 메모리 효율성은 좋아지지만, 삽입과 삭제 구현은 더 복잡해진다.

6. Merkle Tree란 무엇인가?

Merkle Patricia Trie를 이해하려면 Merkle Tree도 알아야 한다.

Merkle Tree는 각 노드가 해시값을 가지는 트리 구조다. 리프 노드는 데이터의 해시를 가지고, 부모 노드는 자식 노드들의 해시를 다시 해시해서 만든다.

        Root Hash
        /       \
   Hash A       Hash B
   /   \        /   \
data1 data2  data3 data4

Merkle Tree의 핵심은 다음과 같다.

전체 데이터를 직접 비교하지 않아도, 루트 해시만 비교하면 데이터가 변경되었는지 확인할 수 있다.

예를 들어 data3이 바뀌면 Hash B가 바뀌고, 결국 Root Hash도 바뀐다. 즉, Merkle Tree는 데이터 무결성을 검증하는 데 유용하다.

또한 특정 데이터가 트리에 포함되어 있다는 것을 증명할 때도 전체 데이터를 다 제공할 필요가 없다. 해당 데이터에서 루트까지 올라가는 경로에 필요한 해시들만 제공하면 된다. 이를 Merkle Proof라고 한다.

7. Merkle Patricia Trie란 무엇인가?

Merkle Patricia Trie는 이름 그대로 Merkle Tree와 Patricia Trie의 특징을 결합한 자료구조다. 간단히 말하면 다음과 같다.

Patricia Trie:
key를 prefix 기반으로 효율적으로 저장하고 검색한다.

Merkle Tree:
각 노드에 해시를 붙여 데이터 무결성을 검증한다.

Merkle Patricia Trie:
key-value 데이터를 효율적으로 저장하면서,
각 노드의 해시를 통해 전체 상태의 무결성과 포함 여부를 검증한다.

즉, Merkle Patricia Trie는 단순한 검색 자료구조가 아니라, 검색과 검증을 동시에 지원하는 자료구조다.

예를 들어 다음과 같은 key-value가 있다고 하자.

do   → verb
dog  → puppy
doge → coin

Patricia Trie처럼 공통 prefix를 공유한다.

do
├─ 끝 → verb
└─ g
   ├─ 끝 → puppy
   └─ e → coin

여기에 Merkle Tree처럼 각 노드에 해시를 붙인다.

Hash(root)
└─ Hash(do)
   ├─ Hash(value: verb)
   └─ Hash(g)
      ├─ Hash(value: puppy)
      └─ Hash(e → coin)

이제 doge → coin 값이 바뀌면, 그 값이 포함된 경로의 해시들이 바뀌고 최종적으로 root hash도 바뀐다.

따라서 루트 해시 하나로 전체 상태가 바뀌었는지 확인할 수 있다.

8. 이더리움에서 Merkle Patricia Trie를 사용하는 이유

이더리움에는 수많은 계정 상태가 존재한다.

예를 들어 다음과 같은 데이터들이 있다.

주소 A → 잔액 10 ETH
주소 B → 잔액 3 ETH
주소 C → nonce 5
주소 D → 스마트 컨트랙트 코드 정보

블록체인에서는 이 상태 데이터를 단순히 저장하는 것만으로는 부족하다. 중요한 것은 다음이다.

이 상태가 정말 블록에 기록된 상태와 일치하는지 검증할 수 있어야 한다.

이더리움은 전체 계정 상태를 Merkle Patricia Trie에 저장하고, 그 루트 해시를 블록 헤더에 기록한다.

Block Header
└─ stateRoot

이 stateRoot는 현재 이더리움 전체 상태를 대표하는 해시값이다.

계정 하나의 잔액이 바뀌어도 관련된 노드의 해시가 바뀌고, 최종적으로 stateRoot도 바뀐다. 따라서 블록 헤더의 stateRoot를 통해 해당 블록 시점의 전체 상태를 검증할 수 있다.

9. 이더리움 State Trie의 key와 value

이더리움의 State Trie는 대략 다음과 같이 이해할 수 있다.

key   = 계정 주소
value = 해당 주소의 계정 상태

다만 정확히는 주소 자체를 그대로 key로 쓰기보다는, 주소를 해시한 값을 Trie의 key로 사용한다고 보면 된다.

각 계정의 상태는 단순히 잔액만 의미하지 않는다. 이더리움의 account state에는 다음 정보들이 포함된다.

Account State
├─ nonce
├─ balance
├─ storageRoot
└─ codeHash

각 항목의 의미는 다음과 같다.

nonce:
해당 계정이 보낸 트랜잭션 수 또는 컨트랙트 생성 횟수와 관련된 값

balance:
계정의 ETH 잔액

storageRoot:
스마트 컨트랙트의 내부 저장소를 가리키는 Storage Trie의 루트 해시

codeHash:
스마트 컨트랙트 코드의 해시

즉, 이더리움의 State Trie는 다음과 같은 형태로 볼 수 있다.

address A → account state A
address B → account state B
address C → account state C

그리고 어떤 주소가 스마트 컨트랙트 계정이라면, 그 계정의 내부 저장소는 storageRoot를 통해 별도의 Storage Trie로 연결된다.

10. 스마트 컨트랙트의 세부 저장소는 어디에 저장될까?

스마트 컨트랙트는 상태 변수를 가질 수 있다.

예를 들어 Solidity 코드에서 다음과 같은 변수가 있다고 하자.

uint256 totalSupply;
mapping(address => uint256) balances;

이 값들은 컨트랙트 코드 내부에 직접 저장되는 것이 아니다. 컨트랙트 작성자가 별도로 어딘가에 저장하는 것도 아니다. 컨트랙트별 세부 저장소는 해당 컨트랙트 계정의 storageRoot가 가리키는 별도의 Storage Trie에 저장된다. 그리고 이 데이터는 이더리움 노드들이 자신의 상태 데이터베이스에 저장한다.

구조를 단순화하면 다음과 같다.

Ethereum Node
└─ State Database
   └─ State Trie
      └─ key: contract address
         value: Account State
            ├─ nonce
            ├─ balance
            ├─ storageRoot ──→ Storage Trie
            └─ codeHash

그리고 Storage Trie는 다음과 같은 형태다.

Storage Trie of Contract A
├─ key: storage slot 0 → value
├─ key: storage slot 1 → value
├─ key: storage slot 2 → value
└─ ...

즉, 컨트랙트 A의 상태 변수들은 컨트랙트 A의 Storage Trie에 저장된다.

11. 컨트랙트 storage가 변경되면 어떤 일이 일어날까?

예를 들어 다음 코드가 실행된다고 하자.

balances[msg.sender] = 100;

이 코드는 EVM에서 실행되며, storage 값을 변경하는 명령으로 이어진다. 이때 이더리움 노드는 실행 결과에 따라 해당 컨트랙트의 Storage Trie를 갱신한다.

흐름은 다음과 같다.

1. EVM이 balances[msg.sender]가 저장될 storage slot을 계산한다.
2. 해당 컨트랙트의 Storage Trie에서 그 slot 값을 100으로 변경한다.
3. Storage Trie의 root hash가 변경된다.
4. Account State의 storageRoot가 변경된다.
5. State Trie의 root hash, 즉 stateRoot가 변경된다.
6. 변경된 stateRoot가 블록 헤더에 기록된다.

이 구조 덕분에 이더리움은 스마트 컨트랙트의 세부 상태 변경까지 최종적으로 하나의 stateRoot에 반영할 수 있다.

12. 전체 구조 정리

이더리움의 상태 저장 구조를 한 번에 정리하면 다음과 같다.

Block Header
└─ stateRoot
   └─ State Trie
      ├─ address A → Account State
      │              ├─ nonce
      │              ├─ balance
      │              ├─ storageRoot
      │              └─ codeHash
      │
      └─ contract address B → Account State
                             ├─ nonce
                             ├─ balance
                             ├─ storageRoot ──→ Storage Trie
                             │                  ├─ slot 0 → value
                             │                  ├─ slot 1 → value
                             │                  └─ ...
                             └─ codeHash

핵심은 다음이다.

주소를 key로 해서 계정 상태를 찾는다.
계정 상태에는 balance, nonce, storageRoot, codeHash가 들어 있다.
컨트랙트의 내부 저장소는 storageRoot가 가리키는 별도 Storage Trie에 저장된다.
모든 변경은 최종적으로 stateRoot에 반영된다.

13. 결론

Trie는 문자열이나 key를 prefix 기반으로 효율적으로 저장하고 검색하기 위한 자료구조다. 일반 Trie는 문자 하나마다 노드를 만들지만, Patricia Trie는 갈림길이 없는 경로를 압축하여 노드 수를 줄인다.

Merkle Tree는 각 노드에 해시를 붙여 데이터의 무결성을 검증할 수 있게 한다. Merkle Patricia Trie는 이 둘을 결합하여, key-value 데이터를 효율적으로 저장하면서도 전체 데이터의 변경 여부와 특정 데이터의 포함 여부를 검증할 수 있게 한다.

이더리움은 이러한 Merkle Patricia Trie를 사용하여 전체 계정 상태를 관리한다. 주소를 key로 사용해 account state를 찾고, account state 안의 storageRoot를 통해 스마트 컨트랙트별 세부 저장소를 다시 찾는다. 그리고 이 모든 상태 변화는 최종적으로 블록 헤더의 stateRoot에 반영된다.

따라서 Merkle Patricia Trie는 이더리움에서 단순한 저장 자료구조가 아니라, 상태 저장, 검색, 무결성 검증, 포함 증명을 동시에 가능하게 하는 핵심 자료구조라고 볼 수 있다.

Codex Skill 등록하기 - bcpprm 사례로 익히는 워크플로 자동화 가이드

cusum26 — Sat, 23 May 2026 00:02:09 +0900

개발을 하다 보면 반복해서 수행하는 작업이 생깁니다. 변경 사항을 확인하고, 브랜치를 만들고, 커밋 메시지를 정리한 뒤, 원격 저장소에 푸시하고 PR까지 생성하는 흐름도 그중 하나입니다.

이런 반복 작업을 매번 자연어로 길게 설명하는 대신, Codex가 일정한 규칙에 따라 수행하도록 만들 수 있는 방법이 Skill입니다.

이 글에서는 제가 실제로 등록한 bcpprm Skill을 사례로 삼아, Codex에 새로운 Skill을 등록하는 전체 과정을 정리합니다. 이후 다른 자동화 Skill을 만들 때에도 그대로 참고할 수 있도록 기록합니다.

예시로 사용하는 bcpprm는 Branch → Commit → Push → Pull Request 흐름을 지원하도록 만든 Skill입니다.

먼저 결정할 것: Skill인가, Plugin인가?

Codex에 새로운 동작을 추가하려고 할 때 가장 먼저 구분해야 하는 것은 Skill과 Plugin의 역할입니다.

Skill

Skill은 특정 요청이 들어왔을 때 Codex가 따라야 하는 작업 지침입니다. 사용자가 자연어로 특정 작업을 요청하면, Skill에 정의된 절차와 규칙을 기준으로 작업을 수행합니다.

예를 들어 다음과 같은 요청을 반복적으로 처리하고 싶다면 Skill이 적합합니다.

bcpprm 해줘

이 요청이 들어왔을 때 Codex가 Git 상태를 확인하고, 브랜치·커밋·Push·PR 생성 절차를 정해진 규칙대로 수행하도록 만들 수 있습니다.

Plugin

Plugin은 Skill뿐 아니라 assets, metadata 등 여러 구성 요소를 묶어 관리하는 패키지에 가깝습니다. 하나의 단순한 워크플로를 추가하려는 상황이라면 오히려 구조가 과해질 수 있습니다.

무엇을 선택해야 할까?

필요한 기능	권장 방식
브랜치 생성, 커밋, PR 작성처럼 정해진 작업 절차 자동화	Skill
여러 기능과 리소스를 함께 배포·관리하는 패키지	Plugin 고려

bcpprm 역시 처음에는 Plugin 형태를 고려했지만, 최종적으로는 자연어 요청에 반응해 하나의 Git/PR 워크플로를 수행하는 기능이므로 Skill로 정리했습니다.

Codex Skill의 기본 설치 위치와 구조

새로운 Skill은 사용자 홈 디렉터리 아래의 Codex Skill 경로에 둡니다.

~/.codex/skills/<skill-name>/

bcpprm의 실제 설치 경로는 다음과 같습니다.

/Users/username/.codex/skills/bcpprm/

Skill의 최소 구조는 매우 단순합니다.

~/.codex/skills/<skill-name>/
└── SKILL.md

다만 브랜치명 규칙, 커밋 메시지 규칙, PR 템플릿처럼 별도로 관리할 설정이 있다면 assets/ 디렉터리를 함께 두는 방식이 좋습니다.

~/.codex/skills/<skill-name>/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

bcpprm는 다음 구조로 구성했습니다.

/Users/username/.codex/skills/bcpprm/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

이 구조의 핵심은 동작 지침과 규칙 데이터를 분리하는 것입니다. Skill의 전체 흐름은 SKILL.md가 담당하고, 반복적으로 수정될 수 있는 Git·PR 규칙은 assets/에서 별도로 관리합니다.

Step 1: Skill 이름 정하기

Skill 이름은 이후 여러 위치에서 동일한 식별자로 사용됩니다.

Skill 디렉터리 이름
SKILL.md frontmatter의 name
사용자가 자연어 요청에서 언급할 키워드

따라서 이름은 짧고, 기억하기 쉽고, 요청문에 자연스럽게 넣을 수 있어야 합니다.

이름을 정할 때의 기준

영문 소문자 사용을 권장한다.
공백 없이 작성한다.
수행하는 작업을 연상할 수 있는 이름으로 짓는다.
너무 일반적인 단어보다는 고유한 트리거가 되는 이름이 좋다.

bcpprm는 Branch, Commit, Push, Pull Request 흐름을 빠르게 떠올릴 수 있는 이름으로 정했습니다.

bcpprm

이후 사용자는 다음처럼 요청할 수 있습니다.

bcpprm 해줘

Step 2: 핵심 파일 SKILL.md 만들기

SKILL.md는 Skill의 핵심 파일입니다. Codex가 언제 이 Skill을 적용해야 하는지, 적용된 뒤 어떤 순서와 규칙으로 작업해야 하는지를 정의합니다.

가장 기본적인 형태는 다음과 같습니다.

---
name: myskill
description: Use when ...
---

# My Skill

이 스킬이 수행할 작업과 규칙을 작성합니다.

Frontmatter에서 중요한 두 필드

필드	역할
name	Skill의 식별자
description	어떤 사용자 요청에서 Skill을 적용해야 하는지 설명하는 트리거 정의

여기서 특히 중요한 것은 description입니다. Skill이 잘 만들어져 있어도 사용자의 요청과 연결되지 않으면 동작을 기대하기 어렵습니다. 따라서 실제 사용자가 말할 법한 표현을 구체적으로 포함하는 것이 좋습니다.

bcpprm의 frontmatter 예시

---
name: bcpprm
description: Use when the user mentions `bcpprm`, tries `/bcpprm`, or asks to create a branch, commit, push, and draft or create a pull request ...
---

이 정의에는 다음 의도가 담겨 있습니다.

사용자가 bcpprm라는 이름을 직접 말했을 때 감지한다.
사용자가 /bcpprm처럼 입력했을 때도 관련 요청으로 해석할 수 있게 한다.
Skill 이름을 모르더라도 “브랜치 만들고 커밋하고 PR 올려줘” 같은 자연어 요청을 감지할 여지를 둔다.

단, 여기서 주의해야 할 점이 있습니다. description에 /bcpprm을 포함했다고 해서, 이것이 곧바로 Codex의 내장 Slash Command로 등록되는 것은 아닙니다. 이 차이는 뒤에서 다시 다루겠습니다.

Step 3: Skill 본문에 실제 워크플로 정의하기

Frontmatter가 “언제 이 Skill을 사용할 것인가”를 정의한다면, 본문은 “Skill이 선택된 뒤 무엇을 할 것인가”를 정의합니다.

Skill 본문에는 최소한 다음 요소를 담는 것이 좋습니다.

작업 수행 순서
반드시 지켜야 하는 동작 규칙
트리거 예시
최종 출력 또는 완료 조건
위험한 작업에 대한 승인 규칙

재사용 가능한 기본 템플릿은 다음과 같이 만들 수 있습니다.

# Skill Name

이 스킬은 다음 순서로 동작합니다.

1. 현재 상태 확인
2. 필요한 규칙 파일 읽기
3. 작업 내용 결정
4. 변경 작업 실행
5. 실행 결과 보고

## 필수 동작

- ...

## 트리거 예시

- `myskill 해줘`

## 완료 조건

- ...

bcpprm에 정의한 작업 흐름

bcpprm는 Git 변경 사항을 PR로 연결하는 Skill이므로, 아래와 같은 순서로 동작하도록 구성했습니다.

현재 Git 상태와 변경 사항을 확인한다.
assets/ 아래의 규칙 파일을 읽는다.
변경 내용을 바탕으로 브랜치명을 결정한다.
스테이징 대상 파일을 확인한 뒤 git add를 수행한다.
규칙에 맞는 커밋 메시지를 생성하고 커밋한다.
원격 저장소로 브랜치를 Push한다.
이미 생성된 PR이 있는지 확인한다.
PR이 없다면 정해진 형식에 따라 새 PR을 생성한다.

이처럼 본문에는 단순히 “PR을 만들어라”가 아니라, 실제 작업에서 놓치면 안 되는 상태 확인과 중복 확인 과정까지 포함시키는 것이 중요합니다.

Step 4: 변할 수 있는 규칙은 assets/로 분리하기

Skill을 작성하다 보면 동작 자체는 같지만, 팀이나 프로젝트에 따라 달라지는 규칙이 있습니다.

예를 들어 다음 항목들은 자주 변경될 수 있습니다.

브랜치명 패턴
커밋 메시지 컨벤션
PR 제목 형식
PR 본문 섹션
기본 대상 브랜치

이런 내용을 SKILL.md 본문에 모두 직접 적어두면, 규칙이 변경될 때마다 동작 설명까지 함께 수정해야 합니다. 반대로 규칙을 별도 asset으로 분리하면 Skill의 흐름은 유지하면서 설정만 바꿀 수 있습니다.

권장하는 asset 구성

파일	용도
conventions.json	Codex가 구조적으로 참고할 수 있는 규칙 데이터
conventions.md	사람이 읽고 수정하기 쉬운 설명과 예시

bcpprm의 규칙 예시

bcpprm에서는 다음과 같은 규칙을 asset으로 관리했습니다.

항목	규칙
브랜치명	type/summary
커밋 메시지	type: summary
PR 제목	[TYPE] 제목
기본 대상 브랜치	main
PR 본문 섹션	요약, 작업내용, 변경파일, 검증, 비고

왜 JSON과 Markdown을 함께 두는가?

conventions.json은 구조가 명확하기 때문에 자동화 규칙으로 참고하기 좋습니다. 반면 conventions.md는 사람이 컨벤션의 배경과 예시를 이해하거나 직접 수정할 때 훨씬 편리합니다.

즉, 두 파일은 중복이 아니라 목적이 다릅니다.

JSON: 작업 수행 시 참조할 수 있는 명시적인 규칙
Markdown: 규칙을 유지보수하는 사람을 위한 설명서

각 파일의 역할을 명확히 나누기

Skill을 만들 때 파일 수가 늘어나면 “어떤 내용을 어디에 두어야 하는가?”가 애매해질 수 있습니다. bcpprm를 기준으로 파일의 책임을 정리하면 다음과 같습니다.

파일	책임	bcpprm에서의 역할
SKILL.md	Codex가 수행할 워크플로와 사용 조건 정의	Git 상태 확인부터 PR 생성까지의 절차 정의
assets/conventions.json	기계적으로 읽기 쉬운 규칙 데이터	브랜치명·커밋 메시지·PR 형식 정의
assets/conventions.md	사람을 위한 설명과 예시	컨벤션의 의미와 작성 예시 기록

이렇게 책임을 분리해 두면 새로운 Skill을 만들 때에도 같은 패턴을 재사용할 수 있습니다.

예를 들어 배포 자동화 Skill이라면 SKILL.md에 배포 절차를 두고, assets/에는 대상 환경, 브랜치 정책, 검증 체크리스트 등을 둘 수 있습니다.

Step 5: 등록 후에는 새 세션에서 테스트하기

Skill 파일을 생성했다고 해서 현재 열려 있는 Codex 세션이 즉시 새로운 Skill을 반영한다고 가정하면 안 됩니다. 이미 실행 중이던 세션은 새로 추가된 Skill을 다시 읽지 않을 수 있기 때문입니다.

따라서 Skill 등록 이후에는 새 Codex 세션을 열어 테스트하는 과정을 권장합니다.

테스트 순서

새로운 Codex 세션을 연다.
Skill 이름을 직접 포함한 요청을 보낸다.
이름 없이 작업 의도만 담은 자연어 요청도 테스트한다.
실제로 정의한 규칙 파일과 워크플로가 반영되는지 확인한다.

bcpprm 테스트 요청 예시

bcpprm 해줘

bcpprm 규칙대로 진행해줘

현재 변경 사항으로 브랜치 만들고 커밋한 뒤 PR까지 작성해줘

마지막 요청까지 잘 처리된다면, Skill 이름에만 의존하지 않고 작업 의도에 따라 선택될 수 있도록 description이 충분히 작성되어 있는지 확인하는 데 도움이 됩니다.

등록 여부를 확인하는 방법

테스트 전에 가장 먼저 확인할 것은 실제 파일이 올바른 위치에 생성되어 있는지입니다.

bcpprm의 경우 확인 대상 파일은 다음과 같습니다.

/Users/username/.codex/skills/bcpprm/SKILL.md
/Users/username/.codex/skills/bcpprm/assets/conventions.json
/Users/username/.codex/skills/bcpprm/assets/conventions.md

그 다음에는 Codex 환경에서 Skill 목록에 표시되는지 확인하고, 새 세션에서 트리거 요청을 실행합니다.

확인 체크포인트

폴더명이 SKILL.md의 name과 일치하는가?
SKILL.md가 올바른 경로에 존재하는가?
description에 실제 사용할 요청 표현이 포함되어 있는가?
asset 파일을 읽도록 본문에 명시되어 있는가?
새 세션에서 Skill이 적용되는가?

Codex 버전이나 실행 환경에 따라 Skill 목록을 확인하는 UI나 명령 노출 방식은 달라질 수 있으므로, 최종적으로는 새 세션에서 실제 요청이 의도한 흐름으로 처리되는지를 기준으로 판단하는 것이 가장 안전합니다.

모두 확인 후 입력창에 /skills -> List skills 결과, bcpprm이 보이면 정상적으로 등록된 것입니다.

원격 저장소를 변경하는 Skill에는 승인 규칙을 넣자

bcpprm처럼 Git Push 또는 PR 생성을 포함하는 Skill은 단순한 문서 요약 Skill과 성격이 다릅니다. 실행 결과가 로컬에만 머물지 않고 원격 저장소에 영향을 주기 때문입니다.

따라서 다음과 같은 작업을 수행하는 Skill에는 승인 규칙과 실패 대응 방법을 명시하는 것이 좋습니다.

git push
git push --force-with-lease
gh pr create
배포 실행
원격 리소스 수정 또는 삭제

GitHub CLI(gh)가 필요한 이유

bcpprm의 마지막 단계는 GitHub Pull Request를 확인하고, 필요한 경우 새 PR을 생성하는 작업입니다. git 명령어만으로 브랜치 생성, 커밋, 원격 저장소 Push까지는 처리할 수 있지만, GitHub 위에서 PR을 조회하거나 생성하려면 GitHub 서비스와 상호작용할 수 있는 도구가 필요합니다.

이때 사용하는 도구가 GitHub CLI, 즉 gh입니다. gh를 이용하면 브라우저를 열어 수동으로 PR을 작성하지 않아도 터미널에서 인증 상태 확인, 기존 PR 조회, 새 PR 생성까지 이어서 수행할 수 있습니다.

명령어	역할
gh auth status	현재 환경에서 GitHub 계정 인증 상태 확인
gh pr list --head <branch-name>	해당 브랜치로 이미 생성된 PR이 있는지 확인
gh pr create --base main --title "[TYPE] 제목" --body-file <pr-body-file>	규칙에 맞는 제목과 본문으로 PR 생성

예를 들어 인증 상태는 다음 명령으로 확인할 수 있습니다.

gh auth status

현재 브랜치로 이미 생성된 PR이 있는지는 다음처럼 확인할 수 있습니다.

gh pr list --head <branch-name>

기존 PR이 없고 새로 생성해야 한다면 다음과 같이 대상 브랜치, 제목, 본문을 지정할 수 있습니다.

gh pr create --base main --title "[TYPE] 제목" --body-file <pr-body-file>

bcpprm에서 git과 gh가 담당하는 역할

bcpprm는 로컬 변경 사항을 GitHub PR까지 연결하는 워크플로입니다. 이 과정에서 git과 gh는 서로 다른 범위를 담당합니다.

도구	담당 범위
git	로컬 변경 사항 확인, 브랜치 생성, 스테이징, 커밋, 원격 저장소 Push
gh	GitHub 인증 상태 확인, 기존 PR 조회, 새 PR 생성

전체 흐름은 다음처럼 이어집니다.

git status
→ git checkout -b <branch-name>
→ git add <files>
→ git commit -m "<commit-message>"
→ git push -u origin <branch-name>
→ gh auth status
→ gh pr list --head <branch-name>
→ gh pr create ...

단, 모든 경우에 gh pr create를 바로 실행하는 것은 적절하지 않습니다. 이미 같은 브랜치로 생성된 PR이 있다면 새 PR을 중복 생성하는 대신 기존 PR을 안내하거나 갱신된 커밋이 반영되었는지 확인해야 합니다.

bcpprm에 적용할 수 있는 안전 규칙

Push 또는 PR 생성 전에 사용자 승인을 받도록 한다.
강제 Push가 필요하다면 일반 Push보다 더 엄격하게 확인한다.
PR 작업 전에 gh auth status로 GitHub CLI 인증 상태를 점검할 수 있도록 한다.
gh pr create 실행 전, 현재 브랜치에 연결된 기존 PR이 있는지 먼저 확인한다.
인증 실패나 권한 부족으로 PR 생성이 실패하면 로그인 상태와 저장소 접근 권한을 우선 점검한다.

이러한 규칙은 작업을 느리게 만들기 위한 것이 아니라, 자동화 범위가 커질수록 발생할 수 있는 원격 저장소 변경 실수와 중복 작업을 통제하기 위한 장치입니다.

bcpprm 테스트

branch 명명 규칙부터 commit, PR 메시지 convention 모두 지켜서 workflow를 제대로 수행한 것을 확인할 수 있습니다.

Skill과 Slash Command는 다르다

Skill을 처음 등록할 때 가장 혼동하기 쉬운 부분은 Slash Command와의 차이입니다.

Skill은 자연어 요청을 바탕으로 특정 작업 지침을 적용하는 방식입니다. 반면 Slash Command는 별도로 등록되거나 제품이 제공하는 명령 체계입니다.

따라서 Skill 이름이 bcpprm라고 해서 자동으로 다음 명령이 내장 명령처럼 동작하는 것은 아닙니다.

/bcpprm

하지만 SKILL.md의 description에 관련 표현을 넣고, 자연어 요청으로 다음과 같이 사용할 수 있습니다.

bcpprm 해줘

정리하면 bcpprm의 현재 형태는 다음과 같습니다.

구분	해당 여부
Codex Skill	O
Plugin	X
내장 Slash Command	X
자연어 트리거 기반 워크플로	O

Plugin으로 시작했다가 Skill만 남기고 싶을 때

처음에는 구조를 넓게 잡아 Plugin으로 만들었다가, 실제로는 Skill 하나만 있으면 충분하다고 판단할 수도 있습니다. bcpprm 역시 이런 정리 과정을 거쳤습니다.

Plugin을 걷어내고 Skill만 유지하려면 다음 순서로 정리할 수 있습니다.

Plugin 안에서 필요한 SKILL.md와 assets/ 파일만 추출한다.
~/.codex/skills/<skill-name>/ 경로에 복사한다.
기존 Plugin 디렉터리를 삭제한다.
로컬 marketplace 등에 등록된 Plugin 항목을 제거한다.
새 Codex 세션에서 Skill 단독으로 동작하는지 검증한다.

bcpprm에서는 다음 항목을 제거했습니다.

~/vscode/plugins/bcpprm
~/vscode/.agents/plugins/marketplace.json 내부의 bcpprm 항목

이 과정을 통해 최종 구조는 Plugin 의존 없이 ~/.codex/skills/bcpprm/ 아래의 파일만으로 관리되는 형태가 되었습니다.

다른 Skill을 만들 때 그대로 재사용할 체크리스트

새로운 Skill을 등록할 때마다 아래 항목을 순서대로 확인하면 빠뜨리는 부분을 줄일 수 있습니다.

설계 단계

수행하려는 기능이 Skill에 적합한 단일 워크플로인가?
여러 기능과 리소스를 패키지로 관리해야 한다면 Plugin이 더 적합하지 않은가?
사용자가 자연어로 부르기 쉬운 Skill 이름을 정했는가?

파일 작성 단계

~/.codex/skills/<skill-name>/ 디렉터리를 만들었는가?
SKILL.md에 name을 정확히 작성했는가?
description에 실제 요청문과 유사한 트리거 표현을 넣었는가?
작업 순서, 완료 조건, 필수 규칙을 본문에 명시했는가?
변경될 수 있는 규칙을 assets/로 분리할 필요가 있는가?

검증 단계

새 Codex 세션에서 테스트했는가?
Skill 이름을 포함한 요청과 자연어 작업 요청을 모두 시험했는가?
원격 변경 작업이 있다면 승인 절차를 포함했는가?
실패 시 확인할 인증·환경 점검 방법을 적어두었는가?

최종 정리: "좋은 Skill은 작업 지시서이자 운영 규칙이다"

bcpprm를 등록하면서 가장 중요했던 점은 단순히 “브랜치와 PR을 자동으로 만들어주는 기능”을 추가하는 것이 아니었습니다. 실제로 반복 가능한 Skill을 만들기 위해서는 다음 요소가 함께 필요했습니다.

사용자의 요청을 안정적으로 감지할 수 있는 구체적인 description
순서가 명확한 SKILL.md 워크플로
자주 바뀌는 컨벤션을 분리한 assets/ 구조
새 세션에서의 실제 동작 검증
Push와 PR 생성 같은 원격 작업에 대한 안전 규칙

즉, Skill은 단순한 프롬프트 조각이 아니라 반복 작업을 신뢰할 수 있게 수행하도록 만드는 작은 운영 문서에 가깝습니다.

현재 bcpprm는 다음 세 파일을 중심으로 동작하는 자연어 트리거 기반 Codex Skill입니다.

~/.codex/skills/bcpprm/
├── SKILL.md
└── assets/
    ├── conventions.json
    └── conventions.md

앞으로 배포 체크, 코드 리뷰 준비, 문서 생성, 테스트 실행처럼 반복되는 개발 작업이 생긴다면, 같은 구조로 새로운 Skill을 설계해볼 수 있습니다.

작업 순서를 명시하고, 변하는 규칙을 asset으로 분리하고, 위험한 동작에는 승인 기준을 두는 것.

이 세 가지를 지키면 특정 사례를 넘어 재사용 가능한 자동화 워크플로로 발전시킬 수 있습니다.

알림 아키텍처 (2) - Processing Layer

cusum26 — Tue, 31 Mar 2026 01:47:21 +0900

알림 시스템에서 가장 먼저 마주하는 문제는 “알림이라는 작업을 어떻게 생성하고 누구에게 전달할 것인가”이다. 특히 하나의 이벤트가 수백만 명에게 전달되어야 하는 상황에서는 단순한 구현으로는 감당할 수 없는 부하가 발생한다. 이에 각 도메인 서비스에서 직접 알림 메시지를 생성하여 처리하기보다 알림 담당 도메인을 두고 event-driven 모델로 통신하는 구조가 적합하다. 이처럼 생성과 전달 책임을 분리하기 위해서 알림은 독립적인 이벤트 형태로 정의할 필요가 있다.

다음으로 고민해야 할 것은 이 이벤트를 어떻게 사용자에게 안정적으로 분배할 지이다. 알림 기능은 대부분 유저 인터렉션을 위한 후속 작업의 성격으로 이용가능한 자원이 제한적이고 알림 이벤트 각각은 서로 독립적이다. 따라서 작업을 최대한 균등하게 분배하고 비동기적으로 처리하는 구조가 핵심이 된다. 따라서 대부분의 대규모 알림 시스템은 Kafka와 같은 외부 시스템에 이벤트를 produce하며 돌입한다.

Kafka가 어떤 구조로 이벤트를 균등하게 분배하고 비동기 처리 구조를 지원하는지 궁금하다면 아래 포스팅 참고

2026.01.22 - [dev/infra] - Kafka - 이벤트 기반의 비동기 작업 처리 구조로 알림 기능 구현하기 (3)

알림 기능이 어떤 흐름으로 구현되는지 제대로 알아보자.

도메인 이벤트

알림은 항상 어떤 “이벤트”로부터 시작된다. 예를 들어 한 사용자가 게시글에 좋아요를 눌렀다고 가정해보자. 시스템 내부에서는 단순히 "좋아요가 눌렸다"는 DB 상태 변화에 그치지 않고, 이를 계기로 알림 전송이나 행동 로그 기록과 같은 후속 로직이 함께 트리거된다. 이런 구조에서 각 로직을 서로 강하게 결합시키기보다는 의미 있는 사건을 하나의 객체로 정의하고 이를 기반으로 소통하는 방식이 필요하다.

이때 시스템 내에서 발생한 의미 있는 사건을 표현하는 단위가 이벤트이다. 위 예시에서 "사용자가 게시글에 좋아요를 누른 사건"을 도메인 이벤트로 표현하면 다음과 같다.

postLikeEvent
- actor: A (좋아요를 누른 사용자)
- target: B (게시글 작성자)
- content: postId (게시글)

서비스는 내부에서 직접 데이터를 처리하는 대신 이벤트의 형태로 외부로 전달할 수 있다. 좋아요 서비스는 producer로서 이 이벤트를 메시지 브로커에 발행하고 알림 서비스는 consumer로서 이를 구독하여 비동기적으로 처리하는 구조를 통해 알림 로직을 원래 서비스 로직과 분리할 수 있고, 새로운 consumer를 추가하는 것만으로 기능을 확장할 수 있다.

알림 이벤트

알림 시스템에서는 “알림 이벤트”와 “알림 데이터”를 구분해서 이해할 필요가 있다. 알림 이벤트는 특정 도메인 이벤트로부터 파생된 알림 도메인의 이벤트로 어떤 사용자에게 어떤 알림을 생성해야 하는지를 나타내는 중간 단계의 데이터이다. 반면 알림 데이터는 실제 DB에 저장되어 사용자에게 전달되는 최종 결과물로 메시지 형태로 가공되어 저장되고 읽음 상태 등을 포함한다.

만약 위의 postLikeEvent를 감지한 Consumer가 작성자에게 알림을 보내는 로직을 바로 호출한다면 "좋아요 누른 사건" 자체를 나타내는 도메인 이벤트는 알림 이벤트의 역할과 다르지 않다. 알림 서비스가 따로 분리되어있더라도 이 이벤트로부터 직접 알림을 생성해서 유저에게 리턴한다면 postLikeEvent는 도메인 이벤트이자 알림 이벤트가 되고, 생성한 결과물이 알림 데이터가 된다. 이런 구조에서는 postLikeEvent를 매개로 좋아요 도메인과 알림 도메인이 강하게 결합된다.

이처럼 단순한 경우에는 도메인 이벤트가 곧 알림 이벤트로 이어질 수 있지만 현실적인 시스템에서는 아래와 같은 요구사항만 봐도 도메인간 결합도를 낮출 필요가 있기 때문에 두 이벤트를 분리하는 것이 일반적이다.

1. 알림 수신 off인 상황

좋아요 이벤트가 발생하더라도 알림 수신을 꺼놓은 유저에게는 알림을 안 보내도록 해야한다. 만약 postLikeEvent가 곧 알림 이벤트인 구조라면 작성자는 알림 수신을 꺼놓았더라도 좋아요 이벤트에 대해 항상 알림 데이터를 저장하게 되어 비효율적이다.

2. UI용 메시지

도메인 이벤트를 알림 이벤트로 보는 구조에서는 이벤트 하나하나에 알림 데이터가 생성되어 "A 외 99명이 좋아요를 누름"와 같은 aggregation 메시지 구현에 비효율적이다. 따라서 좋아요 기능을 담당하는 도메인과 UI용 결과물을 담당하는 알림 도메인의 책임을 중간에서 분리시키는 독립적인 알림 이벤트의 존재가 필요하다.

3. 하나의 이벤트 → 여러 알림

하나의 도메인 이벤트에 대해 여러 알림을 생성해야 할 경우, 이 작업을 안정적으로 분배하기 위해서 중간 데이터가 필요하다. 앞선 예시에서는 좋아요를 받은 사용자 한 명에게만 알림을 보내면 되기 때문에 도메인 이벤트에서 바로 알림 데이터를 만들어도 큰 문제가 없다. 하지만 팔로워가 많은 사용자가 게시글을 작성했다고 가정해보자.

postCreateEvent
- writerId: 셀럽 유저 id (100만명의 팔로워를 가진 사용자)
- postId: 새로 생성된 게시글 id

100만명의 팔로워를 가진 셀럽이 새 게시글을 작성한 사건을 post 도메인의 이벤트 postCreateEvent라 하자. 모든 팔로워가 이에 대한 알림을 받게 하기 위해서는 수신자 정보가 필요하므로 postCreateEvent의 정보만으로는 부족하다.

postNoficationEvent
- actor: 셀럽 A (100만명의 팔로워를 가진 사용자)
- target: B (A의 팔로워)
- content: postId (새로 생성된 게시글)

따라서 알림 데이터 생성에 필요한 정보를 담은 별도의 알림 이벤트 postNotificationEvent를 정의함으로써 post와 알림 두 도메인의 경계를 보다 명확히 할 수 있다. 그러나 이 경우 서비스는 단순히 하나의 도메인 이벤트 생성으로 끝나지 않고 팔로워 하나하나에 대응하는 100만 개의 알림 데이터를 생성, 처리하는 작업으로 확장된다.

MapReduce 패턴

위에서 봤듯이 무작정 도메인 이벤트와 알림 이벤트를 분리한다고 효율적인 알림 시스템이 완성되지는 않는다. 핵심은 이 이벤트를 “어떻게” 확장할 것인가이다.

MapReduce 패턴은 대용량 데이터를 효율적으로 처리하기 위해 작업을 분할(Map)하고 이를 분산 시스템을 통해 재배치(Shuffle)한 뒤, 병렬로 처리(Reduce)하는 분산 처리 모델이다. 이 패턴은 하나의 무거운 작업을 여러 개의 독립적인 작업 단위로 나누고 이를 여러 노드에서 동시에 처리함으로써 전체 처리 성능을 향상시키는 것을 목표로 한다.

이러한 Map → Shuffle → Reduce 과정은 분산 메시징 시스템을 활용한 fan-out 아키텍처에서 자연스럽게 제공된다. 아래는 Kafka 기반 실시간 이벤트 처리 시스템이 유저마다 서로 다른 알림 이벤트를 생성하는 무거운 반복 작업을 처리하는 과정이다.

[Post Service]
- event: PostCreateEvent
- producer: post-created-topic
↓
[Fanout Service]
- consumer: PostCreateEventConsumer (fanout-group)
- event: FanoutTaskEvent
- producer: FanoutTaskProducer (fanout-task-topic)
↓
[Notification Service]
- consumer: FanoutTaskConsumer (fanout-worker-group)
- event: PostNotificationEvent
- producer: post-notification-topic

먼저 도메인 이벤트 PostCreateEvent를 수신한 Fanout Service는 전체 알림 대상자를 직접 처리하지 않고 offset/limit 기반의 FanoutTaskEvent로 분할한다. 이 단계는 하나의 이벤트를 여러 개의 작업 단위로 나누는 Map 단계에 해당한다.

이후 생성된 FanoutTaskEvent는 Kafka 토픽으로 전송되며 Kafka는 메시지의 key를 기반으로 파티션에 분산 저장하고 이를 여러 컨슈머에게 분배한다. 이 과정은 데이터를 분산 환경으로 재배치하는 Shuffle 단계와 대응된다.

마지막으로 각 컨슈머는 할당받은 FanoutTaskEvent를 처리하면서 해당 범위의 팔로워를 조회하고 사용자별 NotificationEvent를 생성한다. 이는 각 작업 단위를 실제로 처리하며 결과로 변환하는 Reduce 단계에 해당한다.

결과적으로 이 구조는 단일 이벤트를 직접 확장하지 않고 중간에 작업 단위로 분해한 뒤에 분산 처리함으로써 대규모 fan-out을 효율적으로 수행 가능하다.

FanoutTask 이벤트

MapReduce 패턴이 시스템에서 효율적으로 작동하기 위해선 하나의 도메인 이벤트를 적절한 크기의 작업 단위로 분할하는 과정이 핵심이다. 특히 대규모 fan-out 작업의 경우, 단일 이벤트를 직접 처리하는 대신 중간 단계에서 작업을 분해해야 전체 부하를 효과적으로 분산시킬 수 있다.

이를 위해 fan-out 작업용 중간 이벤트인 FanoutTaskEvent가 필요하다. FanoutTaskEvent는 Consumer에게 offset/limit (또는 cursor 기반)으로 처리 범위를 지시함으로써 하나의 도메인 이벤트를 여러 개의 독립적인 처리 단위로 분할하는 역할을 한다. 이렇게 중복없이 분할된 각 작업은 서로 간섭 없이 병렬로 처리될 수 있는 구조를 갖게 된다.

생성된 FanoutTaskEvent는 Kafka 토픽을 통해 전파되며 Kafka는 메시지의 key를 기준으로 파티션에 분산 저장하고 이를 여러 컨슈머에 할당한다. 이 구조는 Map 단계에서 분할된 작업을 Shuffle 단계를 통해 분산 시스템에 재배치하고 이후 각 컨슈머가 독립적으로 작업을 수행하는 Reduce 단계로 자연스럽게 이어진다.

FanoutTaskEvent가 적용된 시스템이 대규모 fan-out을 어떻게 안정적으로 분산 처리하는지 실제 구현을 통해 알아보자.

FanoutTaskEvent

@Getter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class FanoutTaskEvent {

    // 이벤트 식별용 ID
    private String eventId;        // "postId-offset" 형식 ex) "123-0"

    // 원본 도메인 이벤트 정보
    private Long postId;
    private Long creatorId;

    // fanout 범위
    private int offset;
    private int limit;

    private LocalDateTime createdAt;
}

PostCreateEventConsumer

@Component
@RequiredArgsConstructor
public class PostCreateEventConsumer {

    private final FollowerRepository followerRepository;
    private final FanoutTaskProducer fanoutTaskProducer;

    @KafkaListener(
        topics = "post-created-topic",
        groupId = "fanout-group"
    )
    public void createFanoutTask(PostCreateEvent event) {

        Long creatorId = event.getCreatorId();

        // 전체 팔로워 수 조회 (유저 목록 조회 X)
        int totalFollowers =
            followerRepository.countByCreatorId(creatorId);

        // FanoutTaskEvent 생성 + Kafka 전송
        fanoutTaskProducer.produce(event, totalFollowers);
    }
}

FanoutTaskProducer

@Component
@RequiredArgsConstructor
public class FanoutTaskProducer {

    private final KafkaTemplate<String, FanoutTask> kafkaTemplate;

    private static final int BATCH_SIZE = 1000;  //한 FanoutTaskEvent 당 1000명의 유저 담당

    public void produce(PostCreateEvent event, int totalFollowers) {

        Long creatorId = event.getCreatorId();

        for (int offset = 0; offset < totalFollowers; offset += BATCH_SIZE) {

            // FanoutTask 생성
            FanoutTaskEvent event = new FanoutTaskEvent(
                event.getPostId(),
                creatorId,
                offset,
                BATCH_SIZE
            );

            // shard 계산
            int shard = offset / BATCH_SIZE;

            // partition key 생성
            String key = creatorId + "-" + shard;

            // Kafka로 전송
            kafkaTemplate.send(
                "fanout-task-topic",
                key,
                event
            );
        }
    }
}

위의 세 파일은 fan-out 도메인의 서비스로 post 도메인의 이벤트가 알림 도메인을 트리거하는 흐름에서 부하를 분산시키는 중간 과정을 담당한다.

도메인 이벤트인 post-create-topic을 구독한 PostCreateEventConsumer는 PostCreateEvent를 감지하면 fanoutTaskProducer를 호출하여 FanoutTaskEvent를 생성한다. 이때 FanoutTaskEvent는 팔로워 목록 전체를 처리하지 않고 offset, limit를 기반으로 일정 범위의 팔로워를 처리하는 작업 단위 이벤트로 분할된다.

limit가 BATCH_SIZE=1000으로 정의된 FanoutTaskEvent는 팔로워 1000명을 하나의 작업 단위로 묶음으로써 100만명에 대한 알림 이벤트로 확장되기 전에 먼저 1000개의 작업 이벤트로 나눠지게 한다.

FanoutTaskEvent는 “creatorId-shard” 형식의 파티션 키를 사용하여 Kafka의 분산 처리 기능을 활용한다. 이는 fan-out 대상이 creator를 기준으로 조회되는 follower 집합이기 때문에 데이터 접근 패턴과 분산 전략을 일치시키기 위함이다.

하나의 도메인 이벤트가 대량의 알림 이벤트로 바로 확장되기 전에 여러 개의 작업 단위로 나뉘면서 부하가 분산된다.

FanoutTaskConsumer

@Component
@RequiredArgsConstructor
public class FanoutTaskConsumer {

    private final FollowerRepository followerRepository;
    private final KafkaTemplate<String, PostCreateNotificationEvent> kafkaTemplate;

    @KafkaListener(
        topics = "fanout-task-topic",
        groupId = "fanout-worker-group",
        concurrency = "3" // 스레드 3개로 병렬 처리
    )
    public void createPostNoti(FanoutTaskEvent task) {

        // 해당 범위 팔로워 조회
        List<Long> followers = followerRepository.findFollowers(
            task.getCreatorId(),
            task.getOffset(),
            task.getLimit()
        );

        // 범위 내 모든 팔로워에 대한 NotificationEvent 생성
        for (Long userId : followers) {

            PostCreateNotificationEvent event =
                PostCreateNotificationEvent.from(userId, task);

            kafkaTemplate.send(
                "notification-topic",
                userId.toString(), // partition key = userId
                event
            );
        }
    }
}

fanout-task-topic을 구독한 FanoutTaskConsumer는 Notification 도메인의 로직으로 fan-out 작업 이벤트를 감지하면 알림 이벤트를 생성한다. 각 브로커에 분산된 1000개의 FanoutTaskEvent를 세 개의 스레드가 병렬 처리하며 한 task당 1000개의 PostCreateNotificationEvent를 생성함으로써 1000개의 작업 이벤트를 100만개의 알림 이벤트로 확장시킨다.

이렇게 확장된 알림 이벤트는 결국 모든 팔로워에 대한 알림 데이터에 대응한다. PostCreateNotificationEvent의 Consumer는 해당 이벤트로부터 알림 데이터를 생성하고 DB에 저장하는 작업 100만 개를 처리한다. 물론 이 작업은 Kafka에 의해 안정적으로 분배되고 비동기 처리 가능하다.

Post, Fanout, Notification 서비스가 Kafka를 통해 1개의 postCreateEvent를 100만개의 postNotificationEvent로 fanout하는 과정

위는 postCreateEvent 1개가 1000개의 FanoutTaskEvent로 분할 후, 100만개의 PostNotificationEvent로 fan-out하는 과정이다. PostNotificationEvent의 Consumer가 알림 이벤트로부터 알림 데이터를 생성하여 DB에 저장하는 과정은 생략했다.

FanoutTask 크기 설정

fan-out 결과로 생성되는 최종 이벤트 개수를 N, fan-out의 stage 수를 t라고 할 때, 각 단계에서의 fan-out 크기를 균등하게 분할하고 각 단계의 작업 크기를 N^{1/t}로 설정하는 것이 연산 비용 측면에서 가장 효율적이다.

전체 fanout 과정을 하나의 트리 구조로 보았을 때 각 단계의 branching factor를 동일하게 유지하여 모든 단계의 부하를 균등하게 분산시키는 방식

위 예시에서는 최종적으로 100만개의 알림 이벤트를 위해 2번의 fanout 단계를 거치므로 각 FanoutTask 단위를 루트 100만 = 1000으로 설정하였다. 만약 1억개의 알림 이벤트를 위해 세 번의 fanout 단계를 넣는다면 fanout 크기는 100명 단위로 충분히 확장성있는 구현이 가능하다.

1 → 100 → 10,000 → 100,000,000

물론 이는 이론적인 수치로 fan-out 과정을 거치며 발생하는 오버헤드와 DB 및 네트워크 IO 비용, 그리고 무엇보다 공간 비용 때문에 현실에서는 stage를 늘리면서 fan-out을 확장하는 일은 거의 없다.

따라서 무작정 도메인 이벤트, fanout 이벤트, 알림 이벤트를 분리한다고 효율적인 알림 시스템이 완성되지는 않는다. 핵심은 이 이벤트를 “언제” 전달할 것인가이다.

이 지점에서 알림 시스템은 중요한 설계 결정을 내려야 한다. 이벤트를 발생시키는 시점에 미리 모든 사용자에게 알림을 생성할 것인지, 사용자가 조회하는 시점에 필요한 알림을 계산할 것인지이다. 이 선택이 바로 fan-out 전략이며 알림 시스템의 확장성을 결정짓는 핵심 요소가 된다.

통지, 알림, 공지 등을 모두 포괄하는 알림 도메인은 기본적으로 이벤트가 발생하는 시점에 수신 대상자가 이를 조회하도록 하는 것이 주 목적이므로 fanout-on-write 방식이 직관적이다. 그러나 이 구조에 수반하는 비효율과 효율적인 알림 시스템은 이를 어떻게 피해가는지 fan-out 전략에 대해 알아보자.

Fan-out 시점

기본적으로 fan-out은 데이터를 여러 사용자에게 확산시키는 과정으로 여러 사용자에게 보여줄 데이터를 생성하고 전달하는 방식이다. 유튜브를 예로 들면, 만약 구독자가 100만 명인 채널에서 영상을 업로드했을 때 각 구독자에 대해 새 영상 알림을 발송해야한다. 또는 각기 다른 100개의 채널을 구독한 여러 명의 유저가 피드를 새로고침했을 때 각자가 팔로우한 채널에서 새로 올린 영상들이 피드에서 조회돼야한다.

이러한 기능 구현에 있어서 문제는 100만개의 알림 또는 100개의 영상 조합이라는 대용량 데이터를 언제 만들어서 전달할 것인가이다. 이 데이터를 write 시점에 생성할지, read 시점에 생성할지에 따라 fan-out 방식을 구분한다.

개인적으로 fanout-on-read와 fanout-on-write 개념은 ORM에서의 lazy loading과 eager loading 개념이 시스템 아키텍처 수준으로 확장된 사례로 볼 수 있다고 생각한다. 즉 필요한 데이터를 요청 시점에 계산할 것인지(lazy), 미리 계산해 둘 것인지(eager)의 차이와 본질적으로 동일한 문제를 다룬다.

Fanout-on-write (Push 모델)

데이터가 작성되는 시점(Write)에 팔로워의 목록을 확인하여 각 팔로워에게 즉시 전달하는 방식

= 유튜버가 채널에 영상을 업로드하는 순간 모든 구독자에 대해 알림 이벤트를 복제 후 전달

video uploaded 이벤트
↓
Kafka
↓
Consumer가 fan-out 수행(알림 이벤트 produce)
↓
Kafka
↓
Consumer가 알림 로직 수행(DB write)

.
.
.

user 알림 저장
↓
바로 조회

장점

read query 단순해서 read 비용 매우 작음
사용자의 Read 시점에 이미 데이터가 준비되어 있어 조회 속도가 매우 빠름
Kafka와 결합하여 비동기 처리 가능

단점

write 비용 매우 큼
follower 많으면 DB write 과부하 문제 발생
스토리지 소모 큼

Fanout-on-read (Pull 모델)

사용자가 요청하는 시점(Read)에 필요한 데이터를 동적으로 수집, 조합하여 보여주는 방식

= 영상 업로드시 원본 데이터 하나만 저장, 팔로워가 피드를 조회하는 순간 팔로잉한 모든 채널에 대해 새 영상을 실시간으로 가져와서 로드

video uploaded
↓
DB에 저장

.
.
.

user가 피드 조회 요청
↓
fan-out (following list 돌며 각 채널에 대해 새 video 집계)
↓
feed 데이터 구성
↓
조회 가능

장점

write 비용 매우 작음
데이터 중복 저장이 없어 스토리지 절약
구조 및 구현 단순

단점

join으로 인한 read 비용이 큼
대용량 데이터를 실시간으로 집계하므로 조회 성능이 느려질 수 있음
query 복잡

fanout-on-read 방식은 사실 유저의 request로 트리거되는 대부분의 도메인에서 활용되는 일반화된 방식이다. Service 로직에서 Repository를 호출하여 복잡한 쿼리로 데이터를 뽑아오는 익숙한 흐름에 녹아있다.

Fanout-on-write vs Fanout-on-read

fanout-on-write, fanout-on-read는 결국 유저가 필요로 하는 데이터를 언제 생성할지에 대한 전략의 차이로 볼 수 있다.

	fanout-on-read	fanout-on-write
병목 위치	Read path	Write path
주요 작업	scan, join, sort	insert, index, replication
주요 자원	CPU + DB read IO + index scan + sort	storage + disk IO + index write + network
특징	조회 시 동적 계산 - 실시간 조인으로 가져오므로 조회 시 느림 - 중복 저장 없으므로 쓰기 시 빠름	이벤트 생성 시 선계산 - 중복 저장 비용으로 쓰기 시 무거움 - 조회 이전에 이미 데이터 준비되므로 조회 시 빠름
장점	write 가벼움, 스토리지 절약	read 빠름, 쿼리 복잡도 낮음
유리한 사례	read 유연성 중요 + 중복 규모가 큼	read latency 중요 + 중복 규모가 적음

두 방식은 시스템 병목이 read path와 write path 중 어디에 발생할지를 결정하는 트레이드오프로 서비스의 규모와 사용자 특성에 따라 적절히 선택되어야 한다.

실제로 트위터의 피드 시스템은 초기에는 사용자 수와 팔로잉 규모가 작아 fanout-on-read 방식으로도 충분했지만 서비스가 성장하면서 조회 시 조인 비용이 증가하자 일부를 fanout-on-write 방식으로 전환하였다. 그러나 팔로워 수가 매우 많은 셀럽의 경우 DB write 폭발 문제를 유발하므로 최종적으로는 사용자 특성에 따라 fanout-on-read와 fanout-on-write를 혼합한 hybrid 구조로 발전하였다.

Celebrity Problem

기본적인 알림 기능 구현에 있어서는 직관적인 fanout-on-write 방식이 적합하다. 하지만 위에서 봤듯이 write 시점에 심각한 병목을 만들 수 있다. 중복 규모, 즉 fan-out 규모가 클수록 저장 부담과 자원 소모가 심해져 시스템 capacity상 감당하지 못하는 지점이 생길 수 밖에 없다. 앞서 100만 팔로워를 가진 셀럽이 새 게시글을 작성한 예시를 생각해보자.

fanout-on-write 전략을 사용할 경우, 셀럽이 게시글을 업로드하는 하나의 행동이 100만 건의 알림 이벤트 생성 작업으로 이어진다. 이러한 상황에서는 단순한 업로드 작업이 시스템 전체에 큰 부하를 유발하여 처리 지연, 저장공간 부담 등 다양한 문제를 연쇄적으로 일으킬 수 있다. 따라서 알림의 대상 범위가 넓어질수록 fan-out 전략은 자연스럽게 write에서 read 중심으로 이동하게 된다.

팔로워 수가 많은 사용자의 활동이 대규모 fan-out을 유발하며 시스템에 부담을 주는 상황을 Celebrity Problem이라고 한다.

이러한 문제를 해결하기 위해 모든 사용자에게 동일한 방식으로 fan-out을 적용하기보다는 유저의 규모에 따라 다른 전략을 사용하는 방식이 등장하게 된다.

해결 방안

기본적으로 일반 유저의 행동에 의한 알림은 fanout-on-write으로 구현된다. 많은 팔로워를 가진 유저의 행동은 서비스의 가용 자원을 넘어서는 fan-out을 유발하므로 fanout-on-read에 기반하여 구현될 수 밖에 없다.

Fanout-on-read + Lazy fanout

팔로워가 많은 유저의 행동은 알림 이벤트 생성까지 진행하지 않고 그 행동 이벤트 자체만 저장해둔다. 이 상태에서 팔로워가 피드 조회 같은 방식으로 팔로우한 셀럽의 행동 이벤트 조회를 요청하는 시점에 팔로우 목록을 돌며 저장된 행동 이벤트를 기반으로 알림 이벤트를 생성한다. 이는 유저가 조회하는 시점에 필요한 데이터를 계산하는 fanout-on-read 방식이다.

또한 유저가 최초 조회하는 시점에 알림 이벤트를 생성하고 알림을 저장하는 lazy fanout 방식이 사용된다. 이 구조는 유저가 처음 조회할 때까지 알림 도메인 로직을 실행하지 않는다. 따라서 일부 활성 유저에 대해서만 fan-out이 수행되고 스토리지를 효율적으로 사용할 수 있게 된다. 나아가 이후 조회부터는 행동 이벤트 수집없이 이미 생성된 알림 데이터만을 조회함으로써 read 병목을 최소한으로 하여 균형을 맞춘다.

인스타그램에서 친구의 라이브 방송 알림은 라이브 시작과 거의 동시에 오는데 팔로우한 셀럽의 라이브 방송은 시작하고도 한참 알림이 뜨지 않은 경험이 자주 있다. 대부분 알림보다는 피드에 떠서 들어간 경우가 많은 것도 이 때문일 것이라 추측한다. 추가로 알림을 못받은 채 피드로 라이브 방송을 들어가고 나면, 그제서야 방송 시작 알림이 오던 경험도 이 Fanout-on-read + lazy fanout 방식으로 설명이 된다.

전체 공지

공지와 같은 전체 알림의 경우에도 Celebrity Problem 상황과 본질적으로 동일하다. 유저 전체를 수신 대상자로 하는 알림을 미리 생성하는 fanout-on-write 방식은 비효율적이므로 하나의 공지 이벤트를 저장해두고 유저가 접속 또는 조회하는 시점에 보여주는 read 기반 전략이 주로 사용된다. 다만 실제 시스템에서는 읽음 상태 관리나 푸시 알림 처리와 같이 일부 write 작업이 함께 수행되는 hybrid 형태로 구현되는 경우가 많다.

결국 fan-out 시점에 따른 두 방식의 차이는 데이터를 언제 생성할 것인가의 문제로 귀결된다. 이 막대한 비용을 write 시점에 지불할 것인지 read 시점에 지불할 것인지에 대한 선택이다. 물론 이 트레이드오프는 비용 뿐만 아니라 서비스 성격, 트리거 도메인, 이벤트 특징을 고려하여 결정하게 된다.

알림 아키텍처 (1)

cusum26 — Fri, 27 Mar 2026 19:28:19 +0900

대규모 서비스 아키텍처의 주된 관심사는 확장성과 병목 관리라 해도 과언이 아니다. 이와 관련된 트레이드오프나 문제 상황을 경험해보고 핸들할 수 있는 판단력을 갖추는 것이 요즘 시대에 가장 필요한 개발 역량이 아닌가 싶다. 규모가 크지 않은 서비스라도 이와 비슷한 문제 상황을 자연스럽게 고민하게 되는 도메인이 있는데 개인적으로 알림 도메인이라고 생각한다. 어느정도 반복되는 구조를 답습하는 대부분의 도메인과 다르게 각자 서비스 성격에 따라 효율적인 시스템 디자인을 간접적으로 고민해 볼 수 있는 가장 현실적이고 자유도 높은 도메인이 아닐까한다.

기본적으로 알림은 서비스가 유저에게 먼저 request를 보내는 거의 유일한 상호작용이다. 개발자이기 이전에 사용자로서 그동안 수많은 애플리케이션의 알림을 경험하며 귀찮게 하는 기능이라는 인식이 굳어졌다. "유저 혜택, 알림 동의"의 항목도 웬만하면 동의 안하고 넘어간다. 그럼에도 서비스 입장에서는 알림 기능이 비즈니스 목적 실현을 유도하는 나름 핵심 도메인이라는 사실은 부인할 수 없다.

"유저가 떠나지 않게 하기 위한 서비스의 울부짖음" 정도의 인상으로 유저에게 도달하기까지, 소셜 미디어의 확산과 함께 급격히 고도화된 현재의 알림 시스템은 어떻게 디자인되고 어떤 매커니즘으로 구현되는지 호기심이 들었다.

특히나 대형 서비스에서의 알림 도메인은 사실상 확장성 문제를 최전선에서 마주한다. 단순히 메시지를 전달하는 기능을 넘어 대량의 이벤트 발생, 대량의 데이터 저장, 그리고 실시간 사용자 응답이라는 세 가지 축으로 동작하는 과정에서 수많은 문제와 트레이드오프를 자연스럽게 마주한다.

따라서 처리, 저장, 유저 인터렉션 각 과정에서 나타나는 고유한 문제 상황과 책임에 따라 알림 도메인을 Processing Layer, Storage Layer, Serving Layer 세 가지 레이어로 분리하여 각 시스템을 구성하는 핵심 개념에 대해 알아보자.

Processing layer

Processing Layer는 알림 데이터를 실제로 만들어내는 시작점으로 서비스 내에서 발생시킨 도메인 이벤트를 기반으로 알림을 생성하고 흐르게 하는 역할을 담당한다. 어떤 이벤트가 발생했는지 정의하고 해당 이벤트가 어떤 유저에게 전달되어야 하는지 결정하며, 이를 fanout하거나 aggregation하는 방식으로 분배 전략을 선택한다. 생성된 대량의 이벤트는 Kafka와 같은 메시지 브로커를 활용해 비동기적으로 처리하며 다음 레이어로 전달된다.

주요 트레이드오프

Write-time vs Read-time

핵심 개념

개념	설명	예시
domain event	시스템에서 의미있는 사건을 나타내는 객체	domain event, fanout event, notification event
Apache Kafka	이벤트를 비동기로 전달하는 스트림 시스템	like 이벤트 → Kafka topic → consumer group
producer / consumer	이벤트 생성자 / 처리자	service → producer fanout worker → consumer
fanout on write	이벤트 발생 시 미리 유저별 데이터 생성	글 작성 → 팔로워 100명에게 알림 100개 생성
fanout on read	조회 시점에 동적으로 데이터 생성	피드 요청 → 팔로잉 목록 기반 posts 조회
celebrity problem	팔로워 많은 유저 fanout 폭발	팔로워 1억
hybrid fanout	유저 규모에 따라 write/read 혼합	일반 유저=write, 셀럽=read
batch fanout	여러 유저 insert를 묶어서 처리	1000명씩 insert
aggregation	여러 이벤트를 하나의 알림으로 묶음	“A, B, C liked your post”
aggregation window	일정 시간 동안 이벤트를 모아서 처리	5분 동안 like 모으기
outbox pattern	DB + 이벤트 발행을 원자적으로 보장	comment insert + outbox insert
CDC / poller	outbox → Kafka로 이벤트 전송	Debezium
idempotency	동일 이벤트 중복 처리 방지	UNIQUE(event_id)
duplicate 문제	Kafka 재처리로 중복 발생	같은 알림 2번 생성
event ordering	이벤트 순서 보장 문제	follow → unfollow 순서 뒤바뀜
partition key	Kafka 순서 보장을 위한 key	user_id 기준 partition
candidate generation	보여줄 후보 데이터 생성	피드 후보 500개 생성

Storage layer

Storage Layer는 Processing Layer로부터 전달받은 알림 데이터 저장을 담당하는 영역으로 확장성 문제를 가장 직접 마주하는 영역이다. 유저 수에 따라 데이터가 폭발적으로 증가하는 문제를 해결하기 위해 어떤 DB 구조로 어떻게 쌓을지를 정의한다. 템플릿과 실제 전달 데이터를 분리하거나, 파라미터 기반 구조를 사용하는 등 다양한 저장 전략이 고려된다. 결국 이 레이어의 핵심은 대용량의 알림 데이터를 효율적으로 저장하면서도 Serving Layer에서 조회 성능을 확보하도록 설계하는 것이다.

주요 트레이드오프

Space vs Join cost

핵심 개념

개념	설명	예시
notification table 단일 모델	유저 알림 저장 테이블	user_id, actor_id, type
template + delivery 전달 분리 모델	템플릿과 유저 전달 데이터를 분리	Notice + memeberNotice
announcement	공지 저장 테이블	점검 안내
announcement_read	공지 읽음 상태	user_id, announcement_id
notification_template	알림 메시지 템플릿 저장	“{actor} liked your post”
notification_delivery	유저별 알림 데이터	user_id, template_id
event table	이벤트 기록 테이블, 저장 구조지만 처리 목적	outbox_event
param_json / metadata	알림 파라미터 저장	template_id + params ex) {order_id:123}
personal_msg	개인화된 메시지 저장	“철수님이 댓글”
is_read 컬럼	읽음 여부 inline 저장	boolean
notification_read	읽음 상태 분리 테이블	user_id + notification_id
append-only log	수정 없이 insert만 하는 구조	notification log
sharding	DB를 여러 개로 분산	user_id % 100
hot shard 문제	특정 shard에 트래픽 집중	인기 유저
NoSQL (Cassandra 등)	대용량 write 최적화 DB	wide-column DB
TTL	자동 만료 정책	30일 후 삭제
cold storage	오래된 데이터 외부 저장	S3
storage explosion	데이터 폭증 문제	하루 10억 알림
index 비용	insert 시 index 업데이트 비용	user_id index
denormalized view	조회용 비정규화 테이블	notification_view
timeline/feed table	유저별 피드 저장	user_feed

Serving layer

Serving Layer는 저장된 알림 데이터를 사용자에게 실제로 제공하는 단계로 유저 인터랙션을 담당하는 영역이다. 사용자는 읽지 않은 알림 개수를 즉시 확인하고 빠르게 목록을 조회할 수 있어야 한다. 이를 위해 캐시를 활용한 unread count 관리, 읽음 상태 저장 방식, 페이지네이션 전략 등이 함께 고려되며 궁극적으로는 사용자 경험을 해치지 않는 빠른 응답 속도를 보장하는 것이 목표다.

주요 트레이드오프

Latency vs Accuracy

핵심 개념

개념	설명	예시
notification API	알림 목록 조회 API	GET /notifications
announcement + notification merge 전략	공지 + 알림 합쳐서 반환하는 전략	API aggregation
unread count API	안읽은 알림 수 반환	23
Redis unread count	빠른 unread count 캐시로 구현	unread:123 → 5
badge 응답	UI 빨간 점 숫자	앱 상단 알림
pagination	페이지 단위 조회	limit 20
fanout on read 조회 최적화	DB 조회 기반 피드 생성	SELECT posts
cache	빠른 응답을 위한 캐시	feed cache
precomputed timeline	미리 계산된 피드	fanout on write 결과
ranking / relevance	보여줄 순서 결정, 후보 생성은 processing, 정렬은 serving	like 확률 기반
ordering/sorting	정렬 방식	시간순 vs 추천순
feed API	피드 조회	GET /feed
server rendering	서버에서 메시지 생성	API에서 문자열 생성
client rendering	클라이언트에서 메시지 생성	params 기반 렌더링

알림 도메인은 단순한 DB 설계를 너머
이벤트 기반 처리(Kafka, fanout), 대규모 저장(sharding, NoSQL), 고성능 조회(Redis, ranking)를 총괄하여 설계하는 시스템 아키텍쳐 문제다.

flutter - 플러터로 크로스 플랫폼 앱 개발하기(3)

cusum26 — Fri, 6 Mar 2026 23:10:06 +0900

상태 관리 라이브러리

앱에는 고정된 데이터와 변경되는 데이터가 존재한다. 앱의 주된 사용 목적 중 대부분은 변경되는 데이터의 조회로 이 데이터를 어떻게 관리하고 표현하는지가 앱의 성능, 사용성에 큰 영향을 미친다. 상태 관리 라이브러리는 변경되는 데이터를 클래스 내부에서 관리하고 위젯에 담아 화면에 출력하는 클래스간 데이터 흐름을 총괄한다.

상태 관리 라이브러리로는 대표적으로 Provider, Bloc, Riverpod, GetX가 존재한다. GetX는 이제 거의 안 쓰이고, Provider는 일전에 설명한 관계로 Bloc, Riverpod 두 라이브러리를 중심으로 설명한다.

Bloc

Business Logic Component

imperative (명령형) : 외부 자극을 단일 경로를 따라 내부 상태 변화로 매핑하는 상태머신

UI → Event → Bloc → State → UI

Bloc에서의 데이터 흐름은 다음과 같다.

외부 입력
UI가 Bloc에 Event 전달
Bloc 객체에서 로직 실행
State 변경(emit)
BlocBuilder가 변경 감지
UI 반영(build)

state machine : 외부 이벤트를 감지 시 로직을 실행시켜 내부의 상태를 변화시키는 상태 머신
- (현재 상태 + 이벤트 로직) ———(이벤트)——> (새 상태)
Event기반 모델 - 상태 변경을 트리거한 동작을 명시하여 모든 변화를 추적(디버깅, 로깅, 테스트 용이)

add(IncrementEvent);                       //Bloc

ref.read(counter.notifier).increment();    //Riverpod

관련 객체
- BlocProvider: Bloc 객체를 트리에 주입
- Bloc: Widget에서 받은 Event를 처리하는 로직 수행
- BlocBuilder: State 구독 후 변경사항 UI에 반영
MVVM 패턴 표방 - Widget(View)과 Bloc(Model)의 분리

위젯과 Bloc 코드

//일반 Widget
...
ElevatedButton(
  onPressed: () {
    count++;
    setState(() {}); 
  },
  child: Text("증가"),
);
//UI단에서 상태를 변경하는 로직 직접 실행 -> V+M 강하게 결합

Widget build(BuildContext context) {
  return Text('$count');
}
// setState에 의해 자동 빌드



//Bloc 적용 Widget
...
ElevatedButton(
  onPressed: () {
    context.read<CounterBloc>().add(IncrementEvent());
  },
  child: Text("증가"),
);
//UI단에서는 이벤트를 수신할 Bloc에 적당한 이벤트를 던지고 
//Bloc에서 이벤트 감지 후 로직 실행하도록 분리

BlocBuilder<CounterBloc, int>(
  builder: (context, state) {
    return Text('$state');
  },
);
//Bloc 로직 실행으로 인해 변경 감지 시 빌드되도록 상태 구독

//Bloc 내부
on<IncrementEvent>((event, emit) async {
  emit(Loading());
  final result = await apiCall();    //비동기 처리되는 콜백 등록
  if (result) {
    emit(Success(state + 1));       //로직 실행후 변경된 상태 emit
  } else {
    emit(Failure());
  }
});

전통적인 setState()와 Bloc의 차이

상태의 소유권
- setState 구조: 상태(State)는 UI(StatefulWidget)와 강하게 결합(존재가 독립적이긴 해도 로직상 의존적)
- Bloc 구조: 상태는 UI 외부의 Bloc이라는 객체 안에서 Event를 거침으로써 한번 flow가 끊김→ 독립성 강화
상태 변화의 예측 가능성
- setState 구조: 위젯 내부에 변경 로직이 포함 + setState() 후 자동 빌드로 인해 입출력 흐름이 잘 안보임
  - UI 이벤트 → state 변경 → build 재호출이 한 파일 내에서 암묵적으로 진행
  - setState 호출, count++ 등으로 어느 위치에서든 상태를 자유롭게 수정 가능
  - 변경 경로가 여러 개 존재 가능
- Bloc: UI와 로직이 완전 분리되어 상태 변화 추적에 용이
  - add(Event)를 통한 입력(UI→Bloc)과 on<Event> 를 통한 출력(Bloc→UI) 흐름이 명시적으로 드러남
  - 외부 이벤트라는 단일 시작점 강제
  - 상태 변경 경로를 하나로 통일

Riverpod

Provider 구조를 계승하여 확장했다는 의미에서 애너그램(provider -> riverpod)

declarative (선언형) : 상태를 정의해두면 의존 관계에 따라 자동으로 갱신되는 반응형 시스템

UI → Notifier → State → Provider 의존성 전파 → Consumer → UI

Riverpod에서의 데이터 흐름은 다음과 같다.

외부 입력
UI가 Notifier로 상태 변경 전달 (ref.read)
Notifier에서 로직 실행
State 변경
Notifier를 소유한 Provider가 변경 감지 (ref.watch로 연결)
의존성 그래프 전파 (Consumer까지 전달)
UI 반영(build)

Provider의 상태 저장
상태 변경 감지
watch 의존성 관리
rebuild 트리거

Riverpod
 ├─ Provider (정의)
 ├─ Notifier (상태 조작)
 ├─ Consumer/ref.watch (구독)
 └─ ProviderContainer (핵심 저장소 + 의존성 관리)

Provider

값을 제공하는 선언 단위로 값을 생성하는 규칙(함수)과 의존성을 정의하는 객체

상태를 직접 들고 있거나 다른 provider를 조합, 가공하는 객체 모두 해당
ref.watch()로 연결된 의존성 그래프의 모든 노드는 provider
위젯이 State에 접근할 수 있는 유일한 통로(상태에 대한 식별자 제공)
대부분 상태를 직접 들고 있지 않고 Notifier로 접근
상태에 접근할 통로를 어떤 방식으로 제공할지 정의

final counterProvider = NotifierProvider<CounterNotifier, int>(CounterNotifier.new);

위는 int 타입의 상태 count를 관리하는 CounterNotifier라는 객체에 외부 위젯이 접근할 수 있는 통로를 counterProvider라는 이름으로 정의한 코드이다.

Notifier

상태를 직접 관리하는 컨트롤러

실제로 state를 보유한 객체
state를 변경하는 로직 포함
위젯에게 노출되는 상태변경 통로
위젯에 의한 상태 변경 흐름
- 위젯이 Notifier 메서드 호출
- Notifier가 state를 갱신
- ProviderContainer가 변경 감지
- watch 중인 위젯(Consumer)에 최신 state 전달 + rebuild

Consumer

상태를 구독하는 위젯

provider를 watch하는 위젯으로 Notifier를 통해 상태 변경 로직에 접근 가능
상태가 바뀌면 자동 rebuild

ProviderContainer

(provider-consumer)쌍을 저장하고 State의 변경 감지 시, watch 등록한 위젯에게 변경된 상태 전달

앱 전체 상태 저장
- 모든 provider 인스턴스 관리
- 모든 Consumer의 watch 정보 추적
모든 State의 변경 감지
- Notifier가 state 변경 시 ProviderContainer가 이를 감지
- 변경된 상태가 속한 Provider 확인
- 그 Provider를 watch 중인 위젯 목록 조회
- 해당 위젯들에게 state 전달

ProviderContainer   ← 최상위 상태 관리자
   └─ Provider      ← 상태 접근 경로 정의
        └─ Notifier ← 상태 변경 관리 객체
             └─ State ← 실제 상태

Bloc과 Riverpod

Bloc과 Riverpod의 유사점

UI → Notifier → State → Provider → Consumer → UI
UI → Event → Bloc → State → UI
- 이벤트 대신 Notifier 함수를 통한 상태 변경의 통제 구조 계승
상태 외부화 - 독립적인 상태를 두고 이를 참조하여 관리하는 객체(Bloc, Notifier)를 분리하여 상태 직접 수정 차단
UI와 로직 분리
Listen → Watch
- Bloc : 상태 변경 감지 책임이 수신 측에 존재 (상태를 인자로 받는 위젯 빌더)
- Riverpod : (송신 - 수신) 쌍을 따로 관리하는 제3자(ProviderContainer)에게 변경 감지 책임 위임(위젯이 Watch로 Provider 의존성 등록), 위젯은 UI 반영 책임만 존재

코드상 흐름 차이

Bloc: UI → add(Event) → Bloc → emit(state) → BlocBuilder 리빌드(위젯 리빌드)

Riverpod: UI → notifier.increment() → state 변경 → watch 중인 Provider가 감지 → watch 중인 Consumer가 감지 → 위젯 리빌드

// Riverpod 적용 위젯
class CounterPage extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider); // 상태 구독

... 

        ElevatedButton(
          onPressed: () {
            ref.read(counterProvider.notifier).increment();
          },
          child: Text("증가"),
        );
        // UI단에서는 상태를 변경할 Notifier의 메서드를 호출

        final count = ref.watch(counterProvider);
        // 특정 상태를 구독하고 변경 시 자동 rebuild

        Text('$count');

//Provider 내부 (provider + notifier)
final counterProvider =
    NotifierProvider<CounterNotifier, int>(CounterNotifier.new);

class CounterNotifier extends Notifier<int> {
  @override
  int build() => 0;

  void increment() {
    state++;
  }
}

Bloc	Riverpod
add(Event)	notifier.method()
emit(state)	state =
BlocBuilder	ref.watch()
state 인자	final count 변수

Stream 기반 반응 vs 의존성 추적 기반 반응

상태 변경을 전달받고 반응하는 방식에 있어서 Stream기반의 Bloc과 의존성 추적 기반의 Riverpod 사이에는 본질적인 차이가 존재한다.

Bloc - 상태 변경 자체를 데이터로 표현하여 전달 - 이벤트 중심 아키텍쳐

Riverpod - 변경된 상태를 감지하도록 연관된 객체끼리 연결 - 의존성 중심 아키텍쳐

	Stream 기반	의존성 추적 기반
중심 개념	데이터 흐름	의존 관계
연결 방식	구독(listener) 중심	watch 등록 (제3자가 연결 관리)
구조	선형 흐름	그래프 구조
철학	이벤트 드리븐	선언적 의존성

API 통신

실시간으로 변경되는 데이터를 앱 외부에서 받아오기 위해서는 API 통신이 필수적이다. http, Dio 같은 라이브러리를 사용하여 JSON과 다트 객체 간의 변환과 API 요청 전송 및 응답 처리를 구현할 수 있다.

API

Application Programming Interface

서로 다른 소프트웨어 애플리케이션이 서로 어떻게 통신하고 데이터를 공유할 지 미리 정의해둔 규칙이다. API를 통해 클라이언트는 서버의 내부 구조를 알지 못하더라도 약속한 형식에 맞춰 요청을 보내기만 하면 약속한 형식으로 응답을 받아올 수 있다.

어떻게 하는지는 몰라도 무엇을 하는지는 안다

플러터 앱에서 API 호출을 통해 데이터를 받아오는 흐름은 다음과 같다.

1. 사용자 UI 이벤트 처리
- 버튼 클릭이나 입력 변경에 따른 사용자 행동에 대해 이벤트 생성, 해당 이벤트리스너에 의한 API 통신 프로세스 시작
2. API 요청 전송
- 이벤트리스너에서 적절한 파라미터를 채운 후 http 클라이언트를 통해 API 요청 전송
3. API 응답 수신
- 서버로부터 받은 API 응답에 대한 수신 처리(상태 코드 확인, 에러 핸들링)
4. 응답 데이터 처리
- API 응답으로 받은 데이터(JSON, XML)의 파싱 및 변환 후 앱의 로직에 맞게 조작

플러터에서 API 관련 기능을 제공하는 대표적인 라이브러리로 http, Dio 2가지가 존재한다.

http 패키지

http 패키지는 HTTP(Hypertext Transfer Protocol)기반으로 API 요청을 작성하고 응답을 처리할 수 있도록 일반적인 http 메서드를 제공한다.

GET (http.get)

데이터 조회

//패키지 내부 정의
Future<Response> get(Uri url, {Map<String, String>? headers})

//사용 예시
final response = await http.get(
 'https://api.example.com/users', headers : {'Authorization': 'Bearer token'}
);

url : 요청을 보낼 목적지 URL
header: GET 요청에 필요한 정보(일반적으로 인증 정보 또는 content-type)

POST (http.post)

데이터 생성

// 패키지 내부 정의
Future<Response> post(
  Uri url, {
  Map<String, String>? headers,
  Object? body,
  Encoding? encoding,
})

// 사용 예시
final response = await http.post(
  Uri.parse('https://api.example.com/users'),
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json',
  },
  body: '{"name": "John"}',
);

body: 서버에서 POST 요청에 대한 처리로 새 데이터를 생성할 때 필요한 정보

PUT (http.put)

전체 수정

// 패키지 내부 정의
Future<Response> put(
  Uri url, {
  Map<String, String>? headers,
  Object? body,
  Encoding? encoding,
})

// 사용 예시
final response = await http.put(
  Uri.parse('https://api.example.com/users/1'),
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json',
  },
  body: '{"name": "Updated"}',
);

PATCH (http.patch)

부분 수정

// 패키지 내부 정의
Future<Response> patch(
  Uri url, {
  Map<String, String>? headers,
  Object? body,
  Encoding? encoding,
})

// 사용 예시
final response = await http.patch(
  Uri.parse('https://api.example.com/users/1'),
  headers: {
    'Authorization': 'Bearer token',
    'Content-Type': 'application/json',
  },
  body: '{"name": "Partial Update"}',
);

DELETE (http.delete)

데이터 삭제

// 패키지 내부 정의
Future<Response> delete(
  Uri url, {
  Map<String, String>? headers,
  Object? body,
  Encoding? encoding,
})

// 사용 예시
final response = await http.delete(
  Uri.parse('https://api.example.com/users/1'),
  headers: {'Authorization': 'Bearer token'},
);

멱등성

멱등성은 어떤 연산을 여러 번 수행해도 결과가 달라지지 않는 성질로 네트워크로 전달되는 API 통신 특성상 로직 설계에 중요한 고려 사항이 된다. 서버에서는 http의 각 메서드 특징을 고려하여 로직을 설계해야한다.

메서드	멱등성	반복 요청 시 행동	예시
GET	O	상태 변화 없이 같은 결과 반환	GET /users/1
POST	X	호출마다 새 데이터 생성	POST/users/
PUT	O	받은 값으로 덮어쓰기(결과 동일)	PUT /users/1 {name: "John"}
PATCH	△	상황에 따라 결과 달라질 수 있음	PATCH /users/1 {count: count + 1}
DELETE	O	해당하는 데이터 존재할 경우에 삭제	DELETE /users/1

같은 요청을 여러 번 보내도 한 번 보낸 결과와 동일하면 멱등
응답이 아닌 최종 상태 기준으로 판단

API 응답 데이터 처리

API 응답 데이터는 주로 다음과 같은 순서로 처리되어 UI에 반영된다.

JSON → Map → Model(다트 객체) → State → UI

1. API 응답 (JSON)
2. jsonDecode() 호출: JSON → Map
- jsonDecode() 메서드가 JSON 문자열 파싱 후 Dart 기본 타입 Map<String, dynamic> 객체로 역직렬화
3. fromJson() 호출: Map → 모델
- 미리 정의해둔 Model.fromJson() 메서드가 Map<String, dynamic> 객체를 Model 객체로 변환
4. State 변경
5. UI 표시

다음과 같은 구조로 API를 처리하도록 설계된 애플리케이션에서 각 컴포넌트의 역할과 예시 코드는 다음과 같다.

UI
↓
Notifier (상태관리)
↓
Repository (비즈니스 로직)
↓
ApiService (HTTP + 응답 처리)
↓
http client

Service = 실제 네트워크 통신 수행

Model = 외부 데이터를 앱 내부에서 사용할 수 있도록 구조화한 Dart 객체 (응답의 최종 변환 결과)

Repository = 데이터 변환 및 비즈니스 로직 (데이터 조합, 조건 처리, 캐싱 전략)
Notifier = 상태 관리 및 변경 흐름(success, loading, error) 제어

Provider = 변경 전파를 위한 의존성 연결 및 진입점 제공
UI = 변경된 상태를 화면에 표시

Service

class ApiService {
  final String baseUrl;

  ApiService(this.baseUrl);

  Future<Map<String, dynamic>> get(String path) async {
    final response = await http.get(	//http 메서드 get 호출
      Uri.parse('$baseUrl$path'),
      headers: {
        'Authorization': 'Bearer token',
        'Content-Type': 'application/json',
      },
    );

    return _handleResponse(response);
  }

  Map<String, dynamic> _handleResponse(http.Response response) {
    if (response.statusCode >= 200 && response.statusCode < 300) {
      return jsonDecode(response.body);
    } else {
      throw Exception('API Error: ${response.statusCode}');
    }
  }
}

Model

class User {
  final int id;
  final String name;

  User({required this.id, required this.name});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      name: json['name'],
    );
  }
}

Repository

class UserRepository {
  final ApiService api;

  UserRepository(this.api);

  Future<User> getUser() async {
    final data = await api.get('/users/1');	//서비스의 메서드 get 호출
    return User.fromJson(data);
  }
}

Notifier

class UserNotifier extends StateNotifier<User?> {
  final UserRepository repository;

  UserNotifier(this.repository) : super(null);

  Future<void> fetchUser() async {
    state = await repository.getUser(); //상태 변경
  }
}

Provider

final apiServiceProvider = Provider(
  (ref) => ApiService('https://api.example.com'),
);

final userRepositoryProvider = Provider(
  (ref) => UserRepository(ref.read(apiServiceProvider)),
);

final userProvider = StateNotifierProvider<UserNotifier, User?>(
  (ref) => UserNotifier(ref.read(userRepositoryProvider)),
);

...
    final user = ref.watch(userProvider);

    ElevatedButton(
      onPressed: () {
        ref.read(userProvider.notifier).fetchUser();
      },
      child: Text('Load User'),
    );

    Text(user?.name ?? 'Loading...');

Dio 라이브러리

Dio는 플러터 애플리케이션 전용으로 최적화된 네트워킹 및 파일 입출력을 제공하는 라이브러리이다. http 패키지 위에 설계된 Dio의 유연한 http 기능 및 인터셉터, 타임아웃을 활용하여 API 요청 및 응답 처리 로직을 간편하게 구성할 수 있다. 다음은 Dio에서 추가로 제공하는 기능이다.

http 클라이언트 기본 옵션 설정: http 클라이언트의 기본 헤더, 기본 URL, 연결 시간 제한 등의 옵션을 쉽게 설정 가능
인터셉터 지원: 인터셉터를 통해 모든 요청 및 응답에 네트워크 통신의 공통 로직 적용 가능 (토큰 자동 갱신, 공통 헤더 추가, 공통 응답 처리, 로깅, 전역 오류 처리 등)
사용자 정의: 사용자 지정 형식 처리나 직렬화 로직 등 자유도 높은 요청 및 응답 변환기 구현 가능
파일 업로드 및 다운로드: FormData, MultipartFile 등 대용량 파일 업로드/다운로드 기능 지원

Dio API 요청

Dio를 통해 http 요청을 보내기 위해서는 클라이언트 기본 설정을 적용한 Dio 인스턴스를 만들어야한다.

final dio = Dio(
  BaseOptions(
    baseUrl: 'https://api.example.com',
    headers: {
      'Authorization': 'Bearer token',
      'Content-Type': 'application/json',
    },
    connectTimeout: Duration(seconds: 5),
    receiveTimeout: Duration(seconds: 5),
  ),
);

GET (dio.get)

dio.get(String)

// 내부 정의
Future<Response<T>> get<T>(
  String path, {
  Map<String, dynamic>? queryParameters,
  Options? options,
  CancelToken? cancelToken,
  ProgressCallback? onReceiveProgress,
});

// 사용 예시
Future<void> fetchUser() async {
  try {
    final response = await dio.get('/users/1'); //파라미터로 엔드포인트 url 전달

    print(response.data);

  } on DioException catch (e) {
    // Dio 전용 에러 처리
    print('Dio error: ${e.message}');

    if (e.response != null) {
      print('StatusCode: ${e.response?.statusCode}');
      print('Error Data: ${e.response?.data}');
    }

  } catch (e) {
    // 기타 에러
    print('Unknown error: $e');
  }
}

POST (dio.post)

dio.post(String, Map)

// 내부 정의
Future<Response<T>> post<T>(
  String path, {
  Object? data,
  Map<String, dynamic>? queryParameters,
  Options? options,
  CancelToken? cancelToken,
  ProgressCallback? onSendProgress,
  ProgressCallback? onReceiveProgress,
});

// 사용 예시
Future<void> createUser() async {
  try {
    final response = await dio.post(
      '/users', //첫번째 파라미터 = 엔드포인트 url
      data: {'name': 'John'}, //두번째 파라미터 = body
    );

    print('Created: ${response.data}');

  } on DioException catch (e) {
    if (e.response?.statusCode == 400) {
      print('잘못된 요청');
    } else if (e.response?.statusCode == 401) {
      print('인증 필요');
    } else {
      print('기타 서버 에러');
    }

  } catch (e) {
    print('Unexpected error: $e');
  }
}

PUT (dio.put)

dio.put(String, Map)

//내부 정의
Future<Response<T>> put<T>(
  String path, {
  Object? data,
  Map<String, dynamic>? queryParameters,
  Options? options,
  CancelToken? cancelToken,
  ProgressCallback? onSendProgress,
  ProgressCallback? onReceiveProgress,
});

// 사용 예시
Future<void> updateUser() async {
  try {
    final response = await dio.put(
      '/users/1', //첫번째 파라미터 = 엔드포인트 url
      data: {'name': 'Updated Name'}  //두번째 파라미터 = body
      ,
    );

    print('Updated: ${response.data}');

  } on DioException catch (e) {
    print('Error: ${e.message}');

    if (e.response != null) {
      print('StatusCode: ${e.response?.statusCode}');
      print('Error Data: ${e.response?.data}');
    }

  } catch (e) {
    print('Unexpected error: $e');
  }
}

DELETE (dio.delete)

dio.delete(String)

//내부 정의
Future<Response<T>> delete<T>(
  String path, {
  Object? data,
  Map<String, dynamic>? queryParameters,
  Options? options,
  CancelToken? cancelToken,
});

//사용 예시
Future<void> deleteUser() async {
  try {
    final response = await dio.delete(
      '/users/1',
    );

    print('Deleted: ${response.data}');

  } on DioException catch (e) {
    print('Error: ${e.message}');

    if (e.response != null) {
      print('StatusCode: ${e.response?.statusCode}');
    }

  } catch (e) {
    print('Unexpected error: $e');
  }
}

Dio 라이브러리 내부 http 메서드 정의

파라미터	의미
path	요청 경로
data	body (POST/PUT/DELETE 가능)
queryParameters	URL 쿼리
options	헤더 등 추가 설정
cancelToken	요청 취소
onSendProgress	업로드 진행률
onReceiveProgress	다운로드 진행률

POST, PUT 요청에서 대용량 파일 전송

http 요청에서 body에 해당하는 두번째 파라미터(Object)에 Map 형식으로 전송

final formData = FormData.fromMap({
  'name': 'john',
  'file': await MultipartFile.fromFile(
    '/path/image.png',
    filename: 'image.png',
  ),
});  //텍스트와 파일 데이터를 담은 Map 정의

final response = await dio.post(
  '/upload',
  data: formData,  //data 파라미터로 정의해둔 Map 전송
);

flutter - 플러터로 크로스 플랫폼 앱 개발하기(4)

cusum26 — Sat, 28 Feb 2026 01:50:23 +0900

개발환경 세팅과 플러터 핵심 개념 학습을 어느정도 완료했으니 이를 토대로 플러터 프로젝트를 생성해보자. AI와의 채팅을 통해 갈등 관리 기능을 제공하는 간단한 채팅 앱 conflicAI을 만들기로 했다. VScode를 사용한다.

플러터 프로젝트 생성

모바일 앱이므로 웹이나 데스크톱 전용 패키지를 따로 세팅하지 않도록 --platforms로 iOS와 Android를 설정하고 --org로 프로젝트 담당 조직(추후 앱의 식별자에 포함)을 명시해서 프로젝트를 생성한다. 이때 프로젝트 이름은 snake_case로 설정해야 한다.

flutter create --platforms ios,android --org com.cusum26 conflic_ai

create 명령어로 프로젝트를 생성하면 다음과 같은 파일 구조가 만들어지고 앱의 진입점인 main.dart에는 기본적인 위젯과 카운터를 구현한 코드가 존재한다.

플러터 프로젝트 구조

저번 시간에 학습한 플러터 프로젝트의 구조와 실제 프로젝트의 파일 구조를 연결하면 다음과 같다.

Framework - lib 디렉토리
Embedder - android, ios 디렉토리

아직 구조가 잘 안 와닿는다면 복습

flutter - 플러터로 크로스 플랫폼 앱 개발하기(22)

본격적인 프로젝트 개발에 앞서 플러터의 필수 개념에 대해 알아보자. 플러터 아키텍쳐 플러터 프로젝트의 구조를 나름 비유하자면 다음과 같다. 무한하게 상상할 수 있는 Framework가 특정 규칙

imjyh01.tistory.com

pubspec.yaml

pubspec.yaml 파일은 앱에 필요한 모든 외부 자원과 설정을 관리하는데 주로 다음과 같은 역할을 한다.

외부 라이브러리(패키지) 추가

dependencies:
  flutter:
    sdk: flutter

  # 상태관리
  flutter_riverpod: ^2.5.1

  # 네트워크 (API 통신)
  dio: ^5.4.0

  # UI
  cupertino_icons: ^1.0.8
  flutter_svg: ^2.2.3
  
  # 네이버 지도 패키지
  flutter_naver_map: ^1.3.0

네이버 지도 연동, 카카오 로그인, API 통신 등을 구현하기 위해 해당 기능을 제공하는 외부 패키지를 dependencies에 추가함으로써 플러터가 해당 패키지의 소스 코드와 필요한 하위 라이브러리를 자동으로 다운받고 관리하게 된다. 추가로 외부 패키지가 업데이트되며 기존 코드에 영향을 주는 것을 방지하기 위해 특정 버전을 지정(^1.3.0)하여 안정성을 보장할 수 있다.

리소스 등록

flutter:
  uses-material-design: true
  
  # 이미지, 아이콘, JSON 등 일반 리소스 등록
  assets:
    - assets/images/logo.png
    - assets/images/fig1.png
  
  # 폰트 리소스 등록
  fonts:
    - family: MyCustomFont
      fonts:
        - asset: assets/fonts/Pretendard-Regular.ttf
        - asset: assets/fonts/Pretendard-Bold.ttf
          weight: 700  # bold 설정

assets, fonts 디렉토리에 저장된 이미지, 폰트 등 리소스의 경로를 pubspec.yaml에 등록하여 프로젝트가 이를 사용할 수 있게 하고 앱 실행환경에 포함시킨다.

flutter pub get

pubspec.yaml 파일 수정 후에는 위 명령어를 통해 추가 패키지 설치나 리소스 등록을 완료하여 개발 환경이 변경사항을 반영하도록 해야 한다.

크로스 플랫폼 지원 아키텍쳐

앱기능을 구현하고 화면을 그려내는 주된 작업 공간 lib 디렉토리 이외에도 플러터 프로젝트는 여러 디렉토리를 담고 있다. 플러터 엔진이 어떤 방식으로 크로스 플랫폼을 지원하는지 네이티브와의 연결 관점에서 더 알아보자.

lib 디렉토리
- 사진 촬영, 파일 접근, 버튼 색 설정과 같은 모든 논리적 명령을 내리고 화면 설계를 결정
플러터 엔진 = 신경계 역할
1. 척수와 신경 다발 : lib의 코드를 해석하여 화면을 렌더링하고 OS에서 요구하는 규칙에 따라 명령을 실행
2. 뇌→운동 뉴런→근육 : lib에서 내린 명령을 플러터 엔진이 직렬화(Dart 객체→공통 메시지 포맷) 후 네이티브로 전달하여 실행
3. 감각 기관 → 감각 뉴런→뇌 : 각 기기에서 발생하는 네이티브 이벤트(터치, 입력 동작)를 플러터 엔진이 역직렬화(네이티브 객체→Dart 객체) 후 lib로 전달하여 처리
android, ios 디렉토리
- 플러터 엔진의 동작을 각 OS가 요구하는 형식에 맞게 정의한 앱 구조(컨테이너)를 제공하여 네이티브 환경과 호환
- Dart 객체와 네이티브 객체가 공통 메시지 포맷을 통해 직렬화/역직렬화될 수 있도록 구조적으로 지원
네이티브 OS
- 애플리케이션을 실행하기 위해 특정 형식과 규칙을 요구
- Android : Activity가 엔트리 포인트인 APK 앱 패키지 구조와 Android용 네이티브 바이너리 규칙(.so) 요구
- iOS : AppDelegate가 엔트리 포인트인 IPA 앱 번들 구조와 iOS용 네이티브 바이너리 규칙(Mach-O) 요구
네이티브 HW
- lib의 명령을 실행하여 실제 네이티브 환경에서 카메라 렌즈를 움직이거나 화면에 빛을 내는 물리적인 동작 수행
- 네이티브에서 발생한 터치, 입력 등의 동작을 감지하고 이벤트(MotionEvent, UIEvent)를 생성하여 lib로 전달

네이티브 → lib 방향 :
수신 측 런타임인 플러터 엔진은 네이티브 객체 → Dart 객체 직접 변환을 지원하므로
송신 측인 네이티브에서 공통 메시지 포맷으로 변환할 필요 없이 데이터 전달 가능

lib → 네이티브 방향 :
수신 측 런타임인 네이티브(Kotlin/Swift)는 Dart 객체 → 네이티브 객체 직접 변환을 지원하지 않으므로
송신 측인 플러터 엔진에서 Dart 객체 → 공통 메시지 포맷 직렬화 후 데이터 전달 필요

플러터 프로젝트의 네이티브 제어 흐름 예시

1. lib에서 명령 호출
- 사진 촬영이 필요한 기능에서 camera.takePicture() 함수 호출

2. 직렬화
- 플러터 엔진이 함수를 공통 메시지 포맷으로 직렬화(Dart 객체 → 바이너리)

3. 플랫폼 채널을 통한 데이터 전송
- 직렬화된 메시지를 플랫폼 채널을 통해 Android/iOS 네이티브로 전달

4. 네이티브에서 실행
- OS가 메시지를 받아 카메라 API 호출
- 카메라 앱 실행 및 하드웨어 구동

5. 플랫폼 채널을 통한 데이터 반환
- OS는 촬영한 이미지 데이터를 플랫폼 채널로 전송

6.역직렬화
- 플러터 엔진은 전달받은 이미지 데이터를 역직렬화(바이너리 → Dart 객체)

7. lib에서 처리
- 네이티브에서 전달받은 이미지 데이터를 Dart 코드로 처리

각 네이티브 환경과 호환되도록 설계된 플러터 엔진과,
이 엔진이 네이티브 프로젝트 내부에서 실행되도록 지원하는 프로젝트 구조가
플러터 프레임워크가 제공하는 크로스 플랫폼의 핵심이다.

프로젝트 세팅

pubspec.yaml 패키지 추가

name: conflic_ai
description: "AI 상담 및 갈등 해결 서비스 앱"
publish_to: 'none'

version: 1.0.0+1

environment:
  sdk: ^3.11.0

dependencies:
  flutter:
    sdk: flutter

  # 상태관리
  flutter_riverpod: ^2.5.1

  # 네트워크 (AI API 호출)
  dio: ^5.4.0

  # 로컬 저장 (토큰/설정)
  shared_preferences: ^2.2.2

  # UI
  cupertino_icons: ^1.0.8
  flutter_svg: ^2.2.3

  # 모델 비교
  equatable: ^2.0.8
  
  # 하드웨어 제어
  speech_to_text: ^7.0.0
  image_picker: ^1.1.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^6.0.0

flutter:
  uses-material-design: true

앱 개발에 필수적인 기본 라이브러리 의존성을 추가한다.

상태관리 - riverpod
네트워크 통신 - dio
UI - cupertino, flutter_svg
하드웨어 제어 (필수는 아님) - STT, image_picker

프로젝트 실행

Android 에뮬레이터보다 빠르게 돌아가는 iOS 시뮬레이터로 프로젝트를 실행해보자.

open -a Simulator
flutter run

먼저 pubspec.yaml에 등록된 외부 패키지를 다운받은 후 시뮬레이터 위에서 앱의 진입점인 main.dart의 카운터가 실행되는 것을 볼 수 있다.

flutter - 플러터로 크로스 플랫폼 앱 개발하기(2)

cusum26 — Fri, 27 Feb 2026 20:39:07 +0900

본격적인 프로젝트 개발에 앞서 플러터의 필수 개념에 대해 알아보자.

플러터 아키텍쳐

플러터 프로젝트의 구조를 나름 비유하자면 다음과 같다. 무한하게 상상할 수 있는 Framework가 특정 규칙에 따라 상상력을 전기적 신호로 표현할 수 있는 Engine이라는 뇌로 실체화되고, Embedder를 통해 Native까지 전달된 뇌의 전기적 신호가 실제 물리적 움직임으로 구체화된다...

추상화된 하나의 뇌로 네이티브라는 서로 천차만별인 신체를 적절하게 제어하기 위해서는 뇌의 신경이 각 신체 전용 제어 구조로 연결돼야 한다. 이때 Embedder가 각 몸뚱아리 전용 제어 틀을 이 추상화된 뇌에게 제공하는 역할을 한다.

Embedder

세레브로

플러터로 만든 앱이 기기에서 실행되려면 각 네이티브 환경의 인터페이스 규칙을 따르도록 설계되어야 한다. 임베더는 플러터 엔진이라는 뇌를 크로스 플랫폼으로 동작시키기 위해 네이티브와의 연결부를 담당한다. 영화 엑스맨에 나오는 세레브로라는 기계처럼 뇌와 기기를 연결하는 틀을 제공한다고 볼 수 있다.

임베더는 각 OS별 네이티브 프로젝트 구조를 제공하여 플러터 엔진이 각 OS 런타임 위에서 문제없이 실행될 수 있게 한다.

Android: Gradle, manifest, Java/Kotlin 코드
iOS: Xcode 프로젝트, Info.plist, Swift/Obj-C 코드

플러터 엔진은 이 디렉토리에서 정의된 규칙과 구조를 통해 Dart 코드로 네이티브 코드와 통신할 수 있고, OS가 제공하는 네이티브 API를 호출할 수 있다. 플러터로 만든 앱이 임베더를 매개로 네이티브 앱으로서 실행되고, 그 런타임 내부에서 플러터 엔진을 작동시킴으로써 OS를 통해 기기(카메라, 블루투스, GPS, 센서 등)를 제어하고 그 결과를 다시 전달받아 처리할 수 있다.

Engine

플러터 엔진은 다음과 같은 역할을 담당한다.

Skia 자체 렌더링 (화가 역할)
플러터 엔진은 각 기기의 OS가 제공하는 네이티브 UI를 빌려 쓰는 것이 아니라 스키아(Skia) 또는 임펠러(Impeller)라는 강력한 그래픽 엔진을 자체적으로 탑재하고 있다. 따라서 부드러운 화면을 직접 그려내며 OS와 상관없이 동일한 UI/UX를 보장한다.
다트 런타임 (통역사 역할)
lib에 작성된 Dart 코드를 실시간으로 실행하고 관리한다. 개발 환경에서 핫 리로드(Hot Reload)를 지원해 수정한 코드를 즉시 화면에 반영하고 배포 시에는 기계어로 변환해 네이티브 앱에 가까운 고성능을 보장한다.
플랫폼 채널 관리 (통로 역할)
lib의 코드와 네이티브 환경 사이에서 데이터를 전달하는 통로(플랫폼 채널)를 관리한다. lib에 작성된 카메라, 블루투스, 사진 접근과 같은 명령을 각 OS에 바이너리로 직렬화하여 전달하고, 네이티브로부터 전달받는 데이터를 Dart로 역직렬화여 lib로 전달한다.
파일, 네트워크 IO (문지기 역할)
플러터 엔진은 앱에서 발생하는 파일 읽기·쓰기, 네트워크 요청과 같은 입출력 작업을 관리한다.
- 파일 I/O: 로컬 저장소(앱 내부, 외부 저장소 등)에서 데이터를 읽고 쓰는 작업을 처리한다. 예를 들어, 앱 설정 저장, 이미지 다운로드 후 캐싱 등은 플러터 엔진이 OS별 파일 시스템 접근을 중재하여 안전하게 수행한다.
- 네트워크 I/O: HTTP 요청, 소켓 통신 등 네트워크 연동을 담당한다. Dart 코드에서 API 호출을 하면 플러터 엔진이 OS 네트워크 스택과 연결하여 데이터를 주고받고, 응답을 다시 Dart 코드로 전달한다.

위젯

위젯은 화면 표시에 있어서 가장 기본적인 단위로 StatelessWidget, StatefulWidget, InheritedWidget 세 종류가 존재한다. 아주 대표적인 앱의 홈 화면에서 각 위젯울 찾아보고 어떤 느낌인지 감을 잡자.

무신사 앱 UI

StatelessWidget

StatefulWidget

InheritedWidget

이 위젯은 화면의 알맹이가 되는 정보 전달용 위젯으로 statefulWidget이 담는 컨텐츠(데이터)를 뿌려주는 데이터 바구니라고 생각하면 편하다.

위 위젯은 이런 구조로 구현할 수 있을 것이다.

CartProvider(InheritedWidget) ← 장바구니 데이터 뿌려주기

└─ CartIcon (StatelessWidget)

└─ ItemCountBadge (StatefulWidget) ← 장바구니 숫자 받아오기

Inherited를 통한 State의 전달

상위 StatefulWidget (State 보유)
        └── MyInheritedWidget (State 포함)
                 └── 하위 StatefulWidget (context 통해 State 접근)

하위 StatefulWidget가 받는 State 변경 정보에 대한 데이터 소스는 다음과 같다.

위젯 필드 이용(부모가 전달) - 생성자에서 부모 필드에 직접 접근해서 받아옴 : didUpdateWidget()으로 감지 : 자동으로 리빌드
InheritedWidget 이용(트리 기반 공유) - context 기반 전역, 상위 상태를 감지해서 받아옴 : 자동으로 리빌드
일반 객체 (가장 흔함) - animation 같이 변경될 수 있는 값을 가진 위젯이 아닌 객체가 State에 존재 : 자동 rebuild 안 됨 → setState를 따로 호출해야 반영됨

InheritedWidget이 상위 위젯 트리에서 데이터를 받아오는 거면 어차피 부모-자식으로 전달되는 위젯 필드로 충분히 전달 가능한데 InheritedWidget이 굳이 왜 필요한지 의문이 들 수 있다.

= 어차피 상위 트리에서 내려오는 거면 공통 부모에서 받아서 위젯 필드로 내려주면 되는 거 아닌가

물론 충분히 가능하지만 규모가 커지면 다음과 같은 Prop Drilling 문제가 생긴다.

State를 보유한 상위 StatefulWidget이 InheritedWidget에 담아 State를 전달하고 하위 StatefulWidget에서 해당 State를 참조하는 구조는 분명 직관적이다. 그러나 이런 구조는 View를 담당하는 StatefulWidget이 Model에 해당하는 State 변경 로직까지 책임진다는 점에서 UI와 비즈니스 로직이 강하게 결합되어있다고 볼 수 있다. 이는 위젯 중심의 선언형 UI로 MVVC를 지향하는 플러터의 컨셉과 배치된다. 이에 따라 Model과 View의 책임 분리를 제공하는 Provider 구조가 등장했다.

Provider

기본적으로 Provider는 위젯 간 State 전달을 담당하는 라이브러리이다. 앞서 언급한 InheritedWidget의 데이터 전달 구조와의 차이점은 다음과 같다.

플러터에는 Provider를 포함하여 Bloc, Riverpod, getX 등 상태 관리와 전달을 담당하는 여러 패턴, 라이브러리가 존재한다. 이에 관해선 다음 시간에 더 자세히 알아보자.

라이프사이클

라이프사이클은 위젯이 생성되고 삭제, 종료되는 과정에서 발생하는 여러가지 이벤트들의 호출 순서이다. 기본적으로 화면을 담당하는 Widget은 애플리케이션 내내 발생하는 여러 이벤트들에 따라 충분히 변경되거나 삭제, 재생성될 수 있고, 이 결과로 화면은 바뀌거나 안 바뀔 수도 있다.

StatelessWidget

StatelessWidget은 기본적으로 상태가 존재하지 않으므로 생성 ~ 삭제 사이에 변경이 없다(immutable). 따라서 처음에 한 번 빌드되면 이후 재빌드 시 UI 변화가 없는 경우가 많다.

라이프사이클

StatelessWidget 생성자 : immutable → final
createElement() : 렌더링 메타데이터 생성(build때 쓰임)
build() : 자식 위젯트리 반환 = ui 렌더링

StatefulWidget

상태를 담고있는 StatefulWidget은 기본적으로 생성 ~ 삭제 사이에 상태가 쉴 새 없이 변경된다. 따라서 State라는 별도 객체(위젯이 아님)로 상태를 분리한 채로 존재하며 빌드를 포함한 상태 관리는 전부 State에 위임한다.

StatefulWidget 클래스: 상태를 가지는 위젯
State 클래스: 위젯의 상태를 관리하는 메서드를 제공하는 클래스 (위젯이 아님)

Widget 내부에는 immutable한 최소 값만 남기고 변경될 값들은 따로 State 객체에 빼둠으로써 build()함수가 State에 존재한다. 따라서 StatefulWidget은 부모 위젯이 재빌드될 때에나 생명주기에 영향이 가고, 상태 변경은 위젯의 생명주기와 독립적으로 이뤄진다.(State의 setSate() 함수에 의존)

그러나 여기서 놓치기 쉬운 점이 있는데 StatefulWidget이 State를 보유하며 setState 직접 호출이 가능하긴 하지만 State 인스턴스 자체는 완전히 독립적으로 존재하며 서로 참조하는 구조라는 것이다. 즉 기존 인스턴스가 사라지고 새로운 위젯 인스턴스가 생성되더라도 기존 State 인스턴스는 유지될 수 있다.

StatefulWidget과 State의 관계

위 구조로 다음을 알 수가 있다.

State가 유지되는 동안 참조하는 Widget 인스턴스는 여러 번 바뀔 수 있다 - State내부 widget 필드의 값만 변경
StatefulWidget 내부의 key, runtimeType이라는 두 개 필드가 참조할 State를 유일하게 결정하고 이 필드는 불변이다 - 위젯 인스턴스가 유지되는 동안 한 State만 가질 수 있음

라이프사이클

StatefulWidget 생성자 : immutable → final (statefulwidget에 생성자로 전달받는 immutable한 필드는 위젯트리 계산에 사용)
createState() - 한 번만 : 위젯의 상태를 구성하는 값들을 관리하는 State 객체 생성
initState() - 한 번만 : State 객체의 필드 초기화 - context 접근 불가능 = inheritedWidget의 데이터 사용 불가
- 변수 초기화
- AnimationController 생성
- Stream 구독 시작
- API 호출 시작
didChangeDependencies() - 한 번만 : context 의존성 반영 - context 접근 가능
- Theme (앱의 전체 디자인 설정) 변경 반영
  - 다크모드 ↔ 라이트모드
  - primaryColor 변경
- MediaQuery(디바이스 환경 정보) 변경 반영
  - 화면 회전 (가로/세로)
  - 키보드 올라옴
  - 화면 크기 변경
  - 시스템 폰트 크기 변경
- Provider 값 변경 반영
  - 구독 중인 InheritedWidget의 데이터
build() - 여러 번 : 변경된 설계도로 화면 렌더링 - 그려야하는 데이터가 변하면 무조건 호출해서 화면에 반영
- 생성 직후 호출
- 부모 변경 시 호출
- setState 이후 호출
- 의존성 변경 시 호출
setState() - 여러 번 : State 인스턴스의 필드 값을 변경하고 다음 프레임에 build를 실행시키는 트리거 함수
- 위젯과 State 인스턴스 자체는 그대로 유지, 값만 변경
- 상태변경 로직을 안에 넣어서 사용 권장
- 라이프사이클에 포함되지 않음
didUpdateWidget() - 여러 번 : 새 위젯 인스턴스가 생성된 상황에서 State의 기존 인스턴스는 유지하며 참조하는 위젯만 변경
- AnimationController를 새 설정값으로 재구성할 때
- TextEditingController를 부모로부터 동기화할 때
- 부모 리빌드에 의해 외부에서 전달받은 값이 바뀌었을 때 setState()로 내부 상태 업데이트 필요
dispose()- 한번만 : 메모리 누수 방지하며 위젯 종료
- 진행 중인 작업 취소
- 리소스 해제
- 상태 정리

didUpdateWidget() 예시

위와 같은 캘린더 화면을 분석해보자.

StatefulWidget: 일정 정보를 보여주는 위젯
State: 제목, 시작/종료 시간 같은 상태 데이터를 보유
InheritedWidget: 일정 정보를 갖고 있는 데이터 소스

다음은 23일에서 27일로 날짜를 옮겼을 때 화면이 변경되는 과정이다.

1. 날짜별 일정 정보를 담고 있는 InheritedWidget이 바뀜 (23일 → 27일)

2. 27일에 대한 새 StatefulWidget 인스턴스가 생성됨
- 새 Widget 인스턴스가 메모리에 만들어짐
- Flutter 엔진이 새 인스턴스의 runtimeType과 key를 기존 Widget과 비교

3. State 인스턴스는 제목, 시작/종료 시간으로 동일 형식 = runtimeType과 key가 기존 위젯과 동일 → 기존 State 객체 유지
- 기존 State 객체와 새 Widget 연결
- State 객체의 widget 필드가 새 Widget 참조로 갱신
- 이전 Widget 인스턴스는 oldWidget으로 전달

4. didUpdateWidget(oldWidget) 호출
- oldWidget = 이전 StatefulWidget
- widget = 새 StatefulWidget

5. setState() 호출

- State 내부 필드 값(일정 정보) 갱신

6. build() 호출

- 새 Widget 데이터 + 기존 State 구조를 사용해 UI 갱신

레이아웃 위젯

각 위젯에서 인식하는 제스처를 기준으로 분류하면 다음과 같다.

터치/클릭 : Container, Row&Column, Expanded, Stack, Positioned, SizedBox, TabBar
스크롤 : ListView, GridView
스와이프/슬라이드 : PageView

터치/클릭

Container

사각형 상자

다음과 같은 옵션이 존재한다.

padding: 내부 여백
height : 높이
width: 너비
color: 배경색
child: 자식 위젯에 적용될 설정
decoration: 컨테이너의 외형(모양, 배경, 테두리 등)

Row & Column

Row : 가로 레이아웃

Column : 세로 레이아웃

다음과 같은 옵션이 존재한다.

mainAxisAlignment : 각 레이아웃 방향으로 정렬
crossAxisAlignment : 각 레이아웃 수직 방향으로 정렬 (부모 위젯의 높이, 너비 기준- 설정 필요)
children : 정렬될 요소들을 리스트 형태로 화면에 출력 ( children : List.generate(…) )

Expanded

Row와 Column 안에서 남은 공간을 채우도록 확장하는 자식 위젯

Expanded = Row/Column의 자식
기존 자식 레이아웃은 변경되지 않음
부모 위젯(Row/Column)의 공간을 분할/채움
flex 속성으로 비율 조절 가능

Stack

여러 위젯이 서로 겹쳐 배치된 위젯

다음과 같은 옵션이 존재한다.

fit:
- loose : 자식 위젯의 크기를 스택 위젯 크기에 맞게 자유롭게 배치 가능
- expand: 자식 위젯이 스택 위젯과 동일한 크기 고정
- passthrough : 자식 위젯이 스택 위젯의 크기와 위치를 무시하고 자유롭게 배치 가능

children:
- children= [ widget1, widget2 ….] 로 정의 = List<Widget> 타입
- 선언되는 순서로 z-index 조절
- 스택: 밑에서부터 쌓아올림 = 먼저 선언된 자식 위젯이 밑에 배치

Positioned

스택 내부에서 하위 위젯의 위치 설정을 제공하는 위젯

부모 위젯을 기준으로 절대 위치를 설정하는 다음 옵션이 존재한다.

left
top
right
bottom

SizedBox

고정 크기 상자

아이템 간 간격 설정에 용이

(Figma에서 그루핑하면 간격 일정하게 조절 가능한게 SizedBox로 선택되는 거 같음)

TabBar

탭 메뉴를 통한 화면 이동을 제공하는 위젯

Toss앱의 탭 메뉴

세 개의 객체로 구성

TabBar : 화면 이동을 제공하는 탭 메뉴
TabBarView : 탭바를 통해 이동 시 전환되는 각각의 화면
TabBarController : 둘을 연결

옵션

controller: _tabController로 컨트롤러에서 설정한 length만큼의 탭 메뉴 등록
tabs: const [Widget1, Widget2, Widget3 …] 형식으로 TabBar에 보일 탭 메뉴 등록
labelColor - 현재 선택된 메뉴의 색상
unselectedLabelColor - 현재 선택되지 않은 메뉴의 색상 설정
labelPadding - 메뉴 간 간격 조정
indicatorWeight - 선택된 메뉴의 인디케이터 두께 조절
labelStyle, unselectedLabelStyle - 선택된 메뉴와 선택되지 않은 메뉴의 텍스트 스타일 설정

TabController

초기값 설정 필요

옵션

initialIndex: 초기 “탭-페이지” 설정
animationDuration: 탭 메뉴를 눌렀을 때 인디케이터 애니메이션 효과 설정
length: 메뉴(탭) 개수 설정
vsync: 애니메이션을 장치 디스플레이의 수직 동기화와 맞추는 역할
- with TickerProviderStateMixin로 클래스 추가 필요
- 화면 새로고침 타이밍에 맞춰 프레임마다 알맞게 tick 이벤트를 전달
- 애니메이션 시작/중지/재생 속도 제어
- vsync 없으면 표시 안되는 프레임의 애니메이션을 계속 계산 → 배터리/CPU 낭비

TabBarView

controller: _tabController로 컨트롤러에서 설정한 length만큼의 뷰 등록
children: [Widget1, Widget2, Widget3] 형식으로 각 탭 메뉴에 대응하는 화면 정의

스크롤

ListView

스크롤 가능 항목을 목록으로 배치

옵션

scrollDirection: 스크롤방향
- 세로(디폴트 설정) : axis.vertical, 가로 : axis.horizental

reverse: 스크롤 방향과 스크롤 시작 위치를 뒤집음
- ListView는 원래 위에서 시작해서 밑으로 렌더링하는데 reverese가 켜지면 밑에서 시작해서 위로 렌더
- reverse = false) 스크롤 시작 위치 : 맨 위, 스크롤 방향 : 내려서 최신 컨텐츠 조회
- reverse = true) 스크롤 시작위치 : 맨 밑, 스크롤 방향 : 올려서 예전 컨텐츠 조회
- 콘텐츠 순서 자체를 바꾸는 건 아님, 화면 상 렌더링 시작 위치와 스크롤 진행 방향만 반대로
- 채팅창 구현에 적용

controller: 스크롤 제어, 이벤트 처리 제공
- initState()와 연계하면 매 상태 생성 시 스크롤 위치 0부터 시작하도록 구현 가능
→ 스크롤 끝에 도달 확인 후 새로운 데이터 불러오기(새로운 자식 위젯 생성)로 무한 스크롤 구현

pysics: 스크롤 동작 엔진 설정
- BouncingScrollPhysics - 스크롤 끝에서 튕기는 효과(ios)
- ClampingScrollPhysics - 스크롤 끝에서 멈추는 효과(android)
- FixedExtentScrollPhysics - 스크롤 이동 단위 균일
- NeverScrollableScrollPhysics - 스크롤 비활성화

padding: 아이템 간 간격 조정

cacheExtent: 스크롤로 화면 이동 시 기존 화면에서 추가로 캐시해 둘 영역 설정
- 반응 속도와 초기로딩 속도 간의 트레이드오프

GridView

스크롤 가능 위젯을 그리드로 배치

인스타 피드처럼 동일 유형 위젯(이미지)을 모아보는 화면에 적용

gridDelegate: 그리드 레이아웃 정의
- (열 수, 크기, 열 사이 간격 등) → 한 줄에 몇 개 보여줄지 정하면 크기에서 나눠서 행 결정
- SliverGridDelegateWithFixedCrossAxisCount
-> crossAxisCount: 타일 크기와 관계없이 열 수 고정 (타일의 가로가 길 경우 양옆으로 화면 넘어갈 수 O)
- SliverGridDelegateWithMaxCrossAxisExtent
-> maxCrossAxisExtent: 타일 최대 너비를 고정 (화면 가로 크기 / 타일 너비로 열 수 계산)
- mainAxisSpacing, crossAxisSpacing : 그리드 셀 간 간격
scrollDirection
reverse
controller
padding: GridView 내부 간격 설정 (테두리 간격)
- 영화관 좌석처럼 GridView에 내부 간격을 두면 해당 여백을 잡고 스크롤하기에 UX적으로 유용

스와이프/슬라이드

PageView

스와이프 제스처를 인식해서 페이징을 제공하는 위젯

슬라이드 배너 구현에 유용

옵션

children: 슬라이드로 등장할 자식 위젯, List<Widget> 형태로 구성
scrollDirection
controller
pageSnapping: 스와이프 시 자동으로 페이지가 완전히 전환되도록 하는 효과
onPageChanged: 페이지 완전 이동 시 콜백 함수 등록, 페이지 이동 단위로 특정 이벤트 수행 가능

pageSnapping: false로 동작하는 아이폰 창 이동 화면

Controller가 제공하는 addListener가 있는데 굳이 onPageChanged옵션으로 콜백 함수를 등록하는 이유는 다음과 같다.

구분	addListener	onPageChanged
호출 시점	스크롤 중 계속	페이지 전환 완료
값	float (진행률)	int (페이지 index)
용도	애니메이션 동기화, parallax, 스크롤 진행 상태	페이지 인덱스 변경 후 처리, indicator, 상태 업데이트

addListener = 진행 상태 연속 추적

onPageChanged = 페이지 전환 완료 시점 알림

구현 편의상 페이지 단위 전환 전용으로 onPageChanged를 제공하는 것

애니메이션

애니메이션은 시각적으로 흥미로운 피드백 제공하는 효과이다. 애니메이션은 투명도가 변하든, 위치나 크기가 변하든, 기본적으로 시간에 따라 값이 변하는 과정 그 자체이므로 당연히 StatefulWidget의 형태로 제공된다. 이 때문에 헷갈리기 쉬운데 앞서 설명했듯이 이 애니메이션 위젯에게 변화된 값을 뿌리는 데이터 소스는 별도 애니메이션 객체(AnimationController)이고 위젯이 내부에서 참조 중이다.

플러터에서 제공하는 애니메이션은 암시적, 명시적 두 종류가 있다. 애니메이션 위젯이 혼자 애니메이션 효과를 그리는 것이 아님을 유념하고 플러터의 애니메이션 위젯을 알아보자.

애니메이션이 그려지는 과정

1. 초기값 → 결과값 코드 실행
2. Tween 생성
- Tween : 값 보간 공식
3. Animation<double> 생성
- Animation : 시간에 따른 값 변화를 저장
4. controller.forward()
- controller : 시간 진행 제어
5. 매 프레임마다 listener 실행
- listener : 값 변경 감지
6. setState() 호출로 값 변경
- 새 값으로 갱신, 빌드 호출
7. build() 호출로 화면 반영
- 변경된 화면 표시

Tween이 값 범위를 보간하고
Animation이 시간에 따라 값을 만들고
Controller가 시간을 움직이고
listener가 rebuild를 트리거한다.

Flutter는 값이 바뀌었는지 감시하는 게 아니라 rebuild 신호가 왔는지를 감지하여 화면을 그리는 엔진이고,
애니메이션은 프레임마다 rebuild 신호를 발생시키는 방식으로 구현된다.

암시적 애니메이션

플러터는 내부에 AnimationController가 이미 정의된 애니메이션 위젯을 제공한다. 개발자가 직접 AnimationController를 정의하고 중간 동작을 커스텀한 명시적 애니메이션을 만들 수도 있지만 여기선 암시적 애니메이션에 대해 알아보자.

공통 옵션

duration: 애니메이션의 실행 시간 설정 = 값의 변화가 일어나는 시간
Curve: 값이 변하는 속도를 동적으로 설정 = (AnimationController가 0→1로 진행되는 과정을 시간별로 어떻게 보간할지)
- 0→1 변하는 과정을 x축을 시간으로하는 함수 개형으로 표현하면
- Curves.linear : 선형 함수
- Curves.ease : sigmoid 함수
- Curves.easeIn : 지수 함수
- Curves.easeOut : 로그 함수
- Curves.easeInOut : sigmoid 함수
- Curves.fastOutSlowIn : tan 함수
기타 곡선 효과
- Curves.bounceIn : 시작에 바운스
- Curves.bounceOut : 끝에 바운스
- Curves.elasticIn : 시작 부분에 탄성
- Curves.elasticOut : 끝 부분에 탄성
onEnd: 애니메이션 끝날때 호출되는 콜백 함수 = 애니메이션 종료 후 특정 이벤트 처리하도록 설정
- 암시적 애니메이션 = 내부에서 매프레임 자동 setState → onEnd에서 별도 setState 불필요
- 명시적 애니메이션 = AnimationController 직접 정의 → Animation listener에서 매 프레임 setState를 직접 호출 필요

AnimatedOpacity

하위 위젯에 페이드 인, 페이드 아웃 애니메이션을 제공하는 위젯

opcaity는 double 타입 변수로 위젯의 불투명도(선명도) 값을 조절한다.

opacity : (flag ? 0.2 : 1)

-> duration 동안 불투명도가 0.2부터 1까지 tween에 따라 증가

AnimatedPositioned

Positioned 위젯의 위치와 크기를 애니메이션으로 변경하는 위젯

Positioned 위젯에 애니메이션을 입힌거라 스택의 하위 위젯으로 존재한다.

left : (flag ? 0 : 150)

-> duration 동안 Positioned의 x좌표가 부모 위젯 기준으로 0부터 150까지 tween에 따라 증가

AnimatedContainer

Container 위젯의 width, height, color, padding, alignment을 애니메이션으로 변경하는 위젯

width : (opacity ? 100 : 150),
height : (opacity ? 100 : 150)

-> duration 동안 Container의 너비와 높이가 100부터 150까지 tween에 따라 증가

라우팅

라우팅에서 등장하는 주요 개념은 다음과 같다.

MaterialApp
- 앱 전체를 감싸는 최상위 위젯
- 앱을 실행하면 가장 처음 렌더링 되는 첫 위젯
- 내부에서 Navigator, Theme, Locale 등 전역 상태를 관리
WidgetBuilder
- Widget의 생성자 함수를 호출하는 함수타입
- routes 옵션에서 위젯의 이름(String)과 위젯의 생성자(WidgetBuilder) 쌍으로 등록
- 화면 전환 시 페이지 단위로 위젯 빌더 호출
Navigator
- 화면 전환을 담당하는 스택 구조 객체
- 들어갔던 화면(Route 객체)을 스택에 쌓아두고 관리
- push/pop으로 새 화면 이동/이전 화면 복원
Route
- Navigator 스택에 들어가는 화면 단위 객체로 push/pop의 대상
- 내부적으로 builder: (context) => MyPage()같은 함수를 통해 위젯을 생성

navigator

이름 기반 명령형 라우팅 (Navigator 1.0 방식)

이름을 전달받은 네비게이터가 Map<String, WidgetBuilder>으로 builder를 찾아 Route를 생성하고 스택에 직접 push/pop함으로써 화면 전환

MaterialApp (최상위 위젯)
    └─ Navigator 생성(routes 라우팅 정보 전달)
        └─ pushNamed 호출 ('/second')
            └─ Navigator가 route name 수신 ('/second')
                └─ routes(Map<String, WidgetBuilder>)에서 builder 찾음
                    └─ 그 builder를 감싸는 Route 객체 생성 (MaterialPageRoute)
                        └─ Navigator 스택에 push
                            └─ Route가 builder 실행
                                └─ Widget 생성 (SecondPage)
                                    └─ build() 실행 → 화면 렌더링

Page 기반 선언형 라우팅 (Navigator 2.0 방식)

Page 기반에서는 push 호출 없이 pages의 상태 변경만으로 화면 전환 구현

MaterialApp (최상위 위젯)
    └─ Navigator(pages: List<Page> 전달)
        └─ 앱 상태 변경 (pages 리스트에 새 Page 객체 추가)
            └─ setState()로 pages 리스트 변경
                └─ Navigator 리빌드
                    └─ Navigator가 기존 pages와 새 pages diff 비교
                        └─ 새 Page에 대해 createRoute(context) 호출
                            └─ Route 객체 생성 (MaterialPageRoute)
                                └─ Navigator가 Route를 Overlay에 추가
                                    └─ Route가 buildPage() 실행
                                        └─ Widget 생성 (SecondPage)
                                            └─ build() 실행 → 화면 렌더링

위 선언형 라우팅 방식은 웹(Web)과 상태 기반 앱 아키텍처를 제대로 지원하기 위해서 최근에 업데이트됐다.

왜 더 복잡한 구조로 업데이트 됐는지에 대한 이유는 다음과 같다고 한다..

Navigator 1.0	Navigator 2.0
모바일 중심	웹 + 모바일
명령형	선언형
push/pop 기록	상태 기반
URL 무관	URL 동기화 가능

그러나 내가 참고하는 책은 스택을 이용한 명령형 라우팅 기준으로 쓰여 있으므로 우선 Navigator 1.0 방식을 학습한다.

Navigator 이동 방식

Navigator.push, Navigator.pushNamed

새로운 페이지로 이동

1. 앱에서의 페이지 전환 = 새로운 화면 = 네비게이터 스택에 push

2. 새로운 화면 = 새로운 위젯 생성 → 위젯 생성자 인터페이스는 Widget build(BuildContext context)

= context를 인자로 전달하며 새 위젯 생성자를 호출

이 두 가지를 고려하면 화면 이동을 담당하는 다음 두 함수가 직관적으로 이해된다.

Navigator.push(		// Route 객체를 직접 지정해서 화면 전환
  context,
  MaterialPageRoute(
    builder: (context) => SecondPage()
  )
);


Navigator.pushNamed(context, '/second');  //이름 기반 라우팅

메서드	전달 인자	특징
push	Route 객체	이름 없이 직접 Route/Widget 지정해서 생성자 호출
pushNamed	이름	MaterialApp.routes에 들러서 이름에 대응하는 위젯 생성자 찾아서 호출

aliasing 차이만 있을 뿐 사실상 같은 구조로 동작함을 알 수 있다.

Navigator.pop

현재 페이지 지우고 직전 페이지로 이동

initialRoute: '/'  //홈화면
 
Navigator.pushNamed(context, '/second');  //홈화면 위에 두번째 화면

Navigator.pop(context); // 두번째 화면을 지움 = 이전화면(홈화면)이 top

Navigator.pushReplacementNamed

현재 페이지 지우고 새 페이지로 이동

initialRoute: '/'  //홈화면
 
Navigator.pushNamed(context, '/second');  //홈화면 위에 두번째 화면 

Navigator.pushReplacementNamed(context, '/third'); 
// 현재화면(두번째 화면)을 지우고 세번째 화면 푸시 = 홈화면 위에 세번째 화면

Navigator.popUntil

현재 페이지부터 특정 페이지 사이의 모든 페이지를 지우고 원하는 특정 페이지로 이동

Navigator.popUntil(context, ModalRoute.withName("/"))

→ 현재 화면부터 이름이 `/`인 화면까지 모든 화면을 pop

회원 가입처럼 여러 단계에 걸친 동작 종료 후 새 화면으로 이동하도록 구현할 때 활용

Navigator.pushNamed(context, '/home'); //홈화면

Navigator.pushNamed(context, '/first');  // 회원가입 첫번째 단계

Navigator.pushNamed(context, '/second');  // 회원가입 두번째 단계

Navigator.pushNamed(context, '/third');  // 회원가입 세번째 단계

Navigator.popUntil(context, ModalRoute.withName("/home")); 
//회원가입 완료 후 회원가입 단계 페이지 다 지우고 홈화면으로 복귀

flutter - 플러터로 크로스 플랫폼 앱 개발하기(1)

cusum26 — Sun, 22 Feb 2026 03:14:48 +0900

개발 환경 세팅

플러터 설치 (macOS 기준)

(1) 터미널로 설치하는 방법

1. 터미널 앱에서 다음 명령어로 플러터 sdk 설치 (brew는 이미 설치 완료 가정)

brew install --cask flutter

2. flutter 명령어 사용을 위한 PATH 추가 (.zshrc 파일에 sdk가 설치된 경로를 등록)

수동으로 설정한 디렉토리에 다운로드 했다면 "which flutter" 명령어로 sdk 설치된 경로 확인 가능

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. 설치 확인

flutter --version

4. 적용 확인

flutter doctor

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.41.1, on macOS 15.7.3 24G419 darwin-arm64, locale ko-KR)
[✗] Android toolchain - develop for Android devices
✗ Unable to locate Android SDK. Install Android Studio from: https://developer.android.com/studio/index.html On first launch it will assist you in installing the Android SDK components. (or visit https://flutter.dev/to/macos-android-setup for detailed instructions). If the Android SDK has been installed to a custom location, please use flutter config --android-sdk to update to that location.
[✗] Xcode - develop for iOS and macOS (Xcode 26.2)
✗ Unable to get list of installed Simulator runtimes.
✗ CocoaPods not installed. CocoaPods is a package manager for iOS or macOS platform code.
Without CocoaPods, plugins will not work on iOS or macOS. For more info, see https://flutter.dev/to/platform-plugins For installation instructions, see https://guides.cocoapods.org/using/getting-started.html#installation
[✓] Chrome - develop for the web
[✓] Connected device (1 available)
[✓] Network resources

위와 같은 결과 나오면 설치 완료

(2) VS Code에서 설치하는 방법

1. VS Code 마켓플레이스에서 Flutter 확장 프로그램 설치

2. VS Code화면 우측 하단에 뜨는 Dart extension, flutter SDK 플러그인 설치를 물어보는 두 개 알림에 install을, 환경변수 PATH 추가를 물어보는 알림에 ok를 클릭

3. 설치 확인

flutter --version

4. 적용 확인

flutter doctor

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.41.1, on macOS 15.7.3 24G419 darwin-arm64, locale ko-KR)
[✗] Android toolchain - develop for Android devices
✗ Unable to locate Android SDK. Install Android Studio from: https://developer.android.com/studio/index.html On first launch it will assist you in installing the Android SDK components. (or visit https://flutter.dev/to/macos-android-setup for detailed instructions). If the Android SDK has been installed to a custom location, please use flutter config --android-sdk to update to that location.
[✗] Xcode - develop for iOS and macOS (Xcode 26.2)
✗ Unable to get list of installed Simulator runtimes.
✗ CocoaPods not installed. CocoaPods is a package manager for iOS or macOS platform code.
Without CocoaPods, plugins will not work on iOS or macOS. For more info, see https://flutter.dev/to/platform-plugins For installation instructions, see https://guides.cocoapods.org/using/getting-started.html#installation
[✓] Chrome - develop for the web
[✓] Connected device (1 available)
[✓] Network resources

위와 같은 결과 나오면 설치 완료

flutter not found 문제

.zshrc에 PATH 추가 완료 후 flutter --version 입력 시 flutter not found가 뜨는 상황이 자주 발생한다. 특히 맥 기본 터미널에서는 flutter 명령어 사용이 되는데 VS Code 내장 터미널에서 flutter 명령어를 못 찾는 상황(또는 그 반대)이 발생할 수 있다. 이는 zsh가 로그인 셸로 실행될 때는 .zprofile만 읽고, 인터랙티브 셸로 실행될 때는 .zshrc만 읽는 구조로 되어있기 때문이다.

macOS는 기본적으로 zsh 생성시 두 설정을 모두 불러오도록 처리해주지만 가끔 특정 동작 이후에 이 로직이 꼬여 다른 셸로 착각하고 .zprofile과 .zshrc 두 설정 중 하나만 읽고 끝내버리는 경우가 생긴다.

따라서 .zprofile 끝에 .zshrc를 불러오라는 "source ~/.zshrc"를 작성해두면 VS Code나 macOS가 어떤 방식으로 셸을 열든 무조건 .zshrc에 등록된 Flutter 경로를 읽을 수 있게 된다.

(.zshrc에 PATH 추가 완료 후)

open -e ~/.zprofile
echo '[[ -f ~/.zshrc ]] && source ~/.zshrc' >> ~/.zprofile
source ~/.zprofile

새 터미널 열어서 flutter --version 잘 나오는지 확인

Xcode 설치

1. 앱스토어에서 Xcode 설치

2. 설치 후 터미널에 Xcode의 기본 버전 세팅, 권한 허용, 추가 컴포넌트 설치 등을 진행하는 명령어 입력

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
sudo xcodebuild -runFirstLaunch

3. 라이선스 동의

8.7 Entire Agreement; Governing Language This Agreement constitutes the entire agreement between the parties with respect to the use of the Apple Software and Apple Services licensed hereunder and supersedes all prior understandings regarding such subject matter. Notwithstanding the foregoing, to the extent that You have entered into the Apple Developer Program License Agreement (DPLA) with Apple and are validly licensed by Apple to exercise additional rights, or to use additional features or functionality of the Apple Software or Apple Services under the DPLA, You acknowledge and agree that the DPLA shall govern Your use of such additional rights and privileges. No amendment to or modification of this Agreement will be binding unless in writing and signed by Apple. The parties hereto confirm that they have requested that this Agreement and all related documents be drafted in English. Les parties ont exigé que le présent contrat et tous les documents connexes soient rédigés en anglais.

EA1910
06/09/2025

Agreeing to the Xcode and Apple SDKs license requires admin privileges, please accept the Xcode license as the root user (e.g. 'sudo xcodebuild -license').

sudo xcodebuild -license accept

4. 설치 확인

xcodebuild -version

5. Xcode 실행 후 cmd + , 로 Settings → Components → iOS 26.2 옆에 Get 버튼을 눌러 iOS 시뮬레이터 설치

6. 터미널에서 CocoaPods 설치

CocoaPods : iOS 전용 라이브러리 관리자로 프로젝트 외부 앱 실행, 카메라 등 iOS 네이티브 코드에 접근해야 할 때 담당 라이브러리를 자동으로 다운받고 연결해주는 역할 수행

brew install cocoapods

7. 적용 확인

flutter doctor

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.41.1, on macOS 15.7.3 24G419 darwin-arm64, locale ko-KR)
[✗] Android toolchain - develop for Android devices
✗ Unable to locate Android SDK. Install Android Studio from: https://developer.android.com/studio/index.html On first launch it will assist you in installing the Android SDK components. (or visit https://flutter.dev/to/macos-android-setup for detailed instructions). If the Android SDK has been installed to a custom location, please use flutter config --android-sdk to update to that location.
[✓] Xcode - develop for iOS and macOS (Xcode 26.2)
[✓] Chrome - develop for the web
[✓] Connected device (1 available)
[✓] Network resources

위와 같은 결과 나오면 설치 완료

안드로이드 스튜디오 설치

1. 공식 웹사이트에서 안드로이드 스튜디오 설치

2. Setup Wizard에 체크되어 있는 그대로 설치 진행

3. Android Studio 실행 후 cmd + , 로 Settings → Languages & Frameworks → Android SDK → SDK Tools → Android SDK Command-line Tools (latest) 적용

4. 라이선스 동의

flutter doctor --android-licenses

이후 나오는 라이선스 끝날 때까지 y 입력

5. 적용 확인

flutter doctor

Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.41.1, on macOS 15.7.3 24G419 darwin-arm64, locale ko-KR)
[✓] Android toolchain - develop for Android devices (Android SDK version 36.1.0)
[✓] Xcode - develop for iOS and macOS (Xcode 26.2)
[✓] Connected device (2 available)
[✓] Network resources

위와 같은 결과 나오면 설치 완료

에뮬레이터 확인

1. 에뮬레이터 목록 확인

flutter emulators

2. ios 시뮬레이터 실행

시뮬레이터 : 맥의 자원을 빌려 아이폰의 소프트웨어 동작(UI, 앱 실행 등)을 비슷하게 흉내낸 실행 환경
- 하드웨어 가상화가 없어 속도가 매우 빠르고 가벼우며 실제 아이폰의 동작과 미세한 차이 존재 가능

open -a Simulator

IOS 시뮬레이터

3. Android 에뮬레이터 실행

에뮬레이터 : 맥의 자원을 빌려 안드로이드 폰의 하드웨어(CPU, 메모리 등) 전체를 소프트웨어로 구현한 환경
- 완전한 기기를 가상 환경으로 돌리는 것이므로 상당한 자원을 점유하며 실제 기기와 동일하게 동작

flutter emulators --launch Medium_Phone_API_36.1

Android 에뮬레이터

본격적인 flutter 프로젝트 세팅은 다음 시간에 알아보자.

Kafka - 이벤트 기반의 비동기 작업 처리 구조로 알림 기능 구현하기 (4)

cusum26 — Thu, 22 Jan 2026 16:46:15 +0900

도커 환경에서의 Kafka UI 설정

알림 기능이 제대로 동작하는 지 검증하기 앞서 Kafka 브로커가 설계한 대로 작동하는 지 Kafka UI를 통해 확인해보자.

Kafka UI는 Kafka 브로커에 저장된 메시지와 메타데이터를 조회해 시각적으로 표현하는 HTTP 기반의 외부 웹 UI 도구이다. 일반적으로 Docker 컨테이너로 배포되며 브라우저를 통해 Kafka 브로커의 운영 및 모니터링 환경을 제공한다. 다음의 Docker 설정을 통해 브라우저 접속 환경을 구성할 수 있다.

kafka-ui:
  image: provectuslabs/kafka-ui:latest
  container_name: kafka-ui
  ports:
    - "8085:8080"  # 호스트의 브라우저는 8085로 접속 가능
  environment:
    KAFKA_CLUSTERS_0_NAME: local
    KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS: kafka:9092
  depends_on:
    - kafka
  restart: unless-stopped

Kafka UI 접속

이제 도커에서 Kafka를 실행하고 localhost:8085로 접속하면 다음 화면을 볼 수 있다.

서비스 규모가 크지 않아 단일 브로커 구조로 설정했으므로, 현재 클러스터는 1개의 브로커와 7개의 토픽으로 구성되어 있다. approval-show-topic만 3개의 파티션을 가지고 있고, 나머지 토픽은 각각 1개의 파티션으로 설정했는데도 대시보드에 전체 파티션 수가 58개로 표시되어 다소 이상하게 보인다. 우선 토픽별로 파티션 구성을 확인해보자.

대시보드에서 확인한 7개의 토픽을 확인할 수 있다. 하위 6개는 직접 생성한 토픽이지만, 가장 위에는 생성한 적이 없는 __consumer_offsets 토픽이 존재한다. 이 토픽에 대해 알아보자.

__consumer_offsets

Kafka는 내부적으로 50개의 파티션을 사용하여 __consumer_offsets 토픽을 운영하며, 각 컨슈머 그룹의 커밋 내역과 상태 메타데이터를 기록한다.

이 토픽에 생성된 메시지를 살펴보면 {컨슈머 그룹, 토픽, 파티션}을 Key로 하는 메시지와 {컨슈머 그룹}을 Key로 하는 메시지가 있다.

전자는 오프셋 커밋 로그, 후자는 그룹 메타데이터 로그이다.

Key가 {"group", "topic", "partition"}인 오프셋 커밋 로그

Key가 {"group"}인 그룹 메타데이터 로그

offset commit log

컨슈머 그룹, 토픽, 파티션을 Key로 하는 메시지는 일전에 서버 재시작 상황에서 언급했던 컨슈머 오프셋의 커밋 로그이다. 이는 특정 파티션의 작업 진행 상태를 나타내는 체크포인트 역할을 하며 애플리케이션의 갑작스러운 종료나 재시작 상황에서 유실 없이 마지막 처리 지점부터 작업을 재개할 수 있도록 보장한다.

서버 재시작 상황에서 메모리가 날아간 컨슈머는 자신이 어디서부터 다시 읽어야 하는지에 대한 정보(=마지막으로 커밋된 오프셋=컨슈머 오프셋)를 브로커(Group Coodrinator)에게 요청한다. 컨슈머가 언제 꺼질지 모르는 Kafka 브로커는 각 컨슈머가 파티션의 어디까지 처리했는지 오프셋을 커밋할 때마다 내부 토픽에 로그로 기록해둔다. 이때 커밋 로그가 저장되는 내부 토픽이 __consumer_offsets이다.

group-A / approval-show-topic / partition-0 -> committed offset 100
group-B / approval-show-topic / partition-1 -> committed offset 98
group-C / approval-show-topic / partition-2 -> committed offset 97

컨슈머 오프셋은 개별 컨슈머 인스턴스 단위가 아니라 consumer group + topic + partition 단위로 저장된다. 따라서 재시작이나 리밸런싱으로 기존과 다른 컨슈머 인스턴스가 해당 파티션을 맡더라도, 같은 컨슈머 그룹에 속해 있다면 마지막으로 커밋된 오프셋부터 이어서 메시지를 가져올 수 있다. 즉, 커밋 로그에서 컨슈머 오프셋은 컨슈머 그룹의 파티션별 처리 위치를 의미하게 된다.

Group metadata log

__consumer_offsets 토픽에서 컨슈머 그룹만을 Key로 하는 메시지는 해당 그룹의 구성원 정보, 각 파티션 구독 상태, 파티션 할당 상태를 관리하는 그룹 메타데이터 로그이다. 컨슈머 그룹의 상태와 관련된 메타데이터를 기록하며 컨슈머 그룹의 존재 여부, 각 파티션 구독 상태, 현재 오프셋 위치, 리밸런스 발생 여부와 같은 이벤트를 상태 변경으로 간주하여 저장한다.

이 로그는 컨슈머 그룹 전체의 생명주기와 리밸런싱 현황 파악에 사용되며, 컨슈머 그룹 내 구성원 변경이나 세션 유지 상태 관리에 있어서 근거가 되는 정보이다.

commit 기록은 없지만 그룹 메타데이터 로그가 존재하는 hot-board-notice-group

따라서 메시지를 아직 소비하지 않아 커밋 기록이 없더라도, 컨슈머가 토픽을 구독하거나 그룹에 참여하는 순간 이런 상태 변경 정보는 컨슈머 그룹을 Key로 하는 메시지로 __consumer_offsets에 저장된다. 실제로 hot-board-notice-group은 아직 소비 작업을 수행한 적이 없음에도 불구하고, 리더 컨슈머 선출 및 파티션 할당이 성공적으로 완료되었다는 그룹 메타데이터 로그가 기록되어 있다. 이러한 기록들은 단순히 오프셋 추적을 넘어, 컨슈머와 브로커 간의 멤버십 유지, 파티션 재할당, 업무 재분배 등에 활용된다.

알림 기능 이벤트 전달 검증

등록 승인 알림

세 파티션에 분산 저장된 11개의 approval-show-topic 메시지

내내 예로 들었던 approval-show-topic을 살펴보자. 11개의 메시지가 파티션 3개에 골고루 저장되어 있는 것을 볼 수 있다.

3개의 컨슈머 그룹 모두 concurrency=3으로 설정되어있다. 따라서 10,000개의 이벤트가 생성되더라도, 3개의 워커 스레드가 각 파티션을 하나씩 담당하여 승인 알림, 구독 알림, 추천 알림 로직을 총 9개의 스레드에서 메인 흐름과 독립적으로 처리할 수 있다. 설령 애플리케이션이 재시작되더라도, 브로커에 커밋된 오프셋을 기준으로 중단된 위치부터 재처리가 이루어져 시스템의 내구성과 처리 안정성을 보장한다.

등록 반려 알림

3개의 메시지 밖에 없음에도 768Byte를 차지하는 reject-show-topic

매인 로직에서 반려 사유를 직접 전달하는 현재 구조

등록 반려 이벤트의 경우, 메인 로직으로부터 반려 사유를 전달받아야 하므로 최소 정보만 전달하는 다른 메시지에 비해 용량이 크다. 추후 반려 사유 탬플릿이 고정되면 ENUM으로 매핑시켜서 최소한의 파라미터만 전달하는 방안도 가능해보인다.

게시글 댓글 알림

문제없이 전달되는 댓글 이벤트와 대댓글 이벤트

댓글과 대댓글 이벤트도 잘 전달된다.

이로써 Kafka를 이용한 비동기 이벤트 처리 구조를 적용한 알림 기능이 잘 작동함을 확인했다.

사실 Kafka를 공부하면서 줄곧 느낀 점은, Kafka의 진정한 가치는 수십, 수백만 단위의 row를 처리해야하는 대규모 서비스 환경에서 비로소 드러난다는 것이다. 시스템이 available한 최대 capacity를 균일하게 유지하며 수많은 read, write 트래픽을 안정적으로 처리하고, 필요에 따라 수평 확장되는 구조에서 Kafka와 같은 이벤트 기반 통신이 없다면 어떻게 서비스를 안정적으로 설계하고 상태를 일관되게 관리할 지 잘 상상이 가지 않는다.

앞으로 MSA쪽도 공부해보며 이해를 넓히고, 실제 마이크로서비스 개발 과정에서 Kafka를 직접 적용해 보며 그 가치를 검증해 보고 싶다.

Kafka - 이벤트 기반의 비동기 작업 처리 구조로 알림 기능 구현하기 (3)

cusum26 — Thu, 22 Jan 2026 04:47:17 +0900

도커 환경에서의 Kafka 설정

Kafka의 로그 서버는 스프링 애플리케이션과 분리된 외부 브로커로 동작하며, 프로듀서와 컨슈머 클라이언트를 통해 애플리케이션과 통신한다. 따라서 일반적으로 도커 컨테이너나 별도의 서버 환경에서 운영된다. 여기서는 Kafka를 도커 컨테이너 안에서 실행하는 방식으로 설계했다.

스프링 애플리케이션은 로컬 환경에서는 IDE에서, 배포 환경에서는 도커 컨테이너 안에서 실행되므로 어느 환경에서 접속하더라도 도커 내부의 Kafka 브로커를 정확히 식별해 연결해야 한다. 이를 위해 Kafka는 도커 환경에서 포트를 2개 열어 두고, 각각에 리스너를 설정하여 두 가지 방식으로 접근하는 클라이언트와 모두 통신할 수 있도록 구성한다. 도커 내부에서는 클라이언트끼리 직접 연결 가능하므로 외부에서 접속할 포트의 매핑만 명시했다.

개발 환경 (도커 밖): 로컬 호스트에서 IDE로 실행 중인 Spring 애플리케이션은 KAFKA_BOOTSTRAP_SERVERS=localhost:29092로 접속
배포 환경 (도커 안): 도커 컨테이너에서 돌아가는 Spring 애플리케이션은 도커 내부 네트워크를 통해 KAFKA_BOOTSTRAP_SERVERS=kafka:9092로 직접 접속

다음은 도커 컨테이너에서 돌아가는 단일 브로커 Kafka 설정이다.

    kafka:
      image: confluentinc/cp-kafka:latest
      container_name: kafka
      ports:
        - "29092:29092"    # 로컬 호스트 접속 매핑용
      environment:
        # 필수 KRaft 설정
        CLUSTER_ID: "hjeeg3q1SoCw7IKoRw-rMQ"
        KAFKA_NODE_ID: 1
        KAFKA_PROCESS_ROLES: "broker,controller"  # 브로커와 컨트롤러 역할
        KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"  # 컨트롤러 통신용 주소

        # 리스너 설정 (KRafts 모드용 CONTROLLER)
        KAFKA_LISTENERS: 'PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093,PLAINTEXT_HOST://0.0.0.0:29092'
        KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092,PLAINTEXT_HOST://localhost:29092'
        KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT'
        KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'

        # Mac(ARM) 호환 설정 및 성능 최적화
        _JAVA_OPTIONS: "-XX:UseSVE=0"
        KAFKA_HEAP_OPTS: "-Xms512M -Xmx512M"   # JVM 힙 메모리
        KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
        KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
        KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
        KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      volumes:
        - kafka_data:/var/lib/kafka/data   # Docker 내부 볼륨만 사용
      restart: unless-stopped

  volumes:
    kafka_data:

앞서 언급한 ZooKeeper 기반 구조와의 차이로 인해 KRaft 모드에서는 전용 설정 항목들이 존재한다.

각 브로커는 CLUSTER_ID와 KAFKA_NODE_ID를 통해 소속 클러스터와 노드 식별자를 명시하며 PROCESS_ROLES 설정에 controller를 포함함으로써 컨트롤러 역할을 수행할 수 있게 한다.
외부 코디네이터(ZooKeeper) 없이 Raft 합의 알고리즘을 통해 활성 컨트롤러를 선출하므로, 노드 간 통신을 위한 격리된 전용 채널이 필수적이다. 이를 위해 CONTROLLER_LISTENER_NAMES에 채널 명칭을 정의하고, LISTENERS 설정에 실제 대기 포트(주로 9093)를 할당한다.
컨트롤러 채널은 브로커 간 내부 통신 전용이다. 모든 브로커는 도커 내부에서 실행되며, 도커 환경에서는 컨테이너 이름을 통해 즉시 식별 및 라우팅이 가능하다. 따라서 외부 클라이언트에게 자신의 주소를 알리는 용도인 ADVERTISED_LISTENERS에는 컨트롤러 주소를 추가할 필요는 없다
LISTENER QUORUM_VOTERS에는 클러스터 내에서 컨트롤러 투표권을 가진 노드들의 ID와 주소가 명시된다.

KRaft 모드의 Kafka는 구동 전 CLUSTER_ID 생성을 통한 스토리지 초기화 과정을 거치는데, 따로 설정해두지 않았다면 다음 오류 메시지가 뜨며 실행조차 되지 않는다.

다음은 다중 브로커 구조에서의 설정이다.

version: "3.9"
services:
  kafka1:
    image: confluentinc/cp-kafka:latest
    container_name: kafka1
    ports:
      - "29092:29092"
    environment:
      CLUSTER_ID: "hjeeg3q1SoCw7IKoRw-rMQ" # 모든 노드 동일 필수
      KAFKA_NODE_ID: 1
      KAFKA_PROCESS_ROLES: "broker,controller"	# controller 역할 추가
      KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka1:9093,2@kafka2:9093,3@kafka3:9093"
      KAFKA_LISTENERS: "PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093,PLAINTEXT_HOST://0.0.0.0:29092"
      KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka1:9092,PLAINTEXT_HOST://localhost:29092"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
      KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      KAFKA_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
    volumes:
      - kafka1_data:/var/lib/kafka/data

  kafka2:
    image: confluentinc/cp-kafka:latest
    container_name: kafka2
    ports:
      - "29093:29093"
    environment:
      CLUSTER_ID: "hjeeg3q1SoCw7IKoRw-rMQ"
      KAFKA_NODE_ID: 2
      KAFKA_PROCESS_ROLES: "broker,controller"
      KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka1:9093,2@kafka2:9093,3@kafka3:9093"
      KAFKA_LISTENERS: "PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093,PLAINTEXT_HOST://0.0.0.0:29093"
      KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka2:9092,PLAINTEXT_HOST://localhost:29093"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
      KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      KAFKA_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
    volumes:
      - kafka2_data:/var/lib/kafka/data

  kafka3:
    image: confluentinc/cp-kafka:latest
    container_name: kafka3
    ports:
      - "29094:29094"
    environment:
      CLUSTER_ID: "hjeeg3q1SoCw7IKoRw-rMQ"
      KAFKA_NODE_ID: 3
      KAFKA_PROCESS_ROLES: "broker,controller"
      KAFKA_CONTROLLER_QUORUM_VOTERS: "1@kafka1:9093,2@kafka2:9093,3@kafka3:9093"
      KAFKA_LISTENERS: "PLAINTEXT://0.0.0.0:9092,CONTROLLER://0.0.0.0:9093,PLAINTEXT_HOST://0.0.0.0:29094"
      KAFKA_ADVERTISED_LISTENERS: "PLAINTEXT://kafka3:9092,PLAINTEXT_HOST://localhost:29094"
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT,PLAINTEXT_HOST:PLAINTEXT"
      KAFKA_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
      KAFKA_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
    volumes:
      - kafka3_data:/var/lib/kafka/data

volumes:
  kafka1_data:
  kafka2_data:
  kafka3_data:

다중 브로커 구조에서 추가로 신경쓸 점은 다음과 같다.

같은 클러스터를 구성하는 브로커들은 Cluster_ID 를 통일한다.
각 브로커는 외부 클라이언트와의 통신을 위한 포트와, 내부 컨트롤러 간 합의를 위한 전용 제어 채널에 각각 독립된 LISTENER를 바인딩한다.
KAFKA_CONTROLLER_QUORUM_VOTERS 설정에는 클러스터 내 활성 컨트롤러 투표권을 가진 모든 노드의 정보를 명시한다. 예를 들어, 1@kafka1:9093은 노드 ID 1번에 해당하는 컨트롤러의 주소가 kafka1:9093임을 의미하며 노드들은 이 명부를 바탕으로 상호 연결 및 코디네이팅을 수행한다.

KRaft 모드 Kafka 클러스터 구조

Zookeeper 기반 Kafka 클러스터 구조

Kafka 클라이언트 및 인프라 구성

다음은 애플리케이션에 Kafka 도입을 위한 기본적인 클라이언트와 인프라 구성이다

@Configuration
public class KafkaConfig {

    @Value("${spring.kafka.bootstrap-servers}")
    private String bootstrapServers;

    @Value("${spring.kafka.consumer.group-id}")
    private String groupId;

    @Bean
    public ProducerFactory<String, DomainEvent> producerFactory() {
        Map<String, Object> props = new HashMap<>();
        props.put(ProducerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
        props.put(ProducerConfig.KEY_SERIALIZER_CLASS_CONFIG, StringSerializer.class);
        props.put(ProducerConfig.VALUE_SERIALIZER_CLASS_CONFIG, JsonSerializer.class);

        props.put(JsonSerializer.ADD_TYPE_INFO_HEADERS, true);

        return new DefaultKafkaProducerFactory<>(props);
    }

    @Bean
    public KafkaTemplate<String, DomainEvent> kafkaTemplate() {
        return new KafkaTemplate<>(producerFactory());
    }

    @Bean
    public ConsumerFactory<String, DomainEvent> consumerFactory() {
        JsonDeserializer<DomainEvent> deserializer = new JsonDeserializer<>(DomainEvent.class);
        deserializer.addTrustedPackages("*");		//보안상 설정 필요
        deserializer.setUseTypeMapperForKey(false);

        Map<String, Object> props = new HashMap<>();
        props.put(ConsumerConfig.BOOTSTRAP_SERVERS_CONFIG, bootstrapServers);
        props.put(ConsumerConfig.GROUP_ID_CONFIG, groupId);
        props.put(ConsumerConfig.KEY_DESERIALIZER_CLASS_CONFIG, StringDeserializer.class);
        props.put(ConsumerConfig.VALUE_DESERIALIZER_CLASS_CONFIG, JsonDeserializer.class);
        props.put(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest");

        return new DefaultKafkaConsumerFactory<>(props, new StringDeserializer(), deserializer);
    }

    // 재시도 + DLQ 설정
    @Bean
    public DefaultErrorHandler errorHandler(KafkaTemplate<String, DomainEvent> kafkaTemplate) {
        DeadLetterPublishingRecoverer recoverer =
                new DeadLetterPublishingRecoverer(kafkaTemplate,
                        (record, ex) -> new TopicPartition(record.topic() + "-dlq", record.partition()));

        // 1초 간격, 최대 3회 재시도
        FixedBackOff backOff = new FixedBackOff(1000L, 3);

        return new DefaultErrorHandler(recoverer, backOff);
    }

    @Bean
    public ConcurrentKafkaListenerContainerFactory<String, DomainEvent> kafkaListenerContainerFactory(KafkaTemplate<String, DomainEvent> kafkaTemplate) {
        ConcurrentKafkaListenerContainerFactory<String, DomainEvent> factory =
                new ConcurrentKafkaListenerContainerFactory<>();
        factory.setConsumerFactory(consumerFactory());
        factory.setConcurrency(3); // 컨슈머 병렬 처리 스레드 수
        factory.setCommonErrorHandler(errorHandler(kafkaTemplate)); //에러 발생시 처리 로직
        return factory;
    }


}

기본적으로 애플리케이션과 Kafka 브로커 간의 안정적인 메시지 송수신을 위해 ProducerFactory와 ConsumerFactory를 정의하여 각 인스턴스의 핵심 설정을 구성한다. 분산 환경에서 이벤트 객체는 네트워크를 통해 전송되어야 하므로, 데이터의 규격화와 호환성을 위해 JSON 형식의 직렬화 및 역직렬화 과정을 거친다. Kafka 클라이언트의 기본 설정을 주입받고 문자열 Key와 JSON 형식 Value를 처리하는 Serializer/Deserializer를 명시적으로 설정하였다.

Producer가 발행하고, Consumer가 소비할 이벤트 객체를 담는 KafkaTemplate은 ProducerFactory를 인자로 받는다. Kafka에서 메시지는 일단 Producer가 생성하면 구독한 Consumer가 알아서 받아가는 구조이므로 메시지에게 Consumer 정보는 필요없다.

이전에 언급했듯이 Kafka는 시스템 장애 발생 시 애플리케이션이 자체적인 복구 메커니즘을 구현할 수 있는 환경을 제공하는데 DefaultErrorHandler로 이를 구현할 수 있다. 처리에 실패한 데이터를 유실하지 않고 별도의 토픽으로 분리하여 DLQ(Dead Letter Queue)라는 곳에 저장함으로써 장애 원인 분석 및 사후 재처리를 위한 물리적 환경을 제공한다. 이를 활용해 애플리케이션은 일부 이벤트 처리 실패가 전체 이벤트 흐름을 중단시키지 않도록 하는 부분 실패 허용 메커니즘을 구현할 수 있다.

재시도 메커니즘 (FixedBackOff): 일시적인 네트워크 장애나 일시적 오류 시 1초 간격으로 3번 재시도하도록 한 재처리 로직
DLQ (Dead Letter Queue): 3번의 재시도 후에도 실패한 작업은 원본토픽-dlq라는 별도의 스토리지로 격리, 일시적이지 않은 장애나 서버 재시작에 상황에 대응하여 완료하지 못한 작업을 기억

ConcurrentKafkaListenerContainerFactory는 KafkaListener의 실행 환경을 구성하는 핵심 설정이다. 컨슈머 그룹 내에서 파티션의 병렬 처리 수준을 설정하고, 메시지 전달 및 복구 매커니즘을 제어함으로써 Kafka 컨슈머의 생명주기를 오케스트레이션한다.

concurrency를 3으로 설정하면 리스너 내에서 브로커와 통신하는 전용 컨슈머 워커 스레드 3개가 할당된다. 이 스레드는 각자 전용 파티션을 담당해서 폴링(Polling)을 수행하며 파티션 단위 병렬 처리를 가능하게 한다. 이 설정을 주입받은 컨슈머 그룹 수 X concurrency 값 만큼의 스레드 자원이 할당되므로 서버의 자원을 고려하여 설정해야한다. 특히 토픽의 파티션 개수보다 큰 값을 설정하는 경우 항상 유휴 상태인 스레드가 생기므로 주의해야한다.

기본적으로 이 설정은 Kafka 전용 이벤트의 추상화인 DomainEvent 인터페이스를 기준으로 공통 적용되도록 햇다. 애플리케이션에서 상황에 따라 발행되는 실제 이벤트 객체는 모두 DomainEvent를 상속받아 각 도메인별 비즈니스 로직에 맞게 확장되도록 설계했다.

Kafka를 적용한 이벤트 처리 구조

공연 도메인 서비스의 등록 승인 메서드

이제 Kafka를 도입함으로써, 기존 예시의 등록 승인 흐름에서 세 종류의 알림 생성이 어떻게 처리되는지 살펴보자.

    @Transactional
    public AdminAmateurShowSummaryResponseDTO approveShow(Long showId) {
        
        AmateurShow show = amateurShowRepository.findById(showId)
                .orElseThrow(() -> new GeneralException(ErrorStatus.AMATEURSHOW_NOT_FOUND));

        show.approve();

        Member performer  = show.getMember();

        // 승인 트랜잭션 커밋에 대해 이벤트 발행
        eventPublisher.publishEvent(
                new ApproveCommitEvent(show.getId(), performer.getId()
                )
        );

        return AdminAmateurShowSummaryResponseDTO.from(show);
    }

먼저 도메인 로직상 순서 보장을 위해 @TransactionalEventListener의 phase=AFTER_COMMIT을 이용한다. approveShow()는 먼저 커밋에 대한 Spring 이벤트인 ApproveCommitEvent를 발행해서 알림 생성 로직이 승인 트랜잭션 커밋 이후에 호출되도록 한다.

도메인 이벤트 리스너

@Service
@RequiredArgsConstructor
public class ApproveCommitEventListener {
    private final ApprovalShowProducer approvalShowProducer;

    @Async
    @TransactionalEventListener (phase = TransactionPhase.AFTER_COMMIT)
    public void onApproveCommit(ApproveCommitEvent event) {

        //APPROVED 수정 트랜잭션 커밋 이벤트 감지 후 kafka 이벤트 발송
        try {
            approvalShowProducer.publish(
                    new ApprovalShowEvent(event.amateurShowId(), event.performerId())
            );
        } catch (Exception e) {
            throw new IllegalStateException(
                    "승인 이벤트 Kafka 발행 실패",
                    e
            );
        }
    }
}

AFTER_COMMIT 설정으로 승인 트랜잭션 후에 호출된 onApproveCommit 리스너는 Kafka 전용 이벤트 ApprovalShowEvent를 생성해서 approvalShowProducer.publish()를 호출한다.

이때 Kafka 프로듀서의 publish 메서드는 내부적으로 KafkaTemplate.send()를 호출하는데 이는 별도의 자원을 사용해 외부 브로커와의 통신을 수반하는 작업이다. 일반적으로 이런 외부 연동 로직은 핵심 도메인 흐름과 격리하기 위해 @Async를 적용하여 비동기로 처리한다.

Kafka 이벤트

public record ApprovalShowEvent(
        Long amateurShowId,
        Long performerId
) implements DomainEvent {

    @Override
    public DomainEventType getEventType() {
        return DomainEventType.SHOW_APPROVED;
    }
}

ApprovalShowEvent는 앞서 설계한 Kafka 전용 이벤트 DomainEvent의 구현체이다.

Kafka 프로듀서

ApprovalShowEvent를 Kafka 브로커에게 전송하는 프로듀서 클라이언트인 approvalShowProducer는 다음과 같다.

@Component
@RequiredArgsConstructor
public class ApprovalShowProducer {

    private final KafkaTemplate<String, DomainEvent> kafkaTemplate;
    private static final String TOPIC = "approval-show-topic";

    public void publish(ApprovalShowEvent event) {
        if (event == null) return;

        // amateurShowId로 파티션
        kafkaTemplate.send(TOPIC, event.amateurShowId().toString(), event);
    }

}

KafkaTemplate에 ApprovalShowEvent를 담아 approval-show-topic을 토픽을 붙여 브로커에게 전송한다. 이때 파티션 결정에 쓰일 key로 amateurShowId를 보내는데, 이는 Kafka 서버에서 파티셔닝을 위한 해시 계산에 사용되기 때문에 String으로 변환하여 전달한다. 이 메시지를 받은 Kafka 브로커는 ApprovalShowEvent를 Topic에 맞게 분류하고 전달받은 amateurShowId로 저장될 파티션을 결정한다.

Kafka 메시지 토픽 설정

@Configuration
public class KafkaTopicConfig {

    @Bean
    public NewTopic approvalShowTopic() {
        return TopicBuilder.name("approval-show-topic")
                .partitions(3)
                .replicas(3)	//브로커 수보다 클 수 없음
                .build();
    }
}

Kafka 서버가 3개의 브로커 구조라고 가정하자. 위의 설정에 따라 approval-show-topic은 3개의 파티션과 3개의 replica로 구성된다. 예를 들어 amateuerShowId가 34, 15, 60인 이벤트가 연속적으로 들어왔다고 하면 브로커별 approval-show-topic의 구조는 다음과 같다.

id=34인 이벤트 전송 시

id=15인 이벤트 전송 시

id=60인 이벤트 전송 시

Kafka 컨슈머

이제 이렇게 Kafka 브로커에 저장된 이벤트를 컨슈머가 어떻게 소비하는지 알아보자.

@Component
@RequiredArgsConstructor
public class ApprovalConsumerForSubscribers {

    private final NoticeService noticeService;

    @KafkaListener(
            topics = "approval-show-topic",
            groupId = "subscriber-group",
            containerFactory = "kafkaListenerContainerFactory"
    )

    @Transactional
    public void consume(ApprovalShowEvent event) {
        if (event == null) return;

        noticeService.notifySubscribers(event);

    }
}

@Component
@RequiredArgsConstructor
public class ApprovalConsumerForPerformer {

    private final NoticeService noticeService;

    @KafkaListener(
            topics = "approval-show-topic",
            groupId = "approved-group",
            containerFactory = "kafkaListenerContainerFactory"
    )

    @Transactional
    public void consume(ApprovalShowEvent event) {
        if (event == null) return;

        noticeService.notifyPerformer(event);

    }
}

@Component
@RequiredArgsConstructor
public class ApprovalConsumerForRecommendation {

    private final NoticeService noticeService;

    @KafkaListener(
            topics = "approval-show-topic",
            groupId = "recommended-group",
            containerFactory = "kafkaListenerContainerFactory"
    )
    @Transactional
    public void consume(ApprovalShowEvent event) {
        if (event == null) return;

        noticeService.notifyOthers(event);
    }
}

@KafkaListener로 approval-show-topic 토픽을 구독하면 브로커로부터 해당 토픽의 메시지를 받아올 수 있다. groupId로 묶인 컨슈머 그룹은 물리적으로 분리된 환경에서도 일관성이 보장된 데이터를 제공받아 병렬 처리가 가능하다. Kafka는 동일 그룹 내의 컨슈머들에게 파티션을 중복 없이 배분하여 처리량을 수평적으로 확장함과 동시에 각 파티션에는 할당된 담당 컨슈머만 접근하도록 제어함으로써 파티션 단위의 순차 처리를 보장한다.

Kafka 적용 비동기 이벤트 처리 구조에서 approveShow의 스레드별 실행 흐름

위는 amateurShowId=8인 공연의 등록을 승인함으로써 프로듀서가 approval-show-topic 메시지를 발행하고, 이 토픽을 구독한 세 컨슈머 그룹이 받아 각자 스레드에서 후속 작업을 비동기로 처리하는 상황이다. T2, T3, T4 스레드를 할당받은 컨슈머 그룹은 각각 구독자 알림, 등록자 알림, 추천 알림 생성을 수행한다.

Kafka 적용 비동기 이벤트 처리 구조에서 approveShow후 rejectShow의 스레드별 실행 흐름

위는 amateurShowId=23인 공연의 등록을 승인하고, amateurShowId=26인 공연의 등록을 반려한 상황이다. 프로듀서가 approval-show-topic 메시지를 발행해서 Broker 1에게 전송하자마자 구독 중인 컨슈머는 이를 가져와 세 종류의 알림 생성을 비동기로 처리한다.

메인 애플리케이션은 곧바로 reject-show-topic을 발행해서 Broker 2에게 전송하고, rejected-group의 컨슈머는 브로커로부터 이를 받아와 T5 스레드에서 등록 반려에 따른 후속 작업을 처리한다. T2, T4 스레드에서는 등록 승인에 따른 후속 작업이 실행 중인 와중에 T5에서는 등록 거부의 후속 작업이 독립적으로 실행되며 높은 처리량을 확보한다.

Kafka를 매개체로 활용하는 것만으로도 비동기 처리를 구현하고, 프로듀서와 컨슈머의 생명주기를 격리할 수 있다.

Producer-Message-Consumer 구조는 스프링 컨텍스트 내부에서 관리되던 객체를 직접 소비하는 방식이 아니라, 외부 브로커를 통해 유입된 데이터를 독립적으로 처리하는 구조이다. 따라서 클라이언트 설정에서 KafkaListenerContainerFactory는 JVM으로부터 각 컨슈머 그룹이 고유한 워커 스레드를 물리적으로 할당받도록 한다. @KafkaListener로 이 설정을 주입받은 각 컨슈머는 각자의 스레드를 할당받고 애플리케이션의 메인 흐름과 분리되어 실행된다.

따라서 같은 JVM 안에 있더라도 프로듀서와 컨슈머는 서로 다른 스레드에서 동작하며, 컨슈머는 프로듀서가 아닌 Kafka 브로커로부터 전달된 메시지를 비동기적으로 처리한다. 이로 인해 애플리케이션 재시작 상황에서도 유실 걱정 없이 안정적 재처리를 보장할 수 있다.

이 구조는 동일한 애플리케이션 내에 구현되어 있더라도 호출자와 피호출자의 생명주기를 논리적으로 격리한 효과를 내어 향후 물리적으로 격리되는 MSA 구조에서도 바로 적용 가능한 유연한 설계가 된다. 내구성 뿐만 아니라, 하드웨어의 추가만으로 무한한 처리량 증가를 보장하므로 앞서 정의한 5가지 문제(응답 지연 문제, 순서 문제, 롤백 전파 문제, 처리량 문제, 내구성 문제)를 모두 해결한다.

Kafka가 적용된 비동기 처리 구조의 가치

단일 애플리케이션

Kafka의 진정한 가치는 분산 애플리케이션에서 마이크로서비스의 병렬 처리에서 드러나지만 단일 애플리케이션이라고 그 체감이 아예 없진 않다. 특히 fan-out 작업과 같은 대규모 처리 상황에서 높은 안정성을 유지한다.

시스템 내 모든 공연의 등록을 취소하는 메서드가 있다고 가정하자. 이 메서드를 수행하면 DB에 저장된 모든 공연의 등록 상태 column이 REJECTED로 변경되며 이에 따른 후속 작업은 rejected-show-topic을 구독한 KafkaListener에 의해 수행된다. 시스탬에 10000개의 공연이 등록된 상태라고 하자.

Kafka 적용 비동기 이벤트 처리 구조의 10000개 이벤트 처리 동작

위와 같이 3개의 replica와 partition으로 설정된 rejected-show-topic과 concurrency=3으로 설정된 리스너 환경에서 메인 서비스는 비동기적으로 처리되므로 10000번째 이벤트 발행 즉시 응답을 반환할 수 있다. 이 메시지를 구독한 rejected-group의 3개의 워커 스레드들은 할당받은 파티션을 기반으로 리더 브로커를 폴링(polling)하며 메시지를 소비한다.

생성된 10000개의 이벤트들은 key에 따라 각 파티션에 균일하게(약 3333개씩) 분산 저장되며 컨슈머는 설정된 배치 단위(max.poll.records)만큼 퍼와서 각자 스레드에서 처리한다. 이때 각 워커 스레드는 자신에게 할당된 파티션의 메시지만을 순차적으로 처리하며, 이러한 구조를 통해 제한된 자원 내에서도 안정적인 병렬 처리가 가능하다.

Kafka 적용 vs 미적용

Kafka 구조에서는 메시지가 토픽과 파티션을 통해 디스크 기반으로 분산 저장되며 컨슈머는 자신의 처리 가능한 속도에 맞춰 메시지를 소비한다. 이로 인해 자연스럽게 안정적인 backpressure가 보장된다.

backpressure : 시스템의 처리 속도를 초과하는 입력을 제어함으로써 전체 시스템의 안정성을 유지하는 메커니즘

Kafka는 Producer의 전송 속도가 Consumer의 처리 속도를 초과하더라도 밀린 메시지를 디스크 기반 로그에 저장하여 안정적으로 버퍼링한다. 또한 Consumer가 처리 가능한 양만큼 데이터를 가져오는 pull 방식으로 동작하기 때문에 시스템 전체의 처리 속도는 자연스럽게 Consumer의 처리 능력에 맞춰진다. 이와 같은 구조를 통해 Kafka는 유입 속도와 처리 속도간 불일치를 효과적으로 흡수하며 안정적인 backpressure를 제공하는 버퍼 역할을 수행한다.

반면 Spring이 제공하는 @Async 기반 이벤트 처리 구조는 스레드 풀과 메모리 큐를 기반으로 동작하며 동시에 실행 가능한 작업 수는 스레드 풀의 크기로 제한된다. 스레드 수를 초과한 작업은 JVM 힙 메모리 상의 큐에 적재되며 작업의 유입 속도가 처리 속도를 초과할 경우 큐에 작업이 지속적으로 누적된다.

이 과정에서 큐의 크기가 제한되어 있지 않거나 과도하게 크다면 메모리 사용량이 점점 증가하게 되고 결국 힙 메모리가 고갈되면서 OutOfMemoryError(OOM)에 의해 프로그램이 다운될 수 있다. 반대로 큐의 크기가 제한된 경우에는 이를 초과한 작업이 거부되거나 손실될 수 있어 안정적인 처리가 어려워진다.

또한 메모리 사용량이 증가하는 상황에서는 이를 회수하기 위한 GC(Garbage Collection)가 빈번하게 수행되고 이 과정에서 Stop-The-World(STW)가 발생하여 애플리케이션의 응답 지연이 나타난다. 이러한 현상이 반복되면 전체 시스템의 처리량이 급격히 저하되고 서비스 중단으로 이어질 수 있다.

결과적으로 @Async 기반 구조는 작업이 메모리에 의존하여 누적되기 때문에 대규모 fan-out과 같이 순간적으로 많은 이벤트가 발생하는 상황에서 안정적인 부하 제어가 어렵고 Kafka와 같은 메시지 큐 기반 구조에 비해 확장성과 안정성이 떨어진다.

분산 애플리케이션

Kafka의 진가가 가장 잘 드러나는 건 MSA 구조에서이다. 여러 개의 마이크로서비스들이 Kafka 브로커를 통해 정보를 전달하고 각자의 작업을 유기적으로 수행한다.

이와 같은 예시 상황을 가정해보자.

다음은 커뮤니티 기능과 관련있는 3개의 마이크로서비스를 운영하는 분산 애플리케이션 환경이다.

먼저 Community 마이크로서비스는 게시글, 댓글, 대댓글을 관리하는 핵심적인 커뮤니티 도메인 기능을 담당한다. 새로운 댓글이 생성되면 comment-created-topic 메시지를 브로커에 전송한다.

Patrol 마이크로서비스는 커뮤니티의 건전성을 위해 악의적인 내용이 있는지 AI를 이용하여 주기적으로 모니터링한다. Community 마이크로서비스에서 발행한 모든 토픽을 구독하는 community-check-group 리스너를 운영한다. 만약 악성 댓글이 감지된다면 해당 댓글을 삭제하고 malicious-comment-topic 메시지를 브로커에 전송한다.

User Report 마이크로서비스는 사용자 행동 데이터를 수집하여 이상 행동 감지 및 통계 지표를 제공한다. 이상 행동이나 악의적인 행동을 한 유저는 블랙리스트에 기록해둔다. malicious가 붙은 모든 토픽을 구독하는 malicious-event-group 리스너를 운영한다.

분산 애플리케이션에서 커뮤니티 기능을 담당하는 마이크로서비스(community-check-group의 concurrency=1)

분산 애플리케이션에서 커뮤니티 기능을 담당하는 마이크로서비스(community-check-group의 concurrency=3)

위의 그림은 악성 댓글 2개를 작성했을 때 각 마이크로서비스가 어떻게 작동하는지를 나타낸 그림으로 community-check-group의 concurrency 설정이 각각 1, 3인 경우이다.

먼저 Community 마이크로서비스에서 2개의 댓글 생성에 대한 이벤트를 생성해서 Broker 1,2로 각각 전송했다.

Patrol 마이크로서비스의 community-check-group 리스너가 Broker 1로부터 첫번째 댓글에 대한 메시지를 받아와 내용을 검사하는 checkMalicious를 실행한다. 이에 악성 내용을 감지하고 삭제한 후 malicious-comment-topic 메시지를 Broker 2에 전송한다.

이후 리스너가 Broker 2로부터 받아온 두번째 댓글에 대해서도 checkMalicious를 실행한다. 두번째 댓글에서도 악성 내용을 감지하고 삭제 후 malicious-comment-topic 메시지를 Broker 2에 전송한다.(concurrency = 1 일때 동기, 3일때 비동기 처리)

User Report 마이크로서비스의 malicious-event-group 리스너는 Broker 2에서 malicious-comment-topic 메시지를 받아와 댓글 작성자를 블랙리스트에 올리는 blackList 메서드를 실행한다.

서버 장애로 인한 재시작 상황

서버 장애로 인한 재시작 상황(community-check- group의 concurrency=3)

Patrol 마이크로서비스가 첫번째 댓글에 대한 메시지 처리 후 두번째 댓글 이벤트에 대한 checkMalicious 실행 중 다운됐다고 하자.

Patrol 마이크로서비스가 중단된 작업을 재개하는 과정은 다음과 같다.(concurrency=3)

서버 재시작 후, community-check-group 리스너의 워커 스레드(T1, T2, T3)는 그룹 코디네이터 역할을 수행하는 브로커에게 comment-created-topic과 각자 담당 파티션을 보내며 커밋 오프셋(해당 파티션에서 다음 순서로 처리해야 할 오프셋)을 물어본다. (T1은 parition 2, T2는 partition 1, T3는 partition 0 담당)
커밋 오프셋이 변한 과정은 다음과 같다.(partition 0, partition 1, parition 2), LEO(Log End Offset)
1. 첫번째 댓글 이벤트 생성, 처리 전: (3, 1, 2), LEO=(3, 1, 3)
2. 첫번째 댓글 이벤트 처리 후 커밋: (3, 1, 3), LEO=(3, 1, 3)
3. 두번째 댓글 이벤트 생성, 처리 전: (3, 1, 3), LEO=(3, 2, 3)
4. 두번째 댓글 이벤트 처리 중 서버 재시작: (3, 1, 3), LEO=(3, 2, 3)
그룹 코디네이터 역할을 수행하는 브로커는 내부적으로 운영하는 컨슈머 오프셋 로그를 참조하여 각 워커 스레드에게 (담당 파티션, 커밋 오프셋, 리더 브로커 주소) 형식의 응답을 보낸다. 응답을 받은 각 워커 스레드는 자신이 담당하는 파티션의 리더 브로커에게 커밋 오프셋에 해당하는 메시지의 fetch 요청을 한다.(T1은 3, T2는 1, T3는 3 요청)
- T1은 Broker 1에게 partition 2의 #3에 해당하는 메시지를 요청
- T2는 Broker 2에게 partition 1의 #1에 해당하는 메시지를 요청
- T3는 Broker 1에게 partition 0의 #3에 해당하는 메시지를 요청
각 브로커는 요청받은 오프셋의 메시지가 존재하면 바로 전송, 없으면 최대한 늦게 응답

데이터가 없을 때마다 "없음"이라고 즉시 응답할 경우 컨슈머는 바로 "지금은?"이라고 물어보는 무의미한 폴링이 발생하며 네트워크 자원이 낭비

Broker 1은 T1로부터 요청받은 partition 2의 #3인 메시지가 없음(0, 1, 2까지만 존재) -> 지연 응답
Broker 2는 T2로부터 요청받은 partition 1의 #1인 메시지가 존재(0, 1 존재) -> 즉시 응답
Broker 1은 T3로부터 요청받은 partition 0의 #3인 메시지가 없음(0, 1, 2까지만 존재) -> 지연 응답

5. 서버 재시작 후 T2는 Broker 2로부터 partition 1의 #1인 메시지를 전달받고 두번째 댓글 이벤트에 대해 checkMalicious를 호출하여 중단된 작업을 안전하게 재처리하게 된다.

서버 재시작 상황에서 comment-created-topic의 파티션 상태

Kafka의 메시지 시스템은 기존 단일 애플리케이션에서 인메모리로 처리되던 서비스 간 데이터 전송과 메서드 호출 구조를 JVM 바깥으로 옮겨, MSA 환경에서 수평적 확장과 마이크로서비스 간 통신을 내구성 있게 보장한다.

Kafka를 적용한 이벤트 기반 비동기 작업 처리 구조로 구현한 알림 기능이 제대로 동작하는지는 다음 시간에 검증해보자.