Posts on 엔지니어 생존기록

분산 시스템 설계(3) - 액터 모델(2): 상태는 누가 어떻게 관리하나?

Sat, 03 Oct 2026 08:01:33 +0900

모든 어플리케이션은 종류를 막론하고 결국은 상태를 어떻게 관리하나?라는 하나의 질문을 해결합니다. 쇼핑 앱에 로그인해서 주문을 하기 위해서는 회원, 상품, 주문 상태를 관리해야 합니다. 실시간 온라인 게임에서는 각 플레이어의 캐릭터 HP/MP, 스킬 등의 상태와 NPC 들의 상태를 관리하면서 각 플레이어, NPC간의 상호작용을 상태에 실시간으로 반영해야 하죠. 그러니까 좀 단순화해서 말하자면, 개발자가 작성하는 코드는 대부분이 이 상태를 어떻게 안전하면서도 효율적으로 처리할거냐 하는 문제가 됩니다.

그렇기 때문에 이 문제는 역사적으로도 매우 중요한 문제였고, 하드웨어와 네트워크의 발전으로 인해 상태를 관리하기 위한 방법도 많은 변화가 있었습니다.

액터 모델은 병렬성을 달성하기 위한 방법으로 1973년에 이미 제시되었지만, 한동안 빛을 보지는 못했고, 2010년대 들어서야 다시 세상의 주목을 받게 되었죠. 이 글에서는 상태를 다루기 위해 분투했던 지난 날의 역사를 좀 돌아보고자 합니다.(제가 궁금해서 그렇습니다. 하하하…)

객체의 탄생(1960~1970): 상태는 객체 안에 존재한다!

최초의 OOP 언어: Simula 67

객체라는 개념이 현실에 구현된 건 1967년으로 보는 게 적절해 보입니다. 1967년에 Ole-Johan Dahl과 Kristen Nygaard가 Simula 67이라는 언어를 발표하는데요, 우리에게 익숙한 객체, 클래스, 상속 등의 개념과 함께 가상(virtual) 프로시저, coroutine(코드 실행을 정지하고 다시 실행할 수 있는 개념) 등을 제시했습니다.

wikipedia에서 발췌한 Simula 67의 예제 코드를 볼까요?

Begin
 Class Glyph;
 Virtual: Procedure print Is Procedure print;;
 Begin
 End;

 Glyph Class Char (c);
 Character c;
 Begin
 Procedure print;
 OutChar(c);
 End;

 Glyph Class Line (elements);
 Ref (Glyph) Array elements;
 Begin
 Procedure print;
 Begin
 Integer i;
 For i:= 1 Step 1 Until UpperBound (elements, 1) Do
 elements (i).print;
 OutImage;
 End;
 End;

 Ref (Glyph) rg;
 Ref (Glyph) Array rgs (1 : 4);

 ! Main program;
 rgs (1):- New Char ('A');
 rgs (2):- New Char ('b');
 rgs (3):- New Char ('b');
 rgs (4):- New Char ('a');
 rg:- New Line (rgs);
 rg.print;
End;

부모 클래스 Glyph가 있고, Glyph에는 가상 프로시저(가상 메서드) print가 선언되어 있습니다. 그리고 자식 클래스 Char, Line이 선언되어 있고, 각각 print함수를 구현하고 있습니다. 메인 프로그램 코드가 실행되면서 화면에 Abba가 출력되겠죠.

프로세스를 번갈아 실행하기 위해서 coroutine을 제공했지만, 두 프로세스가 동시에 한 객체를 접근하는 경우는 언어의 설계상 존재할 수 없었습니다.

액터 모델에 영감을 주다: Smalltalk

1970년대, Xerox PARC 연구소의 Alan Kay는 Simula에서 영감을 받아 순수 OOP 언어인 Smalltalk를 만들었고(최초의 Smalltalk-71은 1971년에 고안되었습니다.), Object Oriented라는 말을 최초로 사용했습니다. Smalltalk를 순수 OOP 언어로 부르는 이유는, 원시(primitive) 타입이 존재하지 않기 때문입니다. 정수나 부울 등의 모든 값들이 객체이며, 정수간의 계산도 객체 간의 메세지를 전달하여 처리됩니다.

그러니까 이렇게 간단해 보이는 덧셈이,

3 + 4

수신자 객체 3에게 메세지 +와 매개변수 4를 전달해서 결과를 얻는다고 하네요… 지금와서 보면 이렇게 까지 순수할 필요가 있었을까 싶긴합니다만, 어쨌거나 모든 객체가 서로 메세지를 주고 받는다는 이 아이디어는 이후 액터 모델에 영향을 주게 됩니다.

In November, I presented these ideas and a demonstration of the interpretation scheme to the MIT AI lab. This eventuall led to Carl Hewitt's more formal "Actor" approach [Hewitt 73]. In the first Actor paper the resemblence to Smalltalk is at its closest. The paths later diverged, partly because we were much more interested in making things than theorizing, and partly because we had something no one else had: Chuck Thacker’s Interim Dynabook (later known as the “ALTO”).

하지만 Alan Kay는 그 당시에 이론보다는 Dynabook 이라고 하는 어린이 학습용 기기를 만드는 데 훨씬 관심이 있었기 때문에, 액터 모델을 계속 연구하지는 않았다고 합니다. 참고로 그 당시에 구상하던 Dynabook의 모습이라는데요, 참 시대를 앞서 나간 거 같습니다!

By Kay, A.C. - "A personal computer for children of all ages" - paper presented at the ACM National Conference, Boston, Fair use, https://en.wikipedia.org/w/index.php?curid=19820380

Smalltalk는 객체를 메세지로만 소통하는 독립 단위로 보는 관점을 제시했지만, 이후 OOP는 정적 타입과 가상 함수 테이블을 제시했던 Simula의 방식이 주류로 자리잡게 됩니다.

액터 모델의 태동(1973)

앞서 살펴봤듯이 액터 모델의 이론은 1973년에 Carl Hewitt 등이 발표한 A Universal Modular ACTOR Formalism for Artificial Intelligence을 통해 제안되었습니다. 액터 모델을 제안한 이유는 당시 하드웨어가 발전함에 따라 물리적인 프로세서를 여러 개 병렬로 실행하는 아이디어를 생각하기 시작하던 때였는데요, 액터 모델이 거기에 적합하다는 거 였습니다.

Current developments in hardware technology are making it economically attractive to run many physical processors in parallel. This leads to a “swarm of bees” style of programming. The actor formalism provides a coherent method for organizing and controlling all these processors. One way to build an ACTOR machine is to put each actor on a chip and build a decoding network so that each actor chip can address all the others. In certain applications parallel processing can greatly speed up the processing. For example with sufficient parallelism, garbage collection can be done in a time which is proportional to the logarithm of the storage collected instead of a time proportional to the amount of storage collected which is the best that a serial processor can do. Also the architecture looks very promising for parallel processing in the lower levels of computer audio and visual processing.

그러니까 칩 하나에 액터 하나를 심어서 그걸 네트워크로 연결하면 액터가 서로를 찾을 수 있다, 그러면 특정한 상황에서 순차 프로세싱 보다 병렬 프로세싱은 매우 빨라질거다 뭐 그런 이야기 입니다. 액터가 뭐길래 칩 하나에 액터 하나를 심는다는 걸까요? 액터 모델에서 이야기하는 액터는 3가지 작업을 수행할 수 있었습니다.

다른 액터에게 메세지를 보낸다.
새 액터를 만든다.
다음 메세지를 받았을 때 어떻게 행동할지 결정한다.

3번 작업은 곧 액터 자신의 상태를 변경한다는 말인데요, 직접 다른 액터의 상태를 읽거나 변경할 방법은 없으며 메세지를 통해서 작업을 하도록 부탁해야 합니다. 즉, 독자적으로 행동하면서 서로 메세지를 주고 받는 액터를 칩하나에 심어서 병렬 처리를 하자 뭐 그런 이야기였던 셈이죠.

왜 이런 구상을 했는지 당시 상황을 좀 살펴보면 인텔 4004(1971), 8008(1972)등 CPU가 칩 하나로 만들어 지고 있었고, 반도체 칩에 집적되는 트랜지스터의 수가 약 2년마다 두 배로 증가한다(1965년 당시 최초 발언에서는 1년마다 였지만, 1975년 2년마다로 수정)는 무어의 법칙도 맞아가던 시절이었습니다. 그러니까 프로세서가 이제 찍어낼 수 있는 부품의 개념으로 바뀌고 있었고, 실제로 ILLIAC IV(1972)등 여러 병렬 컴퓨터가 만들어 지고 있었습니다.(이후 1975년에 이르러서 제대로 동작했다고 합니다.)

ILLIAC IV의 모습. By Steve Jurvetson from Menlo Park, USA - Flickr, CC BY 2.0, https://commons.wikimedia.org/w/index.php?curid=755549

게다가 현대 인터넷의 시초인 ARPANET이 1969년 구축되어 독립된 노드들이 메세지를 주고받는 통신 모델이 현실화 되었고, Smalltalk가 객체 간의 메세지 통신이 실제로 동작한다는 아이디어를 제공했습니다.

그리고 이후 액터 모델을 실제로 만들려는 시도가 있었습니다.(MIT의 Act 1, Act 2나 일본에서 개발된 ABCL 등) 하지만 연구실 밖에서는 전혀 주목받지 못했고, 액터 모델이 제대로 구현될 수 있다는 걸 세상에 알린 건 Erlang 이었습니다.

Erlang

Erlang은 에릭슨의 전화 교환기의 소프트웨어를 개선하기 위해 Joe Armstrong 등이 설계했습니다. 수많은 동시성 처리와 여러 컴퓨터에 걸친 분산 처리, 수년간 무중단 운영이 가능해야 하며, 하드웨어 및 소프트웨어 오류에 대한 내결함성(fault tolerance)을 가져야 했습니다. 1986년에 개발을 시작한 뒤 Prolog 인터프리터에서 C기반의 VM 환경으로 개선(1992)하는 등의 많은 노력 끝에 실제 개발에 투입될 수 있었고, 1998년에 출시된 AXD301 스위치는 100만 라인이 넘는 Erlang으로 작성되었고 9-nines의 가용성을 달성했다고 알려져 있습니다.

하지만 통신 업계를 제외하면 Erlang은 무명에 가까웠고, 주류는 Erlang과는 다른 길로 발전해갔습니다.

사실 Erlang은 액터 모델에서 영향을 받았다기 보다는, 문제를 해결하려고 노력한 결과 액터 모델의 형태를 갖추게 되었습니다. Joe Armstrong은 자신이 액터 모델을 전혀 몰랐다고 말하기도 했는데요, 어쨌거나 결과적으로는 액터 모델이 잘 동작한다는 걸 증명했습니다.

OOP 전성시대(1980~1990년대)

Bjarne Stroustrup은 1979년, Simula 67의 클래스 개념을 C에 얹은 C with Classes 작업을 시작했습니다. C의 속도와 이식성을 잃지 않으면서도 클래스, 상속, 가상 함수, 함수 오버로딩 등을 추가하려고 했던 거죠. 그리고 1983년에 이름을 C++로 바꾸고 1985년에 첫 번째 상용 컴파일러 Cfront가 출시 됩니다.

이후 90년대에 이르러 C++의 대중화, Delphi, Java 등의 OOP 언어 들이 잇따라 출시되고 전성시대를 이루게 됩니다.

주류 OOP 언어의 객체는 메세지로만 소통하는 독립 단위가 아닌 메모리위의 구조체 + 가상 함수 테이블로 구현되었고, 각각의 객체가 자신의 정보를 은닉하고 외부에 공개한 메서드로만 자신의 상태를 변경할 수 있도록 했습니다. 이런 방식은 처음에는 문제가 없어보였지만 멀티 스레드 상황에서는 스레드 간에 객체의 상태가 가변적으로 공유되는 문제가 있었습니다. 서로 다른 스레드가 동일한 객체의 메서드를 호출할 때, 메모리에서 읽고 쓰는 과정이 겹치면 객체의 상태가 오염되었던 거죠.

물론 훨씬 더 오래 전에 이런 문제를 이미 고민한 사람들이 있었는데요, 모니터를 통해 동시성 문제를 해결하고자 했습니다. 모니터는 mutex(mutual exclusion 또는 lock)와 조건 변수(~까지 기다려 같은 조건 설정)를 통해 접근권을 가지지 못한 스레드가 공유 객체의 상태 값에 접근하지 못하도록 막아줍니다.

sequenceDiagram
participant T1 as 스레드 1
participant T2 as 스레드 2
participant O as 객체
T1->>O: lock 획득, deposit(100) 호출
T2->>O: lock 대기
O-->>T1: 상태값 갱신, lock 해제
T2->>O: lock 획득, withdraw(50) 호출
O-->>T2: 상태값 갱신, lock 해제

위 예제에서 락이 두 스레드의 동시 접근을 순차적으로 정렬하고, 스레드2는 스레드1이 락을 해제할 때 까지 대기 하게 됩니다.

단, 모니터가 데드락이나 라이브락을 막아주지는 못하므로 프로그래머는 신중하게 락의 순서와 범위를 결정해야 합니다.

두 스레드가 계좌 A와 B 사이에서 서로 반대 방향으로 송금한다고 해볼까요? 스레드 1은 A → B, 스레드 2는 B → A로 보내려고 하고, 송금하려면 두 계좌의 락을 모두 잡아야 합니다.

데드락(deadlock) 은 서로가 가진 락을 기다리면서 둘 다 영원히 멈춰버리는 상황입니다.

sequenceDiagram
participant T1 as 스레드 1 (A → B)
participant A as 계좌 A 락
participant B as 계좌 B 락
participant T2 as 스레드 2 (B → A)
T1->>A: lock 획득
T2->>B: lock 획득
T1-xB: lock 요청 → 대기 (T2가 보유 중)
T2-xA: lock 요청 → 대기 (T1이 보유 중)
Note over T1,T2: 서로 상대의 락을 기다리며 둘 다 멈춤 (아무것도 안 함)

라이브락(livelock) 은 데드락을 피하려고 “상대 락을 못 잡으면 내 락을 풀고 다시 시도하자"고 했는데, 둘이 똑같은 타이밍에 양보를 반복하는 상황입니다. 스레드는 계속 바쁘게 움직이지만, 일은 하나도 진행되지 않습니다.

sequenceDiagram
participant T1 as 스레드 1 (A → B)
participant A as 계좌 A 락
participant B as 계좌 B 락
participant T2 as 스레드 2 (B → A)
loop 같은 타이밍에 끝없이 반복
T1->>A: lock 획득
T2->>B: lock 획득
T1-xB: lock 시도 실패
T2-xA: lock 시도 실패
T1->>A: 양보하려고 lock 해제
T2->>B: 양보하려고 lock 해제
end
Note over T1,T2: 둘 다 계속 움직이지만 송금은 영원히 진행되지 않음

좁은 복도에서 마주친 두 사람으로 비유하면, 데드락은 둘 다 “당신이 먼저 비켜요” 하고 가만히 서 있는 거고, 라이브락은 둘 다 같은 쪽으로 계속 비켜주느라 좌우로 왔다 갔다만 하는 겁니다. 보통 데드락은 모든 스레드가 락을 같은 순서로 잡게 해서(예: 계좌 번호가 작은 쪽 먼저) 막고, 라이브락은 재시도 전에 무작위로 잠깐 기다리게(random backoff) 해서 타이밍을 어긋나게 만들어 막습니다.

분산 객체(1990-2000년대 초)

80년대 후반부터 PC와 유닉스 워크스테이션의 성능이 향상되고 가격은 대중화 되기 시작했습니다. 그래서 기존에 쓰던 비싼 메인프레임 컴퓨터 대신에 여러대의 컴퓨터로 업무를 나눠 처리하는 클라이언트/서버 아키텍처가 유행했고, 클라이언트와 서버를 네트워크로 연결하기 위한 LAN도 대중화 되었습니다.

메인프레임과 PC가 한 공간에서, https://www.sleutelboek.eu/web/computerhardware30-13-de-krachtigste-computers

그러다 보니 기업이 쓰던 기존의 메인프레임(주로 COBOL을 사용), 유닉스 서버, 윈도우 등 수많은 기종이 뒤섞이게 되었고, 기업 간에 쓰는 시스템도 매우 달라서 서로 호환이 되지 않는 경우가 종종 발생했습니다. 기업이 합병하는 일이 생기면 시스템 통합이 아주 큰 문제였던 거죠.

1989년 HP, Sun등의 기업이 업계 표준을 만들 목표로 OMG(Object Management Group)을 결성했고, 1991년 CORBA 1.0을 발표했습니다.

CORBA 원격 호출, https://userpages.umbc.edu/~dgorin1/451/middleware/objectoriented.htm

위 다이어그램에 등장하는 요소는 다음과 같습니다.

Client: 원격 객체의 메서드를 호출하는 쪽 프로그램
Object: 실제 처리 로직을 담고 있는 서버 쪽 객체
Stub: 클라이언트 쪽 대리인. IDL 인터페이스 정의로 부터 생성되며, Stub에 대한 호출을 네트워크로 전송할 수 있는 바이트 형태로 변환(마샬링)
Skel(Skeleton): 서버 쪽 대리인. IDL 인터페이스 정의로 부터 생성되며, 도착한 바이트를 메서드 이름과 인자로 복원하고(언마샬링), 실제 객체의 메서드를 호출하고 결과를 다시 마샬링해서 리턴.
ORB(Object Request Broker): 요청을 받아 목적지 객체를 찾고 전달한다. 객체가 같은 프로세스 또는 다른 컴퓨터에 있는지 찾고 연결하여 통신을 처리한다.
IIOP(Internet Inter-ORB Protocol): ORB가 TCP/IP를 통해 통신을 주고 받는데 사용하는 표준 프로토콜. CORBA 2.0에 추가됨.

도식의 화살표를 따라가보면 두 개의 호출을 확인할 수 있습니다. 첫 번째는 같은 ORB에서 관리되는 객체를 호출하는 경우, 그리고 두 번째는 원격의 ORB에서 관리되는 객체를 호출하는 경우입니다.

MS에서도 자신들만의 독자적인 길을 가고 있었는데요, 1996년 윈도우 NT 4.0 기반의 DCOM을 발표했습니다.

DCOM Technology. Şevket Duran Haşim Sak. https://www.slideserve.com/truong/dcom-technology

앞서 살펴본 CORBA와 구조는 거의 동일합니다. COM 런타임이 CORBA의 ORB의 역할을 맡아 객체 생성 및 참조 관리와 호출을 관리합니다. 클라이언트 측에서는 Proxy, 서버에서는 Stub이 호출을 받아 마샬링/언마샬링을 담당합니다.

두 기술 모두 분산 시스템 환경에서 객체가 어디에 존재하는지와 상관없이 로컬 호출 처럼 사용할 수 있도록 하는 위치 투명성을 확보하고자 했습니다. 하지만, 분산 객체는 로컬 객체와 본질적으로 다르다는 주장이 설득력을 얻었죠.

Jim Waldo등 A Note on Distributed Computing의 저자들은 초록(abstract)에서 이렇게 말하고 있습니다.

We argue that objects that interact in a distributed system need to be dealt with in ways that are intrinsically different from objects that interact in a single address space. These differences are required because distributed systems require that the programmer be aware of latency, have a different model of memory access, and take into account issues of concurrency and partial failure.

즉, 로컬 호출과 원격 호출은 다음과 같이 차이가 있다는 겁니다.

차이	로컬 호출	원격 호출
지연	나노초	밀리초, 4~5자릿수 차이
메모리 접근	포인터 공유 가능	주소 공간이 다름, 포인터 무의미
부분 실패	호출자와 피호출자가 같이 죽거나 같이 산다	원격 피호출자만 죽을 수 있고, 죽었는지 느린지 구분 불가
동시성	호출 순서를 제어할 수 있다	다른 클라이언트가 언제든 끼어든다

이 중에 가장 심각한 문제는 동시성과 부분 실패일 겁니다. 은행 시스템에서 입금/인출 하는데 부분적으로 실패한다? 입금이 진행 중인데 인출 돼버렸다? 이건 굉장히 심각하죠. 객체를 네트워크위에 올려놓았지만, 객체의 동시성을 제어하기 위한 락은 네트워크를 넘지 못했죠.

분산 락과 2단계 커밋

분산 시스템에서 원격 객체의 상태를 지키기 위해서는 두 가지 문제를 풀어야 합니다.

상호 배제: 네트워크를 통해 참여하는 여러 노드가 “이 객체를 지금 누가 접근할 수 있나?“에 대해 합의해야 하는 문제입니다. 이 문제를 해결하려면 락이 로컬을 넘어서, 합의 프로토콜(paxos, raft 등)을 통해 복제되는 서비스(분산 락 매니저)여야 합니다. 최근에는 ZooKeeper나 etcd등이 이런 역할을 담당합니다.
원자적 커밋: 여러 노드에 걸쳐있는 변경이 전부 성공하여 반영되거나, 모두 실패하여 취소하는 문제입니다. 이 문제를 해결하기 위해서 2단계 커밋이 제시되었습니다. 각 노드에서 오는 요청을 코디네이터가 처리하며, 코디네이터는 모든 참여자에게 PREPARE를 보냅니다. 모든 참여자가 VOTE_COMMIT으로 응답하면 COMMIT 요청을 보내고, 하나라도 ABORT로 응답하면 ABORT를 보냅니다.

sequenceDiagram
participant C as 코디네이터
participant A as 참여자 A
participant B as 참여자 B
C->>A: PREPARE
C->>B: PREPARE
A-->>C: VOTE_COMMIT (로그 기록 후)
B-->>C: VOTE_COMMIT (로그 기록 후)
C->>A: COMMIT
C->>B: COMMIT

두 경우 모두 조정자가 필요하고, 조정자는 결론이 날 때 까지 요청을 블록해야 합니다. CORBA OTS(Object Transaction Service) 와 DCOM의 MTS(Microsoft Transaction Server)가 2단계 커밋을 분산 객체에 구현한 것인데, 네트워크에서 객체에 락을 걸기 위해 매우 복잡한 절차를 거쳐야 했던 거죠.

마이크로서비스(2010~)

이후 XML을 HTTP로 주고받으면서 이기종간의 상호운용성을 확보하자는 SOAP기반의 웹서비스가 제시되었고 MS등의 각 벤더가 여기 집중했지만 너무 복잡한 표준 명세와 IDE나 프레임워크의 과도한 의존, 그리고 XML 구조가 너무 복잡하고 무거운 이유 등의 문제가 있었습니다. 게다가 2000년대 중반 웹2.0과 ajax의 확산으로 웹의 중심이 브라우저로 옮겨간 것도 SOAP기반 웹서비스가 외면받는 이유가 되었습니다.

그리고 SOA라는 개념도 2000년대 들어 유행했지만, 역시 각 벤더가 고가의 제품과 컨설팅을 중심으로 사업을 전개하면서 그 자체가 또 하나의 병목지점이자 블랙박스가 되었습니다.

그리고 지금 우리는 자유로운 JSON기반의 REST API와 계약 기반의 gRPC등을 통해 마이크로서비스 시대에 살고 있는데요, 마이크로서비스에서 상태는 DB가 책임지고 있습니다.

flowchart LR
LB[로드 밸런서] --> S1[주문 서비스 #1]
LB --> S2[주문 서비스 #2]
LB --> S3[주문 서비스 #3]
S1 --> DB[(주문 DB)]
S2 --> DB
S3 --> DB

이상적인 마이크로서비스 구조에서 각 서비스는 자기 도메인과 연관된 DB만 가지기 때문에 서비스 간의 트랜잭션은 존재하지 않으며, 여러 서비스에 걸친 변경을 처리할 때는 saga 패턴을 사용하게 됩니다.

flowchart LR
subgraph F[정상 흐름: 각 단계는 자기 DB에 로컬 커밋]
direction LR
O[주문 서비스<br/>주문 생성] --> P[결제 서비스<br/>결제 승인] --> I[재고 서비스<br/>재고 차감] --> D[배송 서비스<br/>배송 예약]
end
D -. 배송 예약 실패 .-> CI
subgraph B[보상 흐름: 역순으로 되돌림]
direction RL
CI[재고 서비스<br/>재고 복원] --> CP[결제 서비스<br/>결제 취소] --> CO[주문 서비스<br/>주문 취소]
end

각 단계는 성공시 즉시 커밋되는데, 중간에 요청 하나가 실패할 경우 역순으로 각 커밋을 되돌리는 구조입니다. 각 서비스가 취소와 복원을 위한 로직을 따로 설계해야 하는 거죠. 트랜잭션의 롤백이 아닌 실패를 보상하기 위한 새 트랜잭션을 수행하기 때문에 중간 상태가 다른 요청에 노출될 수 있습니다.

이런 구조는 모든 상태가 DB에 존재하는 상태 없는 서비스에는 잘 맞지만, 실시간 게임이나 장바구니 처럼 처리 대상이 오래 유지되는 상태를 가지는 경우라면, 매번 요청을 받을 때 마다 상태를 DB에서 복원/저장하는 식으로 처리해야 합니다.

이런 경우 상태를 메모리에 올려놓고, 딱 1 군데에서만 그걸 접근하면 어떨까? 하는 질문이 제기되었고, 그래서 액터 모델이 다시 돌아오게 됩니다!

액터 모델의 귀환(2010~)

앞서 상태를 공유함으로써, 또는 분산 시스템에서 상태를 공유하고자 하면서 발생한 문제들과 해결책들을 살펴봤습니다. 그 중에서도 마이크로서비스는 현재 가장 성공적으로 구현되어 운영되고 있습니다. DDD(Domain Driven Design), EDA(Event Driven Architecture)등의 설계를 통해서 서비스 간의 의존성을 명확하게 구분하고 결과적 일관성을 목표로 해서 조금 더 유연하게 상태를 관리하면서 시스템 실패에 대응하는 형태로 진화하고 있죠.

하지만 액터 모델은 상태 관리 문제를 아예 다르게 접근합니다. 처음부터 아예 상태를 공유하지 않으면 된다는 거죠! 2009년에 JVM 기반의 Akka가 나왔고, 이후에 Akka를 .net으로 포팅한 Akka.net이 나왔습니다. 그리고 2015년에 MS는 자사 서비스에서 활용하던 Orleans를 오픈소스로 공개했습니다.

고전 액터 모델에서 액터의 생성 및 삭제는 개발자가 처리해야 했습니다. 특정 액터에게 메세지를 보내려면 반드시 먼저 액터가 생성되어 있어야 하는데, 그래야 액터의 주소를 알 수 있고 거기에 메세지를 보낼 수 있기 때문이죠. Orleans는 항상 액터가 존재한다고 가정하는 가상 액터(virtual actor)를 새롭게 제시했습니다. 개발자는 액터의 존재 유무와 상관없이 메세지를 그냥 보내기만 하면 되고, 액터의 생성 및 삭제 그리고 활성/비활성화는 런타임이 담당하는 구조인거죠.

이렇게 보면 앞서 이야기 했던 분산 객체와도 좀 비슷한 느낌이 들죠? 하지만, 액터 모델의 경우 분산 객체 처럼 RPC(Remote Procedure Call) 호출을 한다기 보다는, 분산 시스템 어딘가에 존재할 액터에게 메세지를 보내는 개념으로 처리됩니다. 그러면 액터는 자신에게 도달한 메세지를 큐에 쌓아뒀다가 순서대로 처리하게 되는 거죠.

그러니까 분산 객체가 원격의 객체가 로컬에 있는 거 처럼 호출하는 게 목표였다면, 액터 모델은 로컬에 있더라도 원격 메세지 호출 처럼 다루자의 느낌입니다. 액터가 어디에 있는지 신경쓰지 말고 메세지 전송/수신 방식을 사용하자는 거죠.

그러니까 로컬에서 로컬로 전송되는 메세지의 경우 네트워크 실패가 거의 발생하지 않는 원격 메세지정도로 생각하자는 거죠.

.NET Orleans의 경우 액터에 대한 메세지 전송이(await order.AddItem(x)) 마치 RPC처럼 보이기도 합니다.

액터 모델을 아주 간단한 도식으로 살펴 보면 다음과 같습니다.

flowchart LR
C1[클라이언트 A] -->|메시지| R[런타임: ID → 노드 라우팅]
C2[클라이언트 B] -->|메시지| R
R --> A1["액터 cart:42<br/>(노드 1, 상태 메모리 보관)"]
R --> A2["액터 cart:77<br/>(노드 2)"]
A1 -.->|주기적/이벤트 저장| DB[(영속 저장소)]

액터에게 메세지를 보내는 클라이언트는 런타임이 이해할 수 있는 액터의 식별자 ID를 목표로 메세지를 전송합니다. 그러면 런타임은 ID를 통해 액터가 어떤 노드에 있는지 찾고, 액터에게 메세지를 전달 해줍니다. 각 액터는 자신의 상태를 메모리에 가지고 있으며(상태는 최종적으로 DB에 저장하지만, 액터가 생성/활성화될 때 메모리에 로드합니다. 시스템에서 액터는 결과적으로 유일하기 때문에 메모리에서 상태를 관리해도 문제가 없습니다!), 큐에 쌓인 메세지를 순서대로 처리하므로 락을 사용하지 않고도 상태의 일관성이 보장됩니다.

시스템에서 액터가 결과적으로 유일한 이유는, 클러스터간의 네트워크 단절등의 불안정한 상황에서는 액터가 중복되어 활성화 될 수도 있기 때문입니다! Orleans의 경우 액터는 활성화 될 때, 저장소에서 ETag(버전 표시)를 확인합니다. 그래서 자신이 가진 ETag을 비교해서 값이 다르다면 저장소에 상태를 덮어쓸 수 없도록 합니다.

물론 액터 모델도 여러 액터에 걸친 처리를 해야 하는 경우가 생길 수도 있습니다. 예를 들어서 하나의 주문에 여러 상품이 포함되는 경우를 생각해보면, 주문도 액터고 상품도 액터입니다. 그런데 주문 액터는 주문에 포함된 모든 상품 주문 상태(장바구니에 뒀다가 주문하는 그 순간에 재고가 없어졌을 수도 있죠!)를 확인하고 주문의 상태를 변경해야 합니다.

Orleans는 이런 문제를 위해서 분산 ACID 트랜잭션을 지원하긴 합니다. 이미 앞서 살펴봤던 락+2단계 커밋기반이기 때문에, 빈번한 데이터 쓰기가 발생하는 경우 성능이 저하될 수 있겠죠. 그리고 ITransactionalStateStorage를 구현하는 데이터 스토리지만 지원되는데 Azure Table Storage, AWS DynamoDB, MSSQL/MySQL 등이 지원되고 있습니다. 그런데 DynamoDB의 경우 최신 버전 다운로드가 398회(2026-09-28 기준)에 불과하고, MSSQL/MySQL 라이브러리의 경우 오래전에 개발이 중단되는 등 사실상 Azure Table Storage 정도가 안정적인 버전이라서 선택지가 좁은 상황입니다.

아무래도 일반적인 해결책은 앞서 살펴봤던 saga 패턴을 사용하는 거겠죠. 그게 아니라면 이 문제가 액터 모델로 풀기에 적절하지 않은 문제 일 수도 있습니다.(DB에서 상태를 관리하는 경우, 트랜잭션 하나로 해결할 수도 있기 때문이죠.) 그래서 액터 모델과 DB에 상태를 저장하는 방식을 섞어 쓰는 경우도 있다고 합니다.

정리

뭔가 액터 모델에 대해서 정리하려다 보니 동시성과 병렬성에 대한 정리도 하고, 객체를 기반으로 한 분산 시스템의 역사에 대해서 살펴보게 됐습니다. 그냥 단순히 제가 궁금해서 그랬던 거긴 한데, 꼼꼼하게 정리하자니 다뤄야할 내용이 너무 많아서 좀 핵심 내용위주로 살펴보면서 정리했습니다. 어쨌거나 다음에는 .NET Orleans를 통해서 액터 모델을 직접 구현해볼까 합니다!

참고자료

분산 시스템 설계(3) - 액터 모델(1) feat. Go, Node.js, .NET, Java, Rust

Sat, 19 Sep 2026 08:11:19 +0900

원래는 액터 모델에 대해서 다루려고 했으나… 조사를 하다 보니, 동시성과 병렬성에 대해서 먼저 정리하고 가는 게 좋겠다 싶은 마음이 들었습니다.(제가 헷갈렸기 때문이기도 하죠!) 그리고 정리를 하다 보니… 모르는 내용이 많아서 이거 저거 정리해서 넣다 보니 일단 각 주요 언어별로 어떻게 동시성과 병렬성을 처리하는지에 대해서 정리하는 문서가 되어버렸습니다!

아주 간단하게 설명하면, 동시성은 여러 작업을 어떻게 처리할지 프로그램을 설계하는 문제고, 병렬성은 동시 실행을 처리하는 하드웨어의 문제입니다.

아마도 흑백요리사 같은 요리 경연 프로그램을 누구나 한 번쯤은 봤을 겁니다. 1대1 또는 n대n으로 요리대결을 진행하죠.

1대1로 요리대결을 할 때는 동시성의 문제가 절대적입니다. 제한된 시간 내에 국을 끓이면서 재료를 손질하다가 오븐에 재료를 넣고 다시 국을 젓고 등의 작업을 어떻게 번갈아가면서 동시에 진행할지 잘 설계해야 되죠. 반면에 n대n으로 요리대결을 할 때는 동시성과 병렬성을 함께 고려해야 합니다. 각자의 작업 배분과 진행 순서를 잘 설계한 다음에 실수 없이 동시에 각자 할 일을 잘 진행해야만 하죠.

먼저 1대1 대결입니다. 조리대는 하나, 요리사도 한 명이죠. 국이 끓는 동안 손 놓고 기다리면 시간이 아까우니까, 그 사이에 재료를 손질하고 오븐을 돌립니다. 이렇게 기다리는 시간에 다른 일을 끼워 넣는 설계가 동시성입니다.

flowchart TB
subgraph ONE["1대1 대결 = 동시성 (조리대 1개, 요리사 1명이 여러 일을 번갈아 처리)"]
direction TB
A1["① 국 불에 올리기"] --> A2["② 재료 손질"] --> A3["③ 국 젓기"] --> A4["④ 오븐에 넣기"] --> A5["⑤ 소스 만들기"] --> A6["⑥ 국 간 맞추기"] --> A7["⑦ 오븐에서 꺼내기"] --> A8["완성"]
A1 -. "불에 올리고 손을 뗌" .-> W1["국이 끓는 중<br/>(손 안 대고 기다리는 시간)"]
W1 -. "이 시간에 ② ③을 처리" .-> A3
A4 -. "오븐에 넣고 손을 뗌" .-> W2["오븐이 굽는 중<br/>(기다리는 시간)"]
W2 -. "이 시간에 ⑤ ⑥을 처리" .-> A6
end

다음은 n대n 대결입니다. 조리대도 여러 개, 요리사도 여러 명이죠. 누가 뭘 맡을지 나눈 다음에는 각자 자기 조리대에서 동시에 병렬로 작업합니다. 물론 그 와중에도 요리사 한 명 한 명은 여전히 자기가 해야 할 일에 대해서 동시성을 고민해야 합니다.

flowchart LR
D["작업 배분<br/>(누가 뭘 맡을지 설계)"]
subgraph MANY["n대n 대결 = 병렬성 (조리대 3개, 요리사 3명이 각자 맡은 일을 동시에 처리)"]
direction LR
subgraph C1["요리사 A (조리대 1)"]
direction LR
B1["국 끓이기"] --> B2["간 맞추기"]
end
subgraph C2["요리사 B (조리대 2)"]
direction LR
B3["재료 손질"] --> B4["오븐에 굽기"]
end
subgraph C3["요리사 C (조리대 3)"]
direction LR
B5["소스 만들기"] --> B6["플레이팅"]
end
end
E["완성"]
D --> B1
D --> B3
D --> B5
B2 --> E
B4 --> E
B6 --> E

뒤에서 살펴볼 런타임 얘기로 바꿔 말하면, 조리대는 CPU 코어, 요리사는 OS 스레드, 각 요리 작업은 goroutine이나 Task 같은 작업 단위에 해당합니다. 조리대가 하나뿐이어도 동시성 설계는 필요하고, 조리대가 여러 개라야 동시에 작업할 수 있는 병렬성이 생기는 거죠.

각 언어의 런타임은 이런 동시성과 병렬성을 해결하는 모습이 조금씩 다릅니다. 흥미를 위해서 그 부분을 먼저 확인해보고 넘어갈까 합니다.

Go

Go는 동시성을 위해서 goroutine을 사용합니다. goroutine은 OS 스레드와 달리 매우 작은 2KB의 스택에서 시작하기 때문에 수십만 개까지도 생성이 가능하고, OS 스레드에서 처리할 goroutine을 쉽게 전환할 수 있기 때문에 goroutine의 전환은 OS 스레드의 문맥 교환(context switching)이 필요하지 않습니다.

참고로 OS 스레드의 문맥 교환은 대략 다음과 같은 과정을 거칩니다. *표시는 특히 많은 시간이 소요되는 과정을 나타냅니다.

커널 모드 진입*: CPU는 필요한 권한을 얻기 위해 유저 모드에서 커널 모드로 진입

스레드1의 상태 저장: CPU 레지스터, 프로그램 카운터, 스택 포인터 등 스레드1의 모든 상태를 스레드1의 메모리 블록에 기록(TCB, Thread Control Block)

스케줄러 상태 갱신: OS가 스레드1을 대기 상태로 설정하고 스레드2를 대기 큐에서 선택

TLB/cache 초기화*: 스레드1과 스레드2가 서로 다른 프로세스의 스레드라면, TLB(translation lookaside buffer)를 초기화

스레드2의 상태 불러오기: 스레드2의 TCB에서 모든 상태를 불러오기

유저 모드로 복귀*: CPU가 유저 모드로 돌아와서 스레드2의 이전 상태로부터 계속 실행

병렬성은 논리 코어 개수를 가리키는 GOMAXPROCS 설정을 통해 해결합니다.(기본값이 논리 코어 개수이고, 자유롭게 설정할 수 있습니다.) 런타임 스케줄러가 goroutine을 여러 OS 스레드에 배분하고, 여러 개의 CPU 코어에서 동시에 실행하면서 자연스럽게 병렬 실행이 가능해지는 구조인 거죠. Go는 GMP(Goroutine-Machine-Processor) 스케줄러를 통해 병렬성을 관리합니다.

G (goroutine): 실행할 작업 단위. OS 스레드와 다르게 스택이 2KB로 시작해서 수십만 개 만들 수 있어요.
M (machine): 실제 OS 스레드.
P (processor): 논리 프로세서. 각 P가 자기 고루틴 실행 큐를 갖고, M이 P를 하나 획득해야 고루틴을 실행할 수 있어요.

각 G, M, P를 통해 병렬성을 관리하는 과정을 도식화 해보면 다음과 같습니다.

flowchart TD
subgraph HW["하드웨어 (4코어)"]
direction LR
C1[코어 1]
C2[코어 2]
C3[코어 3]
C4[코어 4]
end
OS["OS 스케줄러 (커널)<br/>M을 어느 코어에서 돌릴지 결정 — Go는 관여하지 않음<br/>M은 코어에 고정되지 않고 자유롭게 옮겨짐"]
subgraph MS["OS 스레드 M (런타임이 필요한 만큼 생성, 기본 상한은 최대 10000개)"]
direction LR
M1[M1]
M2[M2]
M3[M3]
M4[M4]
M5["M5<br/>blocking syscall 중<br/>P 반납, Go 코드 실행 불가"]
M6["M6<br/>유휴 (idle)<br/>P를 못 얻어 대기"]
end
subgraph GO["Go 런타임 스케줄러 (유저 공간)"]
direction TB
subgraph PS["P = 실행 허가증 + 로컬 큐 + mcache (GOMAXPROCS = 4 → 동시에 Go 코드를 돌리는 M도 최대 4개)"]
direction LR
P0["P0<br/>실행 중: G1<br/>큐: G5 G9"]
P1["P1<br/>실행 중: G2<br/>큐: G6"]
P2["P2<br/>실행 중: G3<br/>큐: G7 G8"]
P3["P3<br/>실행 중: G4<br/>큐: (비어 있음)"]
end
GQ["글로벌 큐<br/>G10 G11 G12 … 100K+<br/>(스택 2 KB로 시작, 필요 시 확장)"]
NP["netpoller<br/>네트워크 I/O 대기 중인 G<br/>M을 블록하지 않음"]
end
C1 --- OS
C2 --- OS
C3 --- OS
C4 --- OS
OS -. "코어에 배치 (시점마다 달라짐)" .-> M1
OS -.-> M2
OS -.-> M3
OS -.-> M4
OS -.-> M5
OS -.-> M6
M1 -- "P 획득" --> P0
M2 -- "P 획득" --> P1
M3 -- "P 획득" --> P2
M4 -- "P 획득" --> P3
GQ -. "① 로컬 큐가 비면 글로벌 큐에서 G를 가져옴<br/>(61틱마다 1번은 로컬 큐보다 먼저 확인 → 기아 방지)" .-> P3
NP -. "② 글로벌 큐도 비면 I/O 완료된 G 확인" .-> P3
P2 -. "③ 그래도 없으면 다른 P의 로컬 큐에서 절반 훔쳐옴<br/>(work stealing, 마지막 수단)" .-> P3

위 예시에서는 CPU에서 사용 가능한 논리 코어가 4개(GOMAXPROCS가 4로 설정된 상태)인 상태를 예시로 보여주고 있습니다.
OS 스케줄러는 각 OS 스레드(M)가 어떤 논리 코어에서 작동할지를 결정합니다.
논리 코어가 4개이기 때문에 OS 스레드가 사용할 수 있는 프로세서(P)도 4개입니다. 동시에 처리할 수 있는 작업 수가 4개인 셈이죠.
각 OS 스레드(M)는 작업을 위해 프로세서(P)를 획득해야 합니다.
3번 프로세서(P3)를 보면 현재 goroutine G4를 실행 중이고, 로컬 큐에 다음 작업이 없기 때문에 G4가 끝나면 처리할 작업이 없는 상태입니다.
① G4가 끝나면 우선 글로벌 큐에서 goroutine을 가져옵니다.
② 글로벌 큐에도 작업이 없다면 완료된 I/O 작업이 있는지 확인합니다.
③ 글로벌 큐와 완료된 I/O 작업도 없다면, 다른 프로세서(P)에서 goroutine 절반을 가져옵니다.

매우 간결하면서도 효과적으로 동시성, 병렬성을 관리하고 있습니다.

정리

정리하자면,

P(프로세서)는 Go 런타임이 만드는 자료구조로, Go 코드를 실행하기 위한 작업대입니다 (작업 더미인 로컬 큐, 공구함인 mcache 포함).
P는 GOMAXPROCS 개수만큼 생성된다. 기본값은 논리 코어 수이며, Go 1.25부터는 cgroup CPU 제한도 반영합니다.
M(OS 스레드)은 고루틴을 실행하는 주체다. 런타임이 필요에 따라 생성하며(ex: goroutine이 특정 M을 독점하면, 그 M은 다른 goroutine을 실행하지 못하므로 런타임이 추가로 M을 생성), 기본 상한은 10,000개입니다.
M이 어떤 코어에서 실행될지는 OS 스케줄러가 결정한다. Go는 관여하지 않습니다.
M은 P를 획득해야만 고루틴을 실행할 수 있다. 따라서 동시에 Go 코드를 실행하는 M은 최대 GOMAXPROCS개입니다.

Node.js

Node.js는 싱글 스레드 기반으로 실행되며 파일, 네트워크 I/O 등의 이벤트가 발생할 때마다 작업 큐에 쌓아뒀다가 해당 이벤트들을 처리할 순서가 되면 큐에서 작업을 꺼내 순차적으로 처리합니다. 즉, I/O 중심의 동시성 작업 처리를 가장 잘할 수 있는 구조를 선택하고 있습니다. 우선 Node.js의 동시성 처리 구조에 대해서 좀 더 자세히 알아볼까 합니다.

Node.js는 다음과 같이 JS 영역과 C/C++기반의 네이티브 런타임 영역으로 구성되어 있습니다.

Node.js 는 JS 코드를 실행해야 할 때마다 V8에게 실행을 요청합니다. 스크립트 코드 실행, 이벤트 루프의 콜백(파일, 네트워크 I/O 등) 등이 발생할 때마다 V8에게 실행을 요청하는 거죠. 이때, 네이티브 영역에서 JS 영역으로 넘어가게 되며 JS의 호출이 모두 끝났을 때(JS 호출 스택이 완전히 비었을 때) 다시 네이티브 영역으로 돌아오게 됩니다.

스크립트 실행 후 발생하는 각 이벤트의 콜백을 처리하기 위해서 네이티브 영역의 libuv는 여러 단계로 구성된 루프를 순환하면서 각 단계의 콜백들을 순차적으로 처리합니다.

flowchart TD
Main["메인 스크립트 실행<br/>(이것도 '콜백 하나'로 취급)"]
Main --> MT
subgraph MT["마이크로태스크 체크포인트 — JS 콜백 하나가 리턴해 호출 스택이 빌 때마다 실행"]
direction LR
NT["① process.nextTick 큐<br/>빌 때까지 전부 실행<br/>(도중에 추가된 것도 계속)"]
PR["② Promise 큐<br/>.then / await 이후 / queueMicrotask<br/>빌 때까지 전부 실행<br/>(도중에 추가된 것도 계속)"]
NT --> PR
PR -->|"②에서 nextTick이 새로 잡혔으면 ①로"| NT
end
MT -->|"두 큐가 모두 빈 뒤에야 다음으로"| Timers
subgraph Loop["이벤트 루프 — 한 바퀴 (각 단계는 자기 큐의 콜백을 순서대로 실행)"]
Timers["timers<br/>만료된 setTimeout / setInterval 콜백"]
Pending["pending callbacks<br/>이전 바퀴에서 미뤄진 I/O 콜백"]
Poll["poll<br/>준비된 I/O 이벤트 수집 → 콜백 실행"]
Wait["OS에 블로킹 대기 (epoll / kqueue / IOCP)<br/>스레드가 멈추므로 CPU 사용 없음<br/>대기 시간 = 가장 가까운 타이머까지 남은 시간"]
Check["check<br/>setImmediate 콜백"]
Close["close callbacks<br/>socket.on('close') 등"]
Exit["루프 종료 → 프로세스 종료"]
Timers --> Pending --> Poll
Poll -->|"실행할 콜백 없음 + setImmediate 예약 없음"| Wait
Wait -->|"I/O 도착 → 깨어나서 poll 안에서 즉시 콜백 실행"| Poll
Wait -->|"타이머 시각 도래 → 이벤트 없어도 깨어남"| Check
Poll -->|"콜백 다 돌림 또는 setImmediate 예약됨"| Check
Check --> Close
Close -->|"살아있는 타이머·핸들 있음 → 다음 바퀴"| Timers
Close -->|"타이머·핸들·예약 아무것도 없음"| Exit
end
Loop -.->|"어느 단계든 콜백 하나 끝날 때마다"| MT

여기서 주목해야 할 부분은 두 가지입니다.

메인 스크립트 실행(CommonJS 기준, 이벤트 루프 진입 전 1회)
이벤트 루프에서 콜백 하나가 종료될 때마다 실행되는 마이크로태스크

위 두 가지 경우 모두 JS 코드 실행을 위해서 네이티브->JS 영역으로 진입했다가 JS 실행이 모두 끝나서 다시 네이티브 영역으로 돌아오는 상황입니다. 즉, JS 실행 후 네이티브 영역으로 돌아올 때마다 마이크로태스크 큐(nextTick 큐 -> Promise 큐 순서) 정리 작업을 진행하는 셈이죠!

참고로 만료된 타이머 여러 개가 있는 경우 각 타이머 콜백을 JS의 반복문 안에서 순차적으로 처리하기 때문에 네이티브 영역으로 돌아가지 않지만, JS 코드에서 runNextTicks()를 명시적으로 호출해서 네이티브로 돌아간 것과 같은 효과를 냅니다. 그리고 setImmediate도 같은 방식으로 처리됩니다.

메인 스크립트 실행

어떻게 메인 스크립트를 실행하고 이벤트 루프에 진입하는지는 모듈의 형식에 따라 달라집니다. 그 이유는 CommonJS, ESM 모듈을 처리하는 방식이 다르기 때문인데요. 아주 간단한 express 예제를 통해 차이점을 알아보겠습니다.

각 모듈의 차이점에 대해서 더 자세한 내용은 Node.js: –experimental-vm-modules를 참조하세요!

CommonJS

아주 간단한 express를 CommonJS 형식으로 작성해봤습니다.

// server.js (CommonJS)
const express = require('express');
const app = express();

app.get('/', (req, res) => {
 res.send('hello');
});

app.listen(3000, () => console.log('listening')); // 내부적으로 콜백을 process.nextTick으로 등록
process.nextTick(() => console.log('tick'));
Promise.resolve().then(() => console.log('promise'));
console.log('end of script');

아래쪽의 4줄을 보면, 총 3개의 콜백과 콘솔 출력이 있죠? 일단 결과를 볼까요?

> node server.js
end of script
listening
tick
promise

end of script -> listening -> tick -> promise의 순서로 출력되네요. 그러니까,

console.log 실행: end of script
process.nextTick: listening
process.nextTick: tick
promise: promise

이런 순서로 실행된 건데요, 앞서 살펴봤던 도식의 메인 스크립트 실행 후 리턴하면서 콜스택이 비었기 때문에 process.nextTick 큐 -> promise 큐의 순서로 큐를 비우면서 콜백을 실행한 결과입니다.

CommonJS는 스크립트를 실행하기 전에, 스크립트의 내용을 다음과 같은 wrapper 함수로 감싸서 함수 형태로 만듭니다.

(function (exports, require, module, __filename, __dirname) {
 // server.js 내용 전체
});

그리고 V8에게 이 함수의 실행을 요청합니다.

더 자세하게 설명하면 V8이 run_main_module.js를 실행하는 과정에서 함수 wrapping 및 실행이 진행됩니다.

그리고 메인 스크립트의 콜 스택이 모두 비어서 실행이 종료되면 V8은 JS 실행을 종료하고 리턴합니다. 그리고는 마이크로태스크 큐에 있는 작업들을 nextTick -> promise의 순서로 모두 실행하게 됩니다. 그래서 다음과 같은 순서로 출력이 진행되죠:

메인 스크립트의 console.log(’end of script’);
nextTick에 등록된 순서대로, console.log(’listening’), console.log(’tick')
다음으로 promise에 등록된 console.log(‘promise’)

ESM

다음은 동일한 코드를 ESM 방식으로 작성한 코드입니다.

// server.mjs
import express from 'express';
const app = express();

app.get('/', (req, res) => {
 res.send('hello')
});

app.listen(3000, () => console.log('listening')); // 내부적으로 콜백을 process.nextTick으로 등록
process.nextTick(() => console.log('tick'));
Promise.resolve().then(() => console.log('promise'));
console.log('end of script');

실행 결과는 다음과 같습니다.

> node server.mjs
end of script
promise
listening
tick

이번에는 end of script -> promise -> listening -> tick 의 순서로 출력되네요. 그러니까,

console.log 실행: end of script
promise: promise
process.nextTick: listening
process.nextTick: tick

이런 순서로 출력된 셈이죠. 마이크로태스크 작업 중에 process.nextTick 대신에 promise 큐의 작업이 먼저 실행된 건데요. 그 과정을 간략하게 살펴보겠습니다.

ESM의 경우 CommonJS처럼 함수로 wrapping하지 않고, 모듈이 비동기(async)방식으로 로드됩니다. CommonJS와 동일하게 실행되다가 ESM 로더를 사용해야 하는지 판단 과정을 거친 뒤에 비동기로 모듈을 로드하게 됩니다.

그러니까 Node.js는 모듈 로드 작업을 promise 체인으로 걸고 메인 스크립트 실행을 종료합니다. 파일 자체는 동기로 읽지만, 모듈 로더는 async 함수이기 때문에 이후의 작업은 모두 promise 큐에서 진행됩니다. 그래서 메인 스크립트가 끝나고 마이크로태스크를 비우는 시점에 본문이 실행됩니다. 아직은 이벤트 루프가 실행되지 않은 상태이고, 대략 다음과 같이 진행됩니다.

메인 스크립트(run_main_module) 종료 → 마이크로태스크 비우기
 ├ nextTick 큐 (비어 있음)
 └ Promise 큐
 ├ 로더의 await 이어짐
 ├ … link, instantiate
 └ module.evaluate() → server.mjs 본문 실행 ← 여기
 └ 본문에서 건 .then → 같은 큐에 붙어 바로 이어서 실행
 └ 본문에서 건 nextTick → Promise 큐 다 빈 뒤 실행

그렇기 때문에 nextTick보다 promise 콜백이 먼저 화면에 출력된 거죠!

I/O는 누가 기다리나

I/O의 성격에 따라 메인 스레드(정확히는 OS 커널)와 별도의 스레드가 I/O 이벤트를 대기 및 처리합니다.

flowchart LR
JS["메인 스레드 (V8 + 이벤트 루프)"]
OS["OS 이벤트 알림<br/>epoll / kqueue / IOCP"]
TP["libuv 스레드 풀<br/>기본 4개, UV_THREADPOOL_SIZE로 최대 1024"]
JS -- "소켓, 타이머" --> OS
JS -- "fs, dns.lookup, crypto, zlib" --> TP
OS -- "완료 이벤트" --> JS
TP -- "완료 이벤트" --> JS

libuv는 이벤트 루프를 관리하면서 필요한 작업을 스레드 풀에 대기 중인 스레드에 할당합니다. 스레드 풀에는 기본적으로 4개의 스레드가 생성되는데요, 만약 4개의 스레드가 무언가 스레드 블록(block)이 필요한 I/O 작업을 진행 중이라면, dns.lookup을 진행해야 되는 HTTP 요청이 막힐 수도 있습니다!

Node.js의 병렬성

Node.js에서 병렬성을 확보하기 위해서는 별도의 worker_threads나 프로세스를 클러스터링해야 하는데요, 다음은 worker_threads를 사용하는 예시입니다.

// worker_thread.mjs
import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';

if (isMainThread) { // 메인 스레드에서 실행할 코드
 const w = new Worker(new URL(import.meta.url), { workerData: 10000000000 }); // 워커 스레드 실행
 w.on('message', (sum) => console.log(sum));
} else { // 워커 스레드에서 실행할 코드
 let sum = 0;
 for (let i = 0; i < workerData; i++) {
 sum += i;
 }
 parentPort.postMessage(sum); // 메인 스레드에 결과 전달
}

그리고 웹서버로 Node.js를 사용하는 경우, 일반적으로 PM2 같은 오케스트레이터를 사용하여 프로세스를 클러스터링하거나 k8s 등의 환경에 배포합니다.

정리

지금까지 확인한 내용을 정리해보면,

CPU를 많이 사용하는 작업은 이벤트 루프의 콜백에서 처리될 경우, 이벤트 루프를 블록하게 됩니다. 그래서 worker_threads를 사용해서 별도의 스레드로 처리하거나, 작업을 아주 작게 쪼개서 이벤트 루프가 막히지 않도록 해야 합니다.
nextTick, promise의 콜백 안에서 nextTick을 계속 걸면 이벤트 루프는 다음으로 진행하지 못합니다. 그래서 타이머나 I/O의 처리가 매우 지연될 수 있습니다.
마찬가지로 promise 콜백 안에서 계속 promise를 걸어도 이벤트 루프는 다음으로 진행하지 못합니다.
nextTick은 지금 콜백이 끝난 직후에 처리해야 하는 작업에만 예외적으로 사용하며, 다음 루프에 처리하는 게 목적이라면 setImmediate를 사용합니다.
setTimeout(0)보다 setImmediate를 사용합니다. setTimeout은 아무리 짧게 잡아도 최소 1ms의 지연이 필요합니다. 그리고 setImmediate는 I/O 콜백을 처리하는 Poll 단계 다음으로 오는 Check 단계에서 처리되므로, I/O 콜백에서 setImmediate를 걸어두면 항상 setTimeout(0) 보다 먼저 처리됩니다.
setInterval 타이머는 정확하지 않습니다. 타이머가 지정된 시간에 도달하더라도 콜백을 처리하는 Poll 단계가 오래 걸리면 처리가 밀리기 때문입니다. 다음 처리 시간을 setTimeout으로 설정하는 게 좀 더 정확한 처리가 가능합니다.

.NET

.NET은 런타임이 관리하는 ThreadPool을 통해 비동기 작업을 나타내는 Task 실행을 조율합니다. async/await를 통해 I/O 등의 비동기 작업을 실행할 때는 관련 코드를 상태 머신으로 전환하여 스레드를 점유하지 않고 완료를 기다리도록 합니다.

.NET 10 부터 Runtime Async를 실험적인 기능(Preview)으로 제공하고 있습니다. 원래 async/await는 컴파일러가 상태 머신으로 변환해야 했습니다. 컴파일러가 코드를 컴파일하다가 async가 붙어있는 메서드를 보면, IAsyncStateMachine을 구현하는 상태 머신 구조체로 변환해서 비동기 작업이 완료될 때 까지 정지할 수 있도록 했었습니다. 그런데 Runtime Async의 경우 컴파일러는 [MethodImpl(MethodImplOptions.Async)] 어트리뷰트가 붙은 IL 코드를 생성하기만 하고, 이후의 비동기 작업 처리는 런타임이 처리하도록 한 거죠. 이렇게 하면 상태 머신의 오버헤드를 줄일 수 있고, 스택 트레이스도 깔끔해지는 등 여러가지 장점이 있습니다. 다만, 아직은 Preview 단계라서 어떤 부분에서 더 성능이 향상되는지 면밀한 검토가 필요해보입니다. 더 자세한 내용은 이 글 끝에 있는 참고 자료를 확인해주세요!

그리고 ThreadPool이 CPU의 여러 코어를 동시에 사용하기 때문에 병렬성은 자연스럽게 따라오는 구조인데요, 앞서 살펴봤던 Go의 GMP와 유사한 구조라고 볼 수 있죠.(물론 아직 goroutine 같은 도구는 지원하지 않고, 각 스레드는 OS 스레드와 1:1로 대응되는 구조입니다!)

.NET은 병렬 프로그래밍을 위해 별도의 런타임 엔진과 라이브러리를 제공합니다! 이건 좀 이따가 더 살펴보죠.

ThreadPool의 구조

ThreadPool의 구조를 간략하게 표현하면 다음과 같습니다.

flowchart TD
subgraph TP["ThreadPool (.NET 6+ 관리 코드 구현)"]
HQ["고우선순위 글로벌 큐<br/>(.NET 10: 블로킹 직전 이관된 로컬 작업)"]
GQ["글로벌 큐<br/>QueueUserWorkItem, Task.Run 등 외부에서 넣은 작업"]
subgraph W1["워커 스레드 1"]
L1["로컬 큐 (LIFO)"]
end
subgraph W2["워커 스레드 2"]
L2["로컬 큐 (LIFO)"]
end
subgraph W3["워커 스레드 3"]
L3["로컬 큐 (LIFO)"]
end
end
IOT["I/O 완료 처리<br/>Windows: IOCP 스레드<br/>Linux/macOS: epoll/kqueue 전용 스레드 (SocketAsyncEngine)"]
HQ -- "① 최우선" --> L1
GQ -- "② 로컬 큐 비면" --> L1
GQ --> L2
GQ --> L3
L2 -. "③ work stealing (FIFO 쪽에서)" .-> L1
IOT -- "완료 콜백을 큐에 넣음" --> GQ
W1 -. "블로킹 직전 로컬 큐 전체 이관" .-> HQ

글로벌 큐: 외부에서 넣은 작업. FIFO.
로컬 큐: 워커 스레드가 실행 중 만든 자식 Task는 자기 로컬 큐에 (LIFO, 캐시 지역성).
워크 스틸링: 자기 큐가 비고 글로벌 큐도 비면 다른 워커의 로컬 큐 반대쪽에서 훔친다.
스레드 수 조절: 최소(기본 논리 코어 수)까지 즉시 생성. 그 이상은 hill climbing 알고리즘이 처리량을 측정하며 천천히 늘린다. 블로킹 감지 시 더 빨리 추가하는 로직은 .NET 6부터.
Windows 스레드 풀 옵션: UseWindowsThreadPool 설정으로 OS 스레드 풀을 쓸 수 있다. Windows Native AOT에서는 기본값. 이 경우 SetMinThreads/SetMaxThreads가 무효.

각 스레드가 자신의 로컬 큐를 가지고 있고, 로컬 큐가 비면 글로벌 큐나 다른 스레드의 로컬 큐에서 가져오는 등의 작업은 Go의 구조와 유사하죠?

.NET의 Thread는 OS 스레드와 1:1 관계이기 때문에 비동기 작업에 대해서 async/await를 사용하지 않으면, 해당 작업을 처리하는 OS 스레드는 작업이 완료될 때까지 블록(block) 됩니다. 만약 윈도우 앱이라면 UI 스레드가 블록돼서 UI가 먹통이 되는 증상이 발생하게 됩니다!

.NET의 병렬성

.NET은 쉽게 병렬성을 얻을 수 있도록 PLINQ(Parallel LINQ)와 TPL(Task Parallel Library)를 제공합니다. 각 기술들은 기존에 제공하는 SDK와 유사하게 사용할 수 있으면서도 사용 가능한 모든 CPU의 자원을 활용하여 작업을 병렬화해서 실행합니다.

출처: https://learn.microsoft.com/en-us/dotnet/standard/parallel-programming/

이런 라이브러리를 활용하면, 순차 버전의 반복문을 아주 간단하게 병렬화 시킬 수 있습니다.

// 순차 버전, 한 번에 하나씩
foreach (var item in sourceCollection)
{
 Process(item);
}

// 병렬화, 여러 개를 동시에!
Parallel.ForEach(sourceCollection, item => Process(item));

그외의 언어들

Java

Java는 .NET과 유사하게 OS 스레드와 1:1 대응되는 Thread를 제공하면서도 goroutine과 유사한 경량 스레드인 가상 스레드(Virtual Thread, JDK 21부터)를 제공합니다. Go와의 차이점이라면 각 goroutine은 전용 스택을 가지는데, 가상 스레드는 전용 스택이 없고 캐리어 스레드(OS 스레드)의 스택 위에서 실행됩니다.

Go는 실행할 goroutine을 스위칭할 때, 각 goroutine의 스택은 고정된 상태로 레지스터 몇 개만 교체하면 되기 때문에 작업의 전환이 매우 빠릅니다. 반면에 가상 스레드는 전환이 일어날 때, 캐리어 스레드의 스택에서 가상 스레드의 프레임을 빼내고, 다른 가상 스레드의 프레임으로 교체하죠. 메모리 사용을 더 효율적으로 하는 측면이 있지만, 가상 스레드 전환은 goroutine에 비해 덩치가 큰 작업이 됩니다.

Go는 처음부터 런타임을 직접 설계해서 goroutine에 최적화된 방식으로 만들 수 있었지만, Java는 매우 역사가 오래된 언어입니다. 그래서 기존에 이미 많은 JVM의 동작 방식에 대한 역사가 쌓여있죠. 기존에 동작하는 부분에 거의 영향을 주지 않으면서도 가상 스레드를 도입하기 위해서 이런 구조를 선택했다고 하는데, 꽤나 영리하면서도 현실적인 선택으로 보입니다.

Rust

요즘 Rust가 참 많이 뜨는 거 같아서 겸사겸사 그냥 한 번 조사해봤습니다. 최근엔 MS에서 Rust가 기존의 C++, C#, TypeScript와 함께 1티어 언어로 선정하기도 했죠!

Rust는 앞서 알아본 4가지 언어와는 근본적으로 다른데요, Rust는 표준 라이브러리 수준의 기본 런타임만 제공하기 때문에 다른 언어처럼 async를 사용하려면 tokio 같은 외부 런타임을 사용해야 합니다. C/C++ 같은 네이티브 계열의 언어라서 그런 듯합니다.

그리고 데이터 레이스(race)의 발생이 컴파일러 레벨에서 차단된다고 하는데요, 데이터 레이스는 동기화되지 않은 상태에서 두 스레드가 같은 메모리에 접근하여 읽기와 쓰기를 동시에 하는 경우에 발생합니다. 누가 빨리 하느냐에 따라서 예측하기 힘든 결과가 발생하는 거죠. 이걸 원천 차단하기 위해서 Rust는 다음과 같은 빌림(Borrow) 규칙을 정하고 있습니다.

가변 참조(&mut)는 딱 하나만 존재
불변 참조(&)는 여러 개 존재 가능
하지만 가변 참조와 불변 참조는 동시에 존재할 수 없음.

그러니까 가변 참조를 통해 쓰기만 하든지, 불변 참조를 통해 읽기만 하든지 해야 한다는 거죠. 그러니까 다음 같은 상황은 오류라는 겁니다.

let mut v = vec![1, 2, 3];
let r1 = &v; // 불변 참조
let r2 = &mut v; // 가변 참조 → 컴파일 에러
println!("{}", r1[0]);

이런 규칙이 자연스럽게 멀티 스레드를 사용하는 경우에도 전파됩니다. 스레드 10개가 counter 하나를 같이 올리는 코드를 볼까요?

let mut counter = 0;
std::thread::scope(|s| {
 for _ in 0..10 {
 s.spawn(|| { counter += 1; }); // 클로저마다 counter의 가변 참조(&mut)를 잡음
 }
});

std::thread::scope는 안에서 만든 스레드가 모두 끝날 때까지 기다려주는 스레드 묶음입니다. 그래서 스레드가 바깥의 변수를 빌려 쓸 수 있죠.

각 클로저는 counter를 고쳐야 하니까 counter의 가변 참조를 하나씩 잡습니다. 10개의 스레드가 동시에 살아있으니 가변 참조도 10개가 되죠. 그래서 가변 참조(&mut)는 딱 하나만 존재 규칙에 위배되므로 컴파일 에러입니다.

error[E0499]: cannot borrow `counter` as mutable more than once at a time

참고로 scope 없이 std::thread::spawn을 바로 쓰면 다른 에러가 먼저 나옵니다. spawn으로 만든 스레드는 main 함수보다 오래 살 수도 있어서, 곧 사라질지도 모르는 지역 변수를 빌려주는 것 자체가 금지되기 때문이죠.(E0373) 이 경우에는 move를 붙여서 소유권을 넘겨야 하는데, 그러면 숫자가 스레드마다 복사되어서 각자 자기 복사본만 올리게 됩니다. 공유가 안 되는 거죠!

그래서 데이터에 대한 동기화를 강제하는 타입을 사용합니다.

let counter = Mutex::new(0); // lock()을 통해서만 접근 가능한 타입
std::thread::scope(|s| {
 for _ in 0..10 {
 s.spawn(|| { *counter.lock().unwrap() += 1; });
 }
});

Mutex는 안에 든 값을 lock()을 통해서만 만질 수 있게 해주는 상자입니다. lock()을 잡은 스레드는 한 순간에 하나뿐이니, 가변 참조도 그 순간 하나뿐이죠. 그리고 각 클로저는 counter 자체를 불변 참조(&)로만 빌리기 때문에 빌림 규칙에도 어긋나지 않습니다.

scope 없이 spawn을 쓰는 경우에는 Arc로 감싸서 소유권을 나눠 갖습니다. Arc는 여러 스레드가 같은 값을 함께 소유하게 해주는 참조 카운터입니다.
let counter = Arc::new(Mutex::new(0));
for _ in 0..10 {
 let c = Arc::clone(&counter);
 std::thread::spawn(move || { *c.lock().unwrap() += 1; });
}

그렇기 때문에 타입 수준에서 동기화 실수가 방지되는 측면이 있죠!

그리고 마지막으로 타입마다 스레드의 경계를 넘어서 보낼 수 있는지 여부를 컴파일러가 판단합니다. 스레드 안전한 타입인지(thread-safe)에 따라서 컴파일러가 판단하여(Send/Sync) 그렇지 않은 경우 컴파일 에러를 발생시킵니다.

정리하자면, 빌림(Borrow) 규칙과 Mutex 같이 동기화를 강제하는 타입, 스레드 안전 타입 여부 등을 통해서 데이터 레이스를 원천적으로 막습니다.

참고 자료

분산 시스템 설계(2) - 일관된 해싱

Sat, 12 Sep 2026 07:56:56 +0900

해시 함수는 주어진 입력에 대해서 고정된 범위의 값으로 매핑합니다. 어떤 값이 주어져도 고정된 범위로 매핑해주기 때문에 분산 시스템에서는 이런 해시 알고리즘이 중요하게 사용됩니다. 분산 시스템에서는 들어오는 사용자의 입력을 분산된 시스템 중 어느 인스턴스에 전달해서 처리하게 할지, 그리고 인스턴스가 추가되거나 삭제될 때는 어떻게 할지 등의 문제를 해결해야 하기 때문이죠.

나머지 연산 해시(modulo hash)

가장 간단한 방법은 시스템으로 들어오는 요청을 해시로 변환하고, 그 해시를 인스턴스 개수로 나눈 나머지를 이용하는 방법입니다.

사용자 10명을 서버 3대에 나누는 모습입니다. 각 사용자 ID를 해시한 뒤 3으로 나눈 나머지가 곧 서버 번호가 됩니다.

flowchart LR
subgraph U["사용자 10명: ID를 해시한 뒤 3으로 나눈 나머지"]
direction TB
u1["user-1<br/>hash = 0xc6c289…<br/>% 3 = 0"]
u2["user-2<br/>hash = 0xd92b69…<br/>% 3 = 1"]
u3["user-3<br/>hash = 0x92303a…<br/>% 3 = 1"]
u4["user-4<br/>hash = 0xbeb218…<br/>% 3 = 2"]
u5["user-5<br/>hash = 0x5d652c…<br/>% 3 = 1"]
u6["user-6<br/>hash = 0x724cae…<br/>% 3 = 0"]
u7["user-7<br/>hash = 0x920811…<br/>% 3 = 2"]
u8["user-8<br/>hash = 0x4c485b…<br/>% 3 = 0"]
u9["user-9<br/>hash = 0x14817f…<br/>% 3 = 2"]
u10["user-10<br/>hash = 0xe4abd1…<br/>% 3 = 0"]
end
subgraph S["서버 3대"]
direction TB
a["server-a<br/>index 0 (4명)"]
b["server-b<br/>index 1 (3명)"]
c["server-c<br/>index 2 (3명)"]
end
u1 --> a
u6 --> a
u8 --> a
u10 --> a
u2 --> b
u3 --> b
u5 --> b
u4 --> c
u7 --> c
u9 --> c
classDef sa fill:#ffcccc,stroke:#333
classDef sb fill:#ccffcc,stroke:#333
classDef sc fill:#ccccff,stroke:#333
class a,u1,u6,u8,u10 sa
class b,u2,u3,u5 sb
class c,u4,u7,u9 sc

각 사용자 ID의 해시 값을 서버 개수로 나눈 나머지에 따라 서버와 매핑되고 있습니다. 같은 ID를 해시하면 항상 같은 값이 나오기 때문에 user-1은 몇 번을 물어봐도 server-a입니다.

나머지 연산 해시 구현

그럼 예시 코드를 확인해볼까요? 우선 나머지 연산 해시 관련 코드입니다.

// src/hash.ts
import crypto from "node:crypto";

/**
 * 나머지 연산(mod) 분배 알고리즘
 * 서버 수가 바뀌면 거의 모든 키의 나머지 값이 바뀐다. 그래서 대부분의 키가 이동한다.
 * @param key 유저ID 등의 키
 * @param servers 서버 목록
 * @returns 분배 대상이 되는 서버 이름
 */
export function modHash(key: string, servers: string[]) {
 const index = Number(hash(key) % BigInt(servers.length));

 return servers[index];
}

/**
 * 노드의 기본 crypto 모듈을 사용하여 입력 값을 해시한다.
 * @param input 입력 값
 * @param algorithm 해시 알고리즘
 * @returns 해시 결과
 */
export function hash(input: string, algorithm = "sha256"): bigint {
 // 256비트 해시 생성 -> 64개의 16진수 문자열(64 * 4 = 256)
 const digest = crypto.createHash(algorithm).update(input).digest("hex");

 // 결과로 나온 16진수 문자열을 256비트 숫자로 변환
 // number는 double 형식이므로, 정수의 범위는 -(2⁵³ - 1) ~ (2⁵³ - 1) 이므로 256bit 정수를 정확하게 표현불가.
 // 그래서 BigInt를 사용함. BigInt의 경우 자바스크립트 엔진에서 단일 값에 허용하는 최대 비트 수까지 할당가능.
 // 정수 비교를 위해 BigInt를 썼지만, sha256 해시의 결과는 항상 같은 길이의 문자열이므로 문자열을 그대로 비교해도 같은 결과를 얻을 수 있다!
 return BigInt(`0x${digest}`);
}

hash 함수는 node.js에서 기본으로 제공하는 crypto 모듈을 통해 입력값의 해시를 생성합니다. 해시 알고리즘의 기본 값은 sha256으로 결과값이 항상 256비트로 구성됩니다. 그리고 나머지 연산 해시는 hash함수를 이용해서 특정 사용자의 식별자를 해시로 변환하고, 서버 개수로 나눈 나머지를 인덱스로 사용해서 사용자와 서버를 매핑합니다.

그리고 이어서 사용자 목록과 서버 목록을 받아서 해시 알고리즘을 적용하는 헬퍼 함수와 매핑 결과를 출력하는데 사용될 헬퍼 함수를 정의합니다.

// src/hash.ts

/**
 * 각 키를 대응하는 서버에 라우팅하여 할당
 * @param keys 유저ID 등의 키 목록
 * @param servers 서버 목록
 * @param hashFn 해시 알고리즘(링, 랑데뷰)
 * @returns
 */
export function assign(
 keys: string[],
 servers: string[],
 hashFn: (key: string, servers: string[]) => string): Record<string, string> {
 const result: Record<string, string> = {};

 for (const key of keys) {
 result[key] = hashFn(key, servers);
 }

 return result;
}

/**
 * 각 서버별 분배 결과를 테이블로 출력.
 */
export function printDistribution(result: Record<string, string>) {
 const distribution: Record<string, number> = {};

 for (const server of Object.values(result)) {
 distribution[server] = (distribution[server] ?? 0) + 1;
 }

 console.table(distribution);
}

그리고 마지막으로 사용자와 서버를 선언하고, 매핑을 진행하는 코드를 작성합니다.

// src/distribution.ts
import { assign, modHash, printDistribution } from "./hash.js";

const users = Array.from(
 {length: 10},
 (_, i) => `user-${String(i + 1)}`,
);

// 해시 알고리즘과 각 해시 알고리즘 실행을 위한 hashFn 구성
const algorithms: Record<string, (servers: string[]) => (key: string, servers: string[]) => string> = {
 "mod": () => modHash,
};

// 각 해시 알고리즘 별로 실행하여 결과 확인
for (const [name, makeHashFn] of Object.entries(algorithms)) {
 console.log(`\n===== ${name} =====`);

 console.log("--- 서버 3대 ---");

 const servers = ["server-a", "server-b", "server-c"];

 const before = assign(users, servers, makeHashFn(servers));

 printDistribution(before);
}

사용자 10명과 서버 3대를 선언하고, 나머지 해시 알고리즘을 통해 매핑을 진행하고 결과를 확인하는 순서로 진행됩니다. 결과를 볼까요?

> npx tsx ./src/distribution.ts

===== mod =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-a │ 4 │
│ server-b │ 3 │
│ server-c │ 3 │
└──────────┴────────┘

4:3:3 이라면 얼추 균등하게 요청이 분배되었네요. 유저를 1000명까지 늘려볼까요?

> npx tsx ./src/distribution.ts

===== mod =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-a │ 339 │
│ server-b │ 347 │
│ server-c │ 314 │
└──────────┴────────┘

역시나 비슷한 결과가 나옵니다.

그런데 말입니다…

그러면 여기서 한 가지 의문이 생깁니다. 얼추 비슷한데 그냥 나머지 연산 해시 이거면 다 되는 거 아닌가? 하고 말이죠. 그러면 서버가 추가되거나 삭제될 때도 잘 동작하는지 추가로 확인해 보겠습니다.

우선 src/hash.ts에 다음 함수를 추가합니다.

// src/hash.ts
/**
 * 서버 목록에 변동이 발생하여 사용자를 재분배한 경우, 재분배로 인해 발생한 이동을 확인한다.
 * @param previous 이전 분배 결과
 * @param current 재분배 결과
 * @returns 재분배 결과 발생한 이동
 */
export function compare(previous: Record<string, string>, current: Record<string, string>) {
 let moved = 0;

 for (const key of Object.keys(previous)) {
 if (previous[key] !== current[key]) {
 moved++;
 }
 }

 return moved;
}

그리고 다음과 같이 src/distribution.ts를 수정합니다.

//src/distribution.ts
...

// 각 해시 알고리즘 별로 실행하여 결과 확인
for (const [name, makeHashFn] of Object.entries(algorithms)) {
 console.log(`\n===== ${name} =====`);

 console.log("--- 서버 3대 ---");

 const servers = ["server-a", "server-b", "server-c"];

 const before = assign(users, servers, makeHashFn(servers));

 printDistribution(before);

 console.log("--- server-d 추가 ---");

 servers.push("server-d");

 const after = assign(users, servers, makeHashFn(servers));

 printDistribution(after);

 console.log(`이동된 사용자 수: ${compare(before, after)} / ${users.length}`);
}

서버를 한 대 추가하고 재분배를 진행해서 얼마나 많은 사용자가 재분배로 인해 다른 서버로 이동되었는지 확인하는 코드가 추가되었습니다. 실행해서 결과를 볼까요?

> npx tsx ./src/distribution.ts

===== mod =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-a │ 339 │
│ server-b │ 347 │
│ server-c │ 314 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-d │ 244 │
│ server-b │ 242 │
│ server-c │ 259 │
│ server-a │ 255 │
└──────────┴────────┘
이동된 사용자 수: 756 / 1000

서버가 한 대 추가되어도 사용자의 분배는 거의 1/4에 가깝게 진행됩니다. 하지만, 이동된 사용자 수는 1/4이 아니라 3/4죠!

서버가 상태를 가지지 않는(stateless) 웹 서버라면 굳이 문제될 건 없어 보입니다. nginx도 기본값으로 순차적으로 돌아가며 요청을 분배하는 라운드 로빈(round-robin) 방식을 사용하고, node.js 프로세스를 관리할 때 많이 사용하는 PM2 역시 라운드 로빈을 사용합니다.

그런데 로컬 캐시와 같이 상태를 가지는 연결이라면, 75%의 사용자가 이동되는 문제는 매우 심각한 문제가 아닐까요?

물론 Redis같은 전역 캐시를 사용해도 됩니다. 다만, 대규모 서비스로 갈수록 단순히 Redis만 사용하기 보다는 메모리 기반 로컬 캐시와 Redis를 조합해서 사용하는 경향이 있습니다. 로컬 캐시에서 응답할 수 있다면 Redis와 네트워크 통신에 걸리는 지연시간을 줄일 수 있기 때문이죠. DB가 업데이트 되면, pub/sub등으로 로컬 캐시를 무효화하고 다시 로드하도록 하는 등의 방식을 사용합니다.

링 해시(ring hash)

그래서 등장한 게 일관성 있게 요청을 분배할 수 있도록 해주는 링 해시 알고리즘입니다.

사용자가 매핑될 수 있는 모든 해시 지점을 하나의 링(원)으로 구성한 뒤에, 그 위에 서버 인스턴스를 해시하여 배치합니다.

SHA256을 사용하는 경우 해시 값은 0부터 2²⁵⁶ - 1까지의 아주 큰 숫자인데요, 이후 표시된 도식에서는 해시 값을 0에서 100 사이 눈금으로 줄여서 표시합니다(해시 값 ÷ 2²⁵⁶ × 100). 매핑 가능한 지점들을 하나의 링으로 구성하기 때문에 눈금 100은 다시 0으로 이어집니다.

그러면 링 위에 서버 3대를 우선 배치해 볼까요?

graph LR
zero(("0<br/>(= 100)"))
b["server-b<br/>위치 40.8"]
c["server-c<br/>위치 76.5"]
a["server-a<br/>위치 83.3"]
zero -->|"시계 방향"| b --> c --> a -->|"100을 지나면 다시 0"| zero
style zero fill:#f0f0f0,stroke:#333
style a fill:#ffcccc,stroke:#333
style b fill:#ccffcc,stroke:#333
style c fill:#ccccff,stroke:#333

서버 이름을 해시하면 각 서버는 링 위의 한 점이 됩니다. server-b는 40.8, server-c는 76.5, server-a는 83.3에 놓였습니다.

눈치채신 분도 있겠지만, 각 서버는 1/3 지점에 정확하게 매핑되지 않았습니다. 그렇기 때문에 server-b가 가장 많은 요청을, server-a가 가장 적은 요청을 받게 됩니다. 이걸 어떻게 해결할지 나중에 다시 이야기 하겠습니다!

사용자 A를 서버에 매핑해야 할 때, A를 해시로 변환해서 원 위의 한 점에 놓고 시계 방향으로 가장 가까운 서버를 찾아서 사용자와 서버를 매핑합니다.

링 해시 도식에서는 시작점(0)이 아래쪽에 위치하고 시계 방향으로 이동해서 다시 시작점(100)으로 이동합니다!

graph BT
zero(("0<br/>(= 100)"))
u7(["user-7<br/>3.5"])
u9(["user-9<br/>8.0"])
u8(["user-8<br/>29.7"])
u5(["user-5<br/>36.4"])
b["server-b<br/>40.8"]
u6(["user-6<br/>44.6"])
u3(["user-3<br/>57.1"])
u4(["user-4<br/>74.4"])
c["server-c<br/>76.5"]
u1(["user-1<br/>77.6"])
a["server-a<br/>83.3"]
u2(["user-2<br/>84.8"])
u10(["user-10<br/>89.3"])
zero --> u7 --> u9 --> u8 --> u5 --> b --> u6 --> u3 --> u4 --> c --> u1 --> a --> u2 --> u10 -->|"다시 0으로"| zero
u1 -.->|"시계 방향으로 처음 만나는 서버"| a
subgraph L["범례: 사용자 색 = 매핑된 서버"]
direction LR
la["server-a 담당 1명"]
lb["server-b 담당 6명"]
lc["server-c 담당 3명"]
end
classDef sa fill:#ffcccc,stroke:#333
classDef sb fill:#ccffcc,stroke:#333
classDef sc fill:#ccccff,stroke:#333
class a,la,u1 sa
class b,lb,u2,u5,u7,u8,u9,u10 sb
class c,lc,u3,u4,u6 sc
style zero fill:#f0f0f0,stroke:#333
style u1 stroke-width:3px

user-1을 해시한 값이 77.6이기 때문에 시계 방향으로 처음 만나는 서버는 83.3의 server-a입니다. 같은 규칙으로 10명을 전부 배치하면 server-b 6명, server-c 3명, server-a 1명이 됩니다. 83.3을 지나 0으로 돌아와서 40.8까지 이어지는 긴 구간이 전부 server-b 몫이기 때문이죠.

그럴듯해 보이지만 몇 가지 단점이 있습니다.

링 위에 각 서버가 균등하게 배치되지 않아서 특정 서버에게 더 많은 사용자가 매핑된다.
서버 하나가 종료되어 사라지는 경우, 그 다음 시계 방향에 위치한 서버가 모든 부담을 떠안는다.

그래서 이런 단점을 해소하기 위해서 각 서버 인스턴스의 가상 노드를 N개 더 만들어서 링 위에 배치합니다.

graph LR
subgraph V1["가상 노드 1개: 담당 구간 a 6.8% / b 57.5% / c 35.7%"]
direction BT
z1(("0"))
b0["server-b<br/>40.8"]
c0["server-c<br/>76.5"]
a0["server-a<br/>83.3"]
z1 --> b0 --> c0 --> a0 --> z1
end
subgraph V2["가상 노드 2개: 담당 구간 a 20.1% / b 41.1% / c 38.8%"]
direction BT
z2(("0"))
a1["server-a#1<br/>3.4"]
c1["server-c#1<br/>6.5"]
b2["server-b#0<br/>40.8"]
c2["server-c#0<br/>76.5"]
a2["server-a#0<br/>83.3"]
b1["server-b#1<br/>90.1"]
z2 --> a1 --> c1 --> b2 --> c2 --> a2 --> b1 --> z2
end
V1 ~~~ V2
classDef sa fill:#ffcccc,stroke:#333
classDef sb fill:#ccffcc,stroke:#333
classDef sc fill:#ccccff,stroke:#333
class a0,a1,a2 sa
class b0,b1,b2 sb
class c0,c1,c2 sc
style z1 fill:#f0f0f0,stroke:#333
style z2 fill:#f0f0f0,stroke:#333

도식의 왼쪽은 가상 노드가 1개인 경우, 그러니까 가상노드를 사용하지 않는 경우와 똑같습니다. 오른쪽은 각 서버 별로 가상 노드를 2개씩 배치하는 예시입니다. 각 점들의 배치가 조금 더 촘촘해졌는데요. 가상 노드가 없을 때 가장 큰 문제였던 server-a와 server-b의 구간에 다른 가상 노드가 몇 개 더 배치되면서 분배가 비교적 더 균등해지게 된 거죠.

이렇게 하면 초기 서버 배치의 불평등을 완화할 수 있고, 서버의 추가/삭제에도 비교적 유연하게 대응할 수 있습니다. 그러면 링 알고리즘을 구현해봅시다!

링 해시 구현

다음과 같이 코드를 작성합니다.

// src/ring.ts
import { hash } from "./hash.js";

/**
 * 해시 링 위의 노드 위치
 */
export type RingPoint = {
 point: bigint;
 /**
 * 노드가 소속된 서버
 */
 server: string
};

/**
 * 해시 링(consistent hashing)을 만든다.
 * 서버 이름에 번호를 붙여 해시한 값이 링 위의 점이 되고, 서버 하나가 점을 vnodes개씩 가지도록 한다.
 * 서버 목록이 바뀔 때마다 링을 새로 만들어야 한다.
 * @param servers 서버 목록
 * @param vnodes 서버 하나가 가지는 지점(virtual node) 수. 기본값 100.
 * @returns point 오름차순으로 정렬된 링. ringHash에 넘겨 재사용한다.
 */
export function makeRing(servers: string[], vnodes = 100): RingPoint[] {
 const ring: RingPoint[] = [];

 for (const server of servers) {
 for (let i = 0; i < vnodes; i++) {
 // 가상노드의 개수만큼 해시를 추가
 ring.push({ point: hash(`${server}#${i}`), server });
 }
 }

 // 이진 탐색을 위해 해시 위치를 기준으로 오름차순 정렬
 return ring.sort((a, b) => (a.point < b.point ? -1 : a.point > b.point ? 1 : 0));
}

/**
 * 해시 링(consistent hashing) 분배 알고리즘
 * 키를 해시한 지점에서 시계 방향으로 처음 만나는 서버를 고른다.
 * 서버가 추가되거나 제거되면 그 서버가 차지한 구간의 키만 이동한다.
 * @param key 유저ID 등의 키
 * @param ring makeRing으로 만든 링
 * @returns 분배 대상이 되는 서버 이름
 */
export function ringHash(key: string, ring: RingPoint[]): string {
 // 키를 해시 링 위의 한 점으로 변환
 const keyPoint = hash(key);

 // 이진 탐색을 위한 양쪽 끝 경계. keyPoint보다 크거나 같은 첫 지점을 찾는다.
 let low = 0;
 let high = ring.length;

 // 탐색 구간이 비게 되면 탐색 종료
 while (low < high) {
 // 탐색 중간 지점 계산
 const mid = Math.floor((low + high) / 2)

 // 중간 지점의 값이 keyPoint보다 작으면, mid이전에는 찾는 값이 없으므로 탐색 범위를 mid+1~high로 재설정
 if (ring[mid].point < keyPoint) {
 low = mid + 1;
 } else { // 중간 지점의 값이 keyPoint보다 더 크면, mid이전에 찾는 값이 있을 수도 있으므로, 탐색 범위를 low~mid로 재설정
 high = mid;
 }
 }

 // 마지막 지점보다 큰 keyPoint의 경우 low가 최대 ring.length까지 갈 수 있다.
 // 그런데 ring[ring.length]는 존재하지 않으므로, % 연산으로 처음부터 순환하도록 한다.(wrap-around)
 return ring[low % ring.length].server;
}

makeRing 함수를 통해 가상 노드 개수만큼 각 서버별로 가상노드를 생성하고, 각 가상노드의 해시 값을 링 위에 배치합니다.

그리고 그렇게 만들어진 해시 링을 사용해서 각 사용자의 요청을 시계 방향의 가장 가까운(사용자 요청의 해시 값보다 크거나 같은) 노드에 매핑하는 거죠.

링에 배치된 서버와 매핑하는 방법: 이진 탐색

각 사용자의 요청을 매핑하기 위해서 이진 탐색을 사용하고 있는데요, 이 과정을 좀 더 자세히 알아보겠습니다.

가상 노드 2개짜리 링(지점 6개)에서 user-1(77.6)의 서버를 찾는 과정입니다. 정렬된 배열에서 77.6보다 크거나 같은 첫 지점을 찾습니다. low는 파란 테두리, high는 보라색 점선 테두리, mid는 노란색 칸입니다. high는 마지막 칸 다음, 즉 배열 끝(6)을 가리킬 수 있어서 #6 칸을 하나 더 그렸습니다. 회색은 탐색에서 빠진 칸입니다.

graph TD
subgraph LG["범례"]
direction LR
lg1["low<br/>탐색 범위의 시작 (포함)"] ~~~ lg2["mid<br/>지금 비교하는 칸"] ~~~ lg3["high<br/>탐색 범위의 끝 (미포함)"] ~~~ lg0["&nbsp;<br/>탐색 범위 안의 칸"] ~~~ lg4["&nbsp;<br/>탐색에서 빠진 칸"]
end
subgraph S1["1단계: mid=3의 76.5 < 77.6 이므로 low = mid + 1 = 4"]
direction LR
s1_0["low<br/>#0 server-a<br/>3.4"] ~~~ s1_1["&nbsp;<br/>#1 server-c<br/>6.5"] ~~~ s1_2["&nbsp;<br/>#2 server-b<br/>40.8"] ~~~ s1_3["mid<br/>#3 server-c<br/>76.5"] ~~~ s1_4["&nbsp;<br/>#4 server-a<br/>83.3"] ~~~ s1_5["&nbsp;<br/>#5 server-b<br/>90.1"] ~~~ s1_6["high<br/>#6<br/>(배열 끝)"]
end
subgraph S2["2단계: mid=5의 90.1 ≥ 77.6 이므로 high = mid = 5"]
direction LR
s2_0["&nbsp;<br/>#0 server-a<br/>3.4"] ~~~ s2_1["&nbsp;<br/>#1 server-c<br/>6.5"] ~~~ s2_2["&nbsp;<br/>#2 server-b<br/>40.8"] ~~~ s2_3["&nbsp;<br/>#3 server-c<br/>76.5"] ~~~ s2_4["low<br/>#4 server-a<br/>83.3"] ~~~ s2_5["mid<br/>#5 server-b<br/>90.1"] ~~~ s2_6["high<br/>#6<br/>(배열 끝)"]
end
subgraph S3["3단계: mid=4의 83.3 ≥ 77.6 이므로 high = mid = 4"]
direction LR
s3_0["&nbsp;<br/>#0 server-a<br/>3.4"] ~~~ s3_1["&nbsp;<br/>#1 server-c<br/>6.5"] ~~~ s3_2["&nbsp;<br/>#2 server-b<br/>40.8"] ~~~ s3_3["&nbsp;<br/>#3 server-c<br/>76.5"] ~~~ s3_4["low, mid<br/>#4 server-a<br/>83.3"] ~~~ s3_5["high<br/>#5 server-b<br/>90.1"] ~~~ s3_6["&nbsp;<br/>#6<br/>(배열 끝)"]
end
subgraph S4["종료: low = high = 4 이므로 ring[4]의 server-a 선택"]
direction LR
s4_0["&nbsp;<br/>#0 server-a<br/>3.4"] ~~~ s4_1["&nbsp;<br/>#1 server-c<br/>6.5"] ~~~ s4_2["&nbsp;<br/>#2 server-b<br/>40.8"] ~~~ s4_3["&nbsp;<br/>#3 server-c<br/>76.5"] ~~~ s4_4["low, high<br/>#4 server-a<br/>83.3"] ~~~ s4_5["&nbsp;<br/>#5 server-b<br/>90.1"] ~~~ s4_6["&nbsp;<br/>#6<br/>(배열 끝)"]
end
LG ~~~ S1
S1 --> S2 --> S3 --> S4
classDef out fill:#e0e0e0,stroke:#999,color:#888
classDef low fill:#fff,stroke:#1f6fd6,stroke-width:3px
classDef high fill:#fff,stroke:#8a2be2,stroke-width:3px,stroke-dasharray:6 3
classDef mid fill:#ffffcc,stroke:#333,stroke-width:3px
classDef found fill:#ffcccc,stroke:#333,stroke-width:3px
classDef past fill:#fafafa,stroke:#bbb,stroke-dasharray:4 3,color:#888
class lg1 low
class lg2 mid
class lg3 high
class lg4 out
class s1_0 low
class s1_3 mid
class s1_6 high
class s2_0,s2_1,s2_2,s2_3 out
class s2_4 low
class s2_5 mid
class s2_6 high
class s3_0,s3_1,s3_2,s3_3 out
class s3_4 mid
class s3_5 high
class s3_6 past
class s4_0,s4_1,s4_2,s4_3,s4_5 out
class s4_4 found
class s4_6 past

세 번 비교하고 index 4의 server-a에 도착했습니다. 지점이 600개(서버 6대 × 가상 노드 100개)라도 10번이면 끝납니다. 만약 키가 마지막 지점 90.1보다 크면 low가 6까지 가는데, 6 % 6 = 0이므로 처음 지점인 server-a#1로 돌아갑니다. 이게 코드 마지막 줄의 wrap-around입니다.

링 해시 분배 코드 작성

이제 링 해시를 사용해서 분배를 진행하는 코드를 작성할 차례입니다.

// src/distribution.ts
import { makeRing, ringHash } from "./ring.js";
...

// 해시 알고리즘과 각 해시 알고리즘 실행을 위한 hashFn 구성
const algorithms: Record<string, (servers: string[]) => (key: string, servers: string[]) => string> = {
 "mod": () => modHash,
 "ring hash": (servers) => {
 const ring = makeRing(servers);

 return (key) => ringHash(key, ring);
 }
};

// 각 해시 알고리즘 별로 실행하여 결과 확인
for (const [name, makeHashFn] of Object.entries(algorithms)) {
 console.log(`\n===== ${name} =====`);

 console.log("--- 서버 3대 ---");

 const servers = ["server-a", "server-b", "server-c"];

 const before = assign(users, servers, makeHashFn(servers));

 printDistribution(before);

 console.log("--- server-d 추가 ---");

 servers.push("server-d");

 const after = assign(users, servers, makeHashFn(servers));

 printDistribution(after);

 console.log(`이동된 사용자 수: ${compare(before, after)} / ${users.length}`);
}

링 해시 알고리즘은 분배를 진행하려면 미리 링을 구성해야 합니다. 그래서 링 해시를 진행하기 전에 makeRing 함수를 통해서 링을 먼저 만들고, 그 링을 사용하는 해시 함수를 리턴합니다.

실행 결과를 볼까요?

> npx tsx ./src/distribution.ts

===== mod =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-a │ 339 │
│ server-b │ 347 │
│ server-c │ 314 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-d │ 244 │
│ server-b │ 242 │
│ server-c │ 259 │
│ server-a │ 255 │
└──────────┴────────┘
이동된 사용자 수: 756 / 1000

===== ring hash =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 317 │
│ server-c │ 316 │
│ server-a │ 367 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 215 │
│ server-c │ 268 │
│ server-a │ 280 │
│ server-d │ 237 │
└──────────┴────────┘
이동된 사용자 수: 237 / 1000

링 해시는 나머지 연산 해시 보다 노드 변경에 훨씬 유연하게 대응하는 걸 볼 수 있습니다. 링 위에 새로운 점이 추가되는 거니까, 예전 노드가 더 가까운 요청들은 계속 기존의 노드와 매핑이 되기 때문에 그렇습니다.

앞의 가상 노드 1개짜리 링에 server-d를 넣어 보겠습니다. server-d는 8.4에 놓입니다.

graph BT
zero(("0<br/>(= 100)"))
u7(["user-7<br/>3.5<br/>b → d 이동"])
u9(["user-9<br/>8.0<br/>b → d 이동"])
d["server-d<br/>8.4 (새 서버)"]
u8(["user-8<br/>29.7"])
u5(["user-5<br/>36.4"])
b["server-b<br/>40.8"]
u6(["user-6<br/>44.6"])
u3(["user-3<br/>57.1"])
u4(["user-4<br/>74.4"])
c["server-c<br/>76.5"]
u1(["user-1<br/>77.6"])
a["server-a<br/>83.3"]
u2(["user-2<br/>84.8<br/>b → d 이동"])
u10(["user-10<br/>89.3<br/>b → d 이동"])
zero --> u7 --> u9 --> d --> u8 --> u5 --> b --> u6 --> u3 --> u4 --> c --> u1 --> a --> u2 --> u10 -->|"다시 0으로"| zero
subgraph L["범례: 사용자 색 = 매핑된 서버"]
direction LR
la["server-a 1명"]
lb["server-b 2명"]
lc["server-c 3명"]
ld["server-d 4명 (전부 b에서 이동)"]
end
classDef sa fill:#ffcccc,stroke:#333
classDef sb fill:#ccffcc,stroke:#333
classDef sc fill:#ccccff,stroke:#333
classDef sd fill:#ffdca8,stroke:#e07000,stroke-width:3px
class a,la,u1 sa
class b,lb,u5,u8 sb
class c,lc,u3,u4,u6 sc
class d,ld,u2,u7,u9,u10 sd
style zero fill:#f0f0f0,stroke:#333

server-d가 8.4에 들어오면 83.3에서 8.4까지의 구간이 server-d 몫이 됩니다. 그 구간에 있던 user-2, user-10, user-7, user-9 네 명이 server-b에서 server-d로 옮겨 가고, 나머지 여섯 명은 그대로인 거죠. 위 실행 결과에서 이동된 사용자 수 237과 server-d에 배정된 수 237이 정확히 같은 것도 같은 이유인데요, 새 서버로 가야 할 사용자만 움직이고 나머지는 한 명도 안 움직이는 거죠.

랑데뷰 해시(HRW, Highest Random Weight)

랑데뷰 해시는 링 해시보다 훨씬 간결하면서도 링 해시와 같은 수준으로 요청을 분배합니다. 사용자의 요청이 들어올 때마다 요청에 대해 가장 해시 점수가 높은 서버를 골라서 매핑시킵니다. 링을 미리 만들 필요도 없고, 서버가 추가되거나 삭제되어도 링을 재구성할 필요 없이 각 요청에 대한 각 서버의 해시 점수만 비교하면 됩니다.

user-1을 서버에 매핑하는 과정입니다. 점수는 링 도식과 같은 방식으로 0에서 100 사이 눈금으로 줄여서 표시했습니다(xxHash 값 ÷ 2⁶⁴ × 100).

flowchart LR
k["user-1"]
subgraph S3["서버 3대: 사용자와 서버를 짝지어 점수 계산"]
direction TB
sa["xxHash(user-1:server-a)<br/>= 37.1"]
sb["xxHash(user-1:server-b)<br/>= 85.0"]
sc["xxHash(user-1:server-c)<br/>= 46.8"]
end
subgraph S4["server-d 추가"]
sd["xxHash(user-1:server-d)<br/>= 47.7"]
end
win["server-b"]
k --> sa
k --> sb
k --> sc
k --> sd
sb ==>|"최고 점수"| win
sd -.->|"85.0보다 낮으니 그대로 server-b"| win
style k fill:#ffffcc,stroke:#333
style sa fill:#ffcccc,stroke:#333
style sb fill:#ccffcc,stroke:#333,stroke-width:3px
style sc fill:#ccccff,stroke:#333
style sd fill:#ffdca8,stroke:#333
style win fill:#ccffcc,stroke:#333,stroke-width:3px

user-1은 server-b와 짝지었을 때 점수가 85.0으로 가장 높으니 server-b에 매핑됩니다. server-d가 추가되어도 새 점수 47.7은 85.0보다 낮기 때문에 user-1은 그대로 server-b에 남습니다. 새 서버에 대해 최고 점수를 받는 사용자만 옮겨 가기 때문에, 링 해시처럼 꼭 필요한 만큼만 이동합니다.

랑데뷰 해시 구현

다음과 같이 코드를 작성해볼까요?

// src/hrw.ts
import xxhash_addon from "xxhash-addon";
const { XXHash64 } = xxhash_addon;

/**
 * 고성능 non-cryptographic xxHash를 통한 해시를 진행한다.
 * @param input 입력값
 * @returns 해시결과
 */
export function xxHash(input: string): bigint {
 const digest = XXHash64.hash(Buffer.from(input));

 // 해시 결과(8바이트 Buffer)를 BigInt로 변환. number는 double 형식이고 표현가능한 정수의 범위는 -(2⁵³ - 1) ~ (2⁵³ - 1) 이므로 64비트를 표현 불가.
 // 16진수 문자열을 거치지 않고 Buffer에서 바로 읽는다. 문자열 변환과 파싱 비용을 줄이기 위해서다.
 return digest.readBigUInt64BE(0);
}

/**
 * 랑데뷰(HRW, Highest Random Weight) 분배 알고리즘
 * @param key 유저ID 등의 키
 * @param servers 서버 목록
 * @returns 분배 대상이 되는 서버 이름
 */
export function rendezvousHash(key: string, servers: string[]): string {
 let selected = "";
 let highestScore = -1n;

 for (const server of servers) {
 // 요청에 대한 각 서버별 해시 계산
 const score = xxHash(`${key}:${server}`);

 // 제일 높은 값의 서버를 선택
 if (score > highestScore) {
 highestScore = score;
 selected = server;
 }
 }

 return selected;
}

사실 랑데뷰 해시의 구현 자체는 간단하기 때문에 별다른 설명이 필요 없는 수준입니다. 정말 간결하죠.

빠르고 균등한 비 암호학적 해시

대신에 위 코드에서 주목할 점은 기존의 SHA-256 알고리즘 대신에 xxHash를 사용한다는 점입니다.

들어오는 요청을 분배하기 위한 해시는 암호학적 요소가 필요 없고, 빠르고 균등하게 분배 되는지가 가장 중요합니다.

이 점은 랑데뷰 해시 뿐만 아니라 다른 모든 해시(나머지, 링 해시)에도 해당되는 내용입니다!

예를 들어서 SHA-256 알고리즘은 암호학적 해시입니다. 공격자가 원래의 값을 찾기 어렵도록 하기 위해서 다음과 같은 방어 기법이 들어가 있죠.

Preimage resistance: 해시에서 원래 입력값을 찾기 어렵게 만든다
Collision resistance: 서로 다른 두 입력이 같은 해시값을 갖기 어렵게 해야 한다

그래서 SHA-256은 대략 다음과 같은 과정으로 해시를 만듭니다.

Input
 ↓
Padding
 ↓
512-bit block으로 분할
 ↓
Block 1 ─┐
Block 2 │
Block 3 ├─→ Compression function
... │
Block N ─┘
 ↓
256-bit hash

반면에 xxHash는 암호학적 고려 없이 데이터를 최대한 빠르게 잘 섞어서 좋은 분포를 만들자가 목표입니다. 그래서 CPU 친화적인 연산을 많이 사용해서 빠르게 계산할 수 있도록 대략 다음과 같은 과정을 거칩니다.

입력
 ↓
여러 accumulator
 ↓
ADD / MUL / ROTATE / XOR
 ↓
mix
 ↓
avalanche
 ↓
64-bit output

간단하게 두 해시의 성능을 비교해볼까요?

// src/perf-check.ts
import { hash } from "./hash.js";
import { xxHash } from "./hrw.js";

const users = Array.from(
 {length: 100000},
 (_, i) => `user-${String(i + 1)}`,
);

const ROUNDS = 5;

/**
 * 해시 함수를 사용자 10만 명에 대해 실행하고 걸린 시간을 잰다.
 * 첫 번째 측정은 JIT 예열(warmup)이므로 측정에서 빼고, ROUNDS만큼 돌린 평균을 출력한다.
 */
function bench(name: string, fn: (input: string) => bigint) {
 for (const user of users) {
 fn(user);
 }

 const start = performance.now();

 for (let round = 0; round < ROUNDS; round++) {
 for (const user of users) {
 fn(user);
 }
 }

 const elapsed = (performance.now() - start) / ROUNDS;

 console.log(`${name}: ${elapsed.toFixed(1)}ms`);
}

bench("SHA256", (user) => hash(user, "sha256"));
bench("XXHash64", (user) => xxHash(user));

실행 결과는 다음과 같습니다.

> npx tsx ./src/perf-check.ts
SHA256: 40.2ms
XXHash64: 23.1ms

xxHash가 약 1.7배 빠른 결과를 보여주고 있네요!

user-1 같은 짧은 키는 해시 계산 자체보다 함수 호출과 Buffer 생성 같은 부차적인 시간이 더 많이 소요됩니다. 그래서 두 해시의 차이가 실제보다 작게 보이지만, 입력이 길어질수록 xxHash의 속도 차이는 더 벌어집니다!

랑데뷰 해시 분배 코드 작성

다시 랑데뷰 해시로 돌아와서, 이제 분배를 진행해볼 수 있도록 코드를 작성할 차례입니다.

// src/distribution.ts
import { rendezvousHash } from "./hrw.js";

...

// 해시 알고리즘과 각 해시 알고리즘 실행을 위한 hashFn 구성
const algorithms: Record<string, (servers: string[]) => (key: string, servers: string[]) => string> = {
 "mod": () => modHash,
 "ring hash": (servers) => {
 const ring = makeRing(servers); // 링을 재사용하기 위해서 클로저로 캡쳐한다.

 return (key) => ringHash(key, ring);
 },
 "랑데뷰(HRW)": () => rendezvousHash,
};

실행 결과는 다음과 같습니다.

> npx tsx ./src/distribution.ts

===== mod =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-a │ 339 │
│ server-b │ 347 │
│ server-c │ 314 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-d │ 244 │
│ server-b │ 242 │
│ server-c │ 259 │
│ server-a │ 255 │
└──────────┴────────┘
이동된 사용자 수: 756 / 1000

===== ring hash =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 317 │
│ server-c │ 316 │
│ server-a │ 367 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 215 │
│ server-c │ 268 │
│ server-a │ 280 │
│ server-d │ 237 │
└──────────┴────────┘
이동된 사용자 수: 237 / 1000

===== 랑데뷰(HRW) =====
--- 서버 3대 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 368 │
│ server-c │ 289 │
│ server-a │ 343 │
└──────────┴────────┘
--- server-d 추가 ---
┌──────────┬────────┐
│ (index) │ Values │
├──────────┼────────┤
│ server-b │ 261 │
│ server-c │ 222 │
│ server-a │ 263 │
│ server-d │ 254 │
└──────────┴────────┘
이동된 사용자 수: 254 / 1000

링 해시보다 훨씬 간단하면서도 유사한 결과를 내고 있습니다. 다만, HRW는 노드 개수가 n일 때, O(n)의 복잡도를 가지기 때문에 노드가 수백 개를 넘어가거나 초당 요청 수가 수백만 정도로 매우 많다면 효율이 많이 떨어지는 문제가 있습니다.

구분	나머지 연산(mod)	링 해시	랑데뷰(HRW)
서버 3대 → 4대일 때 이동한 사용자(1000명 중)	756명	237명	254명
사용자 한 명을 배정하는 비용	해시 1번, O(1)	해시 1번 + 이진 탐색, O(log(n·v))	해시 n번, O(n)
미리 만들어 둘 것	없음	정렬된 링(서버가 바뀔 때마다 다시)	없음
메모리	없음	지점 n·v개	없음
부하 균등	좋음	가상 노드 수(v)에 따라 달라짐	좋음
어울리는 상황	상태 없는 서버	서버가 많을 때(수백 대 이상)	서버가 적을 때, 코드가 단순해야 할 때

n은 서버 수, v는 서버당 가상 노드 수입니다.

참고 자료

요즘 개발자를 위한 시스템 설계 수업, 길벗
xxhash-addon

Node.js: --experimental-vm-modules

Sat, 29 Aug 2026 08:00:25 +0900

최근에 클로드 코드의 작업을 지켜보던 중, 눈에 들어오는 커맨드가 있었습니다. 테스트를 실행하는 코드 앞에 NODE_OPTIONS=--experimental-vm-modules 이런 환경변수가 붙어있더군요. 그래서 vm? 노드에 무슨 vm? 하는 궁금증과 함께 찾아보기 시작했습니다. 확인하다 보니… 이게 그렇게 간단한 이야기는 아니었고, 그동안 노드를 계속 쓰면서도 알려고 하지 않았던 부끄러운 과거를 반성하게 되더군요…

--experimental-vm-modules 를 좀 많이 단순화해서 한 마디로 정리하면, “테스트를 위해 CommonJS 시절에 mocking 하던 것처럼 ESM에서도 할 수 있게 해줄게” 정도일까요? 그러니까 이건 모듈에 관련된 내용이고, 모듈을 알아보려면 일단 Javascript의 서버 런타임의 역사를 좀 살펴볼 필요가 있습니다.

Javascript 초창기의 서버 런타임

1994년에 전설적인 Netscape 브라우저가 출시되었습니다. 그 이후에 전세계가 인터넷의 미래를 선점하기 위해서 움직였고, 마이크로소프트 역시 지금은 사라진 인터넷 익스플로러를 1995년 8월에 공개했습니다. 이후 각 회사는 브라우저와 함께 웹 개발 생태계의 주도권을 쥐기 위해 웹 서버 개발 환경을 출시합니다. 넷스케이프에서는 Netscape Enterprise Server와 LiveWire를 마이크로소프트에서는 IIS와 ASP를 1996년에 출시합니다.

LiveWire의 당시 개발자 문서는 현재도 확인할 수 있는데요, 아래 구조에서 볼 수 있듯이 서버에서 html 페이지를 렌더링해서 프론트로 보내주는 형태입니다. 지금 우리가 쓰는 서버 사이드 렌더링(SSR)의 개념인 셈이죠.

출처: https://docs.oracle.com/cd/E19957-01/816-6411-10/jsserv.htm#1028696

그리고 이후에도 Helma(1998), Jaxer(2008) 등 Javascript를 서버에서 구동할 수 있는 런타임이 등장했지만 한 가지 큰 문제가 있었는데요, 초창기 Javascript에는 모듈의 개념이 아예 없었습니다. 어느 정도 규모가 있는 코드를 작성하다보면 필연적으로 코드를 자르고 묶어서 서로 참조하게 하고, 누군가가 만든 코드를 가져와서 쓰기도 하고 해야 합니다. 그런데 이런 개념이 아예 없었기 때문에 각 서버 런타임별로 자기 나름대로의 방법을 추구하고 있었던 셈이죠.

Netscape LiveWire의 좀 더 자세한 내용이 궁금하신 분은 Server-side JavaScript a decade before Node.js with Netscape LiveWire 를 참고하세요!

나는 꿈이 있어요!

이런 상황 속에서 2009년 1월 Kevin Dangoor는 What Server Side JavaScript needs 라는 글에서 다음과 같이 이야기합니다.

JavaScript needs a standard way to include other modules and for those modules to live in discreet namespaces. … There needs to be a way to package up code for deployment and distribution and further to install packages. … To that end, I’ve set up a new ServerJS group in hopes of getting the interested parties talking and maybe even to get us together face-to-face to produce some code and settle on some interfaces. …

Javascript에게 패키지 배포 및 모듈을 다루는 표준방식이 필요하며, 이를 위해서 ServerJS라는 논의 그룹을 시작한다는 내용입니다. 이후 ServerJS는 CommonJS로 이름을 바꿨고 이후 십 수년간 Node.js의 사실상 표준으로 사용됩니다. 지금와서 보면 그 당시에 대단한 꿈이었고, 저 같은 개발자는 그 덕을 많이 봤던 거죠.

하지만 그렇게 간단하지 않았다

하지만 지금, 우리는 결론을 알고 있습니다. ESM이 결국 표준이 되었고, 그동안 CommonJS로 배포된 패키지는 셀 수도 없이 많았죠. 아주 오랜 시간동안 패키지들은 CommonJS와 ESM을 동시에 지원하려고 애썼고, 결국은 ESM만을 지원하는 패키지를 CommonJS에서 사용할 수 있도록 require()ing Synchronous ESM Graphs 기능이 추가되기도 했습니다. 오랜 기간 동안 CommonJS가 사용된 탓에(특히 Node.js가 폭발적으로 성장하던 시절에!) CommonJS를 무시할 수 없게 된 거죠.

CommonJS와 ESM에 대해 알고 싶으신 분들은 CommonJS와 ESM의 차이점 을 참고하세요!

그 시절 우리가 좋아했던 mocking

흉내지빠귀는 곤충이나 다른 새의 울음소리를 흉내낸다고 해서 영어로는 Mockingbird라고 불립니다.

출처: https://simple.wikipedia.org/wiki/Mockingbird

우리가 테스트를 작성하다보면 Mockingbird 같이, 코드의 각 부분이 실제와 동일한 인터페이스를 갖지만 내부 동작은 완전히 다른 무언가를 만들어야 합니다. 예를 들어서 DB에서 뭔가 데이터를 가져오는 코드를 테스트 한다고 생각해보죠.

// user-service.js
const { db } = require('./database.js');
exports.getUser = (id) => db.query('SELECT * FROM users WHERE id = ?', id);

실제 DB에서 데이터를 가져오는 코드를 그대로 테스트에 활용한다면 다음과 같은 문제가 발생합니다.

테스트하는 환경에 실제 DB가 구동되어야 함
DB에 지연/장애 발생시 테스트 시간이 길어지거나 타임아웃 등으로 실패 발생
DB에 데이터를 쓰는 경우, 테스트용 데이터가 섞여들어가는 문제 발생 가능

그래서 다음과 같이 DB 응답을 대체하는 mock 코드를 통해 테스트를 진행합니다.

// user-service.test.js
jest.mock('./database.js', () => ({ db: { query: jest.fn() } }));

const { db } = require('./database.js');
const { getUser } = require('./user-service.js');

beforeEach(() => jest.resetAllMocks());

...

test('id로 유저 한 명을 조회한다', async () => {
 db.query.mockResolvedValue([{ id: 42, name: '홍길동', email: 'a@b.com' }]);

 const rows = await getUser(42);

 expect(rows).toEqual([{ id: 42, name: '홍길동', email: 'a@b.com' }]);
 expect(db.query).toHaveBeenCalledWith('SELECT * FROM users WHERE id = ?', 42);
});

만약 DB에 조회해오는 쿼리나 인덱스 등의 체크도 필요하다면, 메모리에서 동작하는 better-sqlite3나 mongodb-memory-server 등을 사용하기도 합니다.

그런데 뭐가 문제인가요?

앞선 예시 코드를 보시면 알겠지만, require를 사용하고 있습니다. CommonJS죠. CommonJS에서는 mocking이 매우 쉽습니다. 왜 그런지 결론부터 말씀드리면, CommonJS는 여러분의 코드를 함수로 감싸서 실행하는데, 이때 모듈이 로드되는 과정을 임의로 조정할 수 있습니다.

즉, CommonJS에서는 모든 게 다 함수입니다. 우선 이 부분 부터 확인해보죠.

모든 게 다 함수다.

일단 다음 커맨드를 실행해 볼까요?

> node -v
v26.0.0

> node -e "console.log(require('node:module').wrapper)"
Proxy([
 '(function (exports, require, module, __filename, __dirname) { ',
 '\n});'
])

굉장히 간단한 명령과 출력이지만, 저는 이게 좀 이해하기 어려웠습니다. 하나씩 확인해보면,

1. node:module

앞에 node:가 붙으면, 이 모듈은 Node.js에서 기본으로 제공하는(built-in) 모듈이니까 node_modules 뒤지지 마라 뭐 그런 의미입니다. 그리고 module은 말 그대로 Node.js의 모듈 시스템을 가리킵니다. 다음과 같이 실행해보면,

> node -e "console.log(require('node:module'))"
<ref *1> [Function: Module] {
...
}

Module의 생성자 함수가 리턴되는 걸 확인할 수 있죠?

2. .wrapper

말 그대로 코드의 앞과 뒤를 감싸는 wrapper를 의미합니다. 앞선 .wrapper의 출력 결과를 보면,

Proxy([
 '(function (exports, require, module, __filename, __dirname) { ',
 '\n});'
])

배열에 2개의 요소가 있습니다.

‘(function (exports, require, module, __filename, __dirname) { '
‘\n});’

우리가 어떤 코드를 작성하든지, CommonJS는 우리의 코드를 저 두 줄로 감싸서 함수로 실행한다는 거죠. 그러니까,

// greeting.js
const name = 'world';
module.exports = 'hello, ' + name;

이런 코드가 있다면, Node.js 는 이 코드를 다음과 같이 컴파일합니다.

(function (exports, require, module, __filename, __dirname) { const name = 'world';
module.exports = 'hello, ' + name;

});

즉, 다음과 같은 형태인거죠.

┌──────────────────────────────────────────────────────────────┐
│ (function (exports, require, module, __filename, __dirname) {│ ← Node가 추가
├──────────────────────────────────────────────────────────────┤
│ const name = 'world'; │
│ module.exports = 'hello, ' + name; │ ← 내가 작성한 코드
├──────────────────────────────────────────────────────────────┤
│ }); │ ← Node가 추가
└──────────────────────────────────────────────────────────────┘

그래서 이게 다 뭐라는 건가요?

Node.js가 붙여주는 wrapper의 파라미터를 잘 보시면, exports, require, module, __filename, __dirname 등 우리에게 매우 친숙한 이름들입니다. 그러니까 이게 무슨 전역 변수 같은 게 아니라 wrapper를 통해서 파라미터로 주입된 애들이라는 거죠!(저는 처음 알았습니다…)

그래서 require를 제 맘대로 정의하는 것도 가능합니다.

// my-require.js
const fs = require('fs');

function myRequire(filename) {
 // 1. 대상이 되는 파일을 텍스트로 읽어오기
 const yourCode = fs.readFileSync(filename, 'utf8');

 // 2. 앞, 뒤로 wrapper 코드 붙이기
 const wrapped =
 '(function (exports, require, module, __filename, __dirname) {' +
 yourCode +
 '\n})';

 // 3. 실행 가능한 함수로 변환
 const fn = eval(wrapped);

 // 4. 매개변수를 정의하고 호출하기
 const module = { exports: {} };
 // require 파라미터에 myRequire를 전달함!!!!!
 fn(module.exports, myRequire, module, filename, __dirname);

 // 5. module.exports 값을 리턴
 return module.exports;
}

console.log(myRequire('./greeting.js')); // hello, world

그리고 실행하면 다음과 같은 결과를 볼 수 있습니다.

> node my-require.js
hello, world

그러니까, Node.js가 wrapper로 코드를 감싸게 되면, 테스트를 위해서 만든 mock을 대신 로드하는 require를 주입해서 호출 경로를 바꿀 수 있다는 거죠! 그래서 CommonJS 코드는 mock 테스트가 아주 쉽습니다.

여담이지만, 그래서 최상위 레벨의 return이 코드를 종료시키게 됩니다.
console.log("hello, world");
return;
console.log("앞 줄의 return에서 wrapper 함수를 빠져나가므로 출력되지 않습니다!!");

그런데 ESM은… 달라요!

근데 ESM은… 다릅니다. 아까 봤던 코드를 ESM으로 작성하면 이렇습니다.

import { db } from './database.js';
export function getUser(id) { return db.query('...', id); }

import는 함수가 아니라 선언입니다.(require는 함수였죠!) 게다가 import는 코드가 실행되기 전에 어떤 모듈을 로드할지 결정(resolve)됩니다. 위 코드가 실행되는 시점에서는 이미 db가 선언된 모듈로 로드된 상태라는 거죠. 조금 더 자세히 살펴보면 ESM에서 모듈은 다음과 같이 3단계로 로드됩니다.

분석(parse): 코드 실행 전에 import, export 선언을 추출함
연결(link): 모듈간의 참조 관계를 그래프로 구성함
실행(evaluate): 코드가 실행됨

CommonJS처럼 모듈을 중간에 바꿔치기 하려면 2번 연결 단계가 유일한 희망이지만, ESM은 CommonJS처럼 쉬운 방법은 없습니다.

하지만 Jest가 아니라 node:test 를 사용한다면 이런 방법을 고민할 필요가 없습니다. node:test는 vm 모듈을 사용하지 않습니다!

다시 –experimental-vm-modules 이야기

이제 드디어 --experimental-vm-modules 플래그를 이야기할 차례입니다. 참 먼 길을 돌아왔네요… 제가 모르는 게 이렇게 많았다니 저도 슬픕니다.

어쨌거나, 플래그가 뭘하는 건지 다음 커맨드로 확인해보죠.

> node -e "const vm=require('node:vm'); console.log(typeof vm.SourceTextModule)"
undefined

> node --experimental-vm-modules -e "const vm=require('node:vm'); console.log(typeof vm.SourceTextModule)"
function

vm.SourceTextModule이 원래는 없었는데, 플래그를 설정하자 나타났죠? 이 플래그를 설정하면 vm.Module, vm.SourceTextModule, vm.SyntheticModule을 사용할 수 있게 해줍니다.

이 클래스들을 활용하면 앞서 살펴봤던 ESM 모듈의 3단계를 직접 제어할 수 있습니다.

노드 공식 문서에 따르면 vm.Module, vm.SourceTextModule, vm.SyntheticModule 모두 아직까지 Stability: 1 - Experimental 상태입니다. 각 모듈이 추가된 시점을 보면 9.6.0, 12.16.0 등으로 아주 오래전인데 말이죠. 어쩌면 이 기능은 앞으로 사용하지 않는게 더 좋을 거 같은 느낌도 드네요.

ESM의 모듈 임포트를 직접 제어해보자!

앞서 살펴본 vm.SourceTextModule를 이용해서 다음과 같이 코드를 작성해보겠습니다.

// esm-3steps.js
import vm from 'node:vm';

// vm.createContext는 독립적인 코드 실행공간(샌드박스)을 생성합니다.
// 새로 생성된 context에는 console 조차도 없기 때문에 주입해줘야 합니다.
const context = vm.createContext({ console });

// 1단계 - 분석. 코드를 컴파일하면서 import와 export를 추출합니다.
// 아직 코드는 실행되지 않습니다.
const module = new vm.SourceTextModule(
 `export const greeting = 'hello world';`,
 { context, identifier: 'hello.mjs' },
);
console.log(module.status); // 'unlinked'

// 2단계 - 연결. 모든 import, export에서 로드할 모듈을 결정합니다.
// hello.mjs는 다른 모듈을 import하지 않기 때문에, linker는 아무 일도 하지 않습니다.
await module.link(() => { throw new Error('no imports'); });
console.log(module.status); // 'linked'

// 3단계 - 실행. 이제 코드가 실행됩니다.
await module.evaluate();
console.log(module.status); // 'evaluated'

console.log(module.namespace.greeting); // 'hello world'

그리고 플래그를 붙여서 실행합니다.

> node --experimental-vm-modules esm-3steps.js
unlinked
linked
evaluated
hello world
(node:68009) ExperimentalWarning: VM Modules is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

분석 -> 연결 -> 실행의 3단계가 명확하게 드러나죠? 이제 CommonJS 때 처럼 직접 로드하는 방법을 시도해보려고…. 했습니다만. 코드를 보다 보니, 아 이건 그냥 가능하다 정도만 확인하고 넘어가야겠다 싶었습니다. 좀 많이 복잡하기 때문에 직접 이런 코드를 작성하는 일은 없어야겠다는 생각이 들더군요! 혹시 관심있으신 분들은 esm-loader 폴더 안에 있는 파일을 참조하시면 되고요, 실행 결과는 아래와 같습니다.

> node --experimental-vm-modules esm-loadMock.js
{ id: 42, name: '홍길동' }
(node:81468) ExperimentalWarning: VM Modules is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

mock을 사용하지 않는 디자인

ESM 예제를 보고 나니 mocking을 꼭 이렇게까지 해야 하나 싶은 생각이 들었습니다. 꼭 필요한 경우도 있겠죠. 예를 들면,

내가 작성하지 않은 라이브러리가 껴있는 경우
특정 레이어에서 몇 개의 레이어를 그냥 전달만 하는 경우(ex: handler.js -> service.js -> repository.js -> db.js)
코드 실행 전에 import로 인해 실행되는 경우

뭐 이런 경우는 mocking을 하는 게 더 나을 수도 있습니다. 그런데 실제 코드와 테스트 코드에서 서로 다른 뭔가를 주입할 수 있도록 구성한다면 애초에 mocking을 피할 수 있습니다.

우선 아주 간단하게 실제 DB에 접근할 때 사용될 database.js를 작성합니다.

// database.js
// 코드가 실행되기 전에 import로 인해 실행됩니다!
console.log(' [database.js] connecting to postgres://prod...');

export const db = {
 query(sql, id) {
 throw new Error('REAL DATABASE HIT');
 },
};

그리고 db를 넘겨받아서 데이터를 조회할 user-service.js 를 작성하고요,

// user-service.js
// 팩토리 패턴을 사용해서 import를 하나도 선언하지 않습니다.
// db 파라미터에는 실제 DB나 fake DB가 사용될 수 있죠.
export function createUserService({ db }) {
 return {
 getUser(id) {
 return db.query('SELECT * FROM users WHERE id = ?', id);
 },
 };
}

다음으로 실제 db를 통해 사용자 정보를 조회하는 main.js 입니다.

// 실제 코드를 실행하는 진입점입니다.
import { db } from './database.js';
import { createUserService } from './user-service.js';

export const userService = createUserService({ db });

그리고 마지막으로 fake DB를 사용해서 user-service.js를 테스트할 user-service.test.mjs 를 작성합니다.

// user-service.test.mjs
// 실행 방법: node --test
// node:test는 vm 모듈을 사용하지 않기 때문에 --experimental-vm-modules 플래그가 필요 없습니다!

import { test } from 'node:test';
import assert from 'node:assert';

// fake DB를 만드는 함수
function createFakeDb(rows = {}) {
 const calls = [];
 return {
 calls,
 query(sql, id) {
 calls.push({ sql, id });
 return rows[id] ?? null;
 },
 };
}

test('fake DB로 서비스를 생성하기', async () => {
 const { createUserService } = await import('./user-service.js');
 const fakeDb = createFakeDb({ 42: { id: 42, name: '홍길동' } });

 const service = createUserService({ db: fakeDb });
 const user = service.getUser(42);

 assert.deepStrictEqual(user, { id: 42, name: '홍길동' });
 assert.deepStrictEqual(fakeDb.calls, [
 { sql: 'SELECT * FROM users WHERE id = ?', id: 42 },
 ]);
});

test('찾을 수 없는 데이터 테스트', async () => {
 const { createUserService } = await import('./user-service.js');
 const service = createUserService({ db: createFakeDb() });

 assert.strictEqual(service.getUser(999), null);
});

test('db 오류가 전파되는지 확인하는 테스트', async () => {
 const { createUserService } = await import('./user-service.js');
 const service = createUserService({
 db: { query() { throw new Error('connection reset'); } },
 });

 assert.throws(() => service.getUser(42), /connection reset/);
});

fake DB를 만들고 그걸 팩토리 createUserService 함수에 넘겨줘서, userService가 fake DB를 통해 테스트를 진행하도록 구성하고 있습니다. 테스트 실행 결과는 다음과 같습니다.

> node --test
✔ fake DB로 서비스를 생성하기 (1.105083ms)
✔ 찾을 수 없는 데이터 테스트 (0.085625ms)
✔ db 오류가 전파되는지 확인하는 테스트 (0.432792ms)
ℹ tests 3
ℹ suites 0
ℹ pass 3
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 42.566208

mocking 없이도 깔끔하게 테스트를 진행할 수 있죠? 의존성이 강하게 결합되는 부분을 제거하도록 디자인하면 mocking의 필요성 자체를 없앨 수도 있습니다!

정리

이 글의 시작은 한 플래그에 포함된 “vm"이라는 글자 때문이었지만, 조사를 하는 과정에서 예전에 어떤 일이 있었고, 내가 아무 생각없이 오랫동안 쓰던 게 이런 고민을 통해 나왔던 거구나 하고 공부하는 기회가 되었습니다. 역시… 모르는 게 너무 많군요!

참고자료

SIMD를 알아보자(feat. Go)

Wed, 12 Aug 2026 21:30:50 +0900

최근에 Youtube에서 재밌는 영상 하나를 봤습니다. People Are Mad They’re Told to Learn 이라는 영상인데요, 영상의 발단은 Mitchell Hashimoto의 Everyone Should Know SIMD 라는 글이었습니다. 인터넷에서는 그 글에 대한 반발로 “아니 왜 모든 개발자가 이런 걸 꼭 알아야 한다는 말이냐"등과 같은 반응이 있었고, 저 영상에서는 그 글에 대한 반응과 함께 SIMD로 코드를 작성해보는 내용이 있었습니다. 그걸 보고 나니 저도 궁금해졌습니다. SIMD가 뭔데? 왜 이걸 다 알아야 한다는 거지? 그래서 그냥 한번 시작해봤습니다.

Go 환경설정

우선 Go를 통해 SIMD를 테스트할 수 있는 환경을 마련해보겠습니다. 저는 Go를 brew를 통해 설치했었는데요, 2026년 8월 현재 brew를 통해 설치할 수 있는 최신 버전은 1.26.5입니다. 1.26.5버전도 SIMD가 지원되긴 하지만 AMD64 환경에서만 제한적으로 지원되고, 맥(ARM64)에서 SIMD를 활용하려면 1.27rc2를 설치해야 합니다. 기존에 정식으로 설치된 버전과 간섭없이 동작할 수 있고, 나중에 제거할 때도 아무런 간섭없이 제거할 수 있습니다.

1. 래퍼 프로그램 설치

다음 명령으로 아주 작은 래퍼 프로그램을 설치합니다.

> go install golang.org/dl/go1.27rc2@latest

2. `~/go/bin` 을 PATH에 설정하기

> echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
> source ~/.zshrc
> which go1.27rc2
/Users/onlifecoding/go/bin/go1.27rc2

3. 실제 SDK 다운로드

go1.27rc2 download
Downloaded 0.0% ( 2952 / 68280741 bytes) ...
Downloaded 5.6% ( 3833856 / 68280741 bytes) ...
Downloaded 24.7% (16859008 / 68280741 bytes) ...
Downloaded 41.2% (28131120 / 68280741 bytes) ...
Downloaded 58.3% (39828640 / 68280741 bytes) ...
Downloaded 74.9% (51134112 / 68280741 bytes) ...
Downloaded 90.1% (61488688 / 68280741 bytes) ...
Downloaded 100.0% (68280741 / 68280741 bytes)
Unpacking /Users/onlifecoding/sdk/go1.27rc2/go1.27rc2.darwin-arm64.tar.gz ...
Success. You may now run 'go1.27rc2'

4. 버전 확인하기

> go version
go version go1.26.5 darwin/arm64
> go1.27rc2 version
go version go1.27rc2 darwin/arm64
> go1.27rc2 env GOROOT
/Users/onlifecoding/sdk/go1.27rc2

5. SIMD 지원 확인하기

아래 명령을 통해 simd 패키지의 설명이 출력되면 환경 설정이 잘 끝났습니다.

> GOEXPERIMENT=simd go1.27rc2 doc simd | head -40
package simd // import "simd"
...

6. 설정 삭제하기

추후에 설정을 삭제하려면, SDK를 삭제하고 rm -rf ~/sdk/go1.27rc2, 래퍼 프로그램을 삭제하고 rm ~/go/bin/go1.27rc2, PATH 설정을 ~/.zshrc 에서 삭제하면 깔끔하게 제거할 수 있습니다.

테스트용 코드 작성하기

자 이제 일반 코드와 SIMD가 적용된 코드 간의 비교를 위해서 다음과 같이 코드를 작성 해볼겁니다.

simdbench/
├── go.mod
├── kernels.go # 스칼라 커널
├── kernel_simd.go # SIMD 커널 (goexperiment.simd 전용)
├── kernel_stub.go # SIMD 미지원 환경용 대체 커널
└── kernel_test.go # 정확성 테스트 + 벤치마크

1. 폴더와 모듈 생성

우선 폴더와 모듈을 생성합니다.

> mkdir simdbench && cd simdbench
> go mod init simdbench

2. 테스트에 사용할 2개의 연산 커널

이 테스트는 2개의 연산 커널의 기준으로 모든 테스트가 진행됩니다.

2-1. 합 구하기

다음과 같이 float32 배열의 합을 구합니다.

s = x[0] + x[1] + ... + x[n-1]

4 바이트를 읽어들일 때 마다 1개의 연산이 발생하기 때문에 메모리 중심의 연산 커널입니다. 또한 합을 구하기 위해서는 이전 단계의 합이 존재해야 하기 때문에 CPU가 대기해야 하는 구간이 발생합니다.

2-2. 삼차 다항식 계산

다음과 같은 삼차 다항식을 배열의 각 요소에 대해 독립적으로 계산합니다.

out[i] = ((0.5*x[i] + 1.2) * x[i] - 3.1) * x[i] + 0.7

1개의 요소 당 6번의 연산이 발생하는 계산 중심의 연산 커널입니다. 1번 연산 커널(합 구하기)에 비해 바이트당 연산 횟수가 더 많기 때문에 SIMD가 병렬화하기 더 좋은 구조입니다.

3. 커널 구현하기(kernels.go)

다음과 같이 kernels.go 를 작성합니다.

package kernels

func SumScalar(x []float32) float32 {
 var s float32
 for _, v := range x {
 s += v
 }
 return s
}

// 호너의 방법을 사용하여 거듭제곱 계산을 (곱셈, 덧셈)의 조합으로 변환
// 0.5v³ + 1.2v² − 3.1v + 0.7
// = v(0.5v² + 1.2v − 3.1) + 0.7
// = v(v(0.5v + 1.2) − 3.1) + 0.7
// = ((0.5v + 1.2)·v − 3.1)·v + 0.7
func PolyScalar(x, out []float32) {
 // 입력값을 체크한다. 동시에 컴파일러가 prove 과정에서 len(x) <= len(out)임을 확인한다.
 // 그러면 컴파일러는 아래 for 루프 안의 out[i]에 인덱스 접근 가드를 넣지 않는다.
 if len(out) < len(x) {
 panic("PolyScalar: out이 x보다 짧습니다.")
 }
 for i, v := range x {
 out[i] = ((0.5*v+1.2)*v-3.1)*v + 0.7
 }
}

// SumUnrolled4는 독립된 accumulator 4개를 사용한다.
// 각 덧셈이 앞 덧셈의 결과를 기다리지 않는다. 그래서 CPU가 덧셈 4개를 겹쳐 실행한다.
func SumUnrolled4(x []float32) float32 {
 var s0, s1, s2, s3 float32
 n := len(x)
 m := n - n%4 // 동시에 4개의 계산을 진행하니까 4로 나눠떨어지는 구간을 구하기
 i := 0
 for ; i < m; i += 4 {
 s0 += x[i]
 s1 += x[i+1]
 s2 += x[i+2]
 s3 += x[i+3]
 }
 s := s0 + s1 + s2 + s3
 for ; i < n; i++ { // 4로 나눠 남은 나머지 구간을 계산
 s += x[i]
 }
 return s
}

총 3개의 함수가 작성되었는데요. SumScalar, PolyScalar는 앞서 이야기 했던 연산 커널을 그대로 작성한 함수이고, SumUnrolled4 는 추가 설명이 필요합니다.

CPU는 float32를 더하는 작업에 3-4 사이클을 소비합니다. 그렇기 때문에 순차적으로 하나씩 더하는 SumScalar는 매 루프마다 앞선 더하기가 끝나기를 기다리는 비효율이 발생하게 되죠.

float32는 숫자로 저장되지 않으며, 1 부호 비트 + 8 지수 비트 + 23비트의 가수로 묶여있습니다. 그래서 float32 덧셈을 위해 각 피연산자를 계산 가능한 형태로 묶음을 해제(unpack)하는 1사이클과 계산의 1사이클, 계산 결과를 다시 float32의 형태로 재조정하는 데 1사이클이 필요합니다. 이 과정에 CPU 아키텍처에 따라서 3-4 사이클이 필요하다고 합니다.

그래서 앞선 계산을 기다리는 비효율이 발생하지 않도록 CPU가 4개의 계산을 동시에 진행한 뒤, 결과를 합치도록 하는 겁니다. 이런 방식을 ILP(Instruction-Level Parallelism)이라고 합니다.

4. SIMD 커널 구현하기(kernel_simd.go)

//go:build goexperiment.simd

package kernels

import "simd"

func SumSIMDSingle(x []float32) float32 {
 var acc simd.Float32s // accumulator vector. 실행 환경이 지원하는 SIMD lane 수만큼 누적 슬롯을 가진다. 초깃값은 Mac의 경우 [0, 0, 0, 0]
 lanes := acc.Len() // NEON은 4, AVX는 8 또는 16

 i := 0
 for ; i+lanes <= len(x); i += lanes { // lane 수만큼 딱 떨어지는 구간을 동시에 계산
 acc = acc.Add(simd.LoadFloat32s(x[i : i+lanes])) // 주어진 슬라이스에서 lane 수만큼 잘라서 각 lane별로 누적
 }

 var tmp [16]float32 // 스택에 배열을 생성(AVX512의 경우 최대 float32를 16개 담을 수 있으므로 최댓값으로 생성)
 acc.Store(tmp[:lanes]) // 각 lane의 값을 배열에 저장
 var s float32
 for j := 0; j < lanes; j++ { // 모든 lane의 결과 값을 더하기
 s += tmp[j]
 }

 for ; i < len(x); i++ { // lane 수로 딱 떨어지지 않고 남았던 인덱스에 대해 계산
 s += x[i]
 }
 return s
}

func SumSIMDUnrolled4(x []float32) float32 {
 var a0, a1, a2, a3 simd.Float32s // 4개의 accumulator vector를 생성
 lanes := a0.Len() // vector 하나가 담는 lane 수 확인
 step := lanes * 4 // 4개의 accumulator vector -> Mac의 경우 4 * 4 => 16

 i := 0
 for ; i+step <= len(x); i += step { // step 단위로 딱 떨어지는 구간을 계산 (Mac은 한 번에 16개)
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes])) // 각 accumulator vector에 lane 수만큼 끊어서 누적
 a1 = a1.Add(simd.LoadFloat32s(x[i+lanes : i+2*lanes]))
 a2 = a2.Add(simd.LoadFloat32s(x[i+2*lanes : i+3*lanes]))
 a3 = a3.Add(simd.LoadFloat32s(x[i+3*lanes : i+4*lanes]))
 }

 // step만큼 끊고 남은 나머지 중에서 lane 수만큼 끊을 수 있는 구간을 계산
 for ; i+lanes <= len(x); i += lanes {
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes]))
 }

 // (a0+a1)과 (a2+a3)를 먼저 묶어서 안쪽 Add 두 개가 겹쳐 실행되게 한다
 acc := a0.Add(a1).Add(a2.Add(a3))

 var tmp [16]float32 // 스택에 배열을 생성(AVX512의 경우 최대 float32를 16개 담을 수 있으므로 최댓값으로 생성)
 acc.Store(tmp[:lanes])
 var s float32
 for j := 0; j < lanes; j++ {
 s += tmp[j]
 }

 for ; i < len(x); i++ {
 s += x[i]
 }
 return s
}

func SumSIMDUnrolled8(x []float32) float32 {
 var a0, a1, a2, a3, a4, a5, a6, a7 simd.Float32s // 8개의 accumulator vector를 생성
 lanes := a0.Len() // vector 하나가 담는 lane 수 확인
 step := lanes * 8 // 8개의 accumulator vector -> Mac의 경우 4 * 8 => 32

 i := 0
 for ; i+step <= len(x); i += step { // step 단위로 딱 떨어지는 구간을 계산 (Mac은 한 번에 32개)
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes])) // 각 accumulator vector에 lane 수만큼 끊어서 누적
 a1 = a1.Add(simd.LoadFloat32s(x[i+lanes : i+2*lanes]))
 a2 = a2.Add(simd.LoadFloat32s(x[i+2*lanes : i+3*lanes]))
 a3 = a3.Add(simd.LoadFloat32s(x[i+3*lanes : i+4*lanes]))
 a4 = a4.Add(simd.LoadFloat32s(x[i+4*lanes : i+5*lanes]))
 a5 = a5.Add(simd.LoadFloat32s(x[i+5*lanes : i+6*lanes]))
 a6 = a6.Add(simd.LoadFloat32s(x[i+6*lanes : i+7*lanes]))
 a7 = a7.Add(simd.LoadFloat32s(x[i+7*lanes : i+8*lanes]))
 }

 // step만큼 끊고 남은 나머지 중에서 lane 수만큼 끊을 수 있는 구간을 계산
 for ; i+lanes <= len(x); i += lanes {
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes]))
 }

 // (a0+a1) (a2+a3) (a4+a5) (a6+a7)
 acc := a0.Add(a1).Add(a2.Add(a3)).Add(a4.Add(a5).Add(a6.Add(a7)))

 var tmp [16]float32 // 스택에 배열을 생성(AVX512의 경우 최대 float32를 16개 담을 수 있으므로 최댓값으로 생성)
 acc.Store(tmp[:lanes])
 var s float32
 for j := 0; j < lanes; j++ {
 s += tmp[j]
 }

 for ; i < len(x); i++ {
 s += x[i]
 }
 return s
}

// splat은 모든 lane을 v로 채운 vector를 만든다.
// hot loop 밖에서만 호출하므로 이 작은 루프의 비용은 무시해도 된다.
func splat(v float32, lanes int) simd.Float32s {
 b := make([]float32, lanes)
 for i := 0; i < lanes; i++ {
 b[i] = v
 }
 return simd.LoadFloat32s(b[:lanes])
}

// 호너의 방법을 사용하여 거듭제곱 계산을 (곱셈, 덧셈)의 조합으로 변환
// 0.5v³ + 1.2v² − 3.1v + 0.7
// = v(0.5v² + 1.2v − 3.1) + 0.7
// = v(v(0.5v + 1.2) − 3.1) + 0.7
// = ((0.5v + 1.2)·v − 3.1)·v + 0.7
func PolySIMD(x, out []float32) {
 var probe simd.Float32s
 lanes := probe.Len() // lane 수를 확인하는 용도로만 사용

 // 4개의 다항식 계수를 lane 수만큼 펼쳐서 레지스터에 로드(ex: [0.5, 0.5, 0.5, 0.5])
 c3 := splat(0.5, lanes)
 c2 := splat(1.2, lanes)
 c1 := splat(-3.1, lanes)
 c0 := splat(0.7, lanes)

 i := 0
 for ; i+lanes <= len(x); i += lanes {
 v := simd.LoadFloat32s(x[i : i+lanes]) // 레지스터에 lane 수만큼 로드
 r := c3.Mul(v).Add(c2) // c3 * v + c2 => [0.5*v1+1.2, ... , 0.5*v4+1.2]
 r = r.Mul(v).Add(c1)
 r = r.Mul(v).Add(c0)
 r.Store(out[i : i+lanes]) // 출력 슬라이스의 해당되는 인덱스에 결과값을 저장
 }
 for ; i < len(x); i++ { // lane 수만큼 딱 떨어지지 않고 남은 항목에 대해 계산
 v := x[i]
 out[i] = ((0.5*v+1.2)*v-3.1)*v + 0.7
 }
}

처음에 이 코드를 보면 좀 복잡할 수 있습니다. 저는 상당히 복잡하다고 느꼈었거든요… 그럼 한 줄씩 천천히 가보겠습니다.

//go:build goexperiment.simd

첫 줄의 //go:build goexperiment.simd 는 이 코드가 빌드되는 환경에서 goexperiment.simd 태그가 설정되어있다면 이 파일을 포함하고 아니면 제외하라는 의미입니다. 이 파일에는 SIMD를 사용하는 코드가 작성되어있으니, simd 활성화가 되지 않은 환경에서는 아예 제외하라는 의미인거죠. 환경을 설정하는 과정에서 GOEXPERIMENT=simd go1.27rc2 ... 형식으로 설정을 확인했었는데요. GOEXPERIMENT=simd 이 환경변수가 goexperiment.simd 태그를 활성화 하게 됩니다.

그러면 저 환경변수가 없을 때는 어떻게 될까요? kernel_simd.go 가 빌드에 포함되지 않으니까 빌드 오류가 발생하지 않을까요? 맞습니다. 오류가 발생하죠! 그래서 simd 활성화가 되지 않은 환경을 위해 잠시 뒤에 kernel_stub.go 를 추가하게 됩니다. 잠시 뒤에 다시 알아보죠.

import "simd"

다음으로는 simd 패키지를 임포트합니다. 참고로 simd/archsimd 패키지도 있는데요, 그건 1.26 버전에 AMD64 전용으로 추가된 패키지입니다. arm64에서는 1.27이상에서 제공하는 simd 패키지를 써야 하죠.

4-1. SumSIMDSingle 함수

func SumSIMDSingle(x []float32) float32 {
 var acc simd.Float32s // accumulator vector. 실행 환경이 지원하는 SIMD lane 수만큼 누적 슬롯을 가진다. 초깃값은 Mac의 경우 [0, 0, 0, 0]
 lanes := acc.Len() // NEON은 4, AVX는 8 또는 16

 i := 0
 for ; i+lanes <= len(x); i += lanes { // lane 수만큼 딱 떨어지는 구간을 동시에 계산
 acc = acc.Add(simd.LoadFloat32s(x[i : i+lanes])) // 주어진 슬라이스에서 lane 수만큼 잘라서 각 lane별로 누적
 }

 var tmp [16]float32 // 스택에 배열을 생성(AVX512의 경우 최대 float32를 16개 담을 수 있으므로 최댓값으로 생성)
 acc.Store(tmp[:lanes]) // 각 lane의 값을 배열에 저장
 var s float32
 for j := 0; j < lanes; j++ { // 모든 lane의 결과 값을 더하기
 s += tmp[j]
 }

 for ; i < len(x); i++ { // lane 수로 딱 떨어지지 않고 남았던 인덱스에 대해 계산
 s += x[i]
 }
 return s
}

이 글에서 다루는 첫 번째 SIMD 구현입니다! 이 함수에서도, 그리고 이후로도 simd.Float32s 타입이 중점적으로 쓰이기 때문에 별도로 설명을 하고 넘어가겠습니다.

위 코드를 보면, simd.Float32s에 대해서 accumulator vector라고 적어뒀습니다. accumulator는 뭔가 누적해서 담아두는 걸 말하니까 단어의 뜻은 알겠는데 “vector"는 뭘까요?

여기서 vector는 수학 시간에 이야기하던, 크기와 방향을 가진 화살표가 아니라 같은 타입의 숫자 여러 개를 한 줄로 나란히 담은 묶음입니다. CPU에는 이 묶음을 통째로 담는 넓은 레지스터(vector register)가 있고, SIMD 명령 1개는 묶음 전체에 같은 연산을 한 번에 적용합니다. 계란판에 담긴 계란 4개가 같이 이동하고 같이 계산된다고 생각하면 됩니다. 이때 계란판의 칸 하나하나를 lane이라고 부릅니다.

simd.Float32s는 이 vector register 하나를 Go 타입으로 나타낸 것입니다.

NEON(128비트, 맥): [ f32 | f32 | f32 | f32 ] Len() = 4
AVX2(256비트): [ f32 | f32 | f32 | f32 | f32 x 4 ] Len() = 8
AVX-512(512비트): [ f32 x 16 ] Len() = 16

이 타입의 특징은 4가지입니다.

이름에 개수가 없습니다. 하나의 레지스터에 몇 개의 float32가 들어갈지는 하드웨어가 정하기 때문인데요, 그래서 Len()으로 물어봐야 합니다. 맥(NEON)은 4, AVX2는 8, AVX-512는 16입니다. Float32s를 쓰면 같은 코드가 어느 CPU에서든 그 CPU에서 지원하는 레지스터의 크기로 설정됩니다.
슬라이스가 아니라 값입니다. 크기가 고정이라 힙 할당이 없고, 컴파일러가 가능하면 변수를 레지스터에 그대로 둡니다. 루프 내내 메모리를 오가지 않는 것이 SIMD 성능의 핵심입니다.
메서드 하나가 명령 하나입니다. a.Add(b)는 덧셈 4개를 동시에 수행하는 명령 1개입니다. 이때 lane 0은 lane 0끼리, lane 1은 lane 1끼리만 더해지고 lane 사이에는 아무 교류가 없습니다.
zero value는 모든 lane이 0.0입니다. 그래서 var acc simd.Float32s 선언만으로 누적 계산을 시작할 준비가 끝납니다.

지금까지의 내용을 그림 하나로 정리하면 이렇습니다.

이제 simd.Float32s를 이해했기 때문에 이 함수를 이해할 수 있는 준비가 됐습니다! 위 함수가 하는 일은

accumulator vector 준비
lane 수 만큼 x를 잘라서 SIMD로 누적 계산
accumulator vector의 계산 결과를 배열에 저장
배열에 저장된 각 lane의 계산 결과를 합산
lane 수로 나눠서 딱 떨어지지 않고 남은 x의 요소들을 별도로 합산

생각보다 간단하죠? 이 흐름을 애니메이션으로 보면 더 명확합니다. 12개짜리 슬라이스가 4개씩 레지스터로 올라가고, lane마다 부분합이 쌓이고, 마지막에 부분합 4개가 하나로 합쳐집니다.

4-2. SumSIMDUnrolled4 함수

func SumSIMDUnrolled4(x []float32) float32 {
 var a0, a1, a2, a3 simd.Float32s // 4개의 accumulator vector를 생성
 lanes := a0.Len() // vector 하나가 담는 lane 수 확인
 step := lanes * 4 // 4개의 accumulator vector -> Mac의 경우 4 * 4 => 16

 i := 0
 for ; i+step <= len(x); i += step { // step 단위로 딱 떨어지는 구간을 계산 (Mac은 한 번에 16개)
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes])) // 각 accumulator vector에 lane 수만큼 끊어서 누적
 a1 = a1.Add(simd.LoadFloat32s(x[i+lanes : i+2*lanes]))
 a2 = a2.Add(simd.LoadFloat32s(x[i+2*lanes : i+3*lanes]))
 a3 = a3.Add(simd.LoadFloat32s(x[i+3*lanes : i+4*lanes]))
 }

 // step만큼 끊고 남은 나머지 중에서 lane 수만큼 끊을 수 있는 구간을 계산
 for ; i+lanes <= len(x); i += lanes {
 a0 = a0.Add(simd.LoadFloat32s(x[i : i+lanes]))
 }

 // (a0+a1)과 (a2+a3)를 먼저 묶어서 안쪽 Add 두 개가 겹쳐 실행되게 한다
 acc := a0.Add(a1).Add(a2.Add(a3))

 var tmp [16]float32 // 스택에 배열을 생성(AVX512의 경우 최대 float32를 16개 담을 수 있으므로 최댓값으로 생성)
 acc.Store(tmp[:lanes])
 var s float32
 for j := 0; j < lanes; j++ {
 s += tmp[j]
 }

 for ; i < len(x); i++ {
 s += x[i]
 }
 return s
}

SumSIMDSingle로 이미 4개씩 동시에 더하고 있는데, 여기서 더 빨라질 수 있을까요? 있습니다. 사실 SumSIMDSingle에는 SumScalar에서 봤던 비효율이 그대로 남아있거든요.

acc = acc.Add(...) 는 앞선 Add의 결과가 나와야 다음 Add를 시작할 수 있습니다. vector 덧셈도 결국 덧셈이라 3-4 사이클을 소비하는데요, 그래서 매 루프마다 CPU가 앞선 vector 덧셈이 끝나기를 기다리게 됩니다. SumScalar의 대기 문제가 vector 세계에서 똑같이 재현된 거죠.

해법도 이미 알고 있습니다. SumUnrolled4에서 썼던 트릭을 vector에 그대로 적용하는 겁니다. 서로 독립적인 accumulator vector를 4개 만들어서 기다림 없이 겹쳐 실행되게 하는 거죠. 말하자면 SumUnrolled4의 SIMD 버전인 셈입니다.

accumulator 1개: Add ──▶ Add ──▶ Add ──▶ Add ──▶ ... (앞 결과를 기다린다)

accumulator 4개: a0: Add ───▶ Add ───▶ ...
 a1: Add ───▶ Add ───▶ ...
 a2: Add ───▶ Add ───▶ ...
 a3: Add ───▶ Add ───▶ ... (4개의 연산이 기다림 없이 진행된다)

그래서 이 함수의 루프는 한 번에 step(= lanes * 4, 맥에서는 16개)만큼 전진합니다. 연속된 4개 구간을 각자의 accumulator에 나눠 담는 거죠.

한 바퀴 (i = 0, 맥 기준):
x: [ x0~x3 ][ x4~x7 ][ x8~x11 ][ x12~x15 ]
 ↓a0 ↓a1 ↓a2 ↓a3 ← 4개의 Add가 겹쳐서 실행

그리고 SumSIMDSingle에는 없던 루프가 하나 추가됐는데요, 16개 단위로 끊고 남은 나머지 중에서 4개 단위로 끊을 수 있는 구간을 처리하는 중간 단계입니다. 이 구간은 a0에 몰아서 누적합니다. 많아야 3번 도는 루프라서 accumulator 1개로도 충분하거든요.

마지막 합치기에도 눈여겨볼 부분이 있습니다. a0.Add(a1).Add(a2.Add(a3)) 는 (a0+a1)과 (a2+a3)를 먼저 계산하는 균형 트리 모양인데요, 이렇게 하면 안쪽 Add 2개도 서로 독립이라 겹쳐 실행됩니다. 마지막까지 기다림을 줄이는 거죠.

정리하면 이 함수가 하는 일은 다음과 같습니다.

accumulator vector 4개 준비
step(16개) 단위로 x를 잘라서 accumulator 4개에 겹쳐서 누적
남은 구간 중 lane 수만큼 끊을 수 있는 구간은 a0에 누적
accumulator 4개를 균형 트리로 하나로 합치기
이후는 SumSIMDSingle과 동일 (배열에 저장 → lane 합산 → 나머지 합산)

구조가 SumUnrolled4 + SumSIMDSingle 이라는 게 보이시죠? 전체 흐름을 애니메이션으로 보면 이렇습니다. 20개짜리 슬라이스가 한 바퀴에 16개씩 accumulator 4개로 나눠 담기고, 남은 4개는 중간 단계에서 a0에 더해진 뒤, 균형 트리로 하나로 합쳐집니다.

실제로 얼마나 빨라졌는지는 잠시 뒤 벤치마크에서 확인해 보겠습니다.

4-3. SumSIMDUnrolled8 함수

이 함수는 8개의 accumulator vector를 동시에 사용하면 4개보다 얼마나 빨라질까…를 테스트해보기 위해서 만들었습니다.

구조는 Unrolled4와 동일하기 때문에 설명은 생략하겠습니다!

4-4. PolySIMD 함수

마지막으로 두 번째 연산 커널, 삼차 다항식의 SIMD 버전입니다. 그런데 이 함수를 보기 전에 먼저 봐야 할 함수가 하나 있습니다. 바로 splat 함수입니다.

// splat은 모든 lane을 v로 채운 vector를 만든다.
// hot loop 밖에서만 호출하므로 이 작은 루프의 비용은 무시해도 된다.
func splat(v float32, lanes int) simd.Float32s {
 b := make([]float32, lanes)
 for i := 0; i < lanes; i++ {
 b[i] = v
 }
 return simd.LoadFloat32s(b[:lanes])
}

왜 이런 함수가 필요할까요? 다항식 계산에는 0.5, 1.2 같은 상수 계수가 등장하는데요, vector의 Mul과 Add는 양쪽 모두 vector여야 합니다. 계란판과 계란 1개를 곱할 수는 없는 거죠. 그래서 상수 하나를 모든 lane에 복사해서 [0.5, 0.5, 0.5, 0.5] 같은 vector로 만들어야 하는데, 이 작업을 하는 함수가 splat입니다.

splat은 “철퍼덕 퍼뜨린다"는 뜻으로 SIMD 관련해서 자주 쓰인다고 합니다. broadcast라고도 한다네요.

슬라이스를 만들고 작은 루프를 돌긴 하지만, 잠시 뒤에 보듯 hot loop(빡세게 도는 루프) 밖에서 계수당 1번씩만 호출되기 때문에 무시해도 됩니다. splat이 하는 일을 그림으로 보면 이렇습니다.

// 호너의 방법을 사용하여 거듭제곱 계산을 (곱셈, 덧셈)의 조합으로 변환
// 0.5v³ + 1.2v² − 3.1v + 0.7
// = v(0.5v² + 1.2v − 3.1) + 0.7
// = v(v(0.5v + 1.2) − 3.1) + 0.7
// = ((0.5v + 1.2)·v − 3.1)·v + 0.7
func PolySIMD(x, out []float32) {
 var probe simd.Float32s
 lanes := probe.Len() // lane 수를 확인하는 용도로만 사용

 // 4개의 다항식 계수를 lane 수만큼 펼쳐서 레지스터에 로드(ex: [0.5, 0.5, 0.5, 0.5])
 c3 := splat(0.5, lanes)
 c2 := splat(1.2, lanes)
 c1 := splat(-3.1, lanes)
 c0 := splat(0.7, lanes)

 i := 0
 for ; i+lanes <= len(x); i += lanes {
 v := simd.LoadFloat32s(x[i : i+lanes]) // 레지스터에 lane 수만큼 로드
 r := c3.Mul(v).Add(c2) // c3 * v + c2 => [0.5*v1+1.2, ... , 0.5*v4+1.2]
 r = r.Mul(v).Add(c1)
 r = r.Mul(v).Add(c0)
 r.Store(out[i : i+lanes]) // 출력 슬라이스의 해당되는 인덱스에 결과값을 저장
 }
 for ; i < len(x); i++ { // lane 수만큼 딱 떨어지지 않고 남은 항목에 대해 계산
 v := x[i]
 out[i] = ((0.5*v+1.2)*v-3.1)*v + 0.7
 }
}

함수 위의 주석은 PolyScalar에서 봤던 호너의 방법 그대로입니다. 거듭제곱 없이 (곱하고 더하기) 3단계로 삼차 다항식을 계산하는 거죠. 이 3단계가 SIMD와 만나면 각 단계가 lane 4개를 동시에 처리하게 됩니다.

코드를 위에서부터 따라가 보겠습니다.

먼저 probe는 계산에는 전혀 쓰이지 않는 변수입니다. Len()을 물어보는 용도로만 존재하죠. 그 다음 계수 4개를 splat으로 미리 vector로 펼쳐 둡니다. 루프 밖에서 딱 1번씩만 호출되고, 루프 안에서는 이미 레지스터에 준비된 상수 vector를 가져다 쓰기만 하면 됩니다.

메인 루프는 이렇게 한 번씩 돌아갑니다.

한 바퀴 (맥 기준):
v: [ v0 | v1 | v2 | v3 ] ← x[i:i+4]를 로드
1단계: r = c3·v + c2 (lane 4개 동시)
2단계: r = r·v + c1
3단계: r = r·v + c0
Store: [ f(v0) | f(v1) | f(v2) | f(v3) ] → out[i:i+4]에 기록

lane 0은 v0만으로, lane 1은 v1만으로 자기 다항식을 계산합니다. Add에서 봤던 것과 똑같이 lane 사이에는 아무 교류가 없는 거죠.

그런데 Sum 함수들과 비교해보면 구조가 눈에 띄게 다릅니다. 3가지가 없거든요.

accumulator가 없습니다. v와 r은 매번 새로 만들어지고 해당 반복이 끝나면 사라집니다. 각 반복 사이에 이어지는 값이 없는 거죠.
horizontal reduction이 없습니다. 결과를 Store로 out에 바로 내려쓰면 끝입니다. lane끼리 합칠 일이 없으니까요.
unrolled 버전이 없습니다. 4-2에서 봤던 대기 문제는 이전 계산의 결과를 기다릴 때 생기는데, 이 루프는 각 반복 사이에 의존성이 없습니다. 그래서 accumulator를 늘리지 않아도 CPU가 알아서 여러 반복을 겹쳐 실행합니다.

그러고 나면 마지막으로 동일한 계산식으로 나머지 요소들을 계산합니다.

전체 흐름을 애니메이션으로 보면 이렇습니다. 미리 준비된 계수 vector 4개 아래로, 4개씩 로드 → 호너 3단계 → out에 기록이 반복됩니다. 각 단계에서 사용되는 계수가 주황색으로 표시됩니다.

정리하면 이 함수가 하는 일은 다음과 같습니다.

계수 4개를 splat으로 vector화 (루프 밖에서 1번)
lane 수만큼 로드해서 호너의 방법 3단계로 계산
결과를 out에 바로 저장
남은 원소는 같은 모양의 스칼라 코드로 계산

Sum보다 오히려 단순하죠? 이제 SIMD 커널은 모두 준비되었습니다.

5. 대체 커널 구현하기(kernel_stub.go)

4번 섹션 초반에 다시 돌아온다고 이야기 했던 바로 그 부분입니다. GOEXPERIMENT=simd 없이 빌드하면 kernel_simd.go가 통째로 빠지면서 SumSIMDSingle 같은 함수들이 존재하지 않게 되고, 이 함수들을 부르는 코드는 전부 컴파일 오류가 난다고 했었죠. 그 구멍을 메우는 파일이 kernel_stub.go입니다.

//go:build !goexperiment.simd

package kernels

func SumSIMDUnrolled8(x []float32) float32 { return SumUnrolled4(x) }
func SumSIMDUnrolled4(x []float32) float32 { return SumUnrolled4(x) }
func SumSIMDSingle(x []float32) float32 { return SumUnrolled4(x) }
func PolySIMD(x, out []float32) { PolyScalar(x, out) }

첫 줄의 build tag를 보면 !goexperiment.simd, kernel_simd.go와 정확히 반대 조건입니다. 그래서 어떤 환경에서 빌드하든 두 파일 중 정확히 하나만 빌드에 포함됩니다.

GOEXPERIMENT=simd 있음: kernel_simd.go ✓ kernel_stub.go ✗ → 진짜 SIMD
GOEXPERIMENT=simd 없음: kernel_simd.go ✗ kernel_stub.go ✓ → 스칼라 fallback

내용은 아주 단순합니다. SIMD 함수들과 같은 이름의 함수를 선언하고, 몸통에서는 우리가 가진 가장 빠른 스칼라 버전(SumUnrolled4, PolyScalar)을 그대로 호출합니다. 덕분에 SIMD를 지원하지 않는 환경에서도 컴파일이 항상 성공하고, 호출하는 쪽은 아무것도 바꿀 필요가 없죠.

한 가지 조심할 점이 있는데요, 이 파일 덕분에 GOEXPERIMENT=simd를 빼먹어도 아무 오류 없이 잘 돌아갑니다. “SIMD가 생각보다 안 빠른데?” 싶으면 환경변수부터 확인해보세요!

6. 테스트 작성하기(kernel_test.go)

커널이 다 모였으니 이제 두 가지를 확인해야 합니다. 정답을 내는가(test), 그리고 얼마나 빠른가(benchmark). 순서는 아무래도 정확성이 우선이겠죠?

package kernels

import (
 "fmt"
 "math"
 "math/rand/v2"
 "testing"
)

func data(n int) []float32 {
 x := make([]float32, n)
 for i := range x {
 x[i] = rand.Float32()
 }
 return x
}

// 정확성 우선. 허용 오차를 두는 이유: SIMD는 스칼라와 다른 순서로 더하므로
// 완전히 같은 값을 기대하는 검증은 잘못된 검증이다.
func TestSumImplsMatchScalar(t *testing.T) {
 impls := []struct {
 name string
 fn func([]float32) float32
 }{
 {"unrolled4", SumUnrolled4},
 {"simd-single", SumSIMDSingle},
 {"simd-unrolled4", SumSIMDUnrolled4},
 {"simd-unrolled8", SumSIMDUnrolled8},
 }
 // 모든 분기를 지나도록 길이를 고른다.
 // 32의 배수는 8-vector 본 루프만, 그 사이 값은 중간 단계와 스칼라 tail을 지난다.
 // 0과 1은 본 루프에 한 번도 들어가지 않는 극단값이다.
 for _, n := range []int{0, 1, 3, 4, 5, 7, 8, 15, 16, 17, 31, 32, 33, 63, 64, 65, 1000, 10_037} {
 x := data(n)
 want := SumScalar(x)
 for _, impl := range impls {
 t.Run(fmt.Sprintf("%s/n=%d", impl.name, n), func(t *testing.T) {
 got := impl.fn(x)
 // 상대 오차 1%에 절대 오차 1e-6을 더한다. 합이 0에 가까운 극단값 대비.
 if math.Abs(float64(want-got)) > 1e-2*math.Abs(float64(want))+1e-6 {
 t.Errorf("scalar=%v got=%v", want, got)
 }
 })
 }
 }
}

func BenchmarkSum(b *testing.B) {
 for _, n := range []int{1024, 65536, 1 << 20} {
 x := data(n)
 for _, impl := range []struct {
 name string
 fn func([]float32) float32
 }{
 {"scalar", SumScalar},
 {"unrolled4", SumUnrolled4},
 {"simd-single", SumSIMDSingle},
 {"simd-unrolled4", SumSIMDUnrolled4},
 {"simd-unrolled8", SumSIMDUnrolled8},
 } {
 b.Run(fmt.Sprintf("%s/n=%d", impl.name, n), func(b *testing.B) {
 b.SetBytes(int64(n * 4)) // → MB/s in the output
 for b.Loop() { // Go 1.24+: keeps the call alive
 impl.fn(x)
 }
 })
 }
 }
}

func BenchmarkPoly(b *testing.B) {
 for _, n := range []int{1024, 65536, 1 << 20} {
 x, out := data(n), make([]float32, n)
 b.Run(fmt.Sprintf("scalar/n=%d", n), func(b *testing.B) {
 b.SetBytes(int64(n * 4))
 for b.Loop() {
 PolyScalar(x, out)
 }
 })
 b.Run(fmt.Sprintf("simd/n=%d", n), func(b *testing.B) {
 b.SetBytes(int64(n * 4))
 for b.Loop() {
 PolySIMD(x, out)
 }
 })
 }
}

data 함수는 랜덤 float32 슬라이스를 만드는 도우미입니다. 테스트와 벤치마크가 같이 씁니다.

TestSumImplsMatchScalar는 Sum 구현 4개를 전부 SumScalar와 비교하는 테스트입니다. 가장 단순한 SumScalar를 정답지로 삼는 거죠. 눈여겨볼 부분이 2가지 있습니다.

다양한 길이의 데이터를 사용합니다. 0, 1, 17, 33 같은 값이 섞여 있는 이유는 모든 분기를 지나가게 만들기 위해서입니다. 32의 배수는 Unrolled8의 본 루프만 지나가고, 어중간한 값은 중간 단계와 스칼라 tail까지 지나갑니다. 0과 1은 vector 루프에 한 번도 못 들어가는 극단값이고요.
완전히 같은 값이 아니라 허용 오차로 비교합니다. float 덧셈은 더하는 순서가 바뀌면 마지막 자리가 조금 달라질 수 있습니다(결합법칙이 성립하지 않습니다). SIMD는 스칼라와 더하는 순서가 다르니까 == 비교는 잘못된 검증인 거죠. 그래서 상대 오차 1%에, 합이 0에 가까운 경우를 대비한 절대 오차 1e-6(0.000001)을 더해서 비교합니다.

BenchmarkSum은 구현 5개 × 크기 3개 = 15개의 서브벤치마크를 만듭니다. 크기 3개는 cache에 쏙 들어가는 1024부터 cache를 벗어나는 100만 개까지, 메모리 계층이 달라지는 구간을 골랐습니다.

b.Run에 붙인 이름이 결과에 BenchmarkSum/scalar/n=1024 형태로 그대로 나타납니다.
b.SetBytes(n*4)는 1번 호출이 n×4 바이트를 처리한다고 알려주는 겁니다. 이 덕분에 결과에 MB/s 컬럼이 붙어서 크기가 다른 벤치마크끼리도 처리량으로 비교할 수 있습니다.
for b.Loop()는 Go 1.24에 추가된 벤치마크 루프입니다. 정해진 시간(기본 1초)이 찰 때까지 알아서 반복하고, 반환값을 안 쓰더라도 컴파일러가 호출 자체를 없애버리지 않도록 지켜줍니다.

BenchmarkPoly도 같은 패턴입니다. out 슬라이스를 벤치마크 루프 밖에서 만들어 재사용하기 때문에 측정값에 메모리 할당 비용이 섞이지 않습니다.

이제 정말로 돌려볼 시간입니다!

테스트와 벤치마크 돌려보기

먼저 테스트를 돌려볼까요?

> GOEXPERIMENT=simd go1.27rc2 test -run=Test -v ./...
=== RUN TestSumImplsMatchScalar
=== RUN TestSumImplsMatchScalar/unrolled4/n=0
=== RUN TestSumImplsMatchScalar/simd-single/n=0
=== RUN TestSumImplsMatchScalar/simd-unrolled4/n=0
=== RUN TestSumImplsMatchScalar/simd-unrolled8/n=0
=== RUN TestSumImplsMatchScalar/unrolled4/n=1
=== RUN TestSumImplsMatchScalar/simd-single/n=1
=== RUN TestSumImplsMatchScalar/simd-unrolled4/n=1
=== RUN TestSumImplsMatchScalar/simd-unrolled8/n=1
=== RUN TestSumImplsMatchScalar/unrolled4/n=3
=== RUN TestSumImplsMatchScalar/simd-single/n=3
=== RUN TestSumImplsMatchScalar/simd-unrolled4/n=3
=== RUN TestSumImplsMatchScalar/simd-unrolled8/n=3
...
=== RUN TestSumImplsMatchScalar/unrolled4/n=10037
=== RUN TestSumImplsMatchScalar/simd-single/n=10037
=== RUN TestSumImplsMatchScalar/simd-unrolled4/n=10037
=== RUN TestSumImplsMatchScalar/simd-unrolled8/n=10037
--- PASS: TestSumImplsMatchScalar (0.00s)
 --- PASS: TestSumImplsMatchScalar/unrolled4/n=0 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-single/n=0 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled4/n=0 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled8/n=0 (0.00s)
 --- PASS: TestSumImplsMatchScalar/unrolled4/n=1 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-single/n=1 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled4/n=1 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled8/n=1 (0.00s)
 --- PASS: TestSumImplsMatchScalar/unrolled4/n=3 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-single/n=3 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled4/n=3 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled8/n=3 (0.00s)
 ...
 --- PASS: TestSumImplsMatchScalar/unrolled4/n=10037 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-single/n=10037 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled4/n=10037 (0.00s)
 --- PASS: TestSumImplsMatchScalar/simd-unrolled8/n=10037 (0.00s)
PASS
ok simdbench (cached)

다양한 경우의 수에 대해서 모든 테스트가 통과하는 걸 볼 수 있습니다. 코드가 정확한 걸 확인했으니 이제 벤치마크를 돌려봅시다!

> GOEXPERIMENT=simd go1.27rc2 test -bench=. -benchmem ./...
goos: darwin
goarch: arm64
pkg: simdbench
cpu: Apple M5 Pro
BenchmarkSum/scalar/n=1024-18 2244930 532.5 ns/op 7691.73 MB/s 0 B/op 0 allocs/op
BenchmarkSum/unrolled4/n=1024-18 4383312 273.3 ns/op 14985.48 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-single/n=1024-18 8875933 134.0 ns/op 30566.12 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled4/n=1024-18 19148451 62.21 ns/op 65842.86 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled8/n=1024-18 20095088 59.71 ns/op 68592.91 MB/s 0 B/op 0 allocs/op
BenchmarkSum/scalar/n=65536-18 31131 38428 ns/op 6821.65 MB/s 0 B/op 0 allocs/op
BenchmarkSum/unrolled4/n=65536-18 62958 19042 ns/op 13766.93 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-single/n=65536-18 122510 9654 ns/op 27153.36 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled4/n=65536-18 318691 3733 ns/op 70220.68 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled8/n=65536-18 332295 3638 ns/op 72056.81 MB/s 0 B/op 0 allocs/op
BenchmarkSum/scalar/n=1048576-18 1942 613160 ns/op 6840.47 MB/s 0 B/op 0 allocs/op
BenchmarkSum/unrolled4/n=1048576-18 3706 308846 ns/op 13580.58 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-single/n=1048576-18 7534 159293 ns/op 26330.67 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled4/n=1048576-18 19327 61679 ns/op 68001.61 MB/s 0 B/op 0 allocs/op
BenchmarkSum/simd-unrolled8/n=1048576-18 20790 57774 ns/op 72597.91 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/scalar/n=1024-18 3528297 340.6 ns/op 12024.97 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/simd/n=1024-18 6932178 172.9 ns/op 23692.89 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/scalar/n=65536-18 55312 21780 ns/op 12036.22 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/simd/n=65536-18 113785 10453 ns/op 25077.27 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/scalar/n=1048576-18 3398 349927 ns/op 11986.24 MB/s 0 B/op 0 allocs/op
BenchmarkPoly/simd/n=1048576-18 7154 168198 ns/op 24936.76 MB/s 0 B/op 0 allocs/op
PASS
ok simdbench 25.564s

결과 한 줄 해부하기

처음 보면 숫자가 잔뜩이라 어지러운데요, 한 줄만 잘라서 보면 구조가 단순합니다.

BenchmarkSum/scalar/n=1024-18 2244930 532.5 ns/op 7691.73 MB/s 0 B/op 0 allocs/op
└──────────┬────────────┘└┬┘ └──┬──┘ └────┬────┘ └─────┬────┘ └─┬─┘ └────┬─────┘
 함수/서브벤치마크 이름 ① ② ③ ④ ⑤ ⑤

이름: BenchmarkSum 함수 아래에 b.Run으로 만든 서브벤치마크 이름이 그대로 붙습니다.
① -18: GOMAXPROCS 값입니다. 이 벤치마크를 실행 중인 맥의 CPU 코어가 18개라는 표시입니다.
② 반복 횟수: 측정 시간 동안 함수를 몇 번 호출했는지 센 값입니다. 설정값이 아니라 결과물인 거죠. b.Loop가 약 1.2초 동안 돌 수 있는 만큼 돌고 멈춘 겁니다. 실제로 2,244,930 × 532.5ns ≈ 1.2초가 나옵니다.
③ ns/op: 호출 1번에 걸린 시간인데요, 사실 이 부분 말고는 다 사족에 불과합니다!
④ MB/s: 초당 처리한 데이터 양입니다. b.SetBytes를 호출했기 때문에 붙는 컬럼이고, 크기가 다른 벤치마크끼리 비교할 때는 이 컬럼이 제일 편합니다.
⑤ B/op, allocs/op: -benchmem 옵션이 붙여주는 컬럼입니다. 호출 1번당 힙 할당량인데요, 전부 0인 이유는 커널들이 var tmp [16]float32처럼 스택 배열만 쓰기 때문입니다. 여기 0이 아닌 값이 보이면 측정에 할당 비용이 섞이고 있다는 신호입니다.

반복 횟수를 ops/sec로 읽으면 안 됩니다. 측정 창이 정확히 1초가 아니거든요. 속도 정보는 ns/op와 MB/s에 있고, 반복 횟수는 “몇 번의 호출을 바탕으로 ns/op와 MB/s를 도출했나"를 뜻합니다.

이렇게 읽고 나면 n=1024의 Sum 결과에서 속도가 개선되는 경향이 보입니다. 532 → 273 → 134 → 62 → 60 ns로, 단계마다 절반씩 줄어들다가 마지막에 멈칫하죠. 그런데 이 표는 각 벤치마크를 1번씩만 잰 겁니다. 1번의 측정은 동전 던지기 1번과 같아서, CPU 발열이나 백그라운드 작업에 따라 몇 %씩 쉽게 흔들립니다. 마지막에 멈칫 한게 진짜인지 아니면 뭔가가 개입해서 그런지는 명확하지 않은 거죠.

10번 재서 통계로 판정하기

그래서 제대로 잴 때는 -count=10으로 10번 반복하고, 결과를 파일로 저장합니다.

> GOEXPERIMENT=simd go1.27rc2 test -bench=. -count=10 ./... > result.txt

result.txt를 열어보면 같은 이름이 10줄씩, 조금씩 다른 숫자로 반복됩니다.

goos: darwin
goarch: arm64
pkg: simdbench
cpu: Apple M5 Pro
BenchmarkSum/scalar/n=1024-18 2344214 503.0 ns/op 8142.36 MB/s
BenchmarkSum/scalar/n=1024-18 2438886 492.0 ns/op 8324.60 MB/s
BenchmarkSum/scalar/n=1024-18 2422869 493.4 ns/op 8300.86 MB/s
BenchmarkSum/scalar/n=1024-18 2431774 493.6 ns/op 8298.66 MB/s
BenchmarkSum/scalar/n=1024-18 2439853 492.7 ns/op 8314.17 MB/s
...(이하 200여 줄 생략)...

벤치마크를 10번씩 실행하면 몇가지 잡음이 있더라도 분포를 통해 경향을 비교적 정확하게 파악할 수 있습니다.

결과가 말해주는 것

10개 표본의 중앙값으로 n=1024의 벤치 결과를 그려보면 이렇습니다.

scalar 492.7 ns ████ 8.3 GB/s
unrolled4 254.1 ns ████████ 16.1 GB/s ×1.94
simd-single 126.3 ns ████████████████ 32.4 GB/s ×2.01
simd-unrolled4 58.4 ns ███████████████████████████████ 70.2 GB/s ×2.16
simd-unrolled8 56.7 ns ████████████████████████████████ 72.2 GB/s ×1.03

각 단계가 병목을 하나씩 제거하면서 약 2배씩 빨라졌습니다.

단계	제거한 병목
scalar → unrolled4	덧셈 대기 사슬. 독립 accumulator 4개로 덧셈을 겹쳐 실행
unrolled4 → simd-single	명령 1개가 float32 1개만 처리하던 한계. lane 4개를 동시에 계산
simd-single → simd-unrolled4	vector 덧셈의 대기 사슬. accumulator vector 4개로 다시 겹침
simd-unrolled4 → simd-unrolled8	남은 병목이 거의 없음. 그래서 3~4%에 그침 (아래에서 설명)

크기별 처리량(GB/s, 중앙값)을 보면 또 하나 재미있는 점이 있습니다.

구현	n=1024	n=65536	n=1M	scalar 대비 (n=1M)
scalar	8.3	7.3	7.3	×1.0
unrolled4	16.1	14.6	14.4	×2.0
simd-single	32.4	28.3	28.2	×3.9
simd-unrolled4	70.2	71.7	70.9	×9.7
simd-unrolled8	72.2	74.4	73.9	×10.1

크기가 100만 개로 커져도(cache를 완전히 벗어나도) 처리량이 거의 그대로입니다. 병목이 memory가 아니라 계산 쪽에 있다는 뜻이죠. memory 대역폭이 한계였다면 n=1M에서 그래프가 뚝 꺾였을 겁니다.

그러면 4개 → 8개 unroll이 정말 이득이 있긴 한 걸까요? 이럴 때 쓰는 도구가 benchstat입니다. unrolled4 줄과 unrolled8 줄을 뽑아서 같은 이름으로 바꾼 파일 2개를 만들면, benchstat가 둘을 짝지어 통계 판정을 내려줍니다.

> grep 'simd-unrolled4' result.txt | sed 's|simd-unrolled4|X|' > u4.txt
> grep 'simd-unrolled8' result.txt | sed 's|simd-unrolled8|X|' > u8.txt
> benchstat u4.txt u8.txt

 unrolled4 unrolled8 delta
Sum/n=1024 58.35n → 56.67n -2.88% (p=0.000, n=10)
Sum/n=65536 3.655µ → 3.522µ -3.65% (p=0.000, n=10)
Sum/n=1048576 59.09µ → 56.71µ -4.03% (p=0.000, n=10)

p=0.000은 “이 차이가 우연일 확률이 사실상 0"이라는 뜻입니다. 그러니까 진짜 이득은 맞는데, 34%뿐인 거죠. 이유는 4-2에서 배운 원리 그대로입니다. 여러 accumulator는 CPU가 앞선 덧셈을 기다리는 동안만 일감을 주는데, 4개면 그 대기 시간이 이미 거의 다 채워집니다. 그 다음 한계는 CPU가 1 cycle에 발행할 수 있는 명령 수와 memory에서 데이터를 끌어오는 속도인데, accumulator를 늘려도 이 둘은 개선할 수 없습니다. 남은 34%는 루프 1바퀴가 32개를 처리하면서 비교/분기 비용이 절반으로 준 몫입니다. 즉, 합계 구하기의 경우 SIMD + 4개 accumulator 사용하기가 최적인 셈이죠.

Poly는 어떨까요?

구현	n=1024	n=65536	n=1M
scalar	12.1	12.3	12.2
simd	24.2	25.6	25.6

모든 크기에서 일관되게 약 2.1배입니다. lane이 4개인데 왜 4배가 안 될까요? 호너의 방법 3단계가 앞 단계의 결과에 의존하는 사슬이라서, vector 안에서도 대기가 남기 때문입니다. Sum에서 accumulator를 늘렸던 것처럼, 서로 다른 원소 묶음 여러 개를 겹쳐서 처리하는 unroll을 실험해볼 수 있을 것 같습니다.

후속 실험: Poly도 unroll 해보기

후보로만 남겨두면 아쉬우니 바로 실험해봤습니다. 한 번에 원소 묶음 4개(16개)를 처리하는 PolySIMDUnrolled4를 추가했는데요, 핵심은 연산을 원소별이 아니라 단계별로 묶는 겁니다. 이렇게 하면 매 단계마다 서로 독립적인 연산 4개를 CPU가 처리하게 됩니다.

 v0 := simd.LoadFloat32s(x[i : i+lanes]) // v1, v2, v3도 같은 방식으로 로드
 ...
 // 1단계 4개를 먼저 전부, 그 다음 2단계 4개, 3단계 4개 순서로
 r0 := c3.Mul(v0).Add(c2)
 r1 := c3.Mul(v1).Add(c2)
 r2 := c3.Mul(v2).Add(c2)
 r3 := c3.Mul(v3).Add(c2)

 r0 = r0.Mul(v0).Add(c1)
 // ... r1, r2, r3도 동일

Sum 때처럼 정확성 테스트(TestPolyImplsMatchScalar)를 먼저 통과시키고, -count=10으로 재서 benchstat로 판정했습니다.

 PolySIMD PolySIMDUnrolled4 delta
Poly/n=1024 169.0n → 160.6n -4.97% (p=0.000, n=10)
Poly/n=65536 10.358µ → 9.678µ -6.56% (p=0.000, n=10)
Poly/n=1048576 168.1µ → 154.4µ -8.15% (p=0.000, n=10)

5~~8% 빨라졌습니다. p=0.000이니 진짜 이득이고, Sum의 4개 → 8개(3~~4%)보다는 얻는 이익이 크긴 한데… 굳이? 싶은 느낌도 있긴 하네요.

참고로 PolySIMDUnrolled4의 전체 코드와 정확성 테스트(TestPolyImplsMatchScalar), 벤치마크 추가분은 이 글의 저장소 simdbench 폴더에 있습니다.

마지막 실험: core는 다 쓰고 있었을까?

여기까지 읽고 이런 의문이 들 수 있습니다. “SumSIMDUnrolled4가 이미 core를 다 쓰고 있는 거라면, 더 병렬화할 곳은 없을까?” 그런데 사실 지금까지의 모든 측정에는 함정이 하나 숨어 있습니다. 벤치마크 결과에 표시되던 -18은 GOMAXPROCS 표시일 뿐이고, 벤치마크는 goroutine 1개를 쓰고 있었습니다. 70 GB/s가 전부 core 1개의 처리량이었던 거죠.

지금까지는 2개의 병렬화 수단(accumulator로 명령을 겹치기, 그리고 lane 4개로 데이터를 겹치는 SIMD)을 이용했습니다. 그런데 둘 다 core 1개 안에서 일어나는 일이기 때문에 모든 코어를 다 활용하진 못했던 거죠. 이번에 확인할 마지막 SIMD 커널에서는 슬라이스를 core 수만큼 나눠서 goroutine마다 SumSIMDUnrolled4를 돌리고, 부분합을 하나로 합쳐볼 겁니다!

// SumSIMDParallel은 슬라이스를 core 수만큼 나눠서 goroutine마다 SumSIMDUnrolled4를 돌린다.
// SIMD(lane)와 ILP(accumulator)에 이어 세 번째 병렬화 요소인 core 병렬화를 추가하는 구현이다.
func SumSIMDParallel(x []float32) float32 {
 workers := runtime.GOMAXPROCS(0)
 // 작은 입력(65535 이하)는 goroutine을 만들고 기다리는 비용이 계산 비용보다 크다
 if len(x) < 1<<16 || workers == 1 {
 return SumSIMDUnrolled4(x)
 }

 // 각 워커가 처리해야 할 데이터의 크기
 // 남는 데이터가 발생하지 않도록 worker-1을 더하고 worker로 나눠준다.
 chunk := (len(x) + workers - 1) / workers
 // 각 worker의 출력을 저장할 슬라이스
 partial := make([]float32, workers)
 var wg sync.WaitGroup
 for w := 0; w < workers; w++ {
 lo := w * chunk
 // 남는 데이터가 발생하지 않도록 chunk의 크기를 조정했기 때문에, 후반부 작업에서는 worker의 시작 지점이 데이터의 길이를 넘어서는 경우가 있음.
 if lo >= len(x) {
 break
 }
 hi := min(lo+chunk, len(x))
 wg.Add(1)
 go func(w, lo, hi int) {
 defer wg.Done()
 partial[w] = SumSIMDUnrolled4(x[lo:hi])
 }(w, lo, hi)
 }
 wg.Wait()

 var s float32
 // 부분합을 모두 더하기
 for _, p := range partial {
 s += p
 }
 return s
}

위 코드에서 chunk를 나누는 부분이 헷갈릴 수 있는데요,(제가 그랬다는 겁니다…) 그림으로 보면 좀 더 명확합니다.

10개 입력에 대해서 3개의 worker가 작업을 나눠가질 때, 10/3을 해버리면 결과가 3이 되어서 9번 요소는 버려지는 상황이 되죠. 그래서 딱 떨어지는 경우를 제외하고 +1의 경계에 걸리도록 worker-1을 더해주고 나누도록 합니다. 뭐… 그렇답니다!

이 함수를 추가할 때는 kernel_simd.go의 import에 runtime과 sync를 추가해야 합니다. 측정에 쓴 벤치마크(BenchmarkSumBig)를 포함한 전체 코드는 이 글의 저장소 simdbench 폴더에 있습니다.

작은 입력에 core 병렬화를 걸면 비효율이 증가합니다. 그래서 큰 입력 2개(1M, 16M 원소)로 측정해봤는데요, 16M(64MB)은 cache를 완전히 벗어나 DRAM까지 내려가는 크기입니다.

 simd-unrolled4 simd-parallel
n=1M (4MB) 60.06µ → 28.55µ ×2.1 (p=0.000, n=10)
n=16M (64MB) 1003.3µ → 329.7µ ×3.0 (p=0.000, n=10)

처리량: 70 GB/s → 147 GB/s (n=1M) → 204 GB/s (n=16M)

core를 18개나 줬는데 3배밖에 안 빨라졌습니다. 왜일까요? 204 GB/s가 CPU core들이 실제로 끌어낼 수 있는 실효 대역폭 근처이기 때문입니다. core 1개가 이미 70 GB/s, 그러니까 실효 대역폭의 1/3을 혼자 끌어오고 있었던 겁니다. core가 18개라도 메모리가 데이터를 그보다 빨리 못 내주는 거죠.

앞에서 진행했던 single core 측정에서는 크기가 커져도 처리량이 안 꺾여서 계산 병목이라고 했었는데요, 정확히 말하면 “core 1개의 명령 발행 한계가 core 1개 몫의 메모리 대역폭보다 낮았던” 겁니다.

정리하면 병렬화의 축은 3개이고, 축마다 부딪히는 벽이 다릅니다.

축	기법	부딪히는 벽
ILP	accumulator 4개로 명령 겹치기	덧셈 latency → 명령 발행 폭
SIMD	lane 4개로 데이터 겹치기	명령 발행 폭
core	goroutine으로 나눠 돌리기	DRAM 대역폭

축 3개를 다 쌓으면 n=16M 기준 scalar 대비 약 27배입니다(scalar 처리량 7.3 GB/s로 환산하면 약 8.8ms → 330µs). 여기까지 하고 나면 더 적용할만한 방법은 없어보입니다. 데이터를 읽는 속도보다 빠르게 더할 수는 없으니까요.

정리하면 이번 측정의 교훈은 4가지입니다.

최적화는 병목을 제거할 때만 배수로 돌아옵니다. 병목이 사라진 뒤의 같은 기법은 몇 %짜리입니다.
몇 % 차이는 눈으로 판정할 수 없습니다. -count=10과 benchstat의 p 값이 근거입니다.
벤치마크가 빠르다는 것과 결과가 맞다는 것은 별개입니다. 정확성 테스트가 벤치마크보다 먼저입니다.
병렬화의 축은 3개입니다(ILP, SIMD, core). 그리고 마지막 벽은 memory 대역폭입니다. 데이터를 읽는 속도보다 빠르게 계산할 수는 없습니다.

마치면서

생각보다 복잡한 과정이긴 했지만, 그래도 SIMD가 뭐다 정도는 이해를 한 거 같습니다. 곧 까먹긴 하겠지만요…하하하하하…

참고자료

Typescript: Temporal

Tue, 04 Aug 2026 20:42:31 +0900

Javascript는 아주 혼란스러운 시간을 지나왔습니다. 특히 es6로 넘어가기 전까지는 혼돈 그 자체였죠. 이제서야 어엿한 메이저 언어로서 자리매김했지만 한때는 정말 느리고, 건드리기 싫었던 언어였습니다. 그 덕에 2000년대 말에 RIA(플래시, 실버라이트 등)가 아주 인기를 끌기도 했었죠.

Javascript는 그 이후에 많은 변화를 거치면서 정돈되어 왔습니다. 그런데 아직까지도 제대로 해결되지 못한 부분도 여전히 존재합니다. 최근 Typescript 6.0에 Temporal 이라는 최상위 네임스페이스(ex: Math)가 추가되었는데요, 기존에 사용되어 왔던 Date도 아주 오래전 부터 해결되지 못했던 부분입니다. Temporal에 대한 이야기를 하기 전에 잠시 왜 이런 문제가 발생했는지 짧게 짚고 넘어가죠!

Javascript의 간략한 역사

Maggie Pint에 따르면 2017년에 Javascript를 만든 브랜든 아이크(Brendan Eich)와 다음과 같은 대화를 나눴다고 합니다.

It is now common knowledge that in 1995 Brendan was given only 10 days to write the JavaScript language and get it into Netscape. Date handling is a fundamental part of almost all programming languages, and JavaScript had to have it. That said, it’s a complex problem domain and there was a short timeline. Brendan, under orders to “make it like Java” copied the date object from the existing, infant, java.Util.Date date implementation. This implementation was frankly terrible. In fact, basically all of it’s methods were deprecated and replaced in the Java 1.1 release in 1997. Yet we’re still living with this API 20 years later in the JavaScript programming language.

1995년 당시 Netscape 브라우저 출시를 앞두고 웹 페이지에 동적인 액션을 구현할 스크립트 언어가 필요했고, 그 언어를 10일 만에 완성해야 했습니다. 그리고 그 언어는 Java와 유사하게 만들어야 했다고 합니다. 그 당시 Java는 베타 버전 상태였고, 정식 1.0 출시는 1996년이었습니다. 그러니까 베타 버전이었던 언어의, 제대로 정리되지 않았던 구현을 그대로 Javascript로 옮겼고 그게 아직까지 제대로 정리되지 않았다 뭐 그런 이야기입니다. Javascript가 참고했던 Java 구현은 1997년에 교체되었다고 하니까, Javascript는 이미 이 세상에 존재하지 않는 deprecated된 구현을 30년 넘게 유지하고 있었던 셈이죠!

10일만에 언어를 만든다는 건 정말 대단한 일이죠. 그런데 그렇게 급조한 언어가 이렇게 인기를 끌게 될 줄은 아무도 몰랐던 거죠. 그러다보니 앤더스 헬스버그 (Anders Hejlsberg)가 Javascript that scales를 모토로 Typescript를 만들게 되기도 했죠.

Temporal로 다시 돌아와서

Temporal은 이렇게 오래된 문제를 해결하기 위해 제안되었습니다. 뒤에서 자세히 알아보겠지만 우선 Temporal에서 뭘 지원해준다는 건지 알아볼까요?

Date는 혼자서 모든 걸 다 하려고 했지만, Temporal은 그걸 여러 타입으로 쪼갰습니다. 그래서 좀.. 복잡해 보일 수도 있긴 합니다.

타입	담는 것	값을 찍어보면	이럴 때 씁니다
`PlainDate`	날짜만	`2026-07-31`	생일, 기념일
`PlainTime`	시각만	`09:00:00`	매일 같은 시각에 울리는 알람
`PlainDateTime`	날짜 + 시각	`2026-07-31T09:00:00`	아직 어느 지역인지 안 정한 일정
`ZonedDateTime`	날짜 + 시각 + 타임존	`2026-07-31T09:00:00-04:00[America/New_York]`	실제로 잡힌 뉴욕 회의
`Instant`	절대적인 한 순간	`2026-07-31T13:00:00Z`	로그 시각, 서버끼리 시각 비교
`Duration`	흘러간 양(기간)	`P8M14D` (8개월 14일)	“3일 뒤”, 두 날짜의 간격

잘 보시면 앞에 붙은 이름에 따라 타입이 다루는 값이 다릅니다.

Plain으로 시작하면 타임존이 없습니다. 달력이나 시계에 적힌 글씨 그대로라고 보면 됩니다. “7월 31일 오전 9시"는 서울에서 읽든 뉴욕에서 읽든 그냥 7월 31일 오전 9시죠.
Zoned가 붙으면 값 안에 타임존까지 들어 있습니다. 그래서 “뉴욕의 오전 9시"처럼 지구상의 딱 한 순간을 가리킬 수 있습니다.

Instant는 Date와 가장 비슷한 타입입니다. Date도 속을 들여다보면 “1970년 1월 1일부터 몇 밀리초 지났나"라는 숫자 하나거든요. 이 밖에 연-월만 담는 PlainYearMonth(2026-07), 월-일만 담는 PlainMonthDay(07-31), 지금 시각을 가져오는 Temporal.Now도 있습니다.

지금 이 테이블은 일단 확인만 해두세요, 이제 부터 Date 객체의 구체적인 문제점과 Temporal의 해결책을 하나씩 확인해 볼거니까요!

date-issues.js 파일을 통해 각각의 문제점 코드를 확인할 수 있고, date-issues-fixed.mjs 파일을 통해 Temporal의 코드를 확인할 수 있습니다. node 24 버전까지는 Temporal이 지원되지 않으므로, npm i @js-temporal/polyfill 명령으로 폴리필을 설치해 줘야 합니다.

1. 타임존은 ‘로컬’과 ‘UTC’ 딱 두 개뿐입니다

다음 예제를 볼까요?

process.env.TZ = "America/New_York";

const noon = new Date("2026-07-31T12:00:00Z");
console.log("로컬: getHours()", noon.getHours()); // 로컬: getHours() 8
console.log("UTC: getUTCHours()", noon.getUTCHours()); // UTC: getUTCHours() 12

const seoulHour = new Intl.DateTimeFormat("en-CA", {
 timeZone: "Asia/Seoul",
 hour: "2-digit",
 hourCycle: "h23",
}).format(noon);

// 결과값이 문자열이므로, 시간의 계산은 불가
console.log("서울: ", seoulHour); // 서울: 21

noon은 UTC로 7월 31일 12시 입니다. 이 시점에서 다른 타임존을 적용해서, 예를 들면 UTC->Asia/Seoul 로 변환해서 값을 가져와야 할 때가 있겠죠. 그런데 Date 객체는 딱 두가지만 지원합니다. UTC로 가져오던지, 현재 이 코드를 실행 중인 장비의 로컬 타임존으로 가져오던지.

Intl.DateTimeFormat을 활용하면 다른 타임존의 값을 가져올 수는 있지만, 결과가 문자열이기 때문에 표시이외의 용도로 사용하려면 또 다른 변환 작업을 해야만 합니다.

Temporal은 날짜에 타임존을 결합할 수 있습니다

Temporal은 날짜 값에 타임존을 결합할 수 있습니다(ZonedDateTime). 그 결과 특정 시점에서 다른 타임존의 변환은 물론, 변환된 날짜를 기반으로 계산도 가능합니다.

// 특정 순간을 의미하는 Instant를 생성(Date는 항상 Instant 입니다)
const noon = Temporal.Instant.from("2026-07-31T12:00:00Z");

// 각 타임존으로 noon을 변환
for (const tz of ["America/New_York", "UTC", "Asia/Seoul"]) {
 const z = noon.toZonedDateTimeISO(tz);
 console.log(`${tz.padEnd(20)} ${z.hour}시 (offset ${z.offset})`);
 // America/New_York 8시 (offset -04:00)
 // UTC 12시 (offset +00:00)
 // Asia/Seoul 21시 (offset +09:00)
}

// 문자열이 아니라 값이므로 그대로 계산에 쓸 수 있습니다.
const seoul = noon.toZonedDateTimeISO("Asia/Seoul");
console.log("서울 기준 3시간 뒤:", seoul.add({ hours: 3 }).hour + "시"); // 서울 기준 3시간 뒤: 0시

2. 파서(parser)를 신뢰할 수 없습니다

Date 객체는 문자열을 날짜로 변환할 수 있습니다. 그런데 문자열을 해석하는 파서의 동작이 명확하지 않습니다. 아주 간단하게 살펴볼까요?

process.env.TZ = "America/New_York";

for (const input of [
 '2026-07-31', // 날짜만 있는 ISO → UTC로 해석
 '2026-07-31T09:00', // 시각이 붙은 ISO → 로컬로 해석 (!)
 '2026-07-31 09:00', // T 대신 공백 → 명세 밖, 엔진 재량
 '07/31/2026', // ISO가 아예 아님 → 명세 밖, 엔진 재량
 '2026-07-31T09:00Z', // 명시적 UTC → UTC로 해석
]) {
 console.log(input, "-->", new Date(input).toISOString());
}
// 2026-07-31 --> 2026-07-31T00:00:00.000Z
// 2026-07-31T09:00 --> 2026-07-31T13:00:00.000Z
// 2026-07-31 09:00 --> 2026-07-31T13:00:00.000Z
// 07/31/2026 --> 2026-07-31T04:00:00.000Z
// 2026-07-31T09:00Z --> 2026-07-31T09:00:00.000Z

날짜만 있는 경우 UTC로, 시간이 붙어 있는 경우 로컬로… 이렇게 좀 복잡한 동작을 수행합니다.

Temporal은 명확한 규칙을 요구합니다

// 날짜만 있는 문자열 → PlainDate. 타임존이 아예 개입하지 않습니다.
console.log(`PlainDate.from("2026-07-31")`, Temporal.PlainDate.from("2026-07-31").toString()); // PlainDate.from("2026-07-31") 2026-07-31

// 시각까지 있지만 타임존이 없는 문자열 → PlainDateTime. 역시 타임존은 포함되지 않습니다.
console.log(`PlainDateTime.from("...T09:00")`, Temporal.PlainDateTime.from("2026-07-31T09:00").toString()); // PlainDateTime.from("...T09:00") 2026-07-31T09:00:00

// 명확한 시점을 원하면 타임존을 명시해야 합니다. 생략하면 통과하지 않습니다.
console.log(`ZonedDateTime.from("...[NY]")`, Temporal.ZonedDateTime.from("2026-07-31T09:00[America/New_York]").toString()); // ZonedDateTime.from("...[NY]") 2026-07-31T09:00:00-04:00[America/New_York]

// 추측을 요구하는 입력은 모두 거부됩니다.
for (const [desc, action] of [
 ["타임존 없이 Instant 요구", () => Temporal.Instant.from("2026-07-31T09:00")],
 ["타임존 없이 Zoned 요구", () => Temporal.ZonedDateTime.from("2026-07-31T09:00")],
 ["존재하지 않는 2월 30일", () => Temporal.PlainDate.from("2026-02-30")],
 ["ISO가 아닌 07/31/2026", () => Temporal.PlainDate.from("07/31/2026")],
 ["banana", () => Temporal.PlainDate.from("banana")],
]) {
 try {
 console.log(desc, "→", action().toString(), "(통과)");
 } catch (e) {
 console.log(desc, "→", e.constructor.name, "즉시 예외");
 }
}
// 타임존 없이 Instant 요구 → RangeError 즉시 예외
// 타임존 없이 Zoned 요구 → RangeError 즉시 예외
// 존재하지 않는 2월 30일 → RangeError 즉시 예외
// ISO가 아닌 07/31/2026 → RangeError 즉시 예외
// banana → RangeError 즉시 예외

3. Date는 변경 가능(mutable)합니다

Date 객체는 const로 선언해서 불변하도록(immutable) 만들 수 없습니다.

function startOfMonth(date) {
 date.setDate(1); // 인자로 받은 객체를 직접 수정합니다
 return date;
}

const someDate = new Date('2026-07-31T12:00:00Z');
console.log("함수 호출 전", someDate.toISOString().slice(0, 10)); // 함수 호출 전 2026-07-31
startOfMonth(someDate);
console.log("함수 호출 후", someDate.toISOString().slice(0, 10)); // 함수 호출 후 2026-07-01

Temporal의 날짜는 불변(immutable) 합니다

function startOfMonth(date) {
 return date.with({ day: 1 }); // 원본을 건드리지 않고 새 값을 반환
}

const someDate = Temporal.PlainDate.from("2026-07-31");
console.log("함수 호출 전", someDate.toString()); // 함수 호출 전 2026-07-31
const firstDay = startOfMonth(someDate);
console.log("함수 호출 후", someDate.toString(), " ← 원본 그대로"); // 함수 호출 후 2026-07-31 ← 원본 그대로
console.log("반환값", firstDay.toString()); // 반환값 2026-07-01

4. 서머타임(DST) 동작을 예측할 수 없습니다

서머타임은 시간을 1시간 앞당겨서 해가 떠있는 시간을 좀 더 많이 활용할 수 있도록 하는 제도입니다. 그래서 특정 시간부터 시간이 1시간 앞당겨지고, 서머타임이 끝날 때는 1시간 밀리게 됩니다.

미국의 경우 3월의 둘째 일요일 오전 2시에 서머타임이 시작됩니다. 그러니까 2026년으로 치면 3월 8일 오전 1시 59분에서 2시가 되는 순간, 서머타임이 적용되면서 2시가 아닌 3시가 되는겁니다.

그림으로 보자면, 우선 뉴욕의 2026년 3월 8일 오전 1시 59분입니다.

그리고 오전 2시가 되는 순간, 2시가 통째로 사라지고 3시가 됩니다!

UTC 시간을 잘 보시면, 시간은 그대로 흘러가지만 표시되는 시간만 2시 -> 3시로 변경되면서 2시가 통째로 사라지게 됩니다. 즉 3월 8일 오전 2시 30분은 존재할 수 없는 시간이며, 3월 8일은 24시간이 아닌 23시간짜리 하루입니다.

Date 객체는 이 문제를 제대로 처리하지 못합니다.

// 3월의 두번째 일요일 2am -> 3am으로 변경(-05:00 EST-> -04:00 EDT). 따라서 뉴욕기준 2026년 3월 8일 2am은 존재하지 않음.
// 따라서 2026년 3월 8일은 23시간
// 이후 11월 1일 2am에 다시 EDT->EST로 변경되며, 1am을 두번 통과하므로 11월 1일은 25시간
const beforeSpringForward = new Date('2026-03-08T00:00:00-05:00');
console.log("3월 8일 자정", beforeSpringForward); // 3월 8일 자정 2026-03-08T05:00:00.000Z

// 다음 날(+ 86,400,000 ms) -> 2026-03-09T05:00:00.000Z 이므로, EDT 기준으로는 3월 9일 오전 1시.
const nextDay = new Date(beforeSpringForward.getTime() + 86400000);
console.log("다음날 자정이 아니다!", nextDay.toLocaleString('en-US', { timeZone: 'America/New_York' })); // 다음날 자정이 아니다! 3/9/2026, 1:00:00 AM

Temporal은 서머타임이 정확하게 적용됩니다!

days/weeks/months와 같이 달력의 날짜 기준 계산에는 DST를 적용하고, 시간 단위 계산은 Date와 동일하게 정확한 시간 단위로 계산합니다.

const midnight = Temporal.ZonedDateTime.from("2026-03-08T00:00[America/New_York]");

console.log("3월 8일 자정", midnight.toString());
console.log(" .add({ days: 1 }) ", midnight.add({ days: 1 }).toString(), " ← 진짜 다음 날 자정"); // .add({ days: 1 }) 2026-03-09T00:00:00-04:00[America/New_York] ← 진짜 다음 날 자정
console.log(" .add({ hours: 24 })", midnight.add({ hours: 24 }).toString(), " ← 24시간 뒤 (오전 1시)"); // .add({ hours: 24 }) 2026-03-09T01:00:00-04:00[America/New_York] ← 24시간 뒤 (오전 1시)

// 하루가 몇 시간인지 직접 물어볼 수 있습니다.
for (const d of ["2026-03-07", "2026-03-08", "2026-11-01"]) {
 const z = Temporal.PlainDate.from(d).toZonedDateTime({ timeZone: "America/New_York" });
 console.log(` ${d} → ${z.hoursInDay}시간`);
}
// 2026-03-07 → 24시간
// 2026-03-08 → 23시간
// 2026-11-01 → 25시간

// 존재하지 않는 시각을 예약하려 하면 조용히 옮기지 않고 거부할 수 있습니다.
for (const option of ["compatible", "reject"]) {
 try {
 const r = Temporal.PlainDateTime.from("2026-03-08T02:30")
 .toZonedDateTime("America/New_York", { disambiguation: option });
 console.log(` 02:30 (${option})`.padEnd(24), r.toPlainTime().toString(), "← 조용히 이동함");
 } catch (e) {
 console.log(` 02:30 (${option})`.padEnd(24), e.constructor.name, "← 없는 시각이라고 알려줌");
 }
}
// 02:30 (compatible) 03:30:00 ← 조용히 이동함
// 02:30 (reject) RangeError ← 없는 시각이라고 알려줌

// 11월 1일 01:30은 두 번 존재합니다. 어느 쪽인지 고를 수 있습니다.
for (const option of ["earlier", "later"]) {
 const r = Temporal.PlainDateTime.from("2026-11-01T01:30")
 .toZonedDateTime("America/New_York", { disambiguation: option });
 console.log(` 01:30 (${option})`.padEnd(24), r.toInstant().toString());
}
// 01:30 (earlier) 2026-11-01T05:30:00Z
// 01:30 (later) 2026-11-01T06:30:00Z

5. 계산 API가 조악합니다

Date 객체는 제대로된 날짜 계산 API를 제공하지 않고, 메서드의 이름은 오래 전에 혼란스러웠던 형태를 그대로 가지고 있습니다.(심지어 month는 0부터 시작합니다!)

// 1월 31일 + 1달 -> 2월 31일 -> 3월 3일
const monthEnd = new Date('2026-01-31T12:00:00Z');
monthEnd.setUTCMonth(monthEnd.getUTCMonth() + 1);
console.log("1월 31일 + 1달", monthEnd.toISOString().slice(0, 10)); // 1월 31일 + 1달 2026-03-03

// 두 날짜의 차이 구하기. 86,400,000 ms를 이용해서 나눠야 함. DST를 사용하는 경우 1년에 두 번 틀림
const rangeStart = new Date('2026-01-01T00:00:00Z');
const rangeEnd = new Date('2026-09-15T00:00:00Z');
console.log("두 날짜의 간격", (rangeEnd - rangeStart) / 86400000); // 두 날짜의 간격 257

// 날짜의 각 요소 구하기, getMonth는 0부터 시작하고, getDay는 요일을 리턴 함.
const july31 = new Date("2026-07-31T12:00:00Z");
console.log("getMonth:", july31.getUTCMonth());
console.log("getDay:", july31.getUTCDay());
console.log("getFullYear:", july31.getUTCFullYear());
// getMonth: 6
// getDay: 5
// getFullYear: 2026

Temporal은 오해 없이 정확한 API를 제공합니다.

// 1월 31일 + 1달 → 2월 28일로 잘라냅니다(clamp). 3월로 넘어가지 않습니다.
const endMonth = Temporal.PlainDate.from("2026-01-31");
console.log("1월 31일 + 1달 ", endMonth.add({ months: 1 }).toString()); // 1월 31일 + 1달 2026-02-28
console.log(` overflow:"reject" `, (() => {
 try { return endMonth.add({ months: 1 }, { overflow: "reject" }).toString(); }
 catch (e) { return e.constructor.name + " (넘침을 알려달라고 할 수도 있음)"; }
})());
// overflow:"reject" RangeError (넘침을 알려달라고 할 수도 있음)

// 주의: 한 달씩 두 번 더하는 것과 두 달을 한 번에 더하는 것은 다릅니다.
// ex: 매월 구독 결제일은 최초 결제일에서 누적된 달만큼 한 번에 계산해야 합니다.
console.log(" 1달+1달 ", endMonth.add({ months: 1 }).add({ months: 1 }).toString()); // 1달+1달 2026-03-28
console.log(" 2달 한 번에 ", endMonth.add({ months: 2 }).toString()); // 2달 한 번에 2026-03-31

// 두 날짜의 간격. 86,400,000 같은 상수가 필요 없습니다.
const start = Temporal.PlainDate.from("2026-01-01");
const end = Temporal.PlainDate.from("2026-09-15");
console.log("두 날짜의 간격(일) ", start.until(end).total({ unit: "day" })); // 두 날짜의 간격(일) 257
console.log(" ISO 8601 표기 ", start.until(end, { largestUnit: "month" }).toString()); // ISO 8601 표기 P8M14D

// 필드 접근. 메서드가 아니라 속성이고, 월은 1부터 시작합니다.
const july31 = Temporal.PlainDate.from("2026-07-31");
console.log("month (1부터) ", july31.month);
console.log("day (일) ", july31.day);
console.log("dayOfWeek (요일) ", july31.dayOfWeek, "(1=월요일)");
console.log("year ", july31.year);
console.log("daysInMonth ", july31.daysInMonth);
// month (1부터) 7
// day (일) 31
// dayOfWeek (요일) 5 (1=월요일)
// year 2026
// daysInMonth 31

6. 그레고리력 외의 달력을 지원하지 않습니다

그레고리력은 1582년 교황 그레고리우스 13세가 반포했으며, 윤년과 관련된 오차를 없애기 위해서 제정되었습니다. 지금 전 세계가 쓰고 있는 달력이 바로 그레고리력인 셈이죠. 하지만 가끔은 다른 달력을 써야 하는 경우도 있습니다.

우리와 가장 가까운 나라인 일본을 보자면, 2026년 7월 31일에 연호를 붙여서 “레이와 8년 7월 31일” 이라고 표현합니다. 이런 그레고리력 이외의 달력을 Date 객체는 제대로 지원하지 않습니다.

const july31 = new Date("2026-07-31T12:00:00Z");

// 표기는 가능하지만, 결과는 문자열 값이므로 1과 같은 이유로 날짜 계산 등은 불가능.
for (const calendar of ['hebrew', 'islamic-umalqura', 'japanese', 'buddhist']) {
 console.log(
 calendar,
 new Intl.DateTimeFormat(`en-u-ca-${calendar}`, {
 timeZone: 'UTC',
 dateStyle: 'long',
 }).format(july31)
 );
}
// hebrew 17 Av 5786
// islamic-umalqura Safar 17, 1448 AH
// japanese July 31, 8 Reiwa
// buddhist July 31, 2569 BE

Temporal은 제대로 지원합니다.

const july31 = Temporal.PlainDate.from("2026-07-31");

for (const calendar of ['hebrew', 'islamic-umalqura', 'japanese', 'buddhist']) {
 const d = july31.withCalendar(calendar);
 const year = d.era ? `${d.era} ${d.eraYear}년 (연속 ${d.year})` : `${d.year}년`;
 console.log(calendar, year);
}
// hebrew 5786년
// islamic-umalqura 1448년
// japanese reiwa 8년 (연속 2026)
// buddhist 2569년

// 문자열이 아니기 때문에 계산이 가능합니다.
const japaneseJuly31 = july31.withCalendar("japanese");
console.log(japaneseJuly31.add({ days: 2}).toString()); // 2026-08-02[u-ca=japanese]

Temporal의 현재

Temporal 스펙은 현재 Stage 4 단계이며, 곧 표준으로 병합될 예정입니다. 주요 브라우저들(Safari는 2026년 8월 기준으로 아직 개발 중)은 구현을 마쳤고, Node.js 역시 26 버전에서 Temporal을 정식 지원하고 있습니다.

정식 지원되지 않는 환경에서 Temporal을 사용하려면, @js-temporal/polyfill 를 통해 폴리필해서 사용하는 방법이 권장됩니다.

Typescript의 지원

Typescript 6 와 7에서 Temporal을 정식 지원합니다. 하지만, 지원되는 건 어디까지나 타입 체크이고 실제 실행은 js 런타임에서 진행되니까 실행 가능 여부는 js 런타임에 의해 결정됩니다.

우선 typescript 7 을 설치하고 node의 버전을 체크합니다.

> npm i -D typescript@7 @types/node
> node -v
v26.6.0

VS Code를 사용하는 경우, Typescript 7 확장을 설치해야 7 버전의 IDE 지원을 받을 수 있습니다.

그리고 tsconfig.json 을 다음과 같이 설정합니다.

{
 "compilerOptions": {
 "target": "esnext",
 "module": "nodenext",
 "moduleResolution": "nodenext",
 "lib": ["esnext", "dom"],
 "types": ["node"],
 "strict": true,
 "skipLibCheck": true,
 "noEmit": true
 }
}

그리고 다음 코드를 작성합니다.

// Temporal은 전역(global)이므로 import가 필요 없습니다.
// 타입은 tsconfig의 lib: ["esnext"] 에서 옵니다.
const meeting: Temporal.ZonedDateTime =
 Temporal.ZonedDateTime.from('2026-03-08T09:00[America/New_York]');

console.log(meeting.toString());
console.log(`이 날은 ${meeting.hoursInDay}시간`); // 23 — 서머타임 시작
console.log('서울에서는:', meeting.withTimeZone('Asia/Seoul').toPlainDateTime().toString());

그리고 다음과 같이 실행하여 결과를 확인할 수 있습니다.

> node temporal.ts
2026-03-08T09:00:00-04:00[America/New_York]
이 날은 23시간
서울에서는: 2026-03-08T22:00:00

마치면서

아주 가끔씩 생각날 때 마다 Typescript 업데이트 노트를 읽어봅니다. 이번에도 Go로 재작성된 7 버전도 보고 6 버전도 읽어봤습니다. 그러던 중에 Temporal이라는 게 있는데 이게 도대체 뭔지 모르겠더군요. 그래서 이리저리 찾아보면서 미래의 저를 위해서 정리를 해봤는데 생각보다 꽤나 복잡한 내용이었습니다. 아마도 가까운 시일 내에 금방 잊어버리겠죠…하하하…

참고자료

go를 알아보자(3) - 포인터

Mon, 25 May 2026 08:46:28 +0900

아주 오래전, 중학생이었던 제가 혼자서 C를 공부했던 시절이 있었습니다. 터보C 2.0 컴파일러와 안녕하세요 터보C 라는 책을 하나 들고 열심히 공부를 했습니다. 그때 당시엔 함수라는 개념을 도저히 이해할 수 없었습니다. 그리고 시간이 1-2년 지나서 그 책을 다시 집어 들고 공부를 했지만 이번엔 포인터, 구조체의 개념을 도저히 이해할 수 없었던 기억이 납니다. 그리고 포인터는 대학교 2학년이 되어서야 제대로(??? 그러니까 한 2차원 배열을 다룰 정도?) 이해할 수 있었습니다.

그리고는 그 당시 베타 버전이 출시되던 닷넷(.NET)으로 넘어가면서 포인터와의 악연은 막을 내렸죠. 그런데 말입니다…

최근에 작업을 Go로 하려다보니… 어쩔 수 없이 다시 포인터를 마주하게 됩니다. 20년도 더 지나서 포인터를 다시 보니 너무 헷갈려서 머리가 빙빙 돌더군요. 그래서 저를 위해서 포인터를 다시 한 번 정리해보자, 하는 하찮은 이유로 그냥 정리해봅니다. 미래의 저를 위해서!

포인터…

포인터는 말 그대로 그냥 어느 한 지점을 가리키는 걸 말합니다. 포인터는 두 개의 특수기호 *, & 가 연관되어 있는데요, 우선 *는 어디에서 사용되느냐에 따라 의미가 다릅니다.

타입의 앞에 붙은 경우(ex: *bool) -> 메모리에서 해당 타입의 값이 위치하는 곳을 가리키는 포인터
표현식에서 사용된 경우(ex: *isActive) -> 포인터가 가리키는 지점에 위치한 값, 참조 해제(포인터->실제 값)

그리고 &는 메모리의 주소를 가져오는 연산자로, 변수나 구조체등에 붙이게 되면 값이 위치한 메모리의 주소를 리턴합니다.

다음 예시를 볼까요?

var b bool = true // bool 타입의 변수 b에 true를 설정 -> 메모리의 어딘가 변수 b가 할당됨
var p *bool = &b // 변수 b의 메모리 주소를 bool타입의 포인터 p에 할당
fmt.Println(p) // 포인터 p가 가리키는 -> 변수 b의 메모리 주소가 출력됨(ex: 0xc0000140a0)
fmt.Println(*p) // 포인터 p가 가리키는 -> 참조 해제 -> 변수 b의 값이 출력됨(true)

*p = false // 포인터 p가 가리키는 -> 변수 b의 값을 false로 변경
fmt.Println(b) // 변수 b의 값이 출력됨(false)

그림으로 보면 이렇습니다.

메모리:
 ┌──────────────┐
변수 b 0xc000014090 │ true │ ◄──┬── *p (참조 해제 결과: true)
 └──────────────┘ │
 │ p가 가진 주소를
 │ 따라가서 도달
 ┌──────────────┐ │
포인터 p 0xc0000140a0 │0xc000014090 │ ───┘
 └──────────────┘ (&b로 얻은 주소를 값으로 가짐)

&b 는 변수 b가 위치한 메모리 주소(0xc000014090)를 얻어옵니다.
포인터 p는 그 주소를 자신의 값으로 가집니다.
*p 는 p가 가리키는 곳으로 따라가서 실제 값(true)을 가져옵니다.

간단해 보이지만, 두고두고 사람을 헷갈리게 만드는 요소입니다. 제가 그렇습니다.

nil 포인터 - 아무것도 가리키지 않는 포인터

포인터에는 한 가지 특별한 값이 있는데요, 바로 nil 입니다. 다른 언어의 null 과 비슷한 개념이라고 생각하시면 됩니다. 포인터를 선언만 하고 아무 주소도 할당하지 않으면 zero value인 nil 이 되죠.

var p *bool // 선언만 함 -> p는 nil
fmt.Println(p) // <nil>

if p == nil {
 fmt.Println("p는 아무것도 가리키지 않습니다")
}

fmt.Println(*p) // panic!
 // panic: runtime error: invalid memory address or nil pointer dereference

nil 포인터를 역참조(*p) 하려고 하면 위 코드의 마지막 줄처럼 런타임 패닉이 터집니다. 그래서 포인터를 다룰 때는 사용하기 전에 nil 체크를 하는 습관이 중요합니다.

도대체 이런 포인터를 왜 사용하게 된 걸까요? 메모리를 빠르고 효율적으로 사용하기 위해서 그렇습니다. 좀 더 알아볼까요?

스택(stack) vs 힙(heap)

프로그램이 실행될 때는 스택, 힙 이렇게 2가지 유형의 메모리를 사용합니다.

스택: 여러분이 알고계시는 바로 그 스택입니다. 가장 나중에 들어온 게 가장 먼저 나가는(LIFO) 방식으로 이 타입의 메모리는 관리가 매우 쉽습니다. 메모리에 할당할 때는 스택의 꼭대기를 나타내는 top 포인터를 증가/감소 시키기만 하면 됩니다. 함수가 호출될 때 마다 해당 함수에서 사용하는 모든 지역 변수들을 하나의 프레임으로 구성하여 스택의 꼭대기에 push하고, 함수의 실행이 종료되면 프레임 전체를 pop합니다.
힙: 함수의 실행 주기와 관계없이 프로그램 전체에서 공유되어야 하거나, 스택에 할당되기에 너무 큰 메모리의 경우 힙에 할당됩니다. 스택에서는 함수 실행 주기에 따라 메모리에서 자동적으로 pop을 하는 방식으로 관리가 되지만, 힙은 함수 실행과 관계없이 그대로 남아있습니다. 그래서 주기적으로 가비지 컬렉터(GC)가 더 이상 사용되지 않는 항목을 찾아서 제거하고 메모리를 압축하는 등의 작업을 수행합니다.

이 둘의 차이를 그림으로 보면 이렇습니다.

 STACK (LIFO) HEAP (자유 할당)
 ┌──────────────────────┐
 ┌─────────────────┐ ◄─ top │ ┌────┐ ┌──────┐ │
 │ bar() frame │ (가장 │ │obj1│ │ obj2 │ │
 ├─────────────────┤ 나중에 │ └────┘ └──────┘ │
 │ foo() frame │ push됨) │ ┌────┐ │
 ├─────────────────┤ │ │obj3│ ← GC가 │
 │ main() frame │ │ └────┘ 정리 │
 └─────────────────┘ └──────────────────────┘
 호출 순서: main() → foo() → bar()
 push/pop 으로 관리

아주 단순하게 말하면 값 타입(value type)은 스택에, 참조 타입(reference type)은 힙 메모리에 할당된다고 말할 수 있는데요.(물론 Go 컴파일러는 escape analysis를 수행해서 함수의 수명보다 길게 살아남을 요소들은 힙에 할당하기도 합니다.) 그러면 값 타입과 참조 타입에 대해서 알아보죠.

값 타입(value type) vs 참조 타입(reference type)

일단 값 타입(value type)과 참조 타입(reference type)부터 정리하고 가겠습니다. 너무 기본이지만 어느새 까먹어 버리는 개념이기 때문이죠.

값 타입(value type): int, bool 같은 기본(또는 원시 primitive)타입과 배열, 구조체 등의 복합 타입은 일반적으로 스택에 할당됩니다.
참조 타입(reference type): 슬라이스, 맵, 채널, 인터페이스, 포인터 처럼 힙 메모리 어딘가에 위치하는 실제 데이터를 참조하는 타입입니다.

그런데 사실 참조 타입은 값 타입이기도 합니다. 위에서 설명드린 것 처럼 값 타입이지만, 메모리 어딘가에 위치하는 데이터를 가리키는 포인터를 값으로 가지는 타입을 편의상 참조 타입으로 부르는 거죠.

Go에서는 기본적으로 모든 걸 값으로 전달(pass by value, 값을 복제해서 전달함) 하는데요, 여기에서 참조 타입은 약간 헷갈릴 수도 있게 동작합니다.

다음 코드를 볼까요?

package main

import "fmt"

func main() {
 array1 := [3]int{10, 20, 30} // 값 타입 배열 선언
 fmt.Println(array1) // [10 20 30]

 array2 := array1 // array2 에 array1 할당(pass by value, 배열이 복사됨)
 array2[0] = 100

 fmt.Println(array1) // [10 20 30] array1과 array2는 별개의 복사본이므로 변화 없음

 slice1 := make([]int, 3, 5) // len:3, cap: 5
 slice1[0] = 10
 slice1[1] = 20
 slice1[2] = 30

 fmt.Println(slice1) // [10 20 30]

 slice2 := slice1 // slice1를 slice2에 할당(pass by value)
 slice2[0] = 100

 fmt.Println(slice1) // [100 20 30] slice1과 slice2는 동일한 배열 데이터를 참조함
}

값 타입인 배열의 경우, array2 := array1 에서 배열의 모든 요소들이 새로운 배열로 복제되어 array2에 할당됩니다. 그래서 array2의 데이터를 변경해도 array1은 전혀 영향을 받지 않죠.

참조 타입인 슬라이스의 경우 slice2 := slice1 에서 값 타입인 슬라이스의 헤더(실제 배열 값을 가리키는 포인터, 슬라이스 요소 개수 len, 배열 길이 cap)만 복제되어 slice2로 전달됩니다. 두 슬라이스 모두 동일한 포인터를 가지고 있기 때문에 slice2의 요소를 변경하면 slice1도 변경된 값을 참조하게 됩니다.

이 차이를 그림으로 보면 한눈에 들어옵니다.

▶ 배열 (값 타입) - array2 := array1 후, array2[0] = 100 까지 실행한 상태

 array1 array2
 ┌──┬──┬──┐ 복사 ┌───┬──┬──┐
 │10│20│30│ ────────► │100│20│30│ ← 완전히 별개의 메모리
 └──┴──┴──┘ └───┴──┴──┘ (array2만 100으로 변경됨)


▶ 슬라이스 (참조 타입) - slice2 := slice1 후, slice2[0] = 100 까지 실행한 상태

 slice1 헤더 slice2 헤더
 ┌──────┬───┬───┐ ┌──────┬───┬───┐
 │ ptr │ 3 │ 5 │ │ ptr │ 3 │ 5 │ ← 헤더만 복사
 └──┬───┴───┴───┘ └──┬───┴───┴───┘
 │ │
 └────────────┬────────────┘
 ▼
 underlying array (힙)
 ┌───┬──┬──┬─┬─┐
 │100│20│30│ │ │ ← 동일한 배열을 공유
 └───┴──┴──┴─┴─┘ (slice2의 변경이 slice1에도 보임)
 len=3 cap=5

배열은 통째로 복제되어 두 개의 독립된 메모리가 되지만, 슬라이스는 헤더만 복제되고 실제 데이터(underlying array)는 하나를 공유합니다. 그래서 slice2[0] = 100 으로 변경한 값이 slice1 에서도 보이는 거죠.

구조체도 헷갈리게…

Go는 OOP를 지원하긴 하지만, 클래스를 사용하지 않습니다. 이 부분이 저도 처음엔 좀 의아하긴 했는데요, Go는 값 타입인 구조체를 활용해서 이 문제를 해결합니다.

package main

import "fmt"

type Counter struct {
 count int
}

func main() {
 counter1 := Counter{count: 1}
 fmt.Println(counter1) // {1}

 counter2 := counter1
 counter2.count = 10

 fmt.Println(counter1) // {1}
}

구조체는 값 타입이기 때문에 counter1을 counter2에 대입할 때 count 값이 새로운 복제본으로 복사되어 전달됩니다.

구조체의 메서드 정의

클래스는 지원하는 언어는 클래스의 내부에 메서드(멤버 메서드)를 정의합니다. 하지만 Go는 클래스 대신 구조체를 사용하죠. 그래서 구조체 외부에 메서드를 정의하고 그 메서드의 수신자가 누구인지를 명시하도록 되어 있습니다.

package main

import "fmt"

type Counter struct {
 count int
}

// 값 수신자(value receiver) - 복사본에 대해 수행
func (c Counter) IncrementOnCopy() {
 c.count++
}

// 포인터 수신자(pointer receiver) - 원본에 대해 수행
func (c *Counter) Increment() {
 c.count++ // 원래는 (*c).count++ 이어야 하지만, Go는 자동으로 참조를 해제해준다
}

func main() {
 counter := &Counter{count: 0}
 // 위 라인은 아래 두 줄과 동일
 // tmp := Counter{count: 0}
 // counter := &tmp

 fmt.Println("복사본에 대해 카운트 증가")
 for i := 0; i < 5; i++ {
 counter.IncrementOnCopy()
 fmt.Printf("%d번 증가: %d \n", i+1, counter.count)
 }

 fmt.Println("원본에 대해 카운트 증가")
 for i := 0; i < 5; i++ {
 counter.Increment()
 fmt.Printf("%d번 증가: %d \n", i+1, counter.count)
 }
}

위 코드의 실행결과는 다음과 같습니다.

❯ go run .
복사본에 대해 카운트 증가
1번 증가: 0
2번 증가: 0
3번 증가: 0
4번 증가: 0
5번 증가: 0
원본에 대해 카운트 증가
1번 증가: 1
2번 증가: 2
3번 증가: 3
4번 증가: 4
5번 증가: 5

Go에서는 데이터를 전달할 때 항상 값으로 전달(pass by value)을 사용합니다. 따라서 값 수신자에 전달되는 구조체 데이터 역시 복제되어 전달됩니다. 아무리 IncrementOnCopy() 를 호출해도 복사본에 대해 수행되기 때문에 카운트는 제자리에 멈추게 됩니다.

포인터 수신자는 구조체의 참조를 전달받아 연산을 수행하기 때문에 원본의 값을 변경하게 되고 카운트가 계속 증가하게 됩니다.

이 차이를 그림으로 정리하면 다음과 같습니다.

▶ 값 수신자: func (c Counter) IncrementOnCopy()

 [호출자의 메모리] [함수의 스택 프레임]

 counter 값 복사 c (Counter의 복사본)
 ┌────────┐ ───────────► ┌────────┐
 │count: 0│ │count: 0│
 └────────┘ └───┬────┘
 ▲ │ c.count++
 │ ▼
 │ ┌────────┐
 │ ── 함수가 끝나도 ── │count: 1│ ← 복사본만 증가
 └── 여전히 count: 0 └────────┘
 함수 종료 → c 폐기


▶ 포인터 수신자: func (c *Counter) Increment()

 [호출자의 메모리] [함수의 스택 프레임]

 counter 주소(&counter) 전달 c (*Counter)
 ┌────────┐ ─────────────────► ┌────────────┐
 │count: 0│ │0xc000014090│
 │ ↓ │ ◄── (*c).count++ 으로 ───── │ (원본을 │
 │count: 1│ 원본을 직접 수정 │ 가리킴) │
 └────────┘ └────────────┘
 원본이 변경됨

IncrementOnCopy() 는 호출할 때마다 매번 새로운 복사본을 만들어 그 위에서 1을 더한 뒤, 함수가 끝나면 복사본은 사라집니다. 그래서 원본인 counter.count 는 계속 0인 거죠. 반면 Increment() 는 counter 의 주소만 받기 때문에 함수 안에서 c.count++ 를 하면 원본의 메모리가 직접 바뀝니다.

`new()` 와 `&Counter{}` - 둘 다 구조체 포인터를 만들어요

위 예시에서 counter := &Counter{count: 0} 으로 구조체 포인터를 만들었는데요, Go에는 내장 함수 new() 라는 또 다른 방법도 있습니다.

counter1 := &Counter{} // 빈 구조체 포인터 (모든 필드가 zero value)
counter2 := new(Counter) // 위와 동일한 결과

counter3 := &Counter{count: 10} // 초기값을 지정하고 싶다면 이쪽

new(T) 는 타입 T의 zero value를 가지는 새 메모리를 할당하고 그 포인터를 돌려주는 내장 함수입니다. 초기화할 필드가 없다면 new(Counter) 가 좀 더 간결하긴 한데요, 실제로는 초기값을 함께 지정하는 경우가 대부분이라서 &Counter{...} 쪽이 훨씬 자주 사용됩니다.

참고자료

Tucker의 Go 언어 프로그래밍
Claude

npm 공급망 공격 방어 가이드: min-release-age 설정하기

Mon, 20 Apr 2026 21:17:43 +0900

이 문서는 CLAUDE를 통해 작성되었습니다.

목적: 이 가이드는 npm 생태계에 대한 공급망 공격(Supply Chain Attack) 으로부터 개발자와 조직을 보호하기 위한 실무 설정 가이드입니다. macOS, Windows 모두에서 동일하게 적용할 수 있도록 작성되었습니다.

배경: 왜 이 설정이 필요한가 — axios 사태 (2026년 3월 31일)

2026년 3월 31일, 주당 약 1억 회 다운로드되는 인기 HTTP 클라이언트 라이브러리 axios 의 메인테이너 npm 계정이 탈취되어, 악성 버전 axios@1.14.1과 axios@0.30.4가 npm 레지스트리에 공개되었습니다.

공격 요약

공격자는 사회공학 기법(위장된 회사, 가짜 Slack/Teams 미팅)으로 메인테이너 계정을 탈취했습니다.
악성 버전은 plain-crypto-js@4.2.1이라는 별도의 악성 패키지를 의존성으로 주입했습니다.
해당 패키지의 postinstall 훅은 npm install 실행 즉시 macOS / Windows / Linux용 RAT(원격 제어 트로이목마)을 자동으로 다운로드하여 실행했습니다.
코드를 한 줄도 import 하지 않고, 단지 설치만 해도 감염되었습니다.
악성 버전은 공개 후 약 3시간 뒤에 npm 레지스트리에서 제거되었습니다.

핵심 교훈

만약 새 패키지 버전의 설치를 단 하루만 지연시켰다면, 대부분의 개발자는 이 공격에서 안전했을 것입니다.

대부분의 악성 npm 패키지는 보안 연구자들에 의해 수 시간 내에 탐지·제거됩니다. 따라서 갓 출시된 버전의 설치를 일정 기간 지연시키는 “쿨다운(cooldown)” 전략이 가장 단순하고 강력한 공급망 공격 방어 수단 중 하나입니다.

npm CLI는 11.10.0 버전부터 이 기능을 min-release-age 설정으로 제공합니다.

전체 절차 개요

Node.js 및 npm 버전 확인
Node.js를 24.x로 업그레이드 (필요 시)
npm을 11.10.0 이상으로 업그레이드
min-release-age 설정
설정이 실제로 적용되는지 검증
추가 보안 설정 (선택)

1단계: 현재 버전 확인

터미널(macOS: Terminal / Windows: PowerShell 또는 CMD)을 열고 다음을 실행합니다.

node -v
npm -v

요구 버전

Node.js: v24.x 이상 (npm 11은 공식적으로 Node 24와 함께 제공됨)
npm: 11.10.0 이상

두 버전 모두 충족한다면 3단계로 건너뛸 수 있습니다.

2단계: Node.js 설치 / 업그레이드

Node 버전을 유연하게 관리하기 위해 nvm(Node Version Manager) 사용을 권장합니다.

macOS / Linux — nvm

nvm 설치 (이미 설치되어 있다면 생략):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

설치 후 새 터미널을 엽니다. 그 다음:

# 최신 Node 24.x 설치 및 기본값으로 지정
nvm install 24
nvm alias default 24

이미 Node 24.x가 설치된 경우, 최신 패치 버전으로 업데이트:

nvm install 24 --reinstall-packages-from=current
nvm alias default 24

--reinstall-packages-from=current는 기존에 전역 설치한 패키지들을 새 버전으로 자동 이전합니다.

Windows — nvm-windows

Windows는 별도의 프로젝트인 nvm-windows를 사용합니다.

https://github.com/coreybutler/nvm-windows/releases 에서 nvm-setup.exe 다운로드 후 설치
관리자 권한으로 PowerShell 또는 CMD 실행

# 최신 Node 24.x 설치
nvm install 24

# 설치된 24.x 중 하나를 활성화
nvm use 24

Windows에서 최신 패치 버전으로 업데이트:

nvm install 24
nvm use 24
# (선택) 이전 버전 제거
nvm uninstall <이전버전>

설치 확인

node -v # v24.x.x 가 출력되어야 함

3단계: npm 11.10.0 이상으로 업그레이드

Node 24를 설치해도 번들된 npm이 11.10.0보다 낮을 수 있습니다.

npm -v

11.10.0 미만이라면 업그레이드:

npm install -g npm@latest

nvm 사용자 참고: 이 명령은 -g로 설치하지만, nvm이 각 Node 버전마다 독립된 전역 디렉터리를 두기 때문에 sudo / 관리자 권한 없이 실행할 수 있습니다. 단, 이렇게 업그레이드한 npm은 현재 활성화된 Node 버전에만 적용됩니다. 다른 Node 버전으로 전환(nvm use)하면 해당 버전에 번들된 npm으로 되돌아갑니다.

확인:

npm -v # 11.10.0 이상이어야 함

4단계: `min-release-age` 설정

사용자 수준 .npmrc 파일에 설정을 추가합니다. 이 파일의 위치는 OS별로 다릅니다.

macOS / Linux: ~/.npmrc
Windows: C:\Users\<사용자명>\.npmrc

OS 공통 명령으로 설정:

npm config set min-release-age 7

7은 일(day) 단위입니다 (pnpm은 분 단위이니 혼동 주의). 권장값:

값	설명	적합한 환경
`1`	최소 방어. 대부분의 악성 패키지는 수 시간 내 제거됨	빠른 업데이트가 필요한 개인 프로젝트
`3`	균형 잡힌 선택. Renovate Bot의 권장 기본값	일반 팀/프로젝트
`7`	견고한 방어. 일반적으로 추천	대부분의 팀에 적합
`14`+	매우 보수적	엔터프라이즈 / 금융권

파일 내용 확인

macOS / Linux:

cat ~/.npmrc

Windows (PowerShell):

Get-Content $HOME\.npmrc

출력에 min-release-age=7이 포함되어 있으면 정상입니다.

5단계: 설정이 실제로 작동하는지 검증

⚠️ 알려진 버그 주의: 현재 npm 버전(~11.12.x)에서는 npm config get min-release-age가 null을 반환하는 표시 버그(npm/cli#9199)가 있습니다. 실제 기능은 정상 동작합니다. 따라서 config get 대신 아래의 실제 설치 시험으로 검증하세요.

최근 7일 이내에 배포된 버전을 찾아 설치 시도

# 최근에 자주 배포되는 패키지의 버전 히스토리 확인
npm view @types/node time --json

출력에서 최근 7일 이내 날짜의 버전을 하나 고릅니다. 그 다음 임시 폴더에서:

macOS / Linux:

mkdir -p /tmp/npm-test && cd /tmp/npm-test
npm install @types/node@<최근버전> --dry-run

Windows (PowerShell):

mkdir $env:TEMP\npm-test; cd $env:TEMP\npm-test
npm install @types/node@<최근버전> --dry-run

성공 시 출력 예시

npm error code ETARGET
npm error notarget No matching version found for @types/node@X.X.X
 with a date before 2026/M/D, HH:MM:SS.

“with a date before ...” 의 날짜가 오늘로부터 설정한 일수 이전이면 정상 동작 중입니다. 설정된 기간보다 최근에 배포된 버전은 설치가 거부됩니다.

긴급 상황 대응: 일회성으로 제한 우회

긴급 CVE 패치가 출시되어 최신 버전을 즉시 설치해야 하는 경우, 한 번만 제한을 우회할 수 있습니다:

npm install <패키지명> --min-release-age=0

전역 .npmrc 설정은 유지되며, 이 명령에서만 제한이 무시됩니다.

주의사항 및 한계

npm ci는 영향을 받지 않습니다. min-release-age는 npm install의 의존성 해결 과정에 적용됩니다. package-lock.json이 이미 있고 npm ci로 설치하는 경우(주로 CI 환경), 락파일에 고정된 버전을 설치하므로 이 설정과 무관합니다. → 개발자의 로컬 머신에서 락파일에 악성 버전이 고정되는 것을 막는 것이 핵심 방어선입니다.
~ 버전 범위 관련 버그. 의존성에 ~1.2.3처럼 ~ 범위 지정자가 포함된 경우 min-release-age가 에러를 일으킬 수 있습니다 (npm/cli#9005). 수정되기 전까지는 ^를 사용하는 것을 권장합니다.
숫자만 허용. 7d, 7days 같은 문자 접미사 형식은 지원하지 않습니다. 오직 정수(일수) 만 유효한 값입니다.
예외 목록 미지원. pnpm과 달리 현재 npm은 “이 패키지만 예외” 같은 화이트리스트 기능이 없습니다(npm/cli#8979). 긴급한 경우 위의 --min-release-age=0 플래그로 우회하세요.

추가 보안 권장 사항 (axios 공격에서 배운 교훈)

min-release-age는 공급망 공격 방어의 첫 번째 방어선일 뿐입니다. 다음 조치들을 함께 적용하면 훨씬 안전합니다.

(1) `package-lock.json`을 반드시 Git에 커밋

락파일이 있어야 npm ci로 재현 가능한 설치가 가능하고, 의도치 않은 버전 업그레이드를 막을 수 있습니다.

(2) CI에서는 `npm install` 대신 `npm ci` 사용

npm ci

락파일에 고정된 버전만 설치하므로, 악성 패키지가 떠도 CI가 자동으로 업그레이드하지 않습니다.

(3) 프로덕션 빌드에서 lifecycle script 비활성화 고려

npm config set ignore-scripts true

postinstall 같은 훅이 실행되지 않아 axios 사례와 같은 공격 대부분을 원천 차단합니다. 단, 일부 정상 패키지(네이티브 바인딩 포함)는 빌드에 실패할 수 있으므로 CI에서 먼저 검증 후 적용하세요.

(4) axios 감염 여부 직접 점검

현재 프로젝트에 악성 버전이 혹시 들어와 있지 않은지 확인:

npm ls axios
npm ls plain-crypto-js

다음 중 하나라도 발견되면 즉시 감염으로 간주하고 조치하세요:

axios@1.14.1
axios@0.30.4
plain-crypto-js(모든 버전)

조치 절차

해당 머신의 모든 자격증명 즉시 회전(rotate): API 키, SSH 키, GitHub/npm 토큰, 클라우드 크리덴셜 등
캐시 삭제:
```
npm cache clean --force
```
안전한 버전으로 다운그레이드 (axios@1.14.0 또는 axios@0.30.3)
CI/CD 로그에서 2026년 3월 31일 00:21 UTC ~ 03:15 UTC 사이 npm install 실행 이력 검토

참고 자료

최종 업데이트: 2026년 4월 16일

go를 알아보자(2) - gRPC

Sun, 22 Mar 2026 10:34:52 +0900

paxos 기반의 분산 key-value 스토어 를 만들면서 가장 처음에 ‘뭐지?’ 싶었던 건 gRPC였습니다. gRPC자체를 몰랐다기 보다는 뭔가 코드가 완전 암호같아 보였기 때문이죠. 그래서 gRPC만 우선 따로 간단하게 이해해보자 하고 간단한 앱을 만들어 보고 한 줄씩 따라가면서 이해해보려고 노력했습니다.

gRPC란?

RPC(Remote Procedure Call)은 원격, 그러니까 실행되는 프로그램 입장에서 자신이 아닌 외부의 함수를 호출하는 걸 뜻합니다. 그럼 g는 뭐냐 싶었는데 찾아보니 이건 좀 개발자들의 말장난 같은 느낌이네요… 버전마다 뜻이 다르답니다. 뭐 그렇다니까 그렇겠죠…

어쨌거나 gRPC는 바이너리 형식인 Protocol Buffer(protobuf)를 사용해서 REST에 비해 매우 빠르고, 엄격하게 주고 받을 데이터 및 호출할 함수에 대한 정의를 해줄 수 있는 등의 장점이 있습니다. 단점이라면… 코드가 기존 REST에 비해서 좀 이해하기 어렵다? 별도의 코드 생성과정이 필요하다? 뭐 이런게 있겠네요. 그래서 저도 좀 이해하기가 어려웠었죠.

항목	REST	gRPC
프로토콜	HTTP/1.1 (주로)	HTTP/2
데이터 형식	JSON (텍스트)	Protocol Buffers (바이너리)
계약 정의	OpenAPI/Swagger (선택)	.proto 파일 (필수)
스트리밍	제한적	양방향 스트리밍 지원
브라우저 지원	네이티브	gRPC-Web 필요

그냥 한 번 해보자!

자 그럼 일단 그냥 한 번 해보죠. 아주 간단하게 서버와 클라이언트가 인사를 주고 받는 예제를 만들어 보겠습니다.

폴더 생성 및 go 모듈을 초기화

grpc-helloworld 폴더를 만들고 모듈을 초기화 합니다.

> mkdir grpc-helloworld
> cd grpc-helloworld
> go mod init grpc-helloworld

gRPC 계약(contract) 작성

이제 gRPC를 통해 어떤 메시지를 주고 받을 거며, 어떤 원격의 함수를 호출할 수 있는지 계약(contract)을 정의해주겠습니다. greet.proto 파일에 다음과 같이 작성합니다.

syntax = "proto3";

package greet;

// 생성된 go 코드가 위치할 경로
option go_package = "./pb";

// gRPC를 통해 제공할 서비스(함수 목록)
service Greeter {
 rpc SayHello (HelloRequest) returns (HelloReply) {}
}

// 요청 메시지 형식
message HelloRequest {
 string name = 1; // 필드 번호
}

// 응답 메시지 형식
message HelloReply {
 string message = 1; // 필드 번호
}

추가 설명이 필요 없을 정도로 직관적이죠?

gRPC 코드 생성

이제 proto 파일에 정의된 서비스를 호출 및 응답하는데 사용할 코드를 생성해야 합니다.

# Protocol Buffer 컴파일러 설치
# macos의 경우
> brew install protobuf
# linux(ubuntu / debian)의 경우
# > sudo apt install -y protobuf-compiler

# go install 명령으로 설치된 패키지 경로 설정
> echo 'export PATH="$PATH:$(go env GOPATH)/bin"' >> ~/.zshrc
> source ~/.zshrc

# grpc 관련 패키지 설치
> go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
> go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# 코드 생성
> protoc --go_out=. --go-grpc_out=. greet.proto

pb 폴더를 확인해보면 greet_grpc.pb.go, greet.pb.go 파일 두 개가 생성된 걸 확인할 수 있습니다.

greet.pb.go: proto 파일에 정의된 서비스와 요청/응답 메시지에 대한 정의를 담고 있습니다.
greet_grpc.pb.go: gRPC 클라이언트와 서버의 구현을 담고 있습니다.

서버 코드 작성

일단 코드를 작성하기 전에 다음 명령을 실행하여 부수적으로 필요한 패키지들을 모두 설치하고, go.mod 파일을 정리하도록 합니다.

> go mod tidy

그리고 server/main.go 파일을 다음과 같이 작성합니다.

package main

import (
 "context"
 "log"
 "net"

 "grpc-helloworld/pb"

 "google.golang.org/grpc"
)

type server struct {
 /*
 "protoc --go_out=. --go-grpc_out=. greet.proto" 명령으로 생성된 코드에는 greeterServer, greeterClient 구현이 있음.
 UnimplementedGreeterServer 구조체 역시 protoc가 생성한 것으로 proto 파일에 정의된 Greeter 서비스의 모든 메서드에 대해 껍데기 구현을 가지고 있음.(호출시 codes.Unimplemented 오류 리턴)
 이는 추후 proto 파일에 새로운 메서드가 추가되고, 이에 대한 구현이 되지 않았을 때 컴파일 단계의 오류를 방지하기 위함.
 -> 컴파일은 잘 되지만, 해당 함수를 호출하면 codes.Unimplemented 오류 리턴.
 */
 pb.UnimplementedGreeterServer
}

// pb.UnimplementedGreeterServer의 SayHello 함수를 오버라이드(더 정확히는 덮어서 감추기, shadowing)
func (s *server) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
 return &pb.HelloReply{Message: "Hello " + in.GetName()}, nil
}

func main() {
 // 50051번 포트에 대해 네트워크 리스너를 생성
 lis, err := net.Listen("tcp", ":50051")
 if err != nil {
 log.Fatalf("failed to listen: %v", err)
 }

 // gRPC 서버 생성
 s := grpc.NewServer()
 // Greeter grpc 서비스에 서버를 등록
 pb.RegisterGreeterServer(s, &server{})

 // 서버 시작
 log.Println("Server listening at :50051")
 if err := s.Serve(lis); err != nil {
 log.Fatalf("failed to serve: %v", err)
 }
}

이 코드에서 유심히 봐야 할 내용은(처음에 제가 이해를 못했던 내용은) server 선언부 입니다. 이걸 이해하려면 일단 greet_grpc.pb.go 파일의 다음 내용을 봐야 합니다.

...

// UnimplementedGreeterServer must be embedded to have
// forward compatible implementations.
//
// NOTE: this should be embedded by value instead of pointer to avoid a nil
// pointer dereference when methods are called.
type UnimplementedGreeterServer struct{}

func (UnimplementedGreeterServer) SayHello(context.Context, *HelloRequest) (*HelloReply, error) {
 return nil, status.Error(codes.Unimplemented, "method SayHello not implemented")
}

...

proto 파일에 정의했던 서비스의 함수가 UnimplementedGreeterServer의 메서드로 정의되어 있는데요, 내용을 보면 이 함수가 아직 구현되지 않았다 는 오류 메시지입니다. 그러니까 gRPC 서버를 구현할 때, SayHello 라는 메서드를 직접 구현하지 않으면 대신 이 기본 구현이 실행되면서 서비스를 제공할 함수를 구현해야 한다 고 알려주는 거죠.

근데 왜 이렇게 할까요? 이건 안전장치입니다.

새로운 gRPC 함수가 추가된다고 생각해보죠. 그러면 우선 proto 파일을 수정합니다. 그리고 코드를 생성하죠. 그런데 만약 gRPC 서버 구현을 맡은 사람이 새 함수를 구현하는 걸 깜빡하면 어떻게 될까요? 갑자기 gRPC 서버는 컴파일 조차 되지 않을겁니다. 인터페이스의 함수를 모두 구현하지 못했기 때문이죠.

그런데 기본 구현을 생성해서 그걸 서버 구현에 임베드 하게 된다면? 구현을 못 한 상태에서도 기존 구현은 아무 문제 없이 컴파일 되고 동작합니다!

클라이언트 코드 작성

다음으로 client/main.go를 다음과 같이 작성합니다.

package main

import (
 "context"
 "grpc-helloworld/pb"
 "log"
 "time"

 "google.golang.org/grpc"
 "google.golang.org/grpc/credentials/insecure"
)

func main() {
 // 1. 서버에 연결하기
 conn, err := grpc.NewClient("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
 if err != nil {
 log.Fatalf("failed to dial: %v", err)
 }
 defer conn.Close()

 // 2. GreeterClient 생성
 client := pb.NewGreeterClient(conn)

 // 3. SayHello 메서드 호출(1초 동안 서버가 응답하지 않으면 컨텍스트 취소)
 ctx, cancel := context.WithTimeout(context.Background(), time.Second)
 defer cancel()

 r, err := client.SayHello(ctx, &pb.HelloRequest{Name: "World"})
 if err != nil {
 log.Fatalf("failed to say hello: %v", err)
 }

 log.Printf("Server response: %s", r.GetMessage())
}

gRPC 서버에 연결해서 요청을 보내고 응답을 수신합니다. 만약 요청이 처리되는데 1초 이상 소요된다면, 요청을 취소하게 설정되었습니다.

서버와 클라이언트 실행

2개의 터미널을 열고 먼저 서버를 실행합니다.

❯ go run server/main.go
2026/03/22 10:22:14 Server listening at :50051

그리고 클라이언트를 실행해서 요청을 전송하고 응답을 받습니다.

❯ go run client/main.go
2026/03/22 10:22:51 Server response: Hello World

정리

매우 간단한 예제지만 gRPC 계약 정의와 코드 생성 및 서버와 클라이언트 사용 등의 내용은 충분히 확인할 수 있었습니다. 이걸 몰랐을 때는 완전히 블랙박스 처럼 보였던 코드와 과정을 좀 더 명확하게 이해할 수 있었죠! 이 글의 모든 학습과정은 gemini가 생성한 튜토리얼을 기반으로 저의 삽질을 통해 진행하였습니다.

분산 시스템 설계(1) - Paxos 심화(분산 Key-Value 스토어)

Sun, 22 Mar 2026 10:34:52 +0900

Paxos 알고리즘 관련 세번째 글입니다. 그러니까… 지난 글에서는 아주 간단하게 리더를 선출하는 예제를 만들어 봤었지만, 그게 뭐랄까 좀 예제를 위한 예제 같은 느낌이 들었습니다. Multi-Paxos를 제대로 구현하지도 못했고 말이죠. 그래서 Claude와 함께 고민을 하던 중에 Redis 같은 분산 Key-Value 스토어(이하 dkv)를 만들어 보는 게 어떨까 싶었습니다. 그래서 관련해서 튜토리얼을 생성해내고, 직접 쳐보기도 하면서 Claude Code와 예제를 완성하고 코드를 모두 한 줄씩 읽어가면서 동작을 이해하려 노력해봤습니다.

그 과정의 결과물을 여기 에 올려두었습니다.

간략한 소개

해당 리포지토리에 방문하시면 훨씬 더 상세한 README가 기다리고 있긴 합니다. 해당 내용은 초반에 틀을 제가 손으로 직접 잡고 나머지 부분을 Claude Code와 함께 완성 및 보강했습니다. 여기서는 어떻게 dkv가 동작하는지를 좀 설명드려보고자 합니다.

Paxos Prepare-Accept를 통한 리더 선출

우선 3개의 노드를 실행하는 과정을 볼까요? 일단 첫 번째 노드부터 실행합니다.

❯ go run ./cmd/dkv -id=1
2026/03/17 14:16:53 gRPC listening on 127.0.0.1:9001
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="wal: 재생 완료" node=1 lastApplied=1 totalRecords=42 acceptorStates=41 committedEntries=1
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="paxos: 시작" node=1 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:16:53.495+09:00 level=INFO msg="http: HTTP 서버 시작" node=1 addr=127.0.0.1:8001
Node 1 started — HTTP: 127.0.0.1:8001, gRPC: 127.0.0.1:9001
time=2026-03-17T14:16:54.253+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=1 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:16:54.253+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N1.1 prevNumber=0
time=2026-03-17T14:16:54.256+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N1.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:16:54.256+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N1.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: prepare 거부됨" node=1 peer=1 ballot=N1.1 promisedBallot=N30.1
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: prepare 결과" node=1 promises=0 majority=2 ballot=N1.1 result=실패
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: ballot fast-forward" node=1 from=1 to=30
time=2026-03-17T14:16:54.257+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=1 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N31.1 prevNumber=30
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N31.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:16:54.988+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N31.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: prepare 약속 받음" node=1 peer=1 ballot=N31.1
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: prepare 결과" node=1 promises=1 majority=2 ballot=N31.1 result=실패
time=2026-03-17T14:16:54.994+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 1/2 promises"
...

뭔가 로그가 복잡해 보이지만, 리더 선출을 위한 선거(Prepare)를 진행하고 있습니다. 🟢과 🔴를 주목해서 보시면 선거가 시작됐지만 아직 자신 밖에 없으므로 선거는 실패하고 있습니다. 자 이제 2번 노드 투입합니다!

❯ go run ./cmd/dkv -id=2
2026/03/17 14:17:01 gRPC listening on 127.0.0.1:9002
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="wal: 재생 완료" node=2 lastApplied=1 totalRecords=20 acceptorStates=19 committedEntries=1
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="paxos: 시작" node=2 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:17:01.908+09:00 level=INFO msg="http: HTTP 서버 시작" node=2 addr=127.0.0.1:8002
Node 2 started — HTTP: 127.0.0.1:8002, gRPC: 127.0.0.1:9002
time=2026-03-17T14:17:02.429+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=2 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:02.429+09:00 level=INFO msg="election: 🟢 prepare 시작" node=2 ballot=N1.2 prevNumber=0
time=2026-03-17T14:17:02.431+09:00 level=INFO msg="election: prepare 전송 실패" node=2 peer=3 ballot=N1.2 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.431+09:00 level=INFO msg="election: prepare 거부됨" node=2 peer=1 ballot=N1.2 promisedBallot=N42.1
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: prepare 거부됨" node=2 peer=2 ballot=N1.2 promisedBallot=N25.1
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: prepare 결과" node=2 promises=0 majority=2 ballot=N1.2 result=실패
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: ballot fast-forward" node=2 from=1 to=42
time=2026-03-17T14:17:02.432+09:00 level=INFO msg="election: 실패" node=2 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=2 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: 🟢 prepare 시작" node=2 ballot=N43.2 prevNumber=42
time=2026-03-17T14:17:02.991+09:00 level=INFO msg="election: prepare 전송 실패" node=2 peer=3 ballot=N43.2 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.996+09:00 level=INFO msg="election: prepare 약속 받음" node=2 peer=2 ballot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 약속 받음" node=2 peer=1 ballot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 결과" node=2 promises=2 majority=2 ballot=N43.2 result=성공
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: 미커밋 엔트리 재제안" node=2 slot=1 ballot=N43.2 key=hahaha
time=2026-03-17T14:17:03.008+09:00 level=INFO msg="election: 🎉 리더 당선" node=2 ballot=N43.2 committedUpTo=1

마지막 줄을 보시면 2번 노드는 시작되자 마자 과반수의 지지를 받아 리더가 됩니다! 이때 1번 노드의 상황을 볼까요?

...
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: 🟢 prepare 시작" node=1 ballot=N43.1 prevNumber=42
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=3 ballot=N43.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9003: connect: connection refused\""
time=2026-03-17T14:17:02.997+09:00 level=INFO msg="election: prepare 전송 실패" node=1 peer=2 ballot=N43.1 err="rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:9002: connect: connection refused\""
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 거부됨" node=1 peer=1 ballot=N43.1 promisedBallot=N43.2
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: prepare 결과" node=1 promises=0 majority=2 ballot=N43.1 result=실패
time=2026-03-17T14:17:03.000+09:00 level=INFO msg="election: 실패" node=1 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:03.110+09:00 level=INFO msg="heartbeat: 새 리더 감지" node=1 leader=2 ballot=N43.2 prevLeader=0
...

자신이 리더가 되고자 하는 요청(Prepare)는 한 표도 받지 못했고, 2번 노드가 2표를 모두 약속받은 뒤 Accept까지 진행해버렸기 때문에 2번 노드가 새로운 리더임을 인정하게 됩니다.

이제 3번 노드가 또 합류합니다!

❯ go run ./cmd/dkv -id=3
2026/03/17 14:17:11 gRPC listening on 127.0.0.1:9003
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="wal: 재생 완료" node=3 lastApplied=1 totalRecords=31 acceptorStates=30 committedEntries=1
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="paxos: 시작" node=3 peers="[1 2 3]" electionTimeout=500ms heartbeatInterval=100ms
time=2026-03-17T14:17:11.717+09:00 level=INFO msg="http: HTTP 서버 시작" node=3 addr=127.0.0.1:8003
Node 3 started — HTTP: 127.0.0.1:8003, gRPC: 127.0.0.1:9003
time=2026-03-17T14:17:12.468+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=3 elapsed=2562047h47m16.854775807s threshold=500ms
time=2026-03-17T14:17:12.469+09:00 level=INFO msg="election: 🟢 prepare 시작" node=3 ballot=N1.3 prevNumber=0
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=2 ballot=N1.3 promisedBallot=N43.2
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=3 ballot=N1.3 promisedBallot=N34.3
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=1 ballot=N1.3 promisedBallot=N43.2
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: prepare 결과" node=3 promises=0 majority=2 ballot=N1.3 result=실패
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: ballot fast-forward" node=3 from=1 to=43
time=2026-03-17T14:17:12.471+09:00 level=INFO msg="election: 실패" node=3 err="🔴election failed: 0/2 promises"
time=2026-03-17T14:17:13.092+09:00 level=INFO msg="election: 타이머 발동, 선거 시작" node=3 elapsed=2562047h47m16.854775807s threshold=500ms
...
time=2026-03-17T14:17:16.468+09:00 level=INFO msg="election: 🟢 prepare 시작" node=3 ballot=N49.3 prevNumber=48
time=2026-03-17T14:17:16.469+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=2 ballot=N49.3 promisedBallot=N43.2
time=2026-03-17T14:17:16.469+09:00 level=INFO msg="election: prepare 거부됨" node=3 peer=1 ballot=N49.3 promisedBallot=N43.2
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: prepare 약속 받음" node=3 peer=3 ballot=N49.3
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: prepare 결과" node=3 promises=1 majority=2 ballot=N49.3 result=실패
time=2026-03-17T14:17:16.472+09:00 level=INFO msg="election: 실패" node=3 err="🔴election failed: 1/2 promises"
time=2026-03-17T14:17:17.109+09:00 level=INFO msg="heartbeat: 새 리더 감지" node=3 leader=2 ballot=N43.2 prevLeader=0

처음에는 자신을 리더로 제안(Propose)하지만, 결국 2번 노드가 리더임을 인정하게 됩니다.

Paxos Accept를 통한 key-value 전파

3번 노드에 키를 gundam으로 하고 값을 건담이말을건담으로 넣어볼까요?

❯ curl -L -X PUT http://127.0.0.1:8003/kv/gundam -d "건담이말을건담"
OK (index=2)

참고로 -L 플래그는 요청이 리다이렉트 될 수 있도록 해줍니다. 현재 dkv는 리더가 아닌 노드에게 쓰기 요청을 하면 해당 요청을 리더에게 리다이렉트 하도록 구현되었거든요! 자 그럼 1번 노드에서 키를 조회해볼까요?

❯ curl http://127.0.0.1:8001/kv/gundam
건담이말을건담

3번 노드가 쓰기 요청을 리더인 2번 노드에게 전달하고, 리더는 다른 노드들에 Accept 요청을 전송해서 쓰기 요청이 다른 노드에 전파되도록 합니다. 그래서 1번 노드에서도 키로 값을 조회해올 수 있는 거죠.

리더 선출 과정에서 이미 Prepare를 거쳤기 때문에 바로 Accept단계로 넘어갑니다!

정리

이걸 구현하고 이해해보려고 노력하면서 왜 Paxos가 더 이상 쓰이지 않는지 이해했습니다. 이게 좀 많이 복잡하네요. 솔직히 아직도 좀 헷갈립니다. 다음 부터는 dkv를 만드는 과정에서 제가 새롭게 배운 내용들을 따로 한 번 정리해보려고 합니다. 그러고 나서 Raft를 추가로 구현해볼 생각입니다.

분산 시스템 설계(1) - Paxos 알고리즘(GO)

Sun, 22 Feb 2026 08:03:55 +0900

지난 글에서는 Paxos 알고리즘에 대해서 정리를 했고, 리더 선출 예시를 살펴보면서 구체적인 알고리즘 동작과정을 살펴봤습니다. 해당 예시는 node.js로 작성을 했었죠. 이번에는 그 예시의 Go 버전을 확인해볼까 합니다. 이유는… 별게 없고 그냥 제가 최근에 Go를 좀 보기 시작 했기 때문입니다! 하하하하하….

구조와 동작은 지난 글의 내용과 똑같습니다. 다만, Go는 접근 방식이 다르다 보니 구체적인 구현에서는 좀 차이를 보이는데요. 그런 특징적인 부분들을 정리해보고자 합니다. 미래의 저를 위해서 말이죠!

코드 실행 방법

go는 원래 컴파일을 통해 실행 파일을 생성하지만, 다음 명령을 통해 바로 실행 해볼 수 있으며, 실행 과정은 이전의 node.js 버전과 동일합니다!

> go run . cluster

go run 명령도 컴파일을 합니다! 컴파일을 통해 임시 바이너리를 생성해서 실행을 하지만, 눈에 보이지 않을 뿐입니다. 개발 중에 계속 컴파일 -> 실행은 너무 귀찮죠 하하하하…

프로그램 진입점 구현

프로그램이 시작되는 main.go는 다음과 같습니다.

package main

import (
 "fmt"
 "os"
)

func main() {
 if len(os.Args) < 2 {
 fmt.Println("사용법:")
 fmt.Println(" go run . cluster -- 클러스터 모드 (3개 노드 실행)")
 os.Exit(1)
 }

 switch os.Args[1] {
 case "node":
 runNode() // 클러스터 관리 cli가 각 노드를 실행할 때 사용
 case "cluster":
 runCluster() // 클러스터 관리 cli를 실행
 default:
 fmt.Printf("알 수 없는 명령어: %s\n", os.Args[1])
 os.Exit(1)
 }
}

프로그램에 설정된 인자에 따라서 서로 다른 모드로 실행합니다.

cluster: 클러스터 관리 cli를 실행
node: 서버 노드를 실행

앞서 실행 방법에서 봤듯이 우리는 “cluster” 모드로 클러스터 관리 cli를 실행합니다. 그리고 클러스터 관리 cli가 “node” 모드로 3개의 서버 노드를 실행하게 되죠. main.go와 이후에 살펴볼 cluster.go, node.go 가 모두 같은 main 패키지에 포함되어 있기 때문에 다른 파일의 함수를 자유롭게 가져다 쓸 수 있습니다.

클러스터 관리자 cli 구현

cluster.go의 전체 소스코드는 다음과 같습니다.

package main

import (
 "bufio"
 "encoding/json"
 "fmt"
 "net/http"
 "os"
 "os/exec"
 "os/signal"
 "strconv"
 "strings"
 "sync"
 "syscall"
 "time"
)

type nodeConfig struct {
 id int
 port int
}

// 각 노드 아이디와 포트 번호 정의
var nodes = []nodeConfig{
 {id: 1, port: 3001},
 {id: 2, port: 3002},
 {id: 3, port: 3003},
}

// 가독성을 위해 각 노드의 아이디별 출력 색상 정의
var colors = map[int]string{
 1: "\033[36m", // 파란색 (cyan)
 2: "\033[33m", // 노란색
 3: "\033[35m", // 핑크색 (magenta)
}

const colorReset = "\033[0m"

// 노드 프로세스 관리를 위한 맵 정의
var (
 // 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
 processes = make(map[int]*exec.Cmd)
 // 맵에 대한 동시성 접근을 위한 뮤텍스(lock)
 processesMu sync.Mutex
)

// 노드 프로세스 시작 처리 함수
func startNode(nc nodeConfig) {
 // 현재 노드가 통신해야 할 다른 노드의 URL 목록 생성
 var peers []string
 for _, n := range nodes {
 if n.id != nc.id {
 peers = append(peers, fmt.Sprintf("http://localhost:%d", n.port))
 }
 }

 color := colors[nc.id]
 fmt.Printf("%s노드 %d 시작...%s\n", color, nc.id, colorReset)

 // 노드 프로세스 생성
 args := []string{"run", ".", "node", strconv.Itoa(nc.id), strconv.Itoa(nc.port)}
 args = append(args, peers...)

 cmd := exec.Command("go", args...)

 stdout, err := cmd.StdoutPipe()
 if err != nil {
 fmt.Printf("노드 %d stdout pipe 실패: %v\n", nc.id, err)
 return
 }
 stderr, err := cmd.StderrPipe()
 if err != nil {
 fmt.Printf("노드 %d stderr pipe 실패: %v\n", nc.id, err)
 return
 }

 if err := cmd.Start(); err != nil {
 fmt.Printf("노드 %d 시작 실패: %v\n", nc.id, err)
 return
 }

 // 여러 goroutine에서 동시에 접근할 수 있으므로, 동시성 접근을 위해 뮤텍스를 사용
 processesMu.Lock()
 processes[nc.id] = cmd
 processesMu.Unlock()

 // goroutine: 노드 프로세스의 출력에 색상을 적용하여 출력
 go func() {
 scanner := bufio.NewScanner(stdout)
 for scanner.Scan() {
 fmt.Printf("%s%s%s\n", color, scanner.Text(), colorReset)
 }
 }()

 // goroutine: 노드 프로세스의 에러 출력에 색상을 적용하여 출력
 go func() {
 scanner := bufio.NewScanner(stderr)
 for scanner.Scan() {
 fmt.Printf("%s[노드 %d 에러] %s%s\n", color, nc.id, scanner.Text(), colorReset)
 }
 }()

 // goroutine: 노드 프로세스가 종료될 때 처리
 go func() {
 err := cmd.Wait()
 exitCode := -1
 if cmd.ProcessState != nil {
 exitCode = cmd.ProcessState.ExitCode()
 }
 fmt.Printf("%s[노드 %d] 프로세스 종료 (code: %d, err: %v)%s\n",
 color, nc.id, exitCode, err, colorReset)

 processesMu.Lock()
 delete(processes, nc.id)
 processesMu.Unlock()
 }()
}

// 노드 프로세스 종료 처리 함수
func killNode(id int) {
 processesMu.Lock()
 // 맵에서 노드 프로세스 조회
 cmd, exists := processes[id]
 processesMu.Unlock()

 // 노드 프로세스가 존재하면 종료
 if exists && cmd.Process != nil {
 if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
 fmt.Printf("[클러스터] 노드 %d 시그널 전송 실패: %v\n", id, err)
 }
 color := colors[id]
 fmt.Printf("\n%s[클러스터] 노드 %d 종료%s\n\n", color, id, colorReset)
 } else {
 fmt.Printf("\n[클러스터] 노드 %d 실행 중이 아님\n\n", id)
 }
}

// 클러스터 상태 출력 함수
func printStatus() {
 fmt.Println("\n=== 클러스터 상태 ===")

 // 타임아웃이 1초인 http.Client 생성
 client := &http.Client{Timeout: 1 * time.Second}

 for _, node := range nodes {
 // 즉시 실행되는 익명 함수. 함수 종료시 defer 처리된 리소스 해제
 func() {
 url := fmt.Sprintf("http://localhost:%d/status", node.port)
 resp, err := client.Get(url)
 color := colors[node.id]

 if err != nil {
 fmt.Printf("%s 노드 %d: 다운%s\n", color, node.id, colorReset)
 return
 }
 // err 발생시 resp는 nil. 따라서 err 체크 후 defer 처리가 일반적인 방법.
 defer resp.Body.Close()

 var data StatusResponse
 // resp.Body를 JSON -> StatusResponse 타입으로 변환; 그리고 err 발생시 처리
 if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
 fmt.Printf("%s 노드 %d: (응답 파싱 실패)%s\n", color, node.id, colorReset)
 return
 }

 leaderMark := " "
 if data.IsLeader {
 leaderMark = "👑"
 }

 leaderStr := "none"
 if data.CurrentLeaderID != nil {
 leaderStr = strconv.Itoa(*data.CurrentLeaderID)
 }
 promisedStr := "none"
 if data.PromisedProposal != nil {
 promisedStr = strconv.Itoa(*data.PromisedProposal)
 }
 acceptedStr := "none"
 if data.AcceptedProposal != nil {
 acceptedStr = strconv.Itoa(*data.AcceptedProposal)
 }

 // 노드 상태 출력
 fmt.Printf("%s%s 노드 %d: leader=%s, term=%d, isLeader=%v, promised=%s, accepted=%s%s\n",
 color, leaderMark, node.id, leaderStr, data.CurrentTerm, data.IsLeader,
 promisedStr, acceptedStr, colorReset)
 }()
 }
 fmt.Println()
}

func isValidNodeID(id int) bool {
 for _, n := range nodes {
 if n.id == id {
 return true
 }
 }
 return false
}

func findNode(id int) *nodeConfig {
 for _, n := range nodes {
 if n.id == id {
 return &n
 }
 }
 return nil
}

// === 대화형 CLI 구현 ===

func runCluster() {
 // 모든 노드 시작
 fmt.Print("\n🚀 Starting Paxos Leader Election Cluster...\n\n")

 for _, node := range nodes {
 startNode(node)
 }

 // 모든 노드가 시작될 때까지 대기 후 명령어 출력
 time.AfterFunc(1*time.Second, func() {
 fmt.Println()
 fmt.Println(strings.Repeat("=", 60))
 fmt.Println("📋 사용 가능한 명령어:")
 fmt.Println(" kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)")
 fmt.Println(" start <id> - 종료된 노드 재시작")
 fmt.Println(" status - 클러스터 상태 출력")
 fmt.Println(" exit - 모든 노드 종료 및 종료")
 fmt.Println(strings.Repeat("=", 60))
 fmt.Println()
 })

 // goroutine 끼리 메세지를 주고받기 위한 채널 생성, 버퍼 크기를 1로 설정하여 수신자가 메세지를 받을 때까지 대기할 수 있도록 함
 sigChan := make(chan os.Signal, 1)
 // Ctrl+C 발생시 해당 시그널을 채널로 전달
 signal.Notify(sigChan, os.Interrupt)

 go func() {
 // 채널에서 메세지(Ctrl+C)를 받을 때까지 대기
 <-sigChan
 fmt.Print("\n\n🛑 모든 노드 종료...\n\n")
 // 모든 노드 프로세스에 SIGTERM 시그널 전송
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)
 }()

 // 대화형 CLI 명령어 처리
 scanner := bufio.NewScanner(os.Stdin)
 // Stdin이 종료될 때까지 한 줄씩 읽어서 처리
 for scanner.Scan() {
 line := strings.TrimSpace(scanner.Text())
 if line == "" {
 continue
 }

 parts := strings.SplitN(line, " ", 2)
 cmd := parts[0]
 arg := ""
 if len(parts) > 1 {
 arg = parts[1]
 }

 // 명령어 처리
 switch cmd {
 case "kill":
 id, err := strconv.Atoi(arg)
 if err != nil || !isValidNodeID(id) {
 fmt.Printf("잘못된 노드 ID: %s\n", arg)
 continue
 }
 killNode(id)

 case "start":
 id, err := strconv.Atoi(arg)
 if err != nil || !isValidNodeID(id) {
 fmt.Printf("잘못된 노드 ID: %s\n", arg)
 continue
 }
 processesMu.Lock()
 _, running := processes[id]
 processesMu.Unlock()
 if running {
 fmt.Printf("\n노드 %d 이미 실행 중\n\n", id)
 } else {
 nc := findNode(id)
 if nc != nil {
 startNode(*nc)
 }
 }

 case "status":
 printStatus()

 case "exit":
 fmt.Print("\n🛑 모든 노드 종료...\n\n")
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)

 case "help":
 fmt.Println("\n📋 사용 가능한 명령어:")
 fmt.Println(" kill <id> - 노드 종료")
 fmt.Println(" start <id> - 종료된 노드 재시작")
 fmt.Println(" status - 클러스터 상태 출력")
 fmt.Println(" exit - 모든 노드 종료 및 종료")

 default:
 fmt.Printf("알 수 없는 명령어: %s. 'help' 명령어를 사용하세요.\n\n", cmd)
 }
 }
}

map 타입

두 군데에서 map을 사용하고 있는데 타입 정의 생김새가 좀 다릅니다.

// 키 타입이 int이고, 값 타입이 string인 맵
var colors = map[int]string{
 1: "\033[36m", // 파란색 (cyan)
 2: "\033[33m", // 노란색
 3: "\033[35m", // 핑크색 (magenta)
}
...
// 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
processes = make(map[int]*exec.Cmd)

우선 배열의 인덱스 처럼 둘러싸인 타입이 키의 타입이고, 그 뒤에 붙은 타입이 값의 타입이다 하는 건 몇 번 보다보면 알 수 있습니다. 그런데 colors는 그냥 map을 생성했고, processes는 make 함수를 호출해서 생성하고 있네요?

우선 colors는 map 리터럴(literal) 방식으로 map을 생성하고 있습니다. map안에 어떤 값이 들어갈지 명시해주면서 생성하고 있죠. 그래서 이 때는 Go가 map의 생성을 암묵적으로(implicitly) 처리해줍니다. 그런데 processes는 빈 map을 생성하고 있습니다. 그래서 암묵적으로 map을 생성할 수 없고, 따라서 make 함수를 호출해서 Go가 런타임 초기화를 실행하도록 해줘야 합니다.

map은 javascript의 map, C#의 Dictionary와 같은 key-value 매핑을 저장하는 자료 구조이고 동작방식도 동일합니다. 다만, Go에서는 map을 생성하기 위해서 make 함수를 사용해야 합니다. map외에도 make 함수를 사용하는 경우는 슬라이스와 채널이 있는데요, 이 타입들은 내부적으로 해시테이블, 동적 배열, 큐 등의 자료구조를 사용하기 때문에 Go가 런타임 초기화를 실행해야 합니다. 그래서 make를 실행해야 한다고 하네요! struct나 배열, int등의 다른 기본 타입들은 make없이도 각 타입의 기본 값(zero value)으로도 충분합니다.

또 한가지 Go의 특징은 map에서 값을 찾을 때도 볼 수 있습니다.

// 맵에서 노드 프로세스 조회
cmd, exists := processes[id]

map에서 값을 조회할 때, 리턴 받을 변수를 2개 지정해주면 2번째 변수에는 map에 특정 키에 해당하는 값이 있는지 여부를 같이 리턴해주는데요, 예를 들어 타입스크립트에서는 다음과 같이 해야 합니다.

const cmd = processes.get(id);
const exists = processes.has(id);

typescript 버전과 비교하면 가독성은 떨어지는 느낌입니다. 하지만 간결하죠? 간결함을 우선하는 Go의 철학이 느껴지네요!

동시성 처리 및 lock 걸기

스레드와 고루틴 비교

각 언어와 런타임은 여러 작업을 동시에 처리하기 위해 스레드(thread)를 활용합니다. 스레드는 간단하게 말하면, 코드 실행 묶음이라고 볼 수 있는데요, CPU의 각 코어는 한 번에 하나의 스레드만 처리할 수 있습니다. 예를 들어 1번 코어가 처리 중인 스레드가 네트워크를 통해 응답이 아주 오래걸리는 요청을 처리 중이라면 어떻게 될까요? 1번 코어가 그 스레드를 계속 처리하게 둔다면 우리는 코어 1개를 낭비하는 셈이죠. OS는 이런 비효율을 참지 못합니다. 오래 걸리는 스레드는 응답이 올 때 까지 잠깐 대기 시키고 다른 스레드를 처리하게 하는 등 멀티 스레드 작업을 진행하게 하죠. 언어와 런타임은 이런 OS의 스레드 관리를 기반으로 해서 자체적인 동시성 처리 모델을 제시합니다.

다만, 이 멀티 스레드라는 게 공짜가 아닙니다. 코어가 처리해야 되는 스레드를 변경할 때는 문맥 교환(context-switching)이 발생합니다. 스레드1->스레드2로 문맥 교환되는 과정을 간략하게 살펴보면요,

커널 모드 진입*: CPU는 필요한 권한을 얻기 위해 유저 모드에서 커널 모드로 진입
스레드1의 상태 저장: CPU 레지스터, 프로그램 카운터, 스택 포인터 등 스레드1의 모든 상태를 스레드1의 메모리 블록에 기록(TCB, Thread Control Block)
스케쥴러 상태 갱신: OS가 스레드1을 대기 상태로 설정하고 스레드2를 대기 큐에서 선택
TLB/cache 초기화*: 스레드1과 스레드2가 서로 다른 프로세스의 스레드라면, TLB(translation lookaside buffer)를 초기화
스레드2의 상태 불러오기: 스레드2의 TCB에서 모든 상태를 불러오기
유저 모드로 복귀*: CPU가 유저 모드로 돌아와서 스레드2의 이전 상태로 부터 계속 실행

저도 정확하게 다 아는 건 아니지만, 어쨌든 이런 복잡한 작업을 매번 진행해야 하고 특히 * 가 붙은 부분들이 비교적 많은 시간이 걸리는 작업이라고 합니다. 게다가 또 하나의 문제점도 있습니다. 저 유명한 StackOverflow 에러를 다들 아시겠지만, OS의 스레드는 대략 1-8MB 정도의 스택 메모리를 가지는데, 스레드 내부에서 발생하는 각 로컬 변수와 함수 호출 등을 기록하기 위해서 사용하죠. 그래서 어마어마하게 큰 로컬 변수나 어마어마하게 복잡한 제귀 호출을 하다보면 띵하고 StackOverflow가 발생합니다. 그런데 Go는 이걸 조금 다르게 접근한다고 하네요.

Go는 이런 동시성 처리의 문제를 고루틴(Goroutine)으로 접근합니다. 고루틴은 OS레벨의 스레드가 아니라 각 스레드에서 스위칭해서 실행할 수 있도록 하는 일종의 경량 스레드라고 할 수 있을 거 같네요. 그리고 OS레벨의 스레드가 아니라는 건, 앞서 살펴본 문맥 교환이 발생하지 않도록 하면서도 수많은 동시성 작업을 처리할 수 있다는 말이 됩니다. 게다가 한 가지 더 장점이 있는데요, 고루틴은 스택 메모리를 유연하게 사용합니다. 매우 작게 시작해서(2-4KB) 필요에 따라 늘리고 줄일 수 있게 설계되었습니다.

그러니까 OS 레벨의 스레드를 사용하는 경우,

graph TD
subgraph OS["OS 커널 (스케줄러)"]
direction LR
OSS["OS 스케줄러<br/>모든 스레드를 직접 관리<br/>⚠️ 비싼 문맥 교환"]
end
subgraph CPU["하드웨어 (4코어)"]
C1["코어 1"]
C2["코어 2"]
C3["코어 3"]
C4["코어 4"]
end
subgraph Threads["OS 스레드 (각 1-8 MB 고정 스택)"]
T1["스레드 1<br/>📦 1 MB 스택"]
T2["스레드 2<br/>📦 1 MB 스택"]
T3["스레드 3<br/>📦 1 MB 스택"]
T4["스레드 4<br/>📦 1 MB 스택"]
T5["스레드 5<br/>📦 1 MB 스택"]
T6["스레드 6<br/>📦 1 MB 스택"]
T7["스레드 7<br/>📦 1 MB 스택"]
T8["스레드 8<br/>📦 1 MB 스택"]
end
T1 & T2 & T3 & T4 & T5 & T6 & T7 & T8 -->|"OS 문맥 교환<br/>🐌 ~1-10 μs<br/>커널 모드 전환 + 레지스터 저장<br/>+ 캐시 플러시"| OSS
OSS --> C1 & C2 & C3 & C4
style OS fill:#8b0000,color:#fff
style CPU fill:#1a3a5c,color:#fff
style Threads fill:#2e2e1a,color:#fff

스레드의 문맥 교환 비용도 막대 하지만, 스레드의 개수 * 스택 메모리 를 계산해보면, 메모리 사용량 역시 부담이 되죠.

하지만 고루틴을 사용하는 경우,

graph TD
subgraph CPU["하드웨어 (4코어)"]
C1["코어 1"]
C2["코어 2"]
C3["코어 3"]
C4["코어 4"]
end
subgraph OSThreads["OS 스레드 (코어에 고정)"]
M1["OS 스레드 1<br/>(M)"]
M2["OS 스레드 2<br/>(M)"]
M3["OS 스레드 3<br/>(M)"]
M4["OS 스레드 4<br/>(M)"]
end
C1 --- M1
C2 --- M2
C3 --- M3
C4 --- M4
subgraph GoRuntime["Go 런타임 스케줄러 (유저 공간)"]
GS["Go 스케줄러<br/>⚡ 저비용 고루틴 전환<br/>스택 포인터만 교체"]
end
M1 & M2 & M3 & M4 --> GS
subgraph Goroutines["고루틴 (초기 스택 2-4 KB, 필요시 자동 확장)"]
G1["G1 🪶"]
G2["G2 🪶"]
G3["G3 🪶"]
G4["G4 🪶"]
G5["G5 🪶"]
G6["G6 🪶"]
G7["G7 🪶"]
G8["G8 🪶"]
G9["G9 🪶"]
G10["G10 🪶"]
G11["G11 🪶"]
G12["G12 🪶"]
GN["... 100K+ 🪶"]
end
GS --> G1 & G2 & G3 & G4 & G5 & G6 & G7 & G8 & G9 & G10 & G11 & G12 & GN
style CPU fill:#1a3a5c,color:#fff
style OSThreads fill:#2e1a2e,color:#fff
style GoRuntime fill:#2d5a27,color:#fff
style Goroutines fill:#1a2e1a,color:#fff

각 고루틴은 CPU의 커널 전환 같은 문맥 교환 없이 사용할 수 있으므로 스레드 전환에 비해 50-100배 정도 빠르고 메모리 사용량도 현저히 적습니다.

위 다이어그램에서는 간단하게 설명하기 위해서 마치 Go가 코어와 OS 스레드를 1:1 매핑 시키는 것 처럼 묘사했지만, 사실은 그렇지 않습니다. Go는 GMP(Goroutine-Machine-Processor) 스케쥴러를 사용하는데요, 이 스케쥴러는 OS 스레드(M)를 코어에 1:1 매핑하지는 않습니다. 실제로는 GOMAXPROCS 설정에 따라 논리적 프로세서(P)를 생성하고, 각 P는 OS 스레드(M)에 붙어서 고루틴(G)을 실행합니다. 그러니까 코어와 OS 스레드(M)가 1:N이 될 수도 있는거죠. 또한 특정 P의 대기열이 비면, 다른 P의 대기 중인 고루틴(G)을 빼앗아 올 수도 있습니다!

Java의 Project Loom(JDK 21)에서 지원하는 Virtual Thread가 이 고루틴을 구현한 것입니다!

동시성 처리 작업에 lock 걸기

자 지금까지 미래의 저를 위해서 스레드와 고루틴을 비교해서 적어봤는데요, 어떤 방법을 사용하든 동시성을 다루다 보면 상태 값을 어떻게 공유해야 할지 문제가 생깁니다. 스레드나 고루틴은 생성 순서가 처리 순서를 보장하지 못하기 때문에 예상하지 못한 결과가 나올 수 있죠. 그래서 먼저 접근 한 쪽이 처리 우선권을 가지도록 lock을 걸 필요가 있습니다.

// 노드 프로세스 관리를 위한 맵 정의
var (
 // 키 타입이 int이고, 값 타입이 *exec.Cmd인 맵
 processes = make(map[int]*exec.Cmd)
 // 맵에 대한 동시성 접근을 위한 뮤텍스(lock)
 processesMu sync.Mutex
)
...
// 여러 goroutine에서 동시에 접근할 수 있으므로, 동시성 접근을 위해 뮤텍스를 사용
processesMu.Lock()
processes[nc.id] = cmd
processesMu.Unlock()

Mutex를 통해 lock을 획득한 고루틴만 값을 변경할 수 있도록 하고 있습니다. lock은 필요한 작업을 마치면 반드시 해제 해야 하고, lock을 거는 시간은 최소화 해야 합니다. 따라서 다음과 같은 두 가지 패턴역시 이후 살펴볼 node.go 파일에서 등장합니다.

func (node *PaxosNode) runElection() {
 node.mu.Lock()
 ...
 allNodes := make([]string, len(node.allNodes))
 /**
 * lock은 최대한 짧게 유지하는게 중요하므로 필요한 작업 이후에 해제해야 함.
 * 따라서 이후 작업에 사용할 node.allNodes를 로컬 변수에 복사하여 사용.
 */
 copy(allNodes, node.allNodes)
 majority := node.majority
 nodeID := node.nodeID
 // lock 해제
 node.mu.Unlock()

 // 함수 종료시 리더 선출 상태를 초기화하기 위해 defer 처리
 defer func() {
 node.mu.Lock()
 node.electionInProgress = false
 node.mu.Unlock()
 }()
 ...
}

lock이 필요한 최소한의 작업을 진행하고 그 값을 로컬 변수에 복사. 그리고 lock을 해제하고, 이후의 작업에서는 복사한 로컬 변수로 현재 상태에 대한 작업 진행
함수 종료시 실행되어야 하는 작업을 defer로 감싸고 lock을 통해 상태 값을 변경

채널

채널은 고루틴끼리 서로 메세지를 주고 받을 수 있는 메세지 큐 같은 자료구조입니다. 이 코드에서는 다음과 같이 사용되고 있습니다.

func runCluster() {
 ...
 // goroutine 끼리 메세지를 주고받기 위한 채널 생성, 버퍼 크기를 1로 설정하여 수신자가 메세지를 받을 때까지 대기할 수 있도록 함
 sigChan := make(chan os.Signal, 1)
 // Ctrl+C 발생시 해당 시그널을 채널로 전달
 signal.Notify(sigChan, os.Interrupt)

 go func() {
 // 채널에서 메세지(Ctrl+C)를 받을 때까지 대기
 <-sigChan
 fmt.Print("\n\n🛑 모든 노드 종료...\n\n")
 // 모든 노드 프로세스에 SIGTERM 시그널 전송
 processesMu.Lock()
 for _, cmd := range processes {
 if cmd.Process != nil {
 cmd.Process.Signal(syscall.SIGTERM)
 }
 }
 processesMu.Unlock()
 time.Sleep(500 * time.Millisecond)
 os.Exit(0)
 }()
 ...
}

runCluster를 실행하는 메인 고루틴에서 프로그램 종료 시그널을 수신하면, 해당 시그널을 채널을 통해 고루틴에게 전송합니다. 그리고 시그널을 받은(<-sigChan) 고루틴은 각 프로세스에 종료 시그널을 전송해서 모든 노드가 종료될 수 있도록 합니다.

여기서 주목할 점은 채널을 생성할 때 버퍼 크기를 1로 설정해준 부분입니다. 만약 버퍼 크기가 없다면, 채널을 통해 전송한 메세지는 그 즉시 수신되어야 하며 수신자가 없다면 메세지를 전송한 고루틴은 수신자가 나타날 때 까지 계속 대기 하게됩니다. 그리고 만약 모든 고루틴이 메세지를 수신할 수 없는 상황이 된다면 deadlock이 발생하여 종료됩니다. 이후 node.go 파일에서 좀 더 다양한 채널의 사용 예시가 등장합니다!

즉시 실행 익명 함수(IIFE)로 defer 보장

printStatus 함수를 보면, 클러스터의 상태를 조회하기 위해 각 노드에 상태 조회 api 요청을 전송합니다. 그리고 api 응답을 닫기(close) 위해 defer를 사용하는데요, 이 작업이 항상 실행되도록 보장하기 위해 즉시 실행되는 익명 함수(IIFE, Immediately Invoked Function Express)를 사용하고 있습니다.

// 클러스터 상태 출력 함수
func printStatus() {
 fmt.Println("\n=== 클러스터 상태 ===")

 // 타임아웃이 1초인 http.Client 생성
 client := &http.Client{Timeout: 1 * time.Second}

 for _, node := range nodes {
 // 즉시 실행되는 익명 함수. 함수 종료시 defer 처리된 리소스 해제
 func() {
 url := fmt.Sprintf("http://localhost:%d/status", node.port)
 resp, err := client.Get(url)
 color := colors[node.id]

 if err != nil {
 fmt.Printf("%s 노드 %d: 다운%s\n", color, node.id, colorReset)
 return
 }
 // err 발생시 resp는 nil. 따라서 err 체크 후 defer 처리가 일반적인 방법.
 defer resp.Body.Close()

 var data StatusResponse
 // resp.Body를 JSON -> StatusResponse 타입으로 변환; 그리고 err 발생시 처리
 if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
 fmt.Printf("%s 노드 %d: (응답 파싱 실패)%s\n", color, node.id, colorReset)
 return
 }
 ...
 }()
 }
}

각 API 요청을 IIFE로 감싸면서 해당 함수가 끝날 때 defer된 defer resp.Body.Close() 가 실행될 수 있도록 하고 있습니다.

웹 서버 노드 구현

이제 웹 서버 노드의 구현을 확인해보겠습니다. 우선 node.go의 전체 코드는 다음과 같습니다.

package main

import (
 "bytes"
 "context"
 "encoding/json"
 "fmt"
 "math/rand/v2"
 "net/http"
 "os"
 "os/signal"
 "strconv"
 "strings"
 "sync"
 "syscall"
 "time"
)

// === 타입 정의 ===

type PrepareRequest struct {
 ProposalNumber int `json:"proposalNumber"`
}

type PrepareResponse struct {
 Promise bool `json:"promise"`
 AcceptedProposal *int `json:"acceptedProposal"`
 AcceptedValue *int `json:"acceptedValue"`
}

type AcceptRequest struct {
 ProposalNumber int `json:"proposalNumber"`
 Value int `json:"value"`
}

type AcceptResponse struct {
 Accepted bool `json:"accepted"`
}

type HeartbeatMessage struct {
 LeaderID int `json:"leaderId"`
 Term int `json:"term"`
}

type StatusResponse struct {
 NodeID int `json:"nodeId"`
 CurrentLeaderID *int `json:"currentLeaderId"`
 CurrentTerm int `json:"currentTerm"`
 PromisedProposal *int `json:"promisedProposal"`
 AcceptedProposal *int `json:"acceptedProposal"`
 AcceptedValue *int `json:"acceptedValue"`
 IsLeader bool `json:"isLeader"`
}

// === Paxos 노드 구조체 ===

// PaxosNode는 Paxos 노드의 모든 상태를 관리합니다.
type PaxosNode struct {
 mu sync.Mutex

 // 컨텍스트 (graceful shutdown 용도)
 ctx context.Context
 cancel context.CancelFunc

 // 설정
 nodeID int // 노드 아이디
 port int // 노드 포트
 peers []string // 통신해야 할 다른 노드의 URL 목록
 allNodes []string // 자신을 포함한 모든 노드의 URL 목록
 majority int // 다수 필요 개수 (전체 노드 수 / 2 + 1)

 // === Paxos Acceptor 상태 변수들 ===
 promisedProposal *int // 약속한 제안 번호 (nil = 아직 약속 없음)
 acceptedProposal *int // 수락된 제안 번호 (nil = 아직 수락 없음)
 acceptedValue *int // 수락된 값(리더의 노드 아이디) (nil = 아직 수락 없음)

 // === Leader 상태와 Heartbeat ===
 currentLeaderID *int // 현재 리더 아이디 (nil = 리더 없음)
 currentTerm int // 현재 턴
 electionRound int // 선거 라운드

 // === 타이머 ===
 heartbeatStop chan struct{} // 리더의 하트비트 전송 중지 시그널
 electionTimer *time.Timer // 하트비트 타임아웃 감시 타이머 (3~5초, 리더는 선출 후 중지)
 nextElectionTimer *time.Timer // 다음 선거 시작 타이머
 electionInProgress bool // 선거 진행 중 플래그 (동시 선거 방지)

 // HTTP 클라이언트
 httpClient *http.Client
}

// newPaxosNode는 새로운 Paxos 노드를 생성합니다.
// cli 매개변수로 전달받은 노드 아이디, 포트, 통신해야 할 다른 노드의 URL 목록 등의 값을 변수에 저장
func newPaxosNode(ctx context.Context, nodeID, port int, peers []string) *PaxosNode {
 ctx, cancel := context.WithCancel(ctx)
 selfURL := fmt.Sprintf("http://localhost:%d", port)
 allNodes := append([]string{selfURL}, peers...)
 majority := len(allNodes)/2 + 1

 return &PaxosNode{
 ctx: ctx,
 cancel: cancel,
 nodeID: nodeID,
 port: port,
 peers: peers,
 allNodes: allNodes,
 majority: majority,
 httpClient: &http.Client{Timeout: 1 * time.Second},
 }
}

// intPtr는 int를 *int로 변환하는 헬퍼 함수입니다.
func intPtr(v int) *int {
 return &v
}

// ceilDiv는 올림 나눗셈을 수행합니다.
func ceilDiv(a, b int) int {
 return (a + b - 1) / b
}

// === Paxos Proposer 로직 ===

// runElection은 리더 선출 시작
func (node *PaxosNode) runElection() {
 node.mu.Lock()
 // 이미 리더 선출 중인 경우
 if node.electionInProgress {
 node.mu.Unlock()
 // 리더 선출 중단
 return
 }
 node.electionInProgress = true

 // 제안 번호가 이미 있는 것보다 큰지 확인
 if node.promisedProposal != nil {
 /**
 * 이전에 약속된 제안 번호가 있는 경우, 라운드 조정(다른 노드가 이미 제안한 제안 번호보다 높은 제안 번호를 사용하도록 함)
 *
 * ex: max(0, ceilDiv(6, 3)) = max(0, 2) = 2
 */
 node.electionRound = max(node.electionRound, ceilDiv(*node.promisedProposal, len(node.allNodes)))
 }
 node.electionRound++

 /**
 * 제안 번호 = 노드 아이디 + (라운드 * 노드 개수) -> 각 라운드 마다 노드의 제안 번호의 고유성을 보장하기 위함
 *
 * 예를 들어, 노드 1, 2, 3이 있고, 라운드가 1인 경우,
 * 노드 1, 라운드 1: 1 + (1 * 3) = 4
 * 노드 2, 라운드 1: 2 + (1 * 3) = 5
 * 노드 3, 라운드 1: 3 + (1 * 3) = 6
 * 노드 1, 라운드 2: 1 + (2 * 3) = 7
 * 노드 2, 라운드 2: 2 + (2 * 3) = 8
 * 노드 3, 라운드 2: 3 + (2 * 3) = 9
 * ...
 */
 proposalNumber := node.nodeID + (node.electionRound * len(node.allNodes))
 allNodes := make([]string, len(node.allNodes))
 /**
 * lock은 최대한 짧게 유지하는게 중요하므로 필요한 작업 이후에 해제해야 함.
 * 따라서 이후 작업에 사용할 node.allNodes를 로컬 변수에 복사하여 사용.
 */
 copy(allNodes, node.allNodes)
 majority := node.majority
 nodeID := node.nodeID
 // lock 해제
 node.mu.Unlock()

 // 함수 종료시 리더 선출 상태를 초기화하기 위해 defer 처리
 defer func() {
 node.mu.Lock()
 node.electionInProgress = false
 node.mu.Unlock()
 }()

 fmt.Printf("\n[노드 %d] 🗳️ 리더 선출 시작 / 제안 번호 #%d\n", nodeID, proposalNumber)

 // === Phase 1: PREPARE 요청 전송 ===
 fmt.Printf("[노드 %d] Phase 1: 모든 노드에 PREPARE 요청 전송...\n", nodeID)

 type prepareResult struct {
 resp *PrepareResponse
 err error
 }
 results := make([]prepareResult, len(allNodes))
 var wg sync.WaitGroup

 // 자신을 포함한 모든 노드에 PREPARE 요청 전송
 for i, nodeURL := range allNodes {
 wg.Add(1)
 go func(idx int, url string) {
 defer wg.Done()
 resp, err := node.sendPrepare(url, proposalNumber)
 results[idx] = prepareResult{resp: resp, err: err}
 }(i, nodeURL)
 }
 wg.Wait()

 // PREPARE 요청 결과 처리 - 약속을 받은 것들만 추출
 var promises []PrepareResponse
 for _, r := range results {
 if r.err == nil && r.resp != nil && r.resp.Promise {
 promises = append(promises, *r.resp)
 }
 }

 fmt.Printf("[노드 %d] Phase 1: 약속을 받은 노드 %d/%d 개 (필요 %d 개)\n",
 nodeID, len(promises), len(allNodes), majority)

 if len(promises) < majority {
 fmt.Printf("[노드 %d] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.\n", nodeID)
 node.scheduleNextElection()
 return
 }

 // 수락된 값 중 가장 높은 값을 채택, 없으면 자신을 제안
 proposedValue := nodeID
 highestAcceptedProposal := -1

 for _, p := range promises {
 // 수락된 값 중 가장 높은 값을 채택
 if p.AcceptedProposal != nil && *p.AcceptedProposal > highestAcceptedProposal {
 highestAcceptedProposal = *p.AcceptedProposal
 proposedValue = *p.AcceptedValue
 }
 }

 if highestAcceptedProposal > -1 {
 fmt.Printf("[노드 %d] Phase 1: 이전에 수락된 값 (노드 %d) 채택 / 제안 번호 #%d\n",
 nodeID, proposedValue, highestAcceptedProposal)
 } else {
 fmt.Printf("[노드 %d] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 %d)\n", nodeID, proposedValue)
 }

 // === Phase 2: Accept ===
 fmt.Printf("[노드 %d] Phase 2: 모든 노드에 ACCEPT (값: 노드 %d) 요청 전송...\n", nodeID, proposedValue)

 type acceptResult struct {
 resp *AcceptResponse
 err error
 }
 // ACCEPT 요청 결과를 저장할 슬라이스 생성
 acceptResults := make([]acceptResult, len(allNodes))
 // 모든 작업이 완료될 때까지 대기할 WaitGroup 생성
 wg = sync.WaitGroup{}

 // 자신을 포함한 모든 노드에 ACCEPT 요청 전송, 병렬 처리
 for i, nodeURL := range allNodes {
 // 대기 그룹에 작업 1개 추가
 wg.Add(1)
 // goroutine: ACCEPT 요청 전송
 go func(idx int, url string) {
 // 작업 완료시 대기 그룹에서 작업 1개 제거
 defer wg.Done()
 resp, err := node.sendAccept(url, proposalNumber, proposedValue)
 acceptResults[idx] = acceptResult{resp: resp, err: err}
 }(i, nodeURL)
 }
 // 모든 작업이 완료될 때까지 대기
 wg.Wait()

 // ACCEPT 요청 결과 처리 - 수락된 것들 카운트
 accepts := 0
 for _, r := range acceptResults {
 if r.err == nil && r.resp != nil && r.resp.Accepted {
 accepts++
 }
 }

 fmt.Printf("[노드 %d] Phase 2: 수락된 노드 %d/%d 개 (필요 %d 개)\n",
 nodeID, accepts, len(allNodes), majority)

 if accepts >= majority {
 fmt.Printf("[노드 %d] ✅ 리더 선출 성공! 노드 %d 가 리더가 되었습니다. (제안 번호 %d)\n",
 nodeID, proposedValue, proposalNumber)

 if proposedValue == nodeID {
 fmt.Printf("[노드 %d] 👑 나는 리더!\n", nodeID)
 // 리더는 자신의 선출 타임아웃을 중지 (팔로워만 타임아웃을 감시)
 node.mu.Lock()
 if node.electionTimer != nil {
 node.electionTimer.Stop()
 }
 node.mu.Unlock()
 node.startHeartbeat(proposalNumber)
 }
 } else {
 fmt.Printf("[노드 %d] ❌ Phase 2 실패: 수락된 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.\n", nodeID)
 node.scheduleNextElection()
 }
}

func (node *PaxosNode) sendPrepare(url string, proposalNumber int) (*PrepareResponse, error) {
 body, err := json.Marshal(PrepareRequest{ProposalNumber: proposalNumber})
 if err != nil {
 return nil, fmt.Errorf("marshal prepare request: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/paxos/prepare", bytes.NewReader(body))
 if err != nil {
 return nil, fmt.Errorf("create prepare request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return nil, fmt.Errorf("send prepare to %s: %w", url, err)
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
 return nil, fmt.Errorf("prepare request to %s returned status %d", url, resp.StatusCode)
 }

 var result PrepareResponse
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, fmt.Errorf("decode prepare response from %s: %w", url, err)
 }

 return &result, nil
}

func (node *PaxosNode) sendAccept(url string, proposalNumber, value int) (*AcceptResponse, error) {
 body, err := json.Marshal(AcceptRequest{ProposalNumber: proposalNumber, Value: value})
 if err != nil {
 return nil, fmt.Errorf("marshal accept request: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/paxos/accept", bytes.NewReader(body))
 if err != nil {
 return nil, fmt.Errorf("create accept request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return nil, fmt.Errorf("send accept to %s: %w", url, err)
 }
 defer resp.Body.Close()

 if resp.StatusCode != http.StatusOK {
 return nil, fmt.Errorf("accept request to %s returned status %d", url, resp.StatusCode)
 }

 var result AcceptResponse
 if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
 return nil, fmt.Errorf("decode accept response from %s: %w", url, err)
 }

 return &result, nil
}

func (node *PaxosNode) sendHeartbeat(url string, leaderID, term int) error {
 body, err := json.Marshal(HeartbeatMessage{LeaderID: leaderID, Term: term})
 if err != nil {
 return fmt.Errorf("marshal heartbeat: %w", err)
 }

 req, err := http.NewRequestWithContext(node.ctx, "POST", url+"/leader/heartbeat", bytes.NewReader(body))
 if err != nil {
 return fmt.Errorf("create heartbeat request: %w", err)
 }
 req.Header.Set("Content-Type", "application/json")

 resp, err := node.httpClient.Do(req)
 if err != nil {
 return fmt.Errorf("send heartbeat to %s: %w", url, err)
 }
 defer resp.Body.Close()

 return nil
}

// 리더가 자신을 생존을 알리는 하트비트 전송을 시작하는 함수 (리더만 실행)
func (node *PaxosNode) startHeartbeat(term int) {
 node.mu.Lock()
 // 기존 하트비트 중지 (TOCTOU 경합 방지를 위해 인라인 처리)
 if node.heartbeatStop != nil {
 // 기존 하트비트 채널 종료
 close(node.heartbeatStop)
 }
 // 데이터는 없이 신호만 수신할 채널 생성
 stopCh := make(chan struct{})
 node.heartbeatStop = stopCh
 node.mu.Unlock()

 // goroutine: 각 채널의 메세지 수신 및 처리
 go func() {
 // 1초 간격 타이머 채널 생성
 ticker := time.NewTicker(1 * time.Second)
 // goroutine 종료시 타이머 종료
 defer ticker.Stop()

 for { // 종료될 때까지 무한 반복하는 이벤트 루프
 // 각 채널에서 수신되는 신호를 대기하며, 수신된 신호에 따라 동작 결정(select)
 select {
 case <-stopCh: // 하트비트 중지 신호
 return
 case <-node.ctx.Done(): // context 취소 신호
 return
 case <-ticker.C: // 1초 간격 타이머 채널 신호
 fmt.Printf("[노드 %d] 💓 하트비트 전송 (턴 %d)\n", node.nodeID, term)

 node.mu.Lock()
 // 이후 작업에 사용할 node.peers를 로컬 변수에 복사하여 사용
 peers := make([]string, len(node.peers))
 copy(peers, node.peers)
 // lock 해제
 node.mu.Unlock()

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 for _, peerURL := range peers {
 // goroutine: 하트비트 전송
 go func(url string) {
 _ = node.sendHeartbeat(url, node.nodeID, term)
 }(peerURL)
 }
 }
 }
 }()
}

// 하트비트 중지 처리 함수
func (node *PaxosNode) stopHeartbeat() {
 node.mu.Lock()
 if node.heartbeatStop != nil {
 close(node.heartbeatStop)
 node.heartbeatStop = nil
 }
 node.mu.Unlock()
}

// 모든 타이머와 하트비트를 정리하고 context를 취소하는 함수
func (node *PaxosNode) shutdown() {
 node.mu.Lock()
 if node.electionTimer != nil {
 node.electionTimer.Stop()
 }
 if node.nextElectionTimer != nil {
 node.nextElectionTimer.Stop()
 }
 node.mu.Unlock()
 node.stopHeartbeat()
 node.cancel()
}

// 리더 선출 타임아웃 리셋 처리 함수
//
// 타임아웃 이후, 리더가 없으면 리더 선출 시작
func (node *PaxosNode) resetElectionTimeout() {
 node.mu.Lock()
 defer node.mu.Unlock()

 if node.electionTimer != nil {
 // 기존 리더 선출 타이머 중지
 node.electionTimer.Stop()
 }

 // 리더 선출 타임아웃 랜덤 적용 (3-5초)
 timeout := 3*time.Second + time.Duration(rand.Float64()*2000)*time.Millisecond

 // goroutine: 리더 선출 타임아웃 타이머 설정
 node.electionTimer = time.AfterFunc(timeout, func() {
 fmt.Printf("[노드 %d] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...\n", node.nodeID)

 node.mu.Lock()
 node.currentLeaderID = nil
 // 현재 리더로 선출된 노드가 서비스 다운되는 경우에 해당 노드는 리더 선출에서 제외되어야 함
 // 따라서 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함
 node.acceptedProposal = nil
 node.acceptedValue = nil
 node.mu.Unlock()

 node.runElection()
 })
}

// 다음 리더 선출 예약 처리 함수
func (node *PaxosNode) scheduleNextElection() {
 node.mu.Lock()
 defer node.mu.Unlock()

 if node.nextElectionTimer != nil {
 // 기존 다음 리더 선출 타이머 중지
 node.nextElectionTimer.Stop()
 }

 // 다음 선거 시작 전 랜덤 딜레이 적용
 delay := 2*time.Second + time.Duration(rand.Float64()*3000)*time.Millisecond

 // goroutine: 다음 리더 선출 타이머 설정
 node.nextElectionTimer = time.AfterFunc(delay, func() {
 node.mu.Lock()
 hasLeader := node.currentLeaderID != nil
 node.mu.Unlock()

 // 현재 리더가 없으면 다음 선거 시작
 if !hasLeader {
 node.runElection()
 }
 })
}

// === HTTP 핸들러들 ===

// Paxos Phase 1: Prepare 요청 처리 함수
func (node *PaxosNode) handlePrepare(w http.ResponseWriter, r *http.Request) {
 // 요청 본문을 JSON -> PrepareRequest 타입으로 변환; 그리고 err 발생시 처리
 var req PrepareRequest
 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 fmt.Printf("[노드 %d] PREPARE 요청 수신 / 제안 번호 #%d\n", node.nodeID, req.ProposalNumber)

 // 함수 내부에서만 쓰이므로 포인터(*) 없이 사용
 var resp PrepareResponse

 if node.promisedProposal == nil || req.ProposalNumber > *node.promisedProposal {
 node.promisedProposal = intPtr(req.ProposalNumber)
 // 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함(죽은 리더 재선출 방지)
 node.acceptedProposal = nil
 node.acceptedValue = nil

 fmt.Printf("[노드 %d] → 제안 번호 #%d 약속\n", node.nodeID, req.ProposalNumber)
 resp = PrepareResponse{Promise: true, AcceptedProposal: nil, AcceptedValue: nil}
 } else {
 fmt.Printf("[노드 %d] → 이미 약속한 제안 번호 #%d 거절\n", node.nodeID, *node.promisedProposal)
 resp = PrepareResponse{Promise: false, AcceptedProposal: nil, AcceptedValue: nil}
 }
 node.mu.Unlock()

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// Paxos Phase 2: ACCEPT 요청 처리 함수
func (node *PaxosNode) handleAccept(w http.ResponseWriter, r *http.Request) {
 var req AcceptRequest
 if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 fmt.Printf("[노드 %d] ACCEPT 요청 수신 / 제안 번호 #%d, 값: 노드 %d\n",
 node.nodeID, req.ProposalNumber, req.Value)

 var resp AcceptResponse

 // 약속된 제안 번호가 없거나, 현재 제안 번호가 약속된 제안 번호보다 크거나 같으면 수락
 if node.promisedProposal == nil || req.ProposalNumber >= *node.promisedProposal {
 // 약속된 제안 번호 갱신
 node.promisedProposal = intPtr(req.ProposalNumber)
 // 수락된 제안 번호 갱신
 node.acceptedProposal = intPtr(req.ProposalNumber)
 // 수락된 값 갱신(리더의 노드 아이디)
 node.acceptedValue = intPtr(req.Value)
 // 현재 리더 아이디 갱신
 node.currentLeaderID = intPtr(req.Value)
 // 현재 턴 갱신
 node.currentTerm = req.ProposalNumber

 fmt.Printf("[노드 %d] → 수락! 새로운 리더: 노드 %d (제안 번호 %d)\n",
 node.nodeID, req.Value, req.ProposalNumber)

 // 리더가 아니라면 하트비트 중지
 shouldStopHeartbeat := req.Value != node.nodeID
 node.mu.Unlock()

 if shouldStopHeartbeat {
 node.stopHeartbeat()
 }

 // 리더 선출 타임아웃 리셋
 node.resetElectionTimeout()

 resp = AcceptResponse{Accepted: true}
 } else {
 fmt.Printf("[노드 %d] → 이미 약속한 제안 번호 #%d 거절\n",
 node.nodeID, *node.promisedProposal)
 node.mu.Unlock()
 resp = AcceptResponse{Accepted: false}
 }

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// 리더가 전송하는 하트비트 수신 처리 함수
func (node *PaxosNode) handleHeartbeat(w http.ResponseWriter, r *http.Request) {
 var msg HeartbeatMessage
 if err := json.NewDecoder(r.Body).Decode(&msg); err != nil {
 http.Error(w, "bad request", http.StatusBadRequest)
 return
 }

 node.mu.Lock()
 // 새로운 턴이 시작되었다면,
 shouldReset := msg.Term >= node.currentTerm
 if shouldReset {
 // 새로운 리더가 등장했다면,
 if node.currentLeaderID == nil || *node.currentLeaderID != msg.LeaderID {
 fmt.Printf("[노드 %d] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 %d (턴 %d)\n",
 node.nodeID, msg.LeaderID, msg.Term)
 }

 // 현재 리더 아이디 갱신
 node.currentLeaderID = intPtr(msg.LeaderID)
 // 현재 턴 갱신
 node.currentTerm = msg.Term
 }
 node.mu.Unlock()

 /**
 * 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 *
 * 리더의 하트비트가 안정적으로 수신된다면, 리더 선출의 타임아웃은 계속 리셋된다. -> 현재 상태 유지.
 * 현재 턴 이상의 하트비트만 타임아웃 리셋 (오래된 리더의 하트비트는 무시)
 */
 if shouldReset {
 node.resetElectionTimeout()
 }

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(map[string]bool{"ok": true}); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// 상태 조회 엔드포인트 처리 함수
func (node *PaxosNode) handleStatus(w http.ResponseWriter, r *http.Request) {
 node.mu.Lock()
 isLeader := node.currentLeaderID != nil && *node.currentLeaderID == node.nodeID
 resp := StatusResponse{
 NodeID: node.nodeID,
 CurrentLeaderID: node.currentLeaderID,
 CurrentTerm: node.currentTerm,
 PromisedProposal: node.promisedProposal,
 AcceptedProposal: node.acceptedProposal,
 AcceptedValue: node.acceptedValue,
 IsLeader: isLeader,
 }
 node.mu.Unlock()

 w.Header().Set("Content-Type", "application/json")
 if err := json.NewEncoder(w).Encode(resp); err != nil {
 fmt.Printf("[노드 %d] 응답 쓰기 실패: %v\n", node.nodeID, err)
 }
}

// === 메인 함수 ===

func runNode() {
 if len(os.Args) < 4 {
 fmt.Println("Usage: go run . node <id> <port> <peers...>")
 os.Exit(1)
 }

 nodeID, err := strconv.Atoi(os.Args[2])
 if err != nil {
 fmt.Fprintf(os.Stderr, "invalid node ID %q: %v\n", os.Args[2], err)
 os.Exit(1)
 }

 port, err := strconv.Atoi(os.Args[3])
 if err != nil {
 fmt.Fprintf(os.Stderr, "invalid port %q: %v\n", os.Args[3], err)
 os.Exit(1)
 }

 peers := os.Args[4:]

 ctx := context.Background()
 node := newPaxosNode(ctx, nodeID, port, peers)

 fmt.Printf("[노드 %d] 시작 with 통신해야 할 다른 노드의 URL 목록: %s\n",
 nodeID, strings.Join(peers, ", "))
 fmt.Printf("[노드 %d] 다수 필요: %d 중 %d 이상\n",
 nodeID, len(node.allNodes), node.majority)

 mux := http.NewServeMux()
 mux.HandleFunc("POST /paxos/prepare", node.handlePrepare)
 mux.HandleFunc("POST /paxos/accept", node.handleAccept)
 mux.HandleFunc("POST /leader/heartbeat", node.handleHeartbeat)
 mux.HandleFunc("GET /status", node.handleStatus)

 server := &http.Server{
 Addr: fmt.Sprintf(":%d", port),
 Handler: mux,
 }

 go func() {
 fmt.Printf("[노드 %d] 🚀 포트 %d에서 수신 중...\n", nodeID, port)
 if err := server.ListenAndServe(); err != nil && err != http.ErrServerClosed {
 fmt.Printf("[노드 %d] 서버 에러: %v\n", nodeID, err)
 os.Exit(1)
 }
 }()

 // 리더 선출 예약(랜덤 딜레이 적용)
 delay := 1*time.Second + time.Duration(rand.Float64()*2000)*time.Millisecond
 fmt.Printf("[노드 %d] 리더 조회 전 %dms 대기...\n", nodeID, delay.Milliseconds())

 // 랜덤 딜레이 이후, 리더가 없으면 리더 선출 시작
 time.AfterFunc(delay, func() {
 node.mu.Lock()
 hasLeader := node.currentLeaderID != nil
 node.mu.Unlock()

 if !hasLeader {
 fmt.Printf("[노드 %d] 리더 없음, 리더 선출 시작...\n", nodeID)
 node.runElection()
 }
 })

 // 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 node.resetElectionTimeout()

 sigChan := make(chan os.Signal, 1)
 signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
 <-sigChan

 fmt.Printf("[노드 %d] 종료 중...\n", nodeID)
 node.shutdown()

 shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 2*time.Second)
 defer shutdownCancel()
 _ = server.Shutdown(shutdownCtx)
}

포인터를 이용한 nullable 필드(*int)

이제와서 뒷북이긴 하지만, Go는 포인터를 사용합니다! 하하하하… 그런데 정말 다행인 건 C, C++ 처럼 직접 메모리를 관리하거나 포인터 연산을 걱정할 필요는 없습니다. Go에서 포인터는 그저 모든 게 값인 세상에서 어떤 값을 참조로 사용할지 선택권을 주는 수단입니다. 포인터에 대한 자세한 설명은 다음으로 미루고, 일단 여기서는 nullable 필드를 눈 여겨 보도록 할까요?

type PaxosNode struct {
 ...
 // 설정
 nodeID int // 노드 아이디
 port int // 노드 포트
 peers []string // 통신해야 할 다른 노드의 URL 목록
 allNodes []string // 자신을 포함한 모든 노드의 URL 목록
 majority int // 다수 필요 개수 (전체 노드 수 / 2 + 1)

 // === Paxos Acceptor 상태 변수들 ===
 promisedProposal *int // 약속한 제안 번호 (nil = 아직 약속 없음)
 acceptedProposal *int // 수락된 제안 번호 (nil = 아직 수락 없음)
 acceptedValue *int // 수락된 값(리더의 노드 아이디) (nil = 아직 수락 없음)
 ...
}

똑같은 int 변수 지만 어떤 변수는 int로, 어떤 변수는 *int로 선언되었습니다. Go에서는 변수를 선언할 때 값을 선언하지 않으면 해당 변수 타입의 기본 값으로 초기화를 진행합니다. int의 경우 0이고, *int의 경우는 nil 이죠. 즉, 반드시 값이 존재하지만 초기값이 0인 변수와 값이 존재하지 않을 수도 있는 변수 를 선언하는 거죠.

모든 고루틴이 종료될 때까지 기다리는 WaitGroup

자신을 포함해서 모든 노드에 prepare를 전송하는 코드를 살펴보죠.

// === Phase 1: PREPARE 요청 전송 ===
fmt.Printf("[노드 %d] Phase 1: 모든 노드에 PREPARE 요청 전송...\n", nodeID)

type prepareResult struct {
 resp *PrepareResponse
 err error
}
results := make([]prepareResult, len(allNodes))
var wg sync.WaitGroup

// 자신을 포함한 모든 노드에 PREPARE 요청 전송 ----> 모든 요청을 병렬로 처리
for i, nodeURL := range allNodes {
 wg.Add(1) // 고루틴 시작전 ----> WaitGroup 1 증가
 go func(idx int, url string) {
 defer wg.Done() // 고루틴 종료시 작업 완료 ----> WaitGroup 1 감소
 resp, err := node.sendPrepare(url, proposalNumber)
 results[idx] = prepareResult{resp: resp, err: err}
 }(i, nodeURL)
}
wg.Wait() // 모든 작업이 완료될 때 까지 대기

각 고루틴을 실행하기 전에 Add로 작업 수를 증가시키고, 병렬로 실행되는 고루틴이 종료될 때(defer) Done으로 작업 완료 처리합니다. 그리고 Wait으로 모든 작업이 완료될 때까지 대기하게 되죠. node.js의 Promise.allSettled 와 닮았네요!

채널 select -> 채널을 위한 switch

리더가 자신의 생존을 다른 노드에게 알리는 startHeartbeat 함수를 보면, 여러 채널에서 수신되는 메세지에 따라 다른 동작을 수행하도록 하고 있습니다.

// 리더가 자신을 생존을 알리는 하트비트 전송을 시작하는 함수 (리더만 실행)
func (node *PaxosNode) startHeartbeat(term int) {
 node.mu.Lock()
 // 기존 하트비트 중지 (TOCTOU 경합 방지를 위해 인라인 처리)
 if node.heartbeatStop != nil {
 // 기존 하트비트 채널 종료
 close(node.heartbeatStop)
 }
 // 데이터는 없이 신호만 수신할 채널 생성
 stopCh := make(chan struct{})
 node.heartbeatStop = stopCh
 node.mu.Unlock()

 // goroutine: 각 채널의 메세지 수신 및 처리
 go func() {
 // 1초 간격 타이머 채널 생성
 ticker := time.NewTicker(1 * time.Second)
 // goroutine 종료시 타이머 종료
 defer ticker.Stop()

 for { // 종료될 때까지 무한 반복하는 이벤트 루프
 // 각 채널에서 수신되는 신호를 대기하며, 수신된 신호에 따라 동작 결정(select)
 select {
 case <-stopCh: // 하트비트 중지 신호
 return
 case <-node.ctx.Done(): // context 취소 신호
 return
 case <-ticker.C: // 1초 간격 타이머 채널 신호
 fmt.Printf("[노드 %d] 💓 하트비트 전송 (턴 %d)\n", node.nodeID, term)

 node.mu.Lock()
 // 이후 작업에 사용할 node.peers를 로컬 변수에 복사하여 사용
 peers := make([]string, len(node.peers))
 copy(peers, node.peers)
 // lock 해제
 node.mu.Unlock()

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 for _, peerURL := range peers {
 // goroutine: 하트비트 전송
 go func(url string) {
 _ = node.sendHeartbeat(url, node.nodeID, term)
 }(peerURL)
 }
 }
 }
 }()
}

// 하트비트 중지 처리 함수
func (node *PaxosNode) stopHeartbeat() {
 node.mu.Lock()
 if node.heartbeatStop != nil {
 close(node.heartbeatStop)
 node.heartbeatStop = nil
 }
 node.mu.Unlock()
}

고루틴 내부를 살펴보면 다음과 같이 동작하고 있습니다.

1초 간격의 타이머를 설정하고
무한 반복하는 이벤트 루프 시작
stopCh에 메세지가 들어오면, 이벤트 루프 중지하고 고루틴 종료
context 취소 메세지가 들어오면, 이벤트 루프 중지하고 고루틴 종료
1초 간격 타이머 메세지가 들어오면, 나머지 노드에 하트비트 전송

그리고 그 아래 stopHeartbeat를 보면 고루틴에서 수신하는 stopCh를 close 함수로 닫아버리는데요, 이렇게 하면 모든 수신자에게 중지 신호가 전달됩니다.

context.Context 로 우아한 종료(graceful shutdown)

새로운 노드를 실행하는 runNode, newPaxosNode 함수를 살펴보면, context와 해당 context를 중지시킬 수 있는 cancelFunc를 생성하여 이후 처리 과정에서 계속 사용하도록 전달하고 있습니다.

func newPaxosNode(ctx context.Context, nodeID, port int, peers []string) *PaxosNode {
 ctx, cancel := context.WithCancel(ctx) // context를 중지 시킬 수 있는 cancelFunc 생성
 selfURL := fmt.Sprintf("http://localhost:%d", port)
 allNodes := append([]string{selfURL}, peers...)
 majority := len(allNodes)/2 + 1

 return &PaxosNode{
 ctx: ctx,
 cancel: cancel, // 노드에 cancelFunc 전달
 nodeID: nodeID,
 port: port,
 peers: peers,
 allNodes: allNodes,
 majority: majority,
 httpClient: &http.Client{Timeout: 1 * time.Second},
 }
}

...

func runNode() {
 ...
 ctx := context.Background()
 node := newPaxosNode(ctx, nodeID, port, peers)
 ...
}

// 모든 타이머와 하트비트를 정리하고 context를 취소하는 함수
func (node *PaxosNode) shutdown() {
 ...
 node.cancel() // 노드 중지시 cancelFunc를 실행하여 모든 작업 중지
}

그리고 shutdown 함수를 보면, 노드의 cancelFunc를 실행하여 해당 context와 관련된 모든 작업(http 요청, 타이머, 고루틴 등)을 중지하도록 하고 있습니다.

참고자료

Tucker의 Go 언어 프로그래밍, 공봉식, 골든래빗
요즘 개발자를 위한 시스템 설계 수업. 디렌드라 신하, 테자스 초프라 저. 길벗
CLAUDE

분산 시스템 설계(1) - Paxos 알고리즘

Sat, 14 Feb 2026 10:05:42 +0900

분산 시스템이란?

오래전 시스템은 메인 프레임으로 대표되는 중앙 시스템으로 구성되었습니다. 메인 프레임에 터미널로 연결해서 각자의 작업을 진행했었죠.

(IBM의 701 메인프레임 컴퓨터와 콘솔, 출처: IBM)

그런데 메인 프레임은 엄청난 덩치 뿐만 아니라 취약한 문제가 있었습니다. 메인 프레임이 고장나면 모든 사용자들이 장애의 영향을 받았던 거죠. 그래서 장애를 좀 더 유연하게 견딜 수 있는, 그리고 메인 프레임의 물리적인 한계를 넘어서 처리 용량을 확장할 수 있는 분산 시스템이 등장하기 시작합니다. 제가 기억하는 아주 유명했던 분산 시스템으로 SETI@home(Search for Extra-Terrestrial at home)이 있습니다.

(출처: https://setiathome.berkeley.edu/sah_graphics.php)

1997년에 UC 버클리에서 시작된 프로젝트로 푸에르토 리코에 위치한 아레시보 전파 망원경의 데이터를 통해 외계 생명체의 신호를 탐색하고자 했습니다. 전파 데이터가 너무 방대했기 때문에 이를 처리하기 위해 많은 컴퓨터가 필요했었는데요, 인터넷 연결이 가능한 PC를 가지고 있는 사람 누구나 프로젝트에 참여할 수 있도록 했습니다. 전세계 226개국에서 500만명 이상의 사람들이 자원해서 참여했고, 2020년 데이터 수집이 중단되었다고 합니다.

이렇게 컴퓨팅 파워의 한계와 장애 극복을 위한 분산 컴퓨팅은 계속 발전해왔고 DCOM, CORBA 등의 벤더 종속적인 기술이 등장했습니다. 그리고 SOAP 웹서비스 등의 벤더 독립적인 기술이 등장해 세상을 바꾸나 싶었지만, 찻잔 속의 태풍으로 끝이 났죠. 그리고 SOA 등의 현학적인 용어가 난무하는 시대를 지나 지금 우리는 클라우드가 보편적인 시대를 살고 있습니다. 이제는 분산 시스템이라는 말을 잘 쓰지 않긴합니다. 그게 기본이니까요.

하지만 기본이라는 말은 반대로 하면 원리를 모르는 사람들이 많다는 말도 되겠죠. 물론…. 저도 그 중에 하나입니다. 하하하하….

CAP, PACELC

분산 시스템의 유명한 이론적 정리는 CAP, PACELC가 있습니다. 우선 CAP을 볼까요?

CAP

graph TD
CAP["CAP Theorem<br/>(Brewer's Theorem, 2000)"]
CAP --> C["Consistency<br/>모든 노드가 같은 데이터를 봄"]
CAP --> A["Availability<br/>모든 요청이 응답을 받음"]
CAP --> P["Partition Tolerance<br/>네트워크 분할에도 동작"]
C ~~~ A ~~~ P
subgraph CP["CP Systems"]
CP1["MongoDB"] ~~~ CP2["HBase"] ~~~ CP3["Redis Cluster"]
end
subgraph AP["AP Systems"]
AP1["Cassandra"] ~~~ AP2["DynamoDB"] ~~~ AP3["CouchDB"]
end
subgraph CA["CA Systems (이론적)"]
CA1["Traditional RDBMS<br/>(single node)"]
end
C --> CP
P --> CP
A --> AP
P --> AP
C --> CA
A --> CA
style C fill:#ff9999,stroke:#333
style A fill:#99cc99,stroke:#333
style P fill:#9999ff,stroke:#333
style CP fill:#ffcccc,stroke:#333
style AP fill:#ccffcc,stroke:#333
style CA fill:#ccccff,stroke:#333
style CAP fill:#ffffcc,stroke:#333

Consistency, Availability, Partition Tolerance 이 세가지 요소 중에서 2가지를 선택해야 한다는 게 CAP 이론입니다. 하지만 이 이론에는 함정이 있는데요, 세상에 장애가 발생하지 않은 완벽한 네트워크는 없으므로 반드시 Partition Tolerance는 챙겨야 하기 때문에 CP 또는 AP 둘 중의 하나로 강제된다는 거죠. 그리고 요즘 대세인 결과적 일관성(Eventual Consistency)의 경우 AP에 해당하기는 하지만 일관성(C)을 포기한 건 아니므로 엄밀히 말하면 CAP의 이분법적 분류로는 정확히 설명하기 어렵다는 문제가 있습니다.

PACELC

그래서 대안적으로 제시된 게 PACELC 입니다.

graph TD
PACELC["PACELC Theorem<br/>(Daniel Abadi, 2012)"]
PACELC --> Q{"네트워크 Partition<br/>발생?"}
Q -->|"Yes (P)"| PAC{"Partition 상황"}
Q -->|"No (E)"| ELC{"정상 상황 (Else)"}
PAC -->|"Choose"| PA["Availability<br/>가용성 우선"]
PAC -->|"Choose"| PC["Consistency<br/>일관성 우선"]
ELC -->|"Choose"| EL["Latency<br/>낮은 지연 우선"]
ELC -->|"Choose"| EC["Consistency<br/>일관성 우선"]
subgraph PA_EC["PA/EC Systems"]
direction LR
S1["DynamoDB"] ~~~ S2["Cassandra"] ~~~ S3["CouchDB"]
end
subgraph PA_EL["PA/EL Systems"]
direction LR
S4["Cassandra (tunable)"] ~~~ S5["Riak"]
end
subgraph PC_EC["PC/EC Systems"]
direction LR
S6["MongoDB"] ~~~ S7["HBase"] ~~~ S8["BigTable"]
end
subgraph PC_EL["PC/EL Systems"]
direction LR
S9["PNUTS (Yahoo)"]
end
PA --> PA_EC
PA --> PA_EL
PC --> PC_EC
PC --> PC_EL
EC --> PA_EC
EC --> PC_EC
EL --> PA_EL
EL --> PC_EL
style PACELC fill:#ffffcc,stroke:#333
style Q fill:#fff0e0,stroke:#333
style PAC fill:#ffdddd,stroke:#333
style ELC fill:#ddddff,stroke:#333
style PA fill:#ff9999,stroke:#333
style PC fill:#99ccff,stroke:#333
style EL fill:#99ff99,stroke:#333
style EC fill:#cc99ff,stroke:#333
style PA_EC fill:#ffe0f0,stroke:#333
style PA_EL fill:#e0ffe0,stroke:#333
style PC_EC fill:#e0e0ff,stroke:#333
style PC_EL fill:#fff0e0,stroke:#333

선택지는 다음과 같습니다.

네트워크 장애시(P) -> 가용성(A)이냐 일관성(C)이냐.
정상 상황(E)에서 -> 일관성(C)이냐 낮은 지연(L)이냐.

예를 들면 이번에 알아볼 Paxos 알고리즘은 PC/EC 에 해당합니다.

네트워크 장애시(P) -> 다수의 노드는 동작하지만, 소수의 노드는 동작을 멈춘다. 따라서 일관성(C)을 가용성(A)보다 우선한다.
정상 상황(E)에서 -> 다수의 노드 간에 합의 과정을 거치는데 이 과정에서 보다 많은 지연시간이 발생한다. 따라서 일관성(C)을 낮은 지연(L)보다 우선한다.

Paxos 알고리즘

앞선 정리에서 볼 수 있듯이 Paxos 알고리즘은 합의를 통한 일관성을 가장 중요한 가치로 생각하며, 분산 시스템에서 모든 서버가 같은 상태와 결정을 공유하고 유지할 수 있는 방법을 제안합니다.

Paxos 알고리즘의 핵심 구성 요소는 다음과 같습니다.

제안자(Proposer): 제안자는 합의해야 할 값을 제안하고, 시스템의 다른 노드에 제안값을 전파합니다.
수용자(Acceptor): 제안자에게서 제안을 받고, 제안값의 수용 여부를 다른 노드에 알립니다.
학습자(Learner): 합의된 값을 수용하는 노드.

그럼 이 노드들이 어떻게 서로 합의를 진행하는지 알아볼까요?

sequenceDiagram
participant P as 제안자<br/>(Proposer)
participant A1 as 수용자 1<br/>(Acceptor)
participant A2 as 수용자 2<br/>(Acceptor)
participant A3 as 수용자 3<br/>(Acceptor)
participant L as 학습자<br/>(Learner)
Note over P, L: 📌 1단계: 준비 (Prepare)
rect rgb(220, 240, 255)
P->>A1: Prepare(N)
P->>A2: Prepare(N)
P->>A3: Prepare(N)
A1-->>P: Promise(N)
A2-->>P: Promise(N)
A3-->>P: Promise(N)
Note over P: 과반수 약속 확인 ✅
end
Note over P, L: 📌 2단계: 수락 + 학습 (Accept + Learn)
rect rgb(220, 255, 220)
P->>A1: Accept(N, 값)
P->>A2: Accept(N, 값)
P->>A3: Accept(N, 값)
par 제안자에게 수락 응답
A1-->>P: Accepted ✅
A2-->>P: Accepted ✅
A3-->>P: Accepted ✅
and 학습자에게 동시 전달
A1->>L: Accepted(N, 값)
A2->>L: Accepted(N, 값)
A3->>L: Accepted(N, 값)
end
Note over P: 과반수 수락 → 값 선택 확정 🎉
Note over L: 과반수 수락 확인 → 합의된 값 학습 완료 ✅
end

여기서 중요한 점은 1단계에서는 제안 번호(N)을 제시하고, 2단계에서 제안 번호(N)와 함께 제안 값을 전달한다는 점입니다. 하나씩 알아볼까요?

여기서는 논리적인 구분을 위해서 제안자, 수용자, 학습자를 나눠놓았지만 사실 Paxos에 참여하는 각 노드가 3개의 역할을 모두 수행하는 경우도 있습니다. 이 글의 후반부에서 관련된 예시를 다룰 예정입니다!

1단계: 준비(Prepare)

1단계에서는 제안자가 수용자들에게 자신의 제안번호(N)를 제시하며, 자신의 제안번호(N)에 대해서 ‘수락할 것을 약속해달라(promise)‘고 요청합니다.

수용자들은 제시 받은 제안번호(N)과 이전에 이미 약속한 제안번호(B)에 대해 다음과 같이 반응합니다.

이미 약속한 제안번호(B)가 존재하는가?
존재하지 않는다면, 현재의 제안번호(N)에 대해 수용할 것을 약속한다.
존재한다면, 이미 약속한 제안번호(B)과 현재의 제안번호(N)을 비교한다.
- 이미 약속한 제안번호가 더 크다면(B > N), 현재의 제안번호(N)을 거절한다.
- 현재의 제안번호(N)이 이미 약속한 제안번호(B)보다 더 크다면, 이전 약속(B)을 파기하고 현재의 제안번호(N)에 대해 수용할 것을 약속한다.

flowchart TD
START([수용자가 제안 수신<br/>Prepare N]) --> CHECK{이미 약속한<br/>제안 번호 B가<br/>존재하는가?}
CHECK -->|존재하지 않음| ACCEPT_NEW[✅ 현재 제안 번호 N에 대해<br/>수용할 것을 약속<br/>Promise N]
CHECK -->|존재함| COMPARE{현재 제안 번호 N과<br/>이미 약속한 제안 번호 B<br/>비교}
COMPARE -->|B > N<br/>이미 약속한 번호가 더 큼| REJECT[❌ 현재 제안 거절<br/>Reject N]
COMPARE -->|N > B<br/>현재 제안 번호가 더 큼| ACCEPT_HIGHER[✅ 이전 약속 B 파기<br/>현재 제안 번호 N에 대해<br/>수용할 것을 약속<br/>Promise N]
ACCEPT_NEW --> WAIT([수용 요청 대기<br/>Accept N, 값])
ACCEPT_HIGHER --> WAIT
style START fill:#4A90D9,stroke:#333,color:#fff
style CHECK fill:#F5A623,stroke:#333,color:#fff
style COMPARE fill:#F5A623,stroke:#333,color:#fff
style ACCEPT_NEW fill:#7ED321,stroke:#333,color:#fff
style REJECT fill:#D0021B,stroke:#333,color:#fff
style ACCEPT_HIGHER fill:#7ED321,stroke:#333,color:#fff
style WAIT fill:#9B9B9B,stroke:#333,color:#fff

어떤 값이든 수용할 것을 약속한 노드들은 이제 수용 요청 대시 상태로 진입합니다.

2단계: 수용(Accept)

이제 제안자는 각 수용자에게 자신있게 자신의 제안 번호(N)와 함께 값을 전달합니다. 이제 수용자들은 자신이 수용할 것을 약속한 제안 번호(B)와 비교하며 다음과 같이 반응합니다.

수용할 것을 약속한 제안 번호(B)가 존재하는지 확인
B가 존재하지 않는다면, 제안 번호(N)의 값을 수용(Prepare 없이 Accept가 진행되는 경우는 생각하기 어렵긴 하지만!)
B가 존재한다면, 제안 번호(N)과 비교
- N < B 이면, 이미 약속한 제안 번호(B)가 더 크기 때문에 N을 거절
- N = B 이면, 현재 제안 번호(N)가 수용할 것을 약속한 제안 번호이므로 값을 수용하고, 제안자 및 학습자에게 수용되었음을 통지
- N > B 이면, 현재 제안 번호(N)가 이미 약속한 제안 번호(B)보다 크므로 이전 약속을 파기하고 N을 수용할 것을 약속

flowchart TD
START([수용자가 수락 요청 수신<br/>Accept N, 값]) --> CHECK{현재 약속한<br/>제안번호 B가<br/>존재하는가?}
CHECK -->|존재하지 않음| ACCEPT[✅ 수락<br/>Accepted N, 값]
CHECK -->|존재함| COMPARE{현재 수락 요청의<br/>제안번호 N과<br/>약속한 제안번호 B<br/>비교}
COMPARE -->|B > N<br/>약속한 번호가 더 큼| REJECT[❌ 거절<br/>더 높은 번호에 이미 약속함]
COMPARE -->|N = B<br/>약속한 번호와 동일| ACCEPT2[✅ 수락<br/>Accepted N, 값]
COMPARE -->|N > B<br/>수락 요청 번호가 더 큼| ACCEPT3[✅ 수락<br/>Accepted N, 값]
ACCEPT --> NOTIFY([제안자 + 학습자에게<br/>Accepted 전달])
ACCEPT2 --> NOTIFY
ACCEPT3 --> NOTIFY
REJECT --> WAIT([제안자에게 거절 응답])
style START fill:#4A90D9,stroke:#333,color:#fff
style CHECK fill:#F5A623,stroke:#333,color:#fff
style COMPARE fill:#F5A623,stroke:#333,color:#fff
style ACCEPT fill:#7ED321,stroke:#333,color:#fff
style ACCEPT2 fill:#7ED321,stroke:#333,color:#fff
style ACCEPT3 fill:#7ED321,stroke:#333,color:#fff
style REJECT fill:#D0021B,stroke:#333,color:#fff
style NOTIFY fill:#9B9B9B,stroke:#333,color:#fff
style WAIT fill:#9B9B9B,stroke:#333,color:#fff

위 다이어그램에서 볼 수 있듯이 Prepare 단계에서 과반수의 약속을 받았더라도 Accept 단계에서 거절될 수도 있습니다. 더 높은 제안 번호의 Prepare가 중간에 끼어들 수도 있기 때문이죠.

좀 더 쓸모있는 예시를 들어보자: 분산 시스템의 리더 노드 선출

자, 알고리즘은 뭐 이런 식으로 진행됩니다. 그런데 제가 이 내용을 처음 봤을 때는 솔직히 뭐 어쩌라고? 싶었습니다. 이게 도대체 뭔 소린지, 그리고 어디다가 써먹을 수 있다는 건지 영 감이 안잡혔죠. 그래서 이리저리 머리를 굴려보다가 그럴듯한 예시를 하나 생각해냈습니다.

우리가 쓰는 디비든 쿠버네티스 같은 인프라 운영 시스템이든 각종 실패를 견디기 위해서 노드를 분산해둡니다. 쿠버네티스의 경우 클러스터 운영을 위한 마스터 노드(또는 컨트롤 플레인)와 서비스를 돌리기 위한 워커 노드가 있죠. 특히 마스터 노드의 경우 전체 시스템 관리 및 워커 노드를 제어하는 등의 핵심 역할을 맡고 있습니다. 이런 마스터 노드가 죽으면 곤란하기 때문에 여러 마스터 노드를 실행해서 특정 노드에 장애가 생겨도 서비스 운영에 문제가 없도록 하고 있죠.

그런데 이 글을 시작하면서 분산 시스템에서는 합의가 중요하다고 했었습니다. 여러대의 마스터 노드가 있을 때 각자 서로 다른 결정을 하면 안되겠죠. 그래서 리더 노드를 선출하고 다른 노드들은 리더가 결정한 내용을 따르도록 하고 있습니다. 지금 부터 살펴볼 예제는 바로 그 리더를 선출하는 과정을 Paxos 알고리즘으로 구현해 볼 겁니다!

시스템 개요

간결한 구현을 위해서 시작점이 되는 cli 앱이 3개의 웹 서버 클러스터를 실행하고, 3개의 웹 서버가 서로 통신하면서 Paxos 알고리즘을 통해 리더를 선출하게 됩니다. 그리고 필요에 따라서 각 서버를 죽이거나 재실행해서 다양한 경우를 실험해 볼 수 있도록 할 겁니다.

원래 이런 시스템은 멀티 Paxos로 구현해야 합니다. Paxos는 원래 합의를 한 번 하면 그걸로 끝이기 때문에 여러번의 합의를 하려면 계속 새로운 Paxos 인스턴스를 생성해야 합니다. 그런데 그렇게 하면 너무 복잡하니까, 단일 Paxos로 구현해서 매 라운드 마다 상태 값을 초기화 하고 다시 설정하는 형태로 구현해서 멀티 Paxos를 흉내내는 형태로 구현할 겁니다.

node.js와 typescript를 이용해서 2개의 파일로 구현할 겁니다.

runCluster.ts: 3개의 웹 서버를 실행하고 관리하는 클러스터 관리자 cli 구현
node.ts: 각 웹서버를 express로 구현

그리고 시스템 아키텍처는 다음과 같습니다.

graph TD
USER["사용자 터미널"] --> CLI["runCluster.ts<br/>(클러스터 관리자 + 대화형 CLI)<br/>━━━━━━━━━━━━━━━━<br/>- child_process.spawn으로 3개 노드 생성<br/>- 각 노드 stdout에 색상 적용 출력<br/>- readline으로 대화형 CLI 제공"]
CLI -->|"spawn: npx tsx node.ts 1 3001 ..."| N1["node.ts (노드 1)<br/>:3001"]
CLI -->|"spawn: npx tsx node.ts 2 3002 ..."| N2["node.ts (노드 2)<br/>:3002"]
CLI -->|"spawn: npx tsx node.ts 3 3003 ..."| N3["node.ts (노드 3)<br/>:3003"]
N1 <-->|"HTTP POST"| N2
N2 <-->|"HTTP POST"| N3
N1 <-->|"HTTP POST"| N3
style CLI fill:#f9f,stroke:#333,stroke-width:2px
style N1 fill:#36c,stroke:#333,color:#fff
style N2 fill:#c93,stroke:#333,color:#fff
style N3 fill:#c3c,stroke:#333,color:#fff

runCluster.ts가 3개의 웹서버 노드 프로세스를 생성하고, 각 노드는 Express 서버를 실행하여 HTTP로 통신합니다.

클러스터 관리자 cli 구현

클러스터 관리자 cli는 각 웹서버 노드 프로세스를 실행하고, 특정 노드 프로세스를 죽이거나 다시 시작하거나 할 수 있습니다.

graph LR
CLI["대화형 CLI<br/>(readline)"] --> KILL["kill &lt;id&gt;"]
CLI --> START["start &lt;id&gt;"]
CLI --> STATUS["status"]
CLI --> EXIT["exit"]
KILL --> K_ACTION["child.kill('SIGTERM')<br/>→ 노드 프로세스 종료"]
START --> S_ACTION["startNode(nodeConfig)<br/>→ 새 child_process.spawn<br/>→ 노드 재시작"]
STATUS --> ST_ACTION["fetch GET /status<br/>→ 각 노드 상태 조회<br/>→ 콘솔 출력"]
EXIT --> E_ACTION["processes.forEach(p => p.kill('SIGTERM'))<br/>→ 모든 노드 종료<br/>→ process.exit(0)"]
style CLI fill:#f9f,stroke:#333
style K_ACTION fill:#fcc,stroke:#333
style S_ACTION fill:#cfc,stroke:#333
style ST_ACTION fill:#ccf,stroke:#333
style E_ACTION fill:#ffc,stroke:#333

runCluster.ts의 전체 코드는 다음과 같습니다.

import { spawn, ChildProcess } from 'child_process';
import * as readline from 'readline';
import { fileURLToPath } from 'url';
import { dirname } from 'path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

type NodeConfig = {
 id: number;
 port: number;
};

// 각 노드 아이디와 포트 번호 정의
const NODES: NodeConfig[] = [
 { id: 1, port: 3001 },
 { id: 2, port: 3002 },
 { id: 3, port: 3003 }
];

// 노드 프로세스 관리를 위한 맵 정의
const processes = new Map<number, ChildProcess>();

// 가독성을 위해 각 노드의 아이디별 출력 색상 정의
const colors = {
 1: '\x1b[36m', // 파란색
 2: '\x1b[33m', // 노란색
 3: '\x1b[35m', // 핑크색
 reset: '\x1b[0m', // 기본 색상
};

/**
 * 노드 프로세스를 시작하는 함수
 * @param nodeConfig - 노드 아이디와 포트 번호 정의
 */
function startNode(nodeConfig: NodeConfig) {
 // 현재 노드가 통신해야 할 다른 노드의 URL 목록 생성
 const peers: string[] = NODES
 .filter((n: NodeConfig) => n.id !== nodeConfig.id)
 .map((n: NodeConfig) => `http://localhost:${n.port}`);

 console.log(`${colors[nodeConfig.id as keyof typeof colors]}노드 ${nodeConfig.id} 시작...${colors.reset}`);

 // 노드 프로세스 생성
 const child = spawn(
 'npx',
 ['tsx', 'node.ts', String(nodeConfig.id), String(nodeConfig.port), ...peers],
 {
 cwd: __dirname,
 stdio: ['ignore', 'pipe', 'pipe'],
 }
 );

 // 노드 프로세스의 출력에 색상을 적용 하여 출력
 child.stdout?.on('data', (data: Buffer) => {
 const color = colors[nodeConfig.id as keyof typeof colors] || colors.reset;
 process.stdout.write(`${color}${data.toString()}${colors.reset}`);
 });

 // 노드 프로세스의 에러 출력에 색상을 적용 하여 출력
 child.stderr?.on('data', (data: Buffer) => {
 const color = colors[nodeConfig.id as keyof typeof colors] || colors.reset;
 process.stderr.write(`${color}[노드 ${nodeConfig.id} 오류] ${data.toString()}${colors.reset}`);
 });

 // 노드 프로세스가 종료될 때 처리
 child.on('exit', (code, signal) => {
 console.log(`${colors[nodeConfig.id as keyof typeof colors]}[노드 ${nodeConfig.id}] 프로세스 종료 (code: ${code}, signal: ${signal})${colors.reset}`);
 processes.delete(nodeConfig.id);
 });

 // 노드 프로세스를 관리하는 맵에 추가
 processes.set(nodeConfig.id, child);
}

/**
 * 노드 프로세스 종료
 * @param id - 종료할 노드의 아이디
 */
function killNode(id: number) {
 const child = processes.get(id);

 // 노드 프로세스가 존재하면 종료
 if (child) {
 child.kill('SIGTERM');
 console.log(`\n${colors[id as keyof typeof colors]}[클러스터] 노드 ${id} 종료${colors.reset}\n`);
 } else {
 console.log(`\n[클러스터] 노드 ${id} 실행 중이 아님\n`);
 }
}

/**
 * 클러스터 상태 출력
 */
async function printStatus() {
 console.log('\n=== 클러스터 상태 ===');

 for (const node of NODES) {
 try {
 const res = await fetch(`http://localhost:${node.port}/status`, {
 signal: AbortSignal.timeout(1000),
 });
 const data = await res.json();
 const color = colors[node.id as keyof typeof colors] || colors.reset;
 const leaderMark = data.isLeader ? '👑' : ' ';

 // 노드 상태 출력
 console.log(
 `${color}${leaderMark} 노드 ${node.id}: 리더=${data.currentLeaderId ?? '없음'}, ` +
 `턴=${data.currentTerm}, 리더=${data.isLeader}, ` +
 `약속한 제안 번호=${data.promisedProposal ?? '없음'}, 수락한 제안 번호=${data.acceptedProposal ?? '없음'}${colors.reset}`
 );
 } catch {
 const color = colors[node.id as keyof typeof colors] || colors.reset;
 console.log(`${color} 노드 ${node.id}: ❌ 다운${colors.reset}`);
 }
 }

 console.log('');
}

/**
 * 대화형 CLI 구현
 */

const rl = readline.createInterface({
 input: process.stdin,
 output: process.stdout,
});

// 모든 노드 시작
console.log('\n🚀 Starting Paxos Leader Election Cluster...\n');
for (const node of NODES) {
 startNode(node);
}

// 모든 노드가 시작될 때까지 대기 후 명령어 출력
setTimeout(() => {
 console.log('\n' + '='.repeat(60));
 console.log('📋 사용 가능한 명령어:');
 console.log(' kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)');
 console.log(' start <id> - 종료된 노드 재시작');
 console.log(' status - 클러스터 상태 출력');
 console.log(' exit - 모든 노드 종료 및 종료');
 console.log('='.repeat(60) + '\n');
}, 1000);

// 대화형 CLI 명령어 처리
rl.on('line', async (line: string) => {
 const [cmd, arg] = line.trim().split(' ');

 // 명령어 처리
 switch (cmd) {
 case 'kill':
 const killId = parseInt(arg);
 if (NODES.find((n) => n.id === killId)) {
 killNode(killId);
 } else {
 console.log(`잘못된 노드 ID: ${arg}\n`);
 }
 break;

 case 'start':
 const startId = parseInt(arg);
 const node = NODES.find((n) => n.id === startId);
 if (node) {
 if (processes.has(startId)) {
 console.log(`\n노드 ${startId}: 이미 실행 중\n`);
 } else {
 startNode(node);
 }
 } else {
 console.log(`잘못된 노드 ID: ${arg}\n`);
 }
 break;

 case 'status':
 await printStatus();
 break;

 case 'exit':
 console.log('\n🛑 모든 노드 종료...\n');
 processes.forEach((p) => p.kill('SIGTERM'));
 setTimeout(() => process.exit(0), 500);
 break;

 case 'help':
 console.log('\n📋 사용 가능한 명령어:');
 console.log(' kill <id> - 노드 종료');
 console.log(' start <id> - 종료된 노드 재시작');
 console.log(' status - 클러스터 상태 출력');
 console.log(' exit - 모든 노드 종료 및 종료\n');
 break;

 default:
 if (line.trim()) {
 console.log(`알 수 없는 명령어: ${cmd}. 'help' 명령어를 사용하여 사용 가능한 명령어를 확인하세요.\n`);
 }
 }
});

// Ctrl+C 처리
process.on('SIGINT', () => {
 console.log('\n\n🛑 모든 노드 종료...\n');
 processes.forEach((p) => p.kill('SIGTERM'));
 setTimeout(() => process.exit(0), 500);
});

웹 서버 노드 구현

웹 서버 노드는 paxos 알고리즘을 위한 변수들과 각종 타이머, API 라우트 등을 포함하고 있습니다.

graph TD
subgraph CONFIG["설정 (Configuration)"]
C1["nodeId: number<br>자신의 노드ID"] ~~~ C2["port: number"] ~~~ C3["peers: string[]<br>자신을 제외한 클러스터의 노드"] ~~~ C4["allNodes: string[]<br>자신을 포함한 클러스터의 모든 노드"] ~~~ C5["majority: number<br>다수 노드의 수"]
end
subgraph PAXOS["Paxos Acceptor 상태"]
P1["promisedProposal: number | null<br>수락을 약속한 제안번호"] ~~~ P2["acceptedProposal: number | null<br>수락한 제안번호"] ~~~ P3["acceptedValue: number | null<br>수락한 값(리더의 노드ID)"]
end
subgraph LEADER["Leader 상태"]
L1["currentLeaderId: number | null"] ~~~ L2["currentTurn: number"] ~~~ L3["electionRound: number"]
end
subgraph TIMERS["타이머"]
T1["heartbeatTimer: NodeJS.Timeout | null<br/>(setInterval 1초 주기, 리더가 자신이 살아있음을 전송)"] ~~~ T2["electionTimer: NodeJS.Timeout | null<br/>(setTimeout 3~5초, 리더는 중지)"]
end
subgraph ROUTES["Express Routes"]
R1["POST /paxos/prepare"] ~~~ R2["POST /paxos/accept"] ~~~ R3["POST /leader/heartbeat"] ~~~ R4["GET /status"]
end
subgraph LOGIC["핵심 로직 함수"]
F1["runElection()"] ~~~ F2["startHeartbeat()"] ~~~ F3["stopHeartbeat()"] ~~~ F4["resetElectionTimeout()"] ~~~ F5["scheduleNextElection()"]
end
CONFIG --> PAXOS --> LEADER --> TIMERS --> ROUTES --> LOGIC
style CONFIG fill:#e0f0ff,stroke:#333
style PAXOS fill:#ffe0f0,stroke:#333
style LEADER fill:#f0ffe0,stroke:#333
style TIMERS fill:#fff0e0,stroke:#333
style ROUTES fill:#f0e0ff,stroke:#333
style LOGIC fill:#e0fff0,stroke:#333

각 API는 paxos 알고리즘의 Prepare, Accept 단계를 위한 /paxos/prepare, /paxos/accept와 리더의 생존 신호를 수신할 /leader/heartbeat를 구현합니다.

graph LR
N["노드 (Proposer/Acceptor)"]
N -->|"POST /paxos/prepare<br/>{proposalNumber: N}"| PREP["Phase 1: PREPARE"]
PREP -->|"{promise: boolean,<br/>acceptedProposal: number | null,<br/>acceptedValue: number | null}"| N
N -->|"POST /paxos/accept<br/>{proposalNumber: N, value: V}"| ACC["Phase 2: ACCEPT"]
ACC -->|"{accepted: boolean}"| N
N -->|"POST /leader/heartbeat<br/>{leaderId: L, term: T}"| HB["하트비트 수신"]
HB -->|"{ok: true}"| N
N -->|"GET /status"| ST["상태 조회"]
ST -->|"{nodeId, currentLeaderId,<br/>currentTerm, promisedProposal,<br/>acceptedProposal, acceptedValue,<br/>isLeader}"| N
style PREP fill:#ffcccc,stroke:#333
style ACC fill:#ccffcc,stroke:#333
style HB fill:#ccccff,stroke:#333
style ST fill:#ffffcc,stroke:#333

엔드포인트 요약:

엔드포인트	메서드	요청	응답	용도
`/paxos/prepare`	POST	`{ proposalNumber }`	`{ promise, acceptedProposal, acceptedValue }`	Paxos Phase 1 - 약속 요청
`/paxos/accept`	POST	`{ proposalNumber, value }`	`{ accepted }`	Paxos Phase 2 - 수락 요청
`/leader/heartbeat`	POST	`{ leaderId, term }`	`{ ok }`	리더 생존 신호 전송
`/status`	GET	-	전체 상태 객체	노드 상태 조회 (디버깅용)

node.ts의 전체 코드는 다음과 같습니다.

import express from 'express';

// === 타입 정의 ===

type NodeConfig = {
 id: number;
 port: number;
 peers: string[];
};

type PrepareRequest = {
 proposalNumber: number;
};

type PrepareResponse = {
 promise: boolean;
 acceptedProposal: number | null;
 acceptedValue: number | null;
};

type AcceptRequest = {
 proposalNumber: number;
 value: number;
};

type AcceptResponse = {
 accepted: boolean;
};

type HeartbeatMessage = {
 leaderId: number;
 term: number;
};

// cli 매개변수로 전달받은 노드 아이디, 포트, 통신해야 할 다른 노드의 URL 목록 등의 값을 변수에 저장
const nodeId = parseInt(process.argv[2]);
const port = parseInt(process.argv[3]);
const peers = process.argv.slice(4);
const allNodes = [`http://localhost:${port}`, ...peers];
const majority = Math.floor(allNodes.length / 2) + 1;

console.log(`[노드 ${nodeId}] 시작 with 통신해야 할 다른 노드의 URL 목록: ${peers.join(', ')}`);
console.log(`[노드 ${nodeId}] 다수 필요: ${allNodes.length} 중 ${majority} 이상`);

// === Paxos Acceptor 상태 변수들 ===

let promisedProposal: number | null = null;
let acceptedProposal: number | null = null;
// 수락된 값(리더의 노드 아이디)
let acceptedValue: number | null = null;

// === Leader 상태와 Heartbeat ===

let currentLeaderId: number | null = null;
let currentTerm: number = 0;
// 리더의 하트비트 전송 타이머
let heartbeatTimer: NodeJS.Timeout | null = null;
// 리더 부재시 선출을 진행하기 위한 타이머
let electionTimer: NodeJS.Timeout | null = null;
let electionRound = 0;

// === Paxos Proposer 로직 ===

/**
 * 리더 선출 시작
 * @returns 리더 선출 성공 여부, 실패시 null 반환
 */
async function runElection(): Promise<boolean | null> {
 // 제안 번호가 이미 있는 것보다 큰지 확인
 if (promisedProposal !== null) {
 /**
 * 이전에 약속된 제안 번호가 있는 경우, 라운드 조정(다른 노드가 이미 제안한 제안 번호보다 높은 제안 번호를 사용하도록 함)
 *
 * ex: Math.max(0, Math.ceil(6 / 3)) = Math.max(0, 2) = 2
 */
 electionRound = Math.max(electionRound, Math.ceil(promisedProposal / allNodes.length));
 }
 electionRound++;

 /**
 * 제안 번호 = 노드 아이디 + (라운드 * 노드 개수) -> 각 라운드 마다 노드의 제안 번호의 고유성을 보장하기 위함
 *
 * 예를 들어, 노드 1, 2, 3이 있고, 라운드가 1인 경우,
 * 노드 1, 라운드 1: 1 + (1 * 3) = 4
 * 노드 2, 라운드 1: 2 + (1 * 3) = 5
 * 노드 3, 라운드 1: 3 + (1 * 3) = 6
 * 노드 1, 라운드 2: 1 + (2 * 3) = 7
 * 노드 2, 라운드 2: 2 + (2 * 3) = 8
 * 노드 3, 라운드 2: 3 + (2 * 3) = 9
 * ...
 */
 const proposalNumber = nodeId + (electionRound * allNodes.length);

 console.log(`\n[노드 ${nodeId}] 🗳️ 리더 선출 시작 / 제안 번호 #${proposalNumber}`);

 // Phase 1: PREPARE 요청 전송
 console.log(`[노드 ${nodeId}] Phase 1: 모든 노드에 PREPARE 요청 전송...`);

 const preparePromises = allNodes.map(async (nodeUrl) => {
 // 자신을 포함한 모든 노드에 PREPARE 요청 전송
 try {
 // PREPARE 요청 전송
 const response = await fetch(`${nodeUrl}/paxos/prepare`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ proposalNumber } as PrepareRequest),
 signal: AbortSignal.timeout(1000),
 });

 // PREPARE 요청 실패 시 null 반환
 if (!response.ok) return null;
 return await response.json() as PrepareResponse;
 } catch (error) {
 // PREPARE 요청 실패 시 null 반환
 return null;
 }
 });

 // PREPARE 요청 결과 처리
 const prepareResults = await Promise.allSettled(preparePromises);
 // PREPARE 요청 결과 중 성공한 것들 중 약속을 받은 것들만 추출
 const promises = prepareResults
 .filter((r): r is PromiseFulfilledResult<PrepareResponse> =>
 r.status === 'fulfilled' && r.value !== null && !!r.value.promise
 )
 .map((r) => r.value);

 console.log(`[노드 ${nodeId}] Phase 1: 약속을 받은 노드 ${promises.length}/${allNodes.length} 개 (필요 ${majority} 개)`);

 if (promises.length < majority) {
 console.log(`[노드 ${nodeId}] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.`);
 scheduleNextElection();
 return false;
 }

 // 수락된 값 중 가장 높은 값을 채택, 없으면 자신을 제안
 let proposedValue = nodeId;
 let highestAcceptedProposal = -1;

 for (const p of promises) {
 // 수락된 값 중 가장 높은 값을 채택
 if (p.acceptedProposal !== null && p.acceptedProposal > highestAcceptedProposal) {
 highestAcceptedProposal = p.acceptedProposal;
 proposedValue = p.acceptedValue!;
 }
 }

 if (highestAcceptedProposal > -1) {
 console.log(`[노드 ${nodeId}] Phase 1: 이전에 수락된 값 (노드 ${proposedValue}) 채택 / 제안 번호 #${highestAcceptedProposal}`);
 } else {
 console.log(`[노드 ${nodeId}] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 ${proposedValue})`);
 }

 // Phase 2: Accept
 console.log(`[노드 ${nodeId}] Phase 2: 모든 노드에 ACCEPT (값: 노드 ${proposedValue}) 요청 전송...`);

 const acceptPromises = allNodes.map(async (nodeUrl) => {
 // 자신을 포함한 모든 노드에 ACCEPT 요청 전송
 try {
 // ACCEPT 요청 전송
 const response = await fetch(`${nodeUrl}/paxos/accept`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ proposalNumber, value: proposedValue } as AcceptRequest),
 signal: AbortSignal.timeout(1000),
 });

 // ACCEPT 요청 실패 시 null 반환
 if (!response.ok) return null;
 return await response.json() as AcceptResponse;
 } catch (error) {
 // ACCEPT 요청 실패 시 null 반환
 return null;
 }
 });

 // ACCEPT 요청 결과 처리
 const acceptResults = await Promise.allSettled(acceptPromises);
 // ACCEPT 요청 결과 중 성공한 것들 중 수락된 것들만 추출
 const accepts = acceptResults
 .filter((r) => r.status === 'fulfilled' && r.value !== null && r.value.accepted)
 .length;

 console.log(`[노드 ${nodeId}] Phase 2: 수락된 노드 ${accepts}/${allNodes.length} 개 (필요 ${majority} 개)`);

 if (accepts >= majority) {
 console.log(`[노드 ${nodeId}] ✅ 리더 선출 성공! 노드 ${proposedValue} 가 리더가 되었습니다. (제안 번호 ${proposalNumber})`);

 if (proposedValue === nodeId) {
 console.log(`[노드 ${nodeId}] 👑 나는 리더!`);
 // 리더는 자신의 선출 타임아웃을 중지 (팔로워만 타임아웃을 감시해야 함)
 if (electionTimer) {
 clearTimeout(electionTimer);
 electionTimer = null;
 }
 startHeartbeat(proposalNumber);
 }

 return true;
 } else {
 console.log(`[노드 ${nodeId}] ❌ Phase 2 실패: 수락된 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.`);
 scheduleNextElection();
 return false;
 }
}

/**
 * 다음 리더 선출 예약
 */
function scheduleNextElection() {
 // 다음 선거 시작 전 랜덤 딜레이 적용
 const delay = 2000 + Math.random() * 3000;
 setTimeout(() => {
 // 현재 리더가 없으면 다음 선거 시작
 if (currentLeaderId === null) {
 runElection();
 }
 }, delay);
}

/**
 * 하트비트 시작
 * @param term 현재 턴
 */
function startHeartbeat(term: number) {
 // 하트비트 중지
 stopHeartbeat();

 heartbeatTimer = setInterval(() => {
 console.log(`[노드 ${nodeId}] 💓 하트비트 전송 (턴 ${term})`);

 // 자신(리더)를 제외한 나머지 노드에 하트비트 전송
 peers.forEach(async (peerUrl) => {
 try {
 await fetch(`${peerUrl}/leader/heartbeat`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ leaderId: nodeId, term } as HeartbeatMessage),
 signal: AbortSignal.timeout(1000),
 });
 } catch (error) {
 // 노드 다운 시 무시
 }
 });
 }, 1000);
}

/**
 * 하트비트 중지
 */
function stopHeartbeat() {
 if (heartbeatTimer) {
 clearInterval(heartbeatTimer);
 heartbeatTimer = null;
 }
}

/**
 * 리더 선출 타임아웃 리셋
 *
 * 타임아웃 이후, 리더가 없으면 리더 선출 시작
 */
function resetElectionTimeout() {
 if (electionTimer) {
 clearTimeout(electionTimer);
 }

 // 리더 선출 타임아웃 랜덤 적용 (3-5초)
 const timeout = 3000 + Math.random() * 2000;

 electionTimer = setTimeout(() => {
 console.log(`[노드 ${nodeId}] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...`);
 currentLeaderId = null;
 // 현재 리더로 선출된 노드가 서비스 다운되는 경우에 해당 노드는 리더 선출에서 제외되어야 함
 // 따라서 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함
 acceptedProposal = null;
 acceptedValue = null;
 runElection();
 }, timeout);
}

// === Express Routes ===

const app = express();
app.use(express.json());

// Paxos Phase 1: Prepare
app.post('/paxos/prepare', (req, res) => {
 const { proposalNumber } = req.body as PrepareRequest;

 console.log(`[노드 ${nodeId}] PREPARE 요청 수신 / 제안 번호 #${proposalNumber}`);

 if (promisedProposal === null || proposalNumber > promisedProposal) {
 promisedProposal = proposalNumber;
 // 수락된 상태를 리셋하여 진행하며, 각 리더 선출은 사실상 새로운 Paxos 인스턴스가 되도록 함(죽은 리더 재선출 방지)
 acceptedProposal = null;
 acceptedValue = null;
 console.log(`[노드 ${nodeId}] → 제안 번호 #${proposalNumber} 약속`);

 res.json({
 promise: true,
 acceptedProposal: null,
 acceptedValue: null,
 } as PrepareResponse);
 } else {
 console.log(`[노드 ${nodeId}] → 이미 약속한 제안 번호 #${promisedProposal} 거절`);
 res.json({
 promise: false,
 acceptedProposal: null,
 acceptedValue: null,
 } as PrepareResponse);
 }
});

// Paxos Phase 2: ACCEPT 요청 처리
app.post('/paxos/accept', (req, res) => {
 const { proposalNumber, value } = req.body as AcceptRequest;

 console.log(`[노드 ${nodeId}] ACCEPT 요청 수신 / 제안 번호 #${proposalNumber}, 값: 노드 ${value}`);

 // 약속된 제안 번호가 없거나, 현재 제안 번호가 약속된 제안 번호보다 크거나 같으면 수락
 if (promisedProposal === null || proposalNumber >= promisedProposal) {
 // 약속된 제안 번호 갱신
 promisedProposal = proposalNumber;
 // 수락된 제안 번호 갱신
 acceptedProposal = proposalNumber;
 // 수락된 값 갱신(리더의 노드 아이디)
 acceptedValue = value;
 // 현재 리더 아이디 갱신
 currentLeaderId = value;
 // 현재 턴 갱신
 currentTerm = proposalNumber;

 console.log(`[노드 ${nodeId}] → 수락! 새로운 리더: 노드 ${value} (제안 번호 ${proposalNumber})`);

 // 리더가 아니라면 하트비트 중지
 if (value !== nodeId) {
 stopHeartbeat();
 }

 // 리더 선출 타임아웃 리셋
 resetElectionTimeout();

 res.json({ accepted: true } as AcceptResponse);
 } else {
 console.log(`[노드 ${nodeId}] → 이미 약속한 제안 번호 #${promisedProposal} 거절`);
 res.json({ accepted: false } as AcceptResponse);
 }
});

// 리더가 전송하는 하트비트 수신
app.post('/leader/heartbeat', (req, res) => {
 const { leaderId, term } = req.body as HeartbeatMessage;

 // 새로운 턴이 시작되었다면,
 if (term >= currentTerm) {
 // 새로운 리더가 등장했다면,
 if (leaderId !== currentLeaderId) {
 console.log(`[노드 ${nodeId}] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 ${leaderId} (턴 ${term})`);
 }

 // 현재 리더 아이디 갱신
 currentLeaderId = leaderId;
 // 현재 턴 갱신
 currentTerm = term;

 /**
 * 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 *
 * 리더의 하트비트가 안정적으로 수신된다면, 리더 선출의 타임아웃은 계속 리셋된다. -> 현재 상태 유지.
 */
 resetElectionTimeout();
 }

 res.json({ ok: true });
});

// 상태 조회 엔드포인트
app.get('/status', (req, res) => {
 res.json({
 nodeId,
 currentLeaderId,
 currentTerm,
 promisedProposal,
 acceptedProposal,
 acceptedValue,
 isLeader: currentLeaderId === nodeId,
 });
});

// === 메인 함수 ===

app.listen(port, () => {
 console.log(`[노드 ${nodeId}] 🚀 포트 ${port}에서 수신 중...`);

 // 리더 선출 예약(랜덤 딜레이 적용)
 const delay = 1000 + Math.random() * 2000;
 console.log(`[노드 ${nodeId}] 리더 조회 전 ${Math.round(delay)}ms 대기...`);

 // 랜덤 딜레이 이후, 리더가 없으면 리더 선출 시작
 setTimeout(() => {
 if (currentLeaderId === null) {
 console.log(`[노드 ${nodeId}] 리더 없음, 리더 선출 시작...`);
 runElection();
 }
 }, delay);

 // 리더 선출 타임아웃 리셋(타임아웃 이후, 리더가 없으면 리더 선출 시작)
 resetElectionTimeout();
});

이제 돌려보자!

이제 모든 준비가 끝났습니다. npm start 명령으로 예제를 실행해볼까요?

❯ npm start

> paxos-leader-election@1.0.0 start
> npx tsx runCluster.ts


🚀 Starting Paxos Leader Election Cluster...

노드 1 시작...
노드 2 시작...
노드 3 시작...
[노드 1] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3002, http://localhost:3003
[노드 2] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3001, http://localhost:3003
[노드 2] 다수 필요: 3 중 2 이상
[노드 3] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3001, http://localhost:3002
[노드 3] 다수 필요: 3 중 2 이상
[노드 1] 다수 필요: 3 중 2 이상
[노드 2] 🚀 포트 3002에서 수신 중...
[노드 2] 리더 조회 전 2639ms 대기...
[노드 3] 🚀 포트 3003에서 수신 중...
[노드 3] 리더 조회 전 2096ms 대기...
[노드 1] 🚀 포트 3001에서 수신 중...
[노드 1] 리더 조회 전 1722ms 대기...

============================================================
📋 사용 가능한 명령어:
 kill <id> - 노드 종료 (특정 노드에 장애가 발생하여 종료되는 걸 시뮬레이션)
 start <id> - 종료된 노드 재시작
 status - 클러스터 상태 출력
 exit - 모든 노드 종료 및 종료
============================================================

[노드 1] 리더 없음, 리더 선출 시작...

[노드 1] 🗳️ 리더 선출 시작 / 제안 번호 #4
[노드 1] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 1] PREPARE 요청 수신 / 제안 번호 #4
[노드 1] → 제안 번호 #4 약속
[노드 3] PREPARE 요청 수신 / 제안 번호 #4
[노드 3] → 제안 번호 #4 약속
[노드 2] PREPARE 요청 수신 / 제안 번호 #4
[노드 2] → 제안 번호 #4 약속
[노드 1] Phase 1: 약속을 받은 노드 3/3 개 (필요 2 개)
[노드 1] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 1)
[노드 1] Phase 2: 모든 노드에 ACCEPT (값: 노드 1) 요청 전송...
[노드 1] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 1] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 3] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 3] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 2] ACCEPT 요청 수신 / 제안 번호 #4, 값: 노드 1
[노드 2] → 수락! 새로운 리더: 노드 1 (제안 번호 4)
[노드 1] Phase 2: 수락된 노드 3/3 개 (필요 2 개)
[노드 1] ✅ 리더 선출 성공! 노드 1 가 리더가 되었습니다. (제안 번호 4)
[노드 1] 👑 나는 리더!
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
[노드 1] 💓 하트비트 전송 (턴 4)
ki[노드 1] 💓 하트비트 전송 (턴 4)
ll[노드 1] 💓 하트비트 전송 (턴 4)
 1[노드 1] 💓 하트비트 전송 (턴 4)


[클러스터] 노드 1 종료

[노드 1] 프로세스 종료 (code: 143, signal: null)
[노드 3] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 3] 🗳️ 리더 선출 시작 / 제안 번호 #12
[노드 3] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 2] PREPARE 요청 수신 / 제안 번호 #12
[노드 2] → 제안 번호 #12 약속
[노드 3] PREPARE 요청 수신 / 제안 번호 #12
[노드 3] → 제안 번호 #12 약속
[노드 3] Phase 1: 약속을 받은 노드 2/3 개 (필요 2 개)
[노드 3] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 3)
[노드 3] Phase 2: 모든 노드에 ACCEPT (값: 노드 3) 요청 전송...
[노드 3] ACCEPT 요청 수신 / 제안 번호 #12, 값: 노드 3
[노드 3] → 수락! 새로운 리더: 노드 3 (제안 번호 12)
[노드 2] ACCEPT 요청 수신 / 제안 번호 #12, 값: 노드 3
[노드 2] → 수락! 새로운 리더: 노드 3 (제안 번호 12)
[노드 3] Phase 2: 수락된 노드 2/3 개 (필요 2 개)
[노드 3] ✅ 리더 선출 성공! 노드 3 가 리더가 되었습니다. (제안 번호 12)
[노드 3] 👑 나는 리더!
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
st[노드 3] 💓 하트비트 전송 (턴 12)
art 1
노드 1 시작...
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 1] 시작 with 통신해야 할 다른 노드의 URL 목록: http://localhost:3002, http://localhost:3003
[노드 1] 다수 필요: 3 중 2 이상
[노드 1] 🚀 포트 3001에서 수신 중...
[노드 1] 리더 조회 전 1960ms 대기...
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 1] 💓 새로운 리더로부터 하트비트 수신 / 리더: 노드 3 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
[노드 3] 💓 하트비트 전송 (턴 12)
k[노드 3] 💓 하트비트 전송 (턴 12)
ill 3[노드 3] 💓 하트비트 전송 (턴 12)


[클러스터] 노드 3 종료

[노드 3] 프로세스 종료 (code: 143, signal: null)
[노드 1] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 1] 🗳️ 리더 선출 시작 / 제안 번호 #4
[노드 1] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 2] PREPARE 요청 수신 / 제안 번호 #4
[노드 2] → 이미 약속한 제안 번호 #12 거절
[노드 1] PREPARE 요청 수신 / 제안 번호 #4
[노드 1] → 제안 번호 #4 약속
[노드 1] Phase 1: 약속을 받은 노드 1/3 개 (필요 2 개)
[노드 1] ❌ Phase 1 실패: 약속을 받은 노드가 다수 필요 개수보다 적습니다. 리더 선출을 중단하고 다음 선거 시작.
[노드 2] ⏰ 하트비트 타임아웃 - 리더 없음 감지, 리더 선출 시작...

[노드 2] 🗳️ 리더 선출 시작 / 제안 번호 #17
[노드 2] Phase 1: 모든 노드에 PREPARE 요청 전송...
[노드 1] PREPARE 요청 수신 / 제안 번호 #17
[노드 1] → 제안 번호 #17 약속
[노드 2] PREPARE 요청 수신 / 제안 번호 #17
[노드 2] → 제안 번호 #17 약속
[노드 2] Phase 1: 약속을 받은 노드 2/3 개 (필요 2 개)
[노드 2] Phase 1: 이전에 수락된 값이 없으므로 자신을 제안 (노드 2)
[노드 2] Phase 2: 모든 노드에 ACCEPT (값: 노드 2) 요청 전송...
[노드 2] ACCEPT 요청 수신 / 제안 번호 #17, 값: 노드 2
[노드 2] → 수락! 새로운 리더: 노드 2 (제안 번호 17)
[노드 1] ACCEPT 요청 수신 / 제안 번호 #17, 값: 노드 2
[노드 1] → 수락! 새로운 리더: 노드 2 (제안 번호 17)
[노드 2] Phase 2: 수락된 노드 2/3 개 (필요 2 개)
[노드 2] ✅ 리더 선출 성공! 노드 2 가 리더가 되었습니다. (제안 번호 17)
[노드 2] 👑 나는 리더!
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
[노드 2] 💓 하트비트 전송 (턴 17)
^C

🛑 모든 노드 종료...

클러스터가 실행된 뒤, 1번 노드가 리더로 선출이 되었습니다. 그리고 게속해서 1번 노드가 자신이 살아있음을 다른 노드에서 전송하죠. 이 동안에는 다른 노드들이 리더가 살아있기 때문에 리더 선출을 시도하지 않습니다.

그리고 중간에 kill 1을 입력해서 1번 노드를 제거했습니다. 그러자 리더의 생존 신고(하트비트)가 더 이상 도착하지 않게되고, 이를 감지한 다른 노드들이 리더 선출을 시작합니다. 그리고 노드 3번이 리더가 됩니다.

다시 start 1을 입력해서 1번 노드를 시작하면, 1번 노드는 현재 3번 노드가 리더라는 걸 파악하고 따르기로 합니다. 그리고 다시 3번 노드를 제거하면, 리더 선출이 시작되고 이번엔 2번 노드가 리더가 됩니다.

이 과정을 다이어그램으로 도식화 해보면 다음과 같습니다.

flowchart TD
START["runElection() 호출"] --> CALC["제안 번호 계산<br/>proposalNumber = nodeId + (electionRound * 3)"]
CALC --> PHASE1["Phase 1: PREPARE<br/>모든 노드에 PREPARE 전송"]
PHASE1 --> PROMISE_CHECK{"과반수 약속<br/>받았는가?"}
PROMISE_CHECK -->|"No (promises < majority)"| FAIL1["scheduleNextElection()<br/>2~5초 후 재시도"]
PROMISE_CHECK -->|"Yes (promises >= majority)"| VALUE_CHECK["이전에 수락된 값 확인<br/>없으면 자신을 제안"]
VALUE_CHECK --> PHASE2["Phase 2: ACCEPT<br/>모든 노드에 ACCEPT 전송<br/>(제안 번호, 제안 값)"]
PHASE2 --> ACCEPT_CHECK{"과반수 수락<br/>받았는가?"}
ACCEPT_CHECK -->|"No (accepts < majority)"| FAIL2["scheduleNextElection()<br/>2~5초 후 재시도"]
ACCEPT_CHECK -->|"Yes (accepts >= majority)"| LEADER_CHECK{"proposedValue<br/>=== nodeId?"}
LEADER_CHECK -->|"Yes (나를 제안)"| LEADER["리더 확정! 👑<br/>electionTimer 중지<br/>startHeartbeat()"]
LEADER_CHECK -->|"No (다른 노드 제안)"| FOLLOWER["팔로워로 전환<br/>resetElectionTimeout()"]
LEADER --> END1["하트비트 전송 시작<br/>(1초 주기)"]
FOLLOWER --> END2["하트비트 수신 대기<br/>(3~5초 타임아웃)"]
FAIL1 --> WAIT1["랜덤 딜레이 대기"]
FAIL2 --> WAIT2["랜덤 딜레이 대기"]
WAIT1 --> CHECK1{"currentLeaderId<br/>=== null?"}
WAIT2 --> CHECK2{"currentLeaderId<br/>=== null?"}
CHECK1 -->|Yes| START
CHECK1 -->|No| END3["이미 리더 존재<br/>재시도 안 함"]
CHECK2 -->|Yes| START
CHECK2 -->|No| END3
style START fill:#e0f0ff,stroke:#333
style PHASE1 fill:#ffcccc,stroke:#333
style PHASE2 fill:#ccffcc,stroke:#333
style LEADER fill:#ffd700,stroke:#333,stroke-width:3px
style FOLLOWER fill:#ccccff,stroke:#333
style FAIL1 fill:#ffccaa,stroke:#333
style FAIL2 fill:#ffccaa,stroke:#333

혹시 더 상세한 설명을 원하는 분들 위해서(음.. 미래의 저를 위해서…!) 더 자세한 알고리즘의 흐름을 이 글 마지막의 Appendix에 추가해두었습니다.

Appendix - 더 상세한 설명

미래의 저를 위해서 더 상세한 설명을 남겨두겠습니다!

구체적 시나리오: 노드 3이 리더로 선출

초기 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId
1	null	null	null	null
2	null	null	null	null
3	null	null	null	null

노드 3이 가장 먼저 랜덤 딜레이가 만료되어 선출을 시작한다고 가정합니다.

Phase 1: PREPARE 시퀀스

sequenceDiagram
participant P as 노드 3 (Proposer)
participant A1 as 노드 1 (Acceptor)
participant A2 as 노드 2 (Acceptor)
participant A3 as 노드 3 (Acceptor)
Note over P: electionRound++ → 1<br/>proposalNumber = 3+(1*3) = 6
P->>A1: PREPARE(#6)
P->>A2: PREPARE(#6)
P->>A3: PREPARE(#6)
Note over A1: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋 (죽은 리더 방지)
Note over A2: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋
Note over A3: promisedProposal=null<br/>6 > null → 약속!<br/>promisedProposal=6<br/>accepted 리셋
A1-->>P: {promise:true, accepted:null}
A2-->>P: {promise:true, accepted:null}
A3-->>P: {promise:true, accepted:null}
Note over P: 약속 3/3 (필요 2) ✅<br/>이전 수락 값 없음<br/>→ 자신(노드 3) 제안

핵심 포인트:

promisedProposal === null || proposalNumber > promisedProposal 조건 충족 시 약속
PREPARE 처리 시 acceptedProposal과 acceptedValue를 null로 리셋 (node.ts:295-296)
- 이유: 리더 선출에서는 각 선거가 새로운 Paxos 인스턴스처럼 동작
- 죽은 리더가 재선출되는 것을 방지
응답에 이전 수락 값 포함 (표준 Paxos 메커니즘)

Phase 1 이후 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId
1	6	null (리셋)	null (리셋)	null
2	6	null (리셋)	null (리셋)	null
3	6	null (리셋)	null (리셋)	null

Phase 2: ACCEPT 시퀀스

sequenceDiagram
participant P as 노드 3 (Proposer)
participant A1 as 노드 1 (Acceptor)
participant A2 as 노드 2 (Acceptor)
participant A3 as 노드 3 (Acceptor)
P->>A1: ACCEPT(#6, value:3)
P->>A2: ACCEPT(#6, value:3)
P->>A3: ACCEPT(#6, value:3)
Note over A1: 6 >= promisedProposal(6) → 수락!<br/>acceptedProposal=6<br/>acceptedValue=3<br/>currentLeaderId=3<br/>currentTerm=6<br/>resetElectionTimeout()
Note over A2: 6 >= 6 → 수락!<br/>currentLeaderId=3<br/>currentTerm=6<br/>resetElectionTimeout()
Note over A3: 6 >= 6 → 수락!<br/>currentLeaderId=3<br/>currentTerm=6
A1-->>P: {accepted:true}
A2-->>P: {accepted:true}
A3-->>P: {accepted:true}
Note over P: 수락 3/3 (필요 2) ✅<br/>리더 선출 성공!<br/>proposedValue(3) === nodeId(3)<br/>→ "나는 리더!" 👑<br/>→ electionTimer 중지<br/>→ startHeartbeat(6)

핵심 포인트:

promisedProposal === null || proposalNumber >= promisedProposal 조건 충족 시 수락
모든 Acceptor가 상태 업데이트:
- acceptedProposal, acceptedValue 설정
- currentLeaderId, currentTerm 갱신
- 리더가 아닌 노드는 stopHeartbeat() 호출
- resetElectionTimeout() 호출 → 3~5초 타이머 리셋
노드 3은 proposedValue === nodeId 확인 후:
- electionTimer 중지 (node.ts:192-194) ← 중요! 리더는 타이머 불필요
- startHeartbeat(6) 호출

Phase 2 이후 최종 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	heartbeatTimer	electionTimer	역할
1	6	6	3	3	6	null	활성 (3~5초)	팔로워
2	6	6	3	3	6	null	활성 (3~5초)	팔로워
3	6	6	3	3	6	활성 (1초)	null (중지)	리더 👑

선출 후 하트비트 흐름

sequenceDiagram
participant L as 노드 3 (리더)
participant F1 as 노드 1 (팔로워)
participant F2 as 노드 2 (팔로워)
loop 매 1초 (setInterval 1000ms)
L->>F1: POST /leader/heartbeat {leaderId:3, term:6}
L->>F2: POST /leader/heartbeat {leaderId:3, term:6}
Note over F1: term(6) >= currentTerm(6)<br/>resetElectionTimeout()<br/>타임아웃 리셋: 3~5초
Note over F2: term(6) >= currentTerm(6)<br/>resetElectionTimeout()<br/>타임아웃 리셋: 3~5초
F1-->>L: {ok:true}
F2-->>L: {ok:true}
end
Note over L,F2: 하트비트(1초) << 타임아웃(3~5초)<br/>→ 정상 상태에서는 타임아웃이 절대 만료되지 않음

하트비트 전송 코드 (node.ts:225-245):

function startHeartbeat(term: number) {
 stopHeartbeat(); // 기존 타이머 제거

 heartbeatTimer = setInterval(() => {
 console.log(`[노드 ${nodeId}] 💓 하트비트 전송 (턴 ${term})`);

 // ★ 자신(리더)를 제외한 peers에만 전송
 peers.forEach(async (peerUrl) => {
 try {
 await fetch(`${peerUrl}/leader/heartbeat`, {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
 body: JSON.stringify({ leaderId: nodeId, term }),
 signal: AbortSignal.timeout(1000),
 });
 } catch (error) {
 // 노드 다운 시 무시
 }
 });
 }, 1000);
}

하트비트 수신 핸들러 (node.ts:352-375):

app.post('/leader/heartbeat', (req, res) => {
 const { leaderId, term } = req.body;

 if (term >= currentTerm) {
 if (leaderId !== currentLeaderId) {
 console.log(`[노드 ${nodeId}] 💓 새로운 리더로부터 하트비트 수신`);
 }
 currentLeaderId = leaderId;
 currentTerm = term;
 resetElectionTimeout(); // ★ 핵심! 타임아웃 리셋
 }

 res.json({ ok: true });
});

타이밍 관계:

하트비트 전송: 1초 (setInterval(1000))
선출 타임아웃: 3~5초 (3000 + Math.random() * 2000)
하트비트 주기 « 타임아웃 범위 → 정상 상태에서는 타임아웃 절대 만료 안 됨

리더 장애 감지와 재선출

시나리오: kill 3 → 노드 2가 새 리더로 선출

sequenceDiagram
participant CLI as 클러스터 CLI
participant N3 as 노드 3 (리더)
participant N1 as 노드 1 (팔로워)
participant N2 as 노드 2 (팔로워)
CLI->>N3: kill 3 (SIGTERM)
Note over N3: 프로세스 종료<br/>하트비트 중단
destroy N3
Note over N1: 하트비트 안 옴...
Note over N2: 하트비트 안 옴...
Note over N2: 3.5초 후 타임아웃 만료!<br/>currentLeaderId = null<br/>accepted 상태 리셋<br/>→ runElection()
Note over N2: promisedProposal = 6<br/>electionRound = max(0, ceil(6/3)) = 2<br/>electionRound++ = 3<br/>proposalNumber = 2+(3*3) = 11
N2->>N1: PREPARE(#11)
N2->>N2: PREPARE(#11) (자신)
N2--xN3: PREPARE(#11) (타임아웃)
Note over N1: 11 > 6 → 약속!<br/>promisedProposal=11<br/>accepted 리셋
N1-->>N2: {promise:true}
Note over N2: 자신도 약속
Note over N2: 약속 2/3 (필요 2) ✅
N2->>N1: ACCEPT(#11, value:2)
N2->>N2: ACCEPT(#11, value:2) (자신)
N2--xN3: ACCEPT(#11, value:2) (타임아웃)
Note over N1: 11 >= 11 → 수락!<br/>currentLeaderId=2<br/>currentTerm=11<br/>resetElectionTimeout()
N1-->>N2: {accepted:true}
Note over N2: 자신도 수락
Note over N2: 수락 2/3 (필요 2) ✅<br/>새 리더 확정! 👑<br/>electionTimer 중지<br/>startHeartbeat(11)
loop 매 1초
N2->>N1: heartbeat {leaderId:2, term:11}
Note over N1: resetElectionTimeout()
end

electionRound 조정 로직 (node.ts:70-71):

if (promisedProposal !== null) {
 electionRound = Math.max(electionRound, Math.ceil(promisedProposal / allNodes.length));
}
electionRound++;

예시:

promisedProposal = 6, allNodes.length = 3
electionRound = max(0, ceil(6/3)) = max(0, 2) = 2
electionRound++ = 3
proposalNumber = 2 + (3*3) = 11

과반수 요구:

3개 노드 중 1개 다운 → 2개 응답 (= 과반수) → 선출 가능!
Paxos의 장애 허용 능력: N개 노드에서 (N-1)/2개 장애 허용

재선출 후 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	heartbeatTimer	electionTimer	역할
1	11	11	2	2	11	null	활성 (3~5초)	팔로워
2	11	11	2	2	11	활성 (1초)	null (중지)	리더 👑
3	-	-	-	-	-	-	-	DOWN

노드 재시작과 팔로워 합류

시나리오: start 3 → 노드 3이 팔로워로 자연스럽게 합류

sequenceDiagram
participant CLI as 클러스터 CLI
participant N2 as 노드 2 (리더)
participant N3 as 노드 3 (재시작)
CLI->>N3: start 3 (새 프로세스 spawn)
Note over N3: 모든 상태 초기화<br/>currentLeaderId=null<br/>currentTerm=0<br/>Express 서버 시작 (:3003)<br/>랜덤 딜레이: 1.8초 대기
N2->>N3: heartbeat {leaderId:2, term:11}
Note over N3: term(11) >= currentTerm(0)<br/>새 리더 감지!<br/>currentLeaderId=2<br/>currentTerm=11<br/>resetElectionTimeout()
N3-->>N2: {ok:true}
Note over N3: 딜레이 만료 (1.8초)<br/>currentLeaderId=2 (null 아님)<br/>→ runElection() 호출 안 함! ✅
N2->>N3: heartbeat {leaderId:2, term:11}
Note over N3: resetElectionTimeout()<br/>안정적으로 팔로워 동작

재시작 초기화 흐름 (node.ts:393-409):

app.listen(port, () => {
 console.log(`[노드 ${nodeId}] 🚀 포트 ${port}에서 수신 중...`);

 // 1~3초 랜덤 딜레이
 const delay = 1000 + Math.random() * 2000;
 console.log(`[노드 ${nodeId}] 리더 조회 전 ${Math.round(delay)}ms 대기...`);

 // 딜레이 후 리더가 없으면 선출 시작
 setTimeout(() => {
 if (currentLeaderId === null) { // ★ 핵심 조건
 console.log(`[노드 ${nodeId}] 리더 없음, 리더 선출 시작...`);
 runElection();
 }
 }, delay);

 resetElectionTimeout();
});

핵심 메커니즘:

노드 3이 재시작하면 모든 상태 변수가 초기값 (currentLeaderId = null)
랜덤 딜레이 (1~3초) 동안 대기
이 시간 동안 리더(노드 2)의 하트비트(1초 주기)가 도착
하트비트 수신 시 currentLeaderId = 2로 설정
딜레이 만료 시 currentLeaderId !== null → 선출 시작 안 함!
자연스럽게 팔로워로 합류

재시작 후 안정 상태

노드	promisedProposal	acceptedProposal	acceptedValue	currentLeaderId	currentTerm	electionTimer	역할
1	11	11	2	2	11	활성	팔로워
2	11	11	2	2	11	null (중지)	리더 👑
3	null	null	null	2 (학습)	11 (학습)	활성	팔로워 (새로 합류)

주목: 노드 3은 Paxos 상태가 null이지만 하트비트만으로 리더 정보를 학습합니다. 메모리 기반 구현이므로 재시작 시 상태 복구 없음.

타이밍 관계 요약

타이머	시간	구현	용도
하트비트 전송 주기	1초	`setInterval(1000)`	리더가 팔로워에게 생존 신호 전송
하트비트 타임아웃 (선출 트리거)	3~5초	`3000 + Math.random() * 2000`	팔로워가 리더 장애 감지
초기 선출 딜레이	1~3초	`1000 + Math.random() * 2000`	클러스터 시작 시 동시 선출 방지
선거 실패 후 재시도 딜레이	2~5초	`2000 + Math.random() * 3000`	Phase 실패 후 재시도 간격
HTTP 요청 타임아웃	1초	`AbortSignal.timeout(1000)`	네트워크 요청 타임아웃

타이밍 설계 원칙:

하트비트 주기 « 타임아웃 → 정상 상태에서 타임아웃 절대 만료 안 됨
모든 딜레이/타임아웃에 랜덤 범위 → 선출 충돌 방지 (livelock 방지)
HTTP 타임아웃 « 하트비트 주기 → 빠른 장애 감지

전체 흐름 한눈에 보기

flowchart TD
START["클러스터 시작<br/>runCluster.ts 실행"] --> SPAWN["3개 노드 프로세스 spawn<br/>(child_process.spawn)"]
SPAWN --> NODE1["노드 1: Express 서버 시작<br/>랜덤 딜레이 (1.5초)"]
SPAWN --> NODE2["노드 2: Express 서버 시작<br/>랜덤 딜레이 (2.1초)"]
SPAWN --> NODE3["노드 3: Express 서버 시작<br/>랜덤 딜레이 (1.2초)"]
NODE1 --> TIMEOUT1["resetElectionTimeout()<br/>타임아웃: 4.1초"]
NODE2 --> TIMEOUT2["resetElectionTimeout()<br/>타임아웃: 3.5초"]
NODE3 --> TIMEOUT3["resetElectionTimeout()<br/>타임아웃: 4.2초"]
NODE3 --> FIRST["딜레이 만료 (1.2초)<br/>가장 먼저!"]
FIRST --> ELECTION1["runElection()<br/>제안 번호 #6"]
ELECTION1 --> P1["Phase 1: PREPARE(#6)<br/>→ 3개 약속"]
P1 --> P2["Phase 2: ACCEPT(#6, val:3)<br/>→ 3개 수락"]
P2 --> LEADER1["노드 3 리더 확정 👑<br/>electionTimer 중지<br/>startHeartbeat(6)"]
LEADER1 --> HB_LOOP["하트비트 루프<br/>(1초마다)"]
HB_LOOP --> HB1["노드 1 수신<br/>resetElectionTimeout()"]
HB_LOOP --> HB2["노드 2 수신<br/>resetElectionTimeout()"]
HB1 --> STABLE["안정 상태<br/>리더: 노드 3, 턴: 6"]
HB2 --> STABLE
STABLE --> KILL["사용자: kill 3<br/>리더 프로세스 종료"]
KILL --> STOP_HB["하트비트 중단"]
STOP_HB --> DETECT1["노드 1: 하트비트 안 옴<br/>타임아웃 대기 (4.1초)"]
STOP_HB --> DETECT2["노드 2: 하트비트 안 옴<br/>타임아웃 대기 (3.5초)"]
DETECT2 --> REELECTION["노드 2 타임아웃 만료 (3.5초)<br/>accepted 상태 리셋<br/>runElection()"]
REELECTION --> RE_P1["Phase 1: PREPARE(#11)<br/>→ 2개 약속 (노드 3 DOWN)"]
RE_P1 --> RE_P2["Phase 2: ACCEPT(#11, val:2)<br/>→ 2개 수락"]
RE_P2 --> LEADER2["노드 2 리더 확정 👑<br/>startHeartbeat(11)"]
LEADER2 --> HB_LOOP2["하트비트 루프<br/>(1초마다)"]
HB_LOOP2 --> STABLE2["안정 상태<br/>리더: 노드 2, 턴: 11"]
STABLE2 --> RESTART["사용자: start 3<br/>새 프로세스 spawn"]
RESTART --> NODE3_NEW["노드 3 재시작<br/>모든 상태 초기화<br/>랜덤 딜레이 (1.8초)"]
NODE3_NEW --> HB_RECEIVE["하트비트 수신<br/>currentLeaderId=2<br/>currentTerm=11"]
HB_RECEIVE --> DELAY_EXPIRE["딜레이 만료 (1.8초)<br/>currentLeaderId !== null<br/>→ 선출 안 함"]
DELAY_EXPIRE --> FOLLOWER["노드 3 팔로워로 합류<br/>안정적으로 동작"]
FOLLOWER --> FINAL["최종 클러스터 상태<br/>리더: 노드 2<br/>팔로워: 노드 1, 3"]
style START fill:#e0f0ff,stroke:#333
style LEADER1 fill:#ffd700,stroke:#333,stroke-width:3px
style LEADER2 fill:#ffd700,stroke:#333,stroke-width:3px
style KILL fill:#ffcccc,stroke:#333
style REELECTION fill:#ffddaa,stroke:#333
style FOLLOWER fill:#ccffcc,stroke:#333
style FINAL fill:#ccccff,stroke:#333,stroke-width:2px

참고자료

요즘 개발자를 위한 시스템 설계 수업. 디렌드라 신하, 테자스 초프라 저. 길벗
https://www.ibm.com/history/700
https://setiathome.berkeley.edu/sah_graphics.php
CLAUDE
Perpexity

go를 알아보자(1)

Sat, 10 Jan 2026 10:03:50 +0900

새해가 되고 뭔가 해야하지 않을까… 싶은 불안감이 커지던 중 평소에 node.js의 다음은 go 아니겠나 하고 생각하던 게 떠올랐습니다. 물론 node.js는 대체 불가입니다. 풀스택 개발자에게는 내 고향같은 편안함이 있죠. DB 부터 백엔드, 프론트까지 모든 스택을 하나로 다룰 수 있고 Typescript를 사용하면 정적 타입의 편안함까지 느낄 수 있죠.(물론 타입이 너무 복잡해서 아직도 잘 모릅니다… 하하하하…)

그런데 아무래도 만드는 제품을 on-premiss 솔루션화 하려다 보면, node.js 는 약간 어색함이 있습니다. 어쨌든 스크립트니까 코드가 그대로 노출된다는 단점이 있죠. 난독화를 하긴 하지만, 여전히 불안한 느낌은 있습니다. 물론 바이너리 역시도 100% 안전한 건 없지만, 뭐 그래도 말이죠.

하여간 이제 아주 천천히, 하던대로 go를 알아볼까 합니다. 평소에 많이 하던 코드를 go로 간단하게 작성해보면서 말이죠!

mongodb야 반갑다!

예, mongodb를 이용할 겁니다. 그리고 아주 간단하게 도큐먼트를 하나 집어넣고, 집어 넣은 도큐먼트를 다시 꺼내오는 작업을 할 겁니다.

go를 설치하자.

현재 go 최신버전은 1.25.5 입니다. 저는 맥에서 작성중이기 때문에 homebrew로 그냥 설치하면 됩니다.

> brew install go
> go version
go version go1.25.5 darwin/arm64

프로젝트 셋업

그리고 적당한 곳에 폴더를 생성합니다.

> mkdir mongodb-example
> cd mongodb-example
# go 모듈 초기화
> go mod init mongodb-example

그리고 가장 좋아하는 ide를 띄웁니다. 그러면 go.mod 파일이 하나 보일겁니다.

module test

go 1.25.5

모듈 이름과 go 버전이 보이는데요, 이 파일은 node.js의 package.json 같은 역할을 합니다. 일단 이번에 우리가 사용할 모듈을 설치해볼까요?

> go get go.mongodb.org/mongo-driver/v2/mongo
go: added github.com/golang/snappy v1.0.0
go: added github.com/klauspost/compress v1.16.7
go: added github.com/xdg-go/pbkdf2 v1.0.0
go: added github.com/xdg-go/scram v1.1.2
go: added github.com/xdg-go/stringprep v1.0.4
go: added github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78
go: added go.mongodb.org/mongo-driver/v2 v2.4.1
go: added golang.org/x/crypto v0.33.0
go: added golang.org/x/sync v0.11.0
go: added golang.org/x/text v0.22.0

자 그리고 다시 go.mod 파일을 보면!

module test

go 1.25.5

require (
 github.com/golang/snappy v1.0.0 // indirect
 github.com/klauspost/compress v1.16.7 // indirect
 github.com/xdg-go/pbkdf2 v1.0.0 // indirect
 github.com/xdg-go/scram v1.1.2 // indirect
 github.com/xdg-go/stringprep v1.0.4 // indirect
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 go.mongodb.org/mongo-driver/v2 v2.4.1 // indirect
 golang.org/x/crypto v0.33.0 // indirect
 golang.org/x/sync v0.11.0 // indirect
 golang.org/x/text v0.22.0 // indirect
)

설치된 패키지 목록이 보입니다. package.json 이랑 진짜 비슷하죠? 근데 저 많은 // indirect 는 뭘까요?

그러니까 직접적으로 사용하는 모듈(go.mongodb.org/mongo-driver/v2)가 간접적으로 사용하는 모듈이라는 뜻입니다. 근데 왜 go.mongodb.org/mongo-driver/v2 도 // indirect 냐고요? 아직 이 모듈을 사용하는 코드가 없기 때문입니다!

그럼 코드를 작성해보자.

main.go를 작성할 차례입니다.

// 이 파일은 실행가능한 패키지라는 의미
package main

// 사용할 모듈을 임포트
import (
 "context"
 "fmt"
 "log"
 "time"

 "go.mongodb.org/mongo-driver/v2/bson"
 "go.mongodb.org/mongo-driver/v2/mongo"
 "go.mongodb.org/mongo-driver/v2/mongo/options"
)

// 프로그램의 진입점
func main() {
 /**
 * 컨텍스트는 일종의 프로그램의 실행 환경을 제어하는 객체
 * 컨텍스트에 10초 동안 아무런 신호가 전달되지 않으면 컨텍스트를 취소하고 프로그램을 종료
 * 특정 연산이 너무 오래걸리는 경우 무작정 대기하지 않도록 함
 *
 * := 는 한 줄로 변수를 선언하고 초기화 한다
 */
 ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 // defer는 프로그램이 종료될 때 실행되도록 지연시킨다
 defer cancel()

 // mongodb에 연결
 client, err := mongo.Connect(options.Client().ApplyURI("mongodb://localhost:27017"))
 if err != nil {
 // log.Fatal은 오류가 발생하면 프로그램을 종료하고 오류 메시지를 출력
 log.Fatal(err)
 }
 // 프로그램이 종료될 때 연결을 끊기
 defer client.Disconnect(ctx)

 // mongodb 서버에 연결 확인, ping 성공시 컨텍스트가 취소되지 않고 계속 실행
 if err := client.Ping(ctx, nil); err != nil {
 log.Fatal(err)
 }
 fmt.Println("Connected to MongoDB")

 // users 컬렉션을 가져옴
 collection := client.Database("testdb").Collection("users")

 // bson.M은 자바스크립트 객체와 유사한 형태의 데이터를 저장하는 Binary JSON 형식
 user := bson.M{
 "name": "John Doe",
 "email": "john.doe@example.com",
 "age": 30,
 }

 // 사용자를 컬렉션에 삽입
 insertResult, err := collection.InsertOne(ctx, user)
 if err != nil {
 log.Fatal(err)
 }
 fmt.Println("User inserted with ID:", insertResult.InsertedID)

 // 이메일로 사용자를 찾음
 filter := bson.M{"email": "john.doe@example.com"}
 var result bson.M
 err = collection.FindOne(ctx, filter).Decode(&result)
 if err != nil {
 log.Fatal(err)
 }

 // 찾은 사용자 정보 출력
 fmt.Println("User found:", result)
}

코드를 보면 Go의 특징적인 에러 처리 패턴을 볼 수 있습니다.
if err != nil {
 log.Fatal(err)
}
다른 언어의 try-catch 와는 다르게, Go는 에러를 명시적으로 반환값으로 처리합니다. 이게 처음엔 좀 번거로워 보이지만, 에러가 발생할 수 있는 지점을 명확하게 알 수 있다는 장점이 있죠. 예외가 여러개 중첩 된 경우 예외가 어디서 발생한 건지 어렵게 찾을 필요가 없습니다!

그리고 코드를 실행할 때마다 같은 데이터가 계속 쌓이는 게 싫다면, 삽입 전에 기존 데이터를 삭제하는 코드를 추가할 수도 있습니다.
// 삽입 전에 기존 데이터 삭제 (선택사항)
_, err = collection.DeleteMany(ctx, bson.M{"email": "john.doe@example.com"})
if err != nil {
 log.Fatal(err)
}

그리고 go mod tidy 를 실행한 뒤 다시 go.mod 파일을 보면 다음과 같습니다.

module test

go 1.25.5

require go.mongodb.org/mongo-driver/v2 v2.4.1

require (
 github.com/golang/snappy v1.0.0 // indirect
 github.com/klauspost/compress v1.16.7 // indirect
 github.com/xdg-go/pbkdf2 v1.0.0 // indirect
 github.com/xdg-go/scram v1.1.2 // indirect
 github.com/xdg-go/stringprep v1.0.4 // indirect
 github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
 golang.org/x/crypto v0.33.0 // indirect
 golang.org/x/sync v0.11.0 // indirect
 golang.org/x/text v0.22.0 // indirect
)

직접 임포트해서 사용하는 go.mongodb.org/mongo-driver/v2 모듈이 // indirect 에서 독립했습니다!

mongodb를 띄우자.

간단한 docker-compose.yml 을 사용해서 mongodb를 띄울 겁니다. 프로젝트 루트 폴더(mongodb-example)에 docker-compose.yml 파일을 생성해주세요.

services:
 mongodb:
 image: mongo:latest
 ports:
 - "27017:27017"
 volumes:
 - mongodb_data:/data/db

volumes:
 mongodb_data:

이걸 이렇게 띄우죠.

> docker-compose up -d

이제 결과를 보자

이제 결과를 확인해볼까요?

> go run main.go
Connected to MongoDB
User inserted with ID: ObjectID("6961a3ea4f62d4037b2611bb")
User found: {"_id":{"$oid":"6961a3ea4f62d4037b2611bb"},"name":"John Doe","email":"john.doe@example.com","age":{"$numberInt":"30"}}

예… 이게 끝입니다. 처음이니까요. 하하하하하하.

실습 환경 정리하기

실습이 끝났으면 깔끔하게 정리해줍시다. MongoDB 컨테이너를 종료하고 데이터까지 삭제하려면 다음 명령어를 실행하면 됩니다.

> docker-compose down -v

-v 옵션은 볼륨까지 삭제한다는 의미입니다. 실습용 데이터니까 깔끔하게 지워버리는 게 속이 시원하죠!

참고자료

MongoDB Go Driver
Perplexity와 Claude

Typescript: import attributes

Sat, 20 Sep 2025 00:55:52 +0000

개요

최근에 틈이 날 때 마다 이전 타입스크립트 버전에 대한 릴리즈 노트를 읽어보고 있습니다. 리액트, Nest.js로 개발하면서 자연스럽게 타입스크립트를 몇 년간 사용해왔지만… 사실 제대로 아는 게 없었기 때문이죠. 타입스크립트차 처음 소개된 게 2012년이니까 벌써 13년이나 지났습니다. 긴 시간 동안 참 많은 일이 있었고 단순히 언어를 사용하는 것 만으로는 제대로 이해할 수 없겠죠.

그러던 중에 5.3 버전에서 Import Attributes 지원이 추가되었다는 걸 봤습니다. 내용은 짧았지만 이게 무슨 소리인지 이해하는 데는 시간이 좀 걸렸습니다. 이제 부터 그 이야기를 좀 해볼까 합니다.

나도 모르게 자연스럽게 쓰던 코드

예전에 Node.js로 코드를 짜다 보면 뭔가 데이터를 구성하고 가공하는 코드를 많이 짜곤했습니다. 그럴때 json 파일을 가져오고 활용하는 경우가 많았죠.

예를 들어서 다음과 같은 json 파일이 있을 때,

// src/import-attribute/src/test.json
{
 "name": "test",
 "description": "test",
 "isActive": true
}

이 파일을 가져오고 활용하는 코드는 다음과 같이 작성했습니다.

// src/import-attribute/src/import-json.js
const test = require("./test.json");

console.log(test);

이렇게 json 파일을 가져오면, Node.js 런타임이 파일을 읽어와서 변환까지 처리해줍니다. 그리고 가져온 데이터 객체의 타입을 추론해서 코드 자동 완성까지도 지원해줬죠. Node.js 런타임이 변환까지 처리해주기 때문에 json 파일의 형식이 잘못되어 있다면, require 구문에서 오류가 발생합니다.

Typescript 에서는…?

위 코드를 Typescript로 작성해보겠습니다.

// src/import-attribute/src/import-json.ts
import test from "./test.json";

console.log(test);

위 코드를 작성하자 마자, 다음과 같이 오류가 발생합니다.

타입 스크립트에서 json 파일을 임포트 하려면 resolveJsonModule 옵션 을 true로 설정해야 합니다. tsconfig.json에 다음과 같이 옵션을 추가합니다.

// tsconfig.json
{
 "compilerOptions": {
 "resolveJsonModule": true
 }
}

설정을 추가하면 새로운 에러가 발생합니다.

그러니까 export default 없이 정의된 json 파일을 임포트 해야 하니 allowSyntheticDefaultImports 옵션 을 true로 설정해야 합니다. tsconfig.json에 다음과 같이 옵션을 추가합니다.

// tsconfig.json
{
 "compilerOptions": {
 "resolveJsonModule": true,
 "allowSyntheticDefaultImports": true
 }
}

옵션을 추가하고 나면 오류가 사라집니다! 그러면 일단 컴파일을 진행하고 코드를 실행해볼까요?

> npx tsc
> node import-json.js
undefined

json 파일이 제대로 임포트되지 않고 undefined가 출력됩니다. 컴파일된 코드를 확인해보면 다음과 같습니다.

// src/import-json.js
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
var test_json_1 = require("./test.json");
console.log(test_json_1.default);

import가 아닌 require 구문을 사용하도록 컴파일이 되었네요. 현재 타입스크립트 버전(5.8.3)에서 지원하는 가장 최신의 javascript 문법을 사용하도록 tsconfig.json 에 옵션을 지정해보겠습니다.

// tsconfig.json
{
 "compilerOptions": {
 "resolveJsonModule": true,
 "target": "esnext",
 "moduleResolution": "node",
 "allowSyntheticDefaultImports": true
 }
}

target에는 가장 최신의 javascript 문법을 사용하도록 esnext를 사용하도록 지정했습니다. 그리고 변경된 target에서 resolveJsonModule 옵션을 같이 사용할 수 있도록 moduleResolution을 node로 지정했습니다.

생성되는 코드에서 import 구문을 사용하기 위해서 package.json에서 type을 module로 지정해줍니다.

옵션을 추가하고 다시 컴파일 및 실행 결과를 볼까요?

> npx tsc
> node import-json.js
node:internal/modules/esm/assert:88
 throw new ERR_IMPORT_ATTRIBUTE_MISSING(url, 'type', validType);
 ^

TypeError [ERR_IMPORT_ATTRIBUTE_MISSING]: Module "file:///Users/onlifecoding/src/test/typescript-studies/src/import-attribute/src/test.json" needs an import attribute of "type: json"
 at validateAttributes (node:internal/modules/esm/assert:88:15)
 at defaultLoad (node:internal/modules/esm/load:130:3)
 at async ModuleLoader.loadAndTranslate (node:internal/modules/esm/loader:514:32) {
 code: 'ERR_IMPORT_ATTRIBUTE_MISSING'
}

Node.js v22.14.0

뭔가 복잡해보이지만 결론은 type: json 이라는 import attribute를 지정해야 한다는 오류입니다.

참고로 만약 Node.js 버전이 20 또는 18 이라면 다음과 같은 오류가 발생합니다.

node:internal/errors:497
 ErrorCaptureStackTrace(err);
 ^

TypeError [ERR_IMPORT_ASSERTION_TYPE_MISSING]: Module "file:///Users/onlifecoding/src/test/typescript-studies/src/import-attribute/src/test.json" needs an import assertion of type "json"
 at new NodeError (node:internal/errors:406:5)
 at validateAssertions (node:internal/modules/esm/assert:94:15)
 at defaultLoad (node:internal/modules/esm/load:122:3)
 at ModuleLoader.load (node:internal/modules/esm/loader:396:13)
 at ModuleLoader.moduleProvider (node:internal/modules/esm/loader:278:56)
 at new ModuleJob (node:internal/modules/esm/module_job:65:26)
 at #createModuleJob (node:internal/modules/esm/loader:290:17)
 at ModuleLoader.getJobFromResolveResult (node:internal/modules/esm/loader:248:34)
 at ModuleLoader.getModuleJob (node:internal/modules/esm/loader:229:17)
 at async ModuleWrap.<anonymous> (node:internal/modules/esm/module_job:85:21) {
 code: 'ERR_IMPORT_ASSERTION_TYPE_MISSING'
}

import attribute

위 오류를 해결하기 위해서 임포트 구문에 import attribute를 추가해보겠습니다.

// src/import-attribute/src/import-json.ts
import test from "./test.json" with { type: "json" }

console.log(test);

그런데 여기서 또 하나의 오류가 발생합니다.

가져오기 특성은 '--module' 옵션이 'esnext', 'node18', 'node20', 'nodenext' 또는 'preserve'로 설정된 경우에만 지원됩니다.

그러니까, tsconfig.json에서 module 옵션을 esnext로 지정해줘야 합니다.

{
 "compilerOptions": {
 "resolveJsonModule": true, // JSON을 임포트 할 수 있도록 설정
 "module": "esnext", // import attribute를 사용하기 위해서 설정
 "target": "esnext",
 "moduleResolution": "node",
 "allowSyntheticDefaultImports": true
 }
}

이제 다시 코드를 컴파일 및 실행 해보겠습니다.

> npx tsc
> node import-json.js
{ name: 'test', description: 'test', isActive: true }

json 파일 하나를 임포트하고 실행하기 위해서 참 먼 길을 돌아왔습니다. 도대체 왜 이렇게 복잡해진 걸까요? 이 모든 건 다 보안 때문입니다.

위와 같이 json 파일을 임포트할 때, 확장자 만을 확인하고 파일의 내용이 json 인지는 확인하지 않는 문제가 있었고 이게 보안상 아주 취약한 문제가 될 수 있었습니다. 확장자는 json 파일이지만 실제로는 뭔가 이상한 동작을 수행하는 스크립트를 포함하고 있을 수도 있었죠.

그래서 import attribute를 사용해서 인터넷의 파일을 로드할 때, 확장자 대신에 파일의 MIME 타입이나 CSP 등의 정책에 맞는지 등을 확인할 수 있도록 처리합니다. Node.js에서도 마찬가지 입니다. 누군가 임포트되는 json 파일을 바꿔치기 한다면 동일한 문제가 발생할 수도 있겠죠.

import assertion? attribute? 헷갈리네!

이 기능은 최초 제안된 이후 이름이 여러번 바뀌었는데요, 그 과정을 살펴보면 다음과 같습니다.

2019년 12월: module attributes 로 제안되어 Stage 1 승인
2020년 6월: module attributes Stage 2 승인
2020년 9월: 이름이 import assertions로 변경되면 Stage 3 승인
2021~2022: import assertions 및 JSON Modules 제안 을 Chrome, Node.js, Deno에서 구현함.
2023년 1월: HTML에서 javascript가 아닌 모듈에 대한 처리에 호환되지 않는 부분이 있어서 import assertions는 Stage 2로 돌아감
2023년 3월: 이름이 import attributes로 변경되면 Stage 3 으로 다시 승인됨

그리고 현재 import attribute는 Stage 4(Finished) 단계로 공식 스펙에 편입될 준비를 모두 마친 상태입니다. 앞서 Node.js 20과 18 코드를 실행했을 때 오류 메세지가 needs an import assertion of type "json" 이라고 나왔던 건 바로 이런 이유 때문이었죠.

타입 스크립트는 문법을 허용할 뿐 아무 책임을 지지 않습니다!

릴리즈 노트에서도 설명하고 있지만, 타입스크립트는 그저 이 구문을 사용할 수 있게 지원하는 것 뿐이며 어떤 해석도 하지 않습니다. 왜냐면 이 구문을 어떻게 처리할지는 각 브라우저 및 런타임에 달려있기 때문이죠. 앞서 보신것 처럼 Node.js는 엄격하게 이 구문을 통해 json 파일의 타입을 체크하고 있습니다.

참고 자료

Typescript: Decorator Metadata

Sat, 06 Sep 2025 23:42:51 +0000

개요

Typescript는 5.0 부터 ECMAScript의 표준에 발맞춘 Decorator를 지원하고 있습니다. 얼마전에 이와 관련된 글을 쓴적이 있었죠! 그런데 ECMAScript의 표준에는 이 데코레이터를 좀 더 강력하게 사용할 수 있는 방법도 같이 제시되고 있습니다. 데코레이터의 메타데이터를 이용해서 데코레이터가 감싸고 있는 클래스의 정보를 추출하는 메타 프로그래밍을 지원합니다. Typescript 역시 5.2 버전 부터 이 기능을 지원하고 있습니다.

아주 간단한 예제

그럼 이 데코레이터 메타데이터가 뭔지 간단한 예제를 통해서 확인해보겠습니다. 우선 데코레이터 메타데이터를 사용하기 위해서는 다음과 같이 tsconfig.json 파일을 설정해야 합니다.

{
 "compilerOptions": {
 "target": "es2022",
 "lib": ["es2022", "esnext.decorators", "dom"],
 "experimentalDecorators": false,
 "useDefineForClassFields": true
 }
}

그리고 아직 node.js가 데코레이터 메타데이터를 지원하지 않기 때문에 다음과 같이 코드에 polyfill을 추가해야 합니다.

// 프로그램의 진입점에 한 번만 선언하면 됩니다!
(Symbol as any).metadata ??= Symbol("Symbol.metadata");

이제 간단하게 코드를 작성해볼까요?

// src/decorator-metadata/src/simple-decorator-metadata.ts

// Symbol.metadata polyfill
(Symbol as any).metadata ??= Symbol("Symbol.metadata");

// 데코레이터 Context 인터페이스
interface Context {
 name: string;
 metadata: Record<PropertyKey, unknown>;
}

/**
 * 데코레이터 메타데이터에 필드의 이름을 추가하는 데코레이터
 * @param _target 데코레이터가 적용된 클래스
 * @param context 데코레이터 컨텍스트
 */
function setMetadata(_target: any, context: Context) {
 // 데코레이터 메타데이터에 해당 필드의 이름을 추가합니다.
 context.metadata[context.name] = true;
}

class SomeClass {
 @setMetadata
 foo = 123;

 @setMetadata
 accessor bar = "hello!";

 @setMetadata
 baz() {}
}

// 데코레이터 메타데이터를 확인합니다.
const ourMetadata = SomeClass[Symbol.metadata];
console.log(JSON.stringify(ourMetadata));
// 출력: { "bar": true, "baz": true, "foo": true }

이 코드는 말이죠:

코드 최상단에 Symbol.metadata를 지원하기 위한 polyfill을 추가했습니다.
setMetadata 데코레이터 함수를 정의했습니다.
setMetadata를 호출하면 데코레이터 메타데이터에 ‘해당 필드의 이름’ = true 를 추가합니다.
데코레이터 메타데이터는 각 클래스 별로 고유한 객체이며, Symbol.metadata 을 통해 접근할 수 있습니다.

이 코드를 실행하면 다음과 같은 결과가 출력됩니다.

> npx ts-node ./src/simple-decorator-metadata.ts
{"bar":true,"baz":true,"foo":true}

SomeClass의 foo, bar, baz 필드에 setMetadata 데코레이터가 적용되었기 때문에 데코레이터 메타데이터에 foo, bar, baz 필드의 이름이 추가된 걸 확인할 수 있습니다.

이제 조금 더 실용적인 예제를 살펴볼까요?

의존성 주입(Dependency Injection) 예제

일단 데코레이터를 사용해서 의존성 주입(Dependency Injection)을 구현해보겠습니다.

이 예제는 테스트를 위한 구현이기 때문에 싱글턴 패턴, 순환 참조 탐지 등의 기능을 구현하지 않습니다. 실제 서비스에서는 InversifyJS 같은 의존성 주입 라이브러리를 사용하는 것이 좋습니다.

// src/decorator-metadata/src/dependency-injection.ts
/**
 * Injectable 데코레이터
 * 클래스를 DI 컨테이너에 등록합니다.
 * @param token 클래스 이름
 * @returns 데코레이터 함수
 */
function Injectable(token?: string) {
 return function (target: any) {
 const registry = new Map();
 // token: Logger, target.name: LoggerService, target: LoggerService 클래스
 registry.set(token || target.name, target);

 // 환경에 상관없이 사용할 수 있도록 globalThis에 글로벌 컨테이너를 설정합니다.
 (globalThis as any).diContainer =
 (globalThis as any).diContainer || new Map();

 // 글로벌 컨테이너에 등록합니다.
 for (const [key, value] of registry) {
 (globalThis as any).diContainer.set(key, value);
 }
 };
}

/**
 * Inject 데코레이터
 * 클래스 필드에 DI로 객체의 인스턴스를 주입합니다.
 * @param token 클래스 이름
 * @returns 데코레이터 함수
 */
function Inject(token: string) {
 return function (target: any, context: ClassFieldDecoratorContext) {
 return function (this: any, initialValue: any) {
 // Inject 데코레이터를 전달되는 token(ex: Logger)에 해당하는 서비스 클래스를 찾습니다.
 const container = (globalThis as any).diContainer;
 const serviceClass = container.get(token);

 if (!serviceClass) {
 throw new Error(`컨테이너에서 ${token} 클래스를 찾을 수 없습니다.`);
 }

 return new serviceClass();
 };
 };
}

/**
 * LoggerService 클래스
 */
@Injectable("Logger")
class LoggerService {
 constructor() {
 console.log("LoggerService constructor");
 }

 log(message: string) {
 console.log(`[LOG] ${new Date().toISOString()}: ${message}`);
 }
}

/**
 * DatabaseService 클래스
 */
@Injectable("Database")
class DatabaseService {
 @Inject("Logger")
 private logger!: LoggerService;

 query(sql: string) {
 this.logger.log(`Executing: ${sql}`);
 return { rows: [] };
 }
}

/**
 * UserService 클래스
 */
@Injectable("UserService")
class UserService {
 @Inject("Database")
 private db!: DatabaseService;

 @Inject("Logger")
 private logger!: LoggerService;

 getUser(id: number) {
 this.logger.log(`Getting user ${id}`);
 return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
 }
}

/**
 * 사용 예제
 */
const userService = new UserService();
userService.getUser(123);

조금 복잡하게 느껴집니다… 우선 실행 순서를 정리해보면 다음과 같습니다.

graph TB
subgraph ProcessFlow["🔄 처리 흐름"]
Step1["1️⃣ 클래스 정의 시<br/>데코레이터 실행"]
Step2["2️⃣ 컨테이너에<br/>토큰-클래스 매핑 저장"]
Step3["3️⃣ 인스턴스 생성 시<br/>의존성 자동 해결"]
Step4["4️⃣ 재귀적으로<br/>모든 의존성 주입"]
end
%% 처리 흐름
Step1 --> Step2
Step2 --> Step3
Step3 --> Step4

클래스에 정의된 Injectable 데코레이터에 token(ex: Logger)과 클래스(ex: LoggerService)가 전달됩니다.
Injectable 데코레이터는 글로벌 DI 컨테이너에 token-클래스 매핑을 저장합니다.
그 다음 Inject 데코레이터에 token(ex: Logger)이 전달되면, 글로벌 DI 컨테이너에서 token에 해당하는 클래스를 찾아서 인스턴스를 생성하여 주입합니다.
의존성 주입은 제귀적으로 발생합니다.(UserService -> DatabaseService -> LoggerService)

전체 구조를 도식화 해보면 다음과 같습니다.

graph TB
subgraph GlobalContainer["🌐 글로벌 DI 컨테이너"]
DIMap["globalThis.diContainer<br/>Map&lt;string, Constructor&gt;"]
TokenLogger["'Logger' ➜ LoggerService"]
TokenDatabase["'Database' ➜ DatabaseService"]
TokenUser["'UserService' ➜ UserService"]
end
subgraph DecoratorSystem["🏷️ 데코레이터"]
InjectableDecorator["@Injectable(token?)<br/>📝 클래스 등록 데코레이터<br/>• 토큰 생성<br/>• 컨테이너 저장"]
InjectDecorator["@Inject(token)<br/>💉 의존성 주입 데코레이터<br/>• 컨테이너 조회<br/>• 인스턴스 생성"]
end
subgraph ServiceLayer["🔧 서비스 계층"]
Logger["🟢 LoggerService<br/>@Injectable('Logger')<br/>────────────<br/>+ constructor()<br/>+ log(message: string)"]
Database["🟡 DatabaseService<br/>@Injectable('Database')<br/>@Inject('Logger') logger<br/>────────────<br/>+ query(sql: string)"]
User["🔴 UserService<br/>@Injectable('UserService')<br/>@Inject('Database') db<br/>@Inject('Logger') logger<br/>────────────<br/>+ getUser(id: number)"]
end
subgraph RuntimeExecution["⚡ 실행 시점"]
ClientCode["📱 클라이언트 코드<br/>const userService = new UserService()<br/>userService.getUser(123)"]
end
%% 등록 과정
InjectableDecorator -.->|"🏷️ 클래스에 데코레이터 추가<br/>토큰 생성 및 등록 준비"| Logger
InjectableDecorator -.->|"🏷️ 클래스에 데코레이터 추가<br/>토큰 생성 및 등록 준비"| Database
InjectableDecorator -.->|"🏷️ 클래스에 데코레이터 추가<br/>토큰 생성 및 등록 준비"| User
%% 컨테이너 저장
Logger -.->|"💾 'Logger' 토큰으로<br/>LoggerService 클래스 저장"| TokenLogger
Database -.->|"💾 'Database' 토큰으로<br/>DatabaseService 클래스 저장"| TokenDatabase
User -.->|"💾 'UserService' 토큰으로<br/>UserService 클래스 저장"| TokenUser
%% 의존성 관계
Database -->|"🔗 DatabaseService.logger 필드<br/>LoggerService 인스턴스 필요"| Logger
User -->|"🔗 UserService.db 필드<br/>DatabaseService 인스턴스 필요"| Database
User -->|"🔗 UserService.logger 필드<br/>LoggerService 인스턴스 필요"| Logger
%% 주입 과정
InjectDecorator -.->|"🔍 토큰으로 컨테이너 검색<br/>클래스 찾기 및 인스턴스 생성"| DIMap
%% 실행 과정
ClientCode -->|"🚀 new UserService() 호출<br/>의존성 주입 트리거"| User
%% 스타일링
classDef container fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#000
classDef decorator fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000
classDef service fill:#e8f5e8,stroke:#4caf50,stroke-width:2px,color:#000
classDef client fill:#fce4ec,stroke:#e91e63,stroke-width:2px,color:#000
classDef process fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px,color:#000
class DIMap,TokenLogger,TokenDatabase,TokenUser container
class InjectableDecorator,InjectDecorator decorator
class Logger,Database,User service
class ClientCode client
class Step1,Step2,Step3,Step4 process

실행 결과는 다음과 같습니다.

> npx ts-node ./src/dependency-injection.ts
LoggerService constructor
LoggerService constructor
[LOG] 2025-09-06T00:30:24.749Z: Getting user 123
[LOG] 2025-09-06T00:30:24.750Z: Executing: SELECT * FROM users WHERE id = 123

의존성 주입이 잘 되고 있군요! 그리고 LoggerService constructor가 두번 출력되는 것에서 매번 의존성 주입이 발생할 때 마다 새로운 객체가 생성된 다는 걸 확인할 수 있습니다. 그런데 아직 데코레이터 메타데이터는 보이지 않습니다… 이제 데코레이터 메타데이터를 이용해서 의존성 주입 정보를 더 자세히 확인할 수 있도록 해보겠습니다.

데코레이터 메타데이터를 이용해서 의존성 주입 정보를 확인해보자

앞선 예제에 데코레이터 메타데이터를 추가하여 다음과 같이 작성해보겠습니다.

// src/decorator-metadata/src/di-with-metadata.ts

// Symbol.metadata 를 지원하기 위한 polyfill
(Symbol as any).metadata ??= Symbol("Symbol.metadata");

// 데코레이터 메타데이터 사용할 심볼
const INJECTION_TOKENS_KEY = Symbol("injection-tokens");

/**
 * Injectable 데코레이터
 * 클래스를 DI 컨테이너에 등록합니다.
 * @param token 클래스 이름
 * @returns 데코레이터 함수
 */
function Injectable(token?: string) {
 return function (target: any) {
 const registry = new Map();
 // token: Logger, target.name: LoggerService, target: LoggerService 클래스
 registry.set(token || target.name, target);

 // 환경에 상관없이 사용할 수 있도록 globalThis에 글로벌 컨테이너를 설정합니다.
 (globalThis as any).diContainer =
 (globalThis as any).diContainer || new Map();

 // 글로벌 컨테이너에 등록합니다.
 for (const [key, value] of registry) {
 (globalThis as any).diContainer.set(key, value);
 }
 };
}

/**
 * Inject 데코레이터
 * 클래스 필드에 DI로 객체의 인스턴스를 주입합니다.
 * @param token 클래스 이름
 * @returns 데코레이터 함수
 */
function Inject(token: string) {
 return function (target: any, context: ClassFieldDecoratorContext) {
 const fieldName = context.name as string;
 console.log(`\n=== '${fieldName}' 필드에 @Inject('${token}') 설정 중 ===`);

 const metadata = context.metadata;

 // 메타데이터 객체에 injection tokens 정보가 없으면 생성
 metadata[INJECTION_TOKENS_KEY] ??= new Map<string, string>();

 // TypeScript의 메타데이터에 필드명과 토큰 매핑 저장
 const injectionTokens = metadata[INJECTION_TOKENS_KEY] as Map<
 string,
 string
 >;
 injectionTokens.set(fieldName, token);

 console.log("→ 메타데이터에 저장된 의존성 주입 정보:", injectionTokens);

 return function (this: any, initialValue: any) {
 const container = (globalThis as any).diContainer;
 const serviceClass = container.get(token);
 if (!serviceClass) {
 throw new Error(`컨테이너에서 ${token} 클래스를 찾을 수 없습니다.`);
 }
 return new serviceClass();
 };
 };
}

// 메타데이터를 확인하기 위한 유틸리티 함수들

/**
 * 클래스 인스턴스에서 TypeScript 메타데이터로부터 DI 정보를 확인합니다.
 * @param instance 클래스 인스턴스
 * @returns DI로 주입된 정보
 */
function getInjectionInfo(instance: object): Map<string, string> | undefined {
 const constructor = instance.constructor;
 const metadata = (constructor as any)[Symbol.metadata];

 if (!metadata) {
 return undefined;
 }

 return metadata[INJECTION_TOKENS_KEY] as Map<string, string>;
}

/**
 * 클래스의 생성자를 통해 TypeScript 메타데이터로부터 DI 정보를 확인합니다.
 * @param constructor 클래스 생성자
 * @returns DI로 주입된 정보
 */
function getClassInjectionInfo(
 constructor: Function
): Map<string, string> | undefined {
 const metadata = (constructor as any)[Symbol.metadata];

 if (!metadata) {
 return undefined;
 }

 return metadata[INJECTION_TOKENS_KEY] as Map<string, string>;
}

/**
 * 클래스 인스턴스에서 TypeScript 메타데이터의 DI 정보를 디버깅합니다.
 * @param instance 클래스 인스턴스
 */
function debugInstance(instance: object) {
 const className = instance.constructor.name;
 const injections = getInjectionInfo(instance);

 console.log(`\n=== ${className} 메타데이터의 의존성 주입 정보 ===`);
 if (injections && injections.size > 0) {
 for (const [field, token] of injections) {
 console.log(` ${field} <- ${token}`);
 }
 } else {
 console.log(" 메타데이터에 의존성 주입 정보가 없습니다.");
 }
}

/**
 * 클래스의 전체 TypeScript 메타데이터 구조를 확인합니다.
 * @param constructor 클래스 생성자
 */
function inspectMetadata(constructor: Function) {
 const metadata = (constructor as any)[Symbol.metadata];
 const className = constructor.name;

 console.log(`\n=== ${className} 메타데이터 구조 ===`);

 if (!metadata) {
 console.log(" 메타데이터가 없습니다.");
 return;
 }

 const injectionTokens = metadata[INJECTION_TOKENS_KEY];
 if (injectionTokens) {
 console.log(" 의존성 주입 토큰:", injectionTokens);
 } else {
 console.log(" 의존성 주입 토큰이 없습니다.");
 }
}

/**
 * LoggerService 클래스
 */
@Injectable("Logger")
class LoggerService {
 log(message: string) {
 console.log(`[LOG] ${new Date().toISOString()}: ${message}`);
 }
}

/**
 * DatabaseService 클래스
 */
@Injectable("Database")
class DatabaseService {
 @Inject("Logger")
 private logger!: LoggerService;

 query(sql: string) {
 this.logger.log(`Executing: ${sql}`);
 return { rows: [] };
 }
}

/**
 * UserService 클래스
 */
@Injectable("UserService")
class UserService {
 @Inject("Database")
 private db!: DatabaseService;

 @Inject("Logger")
 private logger!: LoggerService;

 getUser(id: number) {
 this.logger.log(`Getting user ${id}`);
 return this.db.query(`SELECT * FROM users WHERE id = ${id}`);
 }
}

// DEMO: 데코레이터 메타데이터를 통한 DI 정보 확인
console.log("=== 데코레이터 메타데이터를 통한 DI 정보 확인 ===");

// 전체 메타데이터 구조 확인
inspectMetadata(LoggerService);
inspectMetadata(DatabaseService);
inspectMetadata(UserService);

// 생성된 클래스에서 TypeScript 메타데이터의 DI 정보 확인
const userService = new UserService();
debugInstance(userService);
debugInstance(new DatabaseService());
debugInstance(new LoggerService());

// 클래스를 통해 TypeScript 메타데이터의 DI 정보 확인
const userInjections = getClassInjectionInfo(UserService);
console.log("\nUserService 메타데이터의 의존성 주입 정보:", userInjections);

// 메타데이터에 직접 접근해보기
console.log("\n=== 메타데이터에 직접 접근 ===");
const userMetadata = (UserService as any)[Symbol.metadata];
console.log("UserService 메타데이터 객체:", userMetadata);
console.log(
 "UserService 의존성 주입 토큰:",
 userMetadata[INJECTION_TOKENS_KEY]
);

console.log("\n=== 서비스 실행 ===");
userService.getUser(123);

코드의 최상단에 Symbol.metadata를 지원하기 위한 polyfill이 추가되었습니다. 그리고 각 클래스의 데코레이터 메타데이터에 의존성 주입 정보를 저장하는 WeakMap을 선언했습니다.

그리고 Inject 데코레이터에 메타데이터 객체를 이용하여 특정 클래스에서 발생한 의존성 주입 정보를 저장하도록 했습니다. 그리고 여러 헬퍼 함수를 통해 메타데이터의 정보를 확인할 수 있도록 했습니다. 해당 코드를 보시면 다음과 같이 특정 클래스의 데코레이터 메타데이터를 불러오고 있습니다.

const metadata = (UserService as any)[Symbol.metadata];

코드를 실행한 결과를 볼까요?

> npx ts-node ./src/di-with-metadata.ts

=== 'logger' 필드에 @Inject('Logger') 설정 중 ===
→ 메타데이터에 저장된 의존성 주입 정보: Map(1) { 'logger' => 'Logger' }

=== 'db' 필드에 @Inject('Database') 설정 중 ===
→ 메타데이터에 저장된 의존성 주입 정보: Map(1) { 'db' => 'Database' }

=== 'logger' 필드에 @Inject('Logger') 설정 중 ===
→ 메타데이터에 저장된 의존성 주입 정보: Map(2) { 'db' => 'Database', 'logger' => 'Logger' }
=== 데코레이터 메타데이터를 통한 DI 정보 확인 ===

=== LoggerService 메타데이터 구조 ===
 의존성 주입 토큰이 없습니다.

=== DatabaseService 메타데이터 구조 ===
 의존성 주입 토큰: Map(1) { 'logger' => 'Logger' }

=== UserService 메타데이터 구조 ===
 의존성 주입 토큰: Map(2) { 'db' => 'Database', 'logger' => 'Logger' }

=== UserService 메타데이터의 의존성 주입 정보 ===
 db <- Database
 logger <- Logger

=== DatabaseService 메타데이터의 의존성 주입 정보 ===
 logger <- Logger

=== LoggerService 메타데이터의 의존성 주입 정보 ===
 메타데이터에 의존성 주입 정보가 없습니다.

=== 서비스 실행 ===
[LOG] 2025-09-06T01:13:29.104Z: Getting user 123
[LOG] 2025-09-06T01:13:29.105Z: Executing: SELECT * FROM users WHERE id = 123

처음 세 줄은 Inject 데코레이터가 실행될 때 출력되는 로그입니다. 가장먼저 DatabaseService의 logger 필드에 의존성이 주입되고, 이어서 UserService의 db, logger 필드에 순서대로 의존성이 주입되고 있습니다.

그 다음 세줄은 각 클래스의 데코레이터 메타데이터를 살펴보고 있습니다.

그리고 그 다음 세 줄은 각 클래스의 데코레이터 메타데이터를 통해 의존성 주입 정보를 확인하고 있구요, 마지막 2줄은 서비스 실행 결과입니다.

reflect-metadata 와의 비교

reflect-metadata는 데코레이터의 메타데이터를 활용하기 위해 그동안 활용되어 왔습니다. 하지만, 새로운 표준의 등장으로 신규 프로젝트에서는 표준 데코레이터 메타데이터를 사용하는 게 좋습니다.

번들링 사이즈를 줄일 수 있습니다. 라이브러리를 polyfill로 대체할 수 있죠.
데코레이터 메타데이터는 Stage 3 단계에 있습니다. Stage 3는 Candidate 상태로서 대부분 완성 되어 안정적이라고 판단할 수 있는 상태입니다. 따라서 향후 표준이 진행되는 방향을 따라가는 게 자연스럽습니다. 그리고 reflect-metadata 리포지토리에서도 이 점을 분명히 하고 있습니다.
reflect-metadata는 메타데이터를 가져오기 위해 Prototype 체인을 순회합니다. 따라서 메타데이터 처리를 위해 더 많은 작업이 필요하고, 성능 측면에서 불리합니다.

참고자료

Typescript: using 문으로 리소스 관리

Sun, 31 Aug 2025 01:18:53 +0000

이 글에서 사용된 환경 설정

Node.js: 22.14.0
TypeScript: 5.5.3

개요

어떤 종류의 앱이든 만들다 보면 리소스 할당과 해제는 매우 중요한 문제입니다. 메모리를 자동으로 관리해주는 GC의 동작 방식을 보면, 특정한 절차를 통해 더 이상 참조되지 않는 객체를 찾아서 삭제해주는 작업을 반복합니다. 리소스를 할당만 하고 제대로 해제하지 않는다면 이미 사용이 끝난 리소스가 계속해서 메모리와 CPU 리소스를 점유하게 되고 이런 문제가 계속 발생한다면 심각한 앱은 심각한 메모리 누수 문제를 겪게 되겠죠.

C#과 같은 언어에서는 초장기 부터 이런 문제를 해결하기 위해서(당시에는 C, C++의 포인터를 사용할 때 메모리 관리가 어려웠습니다.) 할당한 리소스를 자동으로 해제할 수 있는 방법을 제공했습니다.

C#의 using 문

C#에서는 IDisposable 또는 IAsyncDisposable 인터페이스를 구현하여 리소스를 할당한 후 사용이 끝나면 자동으로 해제되는 방법을 제공합니다.

다음과 같은 텍스트 파일이 있고, 이 파일을 조금씩 읽어서 콘솔에 출력하는 코드를 예시로 들어볼까요?

// csharp-using/text.txt
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla consectetur enim lorem, vestibulum egestas nibh consectetur quis. Nam a fringilla est, eu fringilla dui. Vestibulum neque quam, dignissim ut blandit in, suscipit laoreet dolor. Cras hendrerit urna at elit pellentesque, in bibendum libero laoreet. Nam interdum sapien id metus scelerisque facilisis. Praesent venenatis viverra lacus, nec varius mi mattis at. Sed malesuada velit risus, et pharetra arcu rhoncus sed. Duis sit amet tincidunt nisl, vel gravida ante.

Morbi egestas eu nisl et bibendum. Duis placerat sodales nulla, sed dictum libero mattis vel. Suspendisse velit sapien, scelerisque vel massa quis, ultrices vestibulum mauris. Vestibulum sit amet viverra leo, quis euismod sem. Aliquam dignissim arcu nec lectus lacinia, at pretium urna aliquam. Interdum et malesuada fames ac ante ipsum primis in faucibus. Duis lectus nunc, hendrerit eget lobortis nec, rutrum ut risus. Morbi porta orci velit, et viverra magna ullamcorper ac. Praesent commodo, turpis ut facilisis scelerisque, felis enim efficitur risus, et elementum sapien arcu vel tellus. Praesent feugiat aliquet consequat. Mauris in leo suscipit, molestie erat ut, cursus nibh. In luctus dui et nulla luctus, a elementum libero aliquet. Mauris finibus bibendum vestibulum. Quisque rhoncus purus at turpis hendrerit accumsan. Praesent posuere sapien dolor, vel feugiat sem fermentum vel. Donec massa dui, pulvinar eget quam a, aliquet malesuada arcu.

Curabitur non lorem ut justo luctus luctus. Vivamus ac congue nunc, ac tincidunt velit. Praesent nulla nisl, sollicitudin sed venenatis id, pharetra id neque. Donec tellus magna, dignissim nec faucibus vel, facilisis quis ligula. Nullam eget aliquam nisi. Mauris imperdiet nunc sed augue iaculis euismod. Duis sollicitudin posuere mauris eget accumsan. Etiam vestibulum est at sagittis maximus. Pellentesque mollis diam quis purus venenatis, vel cursus risus dictum. Vivamus elementum, magna ac eleifend rutrum, velit tellus mollis odio, sed volutpat quam felis quis tellus. Morbi a feugiat metus. Nullam sodales sem eu ligula pulvinar, a pellentesque tellus vehicula. Curabitur nec mi ornare, laoreet mi eu, molestie arcu. Curabitur ex lacus, ultricies a dui nec, placerat finibus enim. Vestibulum euismod a dolor eu vulputate.

Donec ac malesuada nisl, ut tincidunt neque. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Aenean rhoncus eros non maximus fringilla. Curabitur lobortis ac lacus in aliquam. Morbi id arcu dui. Cras quis erat cursus, aliquam dolor et, vestibulum risus. Sed eleifend hendrerit nulla, sed maximus risus pellentesque at. Phasellus a placerat metus, vel maximus justo. Sed semper gravida risus, vel pulvinar diam pharetra at. Sed pellentesque libero mi, vitae semper ligula porta in. Suspendisse ornare, arcu nec euismod suscipit, lectus sem placerat nulla, id eleifend nisl mauris et purus. Duis in eros a nibh venenatis posuere.

Morbi rhoncus orci tortor. Vivamus cursus dolor in magna efficitur, a iaculis ligula imperdiet. Curabitur nec consectetur lectus, non bibendum quam. Nullam mollis posuere auctor. Quisque scelerisque luctus ante, vel auctor justo finibus quis. Aenean efficitur massa non nisi blandit, nec ullamcorper lectus egestas. In sed sodales dolor, sed accumsan mi. Nunc tincidunt porttitor arcu in semper. Phasellus rhoncus felis elementum justo tempor, sed congue turpis condimentum. Nam aliquet felis in pharetra convallis. Ut vestibulum hendrerit odio, et aliquet massa fringilla vitae. Fusce est risus, varius nec turpis sit amet, varius consectetur elit. Nam tristique nulla nisl, sed venenatis nunc pretium a.

다음은 이 파일을 읽어서 콘솔에 출력하는 코드입니다.

// csharp-using/main.cs
using System.IO;

var buffer = new char[50];
using (var reader = new StreamReader("text.txt"))
{
 int charsRead = 0;
 while (reader.Peek() != -1)
 {
 charsRead = reader.Read(buffer, 0, buffer.Length);
 Console.Write(buffer, 0, charsRead);
 }
}

이 코드를 실행하려면, cs 파일을 스크립트로 실행할 수 있게 해주는 dotnet-script를 설치해야 합니다.

> dotnet tool install -g dotnet-script
...
You can invoke the tool using the following command: dotnet-script
Tool 'dotnet-script' (version '1.6.0') was successfully installed.

> dotnet script main.cs
...Nam tristique nulla nisl, sed venenatis nunc pretium a.

코드가 중간 언어(IL)로 변환될 때 using 블록으로 감싸진 리소스를 try-finally 블록으로 변환하고 finally 블록 안에서 IDisposable 인터페이스의 Dispose() 메서드를 호출합니다.

finally
{
 streamReader?.Dispose();
}

리소스를 해제하는 걸 일일이 기억할 필요 없이 using 문을 사용하면 리소스의 해제가 자동으로 일어나게 되는 거죠. 정신 없이 코딩하다보면 리소스 해제를 놓치는 경우는 생각보다 자주 일어납니다…그게 개발이죠!

Javascript는?

Javascript는… 이런 기능을 제공하진 않았습니다.

텍스트 파일에 내용을 추가하는 간단한 예제를 볼까요?

// typescript-using/append-file.ts
import fs from "fs";

function appendToFile(filePath: string, content: string): void {
 let fd: number | null = null;

 try {
 // Open file for appending
 fd = fs.openSync(filePath, "a");

 const buffer = Buffer.from(content, "utf8");
 fs.writeSync(fd, buffer);

 console.log(`텍스트 추가 성공 ${filePath}`);
 } catch (error) {
 console.error("텍스트 추가 실패:", error);
 } finally {
 if (fd !== null) {
 fs.closeSync(fd);
 }
 }
}

appendToFile("test.txt", "Hello, world!");
appendToFile("test.txt", "Hello, World!");

보시는 것 처럼 finally 블록에서 직접 리소스를 해제 하도록 하는 코드를 작성해줘야 합니다. 만약 해제를 까먹는다면 어떻게 될까요?

위 코드에서 fs.closeSync(fd)를 주석 처리하고 실행해봐도 실행에는 문제가 없지만, 메모리 누수가 생기겠죠? 그리고 OS의 File Descriptor 또한 계속 차지하다가 Too many open files 에러도 발생할 수 있습니다.

이런 문제가 있다보니 Javascript에서도 리소스 관리를 좀 더 스마트하게 할 수 있는 방법을 제공하기 위한 논의가 진행되었습니다. tc39 에 의해 이미 스펙은 정의되었고, 각 브라우저/런타임 등에서 구현이 시작된 상태입니다.

Typescript의 using 문

Typescript 5.2 버전에서는 Javascript의 스펙에 발 맞춰 using 키워드를 통해 어떤 리소스가 자동으로 해제되는지 선언할 수 있게 되었습니다.

// typescript-using/using-append-file.ts
import fs from "fs";

class FileDescriptor implements Disposable {
 private fd: number;

 constructor(filePath: string, mode: string) {
 this.fd = fs.openSync(filePath, mode);
 }

 get descriptor(): number {
 return this.fd;
 }

 /**
 * 파일 디스크립터가 선언된 스코프를 벗어날 때, 자동으로 파일 디스크립터를 해제합니다.
 */
 [Symbol.dispose](): void {
 if (this.fd !== null) {
 fs.closeSync(this.fd);
 console.log("File descriptor closed automatically");
 }
 }
}

function appendToFileWithUsing(filePath: string, content: string): void {
 try {
 // using 카워드로 선언된 객체는 선언된 스코프를 벗어날 때 자동으로 Symbol.dispose를 호출합니다.
 using file = new FileDescriptor(filePath, "a");

 const buffer = Buffer.from(content, "utf8");
 fs.writeSync(file.descriptor, buffer);

 console.log(`Successfully appended to ${filePath}`);
 } catch (error) {
 console.error("Error appending to file:", error);
 // 에러가 발생하더라도 파일 디스크립터는 자동으로 해제됩니다!
 }
}

appendToFileWithUsing("test.txt", "Hello, world!");
appendToFileWithUsing("test.txt", "Hello, World!");

FileDescriptor 클래스는 Disposable 인터페이스를 통해 Symbol.dispose 메서드를 구현하고 있습니다. Disposable 인터페이스는 파일 디스크립터가 선언된 스코프를 벗어날 때 자동으로 파일 디스크립터를 해제합니다.

위 코드를 실행하면 다음과 같은 결과를 얻을 수 있습니다.

> npx ts-node ./using-append-file.ts
Successfully appended to test.txt
File descriptor closed automatically
Successfully appended to test.txt
File descriptor closed automatically

npx tsc 명령으로 빌드된 소스코드를 보면 뭔가 복잡하긴 하지만, 핵심은 이렇습니다.

function appendToFileWithUsing(filePath, content) {
 try {
 const env_1 = { stack: [], error: void 0, hasError: false };
 try {
 // using 카워드로 선언된 객체는 선언된 스코프를 벗어날 때 자동으로 Symbol.dispose를 호출합니다.
 const file = __addDisposableResource(
 env_1,
 new FileDescriptor(filePath, "a"),
 false
 );
 const buffer = Buffer.from(content, "utf8");
 fs_1.default.writeSync(file.descriptor, buffer);
 console.log(`Successfully appended to ${filePath}`);
 } catch (e_1) {
 env_1.error = e_1;
 env_1.hasError = true;
 } finally {
 __disposeResources(env_1);
 }
 } catch (error) {
 console.error("Error appending to file:", error);
 // 에러가 발생하더라도 파일 디스크립터는 자동으로 해제됩니다!
 }
}

finally 블록을 통해 리소스를 해제하는 코드로 변환되었습니다. 앞서 보신 코드들과 비슷하죠?

리소스 해제 순서

using 문을 통해 리소스를 사용하면, 해당 using 문이 포함된 스코프를 벗어날 때 리소스가 해제됩니다. 그 순서를 확인해볼까요? 다음은 Typescript의 공식 문서에 포함된 예제입니다.

function syncLoggy(id: string): Disposable {
 console.log(`Creating ${id}`);
 return {
 [Symbol.dispose]() {
 console.log(`Disposing ${id}`);
 }
 }
}

function syncFunc() {
 using a = syncLoggy("a");
 using b = syncLoggy("b");
 {
 using c = syncLoggy("c");
 using d = syncLoggy("d");
 }
 using e = syncLoggy("e");
 return;
 // return 문 이후의 코드는 실행되지 않습니다.
 using f = syncLoggy("f");
}

syncFunc();

실행 결과는 다음과 같습니다.

> npx ts-node ./dispose-order.ts
Creating a
Creating b
Creating c
Creating d
Disposing d
Disposing c
Creating e
Disposing e
Disposing b
Disposing a

생성된 리소스는 역순으로 해제되며, 가장 안쪽 스코프에 포함된 c, d가 먼저 해제되는 걸 볼 수 있습니다.

비동기 호출이 필요한 경우

리소스를 해제할 때 비동기 호출이 필요한 경우는 AsyncDisposable 인터페이스를 통해 Symbol.asyncDispose 메서드를 구현하면 됩니다. 역시 Typescript의 공식 문서에 포함된 예제를 통해 확인해볼까요?

async function doWork() {
 // 0.5초 동안 대기합니다.
 await new Promise(resolve => setTimeout(resolve, 500));
}

function asyncLoggy(id: string): AsyncDisposable {
 console.log(`Constructing ${id}`);
 return {
 async [Symbol.asyncDispose]() {
 console.log(`Disposing (async) ${id}`);
 await doWork();
 },
 }
}

async function asyncFunc() {
 await using a = asyncLoggy("a");
 await using b = asyncLoggy("b");
 {
 await using c = asyncLoggy("c");
 await using d = asyncLoggy("d");
 }
 await using e = asyncLoggy("e");
 return;
}
asyncFunc();

실행 결과는 다음과 같습니다.

> npx ts-node ./async-dispose.ts
Constructing a
Constructing b
Constructing c
Constructing d
Disposing (async) d
Disposing (async) c
Constructing e
Disposing (async) e
Disposing (async) b
Disposing (async) a

매번 인터페이스로 구현해야 한다고?

그런데 말입니다… 뭔 코드를 작성할 때 마다 이렇게 클래스를 정의해서 Disposable 인터페이스를 구현해야만 하는 걸까요? 그래서 DisposableStack, AsyncDisposableStack 역시 제공됩니다. 이 객체를 이용하면, 별도의 클래스를 정의하지 않고 해제되어야 할 리소스를 명시할 수 있습니다.

2025년 8월 31일 현재 DisposableStack은 Node.js 에서 구현되지 않았기 때문에 @whatwg-node/disposablestack 패키지를 사용합니다. npm i @whatwg-node/disposablestack 명령으로 설치해주세요.

// typescript-using/disposableTimer.ts
import { DisposableStack } from "@whatwg-node/disposablestack"

async function disposableTimerFunc() {
 using disposer = new DisposableStack();
 // disposer.use(disposableTimer(() => console.log("timer tick"), 1000));
 const timer = setInterval(() => console.log("timer tick"), 1000);
 disposer.defer(() => {
 clearInterval(timer);
 console.log("timer disposed");
 });

 console.log("5초 동안 타이머를 기다립니다...");
 await new Promise(resolve => setTimeout(resolve, 5000));
}

disposableTimerFunc();

그리고 결과를 볼까요?

> npx ts-node ./disposableTimer.ts
5초 동안 타이머를 기다립니다...
timer tick
timer tick
timer tick
timer tick
timer disposed

별도로 인터페이스를 구현하지 않더라도, defer 메서드로 전달한 리소스 해제 코드를 통해 리소스를 해제할 수 있습니다. 단, 주의해야 할 점이 있습니다. 반드시 리소스를 선언한 직후에 defer 메서드로 리소스 해제 코드를 전달해야 합니다. DisposableStack은 stack과 유사한 형태로 마지막에 들어온 게 가장 먼저 나간다 는 원리로 작동합니다. 그래서 불분명한 리소스 해제로 인해서 문제가 발생하지 않으려면 꼭 선언된 직후에 defer 메서드로 리소스 해제 코드를 전달해야 합니다.

핵심 개념 요약

개념	설명	예시
using 선언	스코프를 벗어날 때 자동으로 리소스 해제	`using file = new FileDescriptor(...)`
Disposable	동기 리소스 해제 인터페이스	`[Symbol.dispose](): void`
AsyncDisposable	비동기 리소스 해제 인터페이스	`[Symbol.asyncDispose](): Promise<void>`
DisposableStack	여러 리소스를 스택으로 관리	`disposer.defer(() => cleanup())`
해제 순서	LIFO (Last In, First Out) 방식	마지막에 생성된 것부터 해제

참고자료

Typescript: Decorator

Sat, 02 Aug 2025 23:28:08 +0000

📚 목차 (Table of Contents)

개요

예전에 퇴사했던 직원이 작성했던 프로젝트를 유지보수하기 위해 코드를 들여다 본적이 있었습니다. 그 프로젝트를 A라고 해보죠. 4-5개의 프로젝트를 동시에 띄워놓고 동작을 확인해야 했어서 정신없이 프로젝트를 실행하고 동작을 확인하던 중 A에서 뭔가 제대로 동작하지 않는다는 걸 확인했습니다. 그래서 로그를 확인해보다 놀랐습니다! A에는 로그를 남기는 코드가 단 한 줄도 없었거든요…

그래서 일단 요청을 처리하는 각 메서드 마다 시작과 끝을 로그로 남겨야겠다는 생각에 로그를 추가하다가 문득 얼마전 지나가듯이 봤던 Typescript의 데코레이터(Decorator)가 기억났습니다. 그래서 무작정 찾아보며 코드를 작성하기 시작했습니다.

기존에 작성했던 데코레이터

우선 tsconfig.json 파일을 다음과 같이 설정합니다.

{
 "compilerOptions": {
 "experimentalDecorators": true
 }
}

그리고 데코레이터를 작성합니다.

// src/legacy_decorator.ts

/**
 * 메서드의 시작과 끝을 기록하는 데코레이터
 */
export function loggedMethod(headMessage = "🚩"): MethodDecorator {
 return function actualDecorator<T>(
 target: object,
 propertyKey: string | symbol,
 descriptor: TypedPropertyDescriptor<T>
 ): void | TypedPropertyDescriptor<T> {
 const originalMethod = descriptor.value as unknown as (
 ...args: any[]
 ) => any;
 const methodName = String(propertyKey);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);
 const result = originalMethod.apply(this, args);
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 }

 descriptor.value = replacementMethod as unknown as T;
 return descriptor;
 };
}

class MyClass {
 // @ts-ignore - Typescript 5.8의 데코레이터 타입 체크를 일단 해제
 @loggedMethod() // 메서드에 데코레이터 적용
 myMethod() {
 console.log("myMethod called");
 }
}

const myClass = new MyClass();
myClass.myMethod();

참고로 해당 코드는 Typescript 5.1 에서 작성되었으나, 글을 작성하는 현재 최신 버전인 5.8에서의 실행을 위해 일단 @ts-ignore를 적용했습니다.

그리고 실행해보면 결과는 아래와 같습니다.

❯ npx ts-node legacy_decorator.ts
🚩 Entering method 'myMethod'.
myMethod called
🚩 Exiting method 'myMethod'.

메서드가 호출될 때마다 로그가 출력되는걸 볼 수 있습니다.

그런데 이 데코레이터는 몇가지 문제점이 있습니다. 현재 이 데코레이터는 비동기 함수에 대해서는 제대로 동작하지 않습니다. 비동기 함수 역시 지원하려면 좀 복잡한 로직을 작성해야만 합니다. 그리고 이게 더 큰 문제인데요, 이 데코레이터는 ECMAscript의 TC39에서 제시된 데코레이터 시그니처와 맞지 않습니다. 언젠가는 사라질 운명이라는 거죠.

Typescript 5.0+의 데코레이터

그래서 Typescript 5.0+에서는 표준과 발맞추도록 데코레이터를 개선했습니다. 앞서 보셨던 코드와 동일한 작업을 하는 코드입니다. 이 코드를 실행하기 위해서 tsconfig.json 파일을 다음과 같이 설정합니다.

{
 "compilerOptions": {
 "target": "es2022"
 }
}

그리고 데코레이터를 작성합니다.

// src/new_decorator.ts

function loggedMethod(headMessage = "🚩") {
 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);
 const result = originalMethod.apply(this, args);
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 }

 return replacementMethod;
 };
}

class MyClass {
 @loggedMethod()
 myMethod() {
 console.log("myMethod called");
 }
}

const myClass = new MyClass();
myClass.myMethod();

그럼 코드를 실행해 볼까요?

❯ npx ts-node new_decorator.ts
🚩 Entering method 'myMethod'.
myMethod called
🚩 Exiting method 'myMethod'.

잘 동작합니다! 그러면 비동기 함수를 하나 추가해보면 어떨까요?

// src/new_decorator.ts

function loggedMethod(headMessage = "🚩") {
 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);
 const result = originalMethod.apply(this, args);
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 }

 return replacementMethod;
 };
}

class MyClass {
 @loggedMethod()
 myMethod() {
 console.log("myMethod called");
 }

 // 비동기 메서드
 @loggedMethod()
 async myAsyncMethod() {
 console.log("async method start");
 await new Promise((r) => setTimeout(r, 500));
 console.log("async method end");
 }
}

const myClass = new MyClass();
myClass.myMethod();
myClass.myAsyncMethod();

실행 결과는 다음과 같습니다.

❯ npx ts-node new_decorator.ts
🚩 Entering method 'myMethod'.
myMethod called
🚩 Exiting method 'myMethod'.
🚩 Entering method 'myAsyncMethod'.
async method start
🚩 Exiting method 'myAsyncMethod'. <---- 비동기 함수가 끝나기 전에 로그가 출력되었습니다.
async method end

비동기 함수가 끝나는 걸 기다리지 않고, 바로 메서드 종료 로그가 출력되었죠? 이제 비동기 함수를 지원하도록 변경해볼까요?

// src/new_decorator.ts

function loggedMethod(headMessage = "🚩") {
 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);
 const result = originalMethod.apply(this, args);

 // 비동기 메서드인 경우, Promise가 완료된 후 로그를 출력
 if (result && typeof result.then === "function") {
 return result.finally(() => {
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 });
 }

 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 }

 return replacementMethod;
 };
}

class MyClass {
 @loggedMethod()
 myMethod() {
 console.log("myMethod called");
 }

 // 비동기 메서드
 @loggedMethod()
 async myAsyncMethod() {
 console.log("async method start");
 await new Promise((r) => setTimeout(r, 500));
 console.log("async method end");
 }
}

const myClass = new MyClass();
myClass.myMethod();
myClass.myAsyncMethod();

원본 메서드릐 실행 결과를 받아서 Promise 인지 여부를 확인하는 코드를 추가했습니다. 결과를 볼까요?

🚩 Entering method 'myMethod'.
myMethod called
🚩 Exiting method 'myMethod'.
🚩 Entering method 'myAsyncMethod'.
async method start
async method end
🚩 Exiting method 'myAsyncMethod'.

이제 비동기 함수도 잘 기다려주는 군요! 이제 마지막으로 한 가지만 더 확인해보겠습니다. 예외가 발생했을 때 말이죠!

function loggedMethod(headMessage = "🚩") {
 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);
 const result = originalMethod.apply(this, args);

 // 비동기 메서드인 경우, Promise가 완료된 후 로그를 출력
 if (result && typeof result.then === "function") {
 return result.finally(() => {
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 });
 }

 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 }

 return replacementMethod;
 };
}

class MyClass {
 @loggedMethod()
 myMethod() {
 console.log("myMethod called");
 throw new Error("test"); // 동기 작업에서 오류 발생
 }

 // 비동기 메서드
 @loggedMethod()
 async myAsyncMethod() {
 console.log("async method start");
 await new Promise((res, rej) =>
 setTimeout(() => {
 rej(new Error("test")); // 비동기 작업에서 오류 발생
 }, 500)
 );
 console.log("async method end");
 }
}

const myClass = new MyClass();
myClass.myMethod();
myClass.myAsyncMethod();

위 작업에서 두 메서드 중 하나에서 오류가 발생하도록 해보면 결과는 다음과 같습니다.

❯ npx ts-node new_decorator.ts
🚩 Entering method 'myMethod'.
myMethod called
/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:31
 throw new Error("test");
 ^
Error: test
 at MyClass.myMethod (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:31:11)
 at MyClass.replacementMethod (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:10:37)
 at Object.<anonymous> (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:48:9)
 at Module._compile (node:internal/modules/cjs/loader:1554:14)
 at Module.m._compile (/Users/onlifecoding/.npm/_npx/1bf7c3c15bf47d04/node_modules/ts-node/src/index.ts:1618:23)
 at node:internal/modules/cjs/loader:1706:10
 at Object.require.extensions.<computed> [as .ts] (/Users/onlifecoding/.npm/_npx/1bf7c3c15bf47d04/node_modules/ts-node/src/index.ts:1621:12)
 at Module.load (node:internal/modules/cjs/loader:1289:32)
 at Function._load (node:internal/modules/cjs/loader:1108:12)
 at TracingChannel.traceSync (node:diagnostics_channel:322:14)

뭐 이거도 그렇게 나쁘진 않지만, 데코레이터가 제대로 메서드의 종료를 출력하진 못하고 있죠. 수정해볼까요?

function loggedMethod(headMessage = "🚩") {
 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 function replacementMethod(this: any, ...args: any[]) {
 console.log(`${headMessage} Entering method '${methodName}'.`);

 try {
 const result = originalMethod.apply(this, args);

 // 비동기 메서드인 경우, Promise가 완료된 후 로그를 출력
 if (result && typeof result.then === "function") {
 return result.finally(() => {
 console.log(`${headMessage} Exiting method '${methodName}'.`);
 });
 }

 console.log(`${headMessage} Exiting method '${methodName}'.`);
 return result;
 } catch (error) {
 console.log(
 `${headMessage} Exiting method '${methodName}' with error.`
 );
 throw error;
 }
 }

 return replacementMethod;
 };
}

class MyClass {
 @loggedMethod()
 myMethod() {
 console.log("myMethod called");
 throw new Error("test");
 }

 // 비동기 메서드
 @loggedMethod()
 async myAsyncMethod() {
 console.log("async method start");
 await new Promise((res, rej) =>
 setTimeout(() => {
 rej(new Error("test"));
 }, 500)
 );
 console.log("async method end");
 }
}

const myClass = new MyClass();
myClass.myMethod();
myClass.myAsyncMethod();

이제 함수에서 발생하는 오류를 확인해볼까요?

❯ npx ts-node new_decorator.ts
🚩 Entering method 'myMethod'.
myMethod called
🚩 Exiting method 'myMethod' with error.
/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:39
 throw new Error("test");
 ^
Error: test
 at MyClass.myMethod (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:39:11)
 at MyClass.replacementMethod (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:12:39)
 at Object.<anonymous> (/Users/onlifecoding/src/test/typescript-studies/src/decorator/src/new_decorator.ts:56:9)
 at Module._compile (node:internal/modules/cjs/loader:1554:14)
 at Module.m._compile (/Users/onlifecoding/.npm/_npx/1bf7c3c15bf47d04/node_modules/ts-node/src/index.ts:1618:23)
 at node:internal/modules/cjs/loader:1706:10
 at Object.require.extensions.<computed> [as .ts] (/Users/onlifecoding/.npm/_npx/1bf7c3c15bf47d04/node_modules/ts-node/src/index.ts:1621:12)
 at Module.load (node:internal/modules/cjs/loader:1289:32)
 at Function._load (node:internal/modules/cjs/loader:1108:12)
 at TracingChannel.traceSync (node:diagnostics_channel:322:14)

함수가 오류 때문에 종료되었다고 명확하게 표시되는 걸 확인할 수 있습니다.

좀 더 확장해보기

데코레이터는 더 다양한 상황에서 유용하게 사용할 수 있는데요, 그 중에서 API 호출이 실패할 때 지정된 횟수만큼 재시도하도록 하는 데코레이터를 구현해보겠습니다.

📊 Exponential Backoff 재시도 데코레이터

Exponential Backoff 는 API 호출 등이 실패할 때, 지정된 횟수만큼 재시도하되, 재시도 사이에 시간 간격을 지수적으로 증가시키는 방법입니다. 뭔가 서비스가 일시적으로 오류가 발생했을 때, 복구하는 데 시간이 좀 걸릴 수 있으므로 그걸 대비해서 시간을 늘려가면서 재시도하는 거죠.

// src/retry_decorator.ts

/**
 * 재시도 옵션 인터페이스
 */
interface RetryOptions {
 maxRetries?: number; // 최대 재시도 횟수
 initialDelay?: number; // 초기 대기 시간 (밀리초)
}

/**
 * 특정 시간동안 대기하는 함수
 * @param ms - 대기 시간 (밀리초)
 * @returns 대기 완료 후 프로미스 반환
 */
function sleep(ms: number): Promise<void> {
 return new Promise((resolve) => setTimeout(resolve, ms));
}

/**
 * 재시도 데코레이터
 * @param options - 재시도 옵션
 * @returns 재시도 데코레이터 함수
 */
function retry(options: RetryOptions = {}) {
 const { maxRetries = 3, initialDelay = 1000 } = options;

 return function (
 originalMethod: Function,
 context: ClassMethodDecoratorContext
 ) {
 const methodName = String(context.name);

 async function replacementMethod(this: any, ...args: any[]) {
 let lastError: any;

 for (let attempt = 0; attempt <= maxRetries; attempt++) {
 try {
 const result = originalMethod.apply(this, args);

 // 비동기 메서드의 경우 await 키워드를 사용하여 비동기 작업 완료를 기다림
 if (result && typeof result.then === "function") {
 return await result;
 }

 return result;
 } catch (error) {
 lastError = error;

 if (attempt < maxRetries) {
 // Exponential backoff: 대기 시간 = initialDelay * 2^attempt
 const delay = initialDelay * Math.pow(2, attempt);
 const errorMessage =
 error instanceof Error ? error.message : String(error);

 console.log(
 `🔄 ${delay}ms 후 재시도 ${
 attempt + 1
 }/${maxRetries} - 오류: ${errorMessage}`
 );
 await sleep(delay);
 }
 }
 }

 console.log(`❌ All retries failed for '${methodName}'`);
 throw lastError;
 }

 return replacementMethod;
 };
}

// 예제 사용: Exponential Backoff 재시도 데코레이터
class TestService {
 private asyncAttemptCount = 0;
 private syncAttemptCount = 0;

 // 비동기 메서드에 적용(마지막에 성공하는 케이스)
 @retry({ maxRetries: 3, initialDelay: 500 })
 async unreliableAsyncMethod() {
 this.asyncAttemptCount++;
 console.log(
 `📡 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 ${this.asyncAttemptCount}`
 );

 if (this.asyncAttemptCount < 3) {
 throw new Error(
 `비동기 메서드 테스트 (2번 실패 후 성공) - 시도 ${this.asyncAttemptCount} 회 실패`
 );
 }

 console.log("✅ 비동기 메서드 테스트 (2번 실패 후 성공) - 성공!");

 return "비동기 메서드 테스트 (2번 실패 후 성공) - 성공!";
 }
}

// 결과 테스트
(async () => {
 const service = new TestService();

 console.log("=== 비동기 메서드 테스트 (2번 실패 후 성공) ===");
 try {
 const result = await service.unreliableAsyncMethod();
 console.log("Result:", result);
 } catch (error) {
 const errorMessage = error instanceof Error ? error.message : String(error);
 console.log("Final error:", errorMessage);
 }
})();

실행 해보면 결과는 다음과 같습니다.

❯ npx ts-node retry_decorator.ts
=== 비동기 메서드 테스트 (2번 실패 후 성공) ===
📡 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 1
🔄 500ms 후 재시도 1/3 - 오류: 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 1 회 실패
📡 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 2
🔄 1000ms 후 재시도 2/3 - 오류: 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 2 회 실패
📡 비동기 메서드 테스트 (2번 실패 후 성공) - 시도 3
✅ 비동기 메서드 테스트 (2번 실패 후 성공) - 성공!
Result: 비동기 메서드 테스트 (2번 실패 후 성공) - 성공!

추가 확장 아이디어

이 패턴을 기반으로 다음과 같이 확장해볼 수도 있을 겁니다.

데코레이터	설명	적용 예시
@Cache()	메서드 결과 캐싱	`@Cache({ ttl: 5000 })`
@RateLimit()	호출 빈도 제한	`@RateLimit({ maxCalls: 10, windowMs: 60000 })`
@Timeout()	실행 시간 제한	`@Timeout(5000)`
@Measure()	성능 측정	`@Measure({ threshold: 1000 })`
@Authorize()	권한 검증	`@Authorize(['admin', 'user'])`

참고자료

TypeScript: 인덱스 시그니처와 인덱스 액세스 타입

Thu, 24 Jul 2025 01:09:56 +0000

개요

이전에 작성했던 글에서 enum 타입 대신에 사용할 수 있는 방법 중 이런 코드가 있었습니다.

const Direction = {
 Up: "up",
 Down: "down",
 Left: "left",
 Right: "right",
} as const;

// 바로 여기가 인덱스 액세스 타입입니다!
type DirectionType = (typeof Direction)[keyof typeof Direction];

저는 이 코드를 처음 봤을 때 이게 뭐지? 싶었습니다. 좀 찾아본 뒤에 이해한대로 해석을 적긴했지만 완전히 이해되진 않았었습니다. 그래서 이 글은 제가 이해하고 싶어서 정리해본 내용을 적었는데요. TypeScript의 인덱스 시그니처(Index Signatures)와 인덱스 액세스 타입(Index Access Types)에 대해서 좀 더 자세히 알아보겠습니다.

용어 정리

글을 쓰면서 저도 용어가 좀 헷갈리기 시작했습니다. 우선 혼동을 방지하기 위해 먼저 핵심 용어들을 정리하겠습니다:

한국어	문법	용도
인덱스 시그니처	`[key: string]: any`	동적 키를 가진 객체의 타입 정의
인덱스 액세스 타입	`Type[Key]`	기존 타입에서 특정 속성 타입 추출
typeof 연산자	`typeof value`	값의 타입을 추론
keyof 연산자	`keyof Type`	타입의 모든 키를 유니온으로 추출

인덱스 시그니처 (Index Signatures)

기본 개념과 문법

인덱스 시그니처는 객체의 키가 미리 정해지지 않았지만, 키와 값의 타입을 알고 있을 때 사용하는 타입 정의 방법입니다.

// 기본 문법
interface Dictionary {
 [key: string]: any;
}

// 실제 사용 예시
const dict: Dictionary = {
 john: { name: "John", age: 30, isStudent: true },
 jane: { name: "Jane", age: 25, isStudent: false },
};

console.log(dict.john); // { name: "John", age: 30, isStudent: true }
console.log(dict.jane); // { name: "Jane", age: 25, isStudent: false }

다음과 같이 더 구체적인 타입을 지정할 수도 있습니다:

interface PersonDict {
 [key: string]: {
 name: string;
 age: number;
 isStudent: boolean;
 };
}

const people: PersonDict = {
 john: { name: "John", age: 30, isStudent: true },
 jane: { name: "Jane", age: 25, isStudent: false },
};

사용 예시

인덱스 시그니처는 다음과 같은 경우에 유용하게 사용할 수 있습니다.

API 응답 데이터 처리:

예를 들어 API 응답 데이터가 여러 사용자의 데이터를 객체로 반환하는 경우, 각 사용자 속성의 타입을 인덱스 시그니처로 정의할 수 있습니다.

interface ApiResponseData {
 [userId: string]: {
 name: string;
 email: string;
 lastLogin: Date;
 };
}

const userData: ApiResponseData = {
 user_123: {
 name: "Alice",
 email: "alice@example.com",
 lastLogin: new Date(),
 },
 user_456: { name: "Bob", email: "bob@example.com", lastLogin: new Date() },
};

설정 객체:

설정 값이 너무 많아서 일일이 타입으로 선언하기 어려운 경우, 대략적으로 허용되는 값들을 인덱스 시그니처로 정의할 수 있습니다.

interface AppConfig {
 [feature: string]: boolean | string | number;
 theme: "light" | "dark"; // 명시적 속성도 함께 사용 가능
 version: string;
}

const config: AppConfig = {
 theme: "dark",
 version: "1.0.0",
 enableNotifications: true,
 maxRetries: 3,
 apiEndpoint: "https://api.example.com",
};

제약사항과 주의점

1. Record 타입 사용 권장:

객체의 타입을 정의할 때는 인덱스 시그니처 보다 Record 타입을 사용하는 것이 더 간결하고 명확합니다.

// 인덱스 시그니처 대신 Record 타입 사용
interface Person {
 name: string;
 age: number;
 isStudent: boolean;
}

// 이렇게 하는 것이 더 명확합니다
const people: Record<string, Person> = {
 john: { name: "John", age: 30, isStudent: true },
 jane: { name: "Jane", age: 25, isStudent: false },
};

2. 타입 안전성 한계:

런타임에 실제로 존재하지 않는 속성도 컴파일 타입에는 오류 없이 접근할 수 있습니다.

interface FlexibleObject {
 [key: string]: string | number;
}

const obj: FlexibleObject = { name: "Alice", age: 30 };

// 컴파일 타임에는 에러가 없지만 런타임에 undefined일 수 있음
console.log(obj.nonExistentKey); // undefined (타입상으로는 string | number)

인덱스 액세스 타입 (Index Access Types)

기본 문법과 사용법

인덱스 액세스 타입은 기존 타입에서 특정 속성의 타입을 추출할 때 사용합니다.

interface Car {
 make: string;
 model: string;
 year: number;
 color: {
 red: string;
 green: string;
 blue: string;
 };
}

// 기본 사용법
type CarMake = Car["make"]; // string
type CarColor = Car["color"]; // { red: string; green: string; blue: string; }
type CarRedValue = Car["color"]["red"]; // string

// 여러 속성을 한번에 유니온으로 추출
type CarBasicInfo = Car["make" | "model"]; // string | string = string
type CarMixedInfo = Car["make" | "year"]; // string | number

typeof와 keyof 연산자

이제 처음에 보여드렸던 복잡한 코드를 단계별로 분석해보겠습니다:

const Direction = {
 Up: "up",
 Down: "down",
 Left: "left",
 Right: "right",
} as const;

type DirectionType = (typeof Direction)[keyof typeof Direction];

위 코드를 이해하기 위해 IDE의 도움을 받으면서 하나씩 분석해보겠습니다.

1단계: typeof 연산자

typeof 연산자는 객체 등의 값의 타입을 추론해서 반환합니다.

type DirectionObject = typeof Direction;
// 결과: {
// readonly Up: "up";
// readonly Down: "down";
// readonly Left: "left";
// readonly Right: "right";
// }

Direction이 const로 선언되었으므로, 각 속성이 readonly로 나타나고 있습니다.

2단계: keyof 연산자

keyof 연산자는 타입의 모든 키를 유니온으로 추출합니다.

type DirectionKeys = keyof typeof Direction;
// 결과: "Up" | "Down" | "Left" | "Right"

3단계: 인덱스 액세스 타입으로 값 추출

이제 인덱스 엑세스 타입으로 각 속성의 타입을 추출해보겠습니다.

type DirectionTypeUp = (typeof Direction)["Up"]; // "up"
type DirectionTypeX = (typeof Direction)["Left" | "Right"]; // "left" | "right"
type DirectionTypeAll = (typeof Direction)["Up" | "Down" | "Left" | "Right"]; // "up" | "down" | "left" | "right"

특정 속성만을 지정할 수도 있고, 유니온 타입으로 여러 속성을 지정할 수도 있습니다. 마지막의 DirectionTypeAll은 모든 속성을 유니온 타입으로 지정한 것인데요, 직관적이긴 하지만 속성 개수가 많아지면 이렇게 작성하긴 어려울 겁니다.

여기서 keyof 연산자를 사용해서 타입의 모든 속성을 유니온 타입으로 추출할 수 있습니다.

type AllKeys = keyof typeof Direction; // "Up" | "Down" | "Left" | "Right"
type DirectionTypeAll = (typeof Direction)[AllKeys]; // "up" | "down" | "left" | "right"

위 코드를 좀 더 단순화 하면 다음과 같습니다.

type DirectionType = (typeof Direction)[keyof typeof Direction]; // "up" | "down" | "left" | "right"

배열과 튜플에서의 사용

객체 뿐만 아니라 배열과 튜플같이 인덱스로 요소를 접근하는 타입에서도 인덱스 액세스 타입을 사용할 수 있습니다.

배열에서의 인덱스 액세스:

const arr = [
 { name: "John", age: 30, isStudent: true },
 { name: "Jane", age: 25 },
];

/**
 * ({
 * name: string;
 * age: number;
 * isStudent: boolean;
 * } | {
 * name: string;
 * age: number;
 * isStudent?: boolean;
 * })[]
 */
type PersonArray = typeof arr; // 배열 타입
/**
 * {
 * name: string;
 * age: number;
 * isStudent: boolean;
 * } | {
 * name: string;
 * age: number;
 * isStudent?: boolean;
 * }
 */
type Person = (typeof arr)[0]; // 배열 타입의 첫 번째 요소 타입
/**
 * {
 * name: string;
 * age: number;
 * isStudent?: boolean;
 * } | {
 * name: string;
 * age: number;
 * isStudent?: boolean;
 * }
 */
type Person2 = (typeof arr)[1]; // 배열 타입의 두 번째 요소 타입
/**
 * {
 * name: string;
 * age: number;
 * isStudent: boolean;
 * } | {
 * name: string;
 * age: number;
 * isStudent?: boolean;
 * }
 */
type PersonAll = (typeof arr)[number]; // 배열 타입의 모든 요소 타입

흥미로운 점은 배열 타입은 모든 요소의 타입이 동일하다는 점입니다. 그래서 특정 인덱스의 요소 타입을 사용하든, 모든 요소의 타입을 사용하든 상관없이 타입이 동일합니다.

튜플에서의 인덱스 액세스:

const tuple = [1, "hello", true] as const;

type FirstElement = (typeof tuple)[0]; // 1
type SecondElement = (typeof tuple)[1]; // "hello"
type ThirdElement = (typeof tuple)[2]; // true
type AllElements = (typeof tuple)[number]; // 1 | "hello" | true

튜플은 배열과 다르게 각 인덱스마다 서로 다른 타입을 가질 수 있습니다!

배열 vs 튜플 비교:

// 배열: 모든 인덱스에서 동일한 타입
const numbers: number[] = [1, 2, 3];
type NumberArrayElement = (typeof numbers)[0]; // number
type NumberArrayAny = (typeof numbers)[number]; // number

// 튜플: 각 인덱스마다 다른 타입
const mixedTuple: [string, number, boolean] = ["hello", 42, true];
type TupleFirst = (typeof mixedTuple)[0]; // string
type TupleSecond = (typeof mixedTuple)[1]; // number
type TupleUnion = (typeof mixedTuple)[number]; // string | number | boolean

다양한 활용 방법

이제 실제로 인덱스 엑세스 타입을 사용하는 예시를 살펴보겠습니다.

API 응답 타입에서 특정 데이터 추출

API 응답 타입에서 특정 데이터를 추출하는 경우 인덱스 엑세스 타입을 사용할 수 있습니다.

interface ApiResponse {
 users: Array<{
 id: string;
 name: string;
 email: string;
 profile: {
 avatar: string;
 bio: string;
 };
 }>;
 meta: {
 total: number;
 page: number;
 };
}

type User = ApiResponse["users"][0]; // 개별 사용자 타입
type UserProfile = User["profile"]; // 사용자 프로필 타입
type MetaInfo = ApiResponse["meta"]; // 메타 정보 타입

설정 객체에서 특정 설정 타입 추출

const appConfig = {
 database: {
 host: "localhost",
 port: 5432,
 name: "myapp",
 },
 cache: {
 ttl: 3600,
 maxSize: 1000,
 },
 features: {
 enableNewUI: true,
 enableBetaFeatures: false,
 },
} as const;

type DatabaseConfig = (typeof appConfig)["database"];
type CacheConfig = (typeof appConfig)["cache"];
type FeatureFlags = (typeof appConfig)["features"];

함수 파라미터와 반환 타입 추출

function processUser(user: { id: string; name: string; age: number }) {
 return {
 processed: true,
 user: user,
 timestamp: new Date(),
 };
}

type UserParam = Parameters<typeof processUser>[0]; // { id: string; name: string; age: number }
type ProcessResult = ReturnType<typeof processUser>; // { processed: boolean; user: { id: string; name: string; age: number; }; timestamp: Date }

조건부 타입과의 활용

/**
 * 함수 타입에서 반환 타입이 Promise인지 확인하고 언래핑
 *
 * Promise 타입인 경우, U의 타입을 추론해서 U를 리턴합니다.
 * Promise 타입이 아닌 경우, T를 리턴합니다.
 */
type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;

interface ServiceMethods {
 getUser: () => Promise<{ id: string; name: string }>;
 getUserSync: () => { id: string; name: string };
 deleteUser: (id: string) => Promise<void>;
}

type UserData = UnwrapPromise<ReturnType<ServiceMethods["getUser"]>>; // { id: string; name: string }
type UserDataSync = UnwrapPromise<ReturnType<ServiceMethods["getUserSync"]>>; // { id: string; name: string }

위 에제에서는 getUser 함수의 반환 타입이 Promise<{ id: string; name: string }> 이므로, U의 타입으로 { id: string; name: string } 을 추론해서 UnwrapPromise 타입은 { id: string; name: string } 을 리턴합니다.

권장 사항

명시적 인터페이스 vs 인덱스 시그니처

// ❌ 너무 관대한 타입
interface BadConfig {
 [key: string]: any;
}

// ✅ 구체적인 타입 정의
interface GoodConfig {
 apiUrl: string;
 timeout: number;
 retries: number;
 [feature: string]: string | number | boolean; // 추가 기능용
}

Record 타입 활용

// ❌ 인덱스 시그니처
interface UserPermissions {
 [userId: string]: "read" | "write" | "admin";
}

// ✅ Record 타입 사용
type UserPermissions = Record<string, "read" | "write" | "admin">;

타입 안전성을 위한 검증

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
 return obj[key];
}

const user = { name: "Alice", age: 30 };
const userName = getProperty(user, "name"); // string (타입 안전)
// const invalid = getProperty(user, 'invalid'); // 컴파일 에러

성능 고려사항

1. 컴파일 시간:

복잡한 인덱스 액세스 타입은 컴파일 시간을 증가시킬 수 있습니다.
필요한 경우에만 사용하고, 가능하면 명시적 타입을 정의해야 합니다.

2. 런타임 영향 없음:

모든 타입 정보는 컴파일 시에만 존재하기 때문에 런타임에는 아무런 영향을 주지 않습니다.

요약

주요 패턴 요약

패턴	문법	용도	예시
인덱스 시그니처	`[key: string]: ValueType`	동적 키 객체 정의	`{ [userId: string]: User }`
기본 인덱스 액세스	`Type[Key]`	속성 타입 추출	`User['name']`
typeof 인덱스 액세스	`(typeof value)[Key]`	값에서 속성 타입 추출	`(typeof config)['api']`
keyof와 조합	`Type[keyof Type]`	모든 속성값의 유니온	`User[keyof User]`
배열 요소 타입	`ArrayType[number]`	배열 요소 타입 추출	`Users[number]`
튜플 특정 요소	`TupleType[Index]`	튜플 특정 위치 타입	`[string, number][0]`

연산자 비교

연산자	입력	출력	예시
`typeof`	값 (value)	타입 (type)	`typeof user` → `{ name: string; age: number }`
`keyof`	타입 (type)	키 유니온 (key union)	`keyof User` → `"name" \| "age"`
`Type[Key]`	타입, 키	속성 타입	`User["name"]` → `string`

사용 시나리오별 권장사항

시나리오	권장 방법	이유
API 응답 타입 정의	명시적 인터페이스 + 필요시 인덱스 액세스	타입 안전성과 가독성
설정 객체	Record 타입 또는 명시적 속성 + 인덱스 시그니처	유연성과 타입 안전성 균형
상수 객체에서 값 타입 추출	`as const` + `typeof` + `keyof` 조합	리터럴 타입 보장
배열/튜플 요소 타입	`ArrayType[number]` 또는 `TupleType[Index]`	정확한 요소 타입 추출

정리

핵심 개념 정리

인덱스 시그니처는 동적인 키를 가진 객체의 타입을 정의할 때 사용합니다
인덱스 액세스 타입은 기존 타입에서 특정 속성의 타입을 추출할 때 사용합니다
typeof 연산자는 값의 타입을 추론하고, keyof 연산자는 타입의 모든 키를 추출합니다
배열에서는 모든 요소가 같은 타입을 가지지만, 튜플에서는 각 위치마다 다른 타입을 가질 수 있습니다

참고 자료

Typescript: erasableSyntaxOnly

Sat, 19 Jul 2025 23:47:01 +0000

최근에 몇가지 시험해볼 게 있어서 프로토타이핑을 진행할 일이 있었습니다. 평소 처럼 리액트 프로젝트를 새로 구성하고 이것저것 코딩을 하다가 처음보는 에러를 발견했습니다.

erasableSyntaxOnly… 이건 뭘까요? 잠시 에러를 쳐다보다가 찾아보기 시작했습니다.

그러니까 이 erasableSyntaxOnly는 Typescript 5.8에 추가된 컴파일러 옵션이었습니다.

이 옵션이 추가된 배경은 뭔지, 그래서 뭘 어떻게 바꿔야 하는지 하나씩 알아보겠습니다.

옵션이 추가된 배경

런타임	TypeScript 지원 상태	특징
Bun.js	✅ 네이티브 지원	초기부터 TypeScript 실행 지원
Deno	✅ 네이티브 지원	TypeScript 우선 설계
Node.js (이전)	❌ 별도 도구 필요	`tsc`, `ts-node` 등 필요
Node.js 22.6.0+	✅ 실험적 지원	`--experimental-strip-types`
Node.js 23.6.0+	✅ 기본 지원	별도 플래그 불필요

원래 node.js는 Typescript 코드를 실행하는 기능이 없었습니다. 그래서 tsc를 통해 코드를 트랜스파일링 해서 Javascript로 변환해서 실행하거나 ts-node같은 도구를 사용했었죠. 하지만 Bun.js나 Deno 같이 Typescript 실행을 지원하는 런타임이 나오면서 node.js가 좀 뒤쳐지는 모양새가 되었습니다. 그러던 중에 node.js 22.6.0에서 Typescript 실행을 지원하는 –experimental-strip-types 플래그가 추가되었고 , node.js 23.6.0에서 별도의 설정없이 Typescript 코드를 실행할 수 있게 되었습니다.

물론 아직까지는 몇가지 제약사항이 있습니다.

제약사항

node.js는 Typescript 코드를 실행하기 위해 타입을 제거하는 과정(type stripping)을 거칩니다. 이 과정은 Typescript 컴파일러의 트랜스파일 없이 진행되는데요, 이렇게 하면 몇가지 이점이 있습니다. 우선 타입 제거와 트랜스파일링을 비교해볼까요?

특징	타입 스트리핑	전통적 트랜스파일링
처리 방식	타입만 제거	전체 코드 변환
소스 맵	불필요 (라인 유지)	필요
성능	빠름	상대적으로 느림
디버깅	직관적 (WYSIWYG)	소스 맵 의존
지원 문법	제한적 (erasable만)	모든 TS 문법

소스 맵이 필요없음: 코드의 구조가 전혀 바뀌지 않기 때문에, 소스 맵을 생성할 필요가 없으며 직관적인 디버깅이 가능합니다.
성능 최적화: 컴파일 과정이 없기 때문에, 더 빠른 실행 속도를 기대할 수 있습니다.
실행 과정이 직관적: 타입을 제외하고 작성된 코드 그대로(WYSIWYG) 실행됩니다.

다만, 컴파일 과정을 거치지 않기 때문에 몇가지 제약사항이 생깁니다. Typescript 컴파일러가 특정 기능을 지원하기 위해 Javascript로 변환하는 과정에서 뭔가 코드를 생성해야 한다면 어떨까요? 앞서 말씀 드렸듯이 node.js는 Typescript 코드를 타입만을 제거하고 있는 그대로 실행합니다. 그렇기 때문에 이런 기능들은 더 이상 사용할 수 없으며 다른 방법을 찾아야 합니다.

이 글을 시작하면서 보여드렸던 enum이 이런 제약사항에 가장 큰 영향을 받는 기능입니다. enum을 중심으로 좀 더 자세히 알아보죠!

enum으로 제약사항 알아보기

우선 다음과 같이 tsconfig.json을 설정해서 타입을 제거하지 않고 실행해보겠습니다.

{
 "compilerOptions": {
 "erasableSyntaxOnly": false,
 "outDir": "./dist"
 }
}

그리고 다음과 같이 enum을 선언해보겠습니다.

// enum/enum.ts
enum Direction {
 UP,
 DOWN,
 LEFT,
 RIGHT,
}

그리고 다음과 같이 실행해보겠습니다.

npx tsc

그러면 다음과 같이 타입이 제거된 코드가 생성됩니다.

// dist/enum.js
var Direction;
(function (Direction) {
 Direction[(Direction["UP"] = 0)] = "UP";
 Direction[(Direction["DOWN"] = 1)] = "DOWN";
 Direction[(Direction["LEFT"] = 2)] = "LEFT";
 Direction[(Direction["RIGHT"] = 3)] = "RIGHT";
})(Direction || (Direction = {}));

결과에서 볼 수 있듯이 enum은 원래 Javascript에서 제공되지 않으므로 Typescript 컴파일러가 트랜스파일 하는 과정에서 Javascript 코드를 생성합니다. 하지만 node.js에서 이 코드를 바로 실행하기 위해 erasableSyntaxOnly 옵션을 true로 설정하면, Typescript 컴파일러는 enum에 대해 불평을 쏟아냅니다.

해결 방법

erasableSyntaxOnly 옵션은 이름 그대로 타입을 제거하고 실행할 때 제거될 수 있는 문법들만 허용하겠다 그래서 node.js가 직접 Typescript를 실행할 수 있는 코드만 허용하겠다는 의미입니다.

enum은 별도의 코드를 생성해야 하므로 사용할 수 없으므로, 다음과 같이 별도의 과정없이 사용할 수 있는 형태로 변경해야 합니다.

// enum/enum.ts
// 원래 코드
// enum Direction {
// UP,
// DOWN,
// LEFT,
// RIGHT,
// }

// erasableSyntaxOnly 옵션에서 사용가능한 enum
const Direction = {
 Up: "up",
 Down: "down",
 Left: "left",
 Right: "right",
} as const;

type DirectionType = (typeof Direction)[keyof typeof Direction];

const direction: DirectionType = Direction.Up;

console.log(direction);

enum 대신에 객체 리터럴(literal)을 사용해서 enum을 대신할 수 있도록 합니다. 컴파일된 결과를 확인해볼까요?

// dist/enum.js
// 원래 코드
// enum Direction {
// UP,
// DOWN,
// LEFT,
// RIGHT,
// }
// erasableSyntaxOnly 옵션에서 사용가능한 enum
var Direction = {
 Up: "up",
 Down: "down",
 Left: "left",
 Right: "right",
};
var direction = Direction.Up;
console.log(direction);

타입 정보만 삭제된 채로 코드가 생성되었고, 다음과 같이 실행해보면 결과도 정상적으로 출력됩니다.

> node dist/enum.js
up

type DirectionType = (typeof Direction)[keyof typeof Direction]; 이 부분이 상당히 혼란스러운데요. 이 부분은 다음과 같이 해석할 수 있습니다.

typeof Direction: Direction은 객체 리터럴이고 다음과 같은 타입입니다.

{
 readonly Up: "up";
 readonly Down: "down";
 readonly Left: "left";
 readonly Right: "right";
}

keyof typeof Direction: 위 객체의 키들을 의미합니다. 즉, "Up" | "Down" | "Left" | "Right" 입니다.
(typeof Direction)[keyof typeof Direction]: 인덱스 엑세스 타입을 의미하는데요, Direction 객체에서 사용가능한 모든 값을 유니온 타입으로 반환합니다. 즉, "up" | "down" | "left" | "right" 입니다.

조금 복잡해 보이긴 하지만, 이렇게 함으로써 다음과 같은 효과를 얻을 수 있습니다.

타입 안전성: enum과 마찬가지로 컴파일 타임에 타입 체크가 지원됩니다.
IDE 지원: 타입 정보가 있으니까 IDE가 자동 완성을 지원합니다.
소스 맵이 필요없음: 삭제되는 코드는 빈칸으로 남겨서 라인 수를 유지하기 때문에 소스 맵을 생성 및 사용할 필요가 없습니다.
삭제가능!: 타입 정보만 삭제하고 바로 실행 가능합니다.
디버그 직관성: WYSIWYG(What You See Is What You Get). 코드를 보면 바로 이해할 수 있습니다.

좀 더 간단한 버전

만약, Direction.Up 대신에 문자열 리터럴을 그대로 사용해도 된다면, 다음과 같이 유니온 타입으로 더 간단하게 사용할 수 있습니다.

// 좀 더 간단한 버전
type Direction = "up" | "down" | "left" | "right";

const direction: Direction = "up";

console.log(direction);

타입 정보를 활용할 수 있기 때문에 다음과 같이 IDE의 도움을 받을 수도 있습니다.

Enum 대안 비교표

방법	문법 복잡도	타입 안전성	IDE 지원	런타임 비용	추천도
기존 enum	⭐⭐	⭐⭐⭐	⭐⭐⭐	높음 (객체 생성)	❌ (erasableSyntaxOnly에서 불가)
const 객체 + as const	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	낮음	⭐⭐⭐
string literal union	⭐	⭐⭐⭐	⭐⭐⭐	없음	⭐⭐⭐

그외 제약사항들

클래스를 정의할 때 속성을 정의하는 대신에 생성자의 파라미터로 대신하는 패턴은 사용할 수 없습니다.

// ❌ erasableSyntaxOnly 옵션에서는 이렇게 하면 안됩니다!
class Person {
 constructor(private name: string, public age: number) {}
}

// ✅ 이렇게 해야 합니다.
class Person {
 private name: string;
 public age: number;

 constructor(name: string, age: number) {
 this.name = name;
 this.age = age;
 }
}

그리고 commonjs 스타일의 임포트 구문은 erasableSyntaxOnly 옵션에서 사용할 수 없습니다.

// ❌ erasableSyntaxOnly 옵션에서는 이렇게 하면 안됩니다!
import foo = require("foo");

// ✅ 이렇게 해야 합니다.
import foo from "foo";

erasableSyntaxOnly 제약사항 요약

문법	사용 가능 여부	이유	대안
enum	❌	런타임 코드 생성 필요	`const` 객체 + `as const`
클래스 파라미터 속성	❌	자동 속성 할당 코드 생성	명시적 속성 선언
CommonJS import	❌	import 변환 필요	ES6 import

하지만, Typescript 기능을 활용할 수 있는 방법은 있습니다.

node.js 22.7.0에서 추가된 --experimental-transform-types 플래그를 사용하면 Typescript 에서만 제공되는 enum 같은 문법을 그대로 사용할 수도 있습니다!

테스트를 위해 일단 erasableSyntaxOnly 옵션을 비활성화 하고 enum 코드를 실행해볼까요?

// enum/enum.ts
enum Direction {
 UP,
 DOWN,
 LEFT,
 RIGHT,
}

const direction = Direction.UP;

console.log(direction);

그리고 다음과 같이 실행합니다.

> node --experimental-transform-types enum/enum.ts
0
(node:63565) ExperimentalWarning: Type Stripping is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

불평을 하긴 하지만, 정상적으로 실행되는 걸 확인할 수 있습니다. 이 옵션을 사용하면 내부적으로 Amaro 를 활용해서 소스코드를 해석하고 변환한다고 합니다. 따라서 enum과 같은 Typescript 전용 문법도 사용할 수 있고, 디버깅을 위한 소스맵도 생성됩니다. 하지만 실행을 위해 코드를 변환해야 하니까 아무래도 성능은 떨어지겠죠?

Node.js TypeScript 실행 옵션 비교

플래그	추가 버전	처리 방식	enum 지원	성능	소스 맵
`--experimental-strip-types`	22.6.0	타입만 제거	❌	빠름	불필요
`--experimental-transform-types`	22.7.0	Amaro 변환	✅	보통	생성됨

권장사항

앞서 설명했듯이 erasableSyntaxOnly 옵션은 타입을 제거하고 실행할 수 있는 문법만 허용합니다. Typescript 컴파일러가 코드를 변환하는 작업이 없어야 한다는 의미이며, 임포트 생략(import elision) 또한 여기에 포함됩니다. Typescript가 임의로 임포트를 생략하지 않도록 verbatimModuleSyntax 옵션을 같이 사용하는 게 좋습니다. 임포트 생략과 verbatimModuleSyntax 옵션에 대해서 다룬 글이 있으니 관심 있으신 분은 참고바랍니다.

한 가지 더: Type as Comments

Javascript 표준에서도 타입을 지원하기 위한 논의가 진행되고 있습니다. TC39: Type as Comments 를 보면, Typescript와 유사한 형태로 타입을 선언할 수 있도록 제안이 진행되고 있습니다. 여기서도 타입은 역시 런타임에서는 무시되는 형태인데요, Typescript가 가고자 하는 방향도 이와 맞닿아 있는 걸로 보입니다.

요약

erasableSyntaxOnly 핵심 정리

항목	내용
목적	Node.js의 네이티브 TypeScript 실행 지원
원리	타입만 제거하고 코드 변환 없이 실행
주요 장점	⚡ 빠른 실행, 🚫 소스 맵 불필요, 🎯 직관적 디버깅
주요 제약	enum, 클래스 파라미터 속성, CommonJS import 사용 불가
권장 설정	`erasableSyntaxOnly: true` + `verbatimModuleSyntax: true`

마이그레이션 체크리스트

enum → const 객체 + as const 또는 string literal union으로 변경
클래스 파라미터 속성 → 명시적 속성 선언으로 변경
import foo = require() → ES6 import 구문으로 변경
verbatimModuleSyntax: true 옵션 추가
erasableSyntaxOnly: true 옵션 설정

참고자료

CommonJS와 ESM의 차이점

Sat, 12 Jul 2025 01:07:40 +0000

📋 목차 (Table of Contents)

개요

Javascript는 원래 브라우저에 동작을 구현하기 위한 스크립트 언어였습니다. 따라서 복잡한 설계가 들어가지 않았고, 2000년대 말에 Flash, Silverlight 등의 RIA 붐이 일어나기 전에는 웹 페이지를 구현하기 위해 5000줄이 넘어가는 스크립트를 작성하는 경우도 자주 볼 수 있었습니다.

timeline
title JavaScript 모듈 시스템의 발전사
1995 : JavaScript 탄생. 브라우저 스크립트 언어
2000s : 복잡한 웹 애플리케이션 등장. 모듈 시스템 부재로 인한 문제
2009 : Node.js & CommonJS 등장. 서버사이드 JavaScript 시대
2014 : Webpack 1.0 출시. 모듈 번들러 시대
2015 : ES6 & ESM 표준화. 공식 모듈 시스템 도입
2020s : 현대적 도구들. Vite, ESBuild
2024 : Node.js 22. require() ESM 지원

그 후 CPU의 병렬 처리 능력 향상과 V8 엔진 등의 발전으로 Javascript가 처리할 수 있는 영역이 급속도로 넓어지면서 2009년에 Node.js가 발표되었고, Node.js가 2009년에 처음 발표될 때, CommonJS 모듈 시스템이 같이 공개되었습니다. 덩치가 큰 서버 어플리케이션을 만들 때는 필수적으로 코드를 여러 개의 모듈로 쪼개서 프로젝트를 구성해야 하는데 원래 Javascript에는 그런 개념이 없었기 때문이죠.

그 후 Javascript는 아주 느린 속도로 현대적인 언어가 되어갔습니다. 그리고 2015년, ES6 표준과 함께 ESM(ECMAScript Module)이 도입되었습니다. 드디어 Javascript를 활용하는 환경 어디든(브라우저, 서버) 모두 공통적으로 활용할 수 있는 모듈 시스템이 생긴거죠.

CommonJS

CommonJS 특징

CommonJS는 module.exports를 통해 모듈의 기능을 외부로 내보내고, require()를 통해 다른 모듈을 임포트 합니다. require()를 통한 임포트는 다음과 같은 특성이 있습니다.

모듈 로드는 동기적(synchronous)으로 이루어집니다. 따라서 require()를 통히 모듈 임포트가 모두 끝나기 전에는 코드 실행이 중지됩니다.
어떤 모듈을 로드할지 컴파일 타임에는 알 수 없으며, 코드가 실행되는 런타임에 동적(dynamic)으로 결정됩니다. 따라서 webpack과 같은 번들러는 어떤 모듈이 실제로 로드될지 알 수 없으므로 모듈의 일부만 사용되더라도 전체 모듈을 번들링해야 합니다. 즉, tree-shaking이 불가능합니다.

즉, 모듈을 동기적(synchronous)으로 로드하지만, 실제로 어떤 모듈이 로드될지 컴파일 시점에는 알 수 없는 동적(dynamic) 로딩이 진행된다는 겁니다. 다음 예제를 볼까요?

CommonJS 동적 로딩 예제

우선 모듈을 2개 만들어 줍니다.

// resolution-time/math-utils.cjs
console.log("math-utils.js 로딩 중");

function add(a, b) {
 return a + b;
}

function subtract(a, b) {
 return a - b;
}

function multiply(a, b) {
 return a * b;
}

module.exports = {
 add,
 subtract,
 multiply,
};

// resolution-time/string-utils.cjs
console.log("string-utils.js 로딩 중");

function capitalize(str) {
 return str.charAt(0).toUpperCase() + str.slice(1);
}

function reverse(str) {
 return str.split("").reverse().join("");
}

function truncate(str, length) {
 return str.length > length ? str.substring(0, length) + "..." : str;
}

module.exports = {
 capitalize,
 reverse,
 truncate,
};

각각 간단한 함수 몇 가지를 선언하고, module.exports를 통해 외부로 내보내고 있습니다. 파일의 확장자가 cjs인 이유는 이 파일이 CommonJS 모듈 시스템을 사용하는 파일이라는 것을 명시하기 위해서입니다.

이제 런타임에 모듈을 로드하는 코드를 작성해 보겠습니다.

// resolution-time/commonjs-runtime.cjs
console.log("=== CommonJS 런타임 해석 데모 ===");

// 사용자의 입력을 받습니다.
const userChoice = process.argv[2];
console.log(`사용자가 선택한 값: ${userChoice}`);

// 런타임에 로드할 모듈을 결정 - 사용자의 입력에 따라 어떤 모듈을 로드할지 결정합니다.
let utils;
if (userChoice === "math") {
 // (1) 사용자가 math를 선택한 경우
 console.log("런타임에 수학 유틸리티 로딩 중...");
 utils = require("./math-utils.cjs");
} else if (userChoice === "string") {
 // (2) 사용자가 string을 선택한 경우
 console.log("런타임에 문자열 유틸리티 로딩 중...");
 utils = require("./string-utils.cjs");
} else {
 // (3) 사용자가 값을 입력하지 않은 경우
 console.log("런타임에 두 유틸리티 모두 로딩 중...");
 const mathUtils = require("./math-utils.cjs");
 const stringUtils = require("./string-utils.cjs");
 utils = { ...mathUtils, ...stringUtils };
}

// 런타임에 동적으로 로드된 모듈을 사용합니다.
if (userChoice === "math") {
 // (1) 사용자가 math를 선택한 경우
 console.log("수학 결과:", utils.add(5, 3));
} else if (userChoice === "string") {
 // (2) 사용자가 string을 선택한 경우
 console.log("문자열 결과:", utils.capitalize("hello world"));
} else {
 // (3) 사용자가 값을 입력하지 않은 경우
 console.log("수학 결과:", utils.add(5, 3));
 console.log("문자열 결과:", utils.capitalize("hello world"));
}

// 또 다른 예시: 함수 내에서 조건부 require를 사용합니다.
function getFormatterForType(type) {
 if (type === "number") {
 return require("./math-utils.cjs");
 } else {
 return require("./string-utils.cjs");
 }
}

console.log("\n함수 내에서 동적 로딩:");
const formatter = getFormatterForType("string");
console.log("포맷된 결과:", formatter.capitalize("dynamic loading"));

코드가 좀 복잡해보이지만 위에서 부터 천천히 확인해보면 다음과 같습니다.

사용자의 입력을 파라미터로 받습니다.
입력에 따라 어떤 모듈을 로드할지 결정합니다.
로드된 모듈을 통해 결과를 출력합니다.
함수 내에서 조건부로 모듈을 로드할 수도 있습니다.

이제 코드를 실행해볼까요?

> node resolution-time/commonjs-runtime.cjs math
=== CommonJS 런타임 해석 데모 ===
사용자가 선택한 값: math
런타임에 수학 유틸리티 로딩 중...
math-utils.js 로딩 중
수학 결과: 8

함수 내에서 동적 로딩:
string-utils.js 로딩 중
포맷된 결과: Dynamic loading

파라미터로 math를 입력하자 math-utils.cjs 모듈만 로드되었고, 이후 함수 내에서 동적으로 string-utils.cjs 모듈을 로드하는 코드가 실행되었습니다.

ESM (ECMAScript Modules)

ESM 특징

ESM은 모듈의 기능을 export 키워드를 통해 외부로 내보내고, import 키워드를 통해 다른 모듈을 임포트 합니다. import 키워드를 통한 임포트는 다음과 같은 특성이 있습니다.

모듈의 첫 번째 코드가 실행되기 전에 모든 import가 진행됩니다. 따라서 어떤 모듈을 로드하는지 정적(static)으로 결정되므로, 실제로 로드되는 항목만 번들링하는 tree-shaking이 가능합니다.
비동기적(asynchronous)으로 모듈을 로드할 수 있습니다. 따라서 모듈을 로드하는 동안 중단없이 코드를 실행할 수도 있습니다.

즉, 모듈을 비동기적(asynchronous)으로 로드하고, 어떤 모듈을 로드할지 정적(static)으로 결정되므로, 실제로 로드되는 항목만 번들링하는 tree-shaking이 가능하다는 겁니다. 다음 예제를 볼까요?

ESM 정적 임포트 예제

이번에도 모듈을 2개 먼저 선언하겠습니다.

// resolution-time/math-utils.mjs
console.log("math-utils.mjs 로딩 중");

export function add(a, b) {
 return a + b;
}

export function subtract(a, b) {
 return a - b;
}

export function multiply(a, b) {
 return a * b;
}

// resolution-time/string-utils.mjs
console.log("string-utils.mjs 로딩 중");

export function capitalize(str) {
 return str.charAt(0).toUpperCase() + str.slice(1);
}

export function reverse(str) {
 return str.split("").reverse().join("");
}

export function truncate(str, length) {
 return str.length > length ? str.substring(0, length) + "..." : str;
}

각각의 함수를 export 키워드를 통해 외부로 내보내고 있습니다. 파일의 확장자가 mjs인 이유는 이 파일이 ESM 모듈 시스템을 사용하는 파일이라는 것을 명시하기 위해서입니다.

이제 런타임에 모듈을 로드하는 코드를 작성해 보겠습니다.

// resolution-time/esm-static.mjs
// esm-static.mjs
console.log("=== ESM 정적 해석 데모 ===");

// ESM을 임포트는 컴파일 타임에 로드할 모듈이 결정됩니다.
import { add, multiply } from "./math-utils.mjs";
import { capitalize, reverse } from "./string-utils.mjs";

console.log("모든 임포트가 컴파일 타임에 해석되었습니다!");

// 사용자의 입력을 받습니다.
const userChoice = process.argv[2];
console.log(`사용자가 선택한 값: ${userChoice}`);

// 모듈이 이미 로드되어 있으므로, 사용할 함수를 선택합니다.
if (userChoice === "math") {
 // (1) 사용자가 math를 선택한 경우
 console.log("수학 결과:", add(5, 3));
 console.log("수학 결과:", multiply(4, 7));
} else if (userChoice === "string") {
 // (2) 사용자가 string을 선택한 경우
 console.log("문자열 결과:", capitalize("hello world"));
 console.log("문자열 결과:", reverse("hello"));
} else {
 console.log("수학 결과:", add(5, 3));
 console.log("문자열 결과:", capitalize("hello world"));
}

코드는 다음과 같은 동작을 수행합니다.

모듈에서 사용할 함수만 선택적으로 임포트합니다.
사용자의 입력을 받습니다.
사용자의 입력에 따라 로드된 모듈의 함수를 사용합니다.

코드를 실행해볼까요?

> node resolution-time/esm-static.mjs math
math-utils.mjs 로딩 중
string-utils.mjs 로딩 중
=== ESM 정적 해석 데모 ===
모든 임포트가 컴파일 타임에 해석되었습니다!
사용자가 선택한 값: math
수학 결과: 8
수학 결과: 28

앞서 설명 드린 대로, 첫 번째 코드가 실행되기 전에 모듈의 임포트가 진행되었습니다. 코드를 실행하지 않아도 어떤 모듈이 로드될지 정적(static)으로 알 수 있다는 거죠!

ESM 동적 임포트 예제

자 그러면, 앞선 CommonJS 예제 처럼 동적으로 모듈을 로드해볼까요?

// resolution-time/esm-dynamic.mjs
// esm-dynamic.mjs
console.log("=== ESM 동적 임포트 데모 ===");

// 사용자의 입력을 받습니다.
const userChoice = process.argv[2];
console.log(`사용자가 선택한 값: ${userChoice}`);

// ESM에서 동적으로 모듈을 로드합니다.
let utils;
if (userChoice === "math") {
 // (1) 사용자가 math를 선택한 경우
 console.log("수학 유틸리티를 동적으로 임포트 중...");
 utils = await import("./math-utils.mjs");
} else if (userChoice === "string") {
 // (2) 사용자가 string을 선택한 경우
 console.log("문자열 유틸리티를 동적으로 임포트 중...");
 utils = await import("./string-utils.mjs");
} else {
 // (3) 사용자가 값을 입력하지 않은 경우
 console.log("두 유틸리티를 모두 동적으로 임포트 중...");
 const [mathUtils, stringUtils] = await Promise.all([
 import("./math-utils.mjs"),
 import("./string-utils.mjs"),
 ]);
 utils = { ...mathUtils, ...stringUtils };
}

// 런타임에 동적으로 로드된 모듈을 사용합니다.
if (userChoice === "math") {
 // (1) 사용자가 math를 선택한 경우
 console.log("수학 결과:", utils.add(5, 3));
} else if (userChoice === "string") {
 // (2) 사용자가 string을 선택한 경우
 console.log("문자열 결과:", utils.capitalize("hello world"));
} else {
 // (3) 사용자가 값을 입력하지 않은 경우
 console.log("수학 결과:", utils.add(5, 3));
 console.log("문자열 결과:", utils.capitalize("hello world"));
}

// 함수 내에서 동적으로 모듈을 로드합니다.
async function getFormatterForType(type) {
 if (type === "number") {
 return await import("./math-utils.mjs");
 } else {
 return await import("./string-utils.mjs");
 }
}

console.log("\n함수 내에서 동적 로딩:");
const formatter = await getFormatterForType("string");
console.log("포맷된 결과:", formatter.capitalize("dynamic loading"));

사용자의 입력에 따라 동적으로 async import를 수행하고 있습니다. 결과를 볼까요?

=== ESM 동적 임포트 데모 ===
사용자가 선택한 값: math
수학 유틸리티를 동적으로 임포트 중...
math-utils.mjs 로딩 중
수학 결과: 8

함수 내에서 동적 로딩:
string-utils.mjs 로딩 중
포맷된 결과: Dynamic loading

앞선 CommonJS 예제와 동일한 결과를 확인할 수 있습니다.

핵심 차이점 정리

📊 CommonJS vs ESM 비교표

특성	CommonJS	ESM
문법	`require()` / `module.exports`	`import` / `export`
로딩 방식	동기적 (Synchronous)	비동기적 (Asynchronous)
해석 시점	런타임 (Dynamic)	컴파일 타임 (Static)
Tree-shaking	❌ 불가능	✅ 가능
브라우저 지원	❌ 번들러 필요	✅ 네이티브 지원
Node.js 지원	✅ 기본 지원	✅ 지원 (v14+)
파일 확장자	`.js`, `.cjs`	`.js`, `.mjs`

🔄 모듈 로딩 프로세스 비교

graph TB
subgraph "CommonJS 로딩 프로세스"
A1[코드 실행 시작] --> B1[require 호출]
B1 --> C1[런타임에 모듈 경로 해석]
C1 --> D1[모듈 파일 로드]
D1 --> E1[모듈 코드 실행]
E1 --> F1[module.exports 반환]
F1 --> G1[다음 코드 실행]
end

graph TB
subgraph "ESM 로딩 프로세스"
A2[파싱 단계] --> B2[import 문 발견]
B2 --> C2[컴파일 타임에 모듈 그래프 구성]
C2 --> D2[모든 모듈 비동기 로드]
D2 --> E2[모듈 평가 및 바인딩]
E2 --> F2[코드 실행 시작]
end

핵심 요약

CommonJS: 모듈을 동기적(synchronous)으로 로드하지만, 실제로 어떤 모듈이 로드될지 컴파일 시점에는 알 수 없는 동적(dynamic) 로딩이 진행됩니다.
ESM: 모듈을 비동기적(asynchronous)으로 로드하고, 어떤 모듈을 로드할지 정적(static)으로 결정되므로, 실제로 로드되는 항목만 번들링하는 tree-shaking이 가능합니다.

Tree-shaking

Tree-shaking 개념

Tree-shaking은 배포를 위해 코드를 번들링할 때, 모듈 시스템에서 사용되지 않는 모듈을 제거하는 기능입니다. 즉, 사용하지 않는 모듈을 결과물에서 제거하여 번들 파일의 크기를 줄입니다. 번들 파일의 크기가 줄어들면 로드하는 데 걸리는 시간이 줄어들고 메모리 역시 절약할 수 있겠죠. 프로젝트가 작을 때는 티가 안나지만, 프로젝트의 크기가 커질수록 매우 큰 차이를 보입니다.

Tree-shaking 실습 예제

에제로 확인해보죠! 다음과 같이 package.json을 작성합니다.

//tree-shaking/package.json
{
 "name": "tree-shaking-demo",
 "version": "1.0.0",
 "description": "Demonstrates tree-shaking differences between CommonJS and ESM",
 "type": "module",
 "scripts": {
 "build": "webpack",
 "test-commonjs": "node commonjs-consumer.js",
 "test-esm": "node esm-consumer.mjs",
 "test-esm-multiple": "node esm-consumer-multiple.mjs"
 },
 "devDependencies": {
 "webpack": "^5.89.0",
 "webpack-cli": "^5.1.4"
 }
}

npm install 명령으로 패키지를 설치하고, 다음과 같이 webpack을 설정합니다.

//tree-shaking/webpack.config.cjs
const path = require("path");

module.exports = {
 mode: "production", // tree-shaking을 포함한 최적화 활성화
 entry: {
 "commonjs-bundle": "./commonjs-consumer.cjs",
 "esm-bundle": "./esm-consumer.mjs",
 },
 output: {
 path: path.resolve(__dirname, "dist"),
 filename: "[name].js",
 clean: true,
 },
 optimization: {
 usedExports: true, // tree-shaking 활성화
 sideEffects: false,
 },
 resolve: {
 extensions: [".js", ".mjs"],
 },
 module: {
 rules: [
 {
 test: /\.mjs$/,
 type: "javascript/esm",
 },
 ],
 },
};

이제 webpack을 통해 번들링할 commonjs-consumer.cjs와 esm-consumer.mjs 파일, 그리고 각 파일에서 임포트할 유틸 모듈을 작성합니다.

우선 CommonJS 파일들 부터 작성합니다.

// tree-shaking/large-utils.cjs (CommonJS)
console.log("large-utils.js 로딩 중 - 모든 함수가 로드됩니다!");

// 수학 함수들
function add(a, b) {
 console.log("add 함수 호출됨");
 return a + b;
}

function subtract(a, b) {
 console.log("subtract 함수 호출됨");
 return a - b;
}

function multiply(a, b) {
 console.log("multiply 함수 호출됨");
 return a * b;
}

function divide(a, b) {
 console.log("divide 함수 호출됨");
 return a / b;
}

function power(a, b) {
 console.log("power 함수 호출됨");
 return Math.pow(a, b);
}

// 문자열 함수들
function capitalize(str) {
 console.log("capitalize 함수 호출됨");
 return str.charAt(0).toUpperCase() + str.slice(1);
}

function reverse(str) {
 console.log("reverse 함수 호출됨");
 return str.split("").reverse().join("");
}

function truncate(str, length) {
 console.log("truncate 함수 호출됨");
 return str.length > length ? str.substring(0, length) + "..." : str;
}

// 배열 함수들
function sortArray(arr) {
 console.log("sortArray 함수 호출됨");
 return [...arr].sort();
}

function filterEven(arr) {
 console.log("filterEven 함수 호출됨");
 return arr.filter((num) => num % 2 === 0);
}

function sum(arr) {
 console.log("sum 함수 호출됨");
 return arr.reduce((total, num) => total + num, 0);
}

// 복잡한 유틸리티 함수들
function complexCalculation() {
 console.log("complexCalculation 함수 호출됨");
 let result = 0;
 for (let i = 0; i < 1000000; i++) {
 result += Math.sqrt(i);
 }
 return result;
}

function heavyStringProcessing(str) {
 console.log("heavyStringProcessing 함수 호출됨");
 return str.repeat(10000).split("").reverse().join("");
}

// 모든 함수 내보내기
module.exports = {
 add,
 subtract,
 multiply,
 divide,
 power,
 capitalize,
 reverse,
 truncate,
 sortArray,
 filterEven,
 sum,
 complexCalculation,
 heavyStringProcessing,
};

// tree-shaking/commonjs-consumer.cjs
console.log("=== CommonJS Consumer ===");
console.log("large-utils.js에서 임포트 중...");

// CommonJS는 전체 모듈을 임포트합니다
const utils = require("./large-utils.cjs");

console.log("\nadd 함수만 사용:");
console.log("결과:", utils.add(5, 3));

console.log("\n주의: 'add'만 사용하지만, 모든 함수가 로드됩니다!");
console.log("이는 CommonJS가 전체 모듈 네임스페이스를 로드하기 때문입니다.");

다음으로 ESM 파일들을 작성합니다.

// tree-shaking/large-utils.mjs (ESM)
console.log("large-utils.mjs 로딩 중");

// 수학 함수들
export function add(a, b) {
 console.log("add 함수 호출됨");
 return a + b;
}

export function subtract(a, b) {
 console.log("subtract 함수 호출됨");
 return a - b;
}

export function multiply(a, b) {
 console.log("multiply 함수 호출됨");
 return a * b;
}

export function divide(a, b) {
 console.log("divide 함수 호출됨");
 return a / b;
}

export function power(a, b) {
 console.log("power 함수 호출됨");
 return Math.pow(a, b);
}

// 문자열 함수들
export function capitalize(str) {
 console.log("capitalize 함수 호출됨");
 return str.charAt(0).toUpperCase() + str.slice(1);
}

export function reverse(str) {
 console.log("reverse 함수 호출됨");
 return str.split("").reverse().join("");
}

export function truncate(str, length) {
 console.log("truncate 함수 호출됨");
 return str.length > length ? str.substring(0, length) + "..." : str;
}

// 배열 함수들
export function sortArray(arr) {
 console.log("sortArray 함수 호출됨");
 return [...arr].sort();
}

export function filterEven(arr) {
 console.log("filterEven 함수 호출됨");
 return arr.filter((num) => num % 2 === 0);
}

export function sum(arr) {
 console.log("sum 함수 호출됨");
 return arr.reduce((total, num) => total + num, 0);
}

// 복잡한 유틸리티 함수들
export function complexCalculation() {
 console.log("complexCalculation 함수 호출됨");
 let result = 0;
 for (let i = 0; i < 1000000; i++) {
 result += Math.sqrt(i);
 }
 return result;
}

export function heavyStringProcessing(str) {
 console.log("heavyStringProcessing 함수 호출됨");
 return str.repeat(10000).split("").reverse().join("");
}

// tree-shaking/esm-consumer.mjs
console.log("=== ESM Consumer ===");
console.log("large-utils.mjs에서 임포트 중...");

// ESM은 특정 함수만 임포트합니다
import { add } from "./large-utils.mjs";

console.log("\nadd 함수만 사용:");
console.log("결과:", add(5, 3));

console.log("\n주의: 'add' 함수만 임포트됩니다!");
console.log("다른 함수들은 이 모듈의 범위에 포함되지 않습니다.");

ESM의 경우 CommonJS와 다르게 add 함수만 임포트하고 있습니다. 이 코드를 빌드하고, 빌드된 파일의 크기를 확인해보겠습니다.

> npm run build
> tree-shaking-demo@1.0.0 build
> webpack

asset commonjs-bundle.js 1.79 KiB [emitted] [minimized] (name: commonjs-bundle)
asset esm-bundle.js 404 bytes [emitted] [minimized] (name: esm-bundle)
orphan modules 1.73 KiB [orphan] 1 module
modules by path ./*.cjs 2.41 KiB
 ./commonjs-consumer.cjs 528 bytes [built] [code generated]
 ./large-utils.cjs 1.89 KiB [built] [code generated]
./esm-consumer.mjs + 1 modules 2.14 KiB [built] [code generated]
webpack 5.100.0 compiled successfully in 216 ms

> ls -lh ./dist
total 16
-rw-r--r--@ 1 onlifecoding staff 1.8K Jul 12 09:26 commonjs-bundle.js
-rw-r--r--@ 1 onlifecoding staff 404B Jul 12 09:26 esm-bundle.js

📊 번들 크기 비교

빌드된 파일 크기에 확인할 수 있듯이 esm 번들은 404B로 1.8KB에 비해 약 22% 수준입니다.

xychart-beta
title "번들 크기 비교 (Bytes)"
x-axis [CommonJS, ESM]
y-axis "크기 (Bytes)" 0 --> 2000
bar [1792, 404]

크기 절약 효과:

CommonJS 번들: 1,792 bytes (100%)
ESM 번들: 404 bytes (22.5%)
절약된 크기: 1,388 bytes (77.5% 감소!)

이렇게 간단한 예제에서도 tree-shaking을 통해 번들 파일의 크기를 꽤 줄일 수 있었는데 큰 프로젝트에서는 더 큰 차이가 나겠죠?

🌳 Tree-shaking 작동 원리

graph TB
subgraph "CommonJS (Tree-shaking 불가)"
A1[large-utils.cjs] --> B1[모든 함수 포함]
B1 --> C1[add, subtract, multiply, divide, ...]
C1 --> D1[번들: 1.8KB]
D1 --> E1[사용하지 않는 함수도 포함]
end

graph TB
subgraph "ESM (Tree-shaking 가능)"
A2[large-utils.mjs] --> B2[정적 분석]
B2 --> C2[사용되는 함수만 선택]
C2 --> D2[add 함수만]
D2 --> E2[번들: 404B]
E2 --> F2[78% 크기 감소!]
end

Node.js 22의 새로운 기능

require()ing Synchronous ESM Graphs

ESM이 가야할 방향인 건 분명하지만 문제는 ESM이 표준으로 제시되기까지 너무 오랜 시간이 걸렸고, CommonJS를 사용하는 레거시 코드가 너무나도 많다는 겁니다.

그러면 핵심 라이브러리가 ESM만을 지원하도록 변경된다면 어떻게 해야 될까요? 프로젝트를 ESM으로 마이그레이션 해야겠지만, 이건 그렇게 쉬운 일이 아닙니다. 그래서 Node.js 22에서는 require()ing Synchronous ESM Graphs라는 기능을 제공합니다.

즉, 동기적으로 해석가능한 ESM 그래프를 require를 통해 임포트할 수 있게 해주겠다는 겁니다! 이 기능을 사용하면 레거시 코드를 최소한으로 변경하면서 ESM으로 마이그레이션 할 수 있게 됩니다.

제한사항

주의할 점이 있다면 동기적으로 해석가능한에 주목해야 합니다. 만약 임포트해야 할 모듈에서 top-level await를 사용하고 있다면 이 기능을 사용할 수 없습니다.

🔀 Node.js 22 ESM require() 결정 트리

flowchart TD
A[ESM 모듈을 require로 임포트] --> B{Node.js 22+?}
B -->|No| C[❌ 불가능<br/>ESM을 require할 수 없음]
B -->|Yes| D{top-level await 사용?}
D -->|Yes| E[❌ 불가능<br/>ERR_REQUIRE_ASYNC_MODULE]
D -->|No| F[✅ 가능<br/>require로 ESM 임포트]
E --> G[대안: import 사용]
F --> H[레거시 코드 마이그레이션 용이]
style C fill:#ffcccc
style E fill:#ffcccc
style F fill:#ccffcc
style G fill:#ffffcc
style H fill:#ccffcc

Node.js 22 실습 예제

그럼 예시를 볼까요?

우선 top-level await를 사용하는 ESM 모듈과 사용하지 않는 ESM 모듈을 작성해 보겠습니다.

// require-esm/async-math.mjs
console.log("async-math.mjs 로딩 중 (최상위 await가 있는 ESM)");

// 이 최상위 await는 require()가 작동하지 않게 합니다
const config = await Promise.resolve({ multiplier: 2 });

export function calculate(x, y) {
 return x * y * config.multiplier;
}

export const version = "1.0.0";

// require-esm/math.mjs
console.log("math.mjs 로딩 중 (ESM)");

export function add(a, b) {
 return a + b;
}

export function multiply(a, b) {
 return a * b;
}

export const PI = 3.14159;

export default function calculate(x, y) {
 return x * y + PI;
}

이제 모듈을 로드해볼까요?

// require-esm/test-node22-feature.js
console.log("=== Node.js 22 require(ESM) 기능 테스트 ===");
console.log("Node.js 버전:", process.version);

// 기능이 사용 가능한지 확인
if (process.features && process.features.require_module) {
 console.log("✅ require(ESM) 기능이 사용 가능합니다");
} else {
 console.log("❌ require(ESM) 기능이 사용 불가능합니다");
 console.log("다음과 같은 이유일 수 있습니다:");
 console.log("1. Node.js 22+ 버전을 사용하지 않는 경우");
 console.log("2. --experimental-require-module 플래그를 활성화해야 하는 경우");
}

console.log("\n" + "=".repeat(50));

// 테스트 1: 일반 CommonJS require
console.log("\n테스트 1: 일반 CommonJS 모듈");
try {
 const regularModule = require("./math.mjs");
 console.log("✅ ESM 모듈 require 성공");
 console.log("결과 타입:", typeof regularModule);
 console.log("사용 가능한 익스포트:", Object.keys(regularModule));
} catch (error) {
 console.log("❌ ESM 모듈 require 실패");
 console.log("오류:", error.code || error.message);
}

console.log("\n" + "=".repeat(50));

// 테스트 2: 최상위 await가 있는 ESM
console.log("\n테스트 2: 최상위 await가 있는 ESM");
try {
 const asyncModule = require("./async-math.mjs");
 console.log("✅ 이것은 작동하지 않아야 합니다!");
} catch (error) {
 console.log(
 "❌ 예상된 실패 - 최상위 await가 있는 ESM은 require할 수 없습니다"
 );
 console.log("오류:", error.code || error.message);
}

console.log("\n" + "=".repeat(50));

// 테스트 3: ESM import
console.log("\n테스트 3: 최상위 await가 있는 ESM import");
(async () => {
 try {
 const asyncModule = await import("./async-math.mjs");
 console.log("✅ ESM 모듈 import 성공");
 console.log("결과 타입:", typeof asyncModule);
 console.log("사용 가능한 익스포트:", Object.keys(asyncModule));
 } catch (error) {
 console.log("❌ 비동기 import로 ESM import 실패");
 console.log("오류:", error.code || error.message);
 }
})();

이 코드를 다음과 같이 진행됩니다.

먼저 노드 버전을 통해 동기적으로 해석가능한 ESM 그래프가 require()를 통해 임포트 가능한지 확인합니다.
top-level await를 사용하지 않는 ESM 모듈을 require()를 통해 임포트 합니다. 임포트가 성공해야 합니다.
top-level await를 사용하는 ESM 모듈을 require()를 통해 임포트 합니다. 임포트가 실패해야 합니다.
비동기 import를 통해 top-level await를 사용하는 ESM 모듈을 임포트 합니다. 임포트가 성공해야 합니다.

결과를 확인해볼까요?

> node require-esm/test-node22-feature.js
=== Node.js 22 require(ESM) 기능 테스트 ===
Node.js 버전: v22.14.0
✅ require(ESM) 기능이 사용 가능합니다

==================================================

테스트 1: 일반 CommonJS 모듈
math.mjs 로딩 중 (ESM)
✅ ESM 모듈 require 성공
결과 타입: object
사용 가능한 익스포트: [ 'PI', '__esModule', 'add', 'default', 'multiply' ]

==================================================

테스트 2: 최상위 await가 있는 ESM
❌ 예상된 실패 - 최상위 await가 있는 ESM은 require할 수 없습니다
오류: ERR_REQUIRE_ASYNC_MODULE

==================================================

테스트 3: 최상위 await가 있는 ESM import
async-math.mjs 로딩 중 (최상위 await가 있는 ESM)
✅ ESM 모듈 import 성공
결과 타입: object
사용 가능한 익스포트: [ 'calculate', 'version' ]

앞서 설명 드렸던 대로 top-level await를 사용하지 않는 ESM 모듈은 require()를 통해 임포트가 가능합니다. 하지만 top-level await를 사용하는 ESM 모듈은 require()로 임포트할 수 없으므로 async import를 사용해야 합니다.

실제 프로젝트 적용 사례

제가 개발 중 실제로 겪었던 사례를 소개해드리겠습니다.

🚨 문제 상황: ESM 전용 라이브러리 사용 시 require() 불가능

기존 기능을 k8s 기반으로 전환하기 위해 프로토타이핑을 진행하고 있었습니다. 그런데 코드를 실행하자 다음과 같은 에러가 발생했습니다.

⠋ TSC Initializing type checker.../dist/some/services/kubernetes-job.service.js:315
 mountPath: '/workspace'
 ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /node_modules/@kubernetes/client-node/dist/index.js from /some/services/kubernetes-job.service.js not supported.
Instead change the require of index.js in /dist/some/services/kubernetes-job.service.js to a dynamic import() which is available in all CommonJS modules.
 at TracingChannel.traceSync (node:diagnostics_channel:315:14)
 at Object.<anonymous> (/dist/some/services/kubernetes-job.service.js:12:61) {
 code: 'ERR_REQUIRE_ESM'
}

문제를 찾다보니, tsconfig.json 설정이 "module": "commonjs" 였고 kubernetes-client 라이브러리가 1.0 버전 부터 ESM 전용으로 변경 되었기 때문이었습니다! 게다가 node.js 버전 역시 22.11.0 이었습니다. require(esm)은 node.js 22.12.0 부터 기본적으로 활성화 되었으며, node.js 22.11.0 이하에서는 --experimental-require-module 플래그를 추가해야 합니다.

📋 상황 분석

graph TB
subgraph "문제 발생 환경"
A[TypeScript 프로젝트] --> B[tsconfig.json<br/>module: commonjs]
B --> C[빌드된 JS<br/>CommonJS 형태]
C --> D[kubernetes/client-node<br/>1.0.0+ ESM 전용]
D --> E[❌ ERR_REQUIRE_ESM]
end

graph TB
subgraph "라이브러리 변경사항"
F[kubernetes/client-node 0.x] --> G[CommonJS 지원]
F --> H[kubernetes/client-node 1.0+] --> I[ESM 전용]
I --> J[require 불가능]
end

핵심 문제:

TypeScript 설정: tsconfig.json의 module 설정이 "commonjs"
라이브러리 변경: @kubernetes/client-node 1.0.0부터 ESM 전용 (릴리즈 노트)
Node.js 버전: 개발 환경의 Node.js 22.11.0에서는 기본적으로 require(ESM) 미지원. --experimental-require-module 플래그를 추가해야 합니다.

💡 해결 방법

일단 가장 간단한 해결책으로 다음과 같이 --experimental-require-module 플래그를 추가했습니다.

// package.json
{
 "scripts": {
 "start:dev": "NODE_OPTIONS='--experimental-require-module' nest start --watch",
 "start:prod": "NODE_OPTIONS='--experimental-require-module' node dist/main.js"
 }
}

그리고 문제가 해결된 걸 확인하고, node.js 버전을 현재 최신 버전인 22.17.0 으로 업데이트 했습니다.

참고자료

Typescript: 타입 전용 import & export와 import 생략(elision)

Sat, 05 Jul 2025 01:04:20 +0000

들어가며

최근에 typescript로 간단한 테스트 프로젝트를 설정할 일이 있었습니다. 폴더를 만들고 간단한 테스트를 위해서 기존 프로젝트에서 코드를 조금씩 복사해서 테스트 프로젝트를 구성하던 중 처음 보는 lint 오류를 발견했습니다. 타입 정보로만 사용되는 import에 type을 붙여라! 는 거였죠.

최대한 간단하게 테스트를 해보려던 저는 머리가 복잡해졌죠. 아니 이게 도대체 뭔데 프로젝트 여기저기서 난리가 난걸까 하고 말이죠. 그래서 일단 eslint의 룰을 해제하고 작업을 이어갔습니다.

그리고 나중에 시간이 좀 생겼을 때 관련해서 찾아보니 타입 전용 import, export 그리고 import 생략(elision)에 대해 알게 되었죠.

import 생략은 typescript가 코드를 js로 컴파일 및 변환하는 과정에서 타입 정보로만 사용되는 import를 자동으로 제거한다는 것입니다. 생각해보면, js에서는 딱히 타입을 체크하지 않으니 typescript에서 타입을 체크하기 위해 사용하는 정보가 필요없겠구나 싶긴 했지만 그렇다면 왜 굳이 import에 이게 타입을 위한 import인지 적어야 할까 하는 생각이 들었습니다.

그래서 좀 알아본 뒤, 나름 이해한 내용에 대해 잊어먹지 않기 위해 이 글을 적게 되었죠.

타입 전용(type only) import & export 란?

타입 전용 import & export는 컴파일 타임에 타입을 체크하기 위한 용도로 사용되는 import와 실제 런타임에서 사용되는 import 값들을 구분하기 위해 사용됩니다. 기존 import, export에 type을 붙여서 import type, export type 으로 사용합니다.

// 타입 전용 import
import type { User, Status } from "./types";

// 타입 전용 export
export type { User, Status };

// 혼합된 import (TypeScript 4.5+)
import { type User, api, config } from "./module";

// 타입 전용 import로 가져온 타입을 다시 타입 전용 export로 내보내기
export type { User } from "./user";

여기서 가장 중요한 점은 import type으로 가져온 타입 관련 코드는 컴파일 과정에서 완전히 사라진다는 겁니다. 다음과 같이 테스트해볼 수 있습니다.

우선 ex1/types.ts 파일에 간단한 타입을 하나 작성합니다.

export interface User {
 name: string;
 age: number;
}

그리고 ex1/main.ts 파일에서 위에서 작성한 타입을 사용합니다.

import { type User } from "./types";

// 여기서 User는 컴파일 타임의 타입 체크 용도로만 사용되고 있습니다.
const user: User = {
 name: "John",
 age: 30,
};

console.log(user);

이제 npx tsc 명령어를 통해 컴파일을 하고 dist/type-only-import/ex1/main.js 파일을 확인해보면 다음과 같이 타입 정보로만 사용되는 import가 제거된 것을 확인할 수 있습니다.

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
// 여기서 User는 컴파일 타임의 타입 체크 용도로만 사용되고 있습니다.
const user = {
 name: "John",
 age: 30,
};
console.log(user);

왜 이게 중요한가요?

큰 프로젝트를 빌드하다보면, 모듈 간의 의존성이 복잡해집니다. 어디서 뭘 export하고 import 하는지가 명확하지 않고 외부 라이브러리 까지 복잡하게 얽히면 파악하기 더 어려워집니다. 그리고 빌드 및 번들링과정을 거치면 파일 크기가 커지고 빌드도 오래걸리며, 앱이 실행될 때 덩치가 큰 파일을 로드해야 하니까 메모리 사용도 늘어납니다.

그런데 타입 전용 import & export를 사용하면 컴파일 타임에 타입 정보로만 사용되는 import를 제거하고, 런타임에는 필요한 값들만 남기기 때문에 빌드 시간과 메모리 사용량을 줄일 수 있습니다.

게다가 이해하기 힘든 순환 참조, 사이드 이펙트 등의 오류도 방지할 수 있습니다.

순환 참조 오류

// src/ex2/a.ts
import { B } from "./b";

export class A {
 b: B;
 constructor() {
 this.b = new B();
 console.log("A created");
 }
}

// src/ex2/b.ts
import { A } from "./a";

export class B {
 a: A;
 constructor() {
 this.a = new A();
 console.log("B created");
 }
}

// src/ex2/main.ts
import { A } from "./a";

const a = new A();

위 예제를 빌드 후 node dist/type-only-import/ex2/main.js 명령어를 통해 실행해보면 다음과 같은 오류가 발생합니다.

/Users/onlifecoding/src/test/typescript-studies/dist/type-only-import/ex2/b.js:7
 this.a = new a_1.A();
 ^

RangeError: Maximum call stack size exceeded
 at new B (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/b.js:7:9)
 at new A (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/a.js:7:18)
 at new B (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/b.js:7:18)
 at new A (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/a.js:7:18)
 at new B (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/b.js:7:18)
 at new A (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/a.js:7:18)
 at new B (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/b.js:7:18)
 at new A (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/a.js:7:18)
 at new B (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/b.js:7:18)
 at new A (/Users/onlifecoding/src/test/typescript-studies/dist/ex2/a.js:7:18)

Node.js v22.14.0

클래스 A, B가 각각 타입으로 상대방을 참조하고 있기 때문에 순환참조 오류가 발생합니다. 위 코드에서 타입 전용 import를 사용해볼까요?

// src/ex2/a.ts
import type { B } from "./b";

export class A {
 b: B | undefined;
 constructor() {
 //this.b = new B(); <- 값이 아닌 타입으로만 사용하도록 변경 했습니다.
 console.log("A created");
 }
}

// src/ex2/b.ts
import type { A } from "./a";

export class B {
 a: A | undefined;
 constructor() {
 //this.a = new A(); <- 값이 아닌 타입으로만 사용하도록 변경 했습니다.
 console.log("B created");
 }
}

이제 다시 빌드 후 실행하면 오류가 발생하지 않습니다.

사이드 이펙트 오류

타입 전용 import는 컴파일 과정에서 완전 제거 되기 때문에 import로 인한 예상하지 못한 동작을 방지할 수 있습니다.

// analytics.ts
console.log("Analytics module loaded!"); // 모듈이 로드될 때 실행될 console.log

export interface TrackingEvent {
 name: string;
 data: Record<string, any>;
}

// main.ts
// 타입 전용 import는 console.log가 실행되지 않습니다.
import type { TrackingEvent } from "./analytics";

// 타입과 사이드 이펙트 모두 필요할 때는 따로 명시해줘야 합니다.
import type { TrackingEvent } from "./analytics";
import "./analytics"; // 사이드 이펙트 발생

타입 전용 import & export 사용 시 주의사항

코드 가독성을 위한 구조화

다음과 같이 같은 파일에서 import하더라도 타입 전용 import와 런타임에 값으로 사용되는 import를 명확하게 구분하는 게 좋습니다.

// 타입 전용 import
import type { ComponentProps } from "./components";

// 런타임에 사용되는 import
import { Button, Modal } from "./components";

isolatedModules 옵션 사용시 type 전용 export 사용

Babel, SWC등의 빌드 툴을 사용하는 경우 전체 프로젝트를 한 번에 분석하지 않기 때문에 각 파일이 독립적으로 transpile 될 수 있도록 isolatedModules 옵션을 사용합니다. 이 옵션을 사용할 때는 type 전용 export를 사용해서 타입 정보를 내보내야 합니다.

// 잘못된 방식 - isolatedModules에서 컴파일 에러
export { User } from "./user";
export { Post } from "./post";

// 올바른 방식
export type { User } from "./user";
export type { Post } from "./post";

verbatimModuleSyntax 옵션 사용

tsconfig.json에서 verbatimModuleSyntax 옵션을 사용하면 다음과 같이 타입 전용 import, export의 사용 규칙이 명확해집니다.

타입 전용 import, export는 빌드 과정에서 완전히 제거됩니다.
type 키워드가 사용되지 않은 import, export는 빌드 후에도 유지됩니다.
typescript가 import에 대해서 타입으로 사용되는지 아닌지 검사하지 않도록 합니다. 따라서 typescript가 자동으로 수행하던 import 생략(elision)을 수행하지 않습니다.

참고 자료

Cursor와 MCP를 활용한 프로젝트 설정

Sat, 24 May 2025 09:36:07 +0900

앉아봐라 그 시절에는 말이야…

2000년대 까지만 하더라도 꼭꼭 숨어있는 정보를 찾아내는 게 능력이었습니다. 구글에서 적절하게 검색어를 넣고 자료를 뒤지면서 남들보다 더 많은 정보를 빠르게 찾는 나름의 방법을 익혀나갔죠. 외국에서 공부하고 왔던 한 개발자에게 구글에서 “xxx"에 대해서 검색해보라고 했더니 정말 검색창에 “xxx"만 입력하는 걸 보고 경악했던 일도 있었습니다. 그 당시 구글은 대화 상대도 아니었고 그저 정보를 찾기 위한 검색툴에 불과했으니 툴을 사용해보지 않은 사람들은 사용이 어려웠던 겁니다.

그런데 ChatGPT를 기점으로 시대가 많이 변하더니 이젠 변화의 속도가 점점 가속화 되어 잠시만 눈을 떼면 따라잡기가 어렵다는 느낌이 듭니다. 심지어 이러다가 뒤쳐지는 정도가 아니라 아예 쓸모없어지는게 아닌가 하는 공포마저 들게 됩니다. 별 수 있나요… 최소한 이런 발전에 뒤쳐지지만 말자고 생각하고 노력하는 수 밖에 없죠!

MCP가 정말 좋다며? 근데…

최근에는 MCP나 A2A 같이 에이전트의 활용에 대한 내용들이 많이 나오는 거 같습니다. A2A는 에이전트 간의 협업에 대한 거고, MCP는 에이전트가 활용할 수 있는 툴에 대한 거니까 범위는 다르지만 어쨌건 에이전트 시대에 에이전트를 좀 더 잘 활용할 수 있는 시대로 변화하고 있음은 분명합니다. 세상은 돌고 도는 거라 2000년대 초반에 SOAP를 기반으로 한 웹서비스의 느낌이 들기도 합니다만 어쨌건 구조가 비슷하게 느껴질 뿐 하는 일은 천지차이죠.

MCP에 대해 사람들이 이야기 하는 걸 들어보면 분명 엄청난 프로토콜은 맞습니다만, 저와는 상관이 없어보였습니다. 피그마에서 디자인한 내용을 MCP를 통해 프론트까지 구현한다던지 하는 건 분명 대단하지만, 저는 피그마를 사용하지 않기 때문에 “아 저게 어떤 상황에서는 미친 생산성이 나오겠구나"하는 정도였죠. 근데 진짜 누구에게나 사용가능한 미친 MCP를 발견했습니다. 아니, 이미 존재하고 있었지만 조합해보니 대단했던 거죠.

Context7과 Sequential Thinking

Context7 은 AI를 사용하는 데 있어 가장 중요한 부분인 context의 문제를 해결해줍니다. AI를 학습된 내용을 바탕으로 코드나 답변을 생성하기 때문에 뭔가 최신으로 업데이트된 내용은 제대로 고려하지 못합니다. Context7은 주요 프레임워크나 SDK등의 사용법을 주요 언어 및 환경 별로 어떻게 사용해야 하는지 등을 정리해서 모아놓은 사이트이고, Context7 MCP는 에이전트가 이러한 내용을 자율적으로 검색해서 구현이나 답변에 참고할 수 있도록 해줍니다. 최신 정보를 에이전트가 알아서 가져다 쓸 수 있다는 거죠!

그리고 Sequential Thinking MCP Server 는 에이전트가 사용자의 요청을 받았을 때, 구조화된 사고 과정을 거쳐서 큰 문제를 작게 쪼개고 더 나은 방법을 찾기 위해서 자신의 사고를 검증 하는 등 에이전트의 문제 해결력을 더 높여주는 MCP입니다. 이 MCP는 단독으로 사용해도 큰 효과를 주지만 Context7이랑 합치면 더 시너지가 납니다!

직접 해보자.

우선 개발 동생님의 Context7 소개 영상 을 보면, 두 MCP를 활용해서 아주 간단한 사칙연산을 하는 MCP 서버를 만드는 과정을 보여줍니다. 저도 한 번 따라해봤습니다. 와 정말 대박이었습니다. 이 간단한 과정을 통해서 실제 동작하는 MCP 서버를 만들 수 있다니! 이렇게 함으로써 저는 typescript를 이용해서 MCP 서버를 어떻게 만들어야 하는지 한 번에 이해할 수 있었습니다.

그리고 실제 업무나 개인적으로 스터디할 때 이 MCP를 적극활용하기 시작했습니다. 효과는 정말 대단했습니다. 그 중에 개인 스터디를 위해 준비했던 내용을 공유해보겠습니다.

어떤 상황이냐

최근에 mongodb에 대해서(특히 aggregation pipeline) 한 번 정리하고 싶은 마음이 생겨서 에제 코드를 작성해보고자 했습니다. 그래서 ChatGPT를 통해 기본 구조를 뽑아냈죠. 학생과 선생님 collection이 있는 구조를 설명해주고 초기 데이터를 구성하는 seed 코드를 다음과 같이 생성했습니다.

// seed.js
// Node.js MongoDB seed script for students and teachers collections

const { MongoClient, ObjectId } = require("mongodb");
const faker = require("faker");

// Configuration
const MONGO_URI = process.env.MONGO_URI || "mongodb://localhost:27017";
const DB_NAME = process.env.DB_NAME || "school";

// Constants
const GRADES = [1, 2, 3, 4, 5, 6];
const CLASSES = ["A", "B"];

// Utility to generate random scores array
function generateScores() {
 const count = faker.datatype.number({ min: 3, max: 5 });
 return Array.from({ length: count }).map(() => ({
 math: faker.datatype.number({ min: 40, max: 100 }),
 english: faker.datatype.number({ min: 40, max: 100 }),
 coding: faker.datatype.number({ min: 40, max: 100 }),
 }));
}

async function seed() {
 const client = new MongoClient(MONGO_URI, { useUnifiedTopology: true });
 try {
 await client.connect();
 const db = client.db(DB_NAME);

 // Clear existing data
 await db.collection("students").deleteMany({});
 await db.collection("teachers").deleteMany({});

 // Generate students
 const students = [];
 GRADES.forEach((grade) => {
 CLASSES.forEach((cls) => {
 const className = `${grade}-${cls}`;
 for (let i = 0; i < 18; i++) {
 students.push({
 _id: new ObjectId(),
 name: faker.name.findName(),
 grade,
 class: className,
 scores: generateScores(),
 });
 }
 });
 });

 // Generate teachers
 const teachers = [];
 GRADES.forEach((grade) => {
 CLASSES.forEach((cls) => {
 const className = `${grade}-${cls}`;
 teachers.push({
 _id: new ObjectId(),
 name: faker.name.findName(),
 grade,
 class: className,
 });
 });
 });

 // Insert seed data
 const studentResult = await db.collection("students").insertMany(students);
 const teacherResult = await db.collection("teachers").insertMany(teachers);

 console.log(`Inserted ${studentResult.insertedCount} students`);
 console.log(`Inserted ${teacherResult.insertedCount} teachers`);
 console.log("Seeding completed successfully.");
 } catch (err) {
 console.error("Error during seeding:", err);
 } finally {
 await client.close();
 }
}

seed();

이 코드가 아주 정확하냐 뭐 그런건 그렇게 중요하진 않았습니다. 나중에 수정하면 되니까요. 그리고 빈 폴더를 하나 만들고 Cursor를 열고 다음과 같이 요청했습니다. 사용된 모델은 Cluade 3.7 Sonnet 입니다.

i need to create node.js app for studying mongodb aggregation pipeline.
so i need to create basic project structure and seed script using mongodb node.js driver.

use context7 for looking for how to use node.js mongodb driver.

use sequantial thinking mcp to plan how to create basic project structure and seeding mongodb collestion.
here's starter seed script:

// seed.js
// Node.js MongoDB seed script for students and teachers collections

const { MongoClient, ObjectId } = require('mongodb');
const faker = require('faker');

// Configuration
const MONGO_URI = process.env.MONGO_URI || 'mongodb://localhost:27017';
const DB_NAME = process.env.DB_NAME || 'school';

// Constants
const GRADES = [1, 2, 3, 4, 5, 6];
const CLASSES = ['A', 'B'];

// Utility to generate random scores array
function generateScores() {
 const count = faker.datatype.number({ min: 3, max: 5 });
 return Array.from({ length: count }).map(() => ({
 math: faker.datatype.number({ min: 40, max: 100 }),
 english: faker.datatype.number({ min: 40, max: 100 }),
 coding: faker.datatype.number({ min: 40, max: 100 })
 }));
}

async function seed() {
 const client = new MongoClient(MONGO_URI, { useUnifiedTopology: true });
 try {
 await client.connect();
 const db = client.db(DB_NAME);

 // Clear existing data
 await db.collection('students').deleteMany({});
 await db.collection('teachers').deleteMany({});

 // Generate students
 const students = [];
 GRADES.forEach(grade => {
 CLASSES.forEach(cls => {
 const className = `${grade}-${cls}`;
 for (let i = 0; i < 18; i++) {
 students.push({
 _id: new ObjectId(),
 name: faker.name.findName(),
 grade,
 class: className,
 scores: generateScores()
 });
 }
 });
 });

 // Generate teachers
 const teachers = [];
 GRADES.forEach(grade => {
 CLASSES.forEach(cls => {
 const className = `${grade}-${cls}`;
 teachers.push({
 _id: new ObjectId(),
 name: faker.name.findName(),
 grade,
 class: className
 });
 });
 });

 // Insert seed data
 const studentResult = await db.collection('students').insertMany(students);
 const teacherResult = await db.collection('teachers').insertMany(teachers);

 console.log(`Inserted ${studentResult.insertedCount} students`);
 console.log(`Inserted ${teacherResult.insertedCount} teachers`);
 console.log('Seeding completed successfully.');
 } catch (err) {
 console.error('Error during seeding:', err);
 } finally {
 await client.close();
 }
}

seed();

Context7 MCP를 통해 mongodb 드라이버의 사용법을 참고하고, Sequential Thinking MCP를 어떻게 작업할지 구상해보라고 했습니다. 그러자 에이전트가 MCP를 호출하기 시작합니다.

mongodb와 node.js driver 연결방법, 그리고 aggregation pipeline 사용법을 참고하고 있네요!

그리고 최종적으로 다음과 같이 정리해줍니다.

I've created a complete Node.js project for studying MongoDB aggregation pipelines. Here's what I've set up:

### Project Structure

mongodb-aggregation-study/
├── package.json # Dependencies and npm scripts
├── .gitignore # Git ignore file
├── README.md # Project documentation
└── src/
├── config/
│ └── db.js # MongoDB connection configuration
├── examples/
│ ├── basic.js # Basic aggregation examples
│ └── advanced.js # Advanced aggregation examples
├── index.js # Main application entry point
└── scripts/
└── seed.js # Database seeding script

### Key Features

1. **Database Configuration**: A reusable MongoDB connection module in `db.js`

2. **Seed Script**: Updated version of your script using `@faker-js/faker` to populate the database with students and teachers data

3. **Aggregation Examples**:

 - **Basic**: Simple examples using $match, $group, $project, and $lookup
 - **Advanced**: Complex examples with $expr, $bucket, $reduce, and $facet

4. **NPM Scripts**:
 - `npm run seed` - Populate the database
 - `npm run example:basic` - Run basic aggregation examples
 - `npm run example:advanced` - Run advanced aggregation examples
 - `npm start` - Run the main application

### Getting Started

To use this project:

1. Ensure MongoDB is running locally (or update the connection URI in your environment)
2. Install dependencies with `npm install`
3. Run `npm run seed` to populate the database
4. Try the examples with `npm run example:basic` or `npm run example:advanced`

The project provides a practical environment for learning and experimenting with MongoDB's powerful aggregation pipeline features.

mongodb-aggregation-study/
├── package.json # Dependencies and npm scripts
├── .gitignore # Git ignore file
├── README.md # Project documentation
└── src/
├── config/
│ └── db.js # MongoDB connection configuration
├── examples/
│ ├── basic.js # Basic aggregation examples
│ └── advanced.js # Advanced aggregation examples
├── index.js # Main application entry point
└── scripts/
└── seed.js # Database seeding script

딱히 제가 요청하지 않았던 프로젝트 구조와 기초 및 고급 예제, 그리고 커맨드 까지 생성해서 알려줍니다!

이번엔 mongodb를 도커로 실행하는 방법을 요청해보겠습니다. 이번에도 context7 MCP를 통해 사용법을 참고하라고 알려줍니다.

very well! i need to run mongodb using docker on local. can you add instruction in @README.md for this?

use context7 if you need to reference how to do it

그러자 이렇게 답변해줍니다.

Here are clear instructions you can add to your `README.md` for running MongoDB locally using Docker. This is the most common and recommended way for local development, and it will work cross-platform.

---

## Running MongoDB Locally with Docker

If you don't have MongoDB installed on your machine, you can easily run it using Docker:

docker run --name mongodb-aggregation-study -d -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=mongo -e MONGO_INITDB_ROOT_PASSWORD=mongo mongo:latest

- This command will:
 - Pull the latest MongoDB image if you don't have it.
 - Start a MongoDB server in a container named `mongodb-aggregation-study`.
 - Expose MongoDB on the default port `27017`.
 - Set the root username and password to `mongo` (you can change these if you want).

### Connecting from your app

- By default, your `.env` should use:

 MONGO_URI=mongodb://localhost:27017
 DB_NAME=school

- If you want to use authentication, update your `.env`:

 MONGO_URI=mongodb://mongo:mongo@localhost:27017
 DB_NAME=school

 And make sure your MongoDB connection code supports authentication.

### Stopping and Removing the Container

To stop MongoDB:

docker stop mongodb-aggregation-study

To remove the container:

docker rm mongodb-aggregation-study

그리고 데이터 구조에 변경이 필요해서, 구조를 변경함과 동시에 예제로 같이 수정해달라고 요청했습니다.

currently @generateScores() generate randomly 3-5 scores for math, english, coding. but let's update this to:
{
 mid: { math, english, coding },
 final: { math, english, coding }
}

and update example aggregations if needed.

그러면 예제까지 싹 다 고쳐줍니다! 물론 중간 중간에 .env의 호출이 빠져서 환경 변수를 못읽어오는 바람에 mongodb에 접속이 안된다던지 하는 사소한 문제가 있긴 했지만요.

AI 시대는 일하는 방법이 다르구나!

AI를 개발에 활용한지 2년이 다 되어가는데, 너무 많이 부족합니다. 그만큼 AI의 발전이 빠르다는 말이겠죠. 최근에는 그냥 자연어 기반으로 에이전트를 백그라운드에서 굴리는 OpenAI Codex나 Claude Code 등이 새로운 개발 트렌드로 떠오르는 거 같습니다. 이렇게 되면 에이전트를 여러 개 굴리면서 그냥 말로만 코딩하는 시대가 될 거 같기도 한데요… 아직 돈이 없어서 이런 툴들을 써보진 못했습니다. 조만간에 기회가 있으면 시도해봐야죠. 적어도 뒤쳐지지는 말아야죠!

patch-package로 패키지 커스터마이즈하기

Sat, 10 May 2025 08:45:21 +0900

react와 같이 node.js 기반으로 개발하다보면, 여러 패키지를 설치해서 사용하게 됩니다. 그리고 그러다 보면, 기존 패키지의 코드를 수정해서 사용해야 하는 경우가 생깁니다! 이럴 때는 어떻게 해야 할까요?

미련했던 옛 시절

현재 작업 중인 프로젝트에서는 webrtc 기반으로 코드 에디터의 내용을 동기화 하는 기능을 구현했었습니다. 그러다 보니 오픈소스 패키지를 사용하다가 필요한 기능을 넣기 위해 패키지를 수정할 필요가 있었죠. 그래서 고민하다가… node_modules 폴더에서 해당 패키지의 소스 코드를 찾아서 그걸 /src/lib 폴더에 복사해두고 직접 수정했습니다! 그리곤 설치된 패키지를 import 하는 대신에 /src/lib에 복사해서 수정한 파일을 import 하는 방식으로 구현했죠.

물론 이 방법에도 장점은 있습니다. 간단하죠! 그리고 디버깅도 쉽습니다. 코드가 내 프로젝트 안에 있으니까요. 그런데 이 작업을 할 당시에도 "나중에 시간이 좀 지나서 패키지를 업데이트해야 되면, 일일이 변경점을 찾아서 수정해야 되나...?" 하는 불안감은 있었지만 그런 걸 생각할 여유가 아예 없었기 때문에 그냥 그대로 뒀습니다.

기술적 부채는 결국 돌아온다!

그렇게 대충 마무리를 하고 2년이 지났고, 그 프로젝트를 다시 들여다 보고 있었습니다. 어떻게든 회사가 죽지 않고 버티다 보면 신기하게도 이미 수명이 끝났다고 생각했던 솔루션이 다시 부활하게 되는 순간이 오곤 합니다. 네, 지금이 그런 순간이었던 거죠. 거의 포기했던 솔루션을 다시 봐야 하는 상황인거죠. 개발자라면 이때의 막막한 심정을 공감하실 겁니다. 본인이 막대한 노력을 들여서 일을 장황하게 벌여놨지만, 시간이 한참 지나서 그걸 다시 스스로 수습해야 하는 상황말이죠…

어쨌거나 그 당시에 넘쳐나던 요구사항을 쫓아가기 급급하면서 계속 새로운 기능을 공장처럼 찍어냈고, 여러가지 사정으로 인해 그 기능들은 제대로 테스트 과정을 거치지도 못한 채 방치되었습니다. 빚을 내면서 빨리 개발했지만, 그 빚을 갚지 못하면서 이자만 눈덩이 처럼 불어난 셈이죠. 패키지 파일을 /src/lib에 복사했던 건 수 많은 부채 중의 하나였습니다.

좀 더 우아한 방법이 없을까?

이 문제에 대해 위대하신 ChatGPT님과 대화하다 보니, 여러가지 방법이 있지만 가장 간단한 건 patch-package를 활용하는 방법이라는 걸 알게되었습니다. 그러니까, node_modules/some-package/src/source.js 파일을 직접 수정하고, npx patch-package some-package 명령을 실행하면, 원래 패키지에서 변경된 점을 찾아서 patches 폴더에 기록하고 패키지를 새롭게 빌드해줍니다. patches 폴더에 기록된 내용을 들여다보면 대충 다음과 같은 내용입니다.

diff --git a/node_modules/some-package/src/source.js b/node_modules/some-package/src/source.js
index c0fc343..92a2941 100644
--- a/node_modules/some-package/src/source.js
+++ b/node_modules/some-package/src/source.js
@@ -97,6 +97,7 @@ someArray[someIndex] = (

 // @todo - blah blah some original source code
 const someVariable = 30000
+const someOtherVariable = 4000;

게다가! package.json의 scripts에 postinstall 스크립트를 추가하면, 패키지를 설치할 때마다 자동으로 패치 파일을 적용해줍니다.

"scripts": {
 ...
 "postinstall": "patch-package"
}

패키지를 새로 설치할 때 마다 수작업으로 변경사항을 적용할 필요가 없는 거죠! 다만, patch 파일 이름(some-package+0.1.6.patch) 에서도 알 수 있듯이 패키지의 버전이 바뀐다면 패치는 자동 적용되지 않습니다. 그럴 때는 다음과 같이 파일의 이름을 변경하고 다시 시도해볼 수 있습니다.

# 패키지 버전이 0.1.6에서 0.1.7로 바뀌었다고 가정해봅니다.
> cp patches/some-package+0.1.6.patch patches/some-package+0.1.7.patch
# 패치를 적용해봅니다.
> npx patch-package

만약 패키지가 업데이트 되면서 패치와 관련된 코드가 변경되었다면 패치는 실패하며 그때는 패치를 새로 만들어야 합니다. 이 방법도 만능은 아닌 셈이죠. 그래도 현 시점에서 가장 간단하면서도 우아하게 적용할 수 있는 방법이었습니다.

CRA & CRACO -> VITE 마이그레이션

Thu, 01 May 2025 08:40:44 +0900

CRA와 씨름하다

2022년 한 프로젝트를 처음 시작할 때 저는 리액트에 대해 아주 잘 알지는 못했습니다. 그렇기 때문에 공식 사이트에 나와있는 대로 CRA(Create React App)을 이용해 프로젝트를 생성했습니다. 그리고 몇 달 후, 새롭게 합류한 프론트 개발자가 그 프로젝트에 CRACO를 추가했습니다. 그 당시에는 CRA의 여러 문제점으로 인해서 eject하여 커스텀하게 설정을 하던지, CRACO나 React App Rewired같은 방법을 사용했던 걸로 기억합니다.

그리고 프로젝트가 점점 커지자 몇 가지 문제가 발생했습니다.

개발 환경의 메모리 문제 CRA가 Webpack + Babel을 사용하는데, 앱이 시작 될 때 src 폴더와 node_modules 폴더에서 임포트 되는 모든 파일을 찾아서 의존성 그래프를 생성합니다. 그리고 생성된 결과를 번들링해서 메모리에 저장하는데요, 이 과정에서 많은 메모리가 필요합니다. 프로젝트가 복잡해지고 커질수록 더 악화되겠죠! 그래서 npm run dev 명령에 NODE_OPTIONS='--max-old-space-size=4096' 옵션을 추가하여 메모리를 조금 더 사용할 수 있도록 했습니다.
빌드 시간 문제 프로젝트가 커짐에 따라 시간이 점점 더 걸리더니 결국 빌드에 10분씩 걸리는 지경에 이르렀습니다. 사소한 실수 하나를 수정하기 위해 10분이나 기다려야 하는 건 너무 비효율적이었습니다. 그래서 빌드 시간을 단축시키기 위해서 esbuild를 craco에 엮어서 사용하는 방식을 통해 어느 정도 줄일 수 있었지만 여전히 4-5분 정도의 빌드 타임이 소요되었습니다.
CRA의 지원 종료 2023년 즈음해서 사실상 React 팀에서도 CRA에 대한 지원을 조용히 그만두기로 결정했습니다. 그래서 회사에서 추가로 진행하는 프로젝트에 더 이상 CRA를 사용할 수 없는 상황이었고, 이 때문에 대안을 찾아야 했습니다.

이때쯤 부터 VITE에 대한 이야기가 더 많아졌던 것 같습니다. 몇 년전에 Vue.js 3를 처음 스터디 해볼 때 VITE라는 게 있더라 정도는 봤던 기억이 있었는데, 구체적으로 이게 뭔지는 몰랐죠. 그래서 작년 말에 새로운 프로젝트를 시작 할 때 VITE를 사용해보기로 했습니다.

VITE에 놀라다

VITE는 제 생각보다 더 훌륭했습니다. 왜 사람들이 VITE를 칭송하는지 알겠더군요!

개발 환경의 쾌적함 VITE는 앱이 시작될 때 앱 전체를 번들링 하지 않습니다. 요청되는 페이지와 관련있는 임포트만 번들링하여 제공합니다. 그러니까 엄청 빠르고, 메모리 문제도 없습니다!
빌드도 빠르다! 초기 프로젝트 생성과정에서 간단하게 SWC를 선택할 수 있고, SWC를 이용하면 빌드 시간이 매우 단축됩니다. CRA에는 없던 다른 문제가 발생하긴 했지만 그건 나중에 자세히 말씀드리죠.

왜 그동안 CRA를 가지고 씨름했었을까 하는 현타가 몰려왔지만, 어쩔 수 없었죠. VITE가 좋은지 몰랐으니까!

그래서 한동안 새 프로젝트를 작업하다보니 그 작업이 다시 돌아왔습니다. 네, 기존 프로젝트 유지보수 작업이죠. 즐거운 작업입니다. 근데 이제와서 다시 CRA를 사용하는 건 마음이 불편했습니다. 실제로도 불편했고요. 메모리 옵션을 줬음에도 불구하고 꺼지는 앱과 HMR 할 때 마다 걸리는 시간! 그래서 대충 각을 잡아보고 마이그레이션 작업을 시작했습니다.

인생은 실전이다! CRA -> VITE 마이그레이션

CRA와 craco 제거

우선 CRA와 craco를 제거합니다.

npm uninstall react-scripts @craco/craco

VITE와 필수 플러그인을 설치

다음 명령으로 VITE 및 필수 플러그인을 설치합니다.

npm install -D vite @vitejs/plugin-react-swc vite-plugin-svgr vite-tsconfig-paths @swc/core @swc/cli

vite외에 설치되는 패키지 목록은 다음과 같습니다.

@vitejs/plugin-react-swc: VITE가 React를 지원할 수 있도록 하며, SWC를 사용하여 빌드 속도를 높입니다.
vite-plugin-svgr: SVG 파일을 React 컴포넌트로 변환합니다.(추후에 왜 설치했는지 설명합니다.)
vite-tsconfig-paths: 타입스크립트 경로 별칭을 사용할 수 있도록 합니다.
@swc/core: SWC의 핵심 모듈입니다.
@swc/cli: SWC를 명령줄에서 사용할 수 있도록 합니다.

VITE 설정 파일을 생성

프로젝트의 루트 폴더에 vite.config.ts 파일을 생성하고 다음과 같이 작성합니다.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import tsconfigPaths from "vite-tsconfig-paths";
iport svgr from "vite-plugin-svgr";

// https://vite.dev/config/
export default defineConfig({
 define: {
 global: "globalThis", // <- 패키지 중에 global 관련 에러가 발생할 경우 추가
 },
 plugins: [
 react(),
 tsconfigPaths(),
 svgr(),
 ],
 server: {
 port: 3000,
 },
});

tsconfig.json 파일의 경로 정보 수정

프로젝트의 tsconfig.json 파일을 수정합니다. 아래 내용은 예시이므로 프로젝트에 맞게 수정해야 합니다.

{
 "compilerOptions": {
 "baseUrl": "./src",
 "paths": {
 "@/*": ["*"],
 "@store": ["./app/store"],
 "@pages/*": ["./pages/*"],
 "@components/*": ["./components/*"],
 ...
 },
 "target": "es2015",
 "lib": ["dom", "dom.iterable", "esnext"],
 "allowJs": true,
 "skipLibCheck": true,
 "esModuleInterop": true,
 "allowSyntheticDefaultImports": true,
 "strict": true,
 "forceConsistentCasingInFileNames": true,
 "noFallthroughCasesInSwitch": true,
 "module": "esnext",
 "moduleResolution": "node",
 "resolveJsonModule": true,
 "isolatedModules": true,
 "noEmit": true,
 "jsx": "react-jsx",
 "noImplicitAny": false
 },
 "include": ["src"]
}

vite-env.d.ts 파일 생성

src/vite-env.d.ts 파일을 생성하고 다음과 같이 작성합니다.

/// <reference types="vite/client" />

// svg 파일을 React 컴포넌트로 사용할 수 있도록 선언
declare module "*.svg?react" {
 import * as React from "react";
 const ReactComponent: React.FunctionComponent<
 React.SVGProps<SVGSVGElement> & { title?: string }
 >;
 export default ReactComponent;
}

index.html 파일 수정

public/index.html 파일을 프로젝트의 루트 폴더로 옮기고, 스크립트 링크를 다음과 같이 수정합니다.

...
<body>
 <div id="root"></div>
 <script type="module" src="/src/main.tsx"></script>
</body>
...

환경 변수 업데이트

프로젝트의 .env 파일에서 환경 변수를 REACT_APP_ 대신 VITE_ 접두사를 사용하도록 수정합니다.

// 이전
REACT_APP_API_URL=http://localhost:3000

// 다음과 같이 수정
VITE_API_URL=http://localhost:3000

package.json 파일의 스크립트 수정

프로젝트의 package.json 파일을 수정합니다.

...
 "scripts": {
 "dev": "vite",
 "build": "NODE_ENV=production tsc -b && vite build",
 }
...

svg 임포트 수정

앞서 vite-plugin-svgr 플러그인을 설치했었는데요, VITE에서는 CRA 처럼 svg파일을 컴포넌트로 임포트 할 수 없습니다. 그래서 플러그인을 설치하고 임포트 부분을 다음과 같이 수정합니다.

// 이전 방식
import { ReactComponent as Checklist } from "../assets/checklist.svg";

// 다음과 같이 수정
import Checklist from "../assets/checklist.svg?react";

앞서 작성한 vite-env.d.ts 파일을 다시 확인해보시면 .svg?react를 처리하기 위한 선언이 추가되어 있습니다.

ERR_REQUIRE_ESM 에러

npm run dev 명령으로 프로젝트를 실행했을 때, 다음과 같은 에러가 발생할 수 있는데요,

...
Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/vite-tsconfig-paths/dist/index.js from /path/to/vite.config.ts not supported.
...

그렇다면 프로젝트가 ESM 모듈을 사용하도록 타입을 변경해야 합니다.

{
 "type": "module"
}

global is not defined 에러

몇몇 패키지는 global 변수를 참조하는데, VITE가 global 대신에 브라우저에서 사용하는 globalThis를 사용하도록 설정해주면 됩니다.

앞서 작성한 vite.config.ts 파일을 확인해보시면 다음과 같은 설정이 있었습니다.

export default defineConfig({
 define: {
 global: 'globalThis', // ← 바로 이겁니다!
 },
 ...
});

process.env.NODE_ENV 를 찾을 수 없는 오류

VITE는 process.env.NODE_ENV 대신 import.meta.env.MODE를 사용합니다.

// 이전 방식
const isProduction = process.env.NODE_ENV === "production";

// 다음과 같이 수정
const isProduction = import.meta.env.MODE === "production";

require를 import로 변경

VITE는 CommonJS 모듈 시스템을 사용하지 않습니다. 그래서 require를 import로 변경해야 합니다.

// 이전 방식
import i18n from "i18next";
import { initReactI18next } from "react-i18next";

i18n.use(initReactI18next).init({
 fallbackLng: "en-US",
 lng: "en-US",
 resources: {
 en: {
 translations: require("./locales/en/translations.json"),
 },
 ko: {
 translations: require("./locales/ko/translations.json"),
 },
 },
 ...
});

// 다음과 같이 수정
import i18n from "i18next";
import { initReactI18next } from "react-i18next";
import enTranslations from "./locales/en/translations.json";
import koTranslations from "./locales/ko/translations.json";

i18n.use(initReactI18next).init({
 fallbackLng: "en-US",
 lng: "en-US",
 resources: {
 en: {
 translations: enTranslations,
 },
 ko: {
 translations: koTranslations,
 },
 },
 ...
});

빌드에서 문제가 발생하다.

CRA는 개발환경에서는 문제가 많았지만, 빌드 속도를 제외하고 빌드에서 문제는 특별히 없었습니다. 그런데 VITE로 변경하니 로컬에서는 빌드가 잘 되는데 Github Actions에서는 메모리 이유로 빌드가 실패하는 문제가 발생했습니다.

원인을 찾다보니, 너무 거대한 번들 사이즈가 원인이었습니다. 현재 작업 중인 프로젝트는 좀 복잡한 요구사항으로 인해 무거운 패키지를 많이 사용할 수 밖에 없었는데요. 가장 큰 번들의 크기가 무려 16MB에 이를 정도 였습니다.

다음과 같이 manualChunks 옵션을 사용하여 번들의 크기를 분할하는 방법이 있었지만,

build: {
 rollupOptions: {
 output: {
 manualChunks(id) {
 if (id.includes('node_modules')) {
 if (id.includes('react')) return 'vendor-react';
 if (id.includes('codemirror')) return 'vendor-codemirror';
 return 'vendor';
 }
 },
 },
 },
},

빌드되고 나서 실행과정에서 문제가 생겼기 때문에, 다른 방법을 찾아야 했습니다.

다른 방법으로는 lazy import를 사용하는 방법이었는데, 프로젝트가 워낙 복잡한 상황이었기에 한 번에 적용할 수는 없었고 일단은 Github Actions의 빌드 설정에 메모리 옵션을 추가하는 것으로 해결했습니다.

- run: CI=false npm run build
 env:
 NODE_OPTIONS: --max-old-space-size=8192

일단은 한숨 돌리고 프로젝트를 유지보수 하면서 점진적으로 lazy import를 적용해 나가면서 상황을 개선 해봐야 겠습니다.

React 19 & 19.1 알아보기

Sat, 15 Mar 2025 00:10:50 +0000

1. 프로젝트 세팅하기

1.1 vite 프로젝트 세팅

우선 vite를 이용해서 react 프로젝트를 설정합니다.

> npm create vite@latest react-19
Need to install the following packages:
create-vite@6.3.1
Ok to proceed? (y) y


> npx
> create-vite react-19

│
◇ Select a framework:
│ React
│
◇ Select a variant:
│ TypeScript + SWC
│
◇ Scaffolding project in /Users/onlifecoding/src/studies/react-19...
│
└ Done. Now run:

 cd react-19
 npm install
 npm run dev

> cd react-19
> npm i

이렇게 프로젝트를 설정하고 에디터를 통해 프로젝트를 열어보면, 다음과 같이 react 19 프로젝트가 설정된 것을 확인할 수 있습니다.

{
 ...
 "dependencies": {
 "react": "^19.0.0",
 "react-dom": "^19.0.0"
 },
 "devDependencies": {
 ...
 "@types/react": "^19.0.10",
 "@types/react-dom": "^19.0.4",
 ...
 }
}

1.2 tailwindcss 설정

tailwindcss를 설치합니다.

> npm i tailwindcss @tailwindcss/vite

vite.config.ts 파일에 tailwindcss를 설정합니다.

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import tailwindcss from "@tailwindcss/vite";

// https://vite.dev/config/
export default defineConfig({
 plugins: [react(), tailwindcss()],
 server: {
 port: 3000,
 },
});

src/index.css 파일의 최상단에 다음과 같이 작성합니다.

@import "tailwindcss";

1.3 react-router-dom 및 기본 라우팅 설정

페이지간의 이동을 위해 react-router-dom을 설치합니다.

> npm install react-router-dom

그리고 src/Router.tsx 파일을 생성하고 다음과 같이 코드를 작성합니다.

import { lazy } from "react";
import { createBrowserRouter, Outlet } from "react-router-dom";

const Index = lazy(() => import("./pages/Index"));
const About = lazy(() => import("./pages/About"));

// 루트 레이아웃 컴포넌트
const RootLayout = () => {
 return (
 <div className="h-screen w-full">
 <Outlet />
 </div>
 );
};

export const router = createBrowserRouter([
 {
 path: "/",
 element: <RootLayout />,
 children: [
 {
 index: true,
 element: <Index />,
 },
 {
 path: "/about",
 element: <About />,
 },
 ],
 },
]);

라우팅 확인을 위해 src/pages/Index.tsx 파일을 다음과 같이 작성합니다.

import { Link } from "react-router-dom";

const Index = () => {
 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="text-4xl font-bold">Index</div>
 </div>
 );
};

export default Index;

이어서 src/pages/About.tsx 파일을 다음과 같이 작성합니다.

import { Link } from "react-router-dom";

const About = () => {
 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="text-4xl font-bold">About</div>
 </div>
 );
};
export default About;

마지막으로 라우팅이 동작하도록 src/App.tsx 파일을 다음과 같이 작성합니다.

import { Suspense } from "react";
import { RouterProvider } from "react-router-dom";
import { router } from "./Router";

function App() {
 return (
 <Suspense fallback={<div>Loading...</div>}>
 <RouterProvider router={router} />
 </Suspense>
 );
}

export default App;

이제 프로젝트를 실행하고 라우팅이 동작하는 것을 확인할 수 있습니다.

> npm run dev

2. React 19 알아보기

2.1 Actions

React에서는 데이터를 작성하고 저장하거나 수정하는 일이 빈번하게 발생합니다. 사실 웹 페이지라는 게 데이터를 저장하고, 표시하고, 수정하고, 삭제하는 것이 전부이기 때문입니다. 이렇게 데이터를 다루는 과정에서 무언가 상태 값이 변경되겠죠?(ex: 서버에 데이터를 전송하고 처리되기 기다릴 때, 요청 상태는 요청중 -> 요청 완료 또는 요청중 -> 요청 실패 등으로 변경될 겁니다!) 이렇게 상태가 변경되는 걸 상태 전이(transition)이라고 합니다. 그리고 공식 문서에 따르면, 비동기 상태 전이(async transition)을 사용하는 함수를 Action이라고 정의하고 있습니다.

2.1.1 useTransition

예시를 하나 들어볼까요? 서버에 데이터를 전송하는 경우를 생각해보죠. 서버와의 통신 작업을 진행할 때 중요한 점은, 사용자가 실수로 저장 버튼을 두번 클릭하는 걸 방지할 수 있어야 합니다. 만약 이런 처리가 제대로 되지 않는다면, 데이터가 중복으로 저장되어 문제가 발생할 수 있습니다. 예시를 위해서 src/pages/Index.tsx 파일을 다음과 같이 작성합니다.

import { useState } from "react";
import { Link } from "react-router-dom";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const Index = () => {
 const [message, setMessage] = useState("");
 const [log, setLog] = useState<string[]>([]);

 const handleSave = async () => {
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기
 setLog((prev: string[]) => [...prev, message]);
 };

 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="flex items-center gap-2">
 <input
 type="text"
 placeholder="메세지를 입력하세요"
 value={message}
 onChange={(e) => setMessage(e.target.value)}
 />
 <button onClick={handleSave}>저장</button>
 </div>
 <div className="flex items-center gap-2">
 {log.map((item, index) => (
 <div key={index}>{item}</div>
 ))}
 </div>
 </div>
 );
};

export default Index;

완성된 페이지는 다음과 같습니다.

메세지를 입력할 수 있는 입력 필드와 저장 버튼을 표시하고, 저장 버튼을 클릭하면 메세지를 서버에 저장하는 기능을 구현했습니다. 그리고 서버에 저장하는 걸 흉내내기 위해서 저장 버튼을 누르면 2초 대기 후 저장된 메세지를 표시하도록 했습니다.

이 페이지에서 메세지를 입력하고, 저장 버튼을 누르면 2초 후에 저장된 메세지가 로그에 표시되는 걸 확인할 수 있습니다. 그런데 저장 버튼을 마구 누르면 어떻게 될까요?

서버에 저장하는 동안 입력을 방지하는 작업을 하지 않았기 때문에 누르는 만큼 중복되어 저장되는 걸 볼 수 있습니다. 그러면 입력을 방지하기 위한 장치를 추가해보겠습니다.

...
const Index = () => {
 ...
 const [isSaving, setIsSaving] = useState(false);

 const handleSave = async () => {
 setIsSaving(true);
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기
 setLog((prev: string[]) => [...prev, message]);
 setIsSaving(false);
 };

 return (
 <div className="h-screen w-full flex flex-col gp">
 ...
 <div className="flex flex-col gap-2">
 <div className="flex items-center gap-2">
 ...
 <button
 className="border-2 border-gray-300 rounded-md p-2 disabled:opacity-50 disabled:cursor-not-allowed"
 onClick={handleSave}
 disabled={isSaving}
 >
 저장
 </button>
 </div>
 ...
 </div>
 </div>
 );
};

export default Index;

데이터를 저장하는 중인지 알 수 있는 상태 isSaving을 추가했습니다. 그리고 저장 버튼을 누르면 이 상태를 true로 변경하고, 서버와의 통신이 끝나면 false로 변경합니다. 이렇게 하면 저장 버튼이 눌리지 않은 상태에서는 비활성화되어 입력을 방지할 수 있습니다. 그리고 사용자에게 버튼을 누를 수 없다는 알림을 위해 disabled 속성과 스타일을 추가했습니다.

이제 저장 버튼을 누르면 중복으로 저장되는 걸 막을 수 있습니다. React 19에서는 이런 작업을 쉽게 할 수 있도록 useTransition 훅을 제공합니다. 이 훅은 서버에 데이터를 저장하는 등의 비동기 작업이 시작될 때 isPending 상태를 true로 변경하고, 끝나면 false로 변경합니다. 위 예제를 다음과 같이 수정할 수 있습니다.

import { useState, useTransition } from "react";
import { Link } from "react-router-dom";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

const Index = () => {
 const [message, setMessage] = useState("");
 const [log, setLog] = useState<string[]>([]);
 const [isPending, startTransition] = useTransition();

 const handleSave = async () => {
 startTransition(async () => {
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기
 setLog((prev: string[]) => [...prev, message]);
 });
 };

 return (
 <div className="h-screen w-full flex flex-col gp">
 ...
 <div className="flex flex-col gap-2">
 <div className="flex items-center gap-2">
 ...
 <button
 className="border-2 border-gray-300 rounded-md p-2 disabled:opacity-50 disabled:cursor-not-allowed"
 onClick={handleSave}
 disabled={isPending}
 >
 저장
 </button>
 </div>
 ...
 </div>
 </div>
 );
};

export default Index;

isSaving과 같은 별도의 상태를 사용하지 않아도 되고, 사용자가 직업 setIsSaving(true), setIsSaving(false)를 호출해야 할 필요도 없어졌습니다. startTransition 함수를 사용하면, 호출이 시작될 때와 종료될 때 useTransition 훅이 자동으로 상태를 관리해줍니다.

useTransition은 React 18에서도 사용할 수 있습니다!

2.1.2 useActionState

만약 데이터를 전송하던 중에 오류가 발생한다면 어떻게 될까요? 사용자에게 뭔가 오류가 발생했다는 사실을 알려줘야 합니다. 그렇지 않으면, 사용자는 뭐가 안되는지도 모르면서 계속 여기저기 클릭하다가 결국 사용을 포기하겠죠!

import { useState, useTransition } from "react";
import { Link } from "react-router-dom";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * 서버에 데이터를 전송하는 함수, 일부러 오류를 발생시키기 위해 예외를 던집니다.
 */
const submitMessage = async (message: string) => {
 console.log(`submitMessage: ${message}`);
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기
 throw new Error("서버에 문제가 발생했습니다.");
};

const Index = () => {
 const [message, setMessage] = useState("");
 const [log, setLog] = useState<string[]>([]);
 const [isPending, startTransition] = useTransition();
 const [error, setError] = useState<string | null>(null);

 const handleSave = async () => {
 setError(null);

 startTransition(async () => {
 try {
 await submitMessage(message);

 setLog((prev: string[]) => [...prev, message]);
 } catch (error: unknown) {
 setError(
 error instanceof Error
 ? error.message
 : "알 수 없는 오류가 발생했습니다."
 );
 }
 });
 };

 return (
 <div className="h-screen w-full flex flex-col gp">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="flex flex-col gap-2">
 <div className="flex items-center gap-2">
 <input
 className="border-2 border-gray-300 rounded-md p-2"
 type="text"
 placeholder="메세지를 입력하세요"
 value={message}
 onChange={(e) => setMessage(e.target.value)}
 />
 <button
 className="border-2 border-gray-300 rounded-md p-2 disabled:opacity-50 disabled:cursor-not-allowed"
 onClick={handleSave}
 disabled={isPending}
 >
 저장
 </button>
 {error && <p className="text-red-500">{error}</p>}
 </div>
 <div className="flex flex-col gap-2">
 <p className="text-lg font-bold text-gray-500">로그</p>
 <div className="flex items-center gap-2">
 {log.map((item, index) => (
 <div key={index}>{item}</div>
 ))}
 </div>
 </div>
 </div>
 </div>
 );
};

export default Index;

저장 버튼을 눌렀을 때, 서버에 메세지를 전송하는 걸 흉내내기 위해 submitMessage 함수를 추가했습니다. 그리고 서버에서 뭔가 오류가 발생하는 상황을 만들기 위해 일부러 예외를 던지도록 했습니다.

이제 저장 버튼을 누르면 2초 대기 후 에러 메세지가 표시되는 걸 볼 수 있습니다.

React 19에 추가된 useActionState 훅을 사용하면, 이런 폼 전송 작업의 상태와 에러 처리를 더 쉽게 할 수 있습니다.

import { useActionState, useState } from "react";
import { Link } from "react-router-dom";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

interface submitMessageResult {
 error: string | null;
}

/**
 * 서버에 데이터를 전송하는 함수, 일부러 오류를 발생시키기 위해 예외를 던집니다.
 */
const submitMessage = async (message: string) => {
 console.log(`submitMessage: ${message}`);
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기
 throw new Error("서버에 문제가 발생했습니다.");
};

const Index = () => {
 const [message, setMessage] = useState("");
 const [log, setLog] = useState<string[]>([]);
 /**
 * 각각 Action의 결과, 폼의 값을 전송할 Action, Action의 진행 상태를 나타냅니다.
 *
 * 이 예제에서는 결과 값으로 오류 메세지만 리턴합니다.
 */
 const [result, submitAction, isPending] = useActionState(
 async (
 prevState: submitMessageResult,
 formData: FormData
 ): Promise<submitMessageResult> => {
 const message = formData.get("message") as string;

 if (prevState) {
 console.log(`이전 상태 값: ${JSON.stringify(prevState)}`);
 }

 try {
 await submitMessage(message);

 setLog((prev: string[]) => [...prev, message]);

 return { error: null }; // Action의 결과를 리턴합니다. 오류가 없었으므로 null을 리턴합니다.
 } catch (error: unknown) {
 const errorMessage =
 error instanceof Error
 ? error.message
 : "알 수 없는 오류가 발생했습니다.";
 return { error: errorMessage }; // 오류가 있었으므로 오류 메세지를 리턴합니다.
 }
 },
 { error: null } // 초기 상태는 null입니다.
 );

 return (
 <div className="h-screen w-full flex flex-col gp">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="flex flex-col gap-2">
 <form action={submitAction} className="flex items-center gap-2">
 <input
 name="message"
 className="border-2 border-gray-300 rounded-md p-2"
 type="text"
 placeholder="메세지를 입력하세요"
 value={message}
 onChange={(e) => setMessage(e.target.value)}
 />
 <button
 className="border-2 border-gray-300 rounded-md p-2 disabled:opacity-50 disabled:cursor-not-allowed"
 type="submit"
 disabled={isPending}
 >
 저장
 </button>
 {!isPending && result.error && (
 <p className="text-red-500">{result.error}</p>
 )}
 </form>
 <div className="flex flex-col gap-2">
 <p className="text-lg font-bold text-gray-500">로그</p>
 <div className="flex items-center gap-2">
 {log.map((item, index) => (
 <div key={index}>{item}</div>
 ))}
 </div>
 </div>
 </div>
 </div>
 );
};

export default Index;

직접 setError를 통해 오류 메세지를 설정할 필요 없이 useActionState 훅을 통해 Action의 결과와 진행 상태를 관리할 수 있습니다. 그리고 이전 상태까지도 접근할 수 있어서, 뭔가 이전 상태에 따른 처리를 할 수도 있습니다.

2.1.3 use

아마도 웹에서 가장 빈번한 작업을 서버에서 비동기(async)로 데이터를 조회해서 목록을 출력하는 작업일겁니다. 그런 작업을 하나 추가해볼까요? pages/List.tsx 파일을 추가하고 다음과 같이 작성합니다.

단순한 구현을 위해 코드 중복은 무시하겠습니다!

import { Suspense } from "react";
import { Link } from "react-router-dom";
import MemberList from "./components/MemberList";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * 멤버 목록을 조회하는 함수
 * @returns 멤버 목록
 */
const fetchMemberList = async () => {
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기

 return [
 { id: 1, name: "John" },
 { id: 2, name: "Jane" },
 { id: 3, name: "Jim" },
 ];
};

const List = () => {
 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="text-4xl font-bold">List</div>
 <div className="flex flex-col gap-2">
 {/* 비동기 처리를 위해 Suspense를 사용 */}
 <Suspense fallback={<div>목록을 불러오는 중입니다...</div>}>
 {/* 멤버 목록을 조회하는 함수의 Promise를 넘겨줍니다. */}
 <MemberList memberListPromise={fetchMemberList()} />
 </Suspense>
 </div>
 </div>
 );
};

export default List;

MemberList 컴포넌트에 멤버 목록을 조회하는 함수의 결과인 Promise를 넘겨주고 있습니다. 이제 pages/components/MemberList.tsx 파일을 추가하고 다음과 같이 작성합니다.

import { use } from "react";

interface MemberListProps {
 memberListPromise: Promise<
 {
 id: number;
 name: string;
 }[]
 >;
}

/**
 * 멤버 목록을 조회하는 컴포넌트
 * @param memberListPromise 멤버 목록을 조회하는 Promise
 * @returns 멤버 목록
 */
const MemberList = ({ memberListPromise }: MemberListProps) => {
 // Promise의 결과가 resolve될 때까지 기다립니다.
 const memberList = use(memberListPromise);

 return (
 <ul>
 {memberList.map((member) => (
 <li key={member.id}>{`${member.id} - ${member.name}`}</li>
 ))}
 </ul>
 );
};

export default MemberList;

Promise를 받아서 use 훅으로 넘겨줍니다. use 훅은 Promise 결과가 나올 때 까지(resolve 또는 reject) 기다리고, 그 결과를 반환합니다. 결과를 받아서 li 요소를 생성합니다.

마지막으로 Router.tsx 파일에 다음과 같이 라우팅을 추가합니다.

import { lazy } from "react";
import { createBrowserRouter, Outlet } from "react-router-dom";

const Index = lazy(() => import("./pages/Index"));
const About = lazy(() => import("./pages/About"));
const List = lazy(() => import("./pages/List"));

// 루트 레이아웃 컴포넌트
// eslint-disable-next-line react-refresh/only-export-components
const RootLayout = () => {
 return (
 <div className="h-screen w-full">
 <Outlet />
 </div>
 );
};

export const router = createBrowserRouter([
 {
 path: "/",
 element: <RootLayout />,
 children: [
 {
 index: true,
 element: <Index />,
 },
 {
 path: "/about",
 element: <About />,
 },
 {
 path: "/list",
 element: <List />,
 },
 ],
 },
]);

이제 브라우저에서 http://localhost:3000/list 주소로 이동하면, 서버의 응답을 기다리는 동안 Suspense 컴포넌트의 fallback 속성으로 설정한 내용이 표시되다가 서버의 응답이 오면 멤버 목록을 조회하는 작업이 진행되는 걸 볼 수 있습니다.

만약 서버에서 데이터를 조회하는 작업이 실패한다면, 그러니까 Promise가 reject 된다면 어떻게 될까요? fetchMemberList 함수에서 일부러 오류가 발생하도록 수정해볼까요?

/**
 * 멤버 목록을 조회하는 함수
 * @returns 멤버 목록
 */
const fetchMemberList = async () => {
 throw new Error("서버에 문제가 발생했습니다.");
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기

 return [
 { id: 1, name: "John" },
 { id: 2, name: "Jane" },
 { id: 3, name: "Jim" },
 ];
};

페이지를 새로고침 해보면, 컴포넌트 내용 대신에 오류 메세지가 표시됩니다!

이럴 때는 Promise에 catch 핸들러를 추가할 수도 있지만, ErrorBoundary를 사용해서 오류를 사용자에게 친화적인 메시지로 표시할 수 있습니다. 우선, react-error-boundary 패키지를 설치합니다.

> npm install react-error-boundary

그리고 src/pages/List.tsx 파일의 Suspense 컴포넌트를 ErrorBoundary 컴포넌트로 감싸줍니다.

import { Suspense } from "react";
import { Link } from "react-router-dom";
import MemberList from "./components/MemberList";
import { ErrorBoundary } from "react-error-boundary";

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

/**
 * 멤버 목록을 조회하는 함수
 * @returns 멤버 목록
 */
const fetchMemberList = async () => {
 throw new Error("서버에 문제가 발생했습니다.");
 await wait(2000); // 서버와의 통신을 흉내내기 위해 2초 대기

 return [
 { id: 1, name: "John" },
 { id: 2, name: "Jane" },
 { id: 3, name: "Jim" },
 ];
};

const List = () => {
 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="text-4xl font-bold">List</div>
 <div className="flex flex-col gap-2">
 <ErrorBoundary
 fallback={<div>목록을 불러오는 중에 문제가 발생했습니다.</div>}
 >
 {/* 비동기 처리를 위해 Suspense를 사용 */}
 <Suspense fallback={<div>목록을 불러오는 중입니다...</div>}>
 {/* 멤버 목록을 조회하는 함수의 Promise를 넘겨줍니다. */}
 <MemberList memberListPromise={fetchMemberList()} />
 </Suspense>
 </ErrorBoundary>
 </div>
 </div>
 );
};

export default List;

이렇게 하면 데이터를 조회하는 작업이 실패했을 때, 사용자에게 친화적인 메시지를 표시할 수 있습니다.

React 19.1 업데이트하기

다음 명령을 통해 설치된 패키지의 현재 버전과 최신 버전을 확인합니다.

> npm outdated
Package Current Wanted Latest Location Depended by
@eslint/js 9.22.0 9.24.0 9.24.0 node_modules/@eslint/js react-19
@tailwindcss/vite 4.0.14 4.1.3 4.1.3 node_modules/@tailwindcss/vite react-19
@types/react 19.0.10 19.1.1 19.1.1 node_modules/@types/react react-19
@types/react-dom 19.0.4 19.1.2 19.1.2 node_modules/@types/react-dom react-19
@vitejs/plugin-react-swc 3.8.0 3.8.1 3.8.1 node_modules/@vitejs/plugin-react-swc react-19
eslint 9.22.0 9.24.0 9.24.0 node_modules/eslint react-19
globals 15.15.0 15.15.0 16.0.0 node_modules/globals react-19
react 19.0.0 19.1.0 19.1.0 node_modules/react react-19
react-dom 19.0.0 19.1.0 19.1.0 node_modules/react-dom react-19
react-router-dom 7.3.0 7.5.0 7.5.0 node_modules/react-router-dom react-19
tailwindcss 4.0.14 4.1.3 4.1.3 node_modules/tailwindcss react-19
typescript 5.7.3 5.7.3 5.8.3 node_modules/typescript react-19
typescript-eslint 8.26.1 8.29.1 8.29.1 node_modules/typescript-eslint react-19
vite 6.2.2 6.2.6 6.2.6 node_modules/vite react-19

위 내용 중 Current, Wanted, Latest 열은 다음과 같은 의미를 가집니다.

Current: 현재 설치된 버전
Wanted: package.json 파일에 설정된 버전 범위를 만족하는 최신 버전(ex: “~5.7.2"는 5.7.2 <= 패키지 버전 < 5.8.0, “^6.2.0"은 6.2.0 <= 패키지 버전 < 7.0.0)
Latest: 최신 버전

자 그러면, 모든 패키지를 Wanted 버전으로 업데이트 하겠습니다.

> npm update

이제 다시 패키지 버전을 확인해보면, 다음과 같이 모든 패키지가 최신 버전으로 업데이트 된 것을 확인할 수 있습니다.

Owner Stacks

React 19.1 버전에서 추가된 Owner Stacks는 컴포넌트의 오류가 발생했을 때, 오류가 발생한 컴포넌트의 계층 구조를 표시해줍니다. 그래서 실제로 어떤 컴포넌트에서 오류가 발생했고, 그 컴포넌트는 어떤 컴포넌트가 렌더링한 건지 확인할 수 있어 디버깅할 때 유용합니다.

공식 문서를 참조하여 다음과 같은 예제를 작성해보겠습니다.

우선, 무언가 에러가 발생했을 때 화면에 오버레이를 표시할 수 있도록 index.html 파일을 수정합니다.

<!doctype html>
<html lang="en">
 <head>
 <meta charset="UTF-8" />
 <link rel="icon" type="image/svg+xml" href="/vite.svg" />
 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 <title>Vite + React + TS</title>
 </head>
 <body>
 <!--
 Error dialog in raw HTML
 since an error in the React app may crash.
-->
<div id="error-dialog" class="hidden">
 <h1 id="error-title" class="text-red">Error</h1>
 <p class="">
 <pre id="error-body"></pre>
 </p>
 <div class="mb-10"></div>
 <h2 class="">Owner Stack:</h2>
 <pre id="error-owner-stack" class="nowrap"></pre>
 <button
 id="error-close"
 class="mt-10"
 onclick="document.getElementById('error-dialog').classList.add('hidden')"
 >
 Close
 </button>
</div>
 <div id="root"></div>
 <script type="module" src="/src/main.tsx"></script>
 </body>
</html>

그리고 이 오버레이의 스타일을 src/index.css 파일에 추가합니다.

#error-dialog {
 position: absolute;
 top: 0;
 right: 0;
 bottom: 0;
 left: 0;
 background-color: white;
 padding: 15px;
 opacity: 0.9;
 text-wrap: wrap;
 overflow: scroll;
}

#error-dialog h1 {
 margin-top: 0;
 font-size: 22px;
}

#error-dialog h2 {
 margin-top: 0;
 font-size: 20px;
}

#error-dialog .text-red {
 color: red;
}

#error-dialog .mb-20 {
 margin-bottom: 20px;
}

#error-dialog .mb-10 {
 margin-bottom: 10px;
}

#error-dialog .mb-0 {
 margin-bottom: 0;
}

#error-dialog .mt-10 {
 margin-top: 10px;
}

#error-dialog pre {
 text-wrap: wrap;
}

#error-dialog pre.nowrap {
 text-wrap: nowrap;
}

#error-dialog .hidden {
 display: none;
}

다음으로 오버레이에 에러 메세지와 Owner Stack을 표시할 수 있도록 하는 유틸 함수를 src/utils/errorOverlay.ts 파일에 추가합니다.

export const onConsoleError = ({
 consoleMessage,
 ownerStack,
}: {
 consoleMessage: string;
 ownerStack: string | null;
}) => {
 const errorDialog = document.getElementById("error-dialog");
 const errorBody = document.getElementById("error-body");
 const errorOwnerStack = document.getElementById("error-owner-stack");

 if (errorBody) {
 // Display console.error() message
 errorBody.innerText = consoleMessage;
 }

 if (errorOwnerStack) {
 // Display owner stack
 errorOwnerStack.innerText = ownerStack ?? "-no owner stack-";
 }

 if (errorDialog) {
 // Show the dialog
 errorDialog.classList.remove("hidden");
 }
};

이제 마지막으로 src/main.tsx 파일에 console.error 함수를 재정의하여 console.error 함수가 호출될 때 오버레이에 에러 메세지와 Owner Stack을 표시할 수 있도록 합니다.

import { captureOwnerStack, StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { onConsoleError } from "./utils/errorOverlay.ts";

// 원래의 console.error 함수를 저장
const originalConsoleError = console.error;

// 재정의된 console.error 함수
console.error = function patchedConsoleError(...args) {
 // 원래의 console.error 함수를 호출
 originalConsoleError.apply(console, args);
 // Owner Stack을 캡쳐
 const ownerStack = captureOwnerStack();
 // 오버레이에 에러 메세지와 Owner Stack을 표시
 onConsoleError({
 consoleMessage: args[0],
 ownerStack,
 });
};

createRoot(document.getElementById("root")!).render(
 <StrictMode>
 <App />
 </StrictMode>
);

이제 브라우저에서 무언가 에러가 발생했을 때 오버레이에 에러 메세지와 Owner Stack을 표시할 수 있습니다. 그러면 간단하게 테스트를 해볼까요?

다음과 같이 src/pages/components/Parent.tsx와 src/pages/components/Child.tsx 파일을 추가합니다.

const Child = () => {
 console.error("Child 컴포넌트에서 에러가 발생했습니다.");

 return <div>Child</div>;
};

export default Child;

import Child from "./Child";

const Parent = () => {
 return (
 <>
 <div>Parent</div>
 <Child />
 </>
 );
};

export default Parent;

그리고 src/pages/About.tsx 파일에 Parent 컴포넌트를 추가합니다.

import { Link } from "react-router-dom";
import Parent from "./components/Parent";

const About = () => {
 return (
 <div className="h-screen w-full flex flex-col">
 <div className="w-full flex items-center gap-2 text-blue-500 underline">
 <Link to="/">Index</Link>
 <Link to="/about">About</Link>
 </div>
 <div className="text-4xl font-bold">About</div>
 <Parent />
 </div>
 );
};
export default About;

이제 브라우저에서 About 페이지로 이동해서 에러를 확인해볼까요?

오버레이가 표시되고, Owner Stack에 오류가 발생한 컴포넌트의 계층 구조가 표시되는 것을 확인할 수 있습니다. 에러가 발생한 컴포넌트의 부모 컴포넌트는 Parent 컴포넌트이고, Parent 컴포넌트의 부모 컴포넌트는 About 컴포넌트인 거죠.

단, Owner Stack은 개발 환경에서만 사용가능하기 때문에 main.tsx를 다음과 같이 수정할 필요가 있습니다.

import { captureOwnerStack, StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "./index.css";
import App from "./App.tsx";
import { onConsoleError } from "./utils/errorOverlay.ts";

if (process.env.NODE_ENV === "development") {
 const originalConsoleError = console.error;

 console.error = function patchedConsoleError(...args) {
 originalConsoleError.apply(console, args);
 const ownerStack = captureOwnerStack();
 onConsoleError({
 consoleMessage: args[0],
 ownerStack,
 });
 };
}

createRoot(document.getElementById("root")!).render(
 <StrictMode>
 <App />
 </StrictMode>
);

참고로 process를 사용하려면 다음 명령으로 node의 타입 정보 패키지를 설치해야 합니다.

> npm install --save-dev @types/node

k8s 노드에 접속하기(+ AKS 노드에 접속하기)

Tue, 03 Sep 2024 11:11:51 +0900

k8s에 대해서 스터디하거나 서비스를 배포하다 보면 가끔 워커 노드에 접속해야 할 때가 있습니다. 예를 들면 pod에서 DB나 Redis 등에 제대로 접속하지 못할 때 혹시 네트워크에 문제 있는지 확인하거나 워커 노드의 로그 등을 수집할 때 해당 로그의 위치가 어디인지 등을 확인해야 할 때가 있습니다.

이럴 때 노드에 접속할 수 있는 몇 가지 방법을 알아보겠습니다.

k9s 사용하기

k9s 설치하기

k9s는 k8s 클러스터를 쉽게 관리할 수 있는 터미널 기반의 UI 도구입니다. k9s를 사용하면 k8s 클러스터의 상태를 실시간으로 확인하고, 리소스를 생성하거나 삭제할 수 있습니다. 또한 k8s 클러스터의 로그를 확인하거나, 특정 pod에 쉘로 접속하는 등의 작업을 쉽게 수행할 수 있습니다. 그래픽 환경이 아니라 처음엔 어색할 수 있지만, 익숙해지면 훨씬 빠르게 작업할 수 있습니다.

k9s는 다음과 같이 설치할 수 있습니다.

# MacOS
> brew install derailed/k9s/k9s

# Ubuntu(linuxbrew)
> brew install derailed/k9s/k9s

# Windows
> scoop install k9s

그리고 k9s를 실행하면 됩니다.

k9s로 노드에 접속하기

k9s에서 :pod 명령으로 pod를 선택하고 s를 누르면 해당 pod에 쉘로 접속할 수 있습니다. 그런데 :node 명령으로 노드 목록을 표시해보면 노드에는 쉘로 접속할 수 있는 s 옵션이 표시되지 않습니다. 클러스터의 설정 파일을 찾아서 해당 클러스터에 대해서 쉘을 사용할 수 있도록 설정해줘야 합니다.

클러스터 설정 파일을 찾으려면 다음 명령을 실행합니다.

> k9s info
 ____ __.________
| |/ _/ __ \______
| < \____ / ___/
| | \  / /\___ \
|____|__ \ /____//____ >
 \/ \/

Version: v0.32.5
Config: /Users/onlifecoding/Library/Application Support/k9s/config.yaml
...

Config 항목에 표시되는 경로에 이동하면 clusters 폴더가 있고, 이 폴더에는 k9s로 접속한 적이 있는 k8s 클러스터의 설정 파일이 각 폴더 별로 저장되어 있습니다.

쉘로 접속하려는 클러스터의 폴더로 이동해서 config.yaml 파일의 nodeShell 항목을 true로 변경하면 됩니다.

k9s:
 cluster: aks-test-stg
 namespace:
 active: default
 lockFavorites: false
 favorites:
 - default
 view:
 active: node
 featureGates:
 nodeShell: true # 노드에 쉘 접근 허용하기
 portForwardAddress: localhost

그리고 다시 k9s에서 :node 명령을 실행하면 노드에 쉘로 접속할 수 있는 s 옵션이 표시됩니다. 해당 노드를 선택하고 s를 누르면 노드에 pod이 배포되고, 해당 pod로 노드의 네트워크 통신 등을 테스트 할 수 있습니다.

참고로, 생성되는 pod는 앞서 k9s info로 확인했던 Config 파일에 설정되어 있으며, 기본 값은 이렇습니다.


---
shellPod:
 image: busybox:1.35.0
 namespace: default
 limits:
 cpu: 100m
 memory: 100Mi

이 방법은 매우 간단하긴 하지만 노드 자체에는 접근할 수 없다는 단점이 있습니다.

AKS 노드에 접속하기

AKS에서는 kubectl debug를 통해 노드에 접속할 수 있습니다.

우선 k9s나 kubectl을 통해 노드의 이름을 확인합니다.

> kubectl get nodes -o wide
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
aks-default-28123321-vmss000000 Ready <none> 18m v1.29.7 10.224.0.4 <none> Ubuntu 22.04.4 LTS 5.15.0-1071-azure containerd://1.7.20-1

그리고 접속하려는 노드의 이름을 사용하여 kubectl debug 명령을 실행합니다.

> kubectl debug node/aks-default-28123321-vmss000000 -it --image=mcr.microsoft.com/cbl-mariner/busybox:2.0
Creating debugging pod node-debugger-aks-default-28123321-vmss000000-2jj6t with container debugger on node aks-default-28123321-vmss000000.
If you don't see a command prompt, try pressing enter.
/

노드에 debug용 pod이 생성되고, 해당 pod에 접속되었습니다. 이제 다음 명령으로 node에 접근할 수 있습니다.

> chroot /host

노드에서 확인작업을 마치고 exit 빠져나오면, pod은 종료되지만 삭제되지 않고 남아있는데요, k9s에서 ctrl + d를 눌러 삭제하거나 kubectl delete pod 명령으로 삭제할 수 있습니다.

> kubectl delete pod node-debugger-aks-default-28123321-vmss000000-2jj6t

혹시 클라우드 프로바이더에 상관없이 노드에 접속하는 방법은?

마지막으로 kubectl-plugins를 이용하는 방법이 있습니다. 이 방법은 클라우드 프로바이더에 상관없이 노드에 접속할 수 있는 방법인데요, 클러스터의 어드민 권한이 필요합니다.

참고자료

S3에 업로드된 이미지 접근시 CORS 이슈, 그리고 no-cors

Fri, 21 Jun 2024 08:46:23 +0900

개요

현재 개발 중인 서비스는 이미지나 기타 파일을 업로드하고 가져올 때 NCP(네이버 클라우드 플랫폼)의 Object Storage를 사용 중입니다. 제목에서는 S3라고 했는데? 라고 생각하실 수 있지만, NCP의 Object Storage는 S3와 호환되는 API를 제공하기 때문에 사실상 S3와 동일하게 생각하고 사용할 수 있습니다. 따라서 이후에는 그냥 S3라고 표현하겠습니다.

S3에 업로드된 이미지 등의 에셋을 가져올 때는 CORS 이슈가 발생할 수 있습니다. 이 문제를 해결하려면 S3의 버킷에 CORS 설정을 추가해줘야 합니다. 여러가지 방법이 있을 수 있지만 이 글에서는 S3 Browser를 사용하여 CORS 설정을 추가하는 방법을 알아보겠습니다.

버킷에 CORS 설정하기

S3 Browser를 통해 S3에 접속합니다. 만약 NCP의 Object Storage와 같이 S3 API와 호환되는 서비스를 사용 중이라면, Account type을 S3 Compatible Storage로 선택하고, 접속합니다.

접속하면, 해당 계정의 버킷 목록이 나타납니다. CORS를 설정하고자 하는 버킷을 선택하고 Ctrl + R 을 누르거나 마우스 우클릭 후 CORS Configuration을 선택합니다. 그리고 XML 형식으로 CORS 설정을 추가합니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
 <CORSRule>
 <AllowedMethod>GET</AllowedMethod>
 <AllowedOrigin>http://localhost:3000</AllowedOrigin>
 <AllowedHeader>*</AllowedHeader>
 </CORSRule>
</CORSConfiguration>

그리고 Apply 버튼을 눌러 설정을 저장합니다. 이제 해당 버킷에 업로드된 이미지 등의 에셋을 가져올 때 CORS 이슈가 발생하지 않습니다… 그런데 말입니다. 😣

그런데 말입니다

그런데 한 가지 변수가 있습니다. 이 글의 제목에서 언급된 no-cors입니다. no-cors가 뭔지 일단 알아보야겠죠? no-cors는 Sec-Fetch-Mode 헤더의 설정 값 중에 하나입니다.

Sec-Fetch-Mode??

MDN의 설명을 보면, 유저가 HTML 페이지를 왔다 갔다 하는 요청과 이미지 등의 리소스를 가져오는 요청을 구분하기 위해 사용된다고 합니다. 그러니까 HTML 문서를 요청하는 경우는 navigate, 이미지 등의 리소스를 요청하는 경우는 no-cors로 설정된다는 거죠.

no-cors 요청은 메서드가 HEAD, GET, POST 중 하나여야 하고, CORS에서 허용된 헤더 만을 사용할 수 있으며 요청의 결과로 받은 응답을 javascript 등에서 접근할 수 없다고 합니다.

이제 제가 왜 갑자기 no-cors 이야기를 하는지 눈치 채신 분들도 있을 겁니다. css의 background-image 속성에 S3에 업로르된 이미지가 url로 지정되는 부분이 있었는데, 바로 여기서 그 이미지를 가져오는 요청이 no-cors 였던 겁니다!

그러니까 S3에 CORS 설정을 해줬지만 계속 CORS 오류가 발생한 거죠… 😫

해결 방법

관련해서 문제를 찾다보니 이미 관련해서 먼저 고민한 분들이 있었습니다. CloudFront 이미지 CORS 이슈 를 보면, 결론적으로 이 문제는 Origin 헤더가 누락되었기 때문에 발생한 문제였습니다. CORS 허용이 필요한 경우 요청에 대한 응답으로 Access-Control-Allow-Origin 헤더에 요청한 Origin을 포함해서 돌려줘야 하는데, S3는 요청에 Origin 헤더가 없는 경우 응답에 Access-Control-Allow-Origin 헤더를 넣어주지 않는다는 거죠!

그래서 기존에는 S3의 에셋에 직접 접근 하던걸 NCP의 CDN+로 접근하도록 변경한 다음에, CDN+가 응답 헤더에 Access-Control-Allow-Origin: *를 추가해주도록 설정해서 문제를 해결했습니다. 에셋에 접근하는 도메인이 하나가 아니었기 때문에 부득이 하게 *로 설정했지만, 그렇지 않은 경우는 명시적으로 도메인을 적어줘야 합니다.

난 잘되는데?

참고로 브라우저 마다 no-cors 를 처리하는 방법이 조금씩 다른 듯 합니다. 테스트 결과 별도의 처리 없이도 Firefox에서는 이미지를 가져오는 데 문제가 없었지만, Chrome에서는 문제가 발생했습니다.

참고 자료

How to Terraform(7) - 코드 중복 최소화하기

Sat, 16 Dec 2023 14:09:14 +0900

시리즈 목차

이전 글에서 우리는 모듈을 활용하여 코드를 재사용하는 방법을 알아봤습니다. 그 결과 동일한 리소스에 대해서 코드 중복을 많이 줄일 수 있었죠. 그런데 여전히 중복되는 코드가 있었습니다. 각 리소스마다 프로바이더와 백엔드는 어쩔 수 없이 매번 작성해야 했습니다. 이번 글에서는 이런 중복을 최소화하는 방법을 알아보겠습니다.

Terragrunt 설치하기

Terragrunt는 Terraform의 래퍼(wrapper)로 동작하며, Terraform 코드에서 중복되는 부분을 많이 줄일 수 있도록 도와줍니다. 래퍼로 동작하기 때문에 Terraform으로 실행가능한 init, plan, apply, destroy등의 명령은 그대로 사용할 수 있습니다. 우선 Terragrunt를 설치해볼까요?

Homebrew로 설치하기

리눅스와 맥에서는 Homebrew를 사용해서 Terragrunt를 설치할 수 있습니다.

> brew install terragrunt
> terragrunt --version
terragrunt version 0.54.5

Terraform과 Terragrunt는 다음과 같이 alias로 등록하여 각각 tf, tg로 사용할 수 있습니다.
alias tf="terraform"
alias tg="terragrunt"

Terragrunt 설정하기

먼저 이전 글에서 작업하던 폴더 구조를 다시 확인해볼까요?

terraform-live
└── dev
 └── ec2
 ├── service1
 | ├── main.tf
 | └── outputs.tf
 └── service2
 ├── main.tf
 └── outputs.tf

terraform-modules 리포지토리에 정의되어 있는 모듈을 참조하여 service1, service2를 정의했었습니다. 각 서비스의 main.tf 파일에는 다음과 같은 내용이 공통으로 존재했습니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

...

Terragrunt로 이 중복을 제거해보겠습니다.

terraform-live/terragrunt.hcl 파일을 생성하고 다음과 같이 작성합니다.

generate "providers" {
 path = "providers.tf"
 if_exists = "overwrite_terragrunt"
 contents = <<EOF
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}
EOF
}

그리고 service1의 모든 파일을 삭제하고 terragrunt.hcl 파일을 생성하고 다음과 같이 작성합니다.

terraform {
 source = "github.com/netscout/terraform-modules//modules/ec2?ref=v0.0.1"
}

include {
 path = find_in_parent_folders()
}

inputs = {
 env = "dev"
 port = 8080
}

현재까지의 내용을 정리해보자면, 폴더 구조는 다음과 같습니다.

terraform-live
├── terragrunt.hcl
└── dev
 └── ec2
 ├── service1
 | └── terragrunt.hcl
 └── service2
 ├── main.tf
 └── outputs.tf

그리고 Terragrunt의 plan 명령을 실행합니다. 참고로, Terragrunt는 plan 명령을 실행 할 때, init 명령을 자동으로 실행합니다.

> cd dev/ec2/service1
> tg plan
...
Plan: 2 to add, 0 to change, 0 to destroy.

Changes to Outputs:
 + public_ip = (known after apply)
...

provider 설정이 없는데도 정상적으로 동작합니다. 그리고 outputs.tf가 없어졌는데도 출력값을 확인할 수 있습니다. 어떻게 가능한지 확인해볼까요? service1 폴더를 다시 확인해보면, .terragrunt-cache 폴더가 생성되어 있습니다. 이 폴더에는 Terragrunt가 실행될 때 자동으로 생성된 Terraform 코드가 저장되어 있습니다. 폴더 구조를 볼까요?

service1
├── .terragrunt-cache
│ └── lIQuDV1aWBSG5nm4zKCulAdnsus
│ └── modules
│ └── ec2
│ ├── main.tf
│ ├── outputs.tf
│ ├── providers.tf
│ └── variables.tf
└── terragrunt.hcl

다른 파일들이 있긴 하지만, 핵심만 추리면 이렇습니다. 그러니까 모듈로 선언된 Terraform 코드가 그대로 다운로드 되어 있고, providers.tf 파일이 새로 생성되어 있습니다. 이 파일의 내용을 보면 다음과 같습니다.

# Generated by Terragrunt. Sig: nIlQXj57tbuaRZEa
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

provider 설정 없이도 plan 명령이 정상적으로 동작한 이유가 뭔지 이제 알 수 있죠? Terragrunt가 자동으로 생성해준 코드를 통해 provider 설정이 추가되었기 때문입니다. 다시 terraform-live/terragrunt.hcl 파일의 내용을 확인해볼까요?

generate "providers" {
 path = "providers.tf"
 if_exists = "overwrite_terragrunt"
 contents = <<EOF
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}
EOF
}

providers.tf 파일을 생성하도록 설정하였고, 파일이 존재한다면 덮어쓰도록 했습니다. 그리고 파일의 내용은 provider 블록을 통해 aws 프로바이더를 정의해두었습니다. 그래서 tg plan명령이 실행 될 때 Terragrunt가 providers.tf 파일을 생성하고, 이 파일을 통해 provider 설정이 추가되었던 것입니다.

좀 더 복잡한 경우

겨우 이 몇 줄의 코드 때문에 Terragrunt를 써야 하는 거냐고 생각하실 수도 있지만 이 코드는 좀 더 길어질 수도 있습니다. 예를 들어 프로바이더 설정과 백엔드 설정을 추가한다면 어떻게 될까요?

# terragrunt가 각 모듈에 대해서 backend.tf를 생성한다.
remote_state {
 backend = "s3"

 generate = {
 path = "backend.tf"
 if_exists = "overwrite"
 }

 config = {
 bucket = "terraform-state-example-20231216"
 # 상태 파일이 저장될 경로
 key = "${path_relative_to_include()}/terraform.tfstate"
 region = "ap-northeast-2"

 # 상태 파일을 락으로 사용할 DynamoDB 테이블
 dynamodb_table = "terraform_locks"
 # 상태 파일을 암호화
 encrypt = true
 }
}

generate "providers" {
 path = "providers.tf"
 if_exists = "overwrite_terragrunt"
 contents = <<EOF
terraform {
 # 필요한 프로바이더 목록과 버전 정보
 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "~> 5.0" # 5.0 이상 버전 사용
 }
 }
}

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}
EOF
}

remote_state 블록에는 모든 Terraform 리소스에 적용될 backend 설정을 정의했습니다. config 속성의 내용은 기존의 backend 속성의 내용을 그대로 옮긴 것이며, generate 속성에는 backend.tf 파일을 생성하고 기존에 존재하는 경우 덮어쓰도록 설정했습니다. 자세히 보시면 config.key 속성이 기존과 다릅니다.

key = "${path_relative_to_include()}/terraform.tfstate"

즉, 현재 이 파일의 위치를 기준으로 해서 Terragrunt 명령이 실행되는 폴더의 경로를 가져오도록 했습니다. 만약 dev/ec2/service1 폴더에서 tg plan 명령을 실행한다면, key 값은 dev/ec2/service1/terraform.tfstate가 됩니다. 매번 리소스를 정의할 때 마다 폴더 경로를 key 값으로 수정하지 않아도 알아서 해준다는 거죠!

그리고 generate 블록에는 프로바이더 버전 정보를 추가했습니다. 이렇게 하면 모든 리소스에 대해서 프로바이더 버전을 일괄적으로 관리할 수 있습니다.

정리

이제 Terraform을 통해 IaC를 구현하는 방법의 기초적인 내용은 모두 알아보았습니다. 익숙해지기 전에는 예전에 하던 것 처럼 수작업으로 일일이 리소스를 생성하는 게 훨씬 빠르다는 생각도 들게 됩니다. 하지만, 한 번 잘 설정해두면 속도가 빨라지는 것 뿐만 아니라 리소스의 변경을 추적할 수 있고, 리소스를 정리할 때도 커맨드 한 번으로 정리할 수 있게 됩니다. 지금까지 읽어주셔서 감사드리며, 도움이 되셨기를 바랍니다.

참고자료

License

저작자표시-비영리-변경금지 2.0 대한민국 (CC BY-NC-ND 2.0 KR)

How to Terraform(6) - 모듈 버전관리

Sat, 09 Dec 2023 14:04:13 +0900

시리즈 목차

이전 글에서는 모듈을 활용해서 반복되는 리소스를 재사용 가능한 형태로 정의하는 방법을 알아봤습니다. 그런데 모듈로 재사용성을 높이는 건 좋지만, 문제가 있긴 했습니다. 모듈을 업데이트해야 하는 경우, 이미 모듈을 사용해서 생성된 리소스 역시 업데이트되는 모듈의 영향을 받게 된다는 점입니다. 모듈을 업데이트 하되 기존 리소스는 기존 모듈을 그대로 사용할 수 있도록 하위호환성을 도입하려면 어떻게 해야 할까요?

Git 으로 모듈 버전 관리하기

여기서는 Git을 이용해서 모듈의 버전을 관리하고, 리소스도 각 모듈의 버전을 지정해서 참조하도록 해서 모듈과 리소스 간의 의존성을 관리하는 방법을 알아보겠습니다. 이렇게 하면 모듈을 업데이트할 때 기존 리소스에 영향을 주지 않으면서도 모듈을 업데이트할 수 있습니다. Git으로 모듈 버전을 관리하려면 2개의 Git 리포지토리가 필요합니다. 하나는 모듈을 관리하는 리포지토리, 또 하나는 모듈을 사용하여 리소스를 정의하는 리포지토리입니다. 우선 모듈을 관리하는 리포지토리를 만들어 보겠습니다.

모듈 리포지토리 만들기

모듈을 관리하는 리포지토리를 terraform-modules, 모듈을 사용해서 리소스를 관리하는 리포지토리를 terraform-live라고 가정하고 진행하겠습니다. 먼저 terraform-modules 리포지토리를 생성하고, 이전 글에서 작성했던 EC2 인스턴스 모듈을 이 리포지토리에 옮깁니다. 폴더 구조는 다음과 같습니다.

terraform-modules
└── modules
 └── ec2
 ├── main.tf
 ├── outputs.tf
 └── variables.tf

그리고 이 리포지토리를 GitHub에 푸시합니다. 그리고 다음 명령을 통해 모듈의 버전을 태그합니다.

> git tag -a v0.0.1 -m "EC2 모듈 추가"

~/src/terraform-modules main
> git push --follow-tags
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 185 bytes | 185.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/netscout/terraform-modules.git
 * [new tag] v0.0.1 -> v0.0.1

만약 이전 커밋에 지정된 태그를 삭제하고 싶다면 git tag -d v0.0.1의 형태로 명령을 사용하고 새로운 커밋에 다시 태그를 붙이면 됩니다. 이미 태그를 푸시한 상태라면 git push --delete origin v0.0.1 명령을 사용하면 됩니다.

모듈 리포지토리 참조하기

EC2 모듈의 첫 버전을 v0.0.1로 태그 했습니다. 이제 리소스 리포지토리를 만들어서 이 모듈을 참조해보겠습니다. 우선 terraform-live라는 리포지토리를 생성하고, 이전 글에서 작성했던 EC2 인스턴스 리소스를 이 리포지토리로 옮겨줍니다. 폴더 구조는 다음과 같습니다.

terraform-live 폴더 안에 dev 폴더를 만들고, 그 안에 ec2 폴더를 만들고, service1 폴더를 만들어서 EC2 인스턴스 리소스를 옮겨줍니다.

terraform-live
└── dev
 └── ec2
 └── service1
 ├── main.tf
 └── outputs.tf

이전 글에서 작성한 main.tf는 로컬에 있는 모듈을 참조하도록 설정되어 있습니다. 로컬 대신에 Git의 모듈 리포지토리를 참조하도록 변경하겠습니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

// 모듈 사용
module "ec2" {
 //source = "../../modules/ec2"
 source = "github.com/netscout/terraform-modules//modules/ec2?ref=v0.0.1"

 // 모듈에 전달할 인자
 env = "dev"
 port = 8080
}

source 속성을 자세히 보시면 중간에 //가 들어가 있습니다. //의 앞쪽에는 모듈이 저장된 git 리포지토리의 주소를, 그리고 뒤 쪽에는 모듈의 경로와 태그로 지정된 버전을 명시합니다. 모듈을 참조하기 위한 Terraform 코드 작성은 완료됐지만 아직 한 가지 더 검토해야 할 게 남아있습니다.

Terraform 에게 Git 리포지토리 접근 허용해주기

아마도 모듈 리포지토리는 private 리포지토리로 생성되었을 겁니다. 회사에서 작업하는 모듈에 대한 정의를 public 하게 공개할 수는 없기 때문이죠. 그렇다면 Terraform이 private 리포지토리에 접근할 수 있는 방법을 알려줘야 합니다.

SSH 키 생성 및 등록하기

Terraform이 모듈 리포지토리를 참조하기 위해서 SSH 키를 생성해서 github에 등록해야 합니다. 여기서는 ed25519 알고리즘을 사용해서 키를 생성하겠습니다. ed25519는 rsa보다 보안이 더 강화된 알고리즘으로, 최근에는 ed25519를 사용하는 것을 권장하고 있습니다. 다음 명령을 실행하여 키를 생성합니다.

# "your_email@example.com" 대신에 github 이메일 주소를 입력하세요.
> ssh-keygen -t ed25519 -C "your_email@example.com"
# ssh-agent를 실행하여, 키를 등록한다.
> eval "$(ssh-agent -s)"
> ssh-add ~/.ssh/id_ed25519

그리고 생성된 키의 내용을 클립보드에 복사한 후, 그 내용을 github에 등록합니다. 키의 내용을 클립보드에 복사하려면 ubuntu에서는 xclip을 사용하고,

> cat ~/.ssh/id_ed25519.pub | xclip -selection clipboard

mac에서는 pbcopy를 사용하면 됩니다.

> cat ~/.ssh/id_ed25519.pub | pbcopy

이제 클립보드에 복사된 키를 github에 등록할 차례입니다. github에 접속하고 우측 상단의 아바타 버튼을 누르고 Settings > SSH and GPG keys > New SSH key를 클릭합니다.

Title에는 키를 등록하는 컴퓨터의 이름을 적고, Key에는 위에서 복사한 키를 붙여넣으면 완료입니다. 그러면 모듈을 잘 참조하는지 확인해볼까요?

> cd dev/ec2/service1
> tf init
Initializing the backend...
Initializing modules...
Downloading git::https://github.com/netscout/terraform-modules.git?ref=v0.0.1 for ec2...
- ec2 in .terraform/modules/ec2/modules/ec2

...
Terraform has been successfully initialized!
...

정상적으로 잘 참조하고 있습니다! 이제 모듈을 업데이트 해볼까요?

모듈 업데이트하기

모듈 리포지토리의 EC2 모듈을 업데이트 해보겠습니다. modules/ec2/main.tf 파일을 열고, locals의 변수 정의를 수정하고 aws_security_group.sg 리소스에 ssh 접속을 위한 인바운트 규칙을 추가합니다.

// 로컬 변수 정의
locals {
 // EC2 인스턴스에 할당할 태그
 security_group_name = "${var.name}-${var.env}"
}

resource "aws_instance" "ec2" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = var.ami_id # 변수 ami_id 참조
 instance_type = var.instance_type

 vpc_security_group_ids = [aws_security_group.sg.id]

 // 최초 인스턴스 생성 시에만 실행
 user_data = <<-EOF
 #!/bin/bash
 echo "Hello, World" > index.html
 nohup busybox httpd -f -p ${var.port} &
 EOF

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_security_group" "sg" {
 name = local.security_group_name

 // 인바운드 규칙
 ingress {
 from_port = var.port
 to_port = var.port
 protocol = "tcp"
 cidr_blocks = var.cidr_blocks
 }

 // ssh 접속을 위한 인바운드 규칙(새로 추가)
 ingress {
 from_port = 22
 to_port = 22
 protocol = "tcp"
 cidr_blocks = var.cidr_blocks
 }
}

다음으로 variables.tf 파일을 열고, name 변수를 추가합니다.

// name 변수 추가
variable "name" {
 type = string
}

variable "env" {
 type = string
 // 변수 값이 "dev", "stg", "prod" 중에 하나로 설정되야함
 validation {
 condition = contains(["dev", "stg", "prod"], var.env)
 error_message = "env must be one of dev, stg, prod"
 }
}

variable "ami_id" {
 type = string
 default = "ami-0c6e5afdd23291f73"
}

variable "instance_type" {
 type = string
 default = "t2.micro"
}

variable "port" {
 type = number
}

variable "cidr_blocks" {
 type = list(string)
 default = ["0.0.0.0/0"]
}

그리고 변경 내용을 커밋하고, 모듈 리포지토리를 푸시, 그리고 태그를 추가합니다.

> git tag -a v0.0.2 -m "EC2에 SSH 인바운드 규칙 추가"
> git push --follow-tags
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 207 bytes | 207.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0), pack-reused 0
To https://github.com/netscout/terraform-modules.git
 * [new tag] v0.0.2 -> v0.0.2

업데이트된 모듈 참조하기

이제 업데이트된 모듈을 참조해보겠습니다. terraform-live/dev/ec2/service2 폴더를 추가하고, terraform-live/dev/ec2/service1 폴더에 작성된 main.tf, outputs.tf 파일을 복사해서 붙여넣습니다. 그리고 service2 폴더에 있는 main.tf 파일을 열고, 다음과 같이 모듈의 버전을 v0.0.2로 변경하고 name 변수에 인자를 할당합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

// 모듈 사용
module "ec2" {
 //source = "../../modules/ec2"
 source = "github.com/netscout/terraform-modules//modules/ec2?ref=v0.0.2"

 // 모듈에 전달할 인자
 name="service2"
 env = "dev"
 port = 8080
}

init 명령을 실행해서 모듈 참조를 확인합니다.

> cd dev/ec2/service2
> tf init
Initializing the backend...
Initializing modules...
Downloading git::https://github.com/netscout/terraform-modules.git?ref=v0.0.2 for ec2...
- ec2 in .terraform/modules/ec2/modules/ec2
...

v0.0.2 버전의 모듈의 정상적으로 참조하고 있죠? v0.0.1을 참조하는 service1을 다시 확인해볼까요?

# 모듈 다시 업데이트 하기
> tf get -update
> tf plan
...

service1의 리소스 정의에는 모듈 v0.0.2에서 새로 추가된 name 변수가 지정되어 있지 않지만, name 변수가 아직 추가되지 않는 v0.0.1을 참조하고 있기 때문에 모듈의 버전 변경과 관계없이 잘 동작하는 걸 확인할 수 있습니다.

정리

Git으로 모듈의 버전을 관리하면 모듈이 변경되더라도 이전에 생성된 리소스에는 영향을 주지 않고 안전하게 모듈을 업데이트할 수 있습니다. 점점 좋아지고 있죠? 그런데 여전히 중복은 남아있습니다. service1과 service2 에는 각각 provider에 대한 정의가 있습니다. 그리고 여기서는 backend를 사용하지 않았지만, S3같은 backend를 사용하면 그 설정 역시 각 리소스에 중복해서 들어가게 될 겁니다. 다음에는 이런 중복을 제거할 수 있는 방법을 알아보겠습니다.

참고자료

Terraform Up and Running, 3rd Edition

License

저작자표시-비영리-변경금지 2.0 대한민국 (CC BY-NC-ND 2.0 KR)

How to Terraform(5) - 모듈

Sat, 02 Dec 2023 13:47:25 +0900

시리즈 목차

Terraform을 사용하다보면 동일한 유형의 리소스를 여러번 생성해야 할 때가 있습니다. 예를 들면 개발, 스테이징, 운영 환경을 각각 분리된 EC2 인스턴스로 생성한다고 했을 때, 거의 동일한 EC2 인스턴스를 리소스로 정의하게 되겠죠. 지금까지는 동일한 코드를 복사해서 붙여넣는 방식으로 각 리소스를 정의했습니다. 그런데 이렇게 하면 EC2 인스턴스의 설정이 복잡해지고, 개수가 많아질 수록 중복되는 코드의 양이 늘어나겠죠? 만약 기존에 정의된 EC2 인스턴스의 AMI를 변경해야 한다면, 모든 코드를 찾아서 일일이 변경해야만 할 겁니다. 그리고 이렇게 하다 보면 실수할 확률이 높아지겠죠?

이렇게 동일한 리소스를 반복해서 사용해야 하는 경우, 리소스의 공통적인 내용을 재사용 가능한 형태로 정의해놓고 필요할 때마다 참조해서 사용하되, 바뀌는 부분만 따로 명시해줄 수 있으면 좋을 겁니다. 이런 재사용 가능한 형태로 정의된 리소스를 모듈이라고 합니다.

모듈이란?

Terraform 모듈은 동일한 유형의 리소스를 여러 번 생성할 때, 코드를 중복해서 작성하지 않도록 재사용 가능한 형태로 정의할 수 있습니다. 프로그래밍 언어에서는 함수나 클래스를 떠올려보시면 비슷합니다. 자 그럼 우선 모듈을 사용하기 전에 중복해서 리소스를 정의하는 코드를 먼저 확인해볼까요?

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

// 개발 환경 EC2 인스턴스
resource "aws_instance" "example_dev" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"

 vpc_security_group_ids = [aws_security_group.example_dev.id]

 // 최초 인스턴스 생성 시에만 실행
 user_data = <<-EOF
 #!/bin/bash
 echo "Hello, World" > index.html
 nohup busybox httpd -f -p 8080 &
 EOF

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_security_group" "example_dev" {
 name = "terraform-example"

 // 인바운드 규칙
 ingress {
 from_port = 8080
 to_port = 8080
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

// 스테이징 환경 EC2 인스턴스
resource "aws_instance" "example2_stg" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"

 vpc_security_group_ids = [aws_security_group.example_stg.id]

 // 최초 인스턴스 생성 시에만 실행
 user_data = <<-EOF
 #!/bin/bash
 echo "Hello, World" > index.html
 nohup busybox httpd -f -p 8080 &
 EOF

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_security_group" "example_stg" {
 name = "terraform-example-stg"

 // 인바운드 규칙
 ingress {
 from_port = 8080
 to_port = 8080
 protocol = "tcp"
 cidr_blocks = ["0.0.0.0/0"]
 }
}

개발 환경과 스테이징 환경에서 동작할 EC2 인스턴스를 2개 정의해놓았습니다. 대부분의 코드가 중복되어 있죠? 간단한 코드지만 계속해서 늘어난다고 생각하면 좀 별로이긴합니다. 그러면 일단 중복을 제거할 수 있도록 모듈을 작성해보겠습니다. modules/ec2 폴더를 만들고, 그 안에 ec2 폴더를 만들어서 main.tf 파일을 생성합니다.

// 로컬 변수 정의
locals {
 // EC2 인스턴스에 할당할 태그
 security_group_name = "terraform-example-${var.env}"
}

resource "aws_instance" "ec2" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = var.ami_id # 변수 ami_id 참조
 instance_type = var.instance_type

 vpc_security_group_ids = [aws_security_group.sg.id]

 // 최초 인스턴스 생성 시에만 실행
 user_data = <<-EOF
 #!/bin/bash
 echo "Hello, World" > index.html
 nohup busybox httpd -f -p ${var.port} &
 EOF

 tags = {
 Name = "terraform-example"
 }
}

resource "aws_security_group" "sg" {
 name = local.security_group_name

 // 인바운드 규칙
 ingress {
 from_port = var.port
 to_port = var.port
 protocol = "tcp"
 cidr_blocks = var.cidr_blocks
 }
}

그리고 variables.tf 파일을 생성해서 변수를 정의합니다.

variable "env" {
 type = string
 // 변수 값이 "dev", "stg", "prod" 중에 하나로 설정되야함
 validation {
 condition = contains(["dev", "stg", "prod"], var.env)
 error_message = "env must be one of dev, stg, prod"
 }
}

variable "ami_id" {
 type = string
 default = "ami-0c6e5afdd23291f73"
}

variable "instance_type" {
 type = string
 default = "t2.micro"
}

variable "port" {
 type = number
}

variable "cidr_blocks" {
 type = list(string)
 default = ["0.0.0.0/0"]
}

마지막으로 outputs.tf 파일을 생성해서 EC2 인스턴스의 public IP 주소를 출력하도록 설정합니다.

output "public_ip" {
 value = aws_instance.ec2.public_ip
}

이제 모듈을 사용하는 코드를 작성해보겠습니다. dev/ec2 폴더에 main.tf 파일을 생성하고, 다음과 같이 작성합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

// 모듈 사용
module "ec2" {
 // 모듈의 소스 경로 지정
 source = "../../modules/ec2"

 // 모듈에 전달할 인자
 env = "dev"
 port = 8080
}

모듈의 소스 경로를 상대 경로로 지정해주고, 모듈에 전달하고 싶은 변수를 지정해줍니다. 그리고 stg/ec2 폴더에도 main.tf 파일을 생성하고, 다음과 같이 작성합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

// 모듈 사용
module "ec2" {
 source = "../../modules/ec2"

 // 모듈에 전달할 인자
 env = "stg"
 port = 8080
}

그리고 모듈의 output을 이용해서 EC2 인스턴스의 public IP 주소를 출력하도록 outputs.tf 파일을 생성합니다.

output "public_ip" {
 value = module.ec2.public_ip
}

참고로 폴더 구조는 다음과 같습니다.

.
├── modules
│ └── ec2
│ ├── main.tf
│ └── variables.tf
| └── outputs.tf
├── dev
│ └── ec2
│ └── main.tf
│ └── outputs.tf
└── stg
 └── ec2
 └── main.tf
 └── outputs.tf

우선 dev/ec2 폴더에서 tf init 명령을 실행합니다.

terraform이라고 매번 입력하는게 어려우니 .zshrc나 .bashrc에 다음과 같이 alias 설정을 해서 tf로 사용하는 것도 방법입니다.
alias tf=terraform

> cd dev/ec2
> tf init

Initializing the backend...
Initializing modules...
- ec2 in ../../modules/ec2

Initializing provider plugins...
...

가장 먼저 지정된 모듈의 소스 경로에서 모듈을 가져와서 초기화 하는 걸 확인할 수 있죠? 그리고 tf plan 명령을 실행해볼까요?

참고로 모듈을 수정한 다음에 수정된 모듈을 반영하려면 tf get -update명령을 실행해야 합니다.

> tf plan
...
Plan: 2 to add, 0 to change, 0 to destroy.

Changes to Outputs:
 + public_ip = (known after apply)
...

> tf apply
...
Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Outputs:

public_ip = "..."

모듈에 설정된 내용대로 인스턴스가 생성되었고, 모듈의 출력으로 설정된 public_ip도 출력을 확인할 수 있습니다. 이제 stg/ec2 폴더에서도 동일한 명령을 실행해서 인스턴스를 추가로 생성할 수 있습니다.

정리

모듈을 활용하면 코드의 중복을 줄일 수 있으며, 수작업으로 인해 실수를 방지할 수 있습니다. 하지만 모듈은 또 다른 단점을 가지고 있습니다. 모듈을 수정하게 되면 모듈을 참조하는 모든 리소스의 상태 관리에 영향을 미친다는 점입니다. 어떻게 하면 모듈을 업데이트하면서도 특정 리소스는 이전 모듈을 참조하고, 특정 리로스는 새로 업데이트된 모듈을 참조하도록 할 수 있을까요? 다음 시간에는 그 방법을 알아보겠습니다!

참고자료

Terraform Up and Running, 3rd Edition

License

저작자표시-비영리-변경금지 2.0 대한민국 (CC BY-NC-ND 2.0 KR)

How to Terraform(4) - 상태관리 개선하기

Sat, 25 Nov 2023 14:14:54 +0900

시리즈 목차

이전 글에서는 Terraform의 상태에 대해 알아보았고, 로컬 파일로 관리할 때의 단점을 해결하기 위해서 상태를 S3에 저장하는 방법을 알아보았습니다. 하지만 여전히 문제가 남아있었습니다. 그 문제가 뭐였는지 알아볼까요?

현재 상태관리의 문제점

이전 글에서는 모든 테라폼 리소스가 한 개의 상태 파일로 관리되고 있었습니다. 예시를 위해서 새로 폴더를 만들고 다음 코드를 main.tf에 작성합니다.

일단 예시를 위해서 S3를 사용하지 않고 로컬 파일을 사용합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"
}

그리고 init, plan, apply 명령을 실행합니다.

terraform이라고 매번 입력하는게 어려우니 .zshrc나 .bashrc에 다음과 같이 alias 설정을 해서 tf로 사용하는 것도 방법입니다.
alias tf=terraform

> tf init
...
Terraform has been successfully initialized!
...

> tf plan
...
Plan: 1 to add, 0 to change, 0 to destroy.
...

> tf apply
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

자 여기까지는 뭐 기존과 다를 게 하나도 없습니다. 여기에 두번째 EC2 인스턴스를 추가해볼까요?

//main.tf 기존 코드...

resource "aws_instance" "example2" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"
}

그리고 다시 plan을 실행해봅니다.

> tf plan
aws_instance.example: Refreshing state... [id=i-00c12ab694ff80dfa]

...
Plan: 1 to add, 0 to change, 0 to destroy.
...

두번째 EC2 인스턴스를 추가할 때 우리의 관심사는 aws_instance.example2 리소스 입니다. 하지만 plan 명령을 실행하자 이미 추가된 리소스인 aws_instance.example에 대한 검사가 먼저 진행되었죠? aws_instance.example 리소스가 aws_instance.example2 리소스와 하나의 상태 파일로 관리되고 있기 때문에 Terraform으로서는 어쩔 수 없이 상태 파일의 내용과 테라폼 코드의 리소스를 모두 비교할 수 밖에 없는 거죠. EC2 인스턴스 몇 개는 금방 끝나니까 별 문제가 아닐 수 있지만, 이런 식으로 리소스가 계속 늘어나다 보면 어느새 plan 한번 실행하는데 몇 분이 걸리는 일도 발생할 수 있습니다.

그리고 좀 더 복잡한 문제가 생기는 경우도 있습니다. 만약 반드시 변수로 입력받아야 하는 값이 있다고 생각해볼까요? 테라폼 코드에 작성된 상당수의 리소스가 환경변수 등을 통해서 변수를 입력받아야 한다면 어떨까요? 내가 관심 있는 리소스 하나 작업하기 위해서 모든 변수 값을 제대로 설정해야만 하는 문제가 발생합니다. 정리해보자면,

여러 리소스가 하나의 상태 파일로 관리되기 때문에, 리소스가 추가됨에 따라 상태 파일이 점점 거대해진다.
따라서 새로 추가하는 리소스에 대한 plan, apply 명령에도 기존에 관리되고 있는 모든 리소스에 대한 검사가 진행되므로 시간이 점점 더 오래걸린다.
모든 리소스가 하나의 상태 파일로 관리되면 다른 사람이 일부 리소스를 변경했을 때 변경된 상태 값 역시 공유된다. 만약 다른 사람이 변경한 테라폼 코드를 업데이트 받지 않은 상태에서 내 작업을 진행하면 리소스의 상태를 다시 변경 이전 상태로 되돌리는 등의 예상치 못한 오류가 발생할 수 있다.

이러한 문제를 해결하기 위해서는 각 리소스에 대한 상태를 최대한 작게 나눠서 관리하는 게 좋을 것 같습니다. 나눠서 관리한다는 게 생각보다 별 거 없습니다. 그냥 폴더를 쪼개면 됩니다.

폴더로 나눠서 관리하기

S3 백엔드와 EC2 인스턴스 2개를 만드는 상황을 가정하면 폴더는 대강 이렇게 나눌 수 있습니다.

.
├── global
│ └── s3
│ └── main.tf
├── dev
│ └── ec2
│ └── example
│ └── main.tf
│ └── example2
│ └── main.tf

우선 global 폴더에는 S3 백엔드를 생성하는 코드를 작성합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

# S3 버킷 생성
resource "aws_s3_bucket" "terraform_state" {
 bucket = "terraform-state-example-20231125"

 # 실수로 버킷이 삭제되지 않도록 하려면 아래 주석을 해제하세요.
 # lifecycle {
 # prevent_destroy = true
 # }
}

# 버킷 버전 관리 활성화(상태 파일의 히스토리를 관리하기 위함)
resource "aws_s3_bucket_versioning" "enabled" {
 bucket = aws_s3_bucket.terraform_state.id

 versioning_configuration {
 status = "Enabled"
 }
}

# S3에 저장될 때 암호화 하도록 설정
resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
 bucket = aws_s3_bucket.terraform_state.id

 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

# 모든 public access를 차단(실수로 버킷이 공개되지 않도록 하기 위함)
resource "aws_s3_bucket_public_access_block" "public_access" {
 bucket = aws_s3_bucket.terraform_state.id

 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

# 여러 사람이 동시에 상태 파일을 수정하지 못하도록 DynamoDB를 사용한 락 설정
resource "aws_dynamodb_table" "terraform_locks" {
 name = "terraform_locks"
 billing_mode = "PAY_PER_REQUEST"
 hash_key = "LockID"

 attribute {
 name = "LockID"
 type = "S"
 }
}

그리고 우선 init, plan, apply 를 실행해서 백엔드 설정을 위한 S3 버킷을 생성합니다.

참고로, VS Code에서는 cd 명령 대신에 폴더에 우클릭하고 통합 터미널에서 열기를 선택하면 해당 폴더로 터미널이 이동합니다.

> cd global/s3
> tf init
...
Terraform has been successfully initialized!
...

> tf plan
...
Plan: 5 to add, 0 to change, 0 to destroy.
...

> tf apply
...
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

그리고 생성된 S3에 현재 생성된 리소스의 상태를 저장하기 위해서 main.tf상단에 다음 코드를 추가합니다.

terraform {
 # 필요한 프로바이더 목록과 버전 정보
 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "~> 5.0" # 5.0 이상 버전 사용
 }
 }

 # 상태 파일을 S3에 저장하도록 설정
 backend "s3" {
 bucket = "terraform-state-example-20231125"
 # 상태 파일이 저장될 경로
 key = "global/s3/terraform.tfstate"
 region = "ap-northeast-2"

 # 상태 파일을 락으로 사용할 DynamoDB 테이블
 dynamodb_table = "terraform_locks"
 # 상태 파일을 암호화
 encrypt = true
 }
}

// main.tf 기존 코드...

여기서 주목해야 할 점은 상태 파일이 저장될 경로를 리소스 파일이 정의된 폴더 경로와 일치하도록 설정했다는 점입니다. 이렇게 하면 리로스와 상태 파일의 경로가 일치하므로 상태 파일을 덮어쓴다던지 하는 오류를 피할 수 있습니다. 이제 init 명령을 통해 벡엔드를 설정하겠습니다.

> tf init
Initializing the backend...
Do you want to copy existing state to the new backend?
 Pre-existing state was found while migrating the previous "local" backend to the
 newly configured "s3" backend. No existing state was found in the newly
 configured "s3" backend. Do you want to copy this state to the new "s3"
 backend? Enter "yes" to copy and "no" to start with an empty state.

 Enter a value: yes


Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
...

콘솔에서 S3를 확인해보면,

지정된 경로에 상태 파일이 생성된 것을 확인할 수 있습니다.

이렇게 리소스 별로 상태를 관리할 때 아무래도 자주 관리하지 않는 리소스가 생기기 마련입니다. 시간이 한참 지나서 다시 관리를 해야 할 때, 이전에 사용하던 프로바이더의 버전과 현재 버전이 차이가 많이 날 수도 있겠죠. 그럴 때 기존에 작성한 코드가 제대로 동작하지 않는 문제가 생길 수도 있으므로 프로바이더의 버전을 명시하는 것도 좋은 방법입니다!

이제 dev/ec2/example/main.tf 파일을 생성하고 다음 코드를 작성합니다.

terraform {
 # 필요한 프로바이더 목록과 버전 정보
 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "~> 5.0" # 5.0 이상 버전 사용
 }
 }

 # 상태 파일을 S3에 저장하도록 설정
 backend "s3" {
 bucket = "terraform-state-example-20231125"
 # 상태 파일이 저장될 경로
 key = "dev/ec2/example/terraform.tfstate"
 region = "ap-northeast-2"

 # 상태 파일을 락으로 사용할 DynamoDB 테이블
 dynamodb_table = "terraform_locks"
 # 상태 파일을 암호화
 encrypt = true
 }
}

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

resource "aws_instance" "example" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"
}

그리고 역시 dev/ec2/example 폴더에서 init, plan, apply 명령을 실행합니다.

> cd dev/ec2/example
> tf init
...
Terraform has been successfully initialized!
...

> tf plan
...
Plan: 1 to add, 0 to change, 0 to destroy.
...

> tf apply
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

그리고 dev/ec2/example2/main.tf 파일을 생성하고 동일한 과정으로 EC2 인스턴스를 추가할 수 있습니다.

정리

이제 우리는 각 리소스에 대해 개별적으로 상태 관리를 진행할 수 있습니다. 리소스는 각각의 상태를 가지므로 다른 리소스에 대해 신경쓰지 않고 관리할 수 있고, 특히 새로운 리소스를 추가할 때 역시 기존 리소스의 상태에 대해서 전혀 신경쓰지 않아도 됩니다. 다만 역시나 한 가지 마음에 걸리는 게 있습니다. EC2 인스턴스를 작성 할 때 저희는 동일한 코드를 복붙해서 새로운 인스턴스를 생성했었죠. 사실 지금은 EC2에 별다른 설정을 하지 않아서 뭐 복잡할 건 없습니다만, VPC등의 설정에 따라서는 EC2도 매우 복잡해질 수 있고 저희가 Terraform으로 EC2만 관리할 것도 아니기 때문에 이 부분은 더 나은 방법이 필요해보입니다. 다음 글에서는 모듈을 통해 중복을 줄이는 방법을 알아보겠습니다.

참고자료

Terraform Up and Running, 3rd Edition

License

저작자표시-비영리-변경금지 2.0 대한민국 (CC BY-NC-ND 2.0 KR)

How to Terraform(3) - 상태 관리

Sat, 18 Nov 2023 15:28:03 +0900

시리즈 목차

상태라니 무슨 상태?

상태가 뭔지 설명하기 전에 간단한 실험을 해보죠! 새로운 폴더를 생성하고 아래 코드를 main.tf에 추가하겠습니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

그리고 tf init을 실행해봅시다.

terraform이라고 매번 입력하는게 어려우니 .zshrc나 .bashrc에 다음과 같이 alias 설정을 해서 tf로 사용하는 것도 방법입니다.
alias tf=terraform

> tf init

Initializing the backend...

Initializing provider plugins...
...

Terraform has been successfully initialized!
...

맨 처음에 backend라는 표현이 등장합니다. 이게 웹 어플리케이션도 아닌데 backend는 뭘 말하는 걸까요~? 일단은 궁금증을 뒤로 하고 tf plan을 실행해봅시다.

> tf plan
No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration and found no differences, so no changes
are needed.

아무 것도 바꿀 게 없다고 합니다. 리소스를 하나도 선언하지 않았으니 당연하겠죠. 그런데 여기서 tf apply를 실행해볼까요?

> tf apply
No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration and found no differences, so no changes
are needed.

Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

바꿀건 하나도 없지만 apply 명령이 완료되었습니다. 그런데 apply 명령을 실행한 폴더를 확인해보시면, terraform.tfstate라는 파일이 생겼습니다! 파일을 확인 해보면 이런 내용이 있습니다.

{
 "version": 4,
 "terraform_version": "1.6.2",
 "serial": 1,
 "lineage": "2e6b0c74-0e92-bfe8-1197-36e5547d9375",
 "outputs": {},
 "resources": [],
 "check_results": null
}

이 파일에는 현재 Terraform 코드를 apply해서 구성된 리소스의 상태가 기록되고 있습니다. 즉, 가장 최근에 실행한 apply 명령을 통해 구성된 리소스의 상태(여기서는 aws 클라우드에 생성된 리소스의 상태)가 기록됩니다. 여러분이 plan 명령을 실행 할 때 뭐가 추가되고, 뭐가 수정되며 뭐가 삭제되는지를 이 파일에 기록된 현재 상태를 기준으로 판단하는 거죠. 이 파일에 포함된 속성은 다음과 같습니다.

version: Terraform의 상태 파일 형식 버전입니다. 현재는 4입니다.
terraform_version: Terraform의 버전입니다.
serial: 상태 파일이 변경될 때마다 증가하는 숫자입니다. 이 숫자는 상태 파일이 변경될 때마다 증가하며, 이 숫자를 통해 상태 파일이 변경되었는지를 판단합니다.
lineage: 상태 파일의 고유 식별자입니다. 처음 생성될 때 부여되고, 그 이후로는 변경되지 않습니다.
outputs: Terraform 코드에서 output으로 정의한 출력 값들이 기록됩니다.
resources: Terraform 코드에서 resource로 정의한 리소스들의 상태가 기록됩니다.
check_results: Terraform 코드에서 data로 정의한 데이터 소스들의 상태가 기록됩니다.

그렇다면 EC2 인스턴스를 하나 추가해서 상태 파일이 어떻게 바뀌는지 확인해봅시다! main.tf에 아래 코드를 추가합니다.

resource "aws_instance" "example" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"
}

그리고 tf plan을 실행합니다.

> tf plan
Terraform used the selected providers to generate the following execution plan. Resource actions are indicated
with the following symbols:
 + create

Terraform will perform the following actions:

 # aws_instance.example will be created
 + resource "aws_instance" "example" {
 + ami = "ami-0c6e5afdd23291f73"
 + arn = (known after apply)
 + associate_public_ip_address = (known after apply)
 + availability_zone = (known after apply)
 + cpu_core_count = (known after apply)
 + cpu_threads_per_core = (known after apply)
 + disable_api_stop = (known after apply)
 + disable_api_termination = (known after apply)
 + ebs_optimized = (known after apply)
 + get_password_data = false
 + host_id = (known after apply)
 + host_resource_group_arn = (known after apply)
 + iam_instance_profile = (known after apply)
 + id = (known after apply)
 + instance_initiated_shutdown_behavior = (known after apply)
 + instance_lifecycle = (known after apply)
 + instance_state = (known after apply)
 + instance_type = "t2.micro"
 + ipv6_address_count = (known after apply)
 + ipv6_addresses = (known after apply)
 + key_name = (known after apply)
 + monitoring = (known after apply)
 + outpost_arn = (known after apply)
 + password_data = (known after apply)
 + placement_group = (known after apply)
 + placement_partition_number = (known after apply)
 + primary_network_interface_id = (known after apply)
 + private_dns = (known after apply)
 + private_ip = (known after apply)
 + public_dns = (known after apply)
 + public_ip = (known after apply)
 + secondary_private_ips = (known after apply)
 + security_groups = (known after apply)
 + source_dest_check = true
 + spot_instance_request_id = (known after apply)
 + subnet_id = (known after apply)
 + tags_all = (known after apply)
 + tenancy = (known after apply)
 + user_data = (known after apply)
 + user_data_base64 = (known after apply)
 + user_data_replace_on_change = false
 + vpc_security_group_ids = (known after apply)
 }

Plan: 1 to add, 0 to change, 0 to destroy.

──────────────────────────────────────────────────────────────────────────────────────────────────────────────────

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions
if you run "terraform apply" now.

현재는 생성된 리소스가 하나도 없기 때문에, 상태 값은 비어있는 상태죠. 그래서 Terraform 코드에 정의된 리소스는 모두 새로 추가됩니다. 이제 tf apply를 실행합니다.

> tf apply
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

이제 다시 terraform.tfstate 파일의 내용을 확인합니다.

{
 "version": 4,
 "terraform_version": "1.6.2",
 "serial": 3,
 "lineage": "2e6b0c74-0e92-bfe8-1197-36e5547d9375",
 "outputs": {},
 "resources": [
 {
 "mode": "managed",
 "type": "aws_instance",
 "name": "example",
 "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
 "instances": [
 {
 "schema_version": 1,
 "attributes": {
 "ami": "ami-0c6e5afdd23291f73",
 ...
 },
 "sensitive_attributes": [],
 "private": "..."
 }
 ]
 }
 ],
 "check_results": null
}

방금 전 apply 명령으로 추가된 리소스를 확인할 수 있습니다.

상태는 Terraform이 리소스를 관리할 때 어떻게 변경해야 할지 판단하는 기준이 됩니다. 그렇기 때문에 상태는 Terraform에서 가장 중요합니다. 상태가 제대로 관리되지 않으면 어떤 리소스를 어떻게 변경해야 할지 Terraform이 제대로 판단할 수 없겠죠.

그렇기 때문에 Terraform으로 생성된 리소스를 관리 콘솔에서 직접 변경하면 안됩니다! 상태 파일에 기록된 내용과 실제 리소스의 상태가 달라지기 때문에 Terraform이 제대로 동작하지 않을 수 있습니다.

확인이 끝났으므로 destroy 명령으로 생성된 리소스를 모두 제거합니다. 참고로 제거 작업이 끝난 후 상태 파일은 이렇습니다.

{
 "version": 4,
 "terraform_version": "1.6.2",
 "serial": 5,
 "lineage": "2e6b0c74-0e92-bfe8-1197-36e5547d9375",
 "outputs": {},
 "resources": [],
 "check_results": null
}

serial을 제외하고는 모두 원래대로 돌아왔죠?

상태 파일 관리

보시다시피 별다른 설정이 없다면, 상태 파일은 현재 Terraform 명령을 실행하는 폴더에 생성됩니다. 실습을 위해 간단하게 테스트를 하는 경우라면 문제가 없겠지만, 계속 상태 파일을 이렇게 사용하는 건 매우 위험합니다. 그 이유는!

output등의 민감한 정보가 상태 파일에 기록되기 때문에 파일에 접근할 수 있다면, 민감한 정보를 보호할 수 없습니다.
동일한 리소스에 대해, 여러 장소(컴퓨터)에서 Terraform을 실행해야 하는 경우 각 장소마다 동일한 상태 파일을 가지고 있어야 합니다. 그래서 git등의 버전 관리 시스템으로 상태 파일을 관리할 수도 있지만, commit이나 pull을 까먹는다면 무슨 일이 벌어질까요?

그래서 실제 Terraform을 사용하려면 상태 파일은 로컬 컴퓨터가 아닌, git같은 버전 관리 시스템도 아닌 어딘가 안전하고 항상 접근 가능한 곳에 저장되어야 합니다. 그리고 가능하면 암호화되어야 겠죠! 이 글 서두에 보셨던 backend가 바로 이런 상태 파일을 어딘가에서 안전하게 잘 관리해주는 역할을 합니다. 우리는 지금 AWS를 사용하고 있죠? 그렇다면 이제 S3를 통해 backend를 구성해보겠습니다.

S3 backend 구성

S3로 backend를 구성하려면 우선 S3를 생성해야겠죠? 일단 Terraform으로 S3를 생성하고 그 이후에 backend를 구성해서 상태를 backend로 옮기겠습니다. 새로 폴더를 만들고 main.tf를 다음과 같이 작성합니다.

// AWS 프로바이더 설정
provider "aws" {
 // 아시아 태평양(서울) 리전
 region = "ap-northeast-2"
}

# S3 버킷 생성
resource "aws_s3_bucket" "terraform_state" {
 bucket = "terraform-state-example-20231118"

 # 실수로 버킷이 삭제되지 않도록 하려면 아래 주석을 해제하세요.
 # lifecycle {
 # prevent_destroy = true
 # }
}

# 버킷 버전 관리 활성화(상태 파일의 히스토리를 관리하기 위함)
resource "aws_s3_bucket_versioning" "enabled" {
 bucket = aws_s3_bucket.terraform_state.id

 versioning_configuration {
 status = "Enabled"
 }
}

# S3에 저장될 때 암호화 하도록 설정
resource "aws_s3_bucket_server_side_encryption_configuration" "default" {
 bucket = aws_s3_bucket.terraform_state.id

 rule {
 apply_server_side_encryption_by_default {
 sse_algorithm = "AES256"
 }
 }
}

# 모든 public access를 차단(실수로 버킷이 공개되지 않도록 하기 위함)
resource "aws_s3_bucket_public_access_block" "public_access" {
 bucket = aws_s3_bucket.terraform_state.id

 block_public_acls = true
 block_public_policy = true
 ignore_public_acls = true
 restrict_public_buckets = true
}

# 여러 사람이 동시에 상태 파일을 수정하지 못하도록 DynamoDB를 사용한 락 설정
resource "aws_dynamodb_table" "terraform_locks" {
 name = "terraform_locks"
 billing_mode = "PAY_PER_REQUEST"
 hash_key = "LockID"

 attribute {
 name = "LockID"
 type = "S"
 }
}

우선 aws_s3_bucket 리소스를 통해 S3 버킷을 생성하는데요, 이 버킷에 상태 파일을 저장하게 됩니다. 그리고 필요한 경우 상태 파일의 히스토리를 버전 별로 관리할 수 있도록 버전 관리를 활성화 합니다. 버전 관리를 사용하도록 설정한다면 뭔가 상태 파일에 문제가 있을 경우 이전 버전으로 복구할 수 있겠죠?

그리고 상태 파일은 암호화되어 저장되도록 설정했고, 실수로 버킷이 공개되지 않도록 모든 public access를 차단했습니다. 마지막으로 여러 사람이 동시에 상태 파일을 수정하지 못하도록 DynamoDB를 사용한 락을 설정했습니다. 이제 tf init을 실행해봅시다.

> tf init
...
Terraform has been successfully initialized!
...

그리고 tf plan으로 변경될 리소스를 확인합니다.

> tf plan
...
Plan: 5 to add, 0 to change, 0 to destroy.
...

이어서 tf apply로 리소스를 생성합니다.

> tf apply
...
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.

만약 이전글에서 사용했던 것처럼 제한된 IAM 사용자 권한을 사용하는 경우 “sts:GetCallerIdentity”,“s3:CreateBucket”,“dynamodb:CreateTable”,“dynamodb:DescribeTable”,“s3:ListBucket”,“s3:GetBucketPolicy”,“s3:GetBucketAcl”,“s3:GetBucketCORS”,“s3:GetBucketWebsite”,“s3:GetBucketVersioning”,“s3:GetAccelerateConfiguration”,“s3:GetBucketRequestPayment”,“s3:GetBucketLogging”,“s3:GetLifecycleConfiguration”,“s3:GetReplicationConfiguration”,“s3:GetEncryptionConfiguration”,“s3:GetBucketObjectLockConfiguration”,“s3:GetBucketTagging”,“s3:PutBucketVersioning”,“dynamodb:DescribeContinuousBackups”,“s3:PutBucketPublicAccessBlock”,“s3:PutEncryptionConfiguration”,“dynamodb:DescribeTimeToLive”,“dynamodb:ListTagsOfResource”,“s3:GetBucketPublicAccessBlock”,“s3:GetObject”,“s3:GetObjectVersion”,“dynamodb:GetItem”,“dynamodb:PutItem”,“dynamodb:DeleteItem” 등의 권한이 추가로 필요합니다.

S3는 잘 생성되었지만, 여전히 terraform.tfstate파일은 현재 폴더에 그대로 남아있습니다. 파일 내용을 확인해보면, 방금 생성한 S3의 정보가 담겨있습니다. 아직 backend설정을 하지 않았기 때문에 여전히 상태 파일은 로컬 컴퓨터에서 관리하고 있는 거죠. 그렇다면 backend를 S3로 설정하겠습니다. main.tf에서 기존에 작성된 코드 위에 다음 코드를 추가합니다.

# Terraform 설정
terraform {
 # 필요한 프로바이더 목록과 버전 정보
 required_providers {
 aws = {
 source = "hashicorp/aws"
 version = "~> 5.0" # 5.x 버전 사용
 }
 }

 # 상태 파일을 S3에 저장하도록 설정
 backend "s3" {
 bucket = "terraform-state-example-20231118"
 # 상태 파일이 저장될 경로
 key = "example/terraform.tfstate"
 region = "ap-northeast-2"

 # 상태 파일을 락으로 사용할 DynamoDB 테이블
 dynamodb_table = "terraform_locks"
 # 상태 파일을 암호화
 encrypt = true
 }
}

...

Terraform 블록을 선언하고 사용할 프로바이더와 버전 정보, 그리고 S3를 backend로 사용하도록 설정했습니다. 이제 tf init을 실행하면 로컬에 저장된 상태 파일을 새로 지정된 S3로 이동하게 됩니다.

> tf init
Initializing the backend...
Acquiring state lock. This may take a few moments...
Do you want to copy existing state to the new backend?
 Pre-existing state was found while migrating the previous "local" backend to the
 newly configured "s3" backend. No existing state was found in the newly
 configured "s3" backend. Do you want to copy this state to the new "s3"
 backend? Enter "yes" to copy and "no" to start with an empty state.

 Enter a value: yes

Releasing state lock. This may take a few moments...

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.
...

로컬에 저장된 상태를 S3로 복사하겠냐는 질문이 나오는데, yes를 입력하면 로컬에 저장된 상태 파일이 S3로 복사됩니다. 그리고 terraform.tfstate 파일이 남아있긴 하지만, 내용을 확인 해보면 텅텅 비어 있습니다. 이제 삭제해도 문제가 없겠죠! 참고로 backend에서 상태 파일을 로컬로 다운로드 하고 싶다면 terraform state pull 명령을 사용하면 됩니다.

iamlive를 실행 중이라면 tls: failed to verify certificate: x509 오류나 request send failed, Post "https://sts.ap-northeast-2.amazonaws.com/": proxyconnect tcp: dial tcp 127.0.0.1:80 등의 오류가 발생할 수 있습니다. iamlive의 실행을 위해 선언해둔 환경 변수 때문인데요, 해당 환경 변수를 주석처리하고 터미널 세션을 다시 시작하거나, unset 등의 명령어로 현재 터미널 세션에서 환경 변수를 제거할 수 있습니다.

그렇다면 이제 간단한 EC2 인스턴스를 추가해서 상태가 잘 관리되는지 확인하겠습니다. main.tf에 다음 코드를 추가합니다.

...

resource "aws_instance" "example" {
 // ap-northeast-2 리전의 Ubuntu 20.04 AMI
 ami = "ami-0c6e5afdd23291f73"
 instance_type = "t2.micro"
}

tf plan과 tf apply를 실행하여 동작을 확인합니다.

> tf plan
...
Plan: 1 to add, 0 to change, 0 to destroy.
...

> tf apply
...
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

더 이상 로컬에 상태 파일이 생성되지 않지만, 원격의 S3에서 상태를 읽어와서 잘 관리하고 있네요!

마치며

이제 우리는 상태를 로컬 파일이 아니라 S3를 통해 안전하고 안정적으로 그리고 어디서나 활용할 수 있도록 변경할 수 있습니다. 하지만 여전히 불안한 점은 남아있습니다. EC2를 추가하면서 plan, apply를 실행해보신 분들은 아시겠지만, 여전히 이미 생성된 S3에 대한 상태를 매번 비교하고 있습니다. 하나의 상태에 많은 리소스가 연결되면 이렇게 아주 작은 부분만을 바꿀 때도 전체 상태와 비교를 하게 됩니다. 그리고 아무리 리소스 파일이 공유된 상태라고는 하지만, 여러 사람이 동시에 서로 다른 부분에서 코드를 변경하면 예상하지 어려운 상황이 발생하겠죠. 그래서 상태 파일은 가능하면 작게 유지하는 게 좋습니다. 다음 시간에는 상태 파일을 작게 유지하는 방법에 대해 알아보겠습니다.

참고자료

Terraform Up and Running, 3rd Edition

License

저작자표시-비영리-변경금지 2.0 대한민국 (CC BY-NC-ND 2.0 KR)

Posts on 엔지니어 생존기록

분산 시스템 설계(3) - 액터 모델(2): 상태는 누가 어떻게 관리하나?

객체의 탄생(1960~1970): 상태는 객체 안에 존재한다!

최초의 OOP 언어: Simula 67

액터 모델에 영감을 주다: Smalltalk

액터 모델의 태동(1973)

Erlang

OOP 전성시대(1980~1990년대)

분산 객체(1990-2000년대 초)

분산 락과 2단계 커밋

마이크로서비스(2010~)

액터 모델의 귀환(2010~)

정리

참고자료

분산 시스템 설계(3) - 액터 모델(1) feat. Go, Node.js, .NET, Java, Rust

Go

정리

Node.js

메인 스크립트 실행

CommonJS

ESM

I/O는 누가 기다리나

Node.js의 병렬성

정리

.NET

ThreadPool의 구조

.NET의 병렬성

그외의 언어들

Java

Rust

참고 자료

분산 시스템 설계(2) - 일관된 해싱

나머지 연산 해시(modulo hash)

나머지 연산 해시 구현

그런데 말입니다…

링 해시(ring hash)

링 해시 구현

링에 배치된 서버와 매핑하는 방법: 이진 탐색

링 해시 분배 코드 작성

랑데뷰 해시(HRW, Highest Random Weight)

랑데뷰 해시 구현

빠르고 균등한 비 암호학적 해시

랑데뷰 해시 분배 코드 작성

참고 자료

Node.js: --experimental-vm-modules

Javascript 초창기의 서버 런타임

나는 꿈이 있어요!

하지만 그렇게 간단하지 않았다

그 시절 우리가 좋아했던 mocking

그런데 뭐가 문제인가요?

모든 게 다 함수다.

1. node:module

2. .wrapper

그래서 이게 다 뭐라는 건가요?

그런데 ESM은… 달라요!

다시 –experimental-vm-modules 이야기

ESM의 모듈 임포트를 직접 제어해보자!

mock을 사용하지 않는 디자인

정리

참고자료

SIMD를 알아보자(feat. Go)

Go 환경설정

1. 래퍼 프로그램 설치

2. ~/go/bin 을 PATH에 설정하기

3. 실제 SDK 다운로드

4. 버전 확인하기

5. SIMD 지원 확인하기

6. 설정 삭제하기

테스트용 코드 작성하기

1. 폴더와 모듈 생성

2. 테스트에 사용할 2개의 연산 커널

2-1. 합 구하기

2-2. 삼차 다항식 계산

3. 커널 구현하기(kernels.go)

4. SIMD 커널 구현하기(kernel_simd.go)

4-1. SumSIMDSingle 함수

4-2. SumSIMDUnrolled4 함수

4-3. SumSIMDUnrolled8 함수

4-4. PolySIMD 함수

5. 대체 커널 구현하기(kernel_stub.go)

2. `~/go/bin` 을 PATH에 설정하기

`new()` 와 `&Counter{}` - 둘 다 구조체 포인터를 만들어요

4단계: `min-release-age` 설정

(1) `package-lock.json`을 반드시 Git에 커밋

(2) CI에서는 `npm install` 대신 `npm ci` 사용