# 개발자 매튜 (YOLOG) 전체 글 --- > 소프트웨어 개발자 매튜입니다. 에듀테크 장학카드 관리 서비스를 만들고, 사이드로 친구와 함께 성장하는 AI 투두 플래너 아이두를 개발하고 있습니다. 개발 경험과 생각을 기록합니다. --- # Redis 없이 PostgreSQL 하나로 서버 운영하기 > 배포할 때마다 프리미엄 고객의 AI 리포트가 빠지던 문제를 Redis로 막았다가 다시 PostgreSQL 하나로 옮겨 월 인프라 비용을 약 35% 줄인 이야기입니다. 작업 큐와 잠금을 DB 안에 두고 RDS 하나로 무중단 배포까지 하면서 PostgreSQL을 왜 많이 쓰는지 조금 알게 됐습니다. - 원문: https://www.yolog.co.kr/post/aido-server-architecture - 카테고리: 개발 - 발행: 2026-11-16 - 수정: 2026-11-16 (이미지: Redis 없이 PostgreSQL 하나로 서버 운영하기) 해외 강의 영상으로 공부하다 보면 PostgreSQL을 쓰는 경우가 정말 많았습니다. 그래서 아이두를 처음 만들 때도 자연스럽게 PostgreSQL을 골랐습니다. 다만 서버를 만드는 데 급급해서 왜 PostgreSQL이어야 하는지는 따져 보지 못했고 테이블을 만들고 조인하는 정도로만 썼습니다. 사실상 일반적인 DB들과 별반 다르지 않게 쓰고 있었습니다. 그러다 배포로 서버가 잠깐 내려가는 사이에 돈을 낸 프리미엄 고객에게 주간·월간 AI 리포트가 제대로 전달되지 않는 일을 겪었습니다. 급한 대로 Redis를 붙여서 막았습니다. 생각이 바뀐 건 [모여](https://moyeo.io)를 혼자 바닥부터 만들면서였습니다. 예약 발행 큐의 예외 상황을 다루다가 pg-boss와 `pg_notify`를 알게 됐고 써 보니 인프라 비용을 늘리지 않고도 충분히 풀 수 있는 문제였습니다. 그래서 아이두에도 바로 적용했습니다. 부트캠프나 교육에서 배우는 정답은 당연히 좋은 답입니다. 다만 그 답이 지금 내가 처한 상황에서도 가장 알맞은 답인지는 또 다른 문제라고 생각합니다. 교육은 문제를 푸는 방법을 알려 주지만 내 서비스의 규모와 예산, 혼자 운영할 수 있는 범위까지 대신 따져 주지는 못합니다. 그건 그 상황에 직접 서 봐야 보입니다. 문제를 푸는 방법으로는 맞아도 내 상황에 맞는 방법은 아닐 수 있습니다. 아이두도 그랬습니다. 처음 Redis를 붙여 문제를 푼 방식도 정답이었지만 조금 더 깊게 들여다보니 더 나은 답이 있었습니다. 물론 지금 고른 답에도 더 나은 답이 있을 수 있습니다. 밑바닥부터 서비스를 키우다 보면 그 순간에 정말 필요한 것이 하나씩 보입니다. 인프라 비용도 그렇습니다. 사이드 프로젝트에서는 비용이 내 돈으로 나가니 아낄 길이 더 잘 보였고 이번에 아낀 돈은 **매달 치킨 한 마리 값**입니다. 이 글은 아이두 서버에서 Redis를 걷어 내고 PostgreSQL 하나로 작업 큐와 잠금, 무중단 배포까지 옮긴 과정을 정리한 기록입니다. 작은 프로젝트에 습관처럼 Redis부터 붙이려는 분이 있다면 이 삽질을 보고 다른 선택지를 한 번쯤 떠올려 보시면 좋겠습니다. *** ## 배포할 때마다 사라지던 작업 아이두에서 친구의 할 일에 응원을 보내면 친구에게 푸시 알림이 갑니다. 할 일에 시간을 정해 두면 그 시간에 리마인더가 울립니다. 처음에는 이런 "나중에 해야 할 일"을 서버 메모리에 들고 있었습니다. 알림은 EventEmitter로 서버 안에서 넘겨 보냈고 리마인더는 `setTimeout`으로 예약했습니다. 개발할 때는 아무 문제가 없었습니다. 문제는 배포였습니다. (이미지: 배포로 다시 켜질 때 사라지는 메모리 속 작업) 새 버전을 배포하면 서버는 몇 초 동안 꺼졌다가 다시 켜집니다. 이 몇 초 사이에 두 가지 일이 함께 벌어졌습니다. 하나는 메모리에 들고 있던 "해야 할 일"이 그 순간 모두 사라진다는 점입니다. DB에 저장한 할 일은 그대로지만 응원 알림이 오지 않거나 리마인더가 울리지 않았습니다. 그나마 이건 나은 편이었고 프리미엄 고객이 돈을 내고 받아 보는 주간·월간 AI 리포트가 만들어지지 않는 일까지 생겼습니다. 다른 하나는 서버가 꺼져 있는 동안 앱을 쓰던 사용자가 오류를 본다는 점입니다. 그 사이에 할 일을 저장하거나 완료한 요청은 받아 줄 서버가 없어서 실패했습니다. 그래서 풀어야 할 숙제는 두 가지였습니다. **서버가 꺼져도 해야 할 일은 어딘가에 기록돼 있어야 하고 서버가 바뀌는 순간에도 사용자는 장애를 겪지 않아야 했습니다.** 첫 번째는 작업 큐로, 두 번째는 Blue-Green 배포로 풀었습니다. 작업 큐 이야기부터 하겠습니다. *** ## 처음 고른 답, Redis 가장 먼저 떠오른 건 Redis였습니다. Redis는 서버 밖에 따로 떠 있는 저장소라서 API 서버가 다시 켜져도 데이터가 남습니다. 여기에 BullMQ라는 작업 큐 라이브러리를 얹으면 "나중에 할 일"을 Redis에 넣어 두고 서버가 다시 켜진 뒤 꺼내 쓸 수 있습니다. 그래서 EC2 한 대와 RDS의 PostgreSQL로 돌던 서버에 AWS ElastiCache로 Redis를 하나 더 붙였습니다. 이왕 붙인 김에 캐시와 요청 횟수 제한, 분산 잠금까지 Redis에 맡겼습니다. (이미지: Redis를 쓰던 때의 구성) 효과는 있었습니다. 배포해도 작업이 남았고 알림도 다시 나갔습니다. 대신 두 가지 대가가 따라왔습니다. 하나는 비용입니다. ElastiCache 노드가 붙으면서 월 인프라 비용이 $45까지 올라갔습니다. 엔진을 Valkey로 바꾸면 조금 줄일 수 있지만 외부 캐시 비용이 나간다는 점은 같습니다. 다른 하나는 Redis가 새로운 약점이 됐다는 점입니다. 캐시를 읽는 코드도, 요청 제한도, 잠금도 전부 Redis 응답을 기다리고 있어서 Redis 연결이 끊기면 **모든 API 요청이 응답 없이 멈췄습니다.** 알림을 지키려고 붙인 부품이 오히려 서버 전체를 멈출 수 있는 부품이 됐습니다. 그래서 Redis의 장애가 서비스 전체의 장애로 번지지 않게 하는 구현이 따로 필요했습니다. Redis 응답이 늦으면 오래 기다리지 않고 바로 실패하게 하고 캐시를 읽지 못하면 DB에서 다시 읽게 했습니다. 문제를 막으려고 들인 부품을 지키는 코드가 또 늘어난 겁니다. *** ## 질문을 다시 세우다 돌아보면 문제를 "해야 할 일을 서버 밖 어딘가에 남겨야 한다"로만 보고 있었습니다. 그러니 답도 "서버 밖의 저장소를 하나 더 붙인다"밖에 없었습니다. 모여에서 예약 큐를 다루며 배운 걸 아이두에 비춰 보니 질문이 바뀌었습니다. 할 일을 완료하면 서버는 두 가지를 씁니다. "이 할 일이 완료됐다"는 기록과 "친구에게 알림을 보내라"는 작업입니다. 진짜 문제는 이 두 가지가 함께 남느냐였습니다. DB는 여러 번의 쓰기를 하나로 묶어서 전부 저장하거나 하나도 저장하지 않게 해 줍니다. 이 묶음이 트랜잭션이고 저장이 확정되는 순간을 커밋이라고 부릅니다. 할 일은 PostgreSQL에 쓰고 알림 작업은 Redis에 쓰면 이 둘은 한 트랜잭션으로 묶이지 않습니다. 두 쓰기 사이에 서버가 꺼지면 한쪽만 남습니다. (이미지: 커밋 직후 서버가 꺼졌을 때 세 방식의 차이) 이미 PostgreSQL을 쓰고 있으니 알림 작업도 할 일과 같은 DB의 같은 트랜잭션에 넣으면 되지 않을까요? *** ## 작업 큐를 PostgreSQL 안으로 그 답이 [pg-boss](https://github.com/timgit/pg-boss)였습니다. pg-boss는 작업을 PostgreSQL 테이블에 저장하는 작업 큐입니다. 작업을 넣는 일도 같은 DB에 대한 `INSERT`라서 할 일을 저장하는 트랜잭션 안에서 함께 넣을 수 있습니다. 사용자가 할 일 하나를 완료했을 때 서버에서 무슨 일이 일어나는지 따라가 보겠습니다. (이미지: 할 일 완료 요청이 지나는 길) 요청은 인증과 검증을 거쳐 할 일 완료 UseCase에 도착합니다. UseCase는 트랜잭션을 열고 그 안에서 모든 일을 처리합니다. ```ts title="할 일 완료 UseCase" {4,6,13-14} const todoId = TodoId.reconstitute(id); await unitOfWork.run(async () => { await mutationLock.acquire([TodoLockKeys.todo(id)]); const todo = await todoRepository.findByIdAndUserId(todoId, ownerId); const changed = todo.toggleComplete(completed, timezone, clock.now()); if (!changed) { return; } await todoRepository.updateDetails(todoId, { completed: todo.completed, completedAt: todo.completedAt }); const events = todo.pullDomainEvents(); await applyTodoEvents.execute(events); await completionEffects.execute(events); }); ``` set-todo-completed.use-case.ts 일부 먼저 같은 할 일을 동시에 바꾸지 못하게 잠급니다. 완료 상태를 바꾼 뒤에는 그 결과로 생긴 후속 처리를 이어서 부릅니다. `toggleComplete()`는 값이 실제로 바뀐 경우에만 `true`를 돌려주니 같은 요청이 두 번 와도 알림은 한 번만 나갑니다. 후속 처리 중 `completionEffects`는 오늘 할 일을 다 끝냈으면 친구에게 보낼 알림 작업을 큐에 넣습니다. ```ts title="다 끝냈으면 친구 알림 작업 넣기" {6} if (!isAllCompletedToday(todayStats)) { return; } const friendIds = await friendPort.getMutualFriendIds(ownerId); await todoNotification.enqueueFriendCompleted({ friendId: ownerId.value, notifyUserIds: friendIds, timezone, }); ``` apply-todo-completion-effects.use-case.ts 일부 이 작업은 pg-boss 어댑터를 거쳐 PostgreSQL에 들어갑니다. 핵심은 한 줄입니다. ```ts title="지금 열린 트랜잭션으로 작업 넣기" {4} async enqueue(queue, payload, options = {}) { return this.#boss.send(queue.name, payload, { ...toPgBossJobOptions(queue, options), db: transactionJobDatabase(this.#txHost.tx), }); } ``` pg-boss-job-queue.adapter.ts 일부 `db` 옵션에 지금 열린 트랜잭션을 넘기니 할 일과 알림 작업이 함께 커밋되고 함께 롤백됩니다. 커밋 직후에 서버가 꺼져도 작업은 테이블에 남아 있어서 다시 켜진 서버가 꺼내 보냅니다. 이 방식을 트랜잭셔널 아웃박스(Transactional Outbox)라고 부릅니다. **Redis를 붙였을 때보다 오히려 보장이 더 강해졌습니다.** ### 사라져도 되는 일과 사라지면 안 되는 일 모든 알림의 무게가 같지는 않습니다. 친구의 응원 알림 하나가 늦는 건 아쉬운 정도지만 돈을 내고 기다리던 주간 AI 리포트가 오지 않으면 그 사용자는 떠납니다. 앞에서 겪은 일이 바로 이 경우였습니다. 게다가 돈을 내는 사용자는 생각보다 적습니다. [RevenueCat이 구독 앱을 분석한 자료](https://www.revenuecat.com/blog/growth/subscription-app-trends-benchmarks-2026)를 보면 무료로 시작하는 구독 앱에서 설치 후 35일 안에 돈을 내는 사람은 중앙값 기준 2% 남짓입니다. 100명 중 2명 정도입니다. 아이두도 무료로 시작해 프리미엄을 파는 구조라서 그 2명이 겪는 문제는 서비스 전체의 문제입니다. 그래서 서버가 하는 일을 사라져도 되는지에 따라 나눴습니다. | 일 | 사라지면 | 처리 방식 | | ------------ | ------------------ | ------------------------------------------ | | 주간·월간 AI 리포트 | 돈을 낸 사용자가 떠남 | 작업 큐에 넣고 놓친 회차는 다시 실행, 끝내 실패하면 기본 리포트라도 저장 | | 결제 뒤 프리미엄 열기 | 돈을 낸 사용자가 떠남 | 결제 알림을 받는 트랜잭션에 스토어 상태 확인 작업을 함께 넣음 | | 리마인더, 친구 알림 | 앱을 믿지 못하게 됨 | 같은 트랜잭션에 넣고 먼저 보내는 차선으로 처리 | | 마케팅 알림 | 조금 늦어도 괜찮음 | 같은 큐에 넣되 뒤로 미루는 차선으로 처리 | | 캐시 정리 | 만료 시간이 지나면 저절로 맞춰짐 | 커밋 뒤 메모리에서 바로 처리 | 이렇게 나누고 보니 EventEmitter가 맡던 일 대부분은 사라지면 안 되는 쪽이었습니다. 처음에 EventEmitter를 들인 건 모듈끼리 직접 부르지 않으려는 것이었는데 서버 하나, DB 하나인 서비스에서는 불필요한 오버엔지니어링이었습니다. 커밋 뒤 메모리에서 전달되니 서버가 꺼지면 사라졌고 이벤트 이름만 봐서는 누가 받는지도 잘 보이지 않았습니다. (이미지: EventEmitter를 쓸 때와 지금) 그래서 상태를 바꾸는 이벤트 전달은 모두 걷어 냈습니다. 같은 기능 안의 후속 처리는 UseCase가 직접 부르고 다른 기능이 반응해야 할 때는 같은 트랜잭션에 큐 작업을 넣습니다. EventEmitter는 표의 맨 아래 줄인 캐시 정리에만 남겼습니다. ### 친구 초대도 같은 방식으로 다른 기능이 큐 작업으로 반응하는 대표적인 예가 친구 초대입니다. 초대는 앱과 Next.js로 만든 랜딩 웹, API 서버 세 곳을 거칩니다. (이미지: 친구 초대의 실제 화면과 흐름) 초대받은 사람은 가입하면서 바로 프리미엄 7일을 받습니다. 초대한 사람의 보상은 초대받은 사람이 14일 안에 서로 다른 2일 동안 할 일을 완료해야 갑니다. 할 일을 완료할 때마다 같은 트랜잭션에 "초대 활동 확인" 작업이 들어가고 조건을 채우면 보상 작업이 이어서 실행됩니다. 할 일 기능은 초대 기능을 전혀 모릅니다. *** ## Redis가 하던 나머지 일 작업 큐를 옮기고 나니 Redis가 하던 다른 일들도 PostgreSQL로 옮길 수 있겠다는 생각이 들었습니다. | Redis가 하던 일 | 지금 맡고 있는 곳 | | -------------------- | -------------------------------- | | 작업 큐(BullMQ) | PostgreSQL 테이블에 작업을 저장하는 pg-boss | | 분산 잠금 | PostgreSQL advisory lock | | 같은 알림을 두 번 보내지 않게 막기 | PostgreSQL 부분 unique 인덱스 | | 푸시 발송 횟수 제한 | PostgreSQL 조건부 upsert | | 캐시와 요청 횟수 제한 | 서버 메모리(lru-cache) | pg-boss를 들여다보면서 처음으로 PostgreSQL 문서를 제대로 읽었는데 Redis로 하던 일을 대신할 기능이 이미 거의 다 있었습니다. 앞의 UseCase에서 본 `mutationLock`은 트랜잭션이 끝나면 저절로 풀리는 잠금입니다. ```ts title="트랜잭션이 끝나면 풀리는 잠금" {2} await this.#txHost.tx.execute(sql` SELECT pg_advisory_xact_lock(hashtextextended(ordered."key", 0)) FROM ordered ORDER BY ordered."key" `); ``` postgres-mutation-lock.adapter.ts 일부 Redis 잠금처럼 만료 시간을 맞추거나 풀지 못한 잠금을 걱정할 필요가 없습니다. 같은 알림을 두 번 보내지 않게 막는 일은 부분 인덱스가 맡습니다. ```sql title="리마인더 알림에만 거는 unique 인덱스" {3} CREATE UNIQUE INDEX "Notification_todo_reminder_occurrence_dedup" ON "Notification" ("todoId", "type", (metadata ->> 'stage'), (COALESCE("reminderOccurrenceKey", ''))) WHERE type = 'TODO_REMINDER' AND "todoId" IS NOT NULL; ``` notification_reminder_occurrence/migration.sql 일부 리마인더 알림에만 unique 조건을 걸어서 워커가 같은 리마인더를 두 번 처리해도 두 번째 저장은 DB가 막아 줍니다. 발송 한도는 조건부 upsert 한 문장으로 셉니다. ```ts title="한도 안에서만 사용량 올리기" {7,9} await this.#txHost.tx .insert(outboundUsage) .values({ ...key, used: amount, updatedAt: at }) .onConflictDoUpdate({ target: [outboundUsage.meter, outboundUsage.periodKey, outboundUsage.subject], set: { used: sql`${outboundUsage.used} + ${amount}`, updatedAt: at }, setWhere: sql`${outboundUsage.used} + ${amount} <= ${limit}`, }) .returning({ used: outboundUsage.used }); ``` drizzle-usage-meter.adapter.ts 일부 "한도를 넘지 않으면 올리고 새 값을 돌려줘"를 SQL 한 문장으로 끝냅니다. 한도를 넘으면 아무 행도 돌아오지 않으니 거절하면 됩니다. Redis에서 흔히 `INCR`로 하던 일입니다. ### PostgreSQL을 많이 쓰는 이유 여기까지 오고 나서야 처음의 궁금증에 조금 답할 수 있었습니다. 아이두에서 실제로 쓰고 있는 기능만 골라 MySQL 8과 비교해 봤습니다. | 기능 | 아이두에서 쓰는 곳 | MySQL 8 | | --------------------------- | ----------------------- | ------------------------------- | | 트랜잭션이 끝나면 풀리는 advisory lock | 같은 할 일을 동시에 바꾸지 못하게 잠금 | `GET_LOCK()`은 세션 단위라 직접 풀어야 합니다 | | 부분 인덱스(`WHERE`가 붙은 인덱스) | 리마인더 중복 발송 방지 | 없습니다 | | 조건부 upsert와 `RETURNING` | 발송 한도를 한 문장으로 예약 | `RETURNING`이 없어 다시 조회해야 합니다 | | 데이터를 바꾸는 CTE | 푸시 발송 대기열을 잠그고 바로 상태 변경 | CTE 안에서 데이터를 바꿀 수 없습니다 | | 역할별 기본 설정 | 앱 계정의 쿼리 시간 제한 | 계정별 세션 기본값이 없습니다 | | 트랜잭션 안의 DDL | migration이 실패하면 전부 롤백 | DDL이 바로 커밋됩니다 | `SKIP LOCKED`처럼 MySQL 8에도 있는 기능도 많으니 MySQL이 부족하다는 이야기는 아닙니다. 차이는 **PostgreSQL에는 이런 기능을 엮어 큐와 잠금을 DB 안에서 해결하는 도구가 이미 있다**는 데 있었습니다. *** ## 캐시는 서버 메모리로 마지막 남은 일은 캐시였습니다. 서버가 한 대라서 여러 서버가 캐시를 나눠 쓸 일이 없으니 서버 메모리 안의 캐시로 충분하다고 판단했습니다. 다만 Redis 어댑터를 지우지는 않았고 어느 쪽을 쓸지는 설정값 하나로 고릅니다. ```ts title="설정으로 고르는 캐시 저장소" {3-5} useFactory: (cache, redis) => { const shared = selectSharedRedis(cache, redis); return shared == null ? new InMemoryCacheStore({ defaultTtlMs: cache.defaultTtlMs, maxItems: cache.maxItems }) : new RedisCacheStore(shared, cache.defaultTtlMs); }, ``` cache.module.ts 일부 서버 메모리 캐시는 최대 3,000개, 기본 60초로 제한하고 자주 읽지만 조금 늦어도 괜찮은 값만 담습니다. 캐시를 읽다 실패하면 DB에서 다시 읽으니 캐시 때문에 서비스가 멈추는 일은 없습니다. *** ## RDS 하나로 무중단 배포 Redis를 걷어 내고 나니 서버는 EC2 한 대와 RDS 하나만 남았습니다. (이미지: 지금 아이두 서버 구성) 앱의 요청은 EC2 위의 Nginx가 받아 같은 서버 안의 API 컨테이너로 넘기고 CloudWatch 경보가 EC2와 RDS를 지켜봅니다. 남은 건 처음에 세운 두 번째 숙제입니다. 작업은 더 이상 사라지지 않지만 컨테이너를 내리고 새로 올리는 몇 초 사이에 들어온 요청은 여전히 실패했습니다. ECS를 쓰면 새 컨테이너를 띄우고 ALB가 요청을 옮겨 줍니다. 하지만 이 일은 **같은 서버의 Nginx로도 충분했습니다.** API 컨테이너 자리를 `api-blue`와 `api-green` 두 개 두고 번갈아 쓰는 Blue-Green 배포입니다. (이미지: 머지부터 배포까지) main에 머지하면 테스트와 보안 검사를 통과한 이미지만 올라가고 서버의 배포 스크립트가 여섯 단계를 차례로 실행합니다. 무중단을 만드는 건 네 번째 단계인 Nginx 전환입니다. (이미지: Nginx 전환 전과 후) Nginx가 요청을 어느 컨테이너로 보낼지는 설정 파일 한 줄이 정합니다. 새 컨테이너가 준비되면 이 한 줄을 바꾸고 Nginx를 다시 읽힙니다. ```bash title="실패해도 살아 있는 쪽은 그대로 두는 배포" {7,13} # migrate가 실패하면 여기서 멈춘다 compose run --rm --pull never migrate log "새 API 기동" if ! compose up -d --no-deps --pull never --wait --wait-timeout "$HEALTH_WAIT_S" "api-$next" \ || ! curl -fsS -m 5 "http://127.0.0.1:$next_port/health" >/dev/null; then compose rm -sf "api-$next" >/dev/null || true fail "새 API가 healthy가 아니어서 지웠다. 살아 있는 슬롯($live_port)은 그대로다" fi log "Nginx 전환" if ! point_nginx_at "$next_port"; then point_nginx_at "$live_port" || true fail "Nginx 전환 실패. 살아 있는 슬롯($live_port)으로 되돌렸다" fi wait_nginx_drain ``` deploy.sh 일부 어느 단계에서 실패하든 **지금 응답하고 있는 컨테이너는 건드리지 않습니다.** 새 컨테이너가 90초 안에 준비되지 않으면 새 컨테이너만 지우고 Nginx 전환이 실패하면 원래 자리로 되돌립니다. (이미지: 배포 중 두 컨테이너의 시간표) 두 컨테이너는 같은 RDS를 씁니다. 그래서 DB 구조를 바꾸는 migration은 옛 코드도 그대로 돌 수 있는 변경만 합니다. 컬럼을 지우거나 이름을 바꾸지 않고 더하기만 하니 문제가 생기면 이전 버전을 다시 배포하는 것으로 되돌릴 수 있습니다. ### 두 컨테이너가 함께 도는 동안 전환하는 몇 분 동안은 두 컨테이너가 함께 돌고 둘 다 작업을 꺼내 처리합니다. 같은 리마인더를 두 번 보내지 않을까요? 여기서도 PostgreSQL이 답을 줍니다. pg-boss는 작업을 꺼낼 때 `SELECT ... FOR UPDATE SKIP LOCKED`를 씁니다. 한 컨테이너가 잠근 작업은 다른 컨테이너가 건너뛰니 작업 하나는 한 곳에서만 꺼냅니다. 옛 컨테이너는 종료 신호를 받으면 새 작업을 꺼내지 않고 하던 작업만 마저 끝내는데 그 여유는 Docker 설정에서 줍니다. ```yaml title="종료 여유와 자원 제한" {3} x-api: &api # 하던 작업을 마칠 여유(pg-boss 90초 + 정리) stop_grace_period: 120s read_only: true cap_drop: - ALL deploy: resources: limits: memory: 512M cpus: '1' ``` docker-compose.prod.yml 일부 그래도 끝내지 못한 작업은 큐에 남았다가 새 컨테이너가 다시 실행합니다. 그래서 모든 작업은 두 번 실행돼도 결과가 같도록 만듭니다. 컨테이너는 메모리 512MB와 CPU 1개로 묶어서 한 컨테이너가 이상해져도 서버 전체가 함께 쓰러지지 않게 했습니다. 캐시는 사정이 조금 다릅니다. 두 컨테이너의 메모리 캐시는 서로를 모르니 그 사이에 바뀐 값은 다른 쪽 캐시가 만료될 때까지 몇 분 어긋날 수 있습니다. 이 틈은 PostgreSQL의 LISTEN/NOTIFY로 줄여 볼 생각입니다. 커밋할 때 연결된 서버들에 신호를 보내는 기능인데 모여에서는 이 신호로 웹 알림함을 실시간으로 새로 고치고 있습니다. ### 커넥션 풀과 DB 계정 RDS 하나를 두 컨테이너가 함께 쓰려면 커넥션 수도 계산해야 합니다. (이미지: 커넥션 예산) 컨테이너 하나는 커넥션을 최대 13개(앱 10개, pg-boss 3개) 씁니다. 배포 중에 두 컨테이너가 겹쳐도 26개에 migrate가 더해지는 정도라 RDS 한도 79개 안에 넉넉히 들어옵니다. 앱 계정은 60개까지만 쓸 수 있게 막아서 운영자가 들어갈 자리도 남겼습니다. 한 요청이 커넥션을 몇 개 잡는지도 따져야 합니다. 트랜잭션은 커넥션 하나 위에서 돌기 때문에 그 안의 쿼리를 `Promise.all`로 묶어도 빨라지지 않습니다. 그래서 `Promise.all`은 트랜잭션 밖에서 서로 기다릴 필요가 없는 조회에만 씁니다. ```ts title="서로 상관없는 세 조회 함께 기다리기" {1} const [stats, topTodos, streakContext] = await Promise.all([ todoReadRepository.getTodayTodoStats(ownerId, date), todoReadRepository.findTodayTopTodos(ownerId, date, TODAY_SUMMARY_TOP_TODOS_MAX), streakPort.getStreakContext(ownerId), ]); ``` get-todo-summary.use-case.ts 일부 홈 화면의 오늘 요약은 세 조회를 동시에 실행하는 대신 요청 하나가 커넥션을 세 개까지 잡습니다. > 이걸 놓쳐서 커넥션 풀이 바닥났던 경험은 [아직 출시도 안 했는데 커넥션 풀이 고갈됐다](/post/moyeo-connection-pool-exhaustion)에 따로 적어 두었습니다. DB 계정도 둘로 나눴습니다. 예전에는 API가 테이블을 지울 수도 있는 소유자 계정으로 붙었습니다. (이미지: 앱 전용 계정과 소유자 계정) ```sql title="앱 전용 DB 계정" {1-3} ALTER ROLE aido_app WITH LOGIN NOCREATEDB NOCREATEROLE CONNECTION LIMIT 60; ALTER ROLE aido_app SET statement_timeout = '15s'; ALTER ROLE aido_app SET lock_timeout = '5s'; -- 앞으로 만들 테이블에도 같은 권한 ALTER DEFAULT PRIVILEGES IN SCHEMA public, pgboss GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO aido_app; ``` app-role.sql 일부 앞의 비교표에 있던 "역할별 기본 설정"이 이것입니다. 계정 자체에 쿼리 시간 제한을 걸어 두면 느린 쿼리 하나가 커넥션을 오래 붙잡지 못합니다. *** ## 걷어 내며 만난 세 가지 함정 여기까지만 보면 순조로워 보이지만 실제로는 세 번 발목을 잡혔습니다. ### pg-boss로 옮겨도 사라지던 알림 작업 큐를 pg-boss로 옮기고 나서 문제가 다 풀린 줄 알았습니다. 그런데 팔로우, 응원, 찌르기 알림은 여전히 사라질 수 있었습니다. 이 알림들은 트랜잭션이 커밋된 뒤에 따로 큐에 넣고 있었기 때문입니다. 큐는 PostgreSQL로 옮겼지만 커밋과 큐 등록 사이의 틈은 Redis 시절과 똑같이 남아 있었습니다. 앞의 표에서 "사라지면 안 되는 일"로 분류한 알림들입니다. 이것들도 업무 변경과 같은 트랜잭션 안에서 넣도록 바꾸고 나서야 틈이 닫혔습니다. **큐가 어디 있느냐보다 작업을 언제 넣느냐가 문제였습니다.** ### Nginx를 바꾼 직후의 502 Nginx 설정을 바꾸고 곧바로 옛 컨테이너를 내리면 어떻게 될까요? 로컬에서 전환을 연습해 보니 전환 직후 들어온 요청 일부가 [`502 Bad Gateway`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/502)를 받았습니다. Nginx는 설정을 다시 읽어도 기존 워커를 바로 끄지 않고 받던 연결을 끝낼 때까지 남겨 둡니다. 그 사이 옛 워커는 여전히 옛 컨테이너로 요청을 보내는데 옛 컨테이너를 바로 내리면 이 요청들이 갈 곳을 잃습니다. ```bash title="옛 Nginx 워커가 빠질 때까지 기다리기" {2} # proxy_read_timeout(60초)보다 길게 NGINX_DRAIN_WAIT_S=70 wait_nginx_drain() { for ((waited = 0; waited < NGINX_DRAIN_WAIT_S; waited++)); do [[ -n "$(comm -12 <(printf '%s\n' "$draining_workers") <(nginx_workers))" ]] || return 0 sleep 1 done } ``` deploy.sh 일부 옛 워커가 모두 빠질 때까지 최대 70초를 기다립니다. Nginx가 응답을 기다리는 최대 시간이 60초라서 70초면 처리 중이던 요청은 모두 끝난 뒤입니다. ### 배포 중에 놓친 정기 작업 컨테이너가 바뀌는 순간에는 작업을 꺼내는 쪽이 잠깐 비어 있습니다. 예전에는 1분마다 도는 리마인더 확인 작업이 실행된 시각의 1분 동안만 확인했습니다. 그래서 배포 중에 한 번이라도 실행을 건너뛰면 그 1분 사이에 울려야 할 리마인더는 아무도 확인하지 않은 채 사라졌습니다. 그래서 모든 정기 작업에 놓친 실행을 어떻게 할지(`missed`)를 반드시 적게 했습니다. ```ts title="놓친 실행을 한 번 다시 돌리는 정기 작업" {6} // 놓친 실행은 한 번만 다시 보낸다(실행은 멱등) export const TODO_SERIES_MATERIALIZATION_QUEUE = defineQueue({ name: "todo-series-materialization.v1", payloadSchema: todoSeriesMaterializationPayloadSchema, retry: { retryLimit: 2, retryDelaySeconds: 30, retryBackoff: true }, schedules: [{ key: "daily-todo-series-materialization-scheduler", cron: "10 3 * * *", missed: "once" }], }); ``` todo-series-materialization.queue.ts 일부 리마인더 확인 작업은 여기에 하나를 더했습니다. 마지막으로 성공한 시각을 DB에 남겨 두고 다음 실행이 그때부터 지금까지를 최대 15분까지 한꺼번에 처리합니다. 15분보다 늦은 리마인더는 보내지 않습니다. 오전 9시 할 일 알림이 9시 20분에 오면 오히려 헷갈리기 때문입니다. *** ## 바깥 서비스가 멈출 때 서버 안의 작업을 잃지 않게 만들고 나니 다음 고민은 서버 밖이었습니다. 아이두는 말하거나 적은 내용을 할 일로 바꿀 때 Anthropic, Google, OpenAI의 AI 모델을 부릅니다. 이 중 한 곳이 멈추면 어떻게 될까요? (이미지: AI 업체가 멈춰도 기능이 이어지는 흐름) 업체마다 서킷 브레이커를 세 개씩 두었습니다. 크레딧이 떨어지면 결제 회로, 인증이 실패하면 인증 회로, 과부하나 시간 초과가 이어지면 장애 회로가 열립니다. 회로가 열린 업체는 잠시 건너뛰고 다음 업체로 넘어갑니다. **한 업체가 멈춰도 할 일 만들기는 계속됩니다.** 돈이 걸린 일은 사라지면 안 된다는 원칙도 그대로 지킵니다. 이용 횟수는 호출 전에 미리 차감했다가 결과가 나오면 확정하고 모든 업체가 실패하면 돌려줍니다. 서버의 제한 시간은 앱보다 짧게 잡아서 앱이 먼저 끊지 않고 "횟수는 차감되지 않았어요"까지 받게 했습니다. 사용자 요청과 밤에 도는 리포트 작업은 동시에 부를 수 있는 자리를 따로 두었고 전체, 배치 작업, 사용자 하루 세 단계의 예산과 설정 하나로 호출을 멈추는 Kill Switch도 있습니다. 예산 사용량은 앞에서 본 조건부 upsert 테이블에 그대로 쌓입니다. *** ## 바꾸고 나서 달라진 것 (이미지: Redis를 쓰던 때와 지금) 가장 먼저 비용이 줄었습니다. 캐시를 서버 메모리로 바꾸고 ElastiCache를 없애면서 월 인프라 비용이 $45에서 $29로 약 35% 줄었습니다. Redis 연결이 끊겨 모든 요청이 멈추는 문제도 더는 일어나지 않습니다. 작업 큐와 잠금, 발송 제한이 모두 이미 쓰고 있던 DB 안으로 들어왔기 때문입니다. DB가 멈추면 어차피 서비스도 멈추니 지켜볼 저장소가 하나로 줄었습니다. 무엇보다 처음에 세운 두 숙제가 풀렸습니다. **사라지면 안 되는 일이 할 일과 함께 커밋됩니다.** 배포 중에 할 일을 완료해도 친구 알림은 조금 늦을 뿐 새 컨테이너가 보냅니다. 서버가 바뀌는 순간에도 Nginx가 요청을 살아 있는 컨테이너로 넘기니 사용자는 배포를 알아채지 못합니다. 대신 작업 처리량이 PostgreSQL에 묶이고 서버가 한 대라 서버 자체에 문제가 생기면 그동안은 요청을 받지 못합니다. 지금 규모에서는 충분하다고 판단했고 커질 때를 대비해 바꾸기 쉬운 구조를 만들어 두었습니다. *** ## 바꾸기 쉽게 만들어 둔 구조 처음부터 잘되는 서비스는 많지 않습니다. 그래서 처음부터 큰 인프라를 깔기보다 **작게 시작하되 나중에 쉽게 바꿀 수 있게** 만드는 쪽을 택했습니다. AI가 코드를 대신 써 주는 요즘, 돌아가는 코드는 누구나 만들 수 있지만 기획이 바뀌거나 사용자가 늘었을 때 어디를 고치면 되는지 보이는 구조는 아직 개발자가 설계해야 한다고 생각합니다. 아이두 서버는 할 일, 친구, 알림, 결제 같은 기능마다 폴더를 나누고 각 기능을 같은 네 칸으로 나눕니다. (이미지: 기능 하나의 폴더 구조와 의존 방향) 핵심은 포트(Port)와 어댑터입니다. 포트는 "무엇을 하는지"만 정해 둔 약속이고 "어떻게 하는지"는 어댑터가 맡습니다. 업무 코드는 포트만 알기 때문에 어댑터를 바꿔도 업무 코드는 그대로입니다. 예를 들어 운영자에게 가는 알림은 지금 Discord로 보냅니다. 하지만 업무 코드는 Discord를 모르고 "어느 채널로 무엇을 보낸다"는 약속만 압니다. Slack으로 옮기고 싶다면 어댑터를 만들어 표에 한 줄을 더하면 됩니다. ```ts title="운영 알림 포트와 어댑터 선택표" ins={11-12} // 어디로 보내는지 모르는 포트 export abstract class AdminNotifierPort { abstract send(channel: AdminNotificationChannel, notice: AdminNotice): Promise; } // 설정값으로 어댑터를 고른다 const adapters = { discord: (config, http, policies, clock) => new DiscordAdminNotifierAdapter(config.discordWebhookUrls, http, policies, clock), log: () => new LogAdminNotifierAdapter(), slack: (config, http, policies, clock) => new SlackAdminNotifierAdapter(config.slackWebhookUrls, http, policies, clock), } satisfies Record; ``` admin-notifier-selection.adapter.ts 일부, Slack 줄은 예시 다른 바깥 서비스도 같은 방식입니다. 푸시는 지금 Expo로 보내지만 FCM으로 바꿔도 발송 큐와 재시도 로직은 그대로입니다. 앞에서 본 AI 업체 세 곳도 같은 포트 뒤에 있습니다. 결제는 RevenueCat이 보낸 데이터를 어댑터가 "구독 시작", "갱신", "만료" 같은 아이두의 말로 바꿔 넘기니 결제 서비스를 바꿔도 이 번역기만 새로 만들면 됩니다. 할 일 완료 UseCase 코드에 Drizzle이 한 번도 나오지 않았던 것도 같은 이유입니다. 실제로 ORM을 Prisma에서 Drizzle로 옮겼을 때도 주로 어댑터를 다시 쓰는 일이었습니다. *** ## 다음으로 미뤄 둔 확장 지금 구조는 서버를 늘리지 않는 쪽에 맞춰져 있습니다. 하지만 늘려야 할 때 무엇을 바꿀지는 미리 정해 두었습니다. (이미지: 서버를 늘릴 때의 구성, 숫자는 켜는 순서) | 순서 | 이런 신호가 오면 | 이렇게 바꿉니다 | | -- | ------------------- | ------------------------------------ | | 1 | 작업이 몰려 API 응답이 느려진다 | 작업을 처리하는 워커를 따로 떼고 캐시를 Redis 계열로 옮긴다 | | 2 | RDS 메모리 경보가 울린다 | RDS를 한 단계 큰 것으로 올린다 | | 3 | 서버 한 대로 버티기 어렵다 | ALB를 붙이고 서버를 늘린다 | | 4 | DB 연결 수가 한도에 가까워진다 | PgBouncer나 RDS Proxy를 둔다 | 신호는 CloudWatch와 Sentry 경보가 먼저 알려 줍니다. 어느 단계든 바뀌는 건 설정과 인프라, 그리고 어댑터입니다. 캐시는 `CACHE_TYPE=redis` 한 줄이면 다시 Redis로 돌아갑니다. **Redis를 버린 게 아니라 필요할 때 꺼내 쓸 수 있게 넣어 둔 겁니다.** *** ## 마치며 처음에는 작업을 잃지 않으려면 Redis 같은 저장소를 하나 더 붙여야 한다고 생각했습니다. 하나씩 풀어 보니 필요한 건 새 부품이 아니라 **이미 쓰고 있던 PostgreSQL을 제대로 아는 것**이었습니다. 해외 강의에서 왜 그렇게 PostgreSQL을 쓰는지 이제야 조금 알겠습니다. 글을 마무리하던 즈음 세무사 시험 수석 합격자가 초소형 카메라와 생성형 AI로 답을 받아 적었다고 [자백했다는](https://www.hankookilbo.com/news/article/A2026111510180003684) 소식이 들려왔습니다. 경영학을 전공하며 회계사 시험을 잠깐 준비해 본 터라 응시자 평균이 30점대인 과목의 만점이 무슨 뜻인지는 어렴풋이 알았습니다. 그래서 놀랍기보다는 생각이 많아졌습니다. 외우고 이해해서 푸는 시험이 지금도 맞는 잣대인지, 시험의 모양부터 다시 그려야 하는 건 아닌지 말입니다. 이번 일을 계기로 교육은 물론 채용과 고용을 이어 가는 방식까지 기술의 속도에 뒤처지지 않고 하루빨리 발전했으면 합니다. 시대가 바뀌면 누군가는 손해를 보고 누군가는 기회를 얻기 마련입니다. 그 기회도 꾸준히 준비해 온 사람이라면 충분히 잡을 수 있다고 생각합니다. 어쩌면 이런 기회를 얻는 과정 중 하나는 지금처럼 회사 업무를 하든 개인적으로 사이드 프로젝트를 하든 발전하는 AI의 속도에 쫄지만 말고 안 해 본 일에 도전해 보는 것입니다. 지금은 그런 도전을 하기에 제일 좋은 시기이고 한 사람이 다양한 업무를 해낼 수 있는 시기이기도 합니다. 그래서 나만 가질 수 있는 강점과 경쟁력이 무엇인지 계속 고민하면서 현실에 안주하지 않고 무엇인가 도전해 보는 것이 지금 시대에 제일 중요하지 않을까 하는 개인적인 생각을 해 봅니다. *** 혹시 아이두가 궁금하신 분이 있다면 한 번 써 보셔도 좋겠습니다. 말하거나 적으면 AI가 할 일로 정리해 주고 친구와 서로의 할 일을 응원하면서 끝까지 해낼 수 있게 돕는 앱입니다. iPhone, Android, Mac, 태블릿에서 모두 쓸 수 있습니다. (이미지: 아이두\~ 아이두\~) [App Store](https://apps.apple.com/kr/app/%EC%95%84%EC%9D%B4%EB%91%90-ai-%ED%88%AC%EB%91%90-%ED%94%8C%EB%9E%98%EB%84%88/id6757722325) | [Google Play](https://play.google.com/store/apps/details?id=com.aido.mobile\&pcampaignid=web_share\&pli=1) | [아이두(Aido) 공식 웹사이트](https://www.aido.kr/) | [공식 인스타그램](https://www.instagram.com/aiddoo_official/) --- # 혼자 서비스를 운영한다는 것 > SNS 운영 도구 모여를 혼자 만들며 정한 가격과 지표, 가입 CTA와 GA4 설계, 계정 보호, SES 메일, 장애 알림, 운영 자동화의 기준을 실제 화면과 숫자로 정리한다. - 원문: https://www.yolog.co.kr/post/moyeo-product-operations - 카테고리: 이야기 - 발행: 2026-10-11 - 수정: 2026-10-14 회사에서 제품을 만들고 여러 사이드 프로젝트를 운영하면서 서비스를 알리는 일이 어렵다고 자주 느꼈다. 사용자가 찾아온 뒤에도 풀리지 않는 질문이 있었다. 왜 돈을 내고 쓰는지, 갑자기 가입자가 늘었다면 어디에서 무엇을 보고 들어왔는지 알고 싶었다. 그래야 무엇을 고치고 어디에 힘을 쏟을지 정할 수 있었다. [아이두](https://aido.kr)를 만들 때도 그랬다. 내가 쓰려고 만든 서비스에 누군가 결제했을 때는 기쁘면서도 의외였다. 어떤 불편을 해결해 줬기에 돈을 냈을까 궁금했다. 외국인 사용자의 가입을 보고 다국어 지원을 시작하기도 했다. 쓰는 사람을 알아가면서 처음에는 생각하지 못했던 방향으로 제품을 바꾸게 됐다. 이런 경험이 쌓일수록 유입과 사용 과정을 기록할 필요를 느꼈다. 지표로 어디에서 변화가 생겼는지 찾고, 사용자의 이야기를 들으며 결제하거나 떠난 이유를 이해하고 싶었다. 잘된 시도를 이어 가고 막힌 부분을 고치려면 필요한 일이었지만, 꾸준히 추적하기는 어려웠다. 인원이 적을수록 더 그렇다. 기능을 만들고 문의에 답하는 사이에 홍보할 글과 이미지를 준비해야 한다. 여러 SNS에 게시한 뒤에는 반응과 유입도 살펴야 한다. 일이 생길 때마다 다른 화면을 열고 데이터를 모으다 보니, 혼자 이 과정을 계속 챙기는 데 한계를 느꼈다. [모여](https://moyeo.io)는 이런 부담을 줄이려고 만든 서비스다. SNS 게시물 작성과 예약, 댓글 응대, 성과 확인을 한곳에서 처리하고 브랜드를 소개하거나 문의를 받는 소개 페이지도 제공한다. 홍보한 결과를 보고 다음 작업까지 이어 가도록 돕고 싶었다. 기획과 디자인부터 프론트엔드, 서버, 운영까지 혼자 맡고 있다. > 모여는 2026년 10월 14일 정식 출시했다. Instagram과 Threads 권한 심사, Google 로그인 심사를 마쳤고 YouTube API 할당량 심사는 진행 중이다. [moyeo.io](https://moyeo.io)에서 바로 써 볼 수 있다. 홈에는 연결한 채널의 상태와 오늘 할 일을 함께 두었다. 답하지 않은 댓글과 최근 반응을 확인한 뒤 다음 게시를 준비한다. 여러 앱에서 따로 하던 일을 이곳에서 이어서 처리하도록 구성했다. (이미지: 모여테스트 워크스페이스의 홈. 연결된 채널과 오늘 할 일을 함께 본다.) 처음부터 이런 제품을 생각한 것은 아니다. 출발점은 AI 카드뉴스 제작 도구였다. 방향을 바꾸는 동안 누구에게 필요한지, 얼마를 받아야 하는지, 어떤 숫자를 보고 다음 결정을 내릴지 다시 생각하게 됐다. 이번 글에는 그 과정에서 고민한 제품과 운영의 기준을 정리했다. *** ## 카드뉴스에서 시작한 모여 처음에는 로고와 캐릭터, 제품 사진을 넣고 이야기를 짧게 적으면 브랜드에 맞는 카드뉴스를 만드는 도구를 생각했다. 긴 프롬프트를 작성하고 결과를 편집기로 옮기는 수고를 줄이고 싶었다. 여러 제작 도구를 써 봤지만 내가 원한 조건을 한 번에 만족시키기는 어려웠다. 한국어 문구가 깨지거나, 카드마다 이미지 분위기가 달라지거나, 마음에 들지 않는 부분만 고치기 어려웠다. 이미지 한 장의 완성도와 실제 홍보에 바로 쓸 수 있는 카드 묶음의 완성도는 달랐다. 아래는 당시 만들었던 편집기다. 카드를 직접 편집하고, 선택한 부분을 AI에 수정 요청하고, 게시 전에 미리 보는 흐름까지 구현해 보았다. (이미지: 초기 카드뉴스 프로토타입. 카드 편집과 선택한 문구의 AI 수정을 한 화면에 두었다. 현재 모여와는 다른 초기 구상이다.) 문구를 이미지 모델에 함께 맡기는 방법과 배경을 생성한 뒤 텍스트를 별도로 얹는 방법을 고민했다. 전자는 모델의 표현력에 기대는 비중이 크고, 후자는 글자를 안정적으로 표시하고 수정하기 좋다. 대신 배치와 줄바꿈을 직접 구현하고, 이미지와 글이 어울리도록 조정해야 했다. 아래는 당시 카드뉴스 서비스 프로토타입으로 만든 실제 결과물이다. 카페 홍보용 이미지에 문구를 넣고, 마지막에는 게시물 저장이나 방문을 유도하는 내용을 담았다. (이미지: 초기 카드뉴스 서비스 프로토타입으로 만든 실제 결과물.) ### 다시 만드는 비용 비용도 문제였다. 다섯 장 중 두 장만 마음에 들면 인물이나 분위기를 맞추려고 다시 만들게 된다. 글자를 따로 얹어도 이미지 자체를 재생성하는 비용은 남는다. 아래는 모델과 설정을 고정한 **정사각형 이미지의 출력 비용 예시**다. 다섯 장을 만든 경우와 두 번 다시 만들어 총 열다섯 장을 생성한 경우를 비교했다. 과거 청구액이 아닌 재생성 원가를 가늠하기 위한 계산이다. | 모델과 설정 | 5장 | 15장 | | ------------------------------ | -------: | -------: | | Gemini 3.1 Flash Image, 1K | 약 469원 | 약 1,407원 | | GPT Image 2, 1024×1024, Medium | 약 371원 | 약 1,113원 | | GPT Image 2, 1024×1024, High | 약 1,477원 | 약 4,431원 | 장당 출력 단가는 각각 0.067달러, 0.053달러, 0.211달러이고, 환율은 계산 편의를 위해 달러당 1,400원으로 가정했다. 입력 텍스트와 참조 이미지, 저장·전송 비용, 세금은 별도다. 모델과 설정별 화질이 같다는 의미도 아니다. 단가는 [Google 가격표](https://ai.google.dev/gemini-api/docs/pricing)와 [OpenAI 이미지 생성 비용 안내](https://developers.openai.com/api/docs/guides/image-generation#calculating-costs)를 참고했다. 원가를 계산할 때 기준으로 삼아야 할 것은 **사용자가 만족해서 가져간 결과 한 세트**였다. 몇 번까지 다시 만들게 할지, 실패하면 사용량을 돌려줄지, 언제 환불할지 정해야 가격을 붙일 수 있었다. 실패한 요청에도 요금이 붙는지는 공급자 정책과 실패 단계에 따라 따로 봐야 한다. ### 방향을 바꾼 이유 그사이 이미지 모델도 빠르게 발전했다. 프로토타입을 만들 때는 결과가 아쉬웠는데, 시간이 지나자 프롬프트를 조금만 다듬어도 괜찮은 이미지가 나왔다. 고객이 이미 사용하는 범용 AI 도구에서 충분한 이미지를 얻는다면, 별도의 제작 서비스에 비용을 더 낼 이유는 무엇일까. 브랜드 맥락을 보존하거나 편집 시간을 줄이는 것처럼 추가로 해결하는 일이 있어야 했다. 구독형 AI에도 사용 한도는 있지만, 고객에게는 이미 지불한 도구로 작업을 끝내는 선택지가 있었다. 돌아보면 처음에는 원하는 결과물과 만드는 방법을 먼저 구체화했다. 누가 이 작업을 얼마나 자주 하고, 지금 어떤 방식으로 해결하며, 무엇에 돈을 낼지는 충분히 좁히지 못했다. 이미지 품질을 높이는 데 시간을 더 쓰기 전에, **내가 감당할 원가 안에서 고객이 반복해서 선택할 이유**를 먼저 확인할 필요가 있었다. 그래서 카드뉴스 제작 중심의 구상은 프로토타입 단계에서 접었다. 내가 직접 겪었던 홍보 과정을 돌아보니 이미지를 만든 뒤에도 할 일이 많았다. 어디에 언제 올릴지 정하고, 채널마다 내용을 조정하고, 질문에 답하고, 다음에 무엇을 올릴지 판단해야 했다. (이미지: 콘텐츠를 만드는 순간에서 꾸준히 운영하는 과정으로 관심을 넓혔다.) 모여는 사용자가 다른 도구에서 준비한 콘텐츠를 가져와 게시하고, 댓글에 답하고, 다음 홍보를 준비하는 서비스로 방향을 바꿨다. 이미지 생성 모델이 좋아지면 그 결과물을 모여로 가져와 쓰면 된다. 내가 풀고 싶은 문제는 콘텐츠를 만든 뒤에 남아 있는 운영의 번거로움이었다. PMF(Product-Market Fit)는 제품이 시장의 수요와 맞아 지속적으로 선택받는 상태를 뜻한다. 당시에는 그 단계에 이르기 전에 원가와 대체재 문제를 발견했다. 방향을 바꾼 뒤에는 모여가 해결하려는 일이 실제로 반복되는지, 고객이 그 해결에 돈을 낼 의향이 있는지부터 확인해야 했다. *** ## 다시 쓰는 사용자를 찾아서 먼저 만나고 싶은 고객은 SNS를 직접 운영하면서 다른 업무도 함께 맡는 1인 사업자와 작은 팀이다. 자기 상품이나 서비스를 잘 알아도 홍보에 쓸 시간은 부족하기 쉽다. 콘텐츠를 만든 뒤 여러 채널을 오가며 일을 마무리하는 데에도 시간이 든다. 개발 동아리를 운영하고 교육을 진행하며 약 2,000명을 만났다. 그중 지금도 연락하는 분들과 초기 스타트업을 운영하는 대표님들에게 제품을 보여 주고 의견을 들을 기회가 있었다. 제품을 처음 보고 좋다고 말해 주는 것도 고마웠지만, 더 알고 싶은 것은 며칠 뒤에도 쓰는 이유였다. 먼저 써 본 분들에게 어떤 일을 반복해서 맡기는지, 한 번 써 보고 멈췄다면 어디가 불편했는지를 물었다. 소수라도 꾸준히 쓰는 사람이 있다면 그 사람의 업무에서 모여가 어떤 역할을 하는지 이해하고 싶었다. 이후에도 의견을 들을 때는 최근에 했던 작업을 함께 되짚어 보려 한다. 어떤 콘텐츠를 어느 채널에 올렸는지, 중간에 다른 앱을 열어야 했는지 물으면 구체적인 불편을 찾기 좋다. 새 기능을 요청받았을 때도 먼저 그 기능이 필요해진 상황을 알아보려 한다. * **최근 어떤 일을 끝냈는가?** 실제 사용한 흐름과 기대했던 결과를 확인한다. * **중간에 어디에서 멈췄는가?** 연결, 작성, 예약, 결과 확인 중 어려운 지점을 좁힌다. * **다시 사용한 이유는 무엇인가?** 업무에 계속 필요한 기능과 한 번 살펴본 기능을 구분한다. * **기존 방식으로 돌아갔다면 왜인가?** 익숙함, 품질, 시간, 가격 중 어떤 문제가 남았는지 묻는다. 그다음에는 비슷한 고객도 겪는 문제인지, 모여가 해결하려는 일과 맞는지 살핀다. 혼자 만드는 만큼 구현한 뒤에 유지할 시간까지 생각해야 한다. 지금은 첫 게시를 마친 사람이 다음 주에도 게시하는지, 성과를 본 뒤 새 콘텐츠를 준비하는지, 소개 페이지로 들어온 문의를 처리하는지 살피는 단계다. 이런 작업이 반복되는 모습을 봐야 모여를 계속 쓰는 이유와 유료로 바꿀 이유가 구체적으로 보인다. (이미지: 처음 써 보는 것, 다시 찾는 것, 비용을 지불하는 이유는 각각 확인해야 한다.) 이 관점으로 게시물 작성부터 성과 확인까지의 흐름을 다시 살폈다. 한 번의 게시를 끝낸 뒤에도 다음 작업이 모여 안에서 이어져야 했다. *** ## 게시 다음에 할 일 SNS마다 본문 길이와 사진 수, 동영상 조건이 다르다. 같은 글을 여러 번 복사하는 수고를 줄이되, 게시 전에 채널별 조건은 보여 줘야 했다. 작성 화면에서는 공통 본문과 이미지를 준비한 뒤 채널별로 조정한다. 아래는 모여 소개 게시물을 작성하는 화면이다. Instagram과 Threads를 함께 선택하고 게시될 모습을 옆에서 확인한다. (이미지: 여러 채널을 선택한 작성 화면. 공통 내용에서 시작해 채널별로 다듬고, 게시될 모습을 미리 확인한다.) 예약할 때는 채널과 시간대를 정하고 게시 결과까지 확인하게 했다. API가 지원하는 형식과 권한 안에서 처리하며, 앱에서 직접 마무리해야 하는 요소는 설명한다. 외부 도구가 앱의 기능을 모두 그대로 제공하지는 못하기 때문이다. (이미지: 채널별 캘린더. 같은 주의 Threads·Instagram 게시물을 비교하고, 게시물이 없는 채널도 함께 확인한다.) 모여에서 관리한 게시물과 외부 채널에서 가져온 게시물은 출처를 구분한다. 상태는 예약, 게시 완료, 확인 필요, 실패로 나누고 달력을 보는 시간대도 표시했다. 게시한 다음에는 댓글을 확인해야 한다. 그래서 댓글함에 원래 게시물과 답변 필요 상태, 답글 입력란을 함께 두었다. 어떤 글에 달린 질문인지 다시 찾아보지 않고 답변을 이어 가도록 했다. (이미지: 댓글함. 게시물과 반응을 살피면서 답변이 필요한 댓글을 고르고, 같은 화면에서 답글을 작성한다.) ### 성과를 보고 다음 작업으로 여러 채널의 숫자를 한곳에 모아도 무엇을 할지 모르면 사용자는 화면을 다시 해석해야 한다. 그래서 성과를 확인한 자리에서 반응이 좋았던 게시물을 열고, 다음 글을 준비하거나 밀린 답변을 처리하게 했다. 숫자를 본 다음 할 일로 바로 넘어가게 하는 데 신경을 썼다. 성과 화면에서는 연결한 SNS 채널의 조회수와 반응, 댓글 응답률을 함께 본다. (이미지: 기간별 반응 흐름 아래에 이번 주 할 일을 배치했다. 답글 작성과 다음 게시물 준비로 바로 이어진다.) 그래프 아래에는 답변이 필요한 댓글, 이번 기간에 반응이 좋았던 게시물, 앞으로 예약한 게시물을 함께 두었다. 조회수를 확인한 뒤 다시 메뉴를 찾아다니는 대신 그 자리에서 작업을 시작하는 구조다. 플랫폼마다 제공하는 지표와 수집 시점이 달라 어디까지 비교할 수 있는지도 설명해야 했다. 제공하지 않는 값은 0으로 채우지 않고, 마지막 수집 시각과 집계 대기 상태, 해당 지표의 채널 범위를 표시했다. (이미지: 성과 요약과 채널 비교. 전체 수치가 움직였을 때 어느 채널과 게시물을 더 살펴볼지 좁힌다.) 추천 게시 시간도 표본과 함께 읽어야 한다. 몇 편의 반응이 좋았다고 그 시간이 늘 유리하다고 단정하기는 어렵다. 그래서 정답이 아니라 사용자가 후보 시간을 골라 시험해 볼 근거로 보여 준다. (이미지: 댓글 응답률과 추천 게시 시간. 시간대별 반응과 표본 수를 보고 다음 게시를 준비한다.) *** ## SNS에서 문의까지 SNS 게시물을 보고 관심이 생긴 사람은 프로필 링크를 누른다. 그런데 열린 페이지에서 무엇을 하는 곳인지, 어떻게 문의하는지 찾기 어렵다면 홍보는 거기서 끊긴다. 소개 페이지는 브랜드 설명과 실제 행동 사이를 이어 주려고 넣었다. 사용자는 블록을 조합해 상품과 연락 방법, 위치, 예약 신청을 한 페이지에 담는다. 방문자가 원하는 날짜와 연락처를 남기면 운영자가 일정을 조율하는 방식이다. (이미지: 소개 페이지의 방문자 화면. 브랜드 설명에서 상담 예약 신청과 연락, SNS 채널로 이어진다.) 실제 화면은 [모여 공식 소개 페이지](https://moyeo.io/@moyeo.official)에서 열어 볼 수 있다. 편집할 때는 방문자에게 보일 모습을 옆에서 확인한다. (이미지: 블록을 편집하면서 방문자에게 보일 모습을 함께 확인한다.) ### 쓰던 페이지에서 옮겨 오기 링크 모음 페이지를 만드는 일 자체는 어렵지 않다. 작은 가게를 꾸리는 사람에게 더 어려운 건 여러 홍보 중 무엇이 통했는지 아는 쪽이다. 다만 이미 리틀리나 링크트리, 인포크링크를 쓰고 있다면 옮기는 일부터 부담이라, 쓰던 페이지 주소만 넣으면 링크를 찾아오게 했다. (이미지: 다른 서비스의 링크 가져오기. 쓰던 링크 모음 주소를 넣고 링크를 찾는다.) 서버가 공개 프로필에서 링크를 꺼내 최대 50개까지 보여 주고, 사용자가 고른 링크만 페이지에 붙인다. 사용자가 넣은 주소로 서버가 직접 요청하는 기능이라 SSRF도 막아야 했다. https와 공인 IP만 허용하고 리다이렉트마다 다시 검사하며, 5초나 1MiB를 넘으면 멈춘다. ### 방문 한 번을 어떻게 셀까 분석이 핵심이라면 숫자부터 믿을 수 있어야 한다. 운영자가 미리보기를 열 때마다 방문이 늘거나 링크 미리보기 봇이 손님으로 잡히면 성과 화면이 통째로 틀어진다. 그래서 무엇을 세지 않을지부터 정했다. 봇과 브라우저가 미리 불러온 요청([`Sec-Purpose`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Sec-Purpose)), 모여에 로그인한 채 연 페이지, 편집기 미리보기는 세지 않는다. 방문도 페이지가 실제로 화면에 보일 때만 보낸다. 그다음 기준은 아래와 같다. | 무엇을 | 어떻게 | 왜 | | --------- | ---------------------------------------------- | ------------------ | | 같은 탭 새로고침 | `sessionStorage`로 탭마다 한 번만 센다 | 새로고침이 방문을 부풀리지 않게 | | 다시 온 방문자 | `localStorage`에 마지막 방문일을 30일 두고 서버에는 참·거짓만 보낸다 | 식별자 없이 재방문만 알려고 | | 블록 노출 | 블록이 50% 이상 보이면 방문마다 한 번 | 스쳐 지나간 블록을 빼려고 | | 링크 클릭 | 서버의 `/go` 리다이렉트를 거친 클릭만 센다 | 실제로 이동한 클릭만 남기려고 | | 머문 시간 | 페이지가 가려질 때 보내고 30분에서 자른다 | 열어 둔 탭이 평균을 흔들지 않게 | IP와 `User-Agent`를 해시해 방문자를 묶는 방법은 일부러 쓰지 않았다. 한국 이동통신망은 CGNAT로 많은 사람이 같은 공인 IP를 나눠 써서, 서로 다른 손님이 한 명으로 합쳐질 수 있다. IP는 요청 횟수를 제한하는 데만 쓰고 저장하지 않는다. 쿠키도 쓰임을 좁혔다. 세션 쿠키 `moyeo-bio-source`는 처음 들어온 경로를 기억했다가 같은 방문의 클릭과 신청을 그 경로로 이어 기록한다. `moyeo-bio-visitor`는 링크 제목 A/B 테스트의 그룹을 나눌 때만 읽고 통계에는 쓰지 않으며, 개인정보 처리방침에도 그렇게 적었다. ### 어디에서 왔는가 방문 경로는 `utm_*` 파라미터와 [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Referer)처럼 확실한 단서부터 보고, ChatGPT나 Perplexity에서 온 방문은 AI 검색으로 나눈다. 그래도 모르면 인앱 브라우저의 `User-Agent`를 보고, 아무 단서가 없을 때만 직접 방문으로 센다. 그런데 Instagram 앱에서 열린 방문은 프로필 링크에서 왔을까, DM에서 왔을까? 이런 단서만으로는 가리기 어렵다. 그래서 프로필과 DM 자동 응답, Threads, 네이버 스마트플레이스, QR처럼 링크를 붙일 자리마다 코드가 다른 공유 링크를 만들게 했다. 코드가 붙은 방문은 추측보다 코드를 따른다. (이미지: 유입 경로별 공유 링크. 같은 소개 페이지라도 링크를 붙인 위치마다 다른 링크를 쓴다.) 성과 화면에서는 경로별로 방문과 링크 클릭, 손님 활동을 나란히 본다. 손님 활동은 예약, 문의, 전화, 소식 받기처럼 클릭보다 한 걸음 더 나간 행동이다. (이미지: 방문 경로별로 방문·링크 클릭·손님 활동을 비교한다. 수치는 가렸다.) 방문을 많이 모은 채널과 실제 연락으로 이어진 채널은 다를 수 있다. 어디에 홍보를 더 할지는 그 차이를 봐야 정할 수 있다. 방문 국가와 지역은 Cloudflare가 요청에 붙여 주는 값을 쓰고, 지역은 국내만 시·도 단위로 남긴다. (이미지: 방문 국가 지도. 방문이 있었던 대한민국과 미국을 표시했다. 수치는 가렸다.) 기기는 Client Hints를 먼저 보고, 없으면 `User-Agent`로 휴대폰·컴퓨터·태블릿을 나눈다. (이미지: 기기별 방문과 국내 시·도 분포, 손님이 오는 요일·시간대. 수치는 가렸다.) 해외 방문이 보이면 그 언어의 소개가 필요한지, 휴대폰 방문이 많다면 작은 화면에서 신청 양식이 편한지 살핀다. 손님이 몰리는 시간대는 다음 게시 시점을 정할 때 참고한다. ### 보인 블록과 눌린 블록 클릭이 적다는 사실만으로는 무엇을 고칠지 알기 어렵다. 그래서 블록마다 보인 수와 누른 수를 따로 센다. (이미지: 블록별 보인 수와 누른 수, 누른 비율. 수치는 가렸다.) 예약 버튼까지 내려온 사람이 적다면 위치를 바꾸고, 충분히 보였는데도 누르지 않았다면 문구를 고친다. 이렇게 기록하느라 방문자를 기다리게 해서는 안 됐다. Worker는 먼저 응답하고 이벤트는 `waitUntil`로 뒤에서 넘기며, API는 이를 모아 10초마다 한꺼번에 저장한다. 서버가 멈추면 그 10초를 잃을 수 있지만 감수하기로 했다. ### 페이지 밖으로 이어지는 흐름 다른 링크 모음 서비스와 가장 다른 점은 소개 페이지가 모여의 게시·댓글 기능과 이어져 있다는 것이다. 게시물에 소개 페이지 링크를 넣을 수 있고, 게시한 글마다 공유 링크가 따로 생겨 어떤 글이 방문을 데려왔는지 "게시물에서 온 손님"에서 보인다. Instagram 댓글에 정해 둔 키워드가 달리면 소개 페이지 링크를 DM으로 보낸다. 신청과 소식 메일은 손님의 정보를 받는 곳이라 더 조심했다. 예약과 문의 신청의 개인정보는 건마다 암호화하고, 소식 메일 구독은 확인 메일을 한 번 더 거친다. 이미 쓰는 GA4나 메타 픽셀도 연결할 수 있지만, EEA·영국·스위스 방문자에게는 동의한 뒤에만 켠다. 성과 화면에는 다음 할 일도 둔다. 최근 14일을 정해 둔 규칙으로 살펴, 검색 유입이 없으면 검색 정보를 채우고 공유 링크 방문이 없으면 경로별 링크를 만들라고 권한다. (이미지: 소개 페이지 성과의 다음 할 일. 방문이 없을 때도 검색 정보와 공유 링크부터 준비하게 한다.) AI가 아닌 규칙 기반 제안이라 왜 이 일을 권하는지 그대로 설명할 수 있다. 숫자를 보여 주는 데서 끝내지 않고, 믿고 다음 행동을 고를 수 있는 숫자를 만들고 싶었다. *** ## 시장과 가격 여기까지가 모여가 사용자에게 주려는 것이다. 게시하고, 반응을 보고, 문의까지 받는 흐름을 한곳에 모았다면 이제 누구에게 얼마를 받을지 정해야 했다. 초기 스타트업에서 일하며 시장 규모와 고객 확보에 관한 이야기를 자주 들었다. 직접 서비스를 만들고 나니 누구에게 먼저 다가갈지 정하는 데도 필요한 질문이었다. SNS를 쓰는 사람 중에서도 운영에 어려움을 겪고, 그 문제를 해결하려고 도구에 돈을 낼 고객을 좁혀야 했다. TAM, SAM, SOM은 이 범위를 나누는 데 도움이 됐다. * **TAM, 전체 잠재시장**: 국내외에서 SNS 운영을 위해 도구에 비용을 지불할 수 있는 전체 수요다. * **SAM, 현재 제공 가능한 시장**: 한국어와 현재 지원 채널, 결제·고객 지원 범위 안에서 실제로 도울 수 있는 고객이다. * **SOM, 초기 확보를 목표로 하는 시장**: 내가 도달하고, 사용을 도와주고, 계속 의견을 들을 수 있는 고객이다. 지금은 국내의 1인 사업자와 작은 팀에 집중한다. 업무 이야기를 듣고 첫 사용을 돕기 좋기 때문이다. 초기 고객 수를 정할 때는 혼자서 얼마나 지원할 수 있는지도 고려해야 한다. 시장을 금액으로 추정하려면 업종별로 대상 고객이 몇 곳인지, 얼마나 지불할 의향이 있는지 확인해야 한다. 대상 고객 수에 예상 연간 이용 금액을 곱해 시장을 추정하는 방식이다. 초기 확보 목표인 SOM은 실제 유입과 전환, 유지 데이터를 얻으면서 고칠 계획이다. ### 국내 고객과 해외 사용 해외에서도 사용할 가능성은 열어 두었다. 게시 예약은 지역 날짜와 시각에 `Asia/Seoul` 같은 IANA 시간대 식별자를 함께 저장하고, 실제 실행할 시점은 협정 세계시인 UTC로 계산한다. 서머타임 때문에 존재하지 않거나 두 번 나타나는 시각도 처리해야 한다. 일정을 보는 시간대와 성과를 집계하는 기준, 구독의 결제 기준도 구분했다. 팀원마다 같은 하루를 다르게 해석하거나, 설정을 바꿨다는 이유로 결제일이 움직이면 운영하기 어렵기 때문이다. 해외 고객을 만나려면 언어와 현지의 업무 방식, 결제와 지원 방식도 검증해야 한다. 지금은 국내 고객에게 집중하되, 시간대처럼 나중에 고치려면 여러 기능을 함께 바꿔야 하는 기준은 일찍 정리하려 했다. ### 채널 수에 따른 요금 과금 단위는 연결한 SNS 채널로 잡았다. 채널이 늘면 고객이 관리하는 범위와 수집·처리할 일이 함께 늘어나기 때문이다. 요금은 다음과 같다. 부가세를 포함한 금액이며, 유료 플랜은 최소 3채널부터 시작하도록 설계했다. | 요금제 | 채널당 월 결제 | 채널당 연 결제 | 3채널 월 결제 | | ---- | -------: | -------: | -------: | | Pro | 5,900원 | 59,000원 | 17,700원 | | Team | 9,900원 | 99,000원 | 29,700원 | 연간 요금은 월 결제 10개월분이고, 체험은 14일이다. Team에는 구성원 관리와 게시 승인처럼 함께 운영할 때 필요한 기능을 넣어 가격 차이를 설명했다. 지금 가격은 10월 7일부터 적용한 세 번째 가격표다. 채널당 월 요금을 Pro는 4,900원에서 5,900원으로, Team은 7,900원에서 9,900원으로 올렸다. Free는 성과를 최근 7일까지만 보게 줄였고, 신청과 링크 DM의 월 한도도 각각 300건과 100건에서 50건으로 낮췄다. 소수의 사용이 원가를 크게 늘리지 않도록 저장 용량과 영상 크기, 댓글 수집 주기에도 요금제별 상한을 새로 두었다. 최소 3채널 조건 역시 검증할 가정이다. 여러 채널을 관리할수록 가치가 커지겠지만, 1\~2채널만 쓰는 고객에게는 시작을 막는 조건일 수 있다. 실제 연결한 채널 수와 반복 사용, 요금제 관심, 이탈 이유를 함께 보면서 판단해야 한다. ### 결제를 열기 전의 요금제 신청 가격을 정했다고 바로 받을 수 있는 건 아니었다. 결제 기능은 다 만들어 두었지만, 카드사 심사가 끝날 때까지 실제 결제는 닫아 두었다. 그렇다고 유료 요금제를 원하는 고객을 그냥 돌려보내고 싶지는 않았다. 그래서 결제를 열지 말지를 서버 환경 변수 하나로 정했다. `BILLING_CHECKOUT_ENABLED`가 `false`이면 요금제 변경 창은 결제 대신 요금제 신청을 받는다. 결제를 바로 시작할 수 있는 상태라면 신청은 받지 않는다. 같은 고객 앞에 결제와 신청이라는 두 길이 겹치지 않게 하려는 장치다. ```ts // 설명을 위해 줄인 코드 // billing.fields.ts BILLING_CHECKOUT_ENABLED: z.stringbool().default(false), // request-workspace-plan.use-case.ts const checkout = await checkoutAvailability.forWorkspace({ workspaceId }); if (checkout.status === "available") { return { status: "plan_request_not_needed" }; } return this.#submit(input, parsedInput, plan, now); ``` 신청이 들어오면 운영 메일로 알림이 온다. 운영자는 운영 화면에서 신청을 승인하거나 거절한다. 승인하면 결제 없이 정한 날짜까지 해당 요금제의 유료 한도를 열어 준다. 랜딩 페이지 요금제 카드 아래의 "결제는 곧 열려요. 가입한 뒤 워크스페이스에서 신청하면 확인하고 열어 드려요."라는 안내가 이 상태에서 보이는 문구다. 이 화면은 뒤에서 가입 CTA를 이야기할 때 함께 본다. 웹은 서버가 내려준 요금제 목록의 결제 가능 여부만 보고 화면을 고른다. 심사가 끝나면 웹을 다시 배포하지 않고 이 값 하나만 바꿔 결제를 연다. GA에서도 결제 시작 `checkout_started`와 요금제 신청 `plan_request_submitted`를 다른 이벤트로 센다. ### 매출과 공헌이익 가격을 정하면서는 고객이 늘어날수록 운영 비용을 감당할 수 있는지도 따져 봤다. 매출은 MRR(Monthly Recurring Revenue, 월 반복 매출)과 ARPA(계정당 평균 매출)로 살펴본다. 연간 구독료는 12개월로 나누어 MRR에 반영한다. 한 번에 들어온 결제 금액과 매달 반복되는 매출을 구분하기 위해서다. 매출에서 결제 수수료, AI 호출, 저장과 전송 같은 변동비를 빼면 공헌이익이 남는다. 이 금액으로 서버 기본 요금 같은 고정비를 충당하고, 서비스를 유지하고 개선할 여유를 확보해야 한다. 아래 숫자는 계산 방식을 보여 주기 위한 **가정**이며, 모여의 실제 매출이나 원가가 아니다. 부가세를 제외하고 고객당 월 매출이 2만 원, 변동비가 4천 원이라고 하면 공헌이익은 1만 6천 원이다. 월 고정비가 20만 원이라면 고객 13곳의 공헌이익으로 이를 충당한다. 물론 고객이 늘면 필요한 서버 사양과 지원 업무도 달라진다. 무료 크레딧이 끝난 뒤의 비용, 고객 응대와 유지보수에 드는 시간도 함께 살펴야 한다. 가격을 한 번 정하는 것으로 끝내지 않고, 실제 사용량과 운영 부담을 보며 조정하려 한다. CAC는 고객 한 곳을 획득하는 데 드는 비용이고, LTV는 고객 관계가 이어지는 동안 얻을 가치를 추정한 값이다. 아직 결제와 유지 기간의 표본이 충분하지 않은 모여에서 LTV/CAC 비율을 성과처럼 제시하기는 이르다. 먼저 어떤 경로로 들어온 고객이 작업을 마치고, 결제하고, 다음 달에도 남는지 기록해야 한다. ### 이미지 보관 비용 가격은 저장 정책에도 영향을 줬다. SNS 게시에 사용한 고해상도 원본을 계속 보관하면 사용량과 비용이 쌓인다. 그렇다고 날짜가 지났다는 이유만으로 예약 게시에 필요한 파일을 지우면 사용자가 맡긴 일을 끝내지 못한다. 모여는 Cloudflare R2에 미디어를 저장한다. **게시가 끝났고 더 이상 사용 중인 곳이 없는 원본**에는 요금제별 보관 기간을 적용한다. Free는 30일, Pro는 90일, Team은 180일이다. 원본 보관이 끝나더라도 게시 이력에 필요한 미리보기는 별도로 다룬다. 초안과 예약, 재시도 중인 게시물의 이미지와 소개 페이지, 프로필에서 쓰는 이미지는 지우지 않는다. 사용처가 없는 파일은 별도 유예 기간 뒤 정리하며, 삭제 직전에도 사용 여부와 요금제를 다시 확인한다. 외부 API가 게시할 미디어를 읽을 수 있어야 한다는 요구와 모여가 원본을 얼마나 보관할지는 다른 문제다. 전자는 게시를 완료하기 위한 조건이고, 후자는 사용자의 재사용 편의와 저장 비용 사이에서 정한 제품 정책이다. 요금제를 고를 때 보관 기간이 보여야 하고, 오래 남겨야 하는 원본은 따로 보관하도록 안내해야 한다. *** ## 지표를 보는 기준 가격과 제공 범위를 정했다고 끝나지 않는다. 실제로 어떻게 쓰는지 보고 그 판단을 고쳐야 했다. 앞서 본 SNS 성과는 고객이 자기 홍보를 고칠 때 보는 숫자다. 여기서 다룰 GA와 운영 지표는 내가 모여를 고치려고 모으는 숫자다. GA에서는 화면과 시도한 행동을 보고, 서버에서는 실제 업무가 완료됐는지 확인한다. 예약 버튼을 누른 것과 SNS에 게시된 것은 서로 다른 사건이다. 둘을 연결해서 봐야 버튼을 찾지 못한 문제와 게시 처리에 실패한 문제가 구분된다. ### GA에서 보는 행동 어느 유입 경로에서 가입에 관심을 갖는지, 채널 연결을 시작한 사람이 완료했는지, 작성한 게시물을 실제로 올렸는지 알고 싶었다. 그 질문에 맞춰 가입, 연결 시작, 작성 화면 진입, 예약 요청, 요금제 관심을 나누어 수집했다. 이벤트 이름도 `channel_connect_started`, `composer_opened`, `post_schedule_submitted`처럼 관측한 행동이 드러나게 붙였다. 이메일이나 게시물 본문은 분석 도구에 보낼 필요가 없다. 유입과 행동을 이해하는 데 필요한 값만 남겼다. 아래는 이 이벤트들을 모아 둔 GA 보고서다. 운영·테스트 트래픽이 섞여 있을 수 있어 고객의 행동과 구분해서 읽는다. (이미지: GA 제품 행동 보고서. 9월 13일부터 10월 10일까지 이벤트별 사용자 수와 횟수를 본다. 수치는 가렸다.) 한 사람이 채널 연결을 여러 번 시도할 수 있으므로 사용자 수와 이벤트 횟수는 구분해서 본다. 연결을 시작한 사용자 수와 서버의 연결 완료 기록을 함께 봐야 어디에서 막혔는지 보인다. GA에 이벤트가 비어 있으면 아무도 쓰지 않았다고 보기 전에 수집 누락과 필터, 대상 경로부터 점검한다. ### 가입 CTA와 유입경로 설계 제품 안의 행동보다 앞에 있는 것이 가입이다. 모여 랜딩 페이지에는 가입 버튼이 네 곳에 있다. 상단 헤더와 첫 화면, 요금제 카드, 페이지 마지막이다. 어느 버튼이 실제로 가입을 이끄는지 알아야 버튼의 위치와 문구를 고칠 근거가 생긴다. (이미지: 로그인하지 않은 상태의 랜딩. 헤더·첫 화면·요금제 카드·마지막 영역의 가입 버튼을 표시했다. 요금제 카드 아래에 결제 안내 문구가 보인다.) 그래서 가입 버튼 클릭은 `signup_cta_clicked` 하나로 보내고, 버튼 위치를 `placement`에 `header`, `hero`, `pricing`, `closing` 중 하나로 담았다. 같은 버튼이 로그인한 사람에게는 워크스페이스로 가는 길이 된다. 이 이동까지 세면 가입 관심이 부풀려지므로 로그인하지 않은 방문자의 클릭만 보낸다. ```tsx // landing-start-button.tsx, 설명을 위해 줄인 코드 onClick={() => { // 로그인한 사람의 워크스페이스 이동은 가입 의도로 세지 않는다. if (!isAuthenticated) { analytics.track({ name: "signup_cta_clicked", placement }); } }} ``` GA4에서 주요 이벤트로 표시한 것은 `sign_up` 하나다. 이 이벤트는 이메일 가입이 끝났을 때만 보내고, 소셜 로그인 가입까지 포함한 전체 가입 수는 DB에서 센다. 속성을 만들 때 GA가 켜 둔 `close_convert_lead`와 `qualify_lead`는 모여가 보내지 않는 이벤트라 껐다. `checkout_started`나 `post_schedule_submitted`도 서버가 응답하기 전의 시도라 전환으로 등록하지 않았다. 숫자를 읽기 전에 섞이면 안 되는 트래픽도 걸렀다. 운영자 계정으로 로그인하면 코드가 `traffic_type=internal`을 함께 보내고, GA4 데이터 필터 `Internal Traffic`이 이 방문을 뺀다. 필터는 10월 14일부터 사용 중이며 지난 데이터에는 소급되지 않는다. 로그인과 결제에서 돌아오는 도메인은 원치 않는 추천 목록에 넣었다. `accounts.google.com`, `kauth.kakao.com`, `tosspayments.com`, `toss.im`이다. 로그인이나 결제를 마치고 돌아온 방문이 새 유입처럼 잡히지 않게 하려는 설정이다. Instagram과 Threads도 OAuth를 거치지만 소개 페이지로 들어오는 실제 유입처라 목록에 넣지 않았다. 마지막으로 탐색 분석에 `가입 CTA→첫 공개` 유입경로를 만들었다. 단계는 `signup_cta_clicked` → `bio_page_created` → `bio_page_published`다. 가입 버튼을 누른 사람이 소개 페이지를 만들고 처음 공개하기까지를 본다. GA 유입경로는 사용자별 첫 도달을 세므로 따로 조건을 걸지 않아도 마지막 단계가 첫 공개가 된다. `sign_up`은 단계에 넣지 않았다. 이메일 가입에서만 보내므로, 넣으면 소셜 로그인으로 가입한 사람이 모두 가입 단계에서 이탈한 것처럼 보인다. (이미지: GA4 탐색 분석의 가입 CTA→첫 공개 유입경로. 9월 16일부터 10월 13일까지 세 단계를 기기별로 나눠 본다. 수치는 가렸다.) 기기별로 나누면 모바일과 데스크톱 중 어느 쪽에서 어느 단계에 멈추는지 비교된다. 다만 출시 직후라 표본이 아직 작다. 지금은 비율을 결론으로 읽기보다 끊기는 단계를 찾는 데 쓰고, 실제 가입과 공개 수는 서버 기록과 맞춰 본다. ### KPI의 분모와 관측 기간 제품과 사업의 KPI는 실제 가입·게시·청구 기록에서 계산하도록 했다. 고객 지표를 계산할 때는 운영자와 테스터가 소유한 워크스페이스를 제외한다. 유료 전환은 운영 환경에서 0원보다 큰 금액을 실제로 결제했을 때로 정했다. 쿠폰으로 유료 기능을 사용한 것과 돈을 낸 고객을 구분하기 위해서다. | 알고 싶은 것 | 보는 기준 | 결과를 보고 할 일 | | ----------------- | -------------------------------------- | -------------------- | | 첫 가치를 경험하는가 | 가입 후 7일 내 채널 연결과 첫 게시를 마친 고객 워크스페이스 비율 | 연결·첫 게시에서 막힌 과정 확인 | | 실제 결제로 이어지는가 | 가입 후 90일이 지난 고객 중 그 기간 안에 처음 실제 결제한 비율 | 가격·무료 범위·유료 가치 설명 점검 | | 유료 고객이 남는가 | 월초 유료 구독 중 그달 실제 해지된 비율 | 이탈 이유와 사용 패턴 확인 | | AI를 감당할 원가로 제공하는가 | 실패를 포함한 추정 원가 합계 ÷ 성공 호출 수 | 재시도·한도·모델 선택 점검 | 가입한 지 하루 된 사람을 90일 전환율의 미전환 고객으로 계산하면 안 된다. 가입 시기가 비슷한 집단인 코호트를 나누고, 각 집단을 얼마나 오래 관찰했는지도 함께 본다. 초기 활성화·전환 목표는 점검을 위한 가정으로 둔다. 운영 화면에는 수치뿐 아니라 처리할 일도 모았다. 아래 화면에서는 신규 사용자와 채널 연결, 첫 게시를 살펴보면서 결제 문제와 요금제 신청, 게시 장애 같은 대기열로 바로 이동한다. (이미지: 운영 현황. 처리할 대기열과 사용자, 워크스페이스의 첫 연결·첫 게시를 한 화면에서 본다. 수치는 가렸다.) 현재 상태를 세는 카드와 선택한 기간의 사건을 세는 카드는 기준이 다르다. 전체 워크스페이스 수와 기간 내 첫 연결·첫 게시 수를 그대로 나누어 전환율을 계산하지는 않는다. 단계별 이탈을 나타내는 퍼널로 읽으려면 비교할 대상과 관찰 기간부터 맞춰야 한다. 첫 작업을 마친 뒤에는 다음 주에도 게시하는지, 소개 페이지의 문의를 처리하는지 살펴보려 한다. 앞서 사용자에게 물었던 반복 사용의 이유를 실제 기록과 함께 확인하기 위해서다. *** ## 사용자가 계정을 지킬 수 있도록 유료 기능을 만들면서 계정 공유와 체험 반복도 생각해야 했다. 서버에서 세션을 관리하고 활성 세션을 최대 5개로 제한했다. 한도를 넘으면 가장 오래 사용하지 않은 세션을 정리한다. 사용자는 보안 설정에서 로그인한 기기를 확인하고 개별 세션이나 다른 기기의 세션을 종료할 수 있다. 사용자에게는 자신의 계정에서 무슨 일이 일어났는지 알 방법도 필요했다. 모르는 기기에서 로그인했다면 바로 알아차려야 대응도 빨라진다. 그래서 새 기기 로그인을 감지하면 브라우저와 운영체제, 로그인 시각을 메일로 안내한다. 본인이 로그인하지 않았다면 보안 설정에서 다른 기기를 모두 로그아웃하고 비밀번호를 바꾸도록 했다. 아래는 실제로 받은 안내다. (이미지: 새 기기 로그인 안내. 로그인한 기기와 시각을 알리고, 보안 설정에서 다른 기기를 로그아웃하도록 연결한다.) 모든 로그인에 같은 메일을 보내지는 않는다. 기존 사용자가 새 기기로 로그인한 것을 감지했을 때 보내고, 새 계정의 첫 로그인은 제외한다. 같은 기기에서 로그인을 다시 시도해도 안내가 중복되지 않게 했다. 메일마다 비용이 조금씩 들어도 사용자가 직접 대응할 수단은 주고 싶었다. ### 체험과 쿠폰 세션 제한과 무료 체험의 기준은 따로 정했다. 워크스페이스를 만들 때마다 무료 혜택이 새로 생기지 않도록 체험은 계정당 한 번으로 두고, 미결제 상태의 무료 AI 사용량도 계정 단위로 묶었다. 월 30회와 일 10회 한도를 함께 적용한다. 결제를 열기 전에도 초기 사용자가 필요한 기능을 충분히 써 보게 하고 싶었다. 쿠폰으로 추가 채널이나 Pro·Team 기능을 제공하고, 이용 기간과 발급 조건을 정하게 했다. (이미지: 쿠폰 만들기. 추가 채널이나 Pro·Team 기능 중 제공할 혜택을 고르고 이용 기간을 정한다.) 쿠폰은 이용 권한을 주는 수단이라 모든 쿠폰이 청구 금액을 할인하지는 않는다. 체험과 쿠폰, 실결제를 나누어 두면 쿠폰으로 제공한 혜택과 실제 매출이 섞이지 않는다. 오류로 실패한 작업은 사용량을 돌려줄 기준이 필요했다. 같은 실패를 되풀이하며 외부 호출 비용만 쌓는 경로도 막아야 했다. 정상 사용자의 불편과 비용 악용을 함께 따졌다. 인증과 보안의 상세한 고민은 [서비스 보안을 점검한 글](/post/did-i-secure-my-service)에 따로 정리했다. ### 팀의 권한과 운영자의 대응 Team에서는 작성, 승인, 결제 관리 권한을 나눈다. 버튼만 숨기면 요청을 직접 보내는 길이 남는다. 그래서 권한과 요금제, 사용량은 서버가 한곳에서 판정하고, 화면은 그 결과를 안내한다. 운영자에게도 고객에게 설명할 통로가 필요하다. 공지는 약관 변경, 서비스 안내, 광고로 목적을 나누고 대상과 발송 시점을 정한다. 광고 수신 동의처럼 발송 목적에 따라 필요한 조건도 같은 흐름에서 다룬다. (이미지: 공지 작성. 목적과 수신 대상을 정하고, 고객에게 보낼 내용을 미리 확인한다.) 약관 변경 공지는 시행일을 게시일로부터 30일 뒤부터만 잡도록 막아 두었다. 그래서 출시 직전에 고친 10월 13일 판 정책 문서는 약관 변경이 아니라 서비스 안내 공지로 회원에게 보내고, 서비스 화면에 배너를 함께 띄웠다. 사용을 멈추는 순간의 의견도 들을 수 있도록 계정 삭제와 구독 해지에 이탈 설문을 두었다. 어떤 이유로 떠났는지 확인하면 다음 인터뷰에서 물어볼 내용도 구체적으로 정할 수 있다. (이미지: 이탈 설문. 계정 삭제와 구독 해지 이유를 모아 보고, 남겨 준 의견을 확인한다.) 응답이 쌓이면 사용 기록과 함께 읽으며 어떤 불편을 먼저 해결할지 정할 생각이다. *** ## 메일 발송에 SES를 선택한 이유 이런 기능을 정하다 보니 메일은 회원가입 때 한 번 보내고 끝나는 수단이 아니었다. 이메일 인증과 비밀번호 재설정, 새 기기 로그인, 결제 결과, 채널 연결 해제처럼 서비스 이용 중 알려야 할 일이 계속 생긴다. 어떤 메일을 보낼지 먼저 정한 뒤 발송 도구를 비교했다. Resend는 처음 연동하기 편하다. SDK와 React Email 연동, 발송 로그와 웹훅, 반송 처리 같은 기능을 함께 제공한다. 직접 구현하고 운영할 일을 줄여 주므로 충분히 비용을 지불할 만하다. 다만 모여에는 이미 AWS에서 돌아가는 서버와 백그라운드 작업이 있었다. 필요한 메일을 직접 구성하고 발송 결과를 관리할 기반도 있었으므로, 사용량에 따라 비용을 내는 Amazon SES를 함께 검토했다. ### 무료 한도와 발송량 Resend의 무료 플랜은 월 3,000통, 하루 100통이다. Pro는 월 20달러에 50,000통을 제공하며 일일 발송 통수 제한이 없다. SES의 기본 종량제 발송료는 1,000통당 0.10달러다. [Resend 요금표](https://resend.com/pricing)와 [SES 요금표](https://aws.amazon.com/ses/pricing/)를 기준으로 단순 비교하면 다음과 같다. | 월 발송량 | Resend | SES 기본 발송료 | | ------- | ------: | ---------: | | 3,000통 | 무료 | $0.30 | | 10,000통 | Pro $20 | $1 | | 50,000통 | Pro $20 | $5 | Resend 무료는 하루 100통 이내로 보낼 때의 비교다. SES 금액은 무료 크레딧을 제외한 기본 발송료이며, 데이터·추가 기능·연계 서비스 요금과 세금은 별도다. SES에도 계정과 리전별 발송 할당량이 있으므로 무제한으로 보낼 수 있다는 뜻은 아니다. 무료 범위에 머무르면 Resend의 발송료가 더 낮다. 그래서 사용자 수만으로 비용을 비교하기보다 **한 사람이 몇 통을 받는지와 메일이 어느 날 몰리는지**를 봤다. 가입과 인증 재요청, 기기 변경, 결제 안내가 겹치면 월간 합계에는 여유가 있어도 하루 한도에는 먼저 닿을 수 있다. 필요한 보안 안내가 무료 한도 때문에 빠져서는 안 된다고 봤다. 제공할 알림을 먼저 정하고, 그 발송량을 감당할 비용과 운영 방식을 골랐다. ### 낮은 발송료 뒤에 남는 일 SES가 메일을 받아 갔다고 사용자의 받은편지함에 도착한 것은 아니다. 주소가 잘못됐거나 수신자가 신고했다면 그 결과를 받아 다음 발송에 반영해야 한다. 발송 요청을 재시도할 때 같은 메일이 여러 통 가지 않도록 기록도 남겨야 한다. 모여에서는 발송 작업과 상태를 저장하고 백그라운드에서 처리한다. SES의 반송·불만 이벤트는 SNS와 SQS를 거쳐 서버로 받아 기록한다. 이때 SNS는 소셜 채널이 아니라 AWS의 알림 서비스다. 피드백 처리가 밀리거나 반복해서 실패하는 경우도 별도 경보로 확인하도록 했다. 보낼 수 있다고 많이 보낼 일은 아니다. 일반 알림은 묶어서 보내고 수신자당 하루 20통을 상한으로 둔다. 새 기기 로그인 같은 계정 보안 메일은 이 상한에 걸리지 않는다. 꼭 필요한 안내가 다른 알림에 밀려나지 않게 둘을 나눴다. 따라서 50,000통에 5달러라는 값은 발송료 비교일 뿐이다. 반송 처리와 장애 대응, 유지보수에 드는 내 시간까지 포함하면 운영 비용은 더 커진다. 이 부분을 직접 맡을 수 있는지까지 확인한 뒤 SES를 선택했다. ### 직접 만들 범위 정하기 예전에는 익숙한 도구를 쓰거나 개발 시간을 아끼기 위해 구독료를 지불하는 경우가 많았다. 혼자 모여를 만들면서는 그 선택을 한 번 더 따져 보게 됐다. 제공하는 기능 중 실제로 쓸 것은 무엇이고, 필요한 부분만 구현한다면 얼마나 들까. AI의 도움으로 구현과 검토에 드는 부담이 줄면서 이런 비교에 시간을 더 쓸 수 있었다. 메일 도구 전체를 다시 만드는 대신, 모여에 필요한 템플릿과 발송 기록, 실패 처리에 범위를 맞췄다. 직접 맡을 부분을 정하고 나니 고객에게 필요한 알림을 제공하면서도 고정비를 줄일 선택지가 생겼다. 직접 만든 코드는 이후에도 관리해야 한다. 그 부담이 외부 도구의 요금보다 커지면 다시 고른다. 익숙한 도구라도 이번 제품에 필요한 기능과 운영 비용을 다시 비교해 보려 했다. *** ## 운영 상황을 알아채는 방법 고객에게 안내를 보내는 것과 별개로, 운영자인 나도 서비스에서 일어난 일을 알아야 한다. 누군가 가입했는지, 청구가 완료됐는지, 예약한 게시물이 실패했는지를 대시보드에서 계속 지켜볼 수는 없다. 알림은 그때 필요한 기록을 찾아보게 하는 출발점으로 삼았다. ### 가입과 자동 청구 알림 신규 가입과 자동 청구 완료는 Discord 웹훅으로 받는다. [웹훅](https://docs.discord.com/developers/resources/webhook)은 서버에서 지정한 채널로 메시지를 보내는 방식이다. 이런 업무 알림을 받기 위해 별도의 봇이나 유료 협업 도구를 추가할 필요는 없었다. (이미지: Discord로 받는 신규 가입 알림. 운영·개발 채널을 나누고 가입 방식과 기기 정보를 남긴다. 이름과 이메일, 계정·요청 식별자와 배포 해시는 가렸다.) 운영과 개발 채널은 나눠 두었다. 테스트 중 만든 계정을 실제 가입으로 착각하지 않기 위해서다. 알림에는 가입 방식과 요청 정보로 추정한 브라우저·운영체제, 관련 기록을 찾을 요청 식별자를 담았다. 이름과 이메일은 일부를 가려 보낸다. 가입 이후 실제로 채널을 연결하고 게시했는지는 앞서 본 운영 화면에서 확인한다. Slack도 익숙한 선택지였지만, 혼자 운영 알림을 받는 용도에 유료 협업 기능까지 필요하지는 않았다. Slack의 [무료 플랜](https://slack.com/intl/ko-kr/help/articles/115002422943-Usage-limits-for-free-workspaces)은 최근 90일의 메시지를 조회할 수 있고 1년을 넘긴 데이터는 삭제된다. 모여에서는 기존 Discord 채널을 활용하는 쪽을 택했다. 과거 알림을 찾아보기 위해 별도 구독을 추가하지 않아도 된다는 점이 내게는 유용했다. 다만 결제 기록이나 장애 조사 자료를 Discord에만 맡기지는 않는다. 업무 기록은 서버에 남기고 채팅에는 발생 사실과 찾아볼 단서를 보낸다. 답장이 필요한 고객 문의와 요금제 신청, 실행 중 감지한 장애는 운영 메일로 받는다. 알림을 여러 곳에 똑같이 뿌리기보다 **받은 뒤 해야 할 일**에 맞춰 통로를 나눴다. ### 요청과 작업을 이어서 보기 가입 알림과 달리 게시 실패는 어디까지 처리됐는지 따라가야 원인이 보인다. 모여의 웹은 Cloudflare Workers에서 제공하고, API와 예약 게시를 처리하는 백그라운드 작업은 AWS에서 실행한다. 데이터는 RDS에, 이미지 원본과 미리보기는 Cloudflare R2에 보관한다. 서버로 들어오는 연결은 Cloudflare Tunnel을 거친다. Cloudflare에서는 웹 요청을, 서버 로그에서는 업무 처리 경로를 살핀다. Sentry는 예상 밖 오류를 모아 보고, CloudWatch는 자원 상태와 작업 지연을 감시하는 데 쓴다. 알림을 확인한 뒤 이 기록들에서 영향을 받은 작업과 원인을 좁혀 간다. 서버 로그에는 어떤 작업에서 무슨 일이 생겼는지와 원인 코드, 요청·백그라운드 작업을 연결할 식별자, 배포 버전을 남긴다. 게시 실패가 발생하면 같은 요청이 작업 처리 과정에서 어디까지 진행됐는지 따라갈 수 있어야 한다. 토큰과 쿠키, 개인정보, 외부 API 원문을 그대로 보관하지 않는 것도 기준으로 두었다. (이미지: Cloudflare 운영 Worker의 요청 로그. 요청 시각과 처리 결과를 살펴보고 서버의 작업 기록과 함께 원인을 좁힌다.) 권한과 쿠폰처럼 누가 무엇을 바꿨는지 남겨야 하는 일은 감사 기록으로 구분했다. 결제나 권한 변경은 성공했는데 기록만 빠지지 않도록 업무 변경과 함께 저장한다. 반대로 운영 로그 전송에 실패했다고 성공한 결제를 다시 실행해서도 안 된다. Sentry는 오류 수집에 집중하도록 설정하고, 트레이스 샘플링과 브라우저 세션 녹화는 사용하지 않도록 했다. URL 쿼리와 사용자 정보 등을 제거하고, 사용량 한도 초과처럼 예상한 업무 거절은 장애와 나눈다. 같은 문제를 여러 계층에서 중복 보고하면 알림을 읽고 원인을 찾는 시간이 늘어난다. ### 경보와 첫 대응 혼자 운영할 때는 모든 순간을 지켜볼 수 없다. 그렇다고 모든 실패가 즉시 개입할 일은 아니다. 잠깐의 자원 사용 증가와 고객의 예약 시간이 계속 밀리는 상황을 구분해야 한다. | 경보 | 설정 기준 | 먼저 확인할 것 | | ------------- | ---------------------------------- | ---------------------------- | | API·Worker 오류 | 각각 5분 동안 5건 이상 | 오류 종류와 배포 버전, 관련 요청·작업 | | 호스트 메모리 | 85% 초과가 5분 구간 3회 | 컨테이너 사용량과 지속 여부 | | 작업 지연 | 가장 오래된 처리 대상의 지연이 60초 초과, 1분 구간 5회 | Worker와 외부 API 상태, 영향을 받은 예약 | | RDS 가용 메모리 | 30분 내내 150MiB 미만 | 연결 수와 정렬·임시 테이블, 인스턴스 증설 여부 | | RDS Swap | 30분 내내 64MiB 초과 | 메모리 부족 전조인지, 인스턴스 증설 여부 | | DB 연결 수 | 10분 동안 50개 초과 | 애플리케이션별 연결 수와 누수·폭주 여부 | | 비용 | 월 110달러 예산의 실제 사용액 80%·예측액 100% | 비용이 늘어난 서비스와 사용량 | 작업이 많아도 제시간에 처리하고 있다면 당장 장애는 아니다. 반면 예약 시각을 지난 작업이 쌓이면 고객과의 약속을 이미 어기고 있다. 그래서 자원 비율과 함께 업무 지연을 본다. 표에 넣지 않은 경보도 있다. 디스크 사용률과 RDS CPU는 80% 초과가 5분 구간 3회 이어지면 울린다. SES는 반송 5%와 불만 0.1%를 기준으로 발송 대상을 확인하고, 비용에는 서비스별 하루 5달러 이상의 이상 탐지를 둔다. 표의 RDS 메모리 경보 두 줄은 9월 30일 장애 뒤에 더했다. 그날 아침 db.t4g.micro 인스턴스가 메모리 부족으로 재시작됐고, 백그라운드 작업이 DB에 다시 연결하지 못해 수동으로 재시작할 때까지 약 5시간 멈춰 있었다. 장애 전 며칠 동안 Swap이 43MB에서 113MB로 먼저 늘었기 때문에, 가용 메모리보다 앞서 알려 줄 Swap 경보를 함께 걸었다. 인스턴스는 db.t4g.small로 올리고 DB 연결에 10초 간격의 keepalive를 넣었다. 인스턴스를 올리면서 월 예산도 80달러에서 110달러로 올렸다. 실제 비용은 월 82달러 안팎이라, 실제 사용액 80%인 88달러에 닿으면 평소보다 6달러쯤 더 쓰고 있다는 신호가 된다. 평소 지출에는 울리지 않고 이상 지출에만 울리도록 잡은 값이다. 물론 예산 알림이 지출을 자동으로 막아 주지는 않는다. 실행 중 감지한 장애는 처음에 바로 운영 메일로 알린다. 같은 문제가 계속되면 최초 감지로부터 10분, 1시간, 6시간, 24시간이 지난 시점에 다시 알리고, 이후에는 24시간 간격과 시간당 발송 상한을 적용한다. 각 시점이 지난 뒤 수집기가 해당 문제를 다시 감지해야 보낸다. 시간만 지났다고 무조건 발송하지는 않는다. 긴급 경보와 별개로 매일 아침 Sentry와 Cloudflare 관련 알림, 운영 메일을 확인하는 흐름도 두었다. 이때 공급자가 보내는 정기 보고서와 발생 시점의 장애 알림을 함께 살핀다. 실제로 겪은 [DB 연결 풀 고갈](/post/moyeo-connection-pool-exhaustion) 같은 사건은 수집과 대응의 빈틈을 돌아볼 계기가 됐다. *** ## 반복되는 운영 업무 알림을 받는 통로를 정한 다음에는 받은 일을 놓치지 않고 처리할 방법이 필요했다. Google Workspace에 `support@moyeo.io` 같은 업무용 주소를 마련하고, 고객 문의와 운영 알림, 비용 자료가 서로 묻히지 않게 정리했다. 혼자 쓰더라도 나중에 다른 사람이 업무를 이어받을 수 있는 형태로 두고 싶었다. ### 메일 분류와 아침 점검 Gmail 라벨은 고객 문의·지원, 시스템 장애·운영·보안, 재무 영수증으로 나눴다. 같은 AWS 메일도 비용 안내와 장애 경보는 처리할 일이 다르다. 발신 서비스의 이름보다 메일을 읽고 해야 하는 일을 분류 기준으로 삼았다. (이미지: Gmail의 업무별 분류. 고객·재무·개발·장애와 보안을 나누고, 메일 내용과 발신자는 가렸다.) 필터로 라벨을 붙이고 받은편지함 옆에 업무별 목록을 배치했다. 바로 답할 문의는 처리하고, 후속 작업이 필요하면 할 일과 다시 확인할 시점을 남긴다. 분류 기준을 정한 뒤에는 Claude 자동화를 매일 아침 실행하도록 했다. 새 메일과 운영 알림을 점검하고, 비용 관련 파일은 분류해 Drive에 정리한 뒤 Google Sheets 비용 대장에 기록한다. 첨부 파일을 내려받고 폴더를 찾고 시트로 옮기는 반복을 줄이기 위한 흐름이다. ### 비용 기록과 증빙 자동화 결과는 요약문으로만 남기지 않는다. 비용 기록에는 근거 자료의 링크를 남기고, 공식 증빙이 부족하거나 대조가 필요한 항목은 확인할 일로 표시한다. 결제 알림 한 통을 저장했다고 모든 검토가 끝난 것은 아니다. Drive에는 재무 자료 아래에 구독·계정 관리와 세무·비용 증빙을 나누고, 증빙은 `2026년 2기 (7~12월)`처럼 귀속 기간별로 모았다. 그 안에서 구매증빙, 카드·은행 자료, 홈택스 자료를 구분한다. 신고 준비나 자료 전달이 필요할 때 메일함부터 다시 뒤지지 않기 위해서다. (이미지: 비용 대장. 거래별 증빙 종류·확보 상태·공제 검토 상태를 함께 관리한다. 거래일·금액·결제수단·내부 링크는 가렸다.) 비용 대장에는 거래일과 업체, 통화와 금액, 증빙 링크를 함께 둔다. 원화 확인액과 외화 결제액을 구분하고 취소·환불도 대조한다. 같은 거래의 결제 알림과 청구서가 각각 도착해도 두 번 집계하지 않도록 중복 여부를 확인한다. 증빙 확보와 공제 검토도 다른 상태로 관리한다. 공식 영수증이 있는지, 필요한 정보가 빠졌는지, 카드 청구액과 맞는지 확인할 일이 남을 수 있기 때문이다. 기관별 체크에는 저장할 위치와 다음에 확인할 일을 적고, 요약 탭에서는 보완할 항목을 모은다. (이미지: 기관별 증빙 체크. 저장할 폴더와 다음 확인 사항을 정하고, 월말에 대조할 순서를 남겼다.) 요약 탭에서는 빠진 증빙과 검토할 항목을 한눈에 본다. 비용을 기록한 뒤 신고 준비를 마치려면 무엇이 남았는지 확인하는 곳이다. (이미지: 홈택스 신고 준비를 위한 내부 요약 시트. 빠진 증빙과 공제 검토가 필요한 항목을 모아 본다.) 아침의 자료 정리와 월말의 비용 대조, 세금 신고 주기는 구분한다. 일반적인 개인 일반사업자의 부가세 확정 신고는 6개월 과세기간을 기준으로 연 2회이며 중간의 예정고지·신고는 별도다. [국세청 안내](https://b.nts.go.kr/nts/cm/cntnts/cntntsView.do?cntntsId=7694\&mi=2273)를 기준으로 자료를 준비하고, 공식 증빙과 홈택스 조회 자료를 대조해 최종 검토한다. 자동화에 맡긴 것은 자료를 모으고 옮기며 빠진 항목을 찾는 일이다. 검토가 필요한 상태를 그대로 남겨 두면, 아침에는 모든 메일을 처음부터 읽는 대신 그날 판단해야 할 항목에 집중하면 된다. (이미지: 사용자 이야기와 운영 기록, 비용 자료를 함께 읽고 다음 개선을 정한다.) *** ## 마치며 초기 스타트업에서 일하며 개발 외의 의사결정을 가까이에서 본 경험이 도움이 됐다. 제한된 시간에 무엇부터 할지, 고객의 요청을 어디까지 받아들일지, 비용을 어떻게 볼지에 관한 고민이었다. 직접 운영을 맡으니 당시 들었던 이야기를 내 서비스의 기준으로 옮겨 보게 됐다. AI와 함께 만들면서 이런 판단에 쓰는 시간이 가장 크게 늘었다. 구현에 드는 부담이 줄어든 만큼 사용자의 이야기를 듣고 지표와 운영 방식을 비교하는 데 시간을 썼다. 기능을 완성한 뒤에도 사람들이 실제로 쓰는지, 계속 제공할 비용을 감당할 수 있는지 살펴보려 했다. 제품을 만들 때도 AI가 앞으로 더 잘할 일을 고려하려 한다. 모여에서는 콘텐츠와 일정, 댓글, 성과를 함께 보며 지난 작업을 이해하도록 구성했다. 이 맥락이 한곳에 있으면 앞으로 AI나 Computer Use로 업무를 도울 때도 여러 화면에서 정보를 다시 모으는 수고가 줄어든다고 본다. 실제 업무에서 도움이 되는지는 더 확인해야 한다. 서비스를 잘 만들어도 알리는 일은 여전히 어렵다. 특히 혼자 일하거나 작은 팀에서 여러 업무를 맡는 사람에게는 홍보를 꾸준히 이어 가는 일이 부담이 된다. 모여로 돕고 싶은 것도 그 과정이다. 내가 생각하는 Product Builder는 고객의 문제를 듣고 해결책을 만든 뒤, 운영 결과를 보고 다음 결정을 내리는 사람이다. 기술적으로 깊이 파고들어야 할 때도 있고 만들 수 있어도 미뤄야 할 기능도 있다. 모여를 혼자 만들며 각 영역에서 어떤 선택을 할지 판단하는 경험을 쌓고 있다. 출시는 했지만 결제를 연 뒤에도 지금 정한 가격과 무료 범위가 실제 업무에 맞을지는 아직 모른다. 그래서 요즘은 첫 게시 뒤 다시 돌아오는 이유를 듣는 데 가장 많은 시간을 쓴다. --- # 모여를 만들며 정한 프론트엔드의 기준 > 모여의 게시물 화면을 따라 React 컴포넌트 이름과 Props, 튜플 상태 훅, TanStack Router·Query 조회, oRPC 계약, 대용량 업로드와 여러 탭 동기화에서 정한 기준을 정리했다. - 원문: https://www.yolog.co.kr/post/moyeo-frontend-architecture - 카테고리: 개발 - 발행: 2026-10-07 - 수정: 2026-10-14 (이미지: 개발자와 AI가 벽에 붙여 둔 기준을 보며 함께 웹 앱을 만드는 모습) [모여](https://moyeo.io)는 여러 SNS의 게시물·댓글·성과를 한곳에서 관리하고, 상품 소개와 예약을 위한 공개 페이지를 만드는 서비스다. AI를 쓰면서 구현에 드는 시간은 줄었다. 대신 작성한 코드가 기존 구조와 맞는지 확인할 일이 늘었다. 비슷한 기능인데 상태를 관리하거나 서버 응답을 다루는 방식이 제각각이면 기능을 고칠 때마다 흐름을 다시 파악해야 한다. 그래서 모여에서는 **AI가 참고할 코드와 사람이 검토할 기준**을 함께 정리했다. 기준을 문서에만 적어 두면 코드를 작성할 때마다 다시 확인해야 한다. 이름에서 역할을 짐작하고 익숙한 사용법을 따르며 수정할 곳을 쉽게 찾도록, 코드에도 같은 기준을 담으려 했다. `AGENTS.md`나 `CLAUDE.md`에는 코드만으로 알기 어려운 지침을 남기고, 반복되는 구현은 기존 코드를 참고하도록 했다. Anthropic은 [코드에서 파악할 수 있는 내용은 문서에서 덜어 내라](https://code.claude.com/docs/en/best-practices#write-an-effective-claudemd)고 권한다. OpenAI도 [GPT-6 Astra 관련 안내](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra)에서 매번 불필요한 문서를 읽게 하는 지침은 컨텍스트를 소모하고 작업을 늦출 수 있다고 설명한다. 모여도 같은 방향으로 문서에는 꼭 필요한 지침만 두고, 구체적인 구현은 코드에서 찾게 했다. 이 글에서는 게시물 화면을 따라가며 그 기준을 설명한다. 컴포넌트의 이름과 사용법에서 시작해 상태 관리, 조회, API 계약으로 이어진다. 반복되는 구현에서 아낀 시간은 대용량 업로드와 편집 중인 글의 보호, 여러 탭의 동기화처럼 실제 사용 중에 생기는 문제를 푸는 데 썼다. *** ## 페이지 코드에서 화면 읽기 ### 페이지에서 화면의 순서를 읽는다 모여에서 임시 저장한 신메뉴 안내를 찾아 수정하려고 한다. 게시물 화면에는 보기 선택, 검색창, 상태 필터, 목록이 필요하다. 그런데 화면을 고치려고 페이지 코드를 열었더니 이렇다면 어떨까? ```tsx title="Before: 이름만으로는 화면 구성을 알 수 없다" function PostsPage() { return ( {/* 제목일까, 프로필일까? Header만으로는 모르겠다. */} {/* 사진? 본문? 목록? 검색창도 이 안에 있나? */} {/* 페이지 번호일까, 작성 버튼일까? Footer만으로는 모르겠다. */} ); } ``` 검색창을 고치려면 먼저 `PostsContents` 파일을 열고 그 안의 구성을 확인해야 한다. 페이지 코드는 짧아졌지만 화면을 이해하는 수고는 그대로다. 이름 하나로 설계의 좋고 나쁨까지 가리긴 어렵다. 그래도 **사용하는 곳에서 역할과 흐름이 읽히는지**는 바로 보인다. 코드를 다른 파일로 옮기면 페이지의 줄 수는 줄어든다. 하지만 내부 구현을 열어 봐야 용도가 보인다면 이해하기 쉬워졌다고 하긴 어렵다. 나누는 데서 그치지 말고 **무엇을 함께 묶어 어떤 이름과 사용법으로 드러낼지**까지 정해야 한다. [Context API에 관한 글](/post/react-hooks-usecontext)에서도 Props Drilling에 앞서 컴포넌트의 위계와 합성을 살펴봤다. 여기서도 길어진 코드를 어디로 옮길지보다 어떤 역할로 나눠야 화면이 쉽게 읽힐지가 먼저였다. 그래서 모여의 게시물 페이지는 사용자가 화면을 읽는 순서대로 구성했다. 제목 아래에서 볼 대상을 고르고, 상태와 검색어로 게시물을 좁힌 뒤 목록을 읽는다. 실제 화면도 이 순서다. (이미지: 모여 게시물 화면의 제목, 보기 선택, 검색 조건과 게시물 목록) 제목 아래 한 줄에 보기 탭과 상태 필터, 검색창이 놓이고 그 아래로 목록이 이어진다. 아래는 이 순서를 그대로 옮긴 코드다. 앞의 코드와 비교하면 어느 쪽이 구성과 흐름을 더 잘 보여 줄까? ```tsx title="After: 제목·검색·목록 순서로 배치한다" {3-4} // QueryBoundary는 Suspense와 오류 경계를 묶은 공통 컴포넌트다. function PostsPage() { const [view, setView] = usePostView(); const [{ query, status }, setFilters] = usePostFilters(); return ( 게시물 setView(postViewSchema.parse(value))} > 채널 게시물 모여 게시물 {match(view) .with(PostView.channelPosts, () => ( } error={ChannelPostList.Error} > )) .with(PostView.posts, () => ( setFilters({ query: event.currentTarget.value }) } /> setFilters({ status })} /> } error={PostList.Error} resetKeys={[query, status]} > )) .exhaustive()} ); } ``` 검색 안내를 추가하려면 `Input` 아래를 보면 된다. 임시 저장한 글만 보여 주려면 `PostList`에 넘기는 조건을 바꾼다. 목록을 불러오는 동안과 조회에 실패했을 때의 화면도 같은 자리에 있다. **목록 내부를 열지 않아도 화면의 배치와 상태가 읽힌다.** `PostStatusInput`처럼 역할을 설명하는 이름이면 내부가 선택 창이어도 무엇을 입력받는지 보인다. 이 페이지에서만 쓰는 컴포넌트라면 페이지 가까이에 둔다. 나눴다는 이유만으로 공용 폴더로 옮기지는 않는다. 탭별 분기는 ts-pattern의 `match`로 표현했다. JSX의 선택지가 나란히 보이고, 새 보기가 생겼을 때 빠뜨린 분기도 드러난다. 차이를 보려고 지금의 두 보기에 '예약 글'을 추가한다고 가정해 보자. `ExpandedPostView`는 이 비교에서만 쓰는 타입이다. ```ts title="Before: default가 빠뜨린 탭까지 처리한다" {10} type ExpandedPostView = "channel_posts" | "posts" | "scheduled"; function getPostViewLabel(view: ExpandedPostView) { switch (view) { case "channel_posts": return "채널 게시물"; case "posts": return "모여 게시물"; default: return "모여 게시물"; // 예약 글도 이 이름으로 표시된다. } } ``` ```ts title="After: exhaustive가 빠뜨린 탭을 타입 오류로 알린다" {9} import { match } from "ts-pattern"; // 같은 ExpandedPostView 타입을 사용한다. function getPostViewLabel(view: ExpandedPostView) { return match(view) .with("channel_posts", () => "채널 게시물") .with("posts", () => "모여 게시물") // 'scheduled' 분기가 빠져 있어 타입 오류가 난다. .exhaustive(); } ``` 여기에 `.with("scheduled", () => "예약 글")`을 추가해야 타입 검사를 통과한다. `switch`에서도 `never` 검사로 누락을 막을 수 있다. 모여에서는 분기마다 문구나 JSX를 반환하는 형태가 읽기 좋아 `match`를 썼다. 단순한 참·거짓 조건에는 `if`를 쓴다. ### 배치를 매번 해석하지 않도록 페이지에서 화면의 순서가 보여도 태그마다 긴 클래스 목록을 읽으며 배치를 머릿속으로 다시 조합해야 할 때가 있다. 제목과 작성 버튼을 놓는 코드부터 비교해 보자. ```tsx title="Before: 클래스에서 배치를 읽는다" snippet

게시물

채널에 올릴 글을 작성하고 예약할 수 있어요.

``` ```tsx title="After: 컴포넌트 이름에서 배치를 읽는다" snippet {2-3,6} 게시물 채널에 올릴 글을 작성하고 예약할 수 있어요. ``` `VStack`은 세로 배치, `HStack`은 가로 배치다. SwiftUI에서 쓰는 이름을 빌렸다. 클래스를 하나씩 해석하지 않아도 제목과 버튼이 나란히 있고 그 아래에 안내 문구가 온다는 것이 보인다. 주변에서는 Tailwind CSS의 단점으로 가독성을 꼽는 경우가 많았다. 한 태그에 배치·색상·상태별 클래스가 길게 늘어서는 부담은 반복되는 배치를 컴포넌트로 묶고 조건부 클래스를 `cn`으로 조합하면 어느 정도 덜 수 있다고 본다. 함께 작업할 사람이 매번 정렬과 간격을 해석하지 않아도 되게 하고 싶었다. 공통 배치와 글자 스타일은 `packages/ui`에 두고, AI도 이 컴포넌트를 먼저 쓰도록 `AGENTS.md`에 기준을 남겼다. ```md title="AGENTS.md의 UI 작성 규칙 예시" - 배치는 packages/ui의 VStack, HStack, Center, Grid를 우선 사용한다. - 제목은 Heading, 본문은 Text로 작성하고 공통 간격·글자 토큰을 사용한다. - 추가 스타일은 className으로 지정하고, 조건부 클래스는 cn으로 조합한다. ``` 내부 스타일에는 계속 Tailwind를 쓴다. 자주 쓰는 배치를 공유하는 정도로 두고, 모든 CSS 속성을 Props로 만들지는 않았다. ### 익숙한 Props에 입력 규칙을 담는다 배치는 이름으로 드러내고, 반복되는 입력 규칙은 컴포넌트 안에 둔다. 이 기준은 모여의 공개 소개 페이지에도 똑같이 적용된다. 잠깐 상품 가격 입력으로 넘어가 보자. 숫자 `12_900`을 `12,900원`으로 보여 주고, 입력한 문자열은 다시 숫자로 돌려줘야 한다. ```tsx title="Before: 페이지에서 금액을 표시하고 변환한다" snippet setProductPrice(parseAmountText(event.currentTarget.value)) } /> 원 ``` ```tsx title="After: AmountInput에 금액의 표시와 변환을 맡긴다" snippet {3-4} ``` `AmountInput`은 이름만 봐도 금액을 입력받는 컴포넌트다. 사용하는 쪽은 쉼표와 숫자 변환을 반복하지 않고 가격을 어디에 저장할지만 정한다. Props는 원래 입력 요소의 관례를 따랐다. 안내 문구는 `placeholder`로, 저장 중에 입력을 막을 때는 `disabled`로 쓴다. 구현을 열어 보거나 새 이름을 외울 필요가 없다. 접근성 속성도 그대로 전달하고, 값과 변경 함수만 숫자를 주고받게 정의했다. ```ts title="amount-input.tsx: 숫자를 주고받는 입력 Props" {8} import type { ComponentProps, ReactNode } from "react"; interface AmountInputProps extends Omit< ComponentProps, "defaultValue" | "inputMode" | "value" | "onChange" > { value?: number | null; onChange: (value: number | null) => void; suffix?: ReactNode; } ``` 숫자에 쉼표를 붙이고 입력 문자열을 숫자로 바꾸는 처리는 `AmountInput` 안으로 옮긴다. ```tsx title="입력 안에서 표시와 변환을 처리한다" snippet // formatCount는 언어 설정(locale)에 맞춰 숫자에 자릿수 구분을 넣는다. onChange(parseAmountText(event.currentTarget.value)) } /> ``` ```ts title="입력을 지운 것과 0원을 구분한다" {9} const MAX_AMOUNT_DIGITS = 12; const NON_DIGIT_PATTERN = /\D/gu; function parseAmountText(text: string): number | null { const digits = text .replaceAll(NON_DIGIT_PATTERN, "") .slice(0, MAX_AMOUNT_DIGITS); return digits.length === 0 ? null : Number(digits); } ``` 빈 입력은 `null`, `"0"`은 `0`으로 구분한다. 정수 금액을 받는 입력이므로 숫자만 남기고 열두 자리까지 허용한다. 표시 형식이 바뀌면 `AmountInput`을, 입력 규칙이 바뀌면 `parseAmountText`를 고치면 된다. 값을 바꾸는 입력이니 `onChange`는 필수로 두었다. 선택 사항으로 바꾸고 기본값을 넣으면 연결을 빠뜨려도 타입 검사가 잡아내지 못한다. ```ts title="변경 함수가 꼭 필요한 입력에 noop을 쓰면" import { noop } from "es-toolkit"; // onChange가 optional이면 호출자가 빠뜨려도 통과한다. const onChange = props.onChange ?? noop; onChange(12_900); // 함수가 없으면 사용자가 입력해도 값이 바뀌지 않는다. ``` `noop`은 선택한 뒤 팝오버를 닫는 부가 동작처럼 생략해도 기능이 성립하는 콜백에만 쓴다. 가격 입력 규칙이 바뀌어도 사용하는 페이지마다 문자열 변환 코드를 찾아다닐 필요가 없다. **익숙한 사용법을 유지하면서 변경할 곳을 모으는 것**이 이 컴포넌트를 만든 이유다. 이런 설계 기준은 [추상화에 관한 글](/post/abstraction)에서도 다뤘다. > 개인적으로는 코드가 많아질수록 일관성이 더 중요하다고 생각한다. 0과 1에서 프로그래밍 언어, 자연어 프롬프트로 표현 방식은 바뀌어도 의도를 전달한다는 본질은 크게 다르지 않다. 익숙한 언어로 대화할 때 서로를 더 쉽게 이해하듯 코드에도 익숙한 약속이 필요하다. 네이티브 ``의 `value`와 `onChange`처럼 매번 새로 배우지 않아도 뜻이 통하게 일관성을 지키고 싶다. ### 함께 바뀌는 코드만 묶는다 다시 게시물 화면으로 돌아가자. 목록에서 글을 고르면 본문·첨부 파일 수·게시 상태를 보여 준다고 하자. `PostInfoRow`는 항목의 이름과 값을 놓는 행이다. 여기서 "게시 상태만 배지로 바꿔 주세요"라는 요청을 받으면 `map` 안에서 상태 항목을 따로 구분하게 된다. ```tsx title="Before: 반복문 안에서 상태 행을 구분한다" {16-17} const rows = [ { id: "text", label: "본문", value: post.text }, { id: "attachments", label: "첨부 파일", value: `${post.attachments.length}개`, }, { id: "status", label: "게시 상태", value: post.status }, ]; rows.map((row) => ( : row.value } /> )); ``` 지금은 분기 하나지만 본문에 더 보기, 첨부 파일에 미리보기가 붙으면 반복문 안의 조건도 늘어난다. 세 항목은 모양이 비슷할 뿐 서로 다른 이유로 바뀐다. 각 행을 직접 적으면 요구사항마다 고칠 자리가 드러난다. ```tsx title="After: 바꿀 항목의 JSX를 직접 수정한다" {18} // @moyeo/api는 서버와 웹이 함께 쓰는 API 계약 패키지다. import type { PostRecord } from "@moyeo/api"; import { Card, CardContent } from "@moyeo/ui/components/card"; PostInfoCard.Content = function Content({ post }: { post: PostRecord }) { return ( } /> ); }; ``` 본문에 더 보기 버튼이 필요하면 첫 행을, 게시 상태를 바꾸려면 마지막 행을 고친다. 역할이 다른 항목은 따로 고칠 수 있게 나눠 두었다. 반면 게시물 목록처럼 같은 규칙으로 개수가 늘어나는 UI에는 `map`을 쓴다. ### 카드의 상태와 스타일은 가까이에 둔다 행을 따로 적어도 같은 스타일을 반복해서 만들 필요는 없다. `post-info-card.tsx` 안에서 카드의 상태와 행의 표현을 함께 관리한다. 앞의 `Content`가 내용을 보여 주고, 게시물을 고르기 전에는 `Empty`가 나온다. ```tsx title="PostInfoCard는 빈 상태를 먼저 처리한다" export function PostInfoCard({ post }: { post: PostRecord | null }) { if (post == null) { return ; } return ; } PostInfoCard.Empty = function Empty() { return ( ); }; ``` `Content`와 `Empty`는 이 카드 안에서만 의미가 있다. 네임스페이스 패턴으로 소속을 드러내고 같은 파일에 두었다. 행의 배치와 글자 스타일은 파일 안의 지역 컴포넌트가 맡는다. ```tsx title="PostInfoRow와 Message에 반복 스타일을 모은다" {5,14} import type { ReactNode } from "react"; function PostInfoRow({ label, value }: { label: string; value: ReactNode }) { return ( {label} {value} ); } function Message({ text }: { text: string }) { return ( {text} ); } ``` 행 전체의 간격과 글자 스타일은 `PostInfoRow`에서, 빈 상태의 안내 스타일은 `Message`에서 바꾼다. 게시 상태를 배지로 바꾸는 일은 앞에서 본 그 행 하나로 끝난다. **공통 스타일을 바꿀 곳과 개별 내용을 바꿀 곳이 나뉜다.** *** ## 상태의 사용법과 저장 방법 페이지의 배치를 정했으니 처음에 나온 `usePostView`와 `usePostFilters`를 살펴보자. React에서 상태라고 하면 `useState`가 먼저 떠오른다. 모여의 상태 훅도 현재 값과 변경 함수를 `[value, setValue]` 형태의 **튜플**로 돌려준다. ```ts title="현재 값과 변경 함수를 튜플로 받는다" function PostsPage() { const [view, setView] = usePostView(); const [{ query, status }, setFilters] = usePostFilters(); // 중략 } // 각 위치의 의미와 타입을 정한다. type PostViewState = readonly [ view: PostView, setView: (nextView: PostView) => void, ]; ``` 첫 번째 값으로 현재 상태를 읽고 두 번째 함수로 상태를 바꾼다. `useState`와 사용법이 같다. **저장 방법이 바뀌어도 사용하는 쪽의 인터페이스는 그대로다.** `useState`의 값은 새로고침하면 사라진다. 다음 방문까지 선택을 남기려면 로컬 스토리지나 쿠키가 필요하다. 이처럼 실행이 끝난 뒤에도 값이 남는 성질을 **영속성**이라고 한다. 페이지에는 값을 읽고 바꾸는 방법만 주고, 어디에 얼마나 오래 둘지는 훅 안에서 정하기로 했다. ### URL에서 허용할 값을 먼저 정한다 현재 선택한 탭은 URL의 `view`에 둔다. 같은 주소를 열면 같은 보기가 나오게 하려는 것이다. 검색어와 게시물 상태도 URL에 둔다. 사용자가 주소를 직접 고칠 수 있으니 허용할 값은 Zod로 검사한다. `postStatusSchema`는 앞서 소개한 공유 패키지의 게시물 상태 정의다. 임시 저장인 `draft`, 보관된 글인 `archived` 등이 들어 있다. 목록에서만 쓰는 '전체' 조건은 여기에 `all`을 더해 만든다. ```ts title="URL에서 허용할 보기와 검색 조건을 정한다" import { postStatusSchema } from "@moyeo/api"; import { z } from "zod"; const PostView = { channelPosts: "channel_posts", posts: "posts", } as const; const postViewSchema = z.enum(PostView); type PostView = z.infer; // 'all'은 특정 게시물 상태가 아니라, 상태를 제한하지 않는 보기다. const postStatusFilterSchema = z.enum(["all", ...postStatusSchema.options]); const postsSearchSchema = z.object({ view: postViewSchema .default(PostView.channelPosts) .catch(PostView.channelPosts), status: postStatusFilterSchema.default("all").catch("all"), q: z.string().max(200).optional().catch(undefined), }); type PostsSearch = z.output; ``` `postsSearchSchema`를 라우트의 `validateSearch`에 연결한다. 잘못된 보기와 상태는 기본값으로, 허용 범위를 벗어난 검색어는 없는 값으로 읽는다. ### 저장하는 곳을 바꿔도 사용법은 유지한다 먼저 선택한 보기를 URL에 저장해 보자. 페이지에 돌려주는 것은 값과 변경 함수뿐이다. ```ts title="Before: 선택한 보기를 URL에 저장한다" {17} // postsRouteApi로 게시물 라우트의 검색 조건을 읽고 변경한다. function usePostView(): PostViewState { const view = postsRouteApi.useSearch({ select: (search) => search.view }); const navigate = postsRouteApi.useNavigate(); const reporter = useErrorReporter(); const setView = (nextView: PostView) => { runInBackground( navigate({ search: (previousSearch) => ({ ...previousSearch, view: nextView }), }), reporter, { source: "navigation", operation: "posts.view" }, ); }; return [view, setView] as const; } ``` > `runInBackground`는 비동기 작업의 실패를 놓치지 않도록 모여에서 만든 유틸이다. 여기서는 URL 변경 오류와 작업 정보를 `reporter`에 넘겨 Sentry 같은 도구에서 확인하게 한다. 이제 요구사항이 바뀌었다고 해 보자. "이 탭 선택은 링크로 공유하지 않고, 기기마다 마지막으로 본 탭을 기억하게 하자." 그러면 훅 내부만 브라우저 저장소로 바꾸면 된다. 아래 코드는 현재 모여의 저장소 유틸로 같은 인터페이스를 구현한 대안이다. ```ts title="After: 같은 튜플을 반환하고 기기에 저장한다" {15} import { useStoredValue } from "@/shared/storage/hooks/use-stored-value"; import { createWebStorageStore, } from "@/shared/storage/utils/create-web-storage-store"; const postViewStore = createWebStorageStore({ area: "local", key: "moyeo.posts.view", schema: postViewSchema, }); function usePostView(): PostViewState { const [view, setView] = useStoredValue(postViewStore, PostView.channelPosts); return [view, setView]; } ``` 이 저장소 유틸도 모여에서 직접 만들었다. 서버와 브라우저의 첫 렌더링에서는 기본값을 쓰고, 그 뒤에 기기에 저장된 선택을 반영한다. 두 구현 모두 같은 튜플을 반환하므로 페이지의 `const [view, setView] = usePostView()`는 그대로다. 쿠키나 다른 React 라우터로 바꾸더라도 저장소를 연결하는 코드는 훅 안에 모인다. 페이지는 상태를 읽고 바꾸는 사용법만 알면 된다. 물론 URL과 기기 저장소는 같은 기능이 아니다. 링크 공유가 필요하다면 URL을 유지해야 하고, 저장소로 옮긴다면 라우트의 URL 검증과 데이터 준비 기준도 함께 정리해야 한다. 변경 자체는 남는다. 훅은 **그 변경이 화면 전체로 퍼지지 않게 막는 경계**다. ### 검색 조건은 바꿀 값만 전달한다 "신메뉴 안내"를 검색하다가 임시 저장한 글만 보고 싶다면 검색어가 남아 있어야 한다. Router에서는 기존 검색 조건을 받아 바꿀 값만 덮어쓰면 된다. ```ts title="검색어와 보기는 유지하고 상태만 바꾼다" {3-4} await navigate({ search: (previousSearch) => ({ ...previousSearch, // 기존 검색어와 보기 선택을 유지한다. status: "draft", // 상태만 임시 저장으로 바꾼다. }), replace: true, }); ``` `setFilters`도 같은 방식이다. 페이지는 URL의 다른 값을 다시 조립하지 않고 바꾸려는 조건만 전달한다. ```ts title="페이지에서는 바꾸려는 조건만 전달한다" setFilters({ status: "draft" }); // 검색어를 유지한다. setFilters({ query: "신메뉴 출시" }); // 임시 저장 조건을 유지한다. ``` 검색어는 페이지에서 `query`로 쓰고, 훅 안에서 URL의 `q`와 연결한다. 서버에 조회할 때만 API가 받는 `searchText`라는 이름으로 전달한다. 검색할 때는 뒤로 가기 기록이 쌓이지 않게 현재 주소를 교체하고, 탭을 바꿀 때는 기록을 남긴다. 이런 처리를 훅에 모아 두면 게시물 조건을 바꾸는 곳마다 URL을 다시 조립하지 않아도 된다. 호출이 잦아지는 화면에서는 검색 버튼이나 입력 후 지연을 두되, 적용된 검색 조건은 URL에서 관리한다. ### 링크를 만들 때도 같은 규칙을 따른다 임시 저장한 글 중 "신메뉴"가 들어간 목록을 공유한다고 하자. URL을 문자열로 조립하면 경로나 검색 조건을 잘못 적어도 실행 전에는 알아채기 어렵다. TanStack Router의 `Link`는 **목적지에 맞는 경로 변수와 검색 조건을 함께 검사한다.** ```tsx title="목적지에 맞는 params와 search를 검사한다" {6} import { Link } from "@tanstack/react-router"; 임시 저장한 신메뉴 안내 보기 ``` 앱의 라우트 타입을 등록하면 없는 경로를 적거나 필요한 `workspaceId`를 빠뜨렸을 때 타입 오류가 난다. `status: "drafft"`처럼 상태를 잘못 적은 것도 잡힌다. 반면 사용자가 주소창에 직접 넣은 `?status=unknown`은 앞의 Zod 스키마가 검사해 `"all"`로 읽는다. 링크를 만드는 코드와 URL을 읽는 화면이 같은 정의를 따른다. 라우트마다 검색 조건의 타입을 다시 적거나 문자열의 타입을 단언할 일이 줄어든다. [TanStack Router를 도입한 이유](/post/tanstack-router)도 이 연결에 있었다. 이 검색 조건은 뒤에서 볼 목록의 사전 조회에도 그대로 쓰인다. ### Next.js에서는 nuqs로 URL 상태를 다룬다 Next.js의 `useSearchParams`는 URL 값을 문자열로 읽는다. 아래 코드는 값이 없을 때만 기본 보기를 쓰므로 `?view=unknown`은 걸러지지 않는다. ```ts title="Before: URL 값을 문자열로 읽는다" "use client"; import { useSearchParams } from "next/navigation"; function PostsPage() { const searchParams = useSearchParams(); const view = searchParams.get("view") ?? "channel_posts"; // ?view=unknown이면 view는 그대로 "unknown"이다. // 중략 } ``` nuqs를 쓰면 허용할 값과 기본값을 정해 두고 앞에서 본 튜플 형태로 읽고 바꾼다. ```ts title="After: 허용한 값으로 읽고 URL을 바꾼다" {9} "use client"; import { parseAsStringLiteral, useQueryState } from "nuqs"; function PostsPage() { const [view, setView] = useQueryState( "view", parseAsStringLiteral(["channel_posts", "posts"]) .withDefault("channel_posts"), // 잘못된 값도 기본 보기로 읽는다. ); // 중략 } ``` `setView("posts")`가 URL 변경을 맡으므로 문자열 검사와 갱신 코드를 화면마다 만들지 않아도 된다. Next.js의 경로 검사 기능인 `typedRoutes`와 함께 써도 된다. 모여는 Router로 경로·검색 조건·사전 조회를 한 라우트에 연결했다. Next.js라면 nuqs로 URL 상태의 읽기와 쓰기를 정리하는 방법이 있다. > Next.js에서는 `NuqsAdapter`를 연결한다. 서버도 같은 검색 조건으로 조회한다면 파서를 공유하고 `shallow: false`를 설정해 URL 변경을 서버에 반영한다. 자세한 설정은 공식 문서에 있다.[^nuqs-search] *** ## 목록 조회와 로딩·오류 처리 ### 화면 이름보다 필요한 조건을 받는다 검색 조건을 정했으니 목록을 불러올 차례다. 게시물 관리에서는 전체 글을, 임시 저장 목록에서는 작성 중인 글만 보여 주고 싶다. 이 차이를 목록의 Props로 어떻게 표현하면 좋을까? ```tsx title="Before: 화면 이름으로 조회 조건을 정한다" snippet {3} // 임시 저장한 글을 보고 싶은데, 페이지 이름부터 알려 줘야 한다. ``` 이 인터페이스에서는 `isDraftPage`가 임시 저장한 글 조회를 뜻한다는 규칙이 목록 안에 숨어 있다. 보관된 글을 보여 주는 화면이 생기면 `isArchivedPage`와 분기가 늘어나기 쉽다. ```tsx title="After: 필요한 조회 조건을 전달한다" snippet {3} // 같은 임시 저장 목록이다. 조회할 상태를 직접 전달한다. ``` 화면 이름 대신 필요한 조건을 전달한다. 목록은 받은 조건으로 게시물을 조회해 보여 준다. `pageSize`는 한 번에 가져올 개수다. 전체 결과를 스무 개로 제한한다는 뜻은 아니다. 이제 보관함에서는 `statuses: ["archived"]`를 전달하면 된다. 전체 글이 필요하면 `filters`를 생략한다. **지원하는 조건 안에서는 새 화면이 생겨도 목록 내부에 분기를 추가하지 않는다.** 공통 카드 모양은 `PostList`에서 고치고, 어떤 글을 보여 줄지는 사용하는 페이지에서 정한다. ### 기다리고 다시 시도할 영역도 페이지에서 정한다 목록에 무엇을 보여 줄지 정했으니 기다리는 동안과 실패했을 때의 화면도 정해야 한다. 처음에 본 `QueryBoundary` 안에 목록을 두면 목록·로딩·오류 화면이 한자리에서 읽힌다. ```tsx title="로딩·오류 화면을 목록과 함께 배치한다" snippet {2-3} } error={PostList.Error} > ``` 임시 저장 목록을 불러오는 동안에는 `PostList.Loading`, 조회에 실패하면 `PostList.Error`가 같은 자리에 표시된다. **로딩과 오류를 어디까지 처리할지도 페이지에서 보인다.** 목록과 상세의 경계를 나누면 상세 조회가 실패해도 목록에서 다른 글을 선택할 수 있다. `QueryBoundary` 안에서는 Suspense가 로딩을, Error Boundary가 조회 오류를 처리한다. 재시도할 때는 `QueryErrorResetBoundary`로 Query의 오류 상태도 함께 초기화한다. 이처럼 기다리는 영역을 나누는 이유는 [Suspense로 비동기 상태를 다룬 글](/post/react-hooks-suspense)에 더 자세히 적었다. 목록과 함께 바뀌는 상태 화면은 같은 파일에 모았다. `PostList.Loading`과 `PostList.Error`라는 이름으로 묶으면 어느 목록의 화면인지도 분명해진다. ```tsx title="post-list.tsx: 목록의 로딩·오류 화면" PostList.Loading = () => ; PostList.Error = (props: FallbackProps) => ( ); ``` 기존 `ListSkeleton`과 다른 모양이 필요할 때만 직접 그린다. 이때 es-toolkit의 `range(3)`은 같은 모양이 세 개 필요하다는 뜻을 간단히 보여 준다. ```tsx title="같은 로딩 모양이 세 개 필요하다면" import { range } from "es-toolkit"; range(3).map((index) => ( )); ``` ### 조회한 페이지에서 게시물만 꺼내 읽는다 이제 `PostList` 안에서 데이터를 읽어 보자. 글을 스무 개씩 가져오면 응답은 Query의 `data.pages`에 페이지별로 쌓인다. 화면에서는 그 경계 없이 이어 그리면 된다. 컴포넌트 안에서 배열을 펼쳐도 된다. 여러 곳에서 같은 형태로 읽는다면 `select`에 선택 함수를 연결하는 방법도 있다. 두 방식 모두 같은 게시물 배열을 만든다. ```tsx title="Before: 조회한 뒤 페이지별 게시물을 펼친다" {7} function PostList({ filters, pageSize = 20 }: PostListProps) { const { workspaceId } = workspaceRouteApi.useParams(); const orpc = useOrpc(); const { data } = useSuspenseInfiniteQuery( postListInfiniteOptions(orpc, { workspaceId, ...filters, limit: pageSize }), ); const posts = data.pages.flatMap((page) => page.items); // 중략 } ``` ```tsx title="After: select로 목록에서 읽을 형태를 정한다" {25} import type { InfiniteData } from "@tanstack/react-query"; import type { ListPostsInput, PostList as PostListOutput } from "@moyeo/api"; interface PostListProps { // 공유 요청 타입에서 목록의 사용처가 정할 조건만 받는다. filters?: Pick; pageSize?: number; } // [첫 페이지의 글들], [다음 페이지의 글들] → 하나의 게시물 목록 function selectPosts(data: InfiniteData) { return data.pages.flatMap((page) => page.items); } function PostList({ filters, pageSize = 20 }: PostListProps) { const { workspaceId } = workspaceRouteApi.useParams(); const orpc = useOrpc(); const { data: posts, fetchNextPage } = useSuspenseInfiniteQuery({ // 조회 조건에 맞는 캐시 키와 다음 페이지 설정을 만든다. ...postListInfiniteOptions(orpc, { workspaceId, ...filters, limit: pageSize, }), select: selectPosts, }); // 중략 } ``` 목록은 `posts`를 순서대로 그리고, 더 불러올 때는 `fetchNextPage`를 호출한다. 배열로 바뀌는 것은 **이 훅이 읽는 값뿐**이고, 캐시에는 다음 페이지 조회에 필요한 원래 구조가 그대로 남는다. 선택 함수는 컴포넌트 밖에 두어 렌더링마다 새로 만들지 않는다.[^select] 단순히 배열을 한 번 펼치는 곳이라면 Before도 충분하다. `select`의 이점은 같은 캐시를 읽으면서 사용처마다 필요한 결과를 고른다는 점이다. 요청량을 줄여 주지는 않는다. 아직 불러오지 않은 글까지 찾으려면 검색과 상태 조건은 서버로 보내야 한다. 이 `PostList`는 모여의 Router와 Query 환경에서 재사용한다. 다른 환경에서도 쓸 UI라면 앞의 `PostInfoCard`처럼 데이터를 Props로 받는 편이 낫다. 조회를 연결하는 부분과 내용을 그리는 부분은 필요한 재사용 범위에 맞춰 나눈다. ### 화면과 같은 조건으로 미리 불러온다 앞에서 만든 "임시 저장한 신메뉴 안내 보기" 링크를 눌렀다고 하자. 미리 불러온 데이터가 전체 글이라면 화면이 원하는 목록과 다르다. 화면의 데이터를 준비하는 `loader`에도 **목록과 같은 검색어와 상태를 전달해야 한다.** `loaderDeps`에서 검색어와 상태를 고르고, `loader`에서 그 조건으로 조회한다. 앞의 목록에 넘긴 조건과 비교해 보자. ```ts title="loader도 목록과 같은 조건으로 조회한다" {8,21-22} import { createFileRoute } from "@tanstack/react-router"; export const Route = createFileRoute( // _authenticated와 _app는 URL에 나타나지 않는 레이아웃이다. "/_authenticated/workspaces/$workspaceId/_app/posts", )({ validateSearch: postsSearchSchema, loaderDeps: ({ search }) => ({ view: search.view, query: search.q ?? "", // 검색어가 없으면 빈 입력으로 다룬다. status: search.status, }), loader: async ({ context, params, deps }) => { if (deps.view !== "posts") { return; } await context.queryClient.infiniteQuery( postListInfiniteOptions(context.orpc, { workspaceId: params.workspaceId, searchText: deps.query.trim() || undefined, statuses: deps.status === "all" ? undefined : [deps.status], limit: 20, }), ); }, }); ``` 링크에 넣었던 검색어와 임시 저장 조건은 검증을 거쳐 `loader`에 전달된다. 목록과 같은 조회 옵션에 같은 조건을 넘기므로 미리 받은 결과를 목록이 그대로 쓴다. 채널 게시물 보기라면 선택한 채널도 조건에 포함한다. 조회 옵션에는 캐시를 구분하는 Query Key도 들어 있다. 검색어·상태·워크스페이스가 다르면 결과를 따로 보관한다. 같은 QueryClient에서 같은 키로 조회하면 캐시와 진행 중인 요청을 공유한다. 다만 최신으로 보는 시간인 `staleTime`과 재조회 설정에 따라 추가 요청은 생길 수 있다. 어디에서 요청을 기다리느냐에 따라 오류를 보여 줄 위치도 달라진다. `loader`에서 기다리던 요청이 실패하면 라우트의 오류 화면을 보여 주고, 화면 안의 목록 조회가 실패하면 앞의 `PostList.Error`를 보여 준다. 더 불러오기에 실패했을 때는 이미 읽은 목록을 남기고 아래에 재시도 버튼을 둔다. 모여는 이 Router 구조에 TanStack Start의 서버 렌더링을 연결했다. 공개 소개 페이지의 본문과 메타데이터도 첫 HTML에 담는다. 서버의 Router·QueryClient와 API 쿠키는 요청마다 분리해 다른 사용자의 데이터가 섞이지 않게 했다. 브라우저는 자기 요청에서 준비한 캐시를 이어받는다. 이 첫 화면의 기준은 뒤의 예약 시각 표시에서 다시 나온다. *** ## API 계약과 권한의 기준 데이터를 어디서 읽을지 정했으니 이제 서버와 웹이 주고받을 형식과 요청을 허용할 조건을 맞출 차례다. 모여에서는 응답 정의를 서버와 웹이 함께 쓰고 실행 권한은 서버에서 확인한다. 그리고 화면에서 무엇을 다시 조회할지는 순수 함수에 모았다. ### 웹 밖에서도 사용할 API가 필요했다 게시물 조회와 예약 기능을 모여 웹에만 묶어 두고 싶지는 않았다. 나중에는 외부 서비스에서도 호출하고, AI 도구도 MCP로 같은 기능을 쓰게 하고 싶었다. MCP는 AI 도구가 쓸 기능과 호출 방법을 알려 주는 규약이다. 서버와 웹은 같은 저장소에서 TypeScript로 개발하고 있었다. 내부에서는 **타입을 바로 공유**하고 외부에는 HTTP API와 명세를 제공하는 방식을 찾았다. 비교한 것은 다음 세 구성이었다. | 구성 | 타입을 연결하는 방법 | 모여에서 고려한 점 | | ---------------------- | --------------------------------- | -------------------------------------------------------- | | REST + OpenAPI + Orval | HTTP API 명세에서 웹의 타입과 호출 코드를 생성한다. | 서버 언어에 얽매이지 않지만 명세와 생성물을 갱신·검증하는 과정이 필요하다. | | tRPC | 서버의 API 정의에서 클라이언트 타입을 추론한다. | TypeScript와 Query 연동이 편하다. 외부 공개 시 호출 형식과 명세 구성도 살펴야 한다. | | oRPC | 공유 계약에서 웹의 타입과 HTTP API 명세를 얻는다. | 입출력과 HTTP 경로를 함께 정의한다. 계약의 검증·오류 처리 규칙도 따라야 한다. | REST + Orval 조합도 요청 함수와 Query 코드를 생성해 준다.[^orval] 다만 모여는 서버와 웹을 함께 고치므로 내부 타입은 공유한 TypeScript 계약에서 바로 얻고 외부 문서가 필요할 때 OpenAPI 명세를 만드는 흐름을 택했다. tRPC도 이 조건은 만족한다. 모여는 여기에 더해 외부에서 호출할 HTTP 경로와 입출력까지 같은 계약에서 관리하고 싶었고, 이를 OpenAPI와 함께 구성하기에는 oRPC가 잘 맞았다. 웹도 oRPC의 `OpenAPILink`로 이 HTTP API를 호출한다. REST는 그대로 두고, oRPC는 HTTP API를 정의하고 타입을 연결하는 도구로 쓴다.[^orpc] 물론 oRPC를 쓰려면 그 도구의 계약 작성법과 오류 처리 규칙을 따라야 한다. 외부 연동 기능은 다른 도구에도 있다. tRPC에는 OpenAPI 연동이, Orval에는 MCP 생성 기능이 있다.[^trpc-api][^orval] 모여가 고른 기준은 **내부 타입과 외부 HTTP 명세를 같은 계약으로 관리하는 것**이었다. MCP를 연결할 때는 도구로 공개할 범위와 호출 권한을 따로 정할 계획이다. ### 서버와 웹은 같은 응답 정의를 쓴다 그 선택이 조회 코드에는 어떤 차이를 만들었을까? 게시물 본문을 `text`로 받는 경우를 보자. ```ts title="Before: 서버와 웹에 응답을 각각 정의한다" // 서버의 게시물 응답 const postDetailSchema = z.object({ id: z.string(), text: z.string(), }); // 서버 정의가 바뀌어도 이 타입은 그대로 남는다. type PostResponse = { id: string; text: string }; ``` 모여는 요청·응답의 약속인 **API 계약**을 `packages/api`에 둔다. 앞에서 사용한 `@moyeo/api`가 이 공유 패키지다. 응답 스키마를 계약에 연결하면 서버와 웹이 같은 정의를 사용한다.[^orpc-version] ```ts title="After: 응답 스키마를 공유 계약에 연결한다" {16,27} import { oc } from "@orpc/contract"; import { openapi } from "@orpc/openapi"; import { z } from "zod"; // packages/api: 게시물 응답 중 ID와 본문만 남겼다. export const postDetailSchema = z.object({ id: z.string(), text: z.string(), }); export type PostRecord = z.infer; export const getPostContract = oc .meta(openapi({ method: "GET", path: "/workspaces/{workspaceId}/posts/{postId}", inputStructure: "detailed", // params를 HTTP 경로에 연결한다. })) .input( z.object({ params: z.object({ workspaceId: z.string(), postId: z.string(), }), }), ) .output(postDetailSchema); ``` `input`은 조회할 워크스페이스와 게시물 ID, `output`은 응답의 형태다. 같은 계약의 `method`와 `path`는 외부에서 호출할 HTTP 경로를 정한다. 서버는 이 계약에 맞춰 구현하고, 웹은 계약에 연결된 클라이언트로 조회한다. ```tsx title="웹은 응답 타입을 다시 적지 않고 조회한다" {11} function PostArticle() { const { workspaceId, postId } = postDetailRouteApi.useParams(); const orpc = useOrpc(); const { data: post } = useSuspenseQuery( orpc.publishing.getPost.queryOptions({ input: { params: { workspaceId, postId } }, }), ); // 응답 타입을 따로 적지 않아도 본문이 문자열임을 알 수 있다. return {post.text}; } ``` 공유 스키마에서 `text`를 `body`로 바꾸면 위의 `post.text`에 타입 오류가 난다. **응답 정의는 한곳에서 수정하고, 고쳐야 할 화면은 타입 검사로 찾는다.** 복사해 둔 타입을 믿고 있다가 실행 중에야 문제를 발견하는 일이 줄어든다. 다만 타입 검사는 지금 함께 검사하는 코드에만 적용된다. 이전 버전의 웹이나 외부 클라이언트까지 바뀌지는 않는다. 외부에 공개할 때는 기존 필드를 유지하거나 API 버전을 나누는 등 호환성도 관리해야 한다. ### 할 수 있는 일은 서버가 판단한다 요청의 형태를 계약으로 맞췄다고 해서 누구나 그 요청을 실행해도 되는 것은 아니다. 예를 들어 관리자라도 요금제에서 제공하는 채널 수를 다 썼다면 새 채널은 연결하지 못한다. 역할만 보고 버튼을 활성화하면 이런 차이를 놓친다. ```tsx title="Before: 관리자라는 이유만으로 연결 버튼을 연다" {7} function ChannelConnectButton() { const role = useWorkspaceAccessContext( (context) => context.currentMembership.role, ); // 중략 const canConnect = role === "owner" || role === "admin"; return ; } ``` 여기에 구독 상태와 남은 채널 수를 하나씩 더해 갈 수도 있다. 하지만 사이드바와 설정 화면에 같은 조건을 따로 적으면 한도를 바꿀 때마다 두 화면을 함께 고쳐야 한다. 모여는 아래 기준을 서버의 `AccessControl` 한곳에서 판단한다. | 기준 | 확인할 내용 | | ----------- | --------------------------------------------------- | | 권한 | 이 사용자가 해당 작업을 할 수 있는가. 게시 작업이라면 대상 채널의 접근 권한도 확인한다. | | Entitlement | 이 워크스페이스에서 사용할 수 있는 기능과 한도는 무엇인가. | | Quota | 현재 사용량을 고려해 이번 작업을 더 실행할 수 있는가. | 역할뿐 아니라 사용자와 대상 채널, 수행할 작업의 속성을 함께 보는 방식이 **ABAC**이다. 역할도 판단에 사용하는 속성 중 하나다. 접근 제어 방식의 차이는 앞서 쓴 [ABAC 도입기](/post/rbac-abac)에서 다뤘다. 화면에는 판단 결과와 허용하지 않은 이유를 전달한다. 같은 버튼이라도 권한이 없는 사람에게는 관리자에게 문의하도록, 채널 한도를 다 쓴 사람에게는 요금제를 확인하도록 안내한다. ```tsx title="After: 서버가 판단한 허용 여부와 이유를 읽는다" {3,9} function ChannelConnectButton() { const availability = useWorkspaceAccessContext( (context) => context.actions.connectChannel, ); // 중략 return ( 채널 연결 ); } ``` `ActionButton`은 `isAllowed`로 버튼 상태를, `reasonCode`로 안내 문구를 정하는 공통 컴포넌트다. 위 예제에는 이 부분만 남겼다. 실제 채널 연결 버튼은 한도를 소진한 경우 요금제 안내를 여는 `PlanGateButton`으로 연결한다. 화면은 **어떻게 안내할지**만 정하고, 허용 조건은 서버가 관리한다. 채널 한 자리가 남았을 때 두 탭에서 동시에 연결을 눌렀다고 해 보자. 버튼을 그릴 때는 둘 다 가능했어도, 두 요청을 모두 허용하면 한도를 넘는다. 그래서 요청이 들어오는 시점에 다시 판단한다. | 위치 | 맡긴 책임 | | ----- | --------------------------------------------------- | | DB | 멤버십·채널 접근 권한·구독 상태·사용량을 보관한다. | | 서버 | 이 사실로 허용 여부를 판단하고, 변경 시에는 트랜잭션과 필요한 잠금 안에서 다시 확인한다. | | 클라이언트 | 허용 여부와 사유로 버튼과 안내를 표시한다. | 첫 화면은 SSR에서 준비한 접근 정보를 사용한다. 이후 역할이나 요금제가 바뀌면 Query 캐시를 갱신하고, 버튼도 같은 Query를 구독해 새 판단을 읽는다. 라우트 진입 때 받은 값을 복사해 계속 쓰면 예전 권한으로 버튼을 그리게 된다. > 버튼의 비활성화는 사용자를 위한 안내다. 누가 API를 직접 호출해도 같은 조건이 지켜지도록 최종 허용 여부는 서버가 다시 검사한다. ### 다시 확인할 조건은 정책으로 모은다 서버가 알려 주는 데이터와 화면에서 내릴 판단도 나눴다. 게시 작업이 언제 끝나는지는 서버가 알지만, 어떤 작업을 다시 확인할지는 화면의 조회 정책이 정한다. 목록과 상세가 서로 다른 기준으로 확인하지 않도록 이 판단을 한곳에 모았다. > 모여는 평소 SSE로 서버의 변경 신호를 받는다. 신호를 놓친 경우에 대비해 진행 중이거나 예약이 가까운 작업만 주기적으로 다시 조회한다. 이 보완 조회가 폴링이며, 뒤의 여러 탭 동기화에서도 같은 정책을 사용한다. "예약 2분 전 말고 3분 전부터 확인하자"는 요청을 받았다고 하자. 목록과 상세에 다음 조건을 각각 적었다면 두 곳을 같은 기준으로 고쳐야 한다. ```ts title="Before: 조회하는 곳에서 확인할 작업을 직접 판단한다" {5} const needsPolling = publications.some((publication) => ["publishing", "retry_wait", "unconfirmed"].includes(publication.status) || (publication.status === "scheduled" && publication.schedule != null && Date.parse(publication.schedule.scheduledAt) - nowMs < 2 * 60_000), ); ``` 이 판단을 `publication.model.ts`에 모아 보자. `PublicationListItem`은 공유 패키지에 정의한 예약·게시 작업의 응답 타입이다. 상태와 시각을 낱개로 전달하거나 모델을 다시 만들지 않고, 작업을 그대로 받아 판단한다. ```ts title="After: publication.model.ts에 판단을 모은다" {3,28-29} import type { PublicationListItem } from "@moyeo/api"; const POLLING_WINDOW_MS = 2 * 60_000; export function isInProgress(publication: PublicationListItem) { return ["publishing", "retry_wait", "unconfirmed"].includes( publication.status, ); } export function isScheduleDueSoon( publication: PublicationListItem, nowMs: number, ) { const { status, schedule } = publication; if (status !== "scheduled" || schedule == null) { return false; } const remainingMs = Date.parse(schedule.scheduledAt) - nowMs; return remainingMs < POLLING_WINDOW_MS; } export const PublicationPolicy = { shouldPoll(publication: PublicationListItem, nowMs: number) { return ( isInProgress(publication) || isScheduleDueSoon(publication, nowMs) ); }, }; ``` 진행 중인지와 예약 시각이 가까운지는 각각 순수 함수가 판단한다. `PublicationPolicy`는 두 함수를 묶어 사용하는 쪽에 판단 하나만 내놓는다. 목록과 상세에서는 내부 조건을 다시 적지 않고 같은 정책을 호출한다. ```ts title="목록과 상세에서 같은 정책을 호출한다" {2} const needsPolling = publications.some((publication) => PublicationPolicy.shouldPoll(publication, nowMs), ); ``` 3분 전부터 확인하려면 `POLLING_WINDOW_MS`와 경계값 테스트를 바꾼다. **호출부는 그대로다.** 관련된 판단을 인터페이스 하나로 감싼다는 점에서 [Facade 패턴](/post/facade-pattern)으로 볼 수도 있다. 정책은 확인할 대상을 고르고, 실제 조회 간격과 탭 상태에 따른 실행은 Query와 복구 조회 코드가 맡는다. 현재 시각도 인자로 받으니 테스트에 필요한 상황을 그대로 만들 수 있다. React를 렌더링하거나 서버를 부르지 않고 예약까지 1분 59초 남은 작업을 넘겨 결과만 확인하면 된다. ```ts title="예약까지 1분 59초가 남은 상황을 검사한다" import { createPublicationListItemFixture } from "@moyeo/api/testing"; import { expect, it } from "vitest"; import { PublicationPolicy } from "./publication.model"; it("예약 시각이 2분 미만으로 남으면 다시 확인한다", () => { // Given const nowMs = Date.parse("2026-10-11T00:00:00Z"); // 나머지 필수값은 테스트용 생성 함수가 채운다. const publication = createPublicationListItemFixture({ status: "scheduled", scheduledAt: "2026-10-11T00:01:59Z", }); // When const shouldPoll = PublicationPolicy.shouldPoll(publication, nowMs); // Then expect(shouldPoll).toBe(true); }); ``` 정확히 2분이 남으면 `false`, 예약 시각이 지났는데 아직 예약 상태라면 `true`다. 경계값 테스트도 함께 두어 기준을 바꿀 때 확인한다. 함수가 시스템 시각을 직접 읽지 않으니 Fake Timers도 필요 없다. 응답의 형태가 바뀌면 계약과 사용처를 확인하고, 예약 확인 기준이 바뀌면 정책과 테스트를 고친다. 서버와 공유할 정의와 화면에서 내릴 판단을 구분하니 변경할 곳도 분명해졌다. *** ## 큰 파일과 작성 중인 글 보호 컴포넌트와 상태, 조회 방식을 정리해 두니 새 화면을 만들 때 같은 판단을 반복하는 일이 줄었다. 그만큼 실제 사용 중에 생기는 문제를 살펴볼 여유가 생겼다. 신메뉴 안내에 영상을 첨부하고 본문을 다듬는 과정부터 보자. ### 큰 영상을 준비하는 동안에도 입력할 수 있게 큰 영상을 첨부한 뒤에도 사용자는 본문을 계속 쓰고 싶다. 모여는 업로드하기 전에 파일 내용으로 SHA-256 해시를 만들어 식별값으로 쓴다. 이때 영상을 한 번에 읽으면 계산을 시작하기도 전에 큰 메모리가 필요하다. ```ts title="Before: 파일 전체를 읽고 해시를 계산한다" {2} async function hashBlob(blob: Blob) { const fileBytes = await blob.arrayBuffer(); const digest = await crypto.subtle.digest("SHA-256", fileBytes); return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0"), ).join(""); } ``` `arrayBuffer()`와 `digest` 호출 모두 파일 전체를 한 번에 다룬다. 모여는 hash-wasm으로 8MiB씩 읽어 같은 계산에 차례로 넣었다.[^hash] ```ts title="After: 8MiB씩 읽어 같은 해시 계산에 누적한다" {15} import { createSHA256 } from "hash-wasm"; async function hashBlobInChunks(blob: Blob, signal?: AbortSignal) { const hasher = await createSHA256(); hasher.init(); const chunkBytes = 8 * 1_024 * 1_024; for (let offset = 0; offset < blob.size; offset += chunkBytes) { signal?.throwIfAborted(); // 전체 파일 대신 이번에 계산할 8MiB만 읽는다. const chunkBuffer = await blob .slice(offset, offset + chunkBytes) .arrayBuffer(); hasher.update(new Uint8Array(chunkBuffer)); } signal?.throwIfAborted(); return hasher.digest("hex"); } ``` 나눠 읽어도 해시는 파일 전체에 대해 하나만 나온다. 여기에 Worker를 붙여 계산을 화면의 입력·렌더링과 다른 스레드에서 실행했다. 8MiB씩 읽어 **메모리 부담**을 줄이고, Worker로 **입력이 막히는 문제**를 줄였다. `async`를 붙인다고 계산이 다른 스레드로 옮겨가지는 않는다. 개발 중에 1GiB 파일로 두 방식을 비교했다. | 비교 항목 | 전체를 한 번에 읽기 | 청크 + Worker | | ------------- | ----------- | ----------- | | 최대 추가 RSS 중앙값 | 2.02GiB | 270MiB | | 해싱 시간 | 1.09초 | 2.85초 | RSS는 프로세스가 실제로 차지한 메모리다. 최대 추가 RSS는 약 87% 줄었지만 계산 시간은 늘었다. 빨리 끝내는 것보다 메모리 부담을 낮추고 입력을 이어 가는 쪽을 골랐다. 현재 방식으로 5회 관측하는 동안 50ms 이상 걸린 메인 스레드 작업도 없었다.[^upload-measurement] 대신 자원의 수명을 챙겨야 한다. 사용자가 취소하면 Worker를 종료하고, 미리보기용 임시 주소인 object URL은 사용 후 해제한다. Worker를 쓸 수 없어 메인 스레드에서 계산하는 환경이라면 입력 응답성이 달라질 수 있다. ### 늦게 도착한 응답이 새로 쓴 글을 지우지 않게 본문을 다듬는 AI 요청도 입력을 막지 않는다. 그러다 보면 응답을 기다리는 사이에 사용자가 글을 고치기도 한다. 아래 그림처럼 본문 A로 요청한 뒤 B로 수정했다면, 늦게 도착한 A의 제안보다 지금 쓰고 있는 B를 지켜야 한다. (이미지: 본문 A로 보낸 요청이 끝나기 전에 B로 수정하면 현재 본문 B를 보존한다) 그림의 마지막 칸처럼 A의 제안은 편집기 밖에 머물고 화면에는 B가 남아야 한다. 응답을 작성 폼에 바로 넣으면 요청 뒤에 고친 내용이 사라진다. 아래의 `form`은 본문을 관리하는 React Hook Form 객체다. ```ts title="Before: 응답이 오면 현재 본문을 무조건 교체한다" {5} function PostComposer() { // 중략 function applySuggestion(suggestedText: string) { // 응답을 기다리는 사이 수정한 본문도 덮어쓴다. form.setValue("baseText", suggestedText); } // 중략 } ``` 모여는 요청 당시의 본문과 대상 채널을 기억한다. **둘 중 하나라도 바뀌었다면 현재 글을 유지한다.** 이 판단도 앞의 조회 정책처럼 순수 함수로 분리했다. ```ts title="After: 요청 당시의 초안과 같을 때만 제안을 적용한다" {15} type DraftSnapshot = { text: string; channelId: string; }; function resolveSuggestedText( requestedDraft: DraftSnapshot, currentDraft: DraftSnapshot, suggestedText: string, ) { const isUnchanged = requestedDraft.text === currentDraft.text && requestedDraft.channelId === currentDraft.channelId; return isUnchanged ? suggestedText : currentDraft.text; } ``` 본문이 같더라도 취소되었거나 새 요청으로 교체된 응답일 수 있다. 그 여부는 요청을 관리하는 호출부에서 확인하고, 이 함수는 현재 글을 바꿔도 되는지만 판단한다. 편집을 잃는 원인은 AI 응답 말고도 있다. 아래 경우는 따로 처리했다. * **다른 탭에서 먼저 저장한 경우:** 편집을 시작할 때의 `expectedVersion`을 서버에 보내 충돌을 확인한다. 현재 폼은 남겨 두고 최신 내용을 불러올지는 사용자가 선택한다. * **창을 닫았다가 돌아오는 경우:** 새 글의 본문과 채널 설정을 기기에 저장해 24시간 안에 복원한다. 저장·게시가 끝나면 대기 중인 자동 저장도 취소해 완료된 초안이 다시 생기지 않게 한다. * **서버만 먼저 배포된 경우:** 서버 릴리스가 앞서 생긴 낯선 응답 필드는 제거하고 다시 검사한다. 필수값 누락과 타입 오류는 그대로 거부한다. 새 버전이 있다고 알리고, 작업을 마친 뒤 새로고침하게 한다. 공유 계약만으로는 이미 열려 있는 브라우저의 버전이나 작성 중인 값까지 지키지 못한다. 응답을 받을 수 있는지와 지금 적용해도 되는지는 따로 판단했다. *** ## 예약 시각과 서버 렌더링 ### 같은 오전 1시 30분이 두 번이라면 글을 다 썼다면 게시할 시간을 고른다. "뉴욕 시간으로 11월 1일 오전 1시 30분"은 언제일까? 2026년 그날은 서머타임이 끝나 시계를 한 시간 뒤로 돌린다. 같은 오전 1시 30분이 두 번 오는 날이다. | 사용자가 고를 시각 | 실제 시점 | | ------------------------- | ---------------------- | | 첫 번째 오전 1시 30분 (`−04:00`) | `2026-11-01T05:30:00Z` | | 두 번째 오전 1시 30분 (`−05:00`) | `2026-11-01T06:30:00Z` | 날짜와 시각만으로는 두 후보를 구분할 수 없다. 그렇다고 기기의 시간대로 먼저 바꾸면 사용자가 고른 뉴욕 시간이라는 의미가 사라진다. 그래서 모여는 입력한 날짜·시각·시간대를 함께 서버에 보낸다. ```ts title="예약 입력에는 선택한 지역의 시간대를 함께 담는다" {4} const scheduleInput = { scheduledLocalDate: "2026-11-01", scheduledLocalTime: "01:30", scheduledTimeZone: "America/New_York", }; ``` 서버는 이 값으로 실제 게시할 시점을 계산한다. 두 후보가 생기면 사용자가 어느 쪽인지 고르게 하고, 시계를 앞으로 돌려 사라진 시각이라면 다시 선택하게 한다. 확정된 시점은 DB의 `timestamptz(3)`에 저장하고, 입력한 지역 날짜·시각·시간대와 중복 시각에서 고른 쪽도 따로 남긴다. `timestamptz`만으로는 사용자가 고른 `America/New_York`라는 이름까지 기억하지 못하기 때문이다.[^postgres-time] ### 컨테이너부터 화면까지 시간의 기준을 정한다 예약 계산이 맞다고 끝은 아니다. 개발 환경에서는 서울 시간, 배포한 서버에서는 UTC, DB 연결에서는 또 다른 시간대를 기본값으로 쓴다면 날짜를 읽는 곳마다 결과가 달라질 수 있다. 같은 예약이 실행 환경에 따라 다르게 해석되지 않도록 위치마다 쓸 기준을 정했다. | 위치 | 모여에서 정한 기준 | | ----------- | ----------------------------------------------------------------------------------- | | Docker 컨테이너 | API와 Worker가 사용하는 서버 이미지에 `TZ=UTC`를 둔다. 로컬 Compose의 서버와 PostgreSQL도 UTC로 맞춘다. | | DB | 확정된 시점은 `timestamptz(3)`에 저장하고, 새 연결마다 `timezone=UTC`를 지정한다. DB 서버의 기본 설정에 기대지 않는다. | | 서버 | 환경 설정의 `TZ`는 UTC만 허용한다. 지역별 예약 계산에는 사용자가 선택한 시간대를 명시하고, 확정 시점은 UTC 문자열로 전달한다. | | 클라이언트 | 서버와 첫 브라우저 렌더링에서 같은 표시 시간대와 기준 시각을 사용한다. 사용자의 기기 시간대는 hydration 이후에 읽는다. | 서버 이미지에는 프로세스의 기본 시간대를 적어 두었다. 로컬 Compose에서도 같은 값을 지정한다. ```dockerfile title="서버 이미지에서도 UTC를 기본값으로 둔다" {2} # apps/server/Dockerfile의 실행 단계 ENV TZ=UTC ``` 설정 파일에 적는 것만으로는 배포할 때 다른 값이 들어오는 것을 막지 못한다. 서버의 환경 검증에서도 UTC만 받도록 했다. ```ts title="다른 시간대가 설정되면 시작할 때 발견한다" {5} import { z } from "zod"; // packages/env/src/server/fields/process.fields.ts 중 일부 export const processFields = { TZ: z.literal("UTC", "TZ는 UTC여야 합니다.").default("UTC"), }; ``` 컨테이너의 `TZ`와 DB 연결의 시간대는 서로 다른 설정이다. 그래서 `packages/db`의 공통 연결 코드도 연결을 만들 때마다 `-c timezone=UTC`를 전달한다. 로컬 PostgreSQL은 Compose에서 기본값을 UTC로 두지만, 애플리케이션은 그 기본값이 달라져도 같은 기준으로 연결한다.[^runtime-time] 이 기준은 테스트에서도 확인한다. PostgreSQL의 기본 시간대를 일부러 `Asia/Seoul`로 띄운 뒤 연결 세 개가 모두 UTC인지 검사한다. 다른 테스트에서는 프로세스의 시간대를 UTC·서울·로스앤젤레스로 바꿔도 조회 기간과 토큰 만료 판단이 같은지 비교한다. 여기서 말하는 일관성은 어디서 실행하든 **같은 입력을 같은 의미로** 처리하는 데 있다. 실행·저장 기준은 UTC로 맞추고, 예약과 화면 표시에 필요한 지역 시간대는 명시한다. 모든 사용자에게 UTC로 보여 준다는 뜻은 아니다. 이 구분은 서버가 만든 화면을 브라우저가 이어받을 때도 필요하다. ### 서버와 브라우저에서 같은 날짜를 보여 준다 예약 시점을 제대로 저장해도 화면에서 다르게 읽힐 수 있다. 같은 순간이 서울에서는 11월 1일인데 뉴욕에서는 아직 10월 31일이기도 하다. 서버와 브라우저가 각자의 기본 시간대로 표시하면 첫 HTML과 브라우저가 이어 그린 날짜가 달라진다. ```tsx title="Before: 실행 환경의 기본 시간대로 예약 시각을 표시한다" {7} function ScheduledPostTime({ scheduledAt, }: { scheduledAt: string }) { return ( ); } ``` 서버는 UTC로, 브라우저는 서울 시간으로 돌고 있을 수 있다. 같은 `scheduledAt`을 받아도 기본 설정이 다르면 출력이 달라진다. 언어와 시간대를 명시하면 양쪽이 같은 기준으로 날짜와 시각을 표시한다.[^start-hydration] ```tsx title="After: 표시할 언어와 시간대를 지정한다" {12} function ScheduledPostTime({ scheduledAt, }: { scheduledAt: string }) { const { locale, timeZone } = useAuthContext( (context) => context.preferences, ); return ( ); } ``` 예제에는 표시 기준의 차이만 남겼다. 실제 모여는 같은 설정을 받는 포맷 유틸에서 `Intl.DateTimeFormat`을 재사용한다. ### '오늘'의 기준도 서버와 맞춘다 오늘 예약은 시각만, 다른 날 예약은 날짜까지 보여 주려면 현재 시각도 알아야 한다. 이 현재 시각도 서버와 맞춰야 한다. 서버가 자정 직전에 렌더링하고 브라우저가 자정 직후에 이어 그릴 수도 있기 때문이다. ```tsx title="첫 화면에서는 서버가 정한 기준 시각도 이어받는다" {8} function ScheduledPostTime({ scheduledAt, }: { scheduledAt: string }) { const viewer = useAuthContext( (context) => context.preferences, ); // 서버와 첫 클라이언트 렌더링이 공유한다. const nowAt = useNowAt(); return ( ); } ``` `useNowAt`은 루트 라우트에서 정한 기준 시각을 읽는다. `formatUpcomingInstant`는 그 시각과 표시 설정으로 표시 형식을 고른다. 브라우저가 서버의 HTML을 이어받는 **hydration**이 끝난 뒤에는 필요한 UI만 `useLiveClock`으로 갱신한다. 기기의 시간대도 `useDeviceTimeZone`에서 그 이후에 읽는다. 그래야 서버가 모르는 기기 설정 때문에 첫 화면이 바뀌지 않는다. ### 표시와 집계에 필요한 시간대는 다르다 시간대는 기능마다 목적에 맞게 골랐다. * **게시 캘린더:** 사용자 설정을 우선하고, 없으면 워크스페이스 설정과 기본값인 `Asia/Seoul` 순서로 정한다. * **성과 집계:** 같은 팀이 같은 하루의 실적을 보도록 워크스페이스 시간대를 사용한다. * **결제 기간 계산:** 구독을 시작할 때 정한 시간대를 유지한다. 표시 설정을 바꿨다는 이유로 청구 기간이 움직이지 않게 했다. 게시 캘린더에서는 시간대를 바꾸면 날짜별로 묶이는 게시물도 달라진다. 이 조회의 Query Key에 시간대도 넣었다. 표시 문구만 고치면 이전 시간대로 받은 날짜별 목록이 그대로 남을 수 있다. 시간대는 날짜를 꾸미는 설정에서 그치지 않고 **어느 날의 데이터를 조회하고 다시 쓸지**까지 정한다. *** ## 여러 탭의 게시 상태 동기화 예약을 마쳤다면 이제 게시 결과를 기다릴 차례다. 한 탭에서 보낸 요청의 결과는 다른 탭에서도 보여야 한다. 먼저 서버가 어떤 변경을 알릴지 정하고, 그 신호를 여러 탭에 전달하는 방법을 골랐다. ### 게시 상태의 변경 신호도 계약으로 받는다 SSE는 서버가 브라우저에 변경 신호를 계속 보내도록 연결을 유지하는 방식이다. 모여는 "게시물이 바뀌었다"는 신호를 받으면 해당 데이터를 다시 읽는다. 조회 응답과 마찬가지로 신호의 형태도 앞의 공유 계약에 정의했다. ```ts title="변경 신호의 형태도 응답 계약으로 정한다" {10} import { notificationStreamEventSchema, watchNotificationsInputSchema, } from "@moyeo/api"; import { asyncIteratorObject, oc } from "@orpc/contract"; export const watchNotificationsContract = oc .input(watchNotificationsInputSchema) // 공유 스키마로 스트림의 각 이벤트를 검사한다. .output(asyncIteratorObject(notificationStreamEventSchema)); ``` 공유 스키마에는 알림 변경과 게시물 변경 같은 이벤트가 들어 있다. 게시물 변경에는 워크스페이스와 게시물 ID가 있고, 알림 변경에는 게시물 ID가 없다. 웹은 이벤트 종류부터 확인하고 그에 맞는 값을 읽는다.[^orpc-sse] ```ts title="게시물 변경 신호를 확인한 뒤 갱신을 맡긴다" {17,22} import type { WorkspaceChangedEvent } from "@moyeo/api"; import { consumeAsyncIterator } from "@orpc/client"; import type { OrpcQueryUtils } from "@/api/create-api-client"; function subscribeToPostChanges( orpc: OrpcQueryUtils, signal: AbortSignal, onPostsChanged: (change: WorkspaceChangedEvent) => void, ) { return consumeAsyncIterator( orpc.notification.watchNotifications.call( { query: { scopes: ["publishing"] }, headers: {}, body: undefined }, { signal }, ), { onEvent(event) { if (event.type !== "publishing_changed") { return; } // 게시물 ID와 작업 공간을 담은 이벤트만 갱신 함수에 전달한다. onPostsChanged(event); }, }, ); } ``` `onPostsChanged`는 공유 타입인 `WorkspaceChangedEvent`를 받아 캐시를 갱신한다. 신호에는 워크스페이스와 게시물 ID 말고도 목록 전체를 다시 읽어야 하는지가 담겨 있다. 필요한 정보가 빠지지 않게 이벤트를 통째로 넘겼다. 이벤트 종류를 확인하기 전에 `postIds`를 읽거나 `postIdz`처럼 잘못 적으면 타입 오류가 난다. 일반 조회든 SSE든 타입은 계약에서 이어진다. tRPC도 타입이 연결되는 SSE를 지원하지만, 모여는 이미 고른 계약 체계를 실시간 신호에도 그대로 썼다.[^trpc-api] ### 변경 신호를 탭마다 받아야 할까 각 탭이 이 구독을 직접 실행하면 구현은 단순하다. 다만 같은 계정을 다섯 탭에서 열면 같은 신호를 받는 연결도 다섯 개가 된다. 탭이 늘어나도 연결 하나로 변경을 나눠 받을 수는 없을까? 그래서 대표 탭 하나만 서버에 연결하고 나머지 탭에 신호를 나눠 주게 했다. 이 대표 탭을 리더라고 부른다. Web Locks는 대표 역할이 겹치지 않게 조정하고, BroadcastChannel은 탭 사이에 메시지를 전달한다.[^browser-coordination] SSE 자체의 동작은 [SSE 이해와 구현](/post/http-sse)에서 다뤘다. 아래 도식에서는 어느 탭이 서버와 연결되어 있는지, 그 탭이 숨겨지면 누가 이어받는지를 보면 된다. 처음에는 탭마다 연결하던 것이 리더가 정해지면 하나로 줄고, 리더가 숨겨지면 다른 탭이 연결을 넘겨받는다. 리더가 "이 게시물이 바뀌었다"고 알리면 각 탭은 자기 Query 캐시를 무효화하고 데이터를 다시 읽는다. 앞에서 조회 옵션에 Query Key를 함께 둔 이유도 여기에 있다. 데이터를 읽을 때와 갱신할 때 같은 키로 해당 게시물을 찾아야 한다. 동시에 보이는 창 5개와 이벤트 100개로 비교해 보니 연결이 안정된 상태에서 서버 연결은 5개에서 1개로 줄었다. 각 창이 신호를 받는 것도 확인했다.[^sse-measurement] 대신 연결을 넘겨주고 놓친 신호를 복구하는 일이 생겼다. * **리더가 숨겨지거나 닫히면:** 다른 보이는 탭이 이어받는다. * **SSE 연결을 교체하면:** 새 연결의 첫 신호를 받은 뒤 이전 연결을 닫는다. 이때는 연결이 잠시 겹칠 수 있다. * **조회 중 새 변경이 생기면:** 변경에 붙인 번호를 비교해, 먼저 시작한 조회가 끝나도 다시 읽어야 하는지 확인한다. 완료 신호를 놓친 작업은 앞의 정책에 따라 폴링으로 보완한다. 연결 수를 줄이는 일과 게시 결과를 끝까지 확인하는 일은 함께 설계해야 했다. > 탭 간 통신이 가능한 같은 출처·스토리지 구획 안에서 계정별로 연결을 조정한다. Web Locks나 BroadcastChannel을 쓸 수 없으면 각 탭이 직접 연결한다. *** ## 게시 요청과 실제 성공 ### 사용자가 어디에서 멈추는지 확인한다 게시 결과를 보여 주는 기능을 만들었다면 사용자가 그 단계까지 오는지도 확인해야 한다. 작성 화면을 열고도 게시를 요청하지 않는 경우와 요청한 뒤 게시에 실패한 경우는 고쳐야 할 문제가 다르다. 이 둘을 구분하려고 기록할 지점부터 정했다. | 확인할 흐름 | 브라우저에서 기록하는 행동 | 실제 성공의 기준 | | ------------- | -------------------- | ------------------- | | 작성에서 게시까지 | 작성 화면 진입 → 게시 요청 제출 | 서버가 확인한 외부 채널 게시 완료 | | 요금제 선택에서 결제까지 | 요금제 안내 열기 → 결제 절차 시작 | 서버의 결제·구독 기록 | 화면에서 무엇을 시도했는지는 **브라우저 이벤트**로, 실제로 끝났는지는 **서버 기록**으로 확인한다. 화면 이탈도 같은 기간과 사용자·세션 기준으로 비교한다. 반복 클릭이나 측정 차단도 있으니 이벤트 횟수를 그대로 성공 수로 세지는 않는다. 먼저 화면에서 GA를 직접 호출하는 경우를 보자. 예약 요청을 보내기 직전이라는 뜻은 잘 담겨 있다. 하지만 같은 행동을 다른 화면에서도 기록하려면 이름과 속성 표기까지 일일이 맞춰야 한다. ```ts title="Before: 화면이 GA의 전송 방식까지 안다" {4} function handleScheduleSubmit() { gtag("event", "post_schedule_submitted", { mode: "fixed_time", channel_count: selectedChannels.length, // GA에 맞춘 속성 이름이다. }); // 중략 } ``` 이벤트 이름과 필요한 속성을 Zod로 모으고, 화면에는 이 정의를 따르는 `track`을 제공했다. 게시 요청 이벤트 하나만 보면 다음과 같다. ```ts title="analytics-event.ts: 게시 요청 이벤트의 이름과 속성" {9} import { z } from "zod"; const analyticsEventSchema = z.strictObject({ name: z.literal("post_schedule_submitted"), mode: z.enum(["next_available", "fixed_time", "publish_now"]), channelCount: z.int().positive(), // 게시 대상 채널은 한 개 이상이다. }); type AnalyticsEvent = z.infer; ``` `mode`에는 다음 빈 시간·지정 시각·즉시 게시 중 어떤 방식을 골랐는지 담는다. 이름에 오타를 내거나 채널 개수를 빠뜨리면 스키마에서 얻은 타입이 잡아낸다. 전송하기 직전의 값도 같은 스키마로 한 번 더 검사한다. 화면은 GA의 전송 방식을 직접 호출하지 않고, 모여의 `useAnalytics`가 제공하는 인터페이스를 사용한다. ```ts title="After: 화면은 게시 요청을 제출한 사실만 기록한다" {11} function PostComposer() { const analytics = useAnalytics(); // 중략 function handleScheduleSubmit() { // 요청 제출을 기록한다. 외부 SNS의 게시 완료를 뜻하지 않는다. analytics.track({ name: "post_schedule_submitted", mode: "fixed_time", channelCount: selectedChannels.length, }); // 중략 } // 중략 } ``` 이 호출에는 GA의 SDK나 파라미터 이름이 없다. 어떤 분석 도구로 보낼지는 앱을 시작할 때 전송 객체인 `provider`를 넣어 정한다. [의존성 주입](/post/dependency-injection)으로 전송 방법을 밖에서 넣어 주니 화면은 제품의 행동을 기록하는 일만 맡는다. ```ts title="create-analytics.ts: 검증과 전송을 분리한다" {14} interface AnalyticsProvider { track(event: AnalyticsEvent): void; } function createAnalytics(provider: AnalyticsProvider) { return { track(event: AnalyticsEvent) { const result = analyticsEventSchema.safeParse(event); if (!result.success) { return; } try { provider.track(result.data); } catch { // 분석 호출의 실패가 게시나 결제를 막지 않게 한다. } }, }; } ``` GA 구현은 `createAnalytics(googleAnalyticsProvider)`로 넣는다. Amplitude나 Mixpanel로 바꿀 때는 그 도구의 전송 구현만 넣고 화면의 `analytics.track(...)` 호출은 그대로 둔다. 속성 이름의 변환과 사용자 식별·집계 방식은 전송 구현에서 맞춘다. 테스트에는 이벤트를 배열에 담는 가짜 구현을 넣으면 된다. > 위의 `try`는 SDK 호출이 바로 던지는 오류를 처리한다. Promise로 전송하는 구현이라면 비동기 실패도 처리해야 한다. 분석 실패 때문에 게시나 결제가 멈추면 안 되기 때문이다. 여러 이벤트를 정의할 때는 `name`을 기준으로 `discriminatedUnion`에 묶는다. 다만 호출 자체를 빠뜨린 경우는 스키마가 찾지 못하니 제출 흐름의 테스트로 확인한다. 본문·이메일은 보내지 않고 게시 방식과 채널 개수처럼 필요한 값만 남긴다. 오류의 원인은 `reporter`로, 사용자가 어디까지 진행했는지는 `analytics`로 확인한다. 기록을 많이 남기기보다 다음에 무엇을 고칠지 판단할 근거가 있어야 한다. 분석 도구를 바꾸거나 새 흐름을 시험할 때 화면 전체를 다시 고치지 않으려고 이벤트의 의미와 전송 방법을 나눴다. *** ## 마무리 개발하며 가장 보람을 느끼는 순간은 내가 만든 것이 누군가에게 도움이 될 때다. 내게 번거로웠던 일을 줄이려고 만든 기능이 다른 사람의 수고도 덜어 주면 기쁘다. 여러 사이드 프로젝트를 꾸준히 하는 것도 그 즐거움 때문이다. 만드는 사람의 생각과 쓰는 사람의 생각이 늘 같지는 않다. 충분히 고민한 기능도 기대와 다른 반응을 얻으면 이유를 듣고 고쳐야 한다. 모여에서 바꾸기 쉬운 코드를 중요하게 여긴 것도 그래서다. 더 나은 방법을 찾았을 때 기존 구조 때문에 바꾸기를 망설이고 싶지는 않았다. AI로 구현 시간을 줄인 만큼 무엇을 해결할지 고민하는 데 시간을 더 썼다. 사용자의 불편을 듣고 제품을 계속 운영할 방법을 살피다가 업로드나 동기화 문제를 만나면 다시 기술을 깊이 들여다봤다. 여러 분야를 연결하는 제너럴리스트의 시야와 한 문제를 깊이 공부하는 경험이 모두 필요했다. 내가 좋아하는 것은 문제를 알아가고 해결할 방법을 찾는 과정이다. 복잡한 절차를 줄이거나 설명을 바꾸는 것만으로 해결될 때도 있다. 어떤 도구를 쓰든 내가 한 일이 단 한 사람에게라도 도움이 되었으면 좋겠다. 모여도 사용자의 반응을 보며 계속 고쳐 갈 생각이다. 이 글에서 정리한 기준이 다음 변경을 수월하게 만드는지 함께 살펴보려 한다. *** ## 참고자료 [^select]: [TanStack Query의 select](https://tanstack.com/query/latest/docs/framework/react/guides/render-optimizations), [무한 조회의 페이지 구조](https://tanstack.com/query/latest/docs/framework/react/guides/infinite-queries). [^nuqs-search]: [nuqs의 문자열 리터럴 파서](https://nuqs.dev/docs/parsers/built-in#literals), [서버와 파서 공유](https://nuqs.dev/docs/server-side), [shallow 옵션](https://nuqs.dev/docs/options), [Next.js 어댑터](https://nuqs.dev/docs/adapters). [^orpc]: [oRPC 안정판의 OpenAPI 명세 생성](https://v1.orpc.dev/docs/openapi/openapi-specification). [^orval]: [Orval의 React Query 코드 생성](https://orval.dev/docs/guides/react-query/), [MCP 서버 생성](https://orval.dev/docs/guides/mcp/). [^trpc-api]: [tRPC의 SSE subscription](https://trpc.io/docs/server/subscriptions)은 지원되며, 공식 [OpenAPI 패키지](https://trpc.io/docs/openapi)는 2026-10-11 확인 시 alpha다. 현재 생성 명세에는 subscription이 포함되지 않는다. [^orpc-version]: 예제는 작성 당시 모여에 설치된 oRPC 2.0.0-beta.39 기준 문법이다. 안정판 v1과 계약·스트림 API의 표기가 다르다. [v2 변경 안내](https://orpc.dev/docs/migrations/from-v1). [^orpc-sse]: [oRPC의 이벤트 스트림과 검증](https://orpc.dev/docs/async-iterator-object). [^hash]: [Web Crypto digest의 입력 방식](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest), [hash-wasm의 증분 해싱](https://github.com/Daninet/hash-wasm). [^upload-measurement]: 개발 중 기록한 1GiB 파일의 브라우저 비교다. 최대 추가 RSS 중앙값과 해싱 시간을 비교했으며 Long Task는 현재 방식의 5회 관측이다. 기기·브라우저가 달라지면 결과도 달라질 수 있다. [^browser-coordination]: [Web Locks API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API), [Broadcast Channel의 통신 범위](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API). [^postgres-time]: [PostgreSQL의 날짜·시각 타입](https://www.postgresql.org/docs/current/datatype-datetime.html). `timestamptz`는 시점을 UTC로 저장하며 입력에 사용한 원래 시간대는 보존하지 않는다. [^start-hydration]: [TanStack Start의 hydration 오류 가이드](https://tanstack.com/start/latest/docs/framework/react/guide/hydration-errors). 서버와 첫 클라이언트 렌더링에서 언어·시간대·기준 시각을 일치시킨다. [^sse-measurement]: 개발 중 동시에 보이는 5개 창과 이벤트 100개로 확인한 비교다. 연결 교체 중 중첩과 API 미지원 환경을 포함해 모든 순간 연결이 하나라는 뜻은 아니다. [^runtime-time]: [Dockerfile의 ENV](https://docs.docker.com/reference/dockerfile/#env), [PostgreSQL 연결 시작 옵션](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNECT-OPTIONS). 컨테이너 환경 변수와 DB 세션 설정은 각각 지정한다. --- # 계정 털렸다고 욕하던 나, 내 서비스 보안은 챙겼을까? > TanStack Start SSR에서 쿠키 세션 인증을 잇는 방법, HttpOnly·SameSite 쿠키와 CSRF 방어, 동시 세션 5개 제한과 강제 로그아웃, JWT와 DB 세션 비교, Argon2id 비용까지 모여의 구현으로 정리했다. - 원문: https://www.yolog.co.kr/post/did-i-secure-my-service - 카테고리: 개발 - 발행: 2026-10-04 - 수정: 2026-10-14 (이미지: 로그인한 기기와 새 기기 알림을 살펴보는 모여의 인증 이야기) ## 로그인 버튼 뒤에서 고민한 것들 대부분의 서비스는 회원가입과 로그인에서 시작한다. 이메일과 비밀번호만 확인하면 끝날 것 같지만, 막상 구현해 보면 예상하지 못한 허점이 드러나고 고민해야 할 문제도 늘어난다. 새로고침해도 로그인을 유지하려면 어떻게 해야 할까? 누군가 계정을 훔쳤다면, 이미 로그인한 기기를 어떻게 내보낼까? HTTP와 쿠키, 브라우저와 서버가 요청을 주고받는 방식을 알아야 판단할 수 있는 문제다. 최근 [쿠팡의 개인정보 유출](https://m.korea.kr/briefing/policyBriefingView.do?newsId=156766176), [티빙의 침해사고](https://www.korea.kr/briefing/policyBriefingView.do?newsId=156780195), [정부24의 개인정보 유출](https://www.mois.go.kr/frt/bbs/type001/commonSelectBoardArticle.do?bbsId=BBSMSTR_000000000009\&nttId=129804) 소식을 보며 남의 서비스만 탓할 일은 아니라는 생각이 들었다. 이번에 [모여](https://moyeo.io)를 만들면서는 사용자의 계정과 데이터를 어떻게 보호할지 공부하고, 실제 구현에도 반영했다. 완벽한 보안이라고 말할 수는 없지만, 주어진 시간과 비용 안에서 가능한 부분은 최대한 챙기고 싶었다. 계정을 지키는 일은 요금제와도 이어졌다. 모여에는 팀 플랜이 있다. 팀원이 계정 하나를 함께 쓰면 각자의 권한을 나눈 의미도, 요금제를 설계한 전제도 약해진다. (이미지: 하나의 구독 계정을 여러 사람이 공유해도 서비스 운영 비용은 계속 발생한다) 넷플릭스처럼 구독료를 받는 서비스에서 여러 사람이 계정 하나를 공유하면 사용자는 비용을 아낄 수 있다. 하지만 운영자는 이용이 늘어나는 만큼 서버와 데이터베이스 비용을 계속 부담한다. 서비스를 안정적으로 운영하고 더 좋은 콘텐츠와 기능을 제공하려면 이 비용을 감당할 수익이 필요하다. 그래서 요금제를 설계할 때 정한 이용 범위 안에서 서비스가 쓰이도록 관리해야 한다. 계정 공유를 관리하기 위해 활성 세션 수에도 제한을 두었다. 다만 한 사람도 여러 기기와 브라우저를 오가며 사용할 수 있으므로, 세션을 하나만 허용하는 것은 현실적이지 않았다. 이런 사용성을 고려해 **한 계정의 활성 세션을 최대 5개로 제한했다.** > 추후 사용 패턴을 살펴보고, 활성 세션의 최대 개수를 줄이는 방향도 검토할 예정이다. 이 글은 로그인 이후 요청이 오가는 흐름을 중심으로 모여의 인증 설계를 정리한 기록이다. SSR 인증부터 다중 기기 관리와 강제 로그아웃, 서버 확장과 보안에 드는 비용까지 이어서 설명한다. 모여의 프론트엔드는 TanStack Start, 백엔드는 NestJS이고, 둘 사이 통신에는 oRPC를 사용한다. 웹은 Cloudflare Workers에서, API는 AWS EC2에서 실행된다. 이 배치는 뒤에서 인증 요청이 지나는 경로와 비용을 이야기할 때 다시 등장한다. *** ## 한 번 로그인했는데, 다음 요청은 어떻게 알아볼까? 사용자가 노트북에서 모여에 로그인하면 서버는 이메일로 계정을 찾고 비밀번호를 확인한다. 여기까지는 익숙한 과정이다. 그런데 사용자가 다음 화면을 열면 서버에는 새로운 HTTP 요청이 도착한다. 이전에 비밀번호를 확인했다는 사실만으로 이 요청의 주인이 같은 사람이라고 알 수는 없다. 매번 비밀번호를 보내는 대신, 모여는 로그인에 성공했을 때 로그인 기록과 그 기록을 찾을 토큰을 만든다. 서버에 남기는 로그인 기록이 세션이다. 세션에는 사용자의 ID와 유효기간, 종료 여부 같은 정보를 저장한다. 서버는 발급한 토큰을 브라우저에 전달한다. 이후 요청에 그 토큰이 포함되면, 연결된 세션이 여전히 유효한지 확인한다. 아래 도식은 비밀번호로 인증하는 첫 로그인과 토큰으로 세션을 조회하는 이후 요청의 차이를 보여준다. TanStack Start 같은 SSR 프레임워크를 거치는 경우는 뒤에서 따로 다루고, 여기서는 기본 흐름만 본다. 처음 로그인할 때는 비밀번호를 확인하고, 그다음 요청부터는 세션을 조회한다. 화면을 이동할 때마다 비밀번호를 다시 검증하지는 않는다. 모여가 발급하는 값은 Opaque Token(불투명 토큰)이다. 예측하기 어려운 무작위 문자열로, 토큰 자체에는 이메일이나 권한 같은 사용자 정보가 담겨 있지 않다. 서버는 PostgreSQL에 저장된 세션을 조회해 로그인 상태를 확인한다. 인증 코드의 핵심 흐름만 남기면 다음과 같다. `tokenIssuer`는 토큰을 조회용 값으로 바꾸고, `sessions`는 이 값으로 DB의 세션을 찾는다. ```ts title="토큰으로 로그인 상태 확인하기" async function authenticate(rawToken: string, now: Date) { const tokenDigest = tokenIssuer.digestToken(rawToken); if (tokenDigest === null) { return { status: "authentication_required" }; } const record = await sessions.findByTokenDigest(tokenDigest); if (record === null || !record.session.getStatus(now).isActive) { return { status: "authentication_required" }; } return { status: "authenticated", session: record.session }; } ``` 인증 유스케이스를 단순화한 예시. 계정 상태 확인과 최근 사용 기록 갱신은 생략했다. **토큰이 있다는 것과 로그인 상태가 유효하다는 것은 다르다.** 서버가 기록을 확인하므로, 나중에 문제가 생겼을 때 특정 세션만 골라 끝낼 수도 있다. 세션을 서버에서 관리하기로 한 데는 이 점이 가장 컸다. 구현 더 보기: 토큰 저장과 소셜 로그인 ### 브라우저에 줄 값과 DB에 남길 값을 나눈다 브라우저에는 무작위로 만든 토큰을 보내지만, DB에는 그 토큰을 그대로 저장하지 않는다. 토큰을 가진 사람은 해당 세션으로 요청할 수 있으므로, DB에 남기는 값도 구분하고 싶었다. 서버는 비밀 키와 토큰을 HMAC에 넣어 Digest를 계산한다. 같은 키와 같은 토큰을 넣으면 같은 Digest가 나온다. 따라서 다음 요청에서 토큰을 받았을 때도 같은 계산을 하면, DB에 저장한 세션을 찾을 수 있다. 아래 그림은 브라우저에 보관하는 값과 DB에 저장하는 값의 차이를 보여준다. (이미지: 브라우저는 원문 토큰을 보관하고, 서버는 HMAC Digest로 DB의 세션을 찾는다) > Digest는 원본 값을 해시 함수로 계산한 고정 길이의 결과다. HMAC은 이 계산에 비밀 키를 함께 넣는 방식이다. ```ts title="토큰 원문과 저장할 값을 분리하기" const randomToken = randomBytes(32).toString("base64url"); const rawToken = `v${keyring.activeVersion}.${randomToken}`; const tokenDigest = keyring.digestWithActiveSecret(rawToken); return { rawToken, tokenDigest }; ``` 실제 토큰 발급기의 핵심을 변수 이름과 함께 재구성했다. DB에 저장한 Digest를 브라우저의 토큰 대신 쓸 수는 없다. 반대로 브라우저의 원문 토큰이 탈취되면 그 세션으로 요청할 수 있으니, 서버의 HMAC 키와 원문 토큰은 각각 보호해야 한다. ### 키를 바꾸는 것과 토큰을 갱신하는 것은 다르다 모여는 토큰을 32바이트 난수로 만들고, 앞에 사용한 HMAC 키의 버전을 붙인다. 키를 교체한 뒤에도 어떤 키로 Digest를 계산해야 하는지 알기 위한 정보다. 액세스 토큰과 리프레시 토큰을 번갈아 갱신하는 구조와는 관계가 없다. 세션 토큰과 기기 인식 토큰은 같은 HMAC 키를 사용하지만, Digest를 계산할 때 각 토큰의 용도를 구분하는 문자열을 함께 넣는다. 그래서 토큰 원문이 같더라도 용도가 다르면 서로 다른 Digest가 만들어진다. ### 소셜 로그인도 모여의 세션으로 이어진다 Google·Kakao로 로그인해도 마지막에는 모여의 세션을 만든다. 소셜 계정으로 본인을 확인하는 과정이 앞에 추가될 뿐, 이후 요청에서는 같은 방식으로 모여의 세션을 조회한다. 소셜 제공자가 발급한 API 토큰을 그대로 모여의 로그인 토큰으로 쓰지는 않는다. 중간에 오가는 요청과 응답이 정말 같은 로그인 과정인지도 확인해야 한다. 아래 값과 처리가 각각 이 확인을 나눠 맡는다. | 확인하는 값이나 처리 | 확인하려는 것 | | ----------- | -------------------------------------------------- | | `state` | 돌아온 응답이 우리가 시작한 로그인 요청과 연결되는가? | | 브라우저 바인딩 | 로그인을 시작한 브라우저에서 이어지는 요청인가? | | `nonce` | 받은 ID 토큰이 이번 로그인 과정에서 발급된 것인가? | | PKCE | 인가 코드를 가로채더라도 로그인 시작 시 준비한 값 없이 토큰으로 교환하지 못하게 하는가? | | 일회성 처리 | 이미 처리한 로그인 응답을 다시 사용하지 못하게 하는가? | ### 이메일이 같다고 계정을 바로 합치지 않는다 이메일로 가입한 사용자가 같은 주소의 Google 계정으로 로그인하면 어떻게 할까? 주소 문자열만 보고 두 계정을 합치면, 남의 이메일로 소셜 계정을 만든 사람이 기존 계정에 들어올 수 있다. 그래서 소셜 제공자가 그 이메일을 확인했다고 알려 준 경우에만 기존 계정에 자동으로 연결하고 로그인시킨다. 코드에서는 이 판단을 `verifiedEmail`로 받고, 연결과 로그인이 함께 일어난 결과는 일반 로그인과 구분해 `linked_and_signed_in`으로 남긴다. 확인했다는 근거는 제공자마다 다르다. Google은 서명을 검증한 ID 토큰의 `email_verified`와 함께 Gmail 주소인지, Workspace 도메인(`hd`)인지를 보고, Kakao는 `email_verified`를 본다. 확인되지 않은 주소라면 자동 연결도, 새 가입도 하지 않는다. 기존 모여 계정 쪽 이메일도 언제나 확인된 주소다. 이메일로 가입하면 먼저 그 주소로 링크를 보내고, 링크를 연 화면에서 비밀번호와 프로필까지 제출해야 가입이 끝난다. 링크를 여는 것만으로는 가입이 완료되지 않는다. 확인하지 않은 계정이 생기지 않으니, 이메일 확인 여부를 따로 저장할 필요도 없었다. 이렇게 계정 하나에 이메일·비밀번호·소셜 계정이 함께 붙을 수 있으니, 어떤 로그인 방법이 있는지는 `GET /auth/login-methods` 하나로 읽는다. 이메일, 비밀번호 등록 여부, 제공자별 소셜 연결 여부를 한 응답에 담아 화면마다 로그인 수단을 따로 추측하지 않게 했다. *** ## 로그인 정보를 브라우저에 맡겨도 괜찮을까? 브라우저가 토큰을 보관했다면, 다음 요청에는 그 토큰을 담아 서버로 보내야 한다. 모여에서는 토큰을 보관하고 전달하는 데 [쿠키](https://www.yolog.co.kr/post/http-cookie)를 사용한다. 서버가 응답의 [`Set-Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie) 헤더에 토큰을 담아 보내면 브라우저는 이를 쿠키로 저장한다. 이후 조건에 맞는 요청을 보낼 때는 저장한 쿠키를 [`Cookie`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cookie) 헤더에 담아 함께 보낸다. 여기서 쿠키와 세션은 경쟁하는 선택지가 아니다. **세션은 서버의 로그인 기록이고, 쿠키는 그 기록을 찾을 토큰을 보관하고 전달하는 수단이다.** JWT도 쿠키에 넣을 수 있다. 토큰을 가진 사람은 해당 세션으로 요청을 보낼 수 있다. 그래서 JavaScript가 토큰을 직접 읽지 못하게 하고, 쿠키가 전송되는 조건도 제한했다. ```ts title="모여의 세션 쿠키 설정" const cookie = fastifyCookie.serialize(cookieName, rawToken, { httpOnly: true, // JavaScript로 쿠키 값을 읽지 못하게 한다. secure: isSecure, // HTTPS에서만 전달한다. 운영에서는 true다. sameSite: "lax", // 다른 사이트에서 시작한 전송을 제한한다. path: "/", expires: expiresAt, }); responseHeaders.append("set-cookie", cookie); ``` 실제 쿠키 어댑터 설정을 발췌했다. 변수 이름을 정리하고 쿠키 전송 우선순위 옵션은 생략했다. 세 설정이 막는 것은 각각 다르다. | 설정 | 제한하는 것 | 모여에서의 의미 | | -------------- | --------------------------- | -------------------------- | | `HttpOnly` | JavaScript가 쿠키 값을 읽을 수 있는가? | 브라우저의 코드로 토큰을 직접 읽지 못하게 한다 | | `Secure` | 어떤 통신으로 쿠키를 보낼 것인가? | HTTPS 요청에서만 쿠키를 보낸다 | | `SameSite=Lax` | 다른 사이트에서 시작한 요청에도 붙일 것인가? | 쿠키를 보내는 상황을 제한한다 | `HttpOnly`는 악성 스크립트가 쿠키를 읽어 훔쳐 가는 [세션 하이재킹](https://www.yolog.co.kr/post/security-session-hijacking)의 한 경로를 줄인다. 다만 막는 것은 쿠키 값을 읽는 경로 하나뿐이다. [XSS](https://www.yolog.co.kr/post/security-xss)로 실행된 악성 스크립트는 쿠키 값을 읽지 못해도, 사용자의 브라우저에서 인증된 요청을 보낼 수는 있다. 그래서 쿠키 속성과 함께 입력·출력 처리와 요청 검증도 챙겨야 한다. > `SameSite`를 지정하지 않은 쿠키를 어떻게 다룰지는 브라우저마다 다를 수 있다. 그래서 모여는 기본값에 기대지 않고 `SameSite=Lax`를 직접 지정한다. 브라우저별 지원 현황은 [Can I Use](https://caniuse.com/same-site-cookie-attribute)에서 볼 수 있다. 구현 더 보기: 쿠키의 범위와 만료 ### 쿠키를 어느 주소에 보낼지 정한다 운영 쿠키 이름은 `__Host-moyeo-session`이다. 이름 앞의 `__Host-`는 브라우저가 쿠키 설정을 더 엄격하게 확인하도록 하는 접두사다. `Secure`가 있어야 하고, 경로는 `Path=/`이어야 하며, `Domain`을 지정하면 안 된다. 모여는 운영 환경에서 이 조건을 충족하지 못하면 쿠키를 아예 발급하지 않는다. `Domain`을 지정하지 않았으므로 응답을 받은 호스트의 쿠키가 된다. `moyeo.io`에 저장한 쿠키는 `api.moyeo.io` 요청에 붙지 않는다. 두 서버 사이의 전달은 다음 절에서 설명하는 프록시가 맡는다. ### 쿠키가 남아 있어도 로그인은 끝날 수 있다 모여는 `Expires`로 만료일을 지정하므로 브라우저를 닫았다가 열어도 쿠키가 남을 수 있다. 이런 쿠키를 영속 쿠키라고 한다. 반면 만료일을 지정하지 않는 "세션 쿠키"는 보통 브라우저 세션 동안 사용하는 쿠키를 뜻한다. 여기서 말하는 서버의 로그인 기록인 세션과는 다른 의미다. 브라우저가 쿠키를 보관하는 기간과 서버가 로그인을 허용하는 기간도 다르다. 쿠키가 남아 있더라도 서버의 세션이 만료되거나 종료됐다면 인증할 수 없다. *** ## 새로고침해도 로그인은 이어져야 한다 지금까지는 브라우저와 API 서버가 직접 대화하는 것처럼 설명했다. 모여의 실제 요청 경로에는 Cloudflare Workers에서 실행되는 TanStack Start 서버(`moyeo-web`)가 하나 더 있다. 브라우저는 `moyeo.io/api/v1`으로 요청한다. TanStack Start의 서버 라우트가 이 요청을 NestJS API인 `api.moyeo.io`로 중계한다. 이렇게 요청과 응답을 대신 전달하는 역할이 프록시다. oRPC는 공유한 API 계약을 바탕으로 요청을 만드는 통신 계층이며, 실제 인증 정보는 HTTP 헤더로 오간다. ### 로그인 응답은 브라우저까지 돌아와야 한다 NestJS가 로그인을 처리하고 응답에 `Set-Cookie`를 넣었다면, TanStack Start도 이 헤더를 브라우저에 전달해야 한다. 브라우저가 실제로 받는 것은 TanStack Start의 응답이기 때문이다. 아래 도식은 NestJS의 `Set-Cookie` 응답이 TanStack Start를 거쳐 브라우저에 도달하는 과정을 보여준다. 브라우저는 `moyeo.io`의 응답에 포함된 `Set-Cookie`에 따라 쿠키를 저장한다. 이후 `moyeo.io/api/v1`으로 API 요청을 보내면 저장한 쿠키도 함께 전송한다. TanStack Start는 이 쿠키를 포함한 요청을 NestJS로 중계한다. 모여에서는 프록시가 응답을 전달할 때 `Set-Cookie`가 누락되지 않도록 처리했다. 아래 코드의 `isSafeCookie`는 `Domain`·`Secure`·`SameSite` 등의 전달 조건을 확인하는 함수다. ```ts title="로그인 응답의 쿠키 전달하기" const cookies = upstreamHeaders.getSetCookie(); for (const cookie of cookies) { if (!isSafeCookie(cookie, publicUrl)) { throw new Error("API가 안전하지 않은 cookie를 반환했습니다."); } responseHeaders.append("set-cookie", cookie); } ``` 응답 중계 코드의 쿠키 처리 부분을 단순화했다. 다른 응답 헤더와 리다이렉트 검사는 생략했다. ### SSR은 다른 서버 요청을 만든다 로그인한 상태에서 페이지를 새로고침하면, TanStack Start가 페이지를 만들면서 API 데이터를 먼저 조회할 수 있다. 서버에서 HTML을 만드는 이 과정이 SSR이다. 이때 API를 호출하는 주체는 브라우저가 아니라 TanStack Start 서버다. 브라우저의 JavaScript는 `localStorage`를 읽을 수 있지만, SSR 서버는 사용자의 `localStorage`에 접근할 수 없다. `localStorage`에 저장된 값이 페이지 요청에 자동으로 포함되는 것도 아니다. 반면 쿠키는 조건에 맞는 페이지 요청에 함께 전송되므로, SSR 서버가 요청 헤더에서 읽을 수 있다. **페이지 요청에 담긴 쿠키는 API 요청으로 자동 전달되지 않는다.** TanStack Start가 브라우저 요청의 `Cookie`를 읽어 NestJS 요청 헤더에 직접 넣어야 한다. 아래 도식은 두 요청 사이에서 `Cookie`를 전달하는 과정을 보여준다. NestJS는 전달받은 토큰으로 같은 사용자의 세션을 확인한다. TanStack Start는 그 사용자의 데이터를 받아 HTML을 만든다. 브라우저에서 버튼을 눌렀을 때와 SSR에서 데이터를 읽을 때 모두 같은 로그인 기록으로 인증하는 셈이다. 아래 예시는 쿠키를 읽어서 API 클라이언트의 요청 헤더에 넣는 부분만 남겼다. `createApiClient`는 모여에서 oRPC 클라이언트를 만드는 함수다. ```ts title="SSR 요청에 Cookie 전달하기" function createServerApiClient(request: Request, apiOrigin: string) { const headers: Record = {}; const cookie = request.headers.get("cookie"); if (cookie !== null) { headers.cookie = cookie; } return createApiClient({ baseUrl: apiOrigin, // 실제로는 createApiOriginRequest로 헤더를 정리한 뒤 보낸다 fetch: (apiRequest) => fetch(apiRequest), headers, }); } ``` 설명을 위해 단순화한 예시. 실제 코드는 요청을 인자로 받지 않고 서버에서 현재 요청을 읽는다. 서버에서 실행되는 `fetch`는 사용자의 브라우저 쿠키 저장소에 접근할 수 없다. 그래서 `credentials: "include"`를 설정해도 페이지 요청에 담긴 쿠키가 API 요청으로 넘어가지 않는다. 위 코드처럼 들어온 `Cookie`를 읽어 새 요청의 헤더에 직접 넣어야 한다. 실제 코드에서는 이 함수를 TanStack Start의 `createServerOnlyFn`으로 감싸 서버에서만 실행되게 했고, 지금 처리 중인 페이지 요청은 `getRequest()`로 읽는다. ### 프록시를 거치면 느려지지 않을까? 브라우저가 NestJS를 직접 호출하는 것과 비교하면, TanStack Start를 거치는 요청에는 서버 간 호출이 하나 더 생긴다. 중계 처리와 네트워크 왕복에 시간이 들고, 문제가 생길 수 있는 지점도 늘어난다. (이미지: 브라우저의 API 직접 호출과 TanStack Start를 거치는 프록시 경로 비교) 이처럼 프론트엔드에 필요한 요청을 별도 서버에서 처리하고 백엔드와 연결하는 구성을 BFF라고 한다. 모여의 구성도 같은 방향이다. 널리 쓰이는 패턴이라고 중계 비용이 사라지지는 않는다. 게다가 모여에서는 이 한 번이 생각보다 멀다. Worker는 `https://api.moyeo.io`로 API를 호출하고, 이 요청은 Cloudflare Tunnel을 거쳐 서울 리전의 EC2에 도착한다. 2026년 9월에 한국에서 확인해 보니 `moyeo.io`는 서울(ICN)이 아니라 미국 SJC, `api.moyeo.io`는 LAX의 Cloudflare 데이터센터에서 응답했다. Cloudflare에서 Enterprise보다 낮은 요금제의 도메인은 한국 상호접속료 문제로 서울 데이터센터를 쓰지 못하기 때문이다. 결국 한국 사용자의 요청이 태평양을 건너 Worker에 닿고, Worker의 API 호출이 다시 서울 EC2까지 돌아오는 셈이다. Cloudflare가 API 응답을 기다리다 포기하고 523 오류 페이지를 돌려준 적도 있다. 그런데도 이 구성을 고른 건 브라우저의 쿠키를 같은 출처에서 다루고, SSR에서도 같은 세션으로 인증하는 흐름을 하나로 정리하고 싶었기 때문이다. 어차피 SSR로 페이지를 만들 때는 프록시 라우트가 없어도 TanStack Start가 NestJS에서 데이터를 가져와야 한다. 남은 선택은 브라우저의 API 요청까지 같은 중계 경로로 보낼지였다. 경로를 줄일 방법도 있다. Cloudflare Enterprise 요금제, Cloudflare 밖의 서울 진입점, 공개 데이터를 API 왕복 없이 렌더링하는 방식이다. 다만 모두 비용이나 구조를 바꾸는 결정이라, 지금은 흐름을 통일해 두고 서버 간 호출 시간과 NestJS·DB 처리 시간을 나눠 측정하며 이 비용을 확인할 생각이다. ### 여기서 CORS는 어디에 적용될까? 모여의 브라우저는 웹 페이지와 같은 `moyeo.io`의 API 경로를 호출한다. 브라우저가 보는 요청은 같은 출처이고, TanStack Start에서 NestJS로 보내는 요청은 서버 간 요청이다. **서버 간 요청에는 브라우저의 CORS 검사가 적용되지 않는다.** 브라우저가 `api.moyeo.io`를 직접 호출한다면 이야기가 달라진다. `moyeo.io`와 `api.moyeo.io`는 서로 다른 [출처](https://www.yolog.co.kr/post/http-same-origin-policy)이므로 [CORS](https://www.yolog.co.kr/post/http-cors) 설정을 맞춰야 한다. 쿠키를 포함한다면 클라이언트의 전송 옵션과 서버의 허용 출처도 함께 맞춰야 한다. 모여는 기본 호출 경로를 같은 출처 프록시로 맞췄다. 구현 더 보기: 쿠키 중계와 사용자별 SSR 데이터를 섞지 않기 쿠키를 전달할 때는 요청이 가는 길뿐 아니라 응답이 돌아오는 길도 챙겨야 한다. SSR로 페이지를 만들 때는 다른 사용자의 데이터가 섞이지 않는지도 봐야 한다. 아래 그림은 로그인 요청과 응답에서 쿠키가 이동하는 경로, SSR에서 사용자별로 데이터를 나누는 방식을 보여준다. (이미지: 로그인 요청의 Cookie와 응답의 Set-Cookie는 TanStack Start를 거쳐 전달하고, SSR 클라이언트와 캐시는 사용자 요청마다 따로 만든다) ### 요청을 넘기기 전에 헤더를 정리한다 TanStack Start는 받은 요청을 그대로 NestJS에 넘기지 않는다. `createApiOriginRequest`에서 허용된 API 경로인지 확인하고, 다음 서버로 전달하면 안 되는 헤더를 제거한다. `Host`는 실제 호출할 API 주소에 맞게 바꾸고, 요청이 거쳐 온 주소를 알리는 헤더도 다시 설정한다. 브라우저 요청에 담긴 `Origin`은 NestJS가 요청의 출처를 검사할 수 있도록 유지한다. SSR에서 만드는 API 요청에도 같은 함수를 사용한다. 이렇게 정리한 요청을 보낼 API 주소는 `INTERNAL_API_ORIGIN`에 담는다. 이름은 내부 주소처럼 보이지만 운영 값은 공개 주소인 `https://api.moyeo.io`다. Worker가 AWS 내부망 밖에서 실행되므로, 앞에서 본 것처럼 Cloudflare와 Tunnel을 거쳐 NestJS를 호출한다. ### 로그인 응답과 SSR 조회는 역할이 다르다 로그인 응답은 브라우저에 새 쿠키를 저장시키는 과정이다. NestJS가 쿠키를 여러 개 보내면 TanStack Start도 `Set-Cookie` 헤더를 각각 전달한다. 쿠키의 만료일인 `Expires`에도 쉼표가 들어가므로, 여러 쿠키를 쉼표로 이어 붙이면 어디까지가 하나의 쿠키인지 잘못 해석될 수 있다. 예를 들어 쿠키 두 개를 보내는 응답은 다음과 같다. 첫 번째 줄의 `Wed,` 뒤에 있는 쉼표는 쿠키를 구분하는 문자가 아니라 날짜의 일부다. ```http title="쿠키 두 개는 각각의 Set-Cookie 헤더로 보낸다" Set-Cookie: session=example; Expires=Wed, 21 Oct 2026 07:28:00 GMT; Path=/; Secure; HttpOnly Set-Cookie: device=example; Path=/; Secure; HttpOnly ``` 쿠키 이름과 값은 설명용 예시다. 이를 하나의 문자열로 합친 뒤 쉼표로 나누면 어떻게 될까? 쿠키는 두 개인데, 날짜까지 잘려 세 조각이 된다. ```ts title="쉼표로 합치고 나누면 날짜까지 잘린다" const cookies = [ "session=example; Expires=Wed, 21 Oct 2026 07:28:00 GMT", "device=example", ]; const merged = cookies.join(", "); const pieces = merged.split(","); console.log(pieces); // [ // "session=example; Expires=Wed", // " 21 Oct 2026 07:28:00 GMT", // " device=example" // ] ``` 문제가 생기는 처리의 예시. 날짜 외의 쿠키 속성은 생략했다. 그래서 앞의 중계 코드에서는 `getSetCookie()`로 쿠키를 각각 읽고, `append()`로 헤더를 하나씩 추가했다. 합친 문자열에서 쿠키의 경계를 다시 찾을 필요가 없다. 또 중계한 응답에는 인증 응답인지와 관계없이 모두 [`Cache-Control: no-store`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)를 설정해, 사용자별 응답이 캐시에 남지 않게 한다. SSR 조회는 이미 로그인한 사용자의 데이터를 가져와 HTML을 만드는 과정이다. 페이지 요청의 `Cookie`는 NestJS에 보내지만, NestJS가 응답에 넣은 `Set-Cookie`를 페이지 응답에 자동으로 옮겨 주지는 않는다. **API에 쿠키를 보내는 처리와 브라우저에 새 쿠키를 돌려주는 처리는 별개다.** 모여에서도 로그인 응답 중계와 SSR 데이터 조회를 각각 구현했다. ### A의 데이터가 B의 페이지에 들어가면 안 된다 SSR 서버는 여러 사용자의 요청을 동시에 처리한다. 이때 사용자 정보가 들어 있는 클라이언트나 캐시를 하나로 공유하면, A의 쿠키로 요청하거나 A의 데이터를 B의 페이지에 넣을 위험이 있다. 그래서 모여는 SSR 요청마다 API 클라이언트와 데이터 캐시인 `QueryClient`를 새로 만든다. A와 B가 동시에 새로고침해도 각자의 쿠키로 데이터를 조회하고, 각자의 캐시에 저장한다. 브라우저 안에서는 클라이언트를 재사용하되, SSR 서버에서는 여러 사용자가 이런 객체를 공유하지 않게 했다. 두 요청을 동시에 처리하는 테스트로 쿠키와 캐시가 섞이지 않는지도 확인한다. 코드로 옮기면 다음과 같다. 앞서 본 `createServerApiClient`도 이 안에서 함께 호출해, 각 요청의 쿠키를 읽게 한다. ```ts title="SSR 요청마다 클라이언트와 캐시 만들기" import { QueryClient } from "@tanstack/react-query"; function createSsrContext(request: Request, apiOrigin: string) { const api = createServerApiClient(request, apiOrigin); const queryClient = new QueryClient(); return { api, queryClient }; } ``` 모여의 요청별 분리를 설명하기 위해 재구성했다. 라우터 연결과 캐시 설정은 생략했다. A의 요청과 B의 요청에서 이 함수를 각각 호출하면 서로 다른 객체가 만들어진다. SSR 서버 전체에서 쓸 `QueryClient` 하나를 함수 밖에 만들어 두고 공유하는 것과는 다르다. ### 브라우저가 API를 직접 호출한다면? 앞에서 말했듯 브라우저가 `api.moyeo.io`를 직접 호출하는 구성이라면 CORS 설정을 맞춰야 한다. 이때 사용자 정의 헤더 등을 보내면 브라우저는 실제 요청에 앞서 `OPTIONS` 요청으로 서버가 해당 요청을 허용하는지 먼저 확인할 수 있다. 이것이 preflight이며, 이 사전 확인 요청에는 쿠키를 보내지 않는다. 쿠키를 포함하는 실제 요청을 허용하려면, API 서버는 허용할 출처를 구체적으로 지정해야 한다. 모든 출처를 뜻하는 `*`로 처리할 수는 없다. 브라우저에 `credentials: "include"`를 설정해도 쿠키의 호스트와 `SameSite` 조건은 그대로 적용된다. 이 차이는 앞서 작성한 [CORS 글](https://www.yolog.co.kr/post/http-cors)에서 더 자세히 정리했다. *** ## 쿠키가 있다고 모든 요청을 믿을 수는 없다 브라우저가 쿠키를 자동으로 보내면 로그인 상태를 유지하기는 편하지만, 이를 이용한 공격도 가능해진다. 사용자가 로그인한 브라우저에서 외부 사이트를 열었는데, 그 사이트가 사용자가 의도하지 않은 변경 요청을 보내게 한다면 어떨까? 서버가 쿠키만 확인하면 사용자의 정상 요청으로 오해할 수 있다. 이것이 [CSRF](https://www.yolog.co.kr/post/security-csrf)가 노리는 상황이다. (이미지: 악성 사이트가 로그인된 브라우저에 변경 요청을 유도하고, 쿠키만 확인하는 서비스가 이를 정상 요청으로 오해하는 CSRF의 흐름) 앞에서 본 CORS와도 다르다. CORS는 다른 출처의 응답을 브라우저의 코드가 읽을 수 있는지 다룬다. 서버가 요청을 처리해도 되는지 판단하는 인증과 권한 검사를 대신하지 않는다. **변경 요청에서는 요청의 출처도 확인한다.** 모여는 [`Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Origin)으로 어느 출처에서 시작된 요청인지 확인한다. 모여 클라이언트가 넣는 표시 헤더도 검사하고, 브라우저가 다른 사이트에서 시작한 요청이라고 알렸다면 거부한다. 쿠키로 사용자를 확인하는 것과 별도로 검사하는 조건이다. 허용한 출처에서 왔다는 사실만으로 사용자가 누구인지 알 수 없고, 유효한 세션이 있다는 사실만으로 의도한 변경 요청인지 알 수 없다. 앞에서 설정한 `SameSite` 쿠키도 이 검사와 겹쳐 쓰는 방어다. 구현 더 보기: 변경 요청의 출처 검사 아래는 실제 정책 함수를 읽기 쉽게 정리한 예시다. 이 검사는 데이터를 바꾸는 요청을 대상으로 한다. `GET`·`HEAD`·`OPTIONS`는 제외하고, 그 외 메서드에서는 요청의 출처와 표시 헤더를 확인한다. 제외된 메서드도 로그인과 작업 권한은 그대로 검사한다. ```ts title="변경 요청을 허용할 조건" if (SAFE_METHODS.has(method)) { return true; } if (origin === undefined || !allowedOrigins.has(origin)) { return false; } if (fetchSite === "cross-site") { return false; } if (clientHeader !== TRUSTED_CLIENT_HEADER_VALUE) { return false; } return true; ``` 변경 요청 검사 정책을 명시적인 조건문으로 재구성했다. 사용자 인증은 별도로 수행한다. 클라이언트 표시 헤더는 "모여 클라이언트가 보내는 요청"이라는 표시로 사용하는 공개된 고정값이다. 비밀 키나 로그인 토큰은 아니다. 다른 사이트의 브라우저 코드가 이 헤더를 붙여 요청하려면 CORS 검사도 통과해야 하므로, 서버의 `Origin` 검사와 함께 사용한다. 브라우저 밖에서 요청을 만드는 프로그램은 이 헤더를 직접 넣을 수 있다. 따라서 표시 헤더가 있다고 정상 사용자라고 믿지는 않는다. 실제 사용자와 작업 권한은 세션을 확인한 뒤 별도로 판단한다. *** ## 여섯 번째 기기에서 로그인하면 어떻게 될까? 사용자가 노트북에 이어 휴대전화에서도 로그인하면 또 하나의 세션이 생긴다. 모여는 한 계정에서 동시에 활성 상태인 세션을 5개까지 허용한다. 이 제한은 기기 자체가 아니라 활성 세션의 수를 기준으로 한다. 같은 노트북에서도 Chrome과 Safari를 쓰면 서로 다른 세션이 될 수 있다. 사람 수를 정확히 판별하는 기능은 아니지만, 계정 하나를 무제한으로 함께 쓰는 것을 어렵게 만드는 정책이다. 5개가 찬 뒤 새 기기에서 로그인하면 어떻게 할까? 모여는 **새 로그인을 허용하고, 최근 사용 기록이 가장 오래된 기존 세션을 종료한다.** 새 기기에서 로그인할 때마다 예전 기기를 찾아 로그아웃해야 하는 불편을 줄이고 싶었다. 아래 예시는 노트북 Chrome을 다시 사용한 뒤 새 기기로 로그인하는 상황을 보여준다. 최근 사용 기록이 갱신되면서 어떤 세션이 교체 대상으로 남는지 확인할 수 있다. 노트북 Chrome을 최근에 사용했다면 그 세션을 남기고, 그다음으로 사용 기록이 오래된 세션을 끝낸다. 무조건 로그인한 순서대로 밀어내는 방식은 아니다. 결과적으로 새 로그인은 성공하고 활성 세션은 5개를 유지한다. 교체 정책을 간단히 표현하면 다음과 같다. 여기서 `activeSessions`는 사용할 수 있는 기존 세션들이고, 새 세션을 추가하기 전에 교체 대상을 고른다. ```ts title="새 로그인을 위해 교체할 세션 고르기" const maximumSessions = 5; const replaceCount = activeSessions.length - maximumSessions + 1; const sessionsToReplace = []; if (replaceCount > 0) { const oldestFirst = activeSessions.toSorted((left, right) => { return left.lastSeenAt.getTime() - right.lastSeenAt.getTime(); }); for (const session of oldestFirst.slice(0, replaceCount)) { sessionsToReplace.push(session.id); } } ``` 세션 교체 정책을 단순화한 예시. 동률일 때의 순서와 동시성 처리는 아래 구현 설명에서 다룬다. ### 새 기기 로그인은 이메일로 알려 준다 낯선 기기에서 로그인했을 때 사용자가 알아차릴 수 있어야 한다. 그렇다고 같은 브라우저로 로그인할 때마다 메일을 보내면 금방 무시하게 된다. 그래서 세션 쿠키와 별도로 기기 인식 쿠키를 두었다. 전에 본 브라우저인지 판단하는 용도이며, **기기 인식 쿠키만으로 로그인할 수는 없다.** (이미지: 새 기기 로그인 안내 메일 본문 예시) 이전에 로그인한 기록이 있는 사용자에게 새 기기 로그인이 확인되면, 서버는 발송 조건을 확인한 뒤 안내 메일을 보낸다. 메일에는 로그인 시각과 브라우저·운영체제를 적고, 본인이 아니라면 보안 설정에서 다른 기기를 로그아웃시키고 비밀번호를 바꾸도록 안내한다. 화면 예시는 실제 안내를 바탕으로 개인정보 영역을 제외해 정리했다. 구현 더 보기: 팀 권한, 동시 로그인과 새 기기 알림 ### 팀 기능을 쓸 권한과 계정 공유는 다른 문제다 팀 기능을 허용할 때는 요금제만 확인하지 않는다. 사용자의 역할과 작업하려는 리소스도 함께 확인한다. 이런 속성 기반 판단이 ABAC이다. 다만 권한을 잘 나눠도 모든 팀원이 계정 하나를 공유하면 서버는 같은 사용자로 보게 된다. 그래서 팀 권한과 계정 공유 정책을 함께 고민했다. ### 최근 사용 기록은 요청마다 저장하지 않는다 교체할 세션은 DB에 기록된 최근 사용 시각인 `lastSeenAt`으로 고른다. 값이 같으면 발급 시각을 비교하고, 그 값도 같으면 ID로 순서를 정한다. 사용자가 요청할 때마다 사용 시각을 저장하면 DB에 쓰는 작업도 계속 늘어난다. 그래서 마지막 갱신 이후 최소 15분이 지났을 때 다시 기록한다. 교체 대상을 고를 때도 모든 요청의 정확한 시각이 아니라, DB에 남아 있는 최근 기록을 기준으로 삼는다. 갱신 여부를 판단하는 조건만 남기면 다음과 같다. 두 시각의 차이를 구하고, 15분 이상 지났는지 확인한다. ```ts title="최근 사용 시각을 다시 기록할지 판단하기" function shouldUpdateLastSeen(lastSeenAt: Date, now: Date) { const minimumInterval = 15 * 60 * 1_000; const elapsed = now.getTime() - lastSeenAt.getTime(); return elapsed >= minimumInterval; } ``` 실제 세션 기록 갱신 정책의 시간 조건을 단순화했다. 시각 검증과 DB 갱신은 생략했다. 10시에 기록했다면 10시 1분 요청에서는 다시 쓰지 않고, 10시 15분 이후에 요청이 들어왔을 때 갱신한다. 따로 도는 예약 작업 없이 요청이 들어올 때 판단한다. 기록을 갱신하지 않는 요청에서도 세션이 유효한지는 확인한다. ### 동시에 로그인하면 둘 다 마지막 한 자리를 차지할 수 있다 활성 세션이 4개인 계정에 로그인 두 건이 동시에 들어왔다고 해 보자. 두 요청이 각각 세션 수를 확인하면 둘 다 "하나 더 만들어도 된다"고 판단할 수 있다. 이후 세션을 하나씩 만들면 활성 세션이 6개가 된다. 확인할 때는 맞았던 조건이 다른 요청의 처리 때문에 바뀌는 문제가 **경쟁 조건**이다. 모여는 DB에서 해당 계정의 사용자 행을 잠가 같은 계정의 로그인 처리가 순서대로 진행되게 했다. 첫 요청이 5번째 세션을 만들면, 다음 요청은 5개가 된 상태를 확인한다. 그리고 오래된 세션 하나를 끝낸 뒤 새 세션을 만든다. 잠그는 범위는 해당 계정 하나라서, 다른 계정의 로그인은 기다리지 않는다. 아래 그림은 두 처리 방식의 차이를 보여준다. (이미지: 같은 계정의 로그인 두 건을 순서대로 처리해 활성 세션을 5개로 유지한다) 코드에서는 기존 세션 종료와 새 세션 생성, 알림 기록을 하나의 트랜잭션으로 묶었다. 트랜잭션은 여러 DB 변경을 모두 반영하거나, 중간에 실패하면 함께 되돌리는 처리 단위다. 기존 세션만 종료되고 새 로그인은 저장되지 않는 상황을 피하기 위한 것이다. ```ts title="한 계정의 로그인 처리 순서" await database.transaction(async (transaction) => { await lockUser(transaction, userId); const sessions = await lockActiveSessions(transaction, userId); const replacedIds = selectSessionsToReplace({ activeSessions: sessions, maximumActiveSessionCount: 5, }); await revokeSessions(transaction, replacedIds); await insertSession(transaction, newSession); await recordDeviceNotice(transaction, newSession); }); ``` 실제 세션 생성 트랜잭션을 설명하기 위해 재구성한 예시다. 실제로는 잠근 뒤 계정이 이용 가능한 상태인지도 다시 확인한다. 통합 테스트에서도 로그인 기록이 없는 계정에 요청 7개를 동시에 보내는 경우를 확인했다. 로그인 7건은 성공하고, 세션 2개가 종료돼 활성 세션은 5개가 남는다. ### 로그인은 먼저 끝내고, 안내 메일은 따로 보낸다 기기 인식 쿠키인 `__Host-moyeo-device`는 180일 동안 보관한다. 새 계정의 첫 로그인이나 이미 알고 있는 기기에는 새 기기 안내를 보내지 않는다. 기기 인식 정보가 없는 경우도 이 알림 정책에서 제외한다. 메일을 받을 이메일과 언어 정보가 있는지도 확인한다. 메일 서버가 느리다고 로그인까지 기다리게 하고 싶지는 않았다. 그래서 로그인할 때는 세션과 함께 "이 메일을 보내야 한다"는 기록만 DB에 남긴다. 메일 발송은 별도 작업이 맡고, 같은 사용자와 기기에 대한 중복 발송이나 재시도, 전달 결과도 관리한다. *** ## 문제가 생겼을 때 로그인을 끝낼 수 있어야 한다 새 기기 로그인 메일을 받은 사용자가 "이건 내가 아닌데?"라고 생각했다면, 직접 다른 기기의 로그인을 끝낼 수 있어야 한다. 모여의 보안 설정에서는 다른 기기를 로그아웃시킬 수 있다. 운영자에게도 사용자 문의나 악성 이용에 대응할 수단이 필요해, 모든 기기 로그아웃과 이용 제한 기능을 따로 만들었다. (이미지: 운영자 화면의 계정 관리 기능 예시) 화면은 실제 계정 관리 영역을 바탕으로 정리한 예시다. 로그아웃 버튼은 **서버에 저장된 세션을 종료한다.** 브라우저의 쿠키는 그대로 남는다. 브라우저가 다음 요청을 보내면 서버는 해당 세션이 종료됐음을 확인하고 인증을 거부한다. 아래 도식은 운영자가 세션을 종료한 뒤, 브라우저에 남아 있는 쿠키로 보낸 요청이 서버에서 거부되는 과정을 보여준다. 클라이언트는 세션이 종료됐다는 응답을 받으면 사용자를 로그인 화면으로 안내한다. 운영자가 버튼을 누르는 순간 모든 브라우저가 닫히거나 이미 실행 중인 작업이 취소되는 것은 아니다. 모든 기기 로그아웃만 했다면 다시 로그인할 수 있다. 재로그인까지 막아야 할 때는 계정 이용 제한을 따로 적용한다. ### 비밀번호를 바꿀 때는 어느 기기를 남길까? 사용자가 현재 비밀번호를 확인하고 바꾸는 경우에는 지금 사용 중인 세션을 유지하고 다른 세션을 끝낸다. 비밀번호를 잊어 재설정 링크로 바꾸는 경우에는 모든 세션을 끝낸다. | 조치 | 지금 사용 중인 기기 | 다른 기기 | | ---------------- | ----------- | --------- | | 다른 기기 모두 로그아웃 | 유지 | 다시 로그인 필요 | | 현재 비밀번호를 확인하고 변경 | 유지 | 다시 로그인 필요 | | 재설정 링크로 비밀번호 변경 | 다시 로그인 필요 | 다시 로그인 필요 | | 운영자의 모든 기기 로그아웃 | 다시 로그인 필요 | 다시 로그인 필요 | ### 로그인 유지와 본인 재확인은 다른 시간이다 로그인 상태를 오래 유지하더라도 민감한 작업에는 본인 확인을 다시 요구할 수 있다. 모여는 이 시간을 구분했다. | 기준 | 기본값 | 사용자에게 일어나는 일 | | ---------- | -------- | ----------------------------------- | | 세션의 최대 수명 | 발급 후 30일 | 계속 사용했어도 다시 로그인 | | 사용하지 않은 기간 | 7일 | 최근 사용 기록이 갱신되지 않으면 다시 로그인 | | 최근 본인 확인 | 15분 | 다른 기기 로그아웃·이메일 변경 등 중요한 작업 전에 다시 확인 | 15분이 지나도 로그인은 그대로 유지된다. 페이지를 읽는 것과 계정·결제 설정을 바꾸는 것은 영향이 다르므로, 중요한 작업을 실행할 때 최근에 본인 확인을 했는지 다시 검사한다. 누군가 열려 있는 브라우저를 잠깐 사용하더라도 중요한 조치를 그대로 실행하지 못하게 하려는 구분이다. 모여에서 실제로 최근 본인 확인을 요구하는 작업은 다음과 같다. 같은 작업이라도 최근 확인이 아직 유효하면 매번 확인 창을 띄우지는 않는다. | 영역 | 최근 본인 확인을 요구하는 작업 | | ------ | ---------------------------------------------------- | | 세션 관리 | 다른 기기 모두 로그아웃 | | 계정 | 이메일 변경 요청, 회원 탈퇴 요청 | | 로그인 수단 | 비밀번호 로그인 등록, 소셜 계정 연결·해제 | | 워크스페이스 | 소유권 이전, 워크스페이스 종료 | | 채널 | 새 채널 연결, 기존 채널 재인증 | | 결제 | 요금제 변경, 구독 해지·즉시 해지, 결제수단 등록, 쿠폰 사용 | | 운영자 조치 | 사용자 세션 종료·이용 제한·제한 해제·플랫폼 역할 변경, 쿠폰 관리·환불 처리·공지 변경 등 | 아래 그림은 이런 작업의 예시와 본인 확인 이후 처리 흐름을 보여준다. 확인에는 계정에서 사용할 수 있는 비밀번호나 연결된 소셜 계정을 사용한다. 본인 확인을 마쳤더라도 서버는 작업 권한과 실행 조건을 다시 검사한다. (이미지: 모여의 중요한 작업은 최근 본인 확인이 만료되면 비밀번호나 연결된 소셜 계정으로 확인하고, 서버가 권한과 조건을 다시 검사한다) 비밀번호 변경은 앞의 표와 처리 방식이 조금 다르다. 최근 본인 확인이 유효한지만 보고 허용하지 않고, 사용자가 입력한 현재 비밀번호를 직접 검증한다. 변경에 성공하면 현재 세션의 본인 확인 유효기간도 갱신한다. 구현 더 보기: 운영자 권한과 로그아웃 이후 정리 ### 버튼이 보인다고 조치를 허용하지 않는다 운영자 버튼을 숨기는 것만으로는 권한을 보호할 수 없다. 모여는 서버에서 요청한 사람이 해당 조치를 할 수 있는지 확인한다. DB에서 대상을 잠근 뒤에도 운영자의 권한과 계정 상태를 다시 확인한다. 처음 확인한 뒤 실제로 변경하기 전까지 상태가 바뀔 수 있기 때문이다. 조치를 제한한 보호 대상인지, 앞서 읽은 정보가 다른 변경으로 오래된 상태가 되지는 않았는지도 검사한다. 조치를 실행하면 사유와 처리 이력을 남겨 나중에 누가 무엇을 했는지 확인할 수 있게 한다. ### 민감한 요청은 본인 확인 뒤 다시 처리한다 예를 들어 다른 기기 로그아웃 요청에서 최근 본인 확인이 만료됐다면, 서버는 바로 세션을 종료하지 않고 추가 확인이 필요하다는 응답을 보낸다. 로그인은 유효해도 본인 확인 시간이 지났다면 기다리게 하는 것이다. 서버 코드로 보면 조건 하나다. ```ts title="로그인 중이어도 본인 확인이 만료됐다면 기다린다" if (principal.freshAuthenticationExpiresAt <= now) { return { status: "fresh_authentication_required" }; } return repository.revokeOthers({ userId: principal.userId, currentSessionId: principal.sessionId, revokedAt: now, reason: SessionRevocationReason.revokedOtherSessions(), }); ``` 실제 다른 기기 로그아웃 유스케이스의 조건을 단순화했다. DB의 재검사와 오류 처리는 생략했다. 브라우저는 이 응답을 받아 확인 화면을 띄운다. 비밀번호 확인처럼 현재 화면에서 인증을 마치면 원래 요청을 한 번만 다시 보내고, 취소했다면 작업을 진행하지 않는다. 소셜 계정으로 확인하는 경우에는 외부 로그인 화면을 거쳐 돌아오므로, 원래 작업 화면에서 다시 진행하도록 안내한다. 이 흐름은 oRPC 클라이언트의 인터셉터 하나가 맡는다. 확인 창을 띄우는 브라우저 처리라서 SSR에서는 함께 쓰지 않는다. ```ts title="본인 확인 뒤 원래 요청을 한 번만 다시 보내기" const freshAuthenticationInterceptor = async ({ next }) => { try { return await next(); } catch (error) { // 본인 확인이 필요하다는 오류가 아니면 그대로 넘긴다 if (!isApiError(error, "FRESH_AUTHENTICATION_REQUIRED")) { throw error; } // 확인 창을 띄우고 사용자의 선택을 기다린다 const result = await requests.request(); if (result === "canceled") { throw new FreshAuthenticationCanceledError(); } // try 밖에서 다시 보내므로, 또 실패하면 재시도 없이 오류로 끝난다 return await next(); } }; ``` 실제 재인증 인터셉터를 단순화했다. 타입과 확인 창 등록 코드는 생략했다. 다시 보낸 요청이라고 그대로 통과시키지는 않는다. 서버는 실제 변경 시점에 본인 확인 상태와 작업 조건을 다시 검사한다. 비밀번호 재설정 링크도 여러 번 쓸 수 없게 했다. 토큰이 재설정용인지, 이미 사용됐는지, 발급 후 비밀번호가 바뀌지는 않았는지 확인한다. 토큰을 사용 처리하는 작업과 비밀번호 변경, 모든 세션 종료를 같은 트랜잭션으로 묶는다. ### 로그아웃 뒤에는 캐시와 알림 연결도 정리한다 세션을 종료할 때는 그 세션에 연결된 브라우저 푸시 알림 구독인 WebPush도 같은 트랜잭션에서 정리한다. 클라이언트가 세션 종료 응답을 받으면 사용자 데이터를 담은 `QueryClient` 캐시를 비우고 로그인 화면으로 안내한다. 같은 브라우저에서 다른 계정으로 로그인했을 때 이전 계정의 데이터가 남아 보이지 않게 하기 위해서다. 탭을 여러 개 열어 둔 경우도 챙겼다. 한 탭에서 로그아웃하면 쿠키는 브라우저 전체에서 사라지지만, 다른 탭 화면에는 로그인한 상태의 데이터가 그대로 남는다. 그래서 로그아웃한 탭은 [`BroadcastChannel`](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel)로 다른 탭에 알리고, 로그인한 화면을 보던 탭만 같은 정리를 따라 한다. 이 알림은 `useSignedOutBroadcast`가 주고받는다. 한 탭 안에서도 비슷한 일이 생긴다. 화면 데이터를 가져오는 Query 캐시와 실시간 변경을 받는 SSE 연결이 같은 순간에 세션 만료 오류를 받으면, 캐시 정리와 로그인 화면 이동이 두 번 일어날 수 있다. 그래서 `createSessionRecovery`는 진행 중인 복구가 있으면 같은 Promise를 돌려줘, 재검증과 이동을 한 번만 실행한다. ```ts title="세션 복구를 한 번만 실행하기" function createSessionRecovery(run) { let pending; return { recover: (failure) => { // 이미 복구 중이면 새로 시작하지 않고 같은 Promise를 기다린다 pending ??= Promise.resolve(run(failure)).finally(() => { pending = undefined; }); return pending; }, }; } ``` 실제 세션 복구 함수에서 타입과 내부 함수를 덜어 냈다. *** ## 서버가 늘어나면 JWT가 더 나을까? 여기까지 보면 모여의 인증은 서버의 로그인 기록을 자주 확인한다. 그러면 "서버가 늘어나면 세션을 관리하기 어렵지 않을까? JWT를 쓰는 게 낫지 않을까?"라는 질문이 생긴다. 먼저 서버 한 대의 CPU와 메모리를 키우는 것이 Scale Up, 서버 개수를 늘려 요청을 나누는 것이 Scale Out이다. 세션을 여러 서버가 어떻게 공유할지는 주로 Scale Out에서 고민하게 된다. (이미지: Scale Up은 서버 한 대의 CPU와 메모리를 늘리고, Scale Out은 여러 서버로 요청을 나누며 공유 DB에서 같은 세션을 확인한다) 2026년 10월 기준 모여의 API는 EC2 한 대에서 실행되고, 세션은 API 서버의 메모리가 아니라 PostgreSQL에 저장한다. 그래서 나중에 API 서버를 A와 B로 나눠도, 그림 오른쪽처럼 같은 DB를 조회해 같은 로그인 기록을 확인할 수 있다. A에서 로그인한 사용자의 다음 요청을 꼭 A로 보내지 않아도 된다. JWT는 토큰 안에 사용자 ID나 만료 시각 같은 정보를 담고, 서명을 붙인다. 서버는 서명으로 토큰이 위조되거나 바뀌지 않았는지 확인하고, 발급자·사용 대상·만료 시각 등도 검사한다. 토큰 자체만 검증해 인증하는 구성이라면 요청마다 중앙 세션 저장소를 조회하지 않아도 된다. 그래서 여러 서비스가 같은 토큰을 받아 검증해야 할 때 유용하다. 아래 그림은 두 방식에서 서버가 무엇을 확인하는지 비교한다. 두 토큰 모두 쿠키로 전달할 수 있다. 차이는 쿠키를 사용하는지보다, **현재 로그인 상태를 DB에서 확인하는지, 토큰에 담긴 정보를 검증하는지에 있다.** (이미지: 공유 DB 세션은 API 서버마다 DB의 현재 세션 상태를 조회하고, JWT는 각 서버에서 토큰을 검증한다. 별도 상태 조회가 없는 JWT는 로그아웃 조치를 알 수 없다) 모여에서는 운영자가 로그인을 끝냈을 때 그 조치를 다음 요청부터 반영할 수 있어야 했다. 두 방식은 바로 여기서 갈린다. 아래 움직이는 도식은 같은 로그아웃 조치 이후 두 방식이 다음 요청을 어떻게 처리하는지 보여준다. JWT 쪽은 아직 만료되지 않은 토큰이며, 별도로 로그아웃 상태를 조회하지 않는 경우다. 공유 DB 세션에서는 어느 API 서버로 요청하더라도 종료된 기록을 보고 거부할 수 있다. 반면 JWT의 서명과 만료만 검사하면 운영자가 방금 한 조치를 알 수 없다. JWT가 틀린 방식이라는 뜻은 아니다. 무엇을 매 요청에 확인할지 선택하면 그에 따른 장점과 비용이 생긴다. | 방식 | 얻는 것 | 감당할 비용 | | ----------------- | ---------------------- | -------------------------------------- | | 공유 DB 세션 | 어느 서버에서든 현재 로그인 기록을 확인 | 요청마다 DB를 조회하며, DB 장애에도 대비해야 한다 | | 세션 조회 없는 JWT | 중앙 저장소를 조회하지 않고 토큰을 검증 | 서명 검증 비용과 전송 크기, 만료 전 로그아웃 반영을 고려해야 한다 | | Redis 등 공유 세션 저장소 | 메모리 기반으로 세션을 빠르게 조회 | 별도 저장소의 메모리 비용과 장애·데이터 보존 정책을 관리해야 한다 | **모여에서는 로그인 상태를 바꿀 수 있다는 점이 중요했다.** 기기 제한, 사용자·운영자의 로그아웃, 비밀번호 변경 뒤 다른 기기 정리를 이미 사용하는 DB에서 처리할 수 있었다. 그래서 공유 DB 세션을 선택했다. 서버 대수가 늘어나도 같은 DB를 보면 되므로, 그것만으로 이 선택을 바꿀 이유는 없다. 더 살펴보기: 서버 간 세션 공유와 JWT의 로그아웃 처리 ### 서버 A가 기억한 로그인을 서버 B도 알아야 한다 세션을 서버 A의 메모리에만 저장하면 서버 B는 그 로그인 기록을 모른다. 서버 A를 재시작하면 기록이 사라질 수도 있다. 따라서 로그인한 서버에 다음 요청도 보내거나, 여러 서버가 같은 저장소를 보도록 해야 한다. 서버 한 대의 메모리를 키우는 것만으로는 이 문제가 해결되지 않는다. 공유 DB를 쓰면 기록을 함께 볼 수 있지만, 조회가 늘어나는 만큼 DB 연결과 검색 비용도 든다. 만료된 세션을 정리하는 작업도 필요하다. 모여가 최근 사용 시각을 최소 15분 간격으로 기록하는 것은 요청마다 DB에 쓰는 작업까지 늘어나는 것을 줄이기 위해서다. Redis를 추가한다면 메모리에서 빠르게 조회할 수 있는 장점이 있다. 대신 저장소가 멈췄을 때 어떻게 할지, 데이터를 어디까지 보존할지, 동시에 들어온 로그인 수를 어떻게 제한할지도 새로 관리해야 한다. ### 토큰 갱신을 막아도 이미 발급한 토큰은 남는다 JWT도 강제 로그아웃을 구현할 수 있다. 서버에 차단한 토큰 목록을 두거나, 계정별로 번호를 두고 토큰에 담긴 번호와 비교하는 식이다. 다만 이 상태를 조회하는 비용이 다시 생긴다. 액세스 토큰의 수명을 짧게 하고 리프레시 토큰으로 새 토큰을 받게 할 수도 있다. 액세스 토큰은 API 요청에 사용하고, 리프레시 토큰은 새 액세스 토큰을 발급받는 데 사용한다. 리프레시 토큰을 막으면 다음 갱신은 못 하지만, 이미 발급한 액세스 토큰은 만료까지 남을 수 있다. 다음 요청부터 바로 거부해야 한다면 요청마다 로그아웃 상태를 확인하는 처리가 필요하다. ### 서명 확인과 정보 암호화는 다르다 JWT를 검증할 때는 서명뿐 아니라 어떤 알고리즘으로 만들었는지, 누가 발급했는지, 어느 서비스에서 쓸 토큰인지, 만료됐는지도 확인해야 한다. 흔히 사용하는 서명 JWT의 내용은 Base64URL로 인코딩됐을 뿐이라 토큰을 가진 누구나 읽을 수 있다. 서명은 위조를 막을 뿐이므로 민감한 정보는 넣지 않아야 한다. JWT를 사용해도 계정이 제한됐는지, 현재 권한이 바뀌었는지 확인하려면 DB 조회가 필요할 수 있다. 토큰 형식을 바꾼다고 서비스의 모든 상태 조회가 사라지지는 않는다. JWT 검증과 DB 세션 조회 중 무엇이 더 빠른지는 실제 환경과 부하를 측정해야 판단할 수 있다. 앱이나 외부 프로그램에서 API를 호출할 때도 Opaque Token을 사용할 수 있다. 토큰을 쿠키로 보낼지, 헤더에 직접 넣을지와 토큰을 어떤 형식으로 만들지는 각각 선택할 문제다. *** ## 비밀번호를 안전하게 저장하는 데도 비용이 든다 세션은 로그인한 뒤의 이야기다. 그 전에 확인하는 비밀번호는 어떻게 저장해야 할까? 서버가 공격당했을 때 저장된 비밀번호까지 그대로 노출되면 피해가 커진다. **모여는 비밀번호 원문을 저장하지 않고 Argon2id로 만든 해시를 저장한다.** 해시는 입력값을 정해진 알고리즘으로 계산해 얻은 값이다. 비밀번호를 확인할 때는 사용자가 입력한 비밀번호를 같은 설정으로 계산해, 저장된 해시와 일치하는지 검증한다. 하지만 빠르게 계산할 수 있는 일반 해시만 사용하면 공격자도 흔한 비밀번호를 빠르게 대입할 수 있다. 비밀번호 저장용 해싱은 추측 한 번에 드는 계산과 메모리 비용을 높인다. 모여는 Bun이 제공하는 Argon2id를 선택했다. 별도의 알고리즘을 직접 구현하지 않고, 다음 설정으로 해시를 만든다. ```ts title="모여의 비밀번호 해싱 설정" const passwordHash = await passwordApi.hash(plainTextPassword, { algorithm: "argon2id", memoryCost: 65_536, timeCost: 3, }); ``` 실제 Bun 비밀번호 어댑터의 설정. 메모리 설정의 단위는 KiB다. `memoryCost: 65_536`은 64MiB에 해당한다. 공격자가 비밀번호 후보를 계산하는 데 부담을 주지만, 우리 서버도 그 비용을 지불한다. 해시 8개가 실제로 동시에 실행된다면 설정상 메모리 예산은 **64MiB × 8 = 512MiB**가 된다. 다음 도식은 동시에 실행하는 해시의 개수에 따라 메모리 예산이 늘어나는 모습을 보여준다. 수치는 실제 서버 사용량을 측정한 결과가 아니라, 설정값을 바탕으로 계산한 예산이다. 그런데 모여의 EC2는 2026년 10월 기준 메모리 4GiB인 작은 인스턴스다. 다른 API와 작업도 같은 서버에서 실행되므로 해싱에만 메모리를 모두 줄 수는 없다. 그래서 **비밀번호를 검증하기 전에 로그인 시도 횟수도 제한한다.** 모여는 기본적으로 15분 동안 같은 이메일에 대한 로그인 시도를 10회로 제한한다. IP 주소를 일부 범위로 묶은 IP prefix를 확인할 수 있다면, 같은 범위의 시도를 50회로 제한하는 조건도 적용한다. 비밀번호가 맞았는지와 관계없이 로그인 시도 자체를 센다. 보안에 도움이 되는 비용이라도 서비스가 감당할 수 있는지 봐야 한다. 매번 설정을 크게 올리는 것보다 해싱 비용, 동시 실행 수, 요청 제한을 함께 고민하는 편이 현실적이었다. 다행히 이 비용은 로그인할 때만 든다. 앞에서 본 것처럼 다음 요청부터는 Argon2id를 다시 실행하지 않고 세션을 조회한다. 더 살펴보기: 다른 해싱 방식과 OWASP의 도움 ### 알고리즘 이름만으로 선택하지 않는다 Argon2id 외에도 비밀번호 저장에 사용하는 방식은 여러 가지다. 이미 운영 중인 시스템인지, 런타임이 무엇을 지원하는지, 따라야 하는 규정이 있는지에 따라 선택이 달라질 수 있다. | 방식 | 고려할 상황 | 확인할 점 | | -------- | --------------------- | -------------------------------- | | Argon2id | 새로운 비밀번호 저장 구현 | 메모리·계산 비용과 런타임 지원 | | scrypt | Argon2id를 사용할 수 없는 환경 | 파라미터 조합과 메모리 예산 | | bcrypt | 기존 시스템과의 호환성을 유지할 때 | 계산 비용과 긴 비밀번호 처리 방식, 72바이트 입력 제약 | | PBKDF2 | FIPS 같은 규정 요건이 있는 환경 | 요구하는 암호 모듈과 구현, 반복 횟수 | ### 해시 하나의 비용과 동시 실행 비용을 구분한다 Bun이 만든 해시 문자열에는 salt와 계산 설정도 함께 들어 있다. salt는 같은 비밀번호라도 서로 다른 해시가 나오게 하기 위해 더하는 무작위 값이다. 비밀번호를 검증할 때는 저장된 문자열에 포함된 값과 설정을 사용한다. 모여의 코드에서는 병렬성 옵션을 직접 지정하지 않는다. `timeCost: 3`은 계산 비용에 관한 설정이며, 메모리 64MiB를 세 배로 사용한다는 뜻은 아니다. 앞의 도식은 해시가 동시에 몇 개 실행되는지에 따른 계산이다. 요청 16개가 들어와도 일부가 기다리고 있다면 동시에 실행되는 해시는 그보다 적다. 16칸은 모여의 실제 실행 한도를 뜻하지도 않는다. 서버 프로그램이 사용하는 다른 메모리까지 합친 실제 사용량과 응답 시간은 따로 측정해야 한다. ### 요청 제한도 어디에서 세는지 확인한다 모여는 인증 시도 횟수를 PostgreSQL에 저장한다. 두 요청이 동시에 들어와도 서로의 증가분을 덮어쓰지 않도록 갱신하므로, 여러 API 서버가 같은 DB의 횟수를 함께 사용할 수 있다. 반면 일반 HTTP 요청에 사용하는 Fastify rate limit은 현재 서버 프로세스마다 따로 센다. 서버를 여러 대로 늘리면 같은 사람이 서버마다 허용된 횟수만큼 요청할 수 있다. 그래서 설정에 적힌 숫자와 함께 어디까지 합쳐 세는지도 확인한다. ### OWASP는 빠뜨린 조건을 점검하는 데 도움이 됐다 직접 구현하다 보면 "비밀번호를 해시했으니 됐다"고 생각하고 다음으로 넘어가기 쉽다. OWASP의 자료는 세션 만료나 CSRF 방어, 해싱 설정처럼 함께 확인할 조건을 찾는 데 도움이 됐다. Cheat Sheet는 "이 문제를 구현할 때 무엇을 챙길까?"에 가까운 안내이고, ASVS는 "구현한 서비스가 어떤 보안 요구사항을 충족해야 할까?"를 점검하는 기준이다. 특정 해싱 알고리즘이나 설치만 하면 되는 라이브러리가 아니라, 설계와 검증에 참고하는 자료다. 인증 정책은 NIST 자료를, 알고리즘의 정확한 동작은 해당 명세를 함께 확인하는 식으로 목적에 맞게 참고할 수 있다. ### 응답 시간으로 가입 여부를 추측하는 것도 줄인다 가입된 이메일에는 느린 비밀번호 검증을 하고, 없는 이메일에는 바로 응답한다면 걸린 시간으로 가입 여부를 추측할 수 있다. 그래서 없는 이메일에도 검증용으로 준비한 더미 해시를 사용해 비밀번호 검증을 수행한다. 시간 차이를 줄이기 위한 처리다. 다만 소셜 로그인 전용 계정에는 별도 응답이 있으므로, 가입 여부가 드러나는 문제를 완전히 해결했다고 말할 수는 없다. 비밀번호를 확인한 뒤 세션을 저장하기 전까지 다른 요청이 비밀번호를 바꿀 수도 있다. 모여는 세션을 만들 때 비밀번호 버전을 다시 확인해, 방금 확인한 비밀번호가 여전히 현재 비밀번호인지 검사한다. *** ## 로그인 코드 밖에서도 지켜야 할 것들 인증 코드를 잘 만들어도 DB를 인터넷에 열어 두거나, 사용자 요청과 운영 접속을 구분하지 않으면 보호해야 할 범위가 커진다. 모여에서는 요청이 서버와 DB에 도달하는 경로도 함께 살펴봤다. API는 앞에서 말한 Cloudflare Tunnel로 EC2에 연결한다. EC2 쪽에서 Cloudflare로 연결을 만들고, 그 연결을 통해 API 요청이 들어온다. 그래서 앱 보안 그룹에는 인바운드 허용 규칙을 두지 않았다. 인터넷에서 EC2의 API 포트나 SSH 포트로 바로 들어오는 길이 없으니, 운영자가 서버를 관리할 때는 AWS의 관리 서비스인 SSM으로 접속한다. DB는 공개 접근을 끈 RDS다. PostgreSQL 포트는 앱 보안 그룹에서만 접근하게 했다. 아래 도식은 사용자 요청이 들어오는 경로와 DB에 접근할 수 있는 범위를 보여준다. 접근 경로를 제한했더라도, 그 경로로 들어온 요청이 누구의 것인지는 따로 확인해야 한다. 그래서 NestJS는 전달받은 요청마다 세션과 작업 권한을 검사한다. API에는 Helmet을 적용해 [CSP](https://www.yolog.co.kr/post/http-content-security-policy) 등 보안 헤더를 설정했고, EC2와 RDS의 저장소도 암호화했다. Cloudflare에서는 HTTPS 전환과 TLS 설정, 기본 DDoS 보호를 확인했다. 다만 Cloudflare를 쓴다고 모든 보안 기능이 켜져 있다고 생각하지는 않았다. 실제로 적용한 설정을 확인하는 것도 구현의 일부였다. 운영 설정 더 보기: 무엇을 보호하고, 어디까지 적용했을까? 서버 밖의 보안은 통신, 저장, 접근 경로로 나눠 점검했다. (이미지: 통신할 때 HTTPS로 보호하고, 저장소는 암호화하며, 서버와 DB의 접근 경로를 제한한다) ### 통신할 때는 내용을 엿보기 어렵게 한다 브라우저와 서버가 정보를 주고받을 때는 HTTPS를 사용한다. Cloudflare에서 HTTP 요청을 HTTPS로 돌리고, 암호화 통신에 TLS 1.2 이상을 사용하도록 설정했다. API는 브라우저가 이후에도 HTTPS를 쓰도록 알리는 HSTS 헤더도 보낸다. 설정이 적용된 위치는 구분했다. API가 HSTS를 보내고 있어도 Cloudflare 자체의 HSTS 설정은 꺼져 있었다. 웹 페이지와 API의 보안 헤더도 같지 않았다. 어느 응답에 어떤 설정이 적용됐는지 각각 확인했다. ### 저장할 때도 암호화한다 서버의 디스크인 EBS와 데이터베이스인 RDS의 저장소를 암호화했다. 앞의 HTTPS가 이동 중인 정보를 보호한다면, 이 설정은 서버에 저장된 정보를 보호하기 위한 것이다. EC2가 자신의 설정과 정보를 조회할 때도 접근 토큰을 요구하도록 했다. 이를 위해 IMDSv2를 사용한다. 조회 주소를 안다고 아무 요청으로나 서버 정보를 읽게 두지 않으려는 조치다. ### 서버와 DB에 들어오는 길을 줄인다 본문에서 본 Tunnel과 보안 그룹 설정이 여기에 해당한다. 인터넷에서 EC2로 바로 접속하는 길은 닫고, DB에는 앱 서버만 연결할 수 있게 했다. 로그인 코드가 요청의 사용자를 확인한다면, 이 설정은 그 요청이 들어오는 경로를 제한한다. 다만 장애 대비는 별도로 준비해야 한다. 글을 쓰는 2026년 10월에는 EC2 한 대와 단일 AZ RDS를 쓰고 있다. AZ는 AWS가 데이터센터를 나눠 운영하는 구역이다. 서버나 해당 구역에 문제가 생기면 서비스가 중단될 수 있다. 암호화는 데이터를 지키는 설정이고, 장애 대비는 따로 풀어야 할 문제다. Cloudflare의 추가 기능도 실제로 적용한 범위만 적었다. Access로 접근을 제한하는 곳은 개발 환경이다. 운영 관리자 화면은 별도로 봐야 한다. 봇 요청을 막는 Bot Fight Mode는 꺼져 있고, 흔한 웹 공격을 검사하는 OWASP Core Ruleset은 실제 적용 여부를 확인하지 못했다. 접속 위치는 참고 정보로 사용한다. 신뢰하도록 설정한 중계 경로에서 받은 위치 헤더만 읽고 검증한다. 여행이나 VPN 때문에 접속 나라가 바뀔 수 있으므로, 나라가 달라졌다는 이유만으로 공격이라고 판단하지 않는다. 위치를 알 수 없다면 모르는 상태로 남긴다. *** ## 마치며 (이미지: 사용성·안정성·보안을 다듬어 사용자의 신뢰를 쌓아 가는 모여의 개발 과정) 모여를 혼자 기획하고, 디자인하고, 개발하면서 정말 많은 것을 배웠다. 혼자 만드는 가장 큰 장점은 내가 원하는 방식과 속도로 구현할 수 있다는 점이었다. 궁금한 문제를 깊이 파고들고, 내가 내린 선택의 결과도 직접 확인할 수 있었다. AI 시대에는 개발을 잘 몰라도 제품을 만들고, 제품이 시장에 맞는지(PMF) 확인해 볼 수 있다고 생각한다. 도메인을 깊이 아는 사람이 개발자도 떠올리지 못한 서비스를 만들 수 있고, 아무리 좋은 코드로 만들었어도 쓰이지 않는다면 제품으로서의 의미는 작다. 그 사실은 나도 잘 알고 있다. 다만 비개발자가 만든 여러 서비스를 써 보면서, 좋은 아이디어와 별개로 아쉬운 부분도 경험했다. 누군가에게는 사소한 버그일 수 있지만, 서비스를 만드는 입장에서는 자꾸 눈에 들어오는 작은 불편들이 있었다. 그렇다면 개발자인 나는 어디에서 차이를 만들 수 있을까? 내가 찾은 답은 사용자가 믿고 쓸 수 있는 서비스를 만드는 일이었다. 그 신뢰를 말로만 약속하고 싶지는 않았다. 예상하지 못한 상황에서도 동작을 일관되게 유지하고, 사용자의 계정과 정보를 보호하도록 코드와 보안을 더 챙기고 싶었다. 그렇다고 당장 필요 없는 구조까지 미리 만들지는 않았다. 지금 필요한 문제를, 현재의 시간과 비용 안에서 내가 아는 가장 합리적인 방법으로 해결하려는 것이다. 정답은 없다고 생각한다. 어떤 선택이 맞았는지는 서비스를 운영하며 확인하려 한다. 사용자가 늘면 사용 패턴과 부하를 보며 기기 제한과 인증 조회 비용, 해싱 설정도 다시 살펴볼 생각이다. 지금의 설계를 고집하기보다, 사용자 경험과 운영에 필요한 통제를 기준으로 판단하고 싶다. 내가 부족해서 놓친 문제와, 알고도 외면한 문제는 모두 사용자의 신뢰를 잃게 할 수 있다. 사용자에게는 같은 실망일 수 있지만, 만드는 사람의 태도까지 같지는 않다고 생각한다. **모르는 것은 배우고, 아는 문제는 외면하지 않으면서 더 나은 선택을 코드로 만들어 가고 싶다.** 어쩌면 이것이 내가 개발을 좋아했던 이유이면서, 꾸준히 서비스를 만들며 공부를 해 온 이유이지 않을까? *** ## 같이 읽으면 도움이 되는 글 이 글에서 짧게 넘어간 개념은 아래 글에서 더 자세히 다뤘다. * [HTTP 쿠키 이해하기](https://www.yolog.co.kr/post/http-cookie): 브라우저가 쿠키를 저장하고 다음 요청에 보내는 과정. * [동일 출처 정책 쉽게 이해하기](https://www.yolog.co.kr/post/http-same-origin-policy): 브라우저가 두 주소를 같은 출처로 판단하는 기준. * [CORS 쉽게 이해하기](https://www.yolog.co.kr/post/http-cors): 다른 출처의 API를 호출할 때 브라우저와 서버가 확인하는 조건. * [세션 하이재킹과 HttpOnly](https://www.yolog.co.kr/post/security-session-hijacking): 세션 탈취가 일어나는 방식과 쿠키 보호의 역할. * [XSS 공격이란?](https://www.yolog.co.kr/post/security-xss): 악성 스크립트가 사용자의 브라우저에서 실행되는 문제. * [CSRF 공격과 방어법](https://www.yolog.co.kr/post/security-csrf): 로그인한 브라우저가 의도하지 않은 요청을 보내는 문제. * [CSP로 배우는 웹 보안 설정법](https://www.yolog.co.kr/post/http-content-security-policy): 브라우저가 불러오고 실행할 콘텐츠의 범위를 제한하는 방법. --- # 아직 출시도 안 했는데, 커넥션 풀이 고갈됐다 > 사용자는 나 하나인데 PostgreSQL 커넥션 풀이 고갈됐다. Promise.all과 락 대기가 연결을 붙잡은 원인, pg-boss 작업 큐와 연결 예산을 다시 짠 과정을 그림으로 정리한다. - 원문: https://www.yolog.co.kr/post/moyeo-connection-pool-exhaustion - 카테고리: 개발 - 발행: 2026-10-03 - 수정: 2026-10-14 (이미지: 화면을 보는 사람은 한 명이지만, 뒤에서는 여러 작업이 작은 DB의 연결을 기다리고 있다.) ## 어라, 아직 사용자는 나 하나인데? 회사에 다니며 취미로 개인 서비스를 만들다 보니, 만드는 것만큼이나 알리는 것도 어렵다는 걸 느꼈다. 비슷한 어려움을 겪는 사람들을 만나 시작한 서비스가 [모여](https://moyeo.io)다. 목표는 **누구나 자신을 알릴 수 있게 돕는 것**이었다. 서비스·제품을 만든 사람부터 개인 브랜딩을 하는 사람, 소상공인까지 손쉽게 자기 브랜드를 알릴 수 있도록 만들고 싶었다. (이미지: 여러 SNS에 올릴 글을 작성하고 추천 게시 시간을 확인하는 모여의 예약 발행 화면) > 모여는 2026년 10월 14일 정식 출시했다. [moyeo.io](https://moyeo.io)에서 바로 써 볼 수 있다. 수요를 빠르게 확인하고 약 한 달 동안 서버·클라이언트·인프라를 만들었다. 여러 SNS의 예약 발행과 댓글·성과 관리, AI 작성 지원을 중심으로 구독 결제·환불, 요금제별 이용 한도와 팀원별 접근 권한까지 구현했다. 사용자 흐름을 살펴볼 분석 도구(GA)와 활성화·유료 전환·매출을 확인할 KPI도 설계했다. 운영자 화면과 쿠폰을 붙이고 각 SNS의 앱 심사까지 거치니, 화면에서 보이는 것보다 손이 가는 일이 훨씬 많았다. 화면 디자인부터 소개 이미지와 문구, 홍보까지 혼자 챙기는 것도 쉽지 않았다. 다른 사람들이 자신을 알리도록 돕는 서비스를 만들면서, 정작 내 서비스를 어떻게 보여주고 알릴지도 계속 고민해야 했다. > 프론트엔드 구현과 서비스 운영에서 고민한 이야기는 [모여를 만들며 정한 프론트엔드의 기준](/post/moyeo-frontend-architecture)과 [혼자 서비스를 운영한다는 것](/post/moyeo-product-operations)에 따로 정리했다. 혼자 만드는 서비스라 운영 비용도 아끼고 싶었다. API와 백그라운드 워커를 EC2 한 대에 올리고, 작은 PostgreSQL DB로 시작했다. 당장은 서버 사양을 올릴 생각이 없었다. 그런데 커넥션 풀 고갈 오류가 났다. 아직 정식 출시도 안 했고 사용자는 나 하나인데, 벌써 서버를 키워야 하나? 비용을 아끼려던 나에게는 조금 충격이었다. 사양부터 올리기 전에, 실제로 어디서 막혔는지 로그와 지표를 AI와 함께 분석해 봤다. 정작 DB 쪽 지표는 한가했다. 대신 워커 로그에 이상한 대기가 두 가지 보였다. 미디어 복구 작업(`media_job_recovery`)은 5초를 기다리고도 연결을 받지 못했고, 채널 락을 기다리던 작업은 락 대기 상한(`lock_timeout`)인 5초 동안 연결을 쥔 채 서 있었다. 코드를 따라가 보니 한 작업이 연결 여러 개를 한꺼번에 쓰거나, 연결을 잡은 채 락을 기다리는 곳이 있었다. 이 글에서는 그 과정에서 놓친 부분과, 작은 인프라 안에서 일을 나눠 처리하도록 바꾼 과정을 정리한다. 고친 배포가 불러온 두 번째 장애 이야기도 마지막에 담았다. *** ## CPU 사용률은 낮은데, 왜 느릴까? 작업이 느려지면 CPU 사용률부터 보게 된다. 높으면 처리할 일이 많다고 보고, 낮으면 서버에 여유가 있다고 여긴다. 그런데 사용자가 기다리는 시간 내내 CPU가 일하지는 않는다. 예를 들어 모여는 연결한 계정의 댓글을 각 SNS의 API로 가져와 저장한다. SNS에 따라 특정 게시물의 댓글을 읽기도 하고, 채널을 기준으로 댓글을 모아 읽기도 한다. 필요한 게시물 정보를 추가로 조회하거나, 여러 페이지에 나뉜 댓글과 답글을 이어서 가져오는 경우도 있다. 단순히 "댓글을 가져온다"고 하면 짧아 보이지만, 실제로는 인증·페이지 이동·응답 형식·요청 한도를 함께 고려해야 하는 일이다. 응답을 해석하고 저장할 데이터를 정리할 때는 CPU를 쓴다. 반면 SNS에서 응답이 돌아오기 전까지는 기다린다. 이 둘을 구분하는 것이 출발점이다. 저장할 차례가 돼도 바로 진행하지 못할 수 있다. DB 연결을 빌릴 차례를 기다리거나, 다른 작업이 같은 데이터를 처리하고 있어서 락이 풀리기를 기다리기도 한다. 락은 같은 대상을 동시에 바꾸지 못하도록 처리 순서를 정하는 장치다. 이런 대기는 처리 시간을 늘린다. 그렇다고 기다린 시간만큼 CPU 사용률이 올라가지는 않는다. 작업이 5초 걸렸어도 실제 계산은 아주 짧았을 수 있다. **CPU 사용률만으로는 작업이 어디서 얼마나 기다렸는지 알 수 없다.** 아래 그림은 세 가지 상황을 같은 축으로 비교한다. 파란 선은 CPU 사용률, 보라색 선은 작업 하나를 마치는 데 걸리는 시간이다. 세 그래프는 흐름을 이해하기 위한 개념 예시다. 첫 번째 상황에서는 작업이 짧게 끝난다. CPU 사용률이 조금 오르내려도 작업은 계속 짧은 시간 안에 끝난다. 계산도 길지 않고, 다음 단계로 넘어가는 데 오래 기다리지 않는 상태다. 두 번째 상황은 CPU 사용률이 낮은데 처리 시간이 늘어나는 경우다. 이때는 무엇을 기다리는지 살펴봐야 한다. DB 응답이 느릴 수도 있고, 풀의 빈 연결을 기다릴 수도 있고, 외부 서비스가 응답하지 않을 수도 있다. CPU 사양을 올려도 이런 대기는 그대로일 수 있다. 세 번째 상황에서는 CPU 사용률과 처리 시간이 함께 오른다. 처리해야 할 일이 늘었거나 계산이 무거워졌을 가능성이 크다. 요청 수는 평소와 비슷한데 CPU 사용률만 올랐다면 오래 걸리는 계산이나 반복문부터 의심해 볼 만하다. 요청도 함께 늘었다면 현재 서버가 처리할 수 있는 양을 넘어섰는지 살펴본다. 실제 장애 때 RDS 지표도 두 번째 상황에 가까웠다. 연결은 6개, CPU 사용률은 13%, 읽기 지연은 1ms였으니 DB는 빠르게 답하고 있었다. 그런데 워커가 실행 차례를 5초 넘게 기다린 기록(`limiterWait > 5s`)은 하루 사이 16건에서 66건으로 늘어 있었다. 쿼리가 느린 게 아니라면, 작업은 쿼리를 실행하기도 전에 어딘가에서 기다리고 있었다는 뜻이다. *** ## 연결 여덟 개를 함께 쓴다는 것 DB를 사용하려면 연결이 필요하다. 작업이 생길 때마다 새 연결을 만들었다가 닫을 수도 있지만, 연결을 만드는 데도 시간이 들고 DB가 감당할 수 있는 연결 수에도 한계가 있다. 그래서 애플리케이션은 연결 몇 개를 재사용한다. 이 연결들을 관리하는 것이 커넥션 풀이다. > DB 전체의 연결 한도와 애플리케이션의 풀 크기는 서로 다르다. PostgreSQL의 `max_connections`는 DB 서버 전체의 상한이고, API와 워커는 각각 자기 풀의 상한 안에서 연결을 사용한다. DB에 여유가 있어도 내 풀이 꽉 차면 기다려야 한다. DB의 한도는 설정과 메모리 등 운영 자원에 따라 달라지며, 무작정 늘리면 연결을 유지하는 비용도 커진다. [PostgreSQL 연결 설정](https://www.postgresql.org/docs/current/runtime-config-connection.html) 풀을 처음부터 어려운 장치로 생각할 필요는 없다. 필요한 순간에 연결을 빌리고, 일을 마치면 돌려주는 구조다. 풀은 동시에 빌려줄 수 있는 연결 수를 제한한다. 최대 여덟 개라면 아홉 번째 작업은 앞선 작업이 연결 하나를 돌려줄 때까지 기다린다. 아래 그림에서는 연결 여덟 개에 먼저 작업 여덟 개가 들어온다. 각 작업은 연결을 1.5초 사용한다. 0.5초 뒤에 작업 네 개가 더 도착한다. 새로 온 점들이 어디에 머무는지 보자. 추가된 네 개는 바로 DB로 가지 못한다. 연결 여덟 개가 모두 사용 중이기 때문이다. 풀 바깥에서 기다리다가 먼저 시작한 작업들이 연결을 돌려주면 빈자리로 들어간다. 그래프의 대기 수가 줄어드는 순간과 점이 연결 칸에 들어가는 순간은 같은 사건이다. 새로 도착한 작업이 경험하는 시간은 자신의 DB 처리 시간만이 아니다. 연결을 빌릴 차례를 기다린 시간도 포함된다. 예시에서는 1초를 기다린 뒤 1.5초 동안 처리하므로, 도착부터 완료까지 2.5초가 걸린다. DB가 실행한 부분만 재면 1.5초지만 작업 전체는 더 오래 걸린다. ### DB가 보는 연결과, 애플리케이션이 기다리는 요청 이 대기 줄은 아직 DB 연결을 얻지 못한 요청이다. PostgreSQL이 보는 세션 수에 그대로 나타나지 않는다. DB 대시보드에서 연결 수가 적어 보여도, 애플리케이션 내부에는 연결을 기다리는 호출이 쌓여 있을 수 있다. API와 워커가 같은 DB를 사용해도 각자 만든 풀은 별개다. API의 풀이 비어 있는데 워커의 풀이 꽉 찰 수 있다. 다른 프로세스에 남은 연결을 빌려 오지도 못한다. 전체 연결 수를 하나로 합친 그래프만 보면 어느 프로세스가 자기 상한에 도달했는지 놓치기 쉽다. 풀의 최대치도 실제로 열려 있는 연결 수와 구분해야 한다. 최대 여덟 개라는 설정은 필요할 때 여덟 개까지 만든다는 뜻이다. 늘 여덟 개가 열려 있지는 않다. 유휴 연결을 정리하는 설정에 따라서도 관측값은 달라진다. [node-postgres의 풀 문서](https://node-postgres.com/features/pooling)는 연결을 빌리고 돌려주는 기본 동작을 설명한다. ### 연결은 언제 돌아오는가 쿼리 하나를 마치고 연결을 돌려주기도 하고, 여러 쿼리를 한 트랜잭션으로 묶어 마지막까지 사용하기도 한다. 트랜잭션은 여러 DB 변경을 함께 확정하거나 함께 취소하는 단위다. 그동안 같은 연결을 사용하므로 끝날 때까지 다른 작업이 그 연결을 사용할 수 없다. 확인할 것은 연결을 얻은 뒤 무엇을 하는지다. DB 조회에 10ms를 쓰고 외부 API를 3초 기다리는 동안에도 연결을 잡고 있다면, 다른 작업은 그 연결을 3초 이상 사용할 수 없다. DB의 CPU 사용률은 낮아도 연결은 계속 사용 중인 셈이다. 뒤의 트랜잭션 예시에서 이 구간을 코드로 살펴보자. 그래서 풀 고갈을 만났을 때는 두 가지를 확인한다. 동시에 필요한 연결이 몇 개인지, 빌린 연결을 얼마나 오래 쓰는지다. 들어오는 작업 수가 같아도 연결을 오래 잡고 있으면 기다리는 호출이 늘어난다. *** ## 사용자는 한 명이어도, 일은 계속 생긴다 동시에 필요한 연결을 세려면, 먼저 같은 순간에 도는 일이 몇 개인지 알아야 한다. 이걸 사용자 수로 짐작하면 계산이 틀어진다. 사용자 한 명이 버튼을 한 번 눌렀으니 작업도 하나일 것 같지만, 실제 서비스의 일은 그보다 길게 이어진다. 개인 블로그에 예약 글을 올리는 서비스라면 조금 더 단순할 수 있다. 내가 관리하는 DB에 글을 저장하고, 정해진 시각에 공개 상태로 바꾸면 된다. 모여에는 외부 SNS API라는 요소가 하나 더 있었다. 내가 준비를 끝내도 연동한 SNS가 곧바로 처리해 주지는 않는다. 게시물 하나를 예약하면 발행 시각을 확인하고, 파일을 준비하고, 각 SNS에 맞는 요청을 보내고, 결과를 저장한다. SNS마다 업로드 순서와 요청·응답 형식도 다르다. 중간에 끊겼다면 이미 발행됐는지 다시 확인해야 한다. 발행 뒤에는 새 댓글과 성과를 가져오는 일도 이어진다. 연결한 SNS 계정으로 계속 발행하고 데이터를 읽으려면 인증 정보도 유효해야 한다. API 접근 권한을 확인하는 토큰을 SNS별 방식에 맞춰 갱신하고, 다시 로그인이 필요한 경우에는 계정 재연결을 안내한다. 실패한 작업을 다시 처리하고 오래된 파일과 작업 기록을 정리하는 일도 있다. 아래 그림은 예약 하나 주변에서 계속 생기는 일을 묶어 보여준다. 이 일들은 순서대로 한 번씩 끝나지 않고, 저마다 다른 주기로 다시 돈다. 모든 일을 사용자가 화면을 보고 있을 때만 하면 예약 서비스가 될 수 없다. 브라우저를 닫아도 발행은 진행돼야 하고, 다음 날 들어온 댓글도 발견해야 한다. 이런 일들은 HTTP 요청을 받는 API와 분리해서 백그라운드 워커가 맡는다. 여기서 워커는 뒤에서 작업을 처리하는 프로세스를 뜻한다. 작업마다 운영체제 스레드를 하나씩 만들지는 않는다. 워커 프로세스 하나도 여러 비동기 작업을 함께 다룰 수 있고, 그 작업들이 같은 DB 풀을 사용한다. ### 자주 확인할수록 더 잘 가져올까? 댓글이 빨리 보이면 좋겠다고 매초 SNS를 조회하면 어떨까? 서버를 늘리기 전에 외부 API 한도부터 소진할 수 있다. SNS마다 일정 시간에 보낼 수 있는 요청 수나 하루에 쓸 수 있는 사용량, 즉 quota가 다르다. YouTube는 작업마다 사용 비용을 계산하고, 할당량을 넘으면 데이터를 주는 대신 `quotaExceeded` 오류를 반환한다. [사용량 계산](https://developers.google.com/youtube/v3/determine_quota_cost), [오류 문서](https://developers.google.com/youtube/v3/docs/errors) Meta API의 일부 응답에는 `X-App-Usage` 같은 사용량 헤더가 온다. [Meta의 공식 Instagram API 예시](https://www.postman.com/meta/instagram/documentation/6yqw8pt/instagram-api?entity=request-23987686-af579d08-121e-4897-8f45-5fd41ace49df)에서도 확인할 수 있다. 모여는 이런 사용량 정보와 오류의 재시도 정보를 읽는다. 한도가 부족하면 같은 요청을 즉시 반복하지 않고, 다시 수집할 수 있는 시각으로 작업을 미룬다. 사용자에게는 새 댓글이 안 보이는 답답한 상황이지만, 그때 요청을 더 보내 봐야 소용없다. 너무 자주 확인하면 오히려 다음 데이터를 가져올 기회를 잃는다. 갱신 주기는 원하는 실시간성뿐 아니라 각 SNS의 API 한도와 남은 사용량에 맞춰 정해야 했다. 제한이 풀리는 시각도 SNS와 오류에 따라 다르므로 모든 제한을 몇 분짜리 대기로 처리할 수는 없다. ### 기다리는 동안 화면에는 무엇을 보여줄까? 한도를 지키더라도 사용자에게 아무 설명 없이 기다리게 할 수는 없다. 모여는 이미 가져온 댓글을 계속 보여주고, 마지막 확인 시각과 다음 확인 예정 시각을 안내한다. 일시적인 요청 제한인지, 사용량을 다 쓴 것인지, SNS 계정을 다시 연결해야 하는지도 구분한다. 새 데이터를 가져오지 못해도 기존 댓글은 그대로 남는다. 수집 주기도 서버와 화면이 함께 맞춘다. 서버는 해당 게시물을 다시 확인할 수 있는 시각을 `nextRefreshAvailableAt`으로 내려준다. 화면은 그 시각에 갱신을 요청하고, 탭이 보이지 않을 때는 자동 요청을 예약하지 않는다. 지원하는 SNS에서는 변경 알림도 활용하되, 주기적인 API 수집을 함께 둔다. 기존 댓글을 보여 주는 단계부터 화면을 갱신하기까지의 흐름은 아래와 같다. 버튼을 눌러 요청이 접수됐다는 것과 댓글 수집이 끝났다는 것도 구분한다. 수집은 워커가 이어서 처리한다. 처리 중에는 클라이언트가 상태를 다시 확인하고, 서버의 변경 알림을 받으면 관련 목록과 상세 데이터만 갱신한다. 무조건 모든 데이터를 계속 새로 받는 대신, 지금 보여주는 화면에 필요한 부분을 업데이트하는 것이다. **더 자주 요청하는 것보다, 언제 다시 확인할 수 있는지 알려주는 것이 중요했다.** 외부 SNS의 응답 속도와 한도를 내 마음대로 바꿀 수는 없지만, 기다리는 이유와 진행 상황은 서비스에서 설명할 수 있었다. ### 외부 요청을 줄여도, 내부 작업은 몰릴 수 있다 외부 요청의 간격을 정했어도, 내부 작업이 동시에 몰리는 문제는 남았다. 하루에 처리할 일이 적어도 매분 실행하는 검사들이 같은 초에 도착하면 순간적으로 몰린다. "하루 몇 건인가"와 "같은 순간 몇 건인가"는 다른 질문이었다. 장애 당일 로그에서도 이런 장면이 보였다. 매분 도는 정기 작업 29개가 같은 순간에 한꺼번에 등록된 것이다. 실행 자리는 전체를 합쳐 네 개뿐이라, 정기 작업 15개가 약 9.5초를 줄 서서 기다렸다. 사용자는 한 명도 늘지 않았다. 주기적으로 할 일이 같은 시각에 몰렸을 뿐이다. 사용자 수가 늘면 작업도 늘겠지만 그 비율은 기능에 따라 다르다. 같은 한 명이어도 연결한 채널 수, 예약 게시물 수, 수집 주기에 따라 뒤에서 하는 일이 달라진다. 작은 서비스를 계획할 때도 먼저 세어야 할 것은 그 순간 실행할 일이다. ### 한 명의 SNS 기록도 작은 데이터는 아니다 가입한 뒤에 올린 글만 가져오면 될까? 이미 운영하던 SNS 계정을 연결하면 기존 게시물과 댓글, 성과 정보도 가져와야 한다. 모여의 요금제 설정에서 댓글·성과를 보관하는 기간은 무료 30일, 유료 730일이다. 무료 요금제의 성과 화면은 최근 7일만 보여 주지만, 수집과 보관은 30일 기준이다. 최근 한 달을 모으는 계정과 약 2년을 모으는 계정의 처리량은 같을 수 없다. 평소 글을 자주 올리고 댓글도 많이 달리는 계정이라면, 사용자 한 명이 연결한 채널에도 처리할 기록이 상당히 많다. SNS 응답을 기다리는 시간뿐 아니라 데이터를 해석하고 정리하는 CPU 시간, 응답과 객체를 담아두는 메모리, 결과를 저장할 DB 연결도 필요하다. 한 명이라는 숫자만으로 가벼운 작업이라고 볼 수 없었다. 물론 요금제의 제공 기간만큼 모든 SNS에서 데이터를 한 번에 가져올 수는 없다. SNS마다 조회 가능한 과거 범위와 API 한도가 다르다. 성과 데이터는 연결 이후부터 쌓아야 하는 항목도 있다. 서비스가 보여줄 기간과 실제로 수집할 수 있는 범위를 함께 보고 일을 정해야 한다. ### 한꺼번에 읽기보다, 조금씩 이어 읽기 2년치 데이터를 한 번의 작업에서 모두 읽고 마지막에 저장하면 어떻게 될까? 중간 결과를 오래 메모리에 들고 있어야 하고, 끝에서 실패하면 어디까지 했는지도 알기 어렵다. 긴 수집 하나가 실행 자리를 오래 차지하는 문제도 생긴다. 그래서 모여의 최초 게시물 수집은 페이지 단위로 진행한다. 가져온 페이지를 저장하면서 다음에 읽을 위치도 남긴다. 이 위치가 커서이고, 어디까지 처리했는지 저장한 기록이 체크포인트다. 한 번에 처리할 페이지 수를 채우면 작업을 마치고, 후속 작업이 저장한 위치부터 이어간다. 페이지 데이터와 진행 위치, 후속 작업은 같은 트랜잭션으로 저장한다. 데이터를 저장하지 못했는데 진행 위치만 앞서가면 빠뜨리는 페이지가 생길 수 있기 때문이다. 저장이 함께 성공해야 다음 작업도 이어서 시작할 수 있다. 이 원리가 뒤에서 설명할 작업 큐 선택과 연결된다. 댓글 수집도 다음 페이지의 위치를 남기며 진행한다. 성과의 과거 구간을 채우는 작업은 한 실행에서 쓸 API 요청 예산과 해당 SNS가 허용하는 조회 기간을 보고 범위를 나눈다. 모든 데이터를 똑같은 크기로 자르는 대신, 수집 대상에 맞춰 한 번에 할 일을 제한하는 것이다. 댓글 수집의 저장 경계를 코드로 줄이면 다음과 같다. 외부 응답은 트랜잭션 밖에서 받고, 데이터와 다음 위치는 함께 저장한다. 이번 실행의 페이지 예산을 다 썼다면 이어서 처리할 작업도 같은 트랜잭션에 등록한다. ```ts title="댓글 한 페이지와 진행 위치를 함께 저장" {5,8} const page = await sns.listComments({ cursor }); await db.transaction(async (tx) => { await saveComments(tx, page.comments); await saveCheckpoint(tx, page.nextCursor); if (page.nextCursor !== null && reachedPageBudget) { await enqueueContinuation(tx, page.nextCursor); } }); ``` 실제 수집 흐름 단순화 · SNS 호출과 저장 함수 이름은 설명을 위해 줄였다 아직 예산이 남았다면 같은 실행에서 다음 페이지를 읽는다. 예산에 닿았다면 현재 실행은 끝내고, 후속 작업이 체크포인트부터 이어간다. 어디까지 했는지가 DB에 남으므로 프로세스가 재시작돼도 처음부터 모든 페이지를 다시 읽을 필요가 없다. 이런 처리를 배치라고 부를 수 있다. 배치는 여러 데이터를 일정한 단위로 묶어 처리하는 방식이다. [Spring Batch](https://docs.spring.io/spring-batch/reference/step/chunk-oriented-processing.html)도 청크 단위로 읽고 처리한 결과를 트랜잭션 안에서 저장하는 구조를 제공한다. Spring Batch는 배치 처리를 위한 프레임워크이고, NestJS는 서버 애플리케이션을 구성하는 프레임워크라 쓰임새가 다르다. JavaScript 진영에도 BullMQ 같은 작업 큐가 있고, [NestJS도 큐 연동을 지원한다](https://docs.nestjs.com/techniques/queues). 모여에서는 PostgreSQL 기반 작업 큐인 pg-boss에 실행할 일을 남기고, 페이지를 나누고 진행 위치를 저장하는 부분은 직접 구현했다. 기존 업무 DB와 같은 트랜잭션을 사용할 수 있다는 점이 이 구성에 맞았다. pg-boss는 실행할 작업을 보관하고 워커에 전달한다. 어떤 SNS의 어느 페이지를 읽을지, 한 번에 얼마나 할지, 진행 위치를 어떻게 저장할지는 서비스 코드가 맡는다. 큐를 붙였다고 큰 수집이 저절로 작게 나뉘지는 않는다. 작업을 어떤 크기로 나눌지, 나눈 작업을 몇 개씩 실행할지는 내가 정해야 했다. *** ## 기다리는 일을 겹쳐 처리하는 방법 몇 개씩 실행할지 정하려면, 먼저 한 프로세스가 기다리는 일을 어떻게 겹쳐 처리하는지 알아야 했다. SNS 응답을 기다리는 동안 CPU가 쉬고 있다면, 그 시간에 다른 요청을 처리할 수는 없을까? 이벤트 루프를 사용하는 JavaScript 서버는 이런 기다림을 겹쳐 처리한다. 여기서 I/O는 네트워크로 데이터를 주고받거나 파일을 읽고 쓰는 입출력 작업을 뜻한다. 댓글을 요청하고 SNS 응답을 기다리는 것도 I/O다. 네트워크 요청을 시작한 뒤 응답이 올 때까지 같은 JavaScript 코드를 계속 실행할 필요는 없다. 런타임과 운영체제가 네트워크 작업을 진행하는 동안 JavaScript 실행 스레드는 다른 코드를 처리한다. 응답이 준비되면 그 결과를 처리할 콜백이 다시 실행 차례를 기다린다. 아래 그림은 SNS 요청 세 개를 비교한다. 왼쪽은 한 JavaScript 실행 스레드에서 요청을 시작하고 응답을 처리한다. 그 사이의 네트워크 대기는 별도로 진행된다. 오른쪽은 요청마다 일반 스레드를 하나씩 사용하는 블로킹 방식이다. 각 스레드는 자신이 보낸 요청의 응답을 기다린다. 파란색은 실행, 주황색은 대기, 초록색은 응답 처리가 끝난 상태다. 오른쪽은 전통적인 Java 서버에서 흔히 쓰던 방식의 예시다. Java도 비동기 I/O나 [가상 스레드](https://docs.oracle.com/en/java/javase/21/core/virtual-threads.html)를 쓸 수 있다. 그러니 비교할 것은 언어 이름보다 기다리는 동안 어떤 실행 자원을 쓰는가다. 모여는 NestJS로 서버를 구성하고 Bun으로 실행한다. 외부 SNS와 DB 응답을 기다리는 작업이 많으므로, 기다림을 겹칠 수 있는 비동기 I/O 모델은 이 서비스에 잘 맞았다. 다만 CPU 계산까지 병렬로 해 주지는 않는다. 같은 JavaScript 실행 스레드에서 긴 계산을 하면 다른 요청의 콜백도 늦어진다. [Node.js의 이벤트 루프 설명](https://nodejs.org/learn/asynchronous-work/dont-block-the-event-loop)도 이 구분을 강조한다. ### Promise 콜백도 실행 차례를 기다린다 그렇다면 준비된 콜백은 어떤 순서로 실행될까? 같은 JavaScript 실행 스레드는 한 번에 코드 하나만 실행한다. 외부 작업이 끝났더라도 현재 실행 중인 코드가 끝나야 다음 콜백을 처리할 수 있다. 순서를 보기 위해 브라우저에서 실행할 수 있는 짧은 예시를 보자. ```ts title="콜백의 실행 순서" setTimeout(() => console.log("타이머"), 0); Promise.resolve().then(() => console.log("Promise")); console.log("동기 코드"); ``` 브라우저에서 실행하는 설명용 예시 위에서부터 적었지만 출력은 `동기 코드 → Promise → 타이머` 순서다. 지금 실행 중인 함수는 **호출 스택**에 쌓인다. `setTimeout`의 0은 즉시 실행하라는 뜻이 아니다. 타이머가 준비되면 콜백이 태스크 큐에서 차례를 기다린다. 이미 완료된 Promise의 `.then` 콜백은 별도의 **마이크로태스크 큐**에 들어간다. 현재 동기 코드가 끝나 호출 스택이 비면 마이크로태스크부터 처리한다. 그 과정에서 추가된 마이크로태스크까지 비운 뒤 다음 태스크를 실행하므로, 이 예시에서는 Promise 콜백이 타이머보다 먼저 나온다. [MDN의 마이크로태스크 설명](https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide)도 이 순서를 다룬다. 아래 그림은 같은 코드를 비교한다. 왼쪽은 동기 코드가 짧게 끝난다. 오른쪽은 마지막 출력 전에 긴 동기 계산을 넣었다. 두 큐에 콜백이 준비돼 있어도 호출 스택에서 계산이 끝나지 않으면 실행하지 못한다. Promise로 감싼다고 계산이 다른 스레드로 옮겨 가지도 않는다. `new Promise`에 전달한 함수 자체는 즉시 실행된다. 오래 걸리는 반복문을 그 안에 넣어도 현재 실행 스레드를 계속 사용한다. 세부 실행 순서는 런타임마다 다르지만, 서버에서도 긴 동기 JavaScript 계산은 같은 스레드에서 실행할 다른 콜백을 늦춘다. *** ## 작업 네 개가 연결 네 개는 아니었다 이렇게 기다림을 겹칠 수 있으니 워커 하나로도 작업 여러 개를 함께 진행한다. 대신 너무 많이 겹치지 않도록 동시에 실행할 작업은 네 개로 제한해 두었고, 워커 풀에는 연결이 여덟 개 있었다. 작업 수를 제한했으니 연결도 넉넉하다고 생각했다. 하지만 이 계산은 작업 하나가 연결 하나만 쓸 때만 맞는다. 작업 안에서 DB 호출 여러 개를 동시에 시작하면 이야기가 달라진다. 작업 하나가 연결 네 개를 빌릴 수 있다. 그런 작업이 네 개라면 필요한 연결은 열여섯 개다. 실행 중인 작업은 네 개인데 풀에는 열여섯 개의 DB 호출이 들어오는 것이다. 아래 그림의 작업 A·B·C·D는 각자 DB 호출 네 개를 한다. 왼쪽은 네 호출을 한꺼번에 시작하고, 오른쪽은 두 개씩 시작한다. 풀 크기는 양쪽 모두 여덟 개로 같다. 주황색 점은 이미 시작했지만 연결을 못 얻은 호출, 회색 점은 아직 시작하지 않은 다음 차례다. 왼쪽에서는 연결 여덟 개를 다 쓰고 나머지 여덟 개의 요청이 풀에서 기다린다. 오른쪽에서는 작업 네 개가 두 연결씩 빌리므로 동시에 필요한 연결은 여덟 개다. 나머지는 각 작업 안에서 순서를 기다린다. 해야 할 일의 총량은 그대로다. 그림의 양쪽에는 모두 열여섯 개의 DB 호출이 있다. **바뀐 것은 같은 순간에 공유 풀로 보내는 호출 수다.** 일을 모두 시작한 뒤 풀이 알아서 조절하게 하는 것과, 시작할 양을 작업 쪽에서 정하는 것은 다르다. 오른쪽도 처음에는 여덟 연결을 모두 쓴다. 다른 작업을 위한 자리까지 남기려면, 작업별 제한과 함께 전체 실행 작업 수도 조절해야 한다. 모여에서는 한 번에 여러 대상을 훑는 정리 작업(sweep)이 트랜잭션 네 개를 병렬로 열었고, 미디어 복구 작업은 일곱 개를 열었다. 이런 작업 네 개가 동시에 실행되면, 여덟 개뿐인 워커 업무 풀에 연결을 16\~28개까지 요구할 수 있었다. 바깥쪽 제한기는 작업을 하나로 셌지만 작업 안에서는 여러 연결을 빌리고 있었다. 이 차이가 당시 설계에서 놓친 부분이었다. 작업의 개수만 제한해서는 DB 호출의 개수까지 제한되지 않는다. 작업을 작게 쪼개도 마찬가지다. 하나였던 작업을 일곱 개로 쪼갠 뒤 전부 동시에 실행하면 동시에 필요한 연결 수는 그대로일 수 있다. 작업을 나눌 때도 어떤 작업들이 같은 풀을 쓰는지 확인해야 한다. 이후에는 작업당 동시에 실행하는 트랜잭션을 최대 두 개로 제한했다. 작업 몇 개를 실행할지 정하는 바깥쪽 제한과, 작업 하나 안에서 DB 호출 몇 개를 겹칠지 정하는 안쪽 제한을 함께 둔 것이다. *** ## Promise.all이면 무조건 빨라질까? 독립적인 일은 병렬로 실행하는 편이 빨라질 때가 많다. 서로 다른 외부 API의 응답을 기다리는 시간을 겹칠 수 있고, DB 연결이 충분하면 두 조회를 함께 시작할 수도 있다. 문제는 서로 독립적인 함수도 같은 자원을 나눠 쓸 수 있다는 점이다. 두 함수가 서로의 결과를 필요로 하지 않아도 같은 DB 풀을 사용할 수 있다. 각각 연결 하나를 빌리면 함께 실행하는 동안 두 자리를 차지한다. 코드의 의존성이 없다는 것과 자원을 두 배 써도 괜찮다는 것은 별개다. `Promise.all`은 전달한 Promise들이 모두 성공할 때까지 기다리고, 하나가 실패하면 실패를 알린다. 이때 이미 시작한 나머지 호출은 취소되지 않고 계속 돈다. 그래서 동시에 시작할 호출 수는 `Promise.all` 밖에서 제한해야 한다. [MDN의 Promise.all 문서](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all)에서도 이 동작을 확인할 수 있다. 먼저 항목 하나를 저장하는 함수를 생각해보자. 아래의 `saveCollectedItem`은 설명을 위해 붙인 이름이다. 수집한 항목 하나를 평범한 DB 트랜잭션 안에서 저장한다. `saveItem`은 그 항목을 DB에 쓰는 부분을 줄여 표현했다. ```ts title="수집한 항목 하나 저장" async function saveCollectedItem(item: CollectedItem) { await db.transaction(async (tx) => { await saveItem(tx, item); }); } ``` 설명용 예시 · 트랜잭션마다 풀의 연결 하나를 사용 이 함수를 `map`에 넘기면 각 항목의 저장이 시작된다. `Promise.all`은 이미 시작된 Promise들의 결과를 모아 기다린다. 항목이 여덟 개라면 풀에 빈 연결이 있는지와 관계없이 여덟 개의 DB 호출을 시작한다. ```ts title="모든 항목을 한꺼번에 시작" await Promise.all(items.map(saveCollectedItem)); ``` 설명용 예시 · 항목 하나가 DB 트랜잭션 하나를 실행한다고 가정 ### 작업은 빨라졌는데, 화면은 더 느려졌다 풀에 연결 네 개가 있고, 같은 풀에서 DB 작업 여덟 개와 화면 조회 하나를 처리한다고 가정해보자. DB 작업은 각각 250ms, 화면 조회는 50ms가 걸린다. DB 작업을 시작하고 50ms 뒤에 화면 조회가 들어온다. 세 가지 방식을 비교한다. 하나씩 실행하기, 두 개씩 실행하기, 여덟 개를 한꺼번에 시작하기다. 아래 그림에서 파란 막대는 DB 작업, 초록 막대는 화면 조회, 주황 막대는 화면 조회가 연결을 기다리는 시간이다. 세 경우 모두 시간축은 2.2초로 같고, 막대는 실제 작업이 끝난 지점에서 멈춘다. 하나씩 실행하면 작업 묶음은 2초에 끝난다. 연결 하나만 쓰고 있으므로 중간에 들어온 화면 조회는 다른 연결에서 바로 시작한다. 도착부터 완료까지 걸리는 시간은 50ms다. 두 개씩 실행하면 묶음은 1초에 끝난다. 동시에 두 연결을 사용하므로 화면 조회를 위한 자리가 남는다. 이 경우에도 조회는 바로 시작해 50ms에 끝난다. 여덟 개를 한꺼번에 시작하면 첫 네 개가 연결을 쓰고 다음 네 개가 풀에 줄을 선다. 뒤늦게 들어온 화면 조회는 그 뒤에 선다. 먼저 들어온 여덟 개가 모두 끝난 500ms 시점에야 연결을 얻고, 50ms 동안 실행한다. 조회가 도착한 시점부터는 500ms가 걸린 셈이다. **작업 묶음은 가장 빨리 끝났는데, 화면 조회는 열 배 오래 걸렸다.** 백그라운드 작업이 연결을 먼저 차지한 만큼, 뒤에 들어온 화면 조회가 기다려야 했다. ### 실제 조회에서는 얼마나 달라졌을까? 앞의 그림은 설명용 모델이다. 실제 모여의 코드에서도 병렬 실행이 이득이었을까? 성과 조회에서 두 조회를 순서대로 실행할 때와 함께 실행할 때를 비교했다. 격리된 PostgreSQL에 초당 5·10·20회 읽기를 보내고, API 풀 상한은 네 개로 두었다. 병렬 조회에서 풀 상한을 여섯 개로 늘린 조건도 같이 쟀다. 측정한 것은 성과 데이터를 읽는 코드 구간, 즉 reader 구간의 p95다. p95는 표본의 95%가 그 시간 안에 끝났다는 지표다. 인증이나 응답 전송까지 포함한 전체 HTTP 응답 시간은 재지 않았다. 아래 그림은 가장 부하가 큰 초당 20회, 풀 상한 네 개 조건의 결과다. 초당 20회까지 올려도 순차와 병렬의 p95는 같은 수준이었다. 반면 관측한 연결은 순차가 한 개, 병렬이 두 개였다. 연결은 두 배로 쓰는데 조회 시간은 줄지 않았으니, 해당 조회는 순차 실행을 유지했다. 빨리 끝나는 조회라면 연결을 두 개씩 쓸 만큼의 이득이 있는지부터 확인해야 했다. ### 제한된 병렬 실행도 Promise.all을 쓴다 그렇다고 `Promise.all`을 전부 걷어내지는 않았다. 현재 워커에서는 `mapWithBoundedConcurrency`라는 공통 함수로 실행 수를 제한한다. 내부에서는 정해진 크기로 항목을 나누고, 각 묶음을 `Promise.all`로 기다린다. 앞의 예시를 같은 원리로 바꾸면 다음과 같다. ```ts title="DB 호출을 한 번에 두 개씩 시작" ins={2-6} del={1} await Promise.all(items.map(saveCollectedItem)); const maximumConcurrency = 2; for (let offset = 0; offset < items.length; offset += maximumConcurrency) { const batch = items.slice(offset, offset + maximumConcurrency); await Promise.all(batch.map(saveCollectedItem)); } ``` 실제 동시성 제한 방식을 단순화한 변경 전후 두 개가 끝나면 다음 두 개를 시작한다. 각 항목이 트랜잭션 하나를 실행한다는 앞의 가정에서는, 이 작업이 동시에 시작하는 DB 호출도 최대 두 개다. 실제 공통 함수에는 입력 검증과 결과 수집도 있다. 위 코드는 실행 순서만 보여주도록 줄였다. `Promise.all`은 그대로 두고, 한 번에 시작할 호출 수를 정한 것이다. 이 규칙은 기억에만 맡기지 않았다. 서버 코드에서 `Promise.all` 하나에 DB 호출을 세 개 이상 넣으면 아키텍처 테스트가 실패한다. 작업당 동시 트랜잭션 두 개라는 예산을 코드 리뷰 대신 테스트가 지킨다. 이후에는 병렬로 실행하기 전에 같은 풀을 쓰는지, 연결을 몇 개 쓰는지, 실제로 얼마나 빨라지는지부터 확인한다. 내 작업이 빨리 끝나더라도 다른 요청을 오래 기다리게 한다면 전체 서비스에는 손해일 수 있다. *** ## 락을 기다리느라 연결까지 잡고 있었다 동시에 시작하는 DB 호출을 줄여도 대기가 사라지지는 않는다. 같은 채널을 두 작업이 동시에 처리하면 안 되는 경우가 있기 때문이다. 한 작업이 상태를 읽고 외부 데이터를 수집하는 동안 다른 작업이 같은 채널의 상태를 바꾸면, 앞서 저장한 진행 위치를 덮어쓸 수 있다. 이런 겹침을 막는 장치가 락이다. 먼저 들어간 작업이 처리 권한을 얻고, 다른 작업은 권한이 풀릴 때까지 기다리거나 나중에 다시 시도한다. 문제는 기다리는 방식이다. 기다리는 동안 어떤 자원을 잡고 있는지에 따라 다른 작업의 자리도 달라진다. 연결을 빌린 뒤 락을 얻을 때까지 기다린다고 생각해보자. 채널을 처리하는 작업 A가 이미 실행 중이다. 같은 채널을 처리하려는 B·C·D는 연결을 하나씩 빌리고, A가 락을 풀기를 기다린다. 일을 진행하는 것은 A 하나인데 연결은 네 개가 사용 중이다. 왼쪽에서는 기다리는 세 작업도 연결을 하나씩 차지한다. CPU는 거의 쓰지 않으니 CPU 그래프만 보면 여유로워 보이는데, 풀에는 빈자리가 없다. 모여의 채널 락이 이 모양이었다. 락을 얻을 때까지 기다리는 방식이라, 실행 자리와 연결을 `lock_timeout`인 5초까지 쥐고 있었다. 오른쪽의 try-lock은 지금 락을 얻을 수 있는지 즉시 확인한다. 대기형 락은 얻을 때까지 기다리고, try-lock은 얻지 못하면 바로 실패를 돌려준다. 같은 대상의 중복 처리를 막는다는 점은 둘이 같다. 다른 작업이 락을 잡고 있으면 연결을 돌려주고 작업을 잠시 뒤로 미룬다. 그동안 다른 채널의 작업이 그 연결을 쓸 수 있다. 같은 채널을 두 번 처리하지 않으면서 공유 풀도 오래 붙잡지 않는다. ### 락을 못 얻었다고 작업을 실패시키지는 않는다 이미 같은 채널을 정상적으로 처리하는 작업이 있어서 기다리는 경우는 외부 API 실패와 다르다. 아직 실제 처리를 시작하지 못했는데 실패 횟수를 올리면, 차례를 기다리기만 한 작업이 재시도 한도를 소모할 수 있다. 그래서 작업을 다음 시각으로 옮기는 것과 실패 재시도를 구분한다. 미룬 작업은 큐에 남겨두고 다시 실행할 시각을 지정한다. 실제 요청을 보냈다가 실패한 경우에는 오류에 맞춰 재시도 횟수와 간격을 정한다. 다시 시도할 때도 모두 같은 순간에 몰리면 같은 경쟁이 반복된다. 모여에서는 해당 워커 경로를 try-lock으로 바꾸고, 얻지 못하면 2\~5초 사이에 시각을 분산해 다시 시도하도록 했다. 이런 작은 시간 차이를 지터라고 한다. 작업들이 다시 한꺼번에 몰리지 않도록 재시도 시점을 조금씩 다르게 잡는 것이다. ### 연결을 잡은 채 외부 응답을 기다리지 않는다 락뿐 아니라 외부 API와 파일 전송도 같은 관점에서 봐야 한다. 예약 상태를 읽고 SNS에 발행한 뒤 결과를 저장한다면, 세 단계를 하나의 트랜잭션으로 감싸고 싶어진다. 전부 성공하거나 전부 취소되면 안전할 것 같기 때문이다. 하지만 DB에서 상태를 확인하는 데 10ms, SNS 응답을 기다리는 데 3초, 결과 저장에 10ms가 걸린다고 해보자. DB가 실제로 일하는 시간은 20ms인데 연결은 3초 넘게 빌려야 한다. 그 트랜잭션에서 행을 수정하거나 `FOR UPDATE`로 잠갔다면, 같은 행을 바꾸려는 다른 작업도 트랜잭션이 끝날 때까지 기다린다. `await`로 JavaScript 실행을 양보해도 **DB 연결과 이미 얻은 락은 계속 쥐고 있다.** 다음은 저장 경계를 비교하려고 만든 설명용 코드다. SNS 응답을 기다리는 줄도 트랜잭션 안에 있으므로, 이 시간 동안 연결이 반환되지 않는다. ```ts title="Before · 외부 응답까지 트랜잭션 안에서 기다림" {4} await db.transaction(async (tx) => { const run = await claimRun(tx, runId); // 응답을 기다리는 동안에도 연결과 이미 얻은 락을 유지한다. const result = await sns.fetch(run.input); await saveResult(tx, run, result); }); ``` 안티패턴 설명용 예시 · HTTP 요청은 DB 롤백에 포함되지 않는다 아래 그림은 같은 외부 요청을 트랜잭션 안에 두는 경우와 밖으로 빼는 경우다. 전체 작업 시간은 비슷해도, DB 연결을 빌리는 구간은 달라진다. 왼쪽은 SNS 응답을 기다리는 3초 동안에도 연결을 빌리고 있다. 오른쪽은 상태 확인과 결과 저장이라는 짧은 구간에만 연결을 쓰고, 그 사이에는 돌려준다. 안전해 보였던 묶음에는 문제가 하나 더 있다. SNS 발행은 성공했는데 마지막 DB 저장이 실패하면 어떨까? DB는 롤백할 수 있지만 이미 SNS에 올라간 글은 저절로 지워지지 않는다. **DB 트랜잭션은 외부 HTTP 요청까지 함께 롤백해주지 않는다.** 느린 외부 응답을 기다리느라 연결과 락을 오래 잡고도, 기대한 원자성은 얻지 못하는 셈이다. 그래서 모여의 성과 수집은 먼저 짧은 트랜잭션에서 이번 실행의 처리 권한을 확보하고, 트랜잭션을 끝낸 뒤 SNS API를 호출한다. 결과가 돌아오면 새 트랜잭션에서 실행 식별자와 상태를 확인하고 저장한다. 이전 실행이 늦게 돌아와도 새 실행의 결과를 덮어쓰지 않도록 한다. 이미지 변환·업로드도 같은 식으로 DB 처리 구간과 외부 작업을 나눈다. 성과 수집 흐름을 줄이면 다음과 같다. `claim`과 `complete`는 각각 별도의 짧은 트랜잭션을 실행한다. `leaseToken`은 이번 실행이 결과를 저장할 권한을 식별하는 값이다. `complete`에서는 그 값과 현재 상태를 다시 확인한다. ```ts title="After · 실행 확보 → 외부 요청 → 결과 저장" {5} const claim = await collectionTransaction.claim(runId); if (claim.status !== "claimed") return claim; // 앞의 트랜잭션은 끝났다. 외부 응답 대기에 DB 연결은 필요 없다. const result = await sns.fetch(claim.input); await collectionTransaction.complete({ runId, leaseToken: claim.leaseToken, result, }); ``` 실제 성과 수집 흐름 단순화 · 함수 이름과 데이터 구조는 설명을 위해 줄였다 외부 요청을 보내는 시점에는 앞의 트랜잭션이 이미 끝나 있다. 그래서 응답을 기다리는 몇 초 동안 이 작업은 DB 연결을 하나도 쥐지 않는다. HTTP 호출을 트랜잭션 밖으로 옮기면 확인할 것이 하나 늘어난다. 외부 발행 중에 사용자가 예약을 취소할 수 있다면, 돌아온 결과를 무조건 예약 상태에 덮어쓰면 안 된다. 어떤 실행의 결과인지, 아직 그 결과를 받아들일 상태인지 다시 확인해야 한다. 외부 요청이 성공했는지 알 수 없는 채 끊겼다면, 재시도 전에 이미 처리됐는지도 확인해야 한다. ### 오래 기다리는 것과 데드락은 다르다 HTTP 요청을 트랜잭션 안에서 보낸다고 곧바로 데드락이 생기지는 않는다. 다른 작업이 하나의 락이 풀리기를 기다리는 것은 대기다. **데드락은 서로가 가진 락을 기다려 어느 쪽도 끝낼 수 없는 상태**다. 작업 A가 부모 행을 잠그고 자식 행을 바꾸려는데, 작업 B가 자식 행을 잠근 채 부모 행을 바꾸려 한다고 해보자. A는 B를 기다리고 B는 A를 기다린다. 누군가 먼저 끝나야 락이 풀리지만, 둘 다 끝날 수 없다. 모여에도 이와 같은 잠금 순서 문제가 있었다. 같은 요청의 중복 실행을 막기 위해 남긴 기록을 정리할 때였다. 만료 기록 삭제는 부모 행을 먼저 잠그고 연결된 자식 행을 지웠다. 별도의 응답 데이터 정리 작업은 자식 행을 먼저 잠근 뒤 부모 행을 수정했다. 두 경로가 겹치면 서로의 락을 기다릴 수 있었다. 응답 정리도 부모 행부터 잠그도록 바꿔 **두 경로의 잠금 순서를 부모 → 자식으로 맞췄다.** 함께 실행해도 잠금 순서가 뒤집히지 않는지는 통합 테스트로 확인했다. PostgreSQL은 데드락을 발견하면 트랜잭션 하나를 중단시키지만, 매번 중단과 재시도로 해결하는 것보다 같은 순서로 잠그는 편이 낫다. [PostgreSQL의 데드락 설명](https://www.postgresql.org/docs/18/explicit-locking.html#LOCKING-DEADLOCKS)에서도 이 방법을 설명한다. 트랜잭션을 짧게 유지하면 락을 오래 붙잡는 시간을 줄일 수 있다. 여러 대상을 잠근다면 순서도 맞춰야 한다. 외부 호출을 밖으로 빼는 것과 잠금 순서를 통일하는 것은 각각 다른 원인을 해결하는 일이다. ### 긴 일과 짧은 일을 같은 줄에 세우면 DB 연결을 얻기 전에도 다른 줄이 있다. 워커가 한 번에 실행할 수 있는 작업 수다. 외부 요청 네 개가 실행 자리를 모두 쓰고 있으면, 예약 시각을 확인하는 짧은 주기 작업도 그 뒤에서 기다릴 수 있다. 풀에는 연결이 남아 있어도 실행 차례가 없으면 시작하지 못한다. 아래 그림은 실행 자리 네 개를 똑같이 두고 비교한다. 왼쪽은 모든 작업이 같은 자리를 사용한다. 오른쪽은 외부 요청에 세 자리, 예약 확인에 한 자리를 남긴다. 외부 작업은 각각 3초, 예약 확인 작업은 0.25초라는 설명용 가정이다. 왼쪽의 예약 확인 작업은 0.5초에 도착하지만 3초가 될 때까지 시작하지 못한다. 자신의 처리는 0.25초밖에 안 되는데, 앞의 긴 작업 때문에 2.5초를 기다린다. 오른쪽에서는 예약 확인용 자리가 따로 있으므로 바로 시작한다. 오른쪽이 모든 일에 더 빠르지는 않다. 외부 작업 하나는 자기 차례를 기다린다. 대신 예약 확인에 쓸 자리를 남겨 둔다. 이 비교로 정하려는 것은 어떤 일을 다른 일 때문에 밀리지 않게 할지다. 모여에서는 주기 작업(`scheduler`), DB 중심 작업(`database`), 외부 요청(`provider_io`), 무거운 미디어 처리(`media_heavy`)를 종류별로 나눠 실행한다. 한 번에 실행할 수 있는 작업은 각각 1·3·8·1개다. 작업마다 주로 사용하는 자원이 다르기 때문이다. 외부 응답 대기는 어느 정도 겹칠 수 있지만 영상 처리를 같은 개수만큼 겹치면 CPU와 메모리가 먼저 부족해질 수 있다. 작업을 큐에서 가져온 뒤 실행 자리 앞에서 너무 오래 기다리는 것도 문제다. 큐는 가져간 작업을 이미 처리 중으로 보고, 처리 제한 시간(lease)을 잰다. 실행 차례만 기다리다 그 시간을 다 쓰면 실제 처리를 시작하기도 전에 실패로 판단될 수 있다. 장애 때 실제로 이런 일이 생겼다. 자리만 기다리다 시간을 넘긴 작업은 재시도 기회를 한 번 날렸고, 매분 도는 정기 작업은 실패한 작업을 모아 두는 dead-letter 큐로 넘어갔다. 그래서 지금은 대기가 `min(lease × 0.25, 30초)`에 닿으면 더 기다리지 않고 작업을 미룬다. 미룬 작업은 재시도 횟수를 쓰지 않는다. ### 이미지 변환은 외부 응답 대기와 다르다 모여에는 업로드한 이미지로 목록용 미리보기와 발행에 사용할 파생본을 만드는 작업도 있다. SNS 응답을 기다리는 것과 달리 이미지를 읽고, 크기를 줄이고, 다시 압축하는 동안에는 실제 계산이 필요하다. 압축된 파일이 작아도 펼친 픽셀을 메모리에 담는 데는 더 큰 공간이 들 수 있다. 현재는 `Bun.Image`로 변환한다. 실제 구현에서 WebP 파생본을 만드는 부분만 남기면 다음과 같다. ```ts title="원본 이미지로 WebP 파생본 생성" {7} const resized = image.resize( output.targetWidthPixels, output.targetHeightPixels, { fit: "inside", withoutEnlargement: true }, ); const bytes = await resized.webp({ quality: output.quality }).bytes(); ``` 실제 구현 단순화 · JPEG 분기와 결과 검사는 생략 [Bun 문서](https://bun.com/docs/runtime/image)에 따르면 이렇게 결과를 `await`하는 이미지 변환은 JavaScript 실행 스레드 밖에서 처리된다. 앞 그림의 긴 동기 반복문처럼 콜백 실행을 직접 막는 것과는 다르다. 그래도 같은 서버의 CPU와 메모리를 쓴다. 비동기라는 이유로 여러 개를 한꺼번에 시작하면 계산량과 메모리 사용량이 겹친다. 그래서 이미지 변환과 영상 처리 같은 무거운 미디어 작업은 `media_heavy`라는 그룹에서 한 번에 하나씩 실행한다. 원본의 파일 크기와 픽셀 수에도 상한을 둔다. DB에서는 먼저 처리할 이미지를 확인하고 트랜잭션을 끝낸다. 그 뒤 변환·업로드를 수행하고, 결과를 저장할 때 다시 트랜잭션을 연다. 이미지 변환 내내 DB 연결까지 잡고 있을 필요는 없다. 외부 API 요청은 여덟 개를 겹쳐도 괜찮았지만, 이미지 변환까지 여덟 개를 겹칠 수는 없었다. 작업의 이름보다 실제로 무엇을 쓰는지 보고 실행 수를 정해야 했다. *** ## 할 일을 저장하는 곳도 필요했다 지금까지는 워커가 이미 가져온 일을 어떻게 실행할지 이야기했다. 그렇다면 그 일은 어디에 남겨둘까? 프로세스의 메모리 배열에 넣어두면 간단하지만, 서버가 재시작되는 순간 사라진다. 몇 시간 뒤에 발행할 게시물을 그 배열에만 보관할 수는 없다. 큐는 실행할 일을 기록해두고 처리할 쪽이 가져갈 수 있게 하는 장치다. API는 사용자의 요청을 접수하고 응답한다. 워커는 큐에서 일을 가져와 실행한다. 이렇게 나누면 사용자가 브라우저를 닫거나 API가 재시작돼도 저장된 일을 계속 발견할 수 있다. 큐를 도입해도 처리 비용은 그대로다. 일을 사용자 요청 밖으로 옮길 뿐이다. 뒤에서 실행하는 워커에도 DB 연결, CPU, 메모리와 동시성 제한이 필요하다. 앞에서 본 풀 고갈도 큐에서 꺼낸 일을 실행하는 비용을 잘못 센 데서 시작됐다. ### DB에 저장하고, 큐에 넣으면 끝일까? 예약 서비스를 만들면 보통 두 가지를 해야 한다. 게시물과 예약 상태를 DB에 저장하고, 실행 시각이 되면 발행할 작업을 큐에 등록한다. 두 저장을 따로 하면 중간에 프로세스가 멈췄을 때 문제가 생긴다. 다음 코드를 보자. ```ts title="예약 저장과 외부 큐 등록" {5} await db.transaction(async (tx) => { await saveScheduledPost(tx, post); }); await externalQueue.add("publish", { postId: post.id }); ``` 두 저장소를 따로 쓰는 설명용 예시 첫 저장이 끝난 직후 프로세스가 종료됐다고 생각해보자. DB에는 예약이 있다. 하지만 외부 큐에 넣는 줄은 실행되지 않았다. 화면에는 예약이 보이는데, 정작 그것을 실행할 작업이 없다. 큐에 먼저 넣으면 반대 문제가 생긴다. 워커가 일을 가져갔는데 DB 저장이 아직 끝나지 않았거나 실패했을 수 있다. 순서를 바꿔도 두 저장소가 함께 성공한다는 보장은 생기지 않는다. 아래 그림의 왼쪽은 DB와 외부 큐에 따로 쓰는 경우다. 오른쪽은 예약과 작업 기록을 같은 DB 트랜잭션에 넣는 경우다. 먼저 저장 뒤 중단되는 장면을 보고, 이어서 커밋 전에 실패하는 장면을 보자. 첫 장면에서 왼쪽은 예약만 남는다. 오른쪽은 함께 커밋했으므로 예약과 실행할 일이 모두 남는다. 프로세스가 멈춰도 다른 워커가 기록을 발견할 수 있다. 다음 장면에서는 커밋 전에 실패했으므로 오른쪽의 두 기록이 함께 롤백된다. 두 기록은 같은 트랜잭션으로 확정해야 한다. 같은 DB를 쓰더라도 따로따로 저장하면 중간에 프로세스가 멈췄을 때 한쪽만 남는다. ### 외부 메시지 큐를 쓴다면, 전달할 기록을 먼저 남긴다 Redis 기반 BullMQ나 SQS 같은 외부 큐를 사용할 수도 있다. 업무 DB와 작업 트래픽을 분리할 수 있고, 작업이 늘어나면 처리 워커를 늘릴 수도 있다. 다만 업무 저장과 외부 큐 등록 사이의 틈을 별도로 해결해야 한다. 트랜잭션 아웃박스 패턴은 이 문제를 푸는 방법이다. 업무 데이터를 저장하는 트랜잭션 안에 "외부 큐로 전달할 일"도 DB 행으로 남긴다. 별도 전달 프로세스가 그 행을 읽어 큐로 보낸다. 이름은 길지만 먼저 기억할 원리는 **업무 저장과 전달할 기록을 같이 남긴다**는 것이다. 전달 전에 중단되면 기록이 남아 있으므로 다시 시도한다. 전달에는 성공했는데 완료 표시 전에 중단되면 같은 일을 다시 보낼 수 있다. 따라서 중복으로 받은 작업을 안전하게 처리하고, 전달이 늦어지거나 실패했는지도 확인해야 한다. 이 패턴은 [이전에 쓴 글](/post/transactional-outbox)에서 더 자세히 설명했다. ### 모여는 왜 pg-boss를 골랐나 모여는 이미 업무 데이터를 PostgreSQL에 저장했다. pg-boss도 같은 PostgreSQL에 작업을 저장하고, 업무 트랜잭션을 넘겨 같은 커밋 안에 등록할 수 있었다. 운영할 시스템을 늘리지 않고 예약 저장과 작업 등록을 함께 처리할 수 있다는 점이 좋았다. | 선택지 | 함께 확인할 비용 | 업무 저장과 작업 등록의 연결 | | --------------- | ----------------------------- | -------------------------- | | Redis 기반 BullMQ | Redis 운영과 복구, DB에서 큐로 전달하는 경로 | 업무 DB의 outbox와 전달 단계를 설계 | | SQS 같은 외부 큐 | 큐와 전달 지연·실패, 중복 처리 | 업무 DB의 outbox와 전달 단계를 설계 | | pg-boss | 업무 DB 안에서 큐 조회·정리도 실행 | 같은 PostgreSQL 트랜잭션으로 등록 가능 | 당시 비교한 BullMQ는 Redis 기반 구성이다. 현재는 [PostgreSQL 백엔드](https://docs.bullmq.io/guide/postgresql)도 제공하므로, 새로 선택한다면 이 구성까지 비교해볼 수 있다. 실제 큐 어댑터는 업무 트랜잭션을 받으면 `fromDrizzle`로 감싸 pg-boss에 넘긴다. 작업 데이터와 옵션을 만드는 변환 함수, 예약 시각과 중복 방지 옵션을 덜어내면 다음과 같다. 강조한 줄이 작업 등록에 같은 트랜잭션을 전달하는 부분이다. ```ts title="업무 트랜잭션을 pg-boss에 전달" {6} const jobId = await this.#client.send( command.queue.name, { correlation: command.correlation, payload: command.payload }, { id: command.id, ...(transaction === null ? {} : { db: fromDrizzle(transaction, sql) }), }, ); ``` 설명을 위해 줄인 코드 · 변환 함수와 예약 시각, 중복 방지 옵션 생략 트랜잭션이 있는 경로에서 업무 행과 작업 행이 함께 확정된다. 롤백했을 때 큐 작업도 남지 않는지는 통합 테스트로 확인한다. 같은 트랜잭션을 넘기는 사용법은 [pg-boss의 어댑터 문서](https://pgboss.io/api/adapters)에 설명돼 있다. 결국 pg-boss의 작업 행이 실행할 일을 직접 보관하는 셈이다. 별도 outbox 테이블에서 외부 큐로 옮겨 싣는 단계를 줄일 수 있었다. 같은 DB를 쓰면 그만큼 추가되는 일도 있다. 큐를 조회하고 스케줄을 검사하고 통계를 모으는 부하가 업무 DB에 더해진다. Redis를 따로 운영하지 않는 대신 PostgreSQL이 큐의 일도 맡는 것이다. 큐의 유지보수 주기와 연결도 전체 예산에 포함해야 한다. 예약과 작업을 함께 저장해도 SNS 발행이 꼭 한 번만 일어난다고 장담할 수는 없다. SNS에 게시물을 발행한 직후 결과 저장 전에 중단될 수 있다. 다시 실행할 때 이미 발행했는지 확인하고 중복 부작용을 막는 설계는 여전히 필요하다. "작업을 함께 남긴다"와 "외부 작업을 정확히 한 번 수행한다"는 다른 보장이다. *** ## 알림을 놓쳐도 작업은 남아야 한다 큐에 작업을 저장했다면 워커가 새 일을 발견해야 한다. 계속 DB를 조회하면 찾을 수 있지만, 할 일이 없을 때도 조회한다. 주기를 길게 두면 비용은 줄지만 새 작업의 발견이 늦어진다. 여기에 알림을 같이 쓰면 좋다. 새 작업이 생겼다는 신호를 받고 DB를 확인하는 것이다. PostgreSQL에는 특정 채널의 신호를 듣는 `LISTEN`과 신호를 보내는 `NOTIFY`, `pg_notify()`가 있다. 모여 워커는 pg-boss의 이 경로를 사용한다. 하지만 알림과 작업 기록을 같은 것으로 보면 안 된다. 아래 그림에서 워커의 알림 연결이 끊겼을 때 무엇이 남는지 보자. 워커가 연결해 듣고 있지 않으면 알림을 받지 못한다. 나중에 다시 연결해도 놓친 알림을 다시 받지 못한다. 반면 커밋한 작업 행은 DB에 남아 있다. 재연결한 워커가 주기 조회로 그 행을 발견하면 실행할 수 있다. **알림은 DB를 다시 확인하라는 신호다.** 실행할 일은 DB 기록에 남아 있으므로, 신호를 받지 못했다고 할 일이 없다고 판단하지 않는다. 트랜잭션 안에서 보낸 NOTIFY는 커밋 뒤에 전달되고, 롤백되면 전달되지 않는다. 저장이 아직 확정되지 않았는데 알림만 먼저 보내 실행하는 순서를 피할 수 있다. 이 동작은 [PostgreSQL NOTIFY 문서](https://www.postgresql.org/docs/18/sql-notify.html)에 명시돼 있다. ### 미래 예약은 시각이 지나야 실행할 수 있다 오후 3시에 발행할 작업을 오전에 저장했다고 생각해보자. 저장할 때 알림을 보낼 수는 있지만, 지금은 실행할 시각이 아니다. 이후 시계가 3시를 가리켰다고 DB가 저절로 새 NOTIFY를 보내지도 않는다. 그래서 미래 예약을 발견하려면 실행할 시각이 됐는지 확인하는 조회가 필요하다. "새 행이 들어옴"과 "이미 있는 행이 지금 실행 가능해짐"은 다른 사건이다. 예약 큐에서 알림만으로 충분하지 않은 이유다. 모여는 알림과 주기 조회를 함께 사용한다. 일반 큐는 알림을 놓쳐도 작업을 찾도록 30초마다 확인하고, 예약 발행 등 시각이 중요한 일부 작업은 5초 간격이다. 리스너가 연결되지 않았을 때의 조회 경로도 따로 있다. 조회 간격을 줄이면 발견은 빨라지지만 DB에 보내는 확인도 늘어난다. 큐마다 아무 작업이 없어도 주기적으로 확인한다면 사용자와 무관한 고정 부하가 생긴다. 작은 DB에서는 이 비용도 무시할 수 없다. *** ## 풀을 늘리기 전에 확인할 것들 풀 고갈을 겪으면 연결 수를 늘리고 싶어진다. 실제로 연결 예산이 부족했다면 필요한 변경일 수 있다. 하지만 무엇 때문에 부족한지 모른 채 숫자만 늘리면, 같은 구조가 더 큰 상한에서 반복될 수 있다. 먼저 느린 부분을 나눈다. 작업이 큐에서 아직 기다리는지, 워커 실행 차례를 기다리는지, 연결을 기다리는지, 연결을 얻은 뒤 쿼리나 락에서 기다리는지다. 이 단계들은 모두 처리 시간을 늘리지만 해결할 위치는 다르다. | 보이는 상황 | 다음에 확인할 곳 | | --------------------------- | ----------------------------------- | | DB CPU 사용률은 낮은데 연결을 오래 기다린다 | 프로세스별 풀 점유, 작업 내부의 동시 호출, 연결을 쓰는 시간 | | 연결은 얻었는데 처리가 오래 걸린다 | 쿼리 실행, 락 대기, 트랜잭션 안의 외부 호출 | | 풀에 여유가 있는데 정기 작업이 밀린다 | 워커의 동시 실행 수와 작업 종류별 대기 | | 특정 순간에 대기가 갑자기 늘어난다 | 정기 작업의 등록 시각, 같은 대상에 몰린 작업, 재시도 시각 | ### 프록시를 추가하기 전에 고칠 부분도 있다 연결 수를 늘리는 것 말고도 떠오르는 방법이 있다. PgBouncer나 RDS Proxy처럼 연결을 중간에서 관리하는 도구다. 프로세스가 많아지고 DB 연결 생성과 재사용이 병목이 되는 상황에서는 검토할 가치가 있다. 다만 내 프로세스의 풀 상한까지 넘게 해 주지는 않는다. 워커가 여덟 연결을 모두 빌린 채 기다리고 있다면 그 뒤에 프록시를 둬도 아홉 번째 호출은 먼저 로컬 풀의 빈자리를 기다린다. 한 작업이 여러 연결을 동시에 요구하거나, 연결을 잡고 외부 응답을 기다리는 문제도 그대로 남는다. 알림을 듣는 `LISTEN`처럼 세션을 유지해야 하는 경로도 있다. [PgBouncer의 기능 표](https://www.pgbouncer.org/features.html)는 연결을 재사용하는 모드에 따라 지원되는 세션 기능을 구분한다. 지금 무엇을 공유하고 무엇이 연결을 계속 붙잡는지 확인한 뒤 선택해야 한다. 비용도 따졌다. RDS Proxy는 지금 RDS 인스턴스 비용과 비슷한 고정비가 붙는데, 막힌 곳은 RDS가 아니라 프로세스 안의 풀이었다. 그래서 첫 장애에서는 프록시를 먼저 추가하기보다, 작업 안의 동시 호출과 락 대기를 줄이고 전체 연결 예산을 맞췄다. API를 2대 이상으로 늘리거나 필요 연결이 `max_connections`에서 예약분을 뺀 값에 가까워지면 PgBouncer와 RDS Proxy를 다시 비교한다. ### 지금은 역할별 연결을 따로 센다 연결 예산을 맞추려면 먼저 누가 연결을 쓰는지부터 알아야 한다. 2026년 10월 기준 모여는 API 한 개와 워커 한 개를 같은 EC2에서 실행하고, RDS는 `db.t4g.small`을 사용한다. 처음에는 `db.t4g.micro`로 시작했고, 뒤에서 설명할 메모리 부족 장애를 겪은 뒤 사양을 올렸다. 이 구성에서 API의 업무 풀, 워커의 업무 풀, pg-boss가 작업을 관리하는 풀, 알림을 계속 듣는 연결을 따로 센다. 모두 같은 PostgreSQL로 가지만 사용하는 이유와 연결의 수명이 다르다. API는 업무 풀 4개, pg-boss 풀 2개, 변경 알림 리스너 1개로 최대 7개다. 워커는 업무 풀 14개, pg-boss 풀 2개, 큐 알림 리스너 1개로 최대 17개다. 두 프로세스의 운영 상한을 합하면 24개다. 여기에 마이그레이션 4개와 운영자 점검 5개의 여유를 더해 33개를 계획한다. 33개를 늘 열어 두지는 않는다. 여러 경로가 한꺼번에 쓸 때 허용할 상한에 점검 여유를 더한 숫자다. 장애 전에는 이런 숫자가 코드, 환경 변수, compose 파일, SSM, Terraform 경보에 손으로 흩어져 있었다. 사양을 바꿔도 숫자들이 함께 움직이지 않았다. 지금은 `CAPACITY_PROFILE`이라는 이름 하나가 RDS·EC2 사양과 워커 수를 가리키고, 서버가 그 이름으로 풀 크기, 실행 자리, 연결 경보선을 계산한다. 사양을 올릴 때는 profile 표에 한 줄을 더하고, `bun run capacity:export`로 계산값을 내보내 Terraform에 적용하면 된다. 서버는 시작할 때 계획한 연결 수를 DB의 `max_connections`에서 예약분을 뺀 값과 비교한다. 계획이 더 크면 아예 뜨지 않는다. 연결이 모자란 채로 운영하다 장애로 알아채는 대신, 배포 단계에서 멈추게 했다. 현재 설정의 계산을 조금 더 자세히 보면 워커 업무 풀 14개는 동시에 실행할 작업 13개에 연결 하나씩을 붙인 값이 아니다. 주기 작업 1자리와 DB 중심 3자리에 작업당 동시 트랜잭션 2개를 계산하면 8개다. 상태 점검용 연결 1개를 더하고, 외부 요청 8자리와 미디어 1자리에 `ceil(9 / 2) = 5`개를 배정한다. 합계는 14개다. 외부 요청과 미디어 작업은 처리 내내 DB 연결을 쓰지 않으므로, 두 작업당 연결 하나를 배정했다. 실제 호출이 몰리는 순간에는 이 계산보다 많은 연결이 필요할 수 있다. 정기 작업이 몰리거나 같은 채널의 수집이 겹치거나 워커 수가 바뀌면 실제 점유와 대기를 다시 확인해야 한다. 실행 자리는 주기 작업 1, DB 중심 3, 외부 요청 8, 미디어 1이다. 외부 요청 중 댓글 동기화는 최대 4자리만 써서 다른 외부 작업의 자리를 남긴다. 실행 자리와 연결 수를 같은 숫자로 세지 않는다. DB 연결 경보선은 계획 33개의 1.5배를 올림한 50개다. DB의 `max_connections`와는 별개인 운영 기준이다. API 업무 풀의 유휴 연결 수명은 10초, 워커는 120초다. 연결이 필요할 때 생성되고 유휴 상태에서 정리되므로 관측값은 설정한 최대치보다 낮을 수 있다. 계속 쓰이는 연결은 유휴 시간으로 닫히지 않아 DB 쪽 캐시가 쌓인다. 그래서 연결에는 최대 수명 30분도 두고, 30분마다 새로 연다. 현재 API 컨테이너의 한도는 CPU 0.75코어와 메모리 1GiB, 워커는 CPU 1.25코어와 메모리 1.5GiB다. EC2는 `t4g.medium`이다. AWS 리소스는 Terraform으로 관리하고 Cloudflare 웹은 Wrangler로 배포한다. 서버의 공개 인바운드는 닫고 Tunnel과 SSM을 사용한다. ### 고갈돼도 알아볼 수 있게, 고친 뒤에는 다시 재 보기 계획을 세워도 풀은 언젠가 다시 찰 수 있다. 그래서 API는 업무 풀이 고갈되면 `503`과 `Retry-After` 헤더로 응답한다. 클라이언트는 잠시 뒤 다시 시도하면 된다는 것을 알 수 있고, 동시 수정 충돌을 뜻하는 `409`와도 구분된다. 커밋됐는지 알 수 없는 연결 끊김은 재시도 안내 없이 `500`으로 돌려준다. 같은 요청을 다시 보내면 두 번 처리될 수 있기 때문이다. 수정한 버전(v0.15.2)을 배포하고 지켜보니 풀 고갈도, 자리만 기다리다 만료되는 작업도 더는 나오지 않았다. RDS 연결은 6\~8개 사이를 오갔다. 그래도 조용하다는 것만으로 안심하기는 어려웠다. 그래서 장애 장면을 다시 만들어 보는 `bun run load:worker`를 둔다. 운영 profile로 실제 워커를 띄우고 정기 작업 29개, 같은 채널 동기화 3개, sweep 4개를 한꺼번에 밀어 넣는다. 워크스페이스 300곳의 작업이 몰리는 경우와 워커 두 개가 함께 소비하는 경우도 돌려 본다. RDS를 small로 올린 뒤 다시 돌렸을 때도 네 시나리오 모두 연결 예산 안에서 끝났고, 풀 고갈과 lease 만료, 실패는 한 건도 없었다. *** ## 고친 배포가 다음 장애를 불렀다 풀 고갈은 사라졌지만, 같은 배포가 다른 장애를 하나 불렀다. 고친 버전(v0.15.2)을 새벽에 배포했는데, 그날 아침 RDS가 메모리 부족으로 멈췄다. RDS는 곧 스스로 재시작했지만 워커는 다시 붙지 못했다. 오후에 내가 직접 재시작할 때까지 다섯 시간 가까이 작업이 멈춰 있었다. 이번에도 연결 문제부터 의심했지만, 연결은 많아 봐야 9개였다. 로그와 지표를 AI와 함께 하나씩 짚어 보니, 원인은 바로 그 수정 배포에 함께 넣은 설정 하나였다. pg-boss가 큐 통계를 모으는 주기를 60초에서 15초로 줄였는데, 이 통계는 작업 테이블(`pgboss.job`) 전체를 훑어 집계한다. 집계가 네 배 잦아지자 사용자 수와 상관없이 늘 도는 부하가 메모리 1GiB짜리 `db.t4g.micro`를 밀어냈다. 그럼 DB가 돌아온 뒤에도 워커는 왜 멈춰 있었을까? 연결에 TCP keepalive를 켜 두기만 하고, 첫 확인을 보내기까지의 지연은 정하지 않았다. 이 값이 0이면 OS 기본값인 2시간을 쓴다. pg-boss 풀에는 keepalive가 아예 없었다. 워커의 연결들은 DB가 재시작된 줄도 모르고, 오지 않을 응답을 기다리며 풀을 붙잡고 있었다. 원인을 알고 나니 고칠 곳이 분명해졌다. 후속 버전(v0.15.3)에서 바꾼 것은 다음과 같다. * 업무 풀, pg-boss 풀, 알림 리스너가 같은 keepalive 설정을 쓴다. 10초 동안 오가는 패킷이 없으면 확인 패킷을 보내서, 재시작된 DB를 바로 알아챈다. * pg-boss 통계 주기는 기본값 60초로 되돌렸다. * RDS를 `db.t4g.small`로 올렸다. * 여유 메모리 150MiB 경보와 Swap 경보를 걸고 PostgreSQL 로그를 내보내, 다음에는 원인을 바로 확인할 수 있게 했다. * 사양을 올린 만큼 AWS 예산 경보 기준도 80달러에서 110달러로 올렸다. 돌아보면 두 장애는 결이 달랐다. 첫 번째는 호출 수를 제한하고 연결을 쥐는 시간을 줄여서 풀었고, 두 번째는 DB 사양과 늘 도는 부하, 끊긴 연결을 알아채는 설정까지 봐야 풀렸다. 그리고 첫 장애를 고치면서 같이 넣은 작은 주기 조정이 두 번째 장애를 불렀다. *** ## 이제는 어디서 기다리는지부터 본다 처음에는 서로 의존하지 않는 작업이라면 `Promise.all`로 함께 실행하는 편이 낫다고 생각했다. 작업 네 개를 실행하면 연결도 네 개쯤 쓰겠거니 했다. 하지만 코드를 따라가니 한 작업이 여러 연결을 동시에 빌렸고, 기다리는 동안에도 그 연결을 잡고 있었다. 함수의 개수 대신 실제로 쓰는 자원을 세어야 했다. 이 일을 겪을 때는 출시 전이라 사용자가 나 하나였다. 정식 출시한 지금도 서버 사양을 올리기 전에 같은 순서로 본다. 작업이 어디서 기다리는지, 기다리는 동안 무엇을 쥐고 있는지. 그리고 병렬 실행을 넣기 전에 그 코드가 연결을 몇 개, 얼마나 오래 잡는지부터 센다. --- # SaaS 구독 결제를 만들며 이해한 Facade 패턴 > 토스페이먼츠 정기결제 코드가 커지며 구독 로직이 결제사 규격에 묶였어요. NestJS에서 Facade와 Adapter로 갱신 흐름과 결제 계약을 나눈 과정을 정리했어요. - 원문: https://www.yolog.co.kr/post/facade-pattern - 카테고리: 디자인 패턴 - 발행: 2026-09-05 - 수정: 2026-10-14 [모여](https://moyeo.io)라는 SaaS를 처음부터 끝까지 만들면서 클라이언트와 서버를 모두 개발했어요. 결제도 처음에는 단순했는데, 요구사항이 하나둘 늘어나면서 코드가 복잡해지고 읽기도 어려워지기 시작했어요. 구독을 갱신하는 코드가 결제수단 조회와 토스페이먼츠 요청 구성은 물론, 승인 결과를 확인해 이용 기간을 반영하는 일까지 직접 챙기고 있었어요. 비슷한 기능을 추가할 때마다 이 순서와 토스의 규격을 다시 알아야 했고, 결제 처리를 바꾸려면 여러 곳을 함께 살펴봐야 했어요. 그래서 구독 갱신을 요청하는 쪽에서 이 과정을 전부 알아야 할지 고민했어요. 필요한 작업은 한곳에서 조합하고, 호출하는 쪽은 갱신을 요청하는 데 집중할 수 있으면 좋겠다고 생각했죠. 그 과정에서 Facade 패턴을 도입했어요. 어떤 코드를 묶고 어떤 책임을 남겼는지, NestJS 예제로 풀어 볼게요. (이미지: 복잡한 구독 결제 흐름을 하나의 창구로 정리하는 Facade) > 코드는 설명에 필요한 흐름만 남기고 간추렸어요. 실제 모여 코드와 다른 부분은 해당 위치에서 함께 짚을게요. ## 처음에는 결제에 성공하면 끝인 줄 알았어요 카드가 등록되어 있고, 무료 체험이 끝나 첫 구독료를 청구하는 상황부터 볼게요. 청구할 금액과 기간을 담은 청구서(Invoice)는 `SubscriptionService`가 준비해요. 그런데 갱신 작업은 그다음부터 결제수단 조회, 토스 요청 구성, 오류 해석, 승인 기록까지 직접 처리하고 있어요. ```ts {40,47} @Injectable() class RenewSubscriptionJob { constructor( private readonly subscriptionService: SubscriptionService, private readonly paymentMethodRepository: TossPaymentMethodRepository, // 결제 시도의 중복 실행을 막고, 승인 결과와 실패 사유를 저장해요. private readonly paymentStore: FirstChargeStore, private readonly tossBillingClient: TossBillingClient, ) {} async execute(subscriptionId: string): Promise { const invoice = await this.subscriptionService.prepareRenewal(subscriptionId); if (!invoice) { return; } // 결제 시도를 저장하고, 이 작업이 처음 승인할 요청을 선점해요. const attempt = await this.paymentStore.prepareFirstCharge(invoice); if (!attempt) { return; } const paymentMethod = await this.paymentMethodRepository.findForAccount( invoice.paymentMethodId, invoice.accountId, ); if (!paymentMethod) { // 이 계정에서 사용할 결제수단이 없어 결제 시도를 실패로 기록해요. await this.paymentStore.markPaymentMethodInvalid(attempt.id); return; } let payment: TossPaymentResponse; try { payment = await this.tossBillingClient.charge({ billingKey: paymentMethod.billingKey, idempotencyKey: attempt.idempotencyKey, body: { customerKey: paymentMethod.customerKey, amount: invoice.amountKrw, orderId: attempt.orderId, orderName: invoice.description, }, }); } catch (error) { if (error instanceof TossApiError && error.code === "REJECT_CARD_PAYMENT") { // 카드 승인이 거절됐다는 사유를 결제 시도에 기록해요. await this.paymentStore.markCardDeclined(attempt.id); return; } // 카드 거절로 분류하지 못한 오류는 운영자가 확인할 대상으로 남겨요. await this.paymentStore.markForReview(attempt.id); throw error; } const matchesInvoice = payment.orderId === attempt.orderId && payment.totalAmount === invoice.amountKrw && payment.currency === "KRW" && payment.type === "BILLING"; if (!matchesInvoice || payment.status !== "DONE") { // 청구 내역과 일치하는 승인을 확인하지 못했으므로 구독을 갱신하지 않아요. await this.paymentStore.markForReview(attempt.id); return; } // 토스 승인 내역을 저장하고, 연결된 내부 결제 ID로 구독에 반영해요. const paymentId = await this.paymentStore.saveTossApproval(attempt.id, payment); await this.subscriptionService.applyPayment(invoice.id, paymentId); } } ``` `prepareFirstCharge()`는 청구서에 연결된 결제 시도를 저장하고 처음 실행할 작업만 선점해요. 주문번호와 멱등키도 이때 만들어 보관해요. 이미 처리했거나 결과를 확인 중인 요청은 여기서 다시 승인하지 않아요. HTTP 호출은 Client로 옮겼지만, 구독 갱신 코드는 여전히 토스가 어떤 키를 요구하고, 어떤 상태를 성공으로 보는지 알아야 해요. `billingKey`와 `customerKey`로 요청을 만들고, `DONE`과 `REJECT_CARD_PAYMENT`를 해석하고 있으니까요. 구독을 갱신하는 로직이 **토스의 API 규격**에 강하게 묶여 있어요. 이제 카드 변경 후 다시 결제하는 기능을 붙인다고 해 볼게요. 그쪽에서도 키를 조회하고, 토스 요청을 만들고, 같은 오류 코드를 해석해야 해요. 비슷한 코드를 복사하거나, 기존 함수에 조건을 더 붙이게 되기 쉬워요. (이미지: 구독 갱신 코드에 결제 요청과 이용 권한 처리가 뒤섞인 모습) 기능이 하나 늘 때마다 이런 연결이 하나씩 더 얽혀요. 결제사를 바꿔야 한다면 더 곤란해지고요. 토스 연동을 준비하면서 카드사 심사가 길어지면 어떡하나 걱정했는데, 실제로 2026년 10월 14일 출시 때까지 심사가 끝나지 않았거든요. 출시 일정에 맞추려고 다른 결제사로 바꿔야 했다면 이 코드는 어디까지 고쳐야 했을까요? Client만 교체해서 끝나지 않아요. 토스의 상태와 오류를 해석하는 갱신·재결제 코드는 물론, 토스 응답을 기준으로 작성한 테스트까지 전부 찾아봐야 하죠. 지금 잘 동작하는 것과 변경에 유연한 것은 다른 문제였어요. 그래서 결제사에 대한 지식은 한곳에 모으고, 구독 쪽은 필요한 결과만 알도록 바꾸고 싶었어요. ## 우선 복잡한 사용 과정을 묶어 볼게요 Facade는 복잡한 하위 시스템을 쉽게 사용할 수 있는 인터페이스를 제공하는 패턴이에요. 여기서는 구독과 결제 Service를 조합해, 호출자가 구독 갱신의 세부 순서를 매번 작성하지 않게 만들어요. 외부 연동과 승인 기록을 `TossPaymentService`로 옮기고, 두 Service를 Facade에서 호출해 볼게요. ```ts {8} @Injectable() class SubscriptionBillingFacadeV1 { constructor( private readonly subscriptionService: SubscriptionService, private readonly tossPaymentService: TossPaymentService, ) {} async renewSubscription(subscriptionId: string): Promise { const invoice = await this.subscriptionService.prepareRenewal(subscriptionId); if (!invoice) { return null; } const { paymentId, payment } = await this.tossPaymentService.payInvoice(invoice); if (payment.status === "DONE") { await this.subscriptionService.applyPayment(invoice.id, paymentId); } return payment; } } ``` 이 중간 버전의 `TossPaymentService`는 승인 결과를 저장한 내부 `paymentId`와 토스 응답을 함께 반환해요. 호출자는 이제 `renewSubscription()`만 사용하면 돼요. ```ts await subscriptionBillingFacade.renewSubscription(subscriptionId); ``` 여기까지도 의미 있는 개선이에요. 호출자가 청구서를 만들고, 결제하고, 이용 기간을 반영하는 순서를 전부 알 필요가 없어졌으니까요. 그런데 결제 결과를 사용하려고 하면 아직 문제가 남아 있어요. ## 반환값과 오류는 여전히 토스의 것이에요 앞의 Facade는 내부에서 `DONE`을 해석하고, 호출자에게도 `TossPaymentResponse`를 반환해요. 외부 오류도 그대로 올라오고요. ```ts try { const payment = await subscriptionBillingFacade.renewSubscription(subscriptionId); if (payment?.status === "DONE") { // 호출자도 토스의 응답 구조를 알아야 해요. console.log(payment.paymentKey, payment.approvedAt); } } catch (error) { if (error instanceof TossApiError && error.code === "REJECT_CARD_PAYMENT") { // 결제사의 오류 코드가 여기까지 올라와요. await paymentFailureNotifier.notify(subscriptionId); } else { throw error; } } ``` 호출은 단순해졌지만 결제사를 바꿀 때 수정할 곳은 아직 남아 있어요. Facade와 호출자 모두 토스의 응답을 알고 있기 때문이에요. 이것만으로 Facade가 틀렸다고 할 수는 없어요. Facade의 기본 목적은 하위 시스템을 쉽게 사용하게 하는 것이니까요. 다만 이 예제에서는 **결제사의 응답과 오류까지 내부 계약으로 정리해야** 변경 범위를 줄일 수 있어요. 구독 쪽에서 필요한 결과는 다음 세 가지예요. ```ts // contracts.ts export type PaymentFailureCode = "CARD_DECLINED" | "INVALID_PAYMENT_METHOD" | "PAYMENT_FAILED"; export type PaymentResult = | { status: "SUCCEEDED"; paymentId: string } | { status: "FAILED"; failureCode: PaymentFailureCode } | { status: "PENDING" }; ``` `SUCCEEDED`는 승인을 확인하고 내부 결제 기록까지 저장한 결과예요. `paymentId`는 우리 DB의 ID이고, 토스의 `paymentKey`는 결제 모듈 안에 보관해요. `FAILED`는 실패가 확인된 경우이고, `PENDING`은 처리가 진행 중이거나 결과를 아직 확정할 수 없는 경우예요. timeout이 발생해도 실제 승인은 끝났을 수 있으니 둘을 구분해야 해요. 상태 이름도 토스의 `DONE`을 빌려 오지 않았어요. 결제사와 상관없이 성공·실패·미확정만 표현하도록 우리 계약에서 정한 이름이에요. 상태마다 필요한 필드가 달라서 discriminated union을 사용했어요. `status`를 확인하면 [TypeScript의 narrowing](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#discriminated-unions)이 타입을 좁혀 주므로, 성공한 경우에만 `paymentId`를 꺼낼 수 있어요. 모든 필드를 optional로 두는 것보다 성공인데 결제 ID가 없는 데이터를 막기도 쉽고요. ## Facade에는 구독 갱신의 순서가 남아요 이제 `PaymentService`가 토스 응답 대신 `PaymentResult`를 반환하도록 바꿔 볼게요. 바뀌는 부분부터 보면, 토스의 승인 상태를 해석하던 자리에 내부 결제 결과가 들어와요. ```ts ins={6-9,11} del={2-5} // 구독 갱신 메서드의 결제 처리 부분 const { paymentId, payment } = await this.tossPaymentService.payInvoice(invoice); if (payment.status === "DONE") { await this.subscriptionService.applyPayment(invoice.id, paymentId); } const paymentResult = await this.paymentService.payInvoice(invoice); if (paymentResult.status !== "SUCCEEDED") { return; } await this.subscriptionService.applyPayment(invoice.id, paymentResult.paymentId); ``` 이제 Facade는 `DONE`이나 `paymentKey`를 알 필요가 없어요. 전체 코드도 함께 볼게요. ```ts // subscription-billing.facade.ts import { Injectable } from "@nestjs/common"; import { PaymentService } from "./payment.service"; import { SubscriptionService } from "./subscription.service"; @Injectable() export class SubscriptionBillingFacade { constructor( private readonly subscriptionService: SubscriptionService, private readonly paymentService: PaymentService, ) {} async renewSubscription(subscriptionId: string): Promise { const invoice = await this.subscriptionService.prepareRenewal(subscriptionId); if (!invoice) { return; } const paymentResult = await this.paymentService.payInvoice(invoice); // 실패했거나 결과가 미확정이면 이용 기간을 늘리지 않아요. if (paymentResult.status !== "SUCCEEDED") { return; } await this.subscriptionService.applyPayment(invoice.id, paymentResult.paymentId); } async reconcilePayment(paymentId: string): Promise { // 기존 결제의 결과를 확인해 복구해요. 새 결제를 요청하지는 않아요. const { invoiceId, result } = await this.paymentService.reconcile(paymentId); if (result.status !== "SUCCEEDED") { return; } await this.subscriptionService.applyPayment(invoiceId, result.paymentId); } } ``` 청구할 항목이 없으면 끝내고, 결제에 성공하면 해당 청구서의 이용 기간을 반영해요. 위에서 아래로 읽었을 때 구독 갱신의 흐름이 그대로 보이죠. `reconcilePayment()`도 결과를 놓친 결제를 확인한 뒤 같은 반영 경로를 사용해요. 이 Facade는 백그라운드 작업을 처리하는 Worker에서 실행해요. Worker는 `renewSubscription(subscriptionId)`를 호출하고 청구 시도를 추적할 수 있도록 작업을 기록해 둬요. 메서드 실행이 끝났다고 결제까지 성공한 것은 아니므로, 화면에서는 저장된 결제·구독 상태를 조회해요. Facade가 여러 Service를 조합하는 경우는 흔해요. 그렇다고 Service를 몇 개 이상 주입해야 Facade가 되는 것은 아니에요. 제가 본 기준은 **호출자가 복잡한 사용 순서를 반복하지 않아도 되는지**였어요. [Facade의 기본 설명](https://www.informit.com/articles/article.aspx?p=347700\&seqNum=3)도 하위 시스템을 쉽게 사용하는 데 초점을 맞추고 있어요. (이미지: Facade가 구독과 결제 Service를 연결하고, 성공한 결제만 구독에 반영하는 흐름) 호출하는 쪽은 Facade에 갱신을 한 번 요청할 뿐이에요. 결제가 성공했을 때만 구독 쪽으로 이어지고, 실패하거나 미확정인 결제는 이용 기간에 닿지 않아요. 각 객체의 역할은 이 정도로 나누면 충분해요. | 구성 요소 | 담당하는 일 | | --------------------------- | ------------------------- | | `SubscriptionBillingFacade` | 청구 준비 → 결제 → 구독 반영 순서 조합 | | `SubscriptionService` | 구독 조회, 청구서 확정, 결제된 기간 저장 | | `Subscription` | 청구 가능 여부, 요금·기간, 이용 권한 판단 | | `PaymentService` | 결제 시도 관리, 실행·조회, 결과 기록 | | `TossPaymentGateway` | 내부 결제 계약과 토스 규격 사이의 변환 | | `TossBillingClient` | HTTP 요청과 외부 데이터 검증 | 호출 방향으로 이어 보면 Worker에서 토스 API까지 한 방향으로 내려가요. ```mermaid flowchart TD J["갱신 Worker"] --> F["SubscriptionBillingFacade"] F --> S["SubscriptionService"] F --> P["PaymentService"] S --> E["Subscription Entity"] P --> G["TossPaymentGateway
PaymentGateway 구현"] G --> C["TossBillingClient
HTTP · Zod"] C --> T["토스페이먼츠 API"] ``` 실제 모여 코드에서는 이 Facade 자리를 Use Case 세 개가 나눠 맡아요. 청구 기간이 오면 `ProcessWorkspaceSubscriptionPeriod`가 청구서를 만들고, `ProcessBillingInvoiceCharge`가 결제를 요청하고, 결과를 놓친 결제는 `ReconcileBillingPayment`가 조회로 확인해요. 토스 연동은 모두 `PaymentGateway` port 뒤에 있고요. 글에서는 패턴이 잘 보이도록 이 흐름을 `SubscriptionBillingFacade` 하나로 모았어요. 예제로 돌아오면, Facade에는 구독 갱신의 순서가 남고 요금 계산과 결제 시도 관리는 각각의 객체가 맡아요. 아래 구현을 펼쳐 보면 이 책임이 어떻게 나뉘는지 확인할 수 있어요. 구독 Entity와 Service 구현 예제에서 사용할 구독 조건은 아래처럼 정할게요. | 항목 | 예제 조건 | | ----- | --------------------------- | | 월간 구독 | 한 달 10,000원(예시 금액) | | 연간 구독 | 12개월 100,000원 일괄 결제(예시 금액) | | 무료 체험 | 월간·연간 모두 가입 후 14일 | | 첫 청구 | 체험 종료 시 선택한 요금 청구 | | 만료 | 한국 시간 자정, 갱신 승인 미확인 시 무료 전환 | 금액은 계산을 쉽게 보여 주려고 정한 예시예요. 실제 모여는 워크스페이스 단위로 채널 수만큼 청구하고 유료는 3채널부터 팔아요. 2026년 10월 7일부터 Pro는 채널당 월 5,900원·연 59,000원, Team은 채널당 월 9,900원·연 99,000원이에요. 체험 14일은 실제 정책과 같아요. 이 규칙은 구독 자신의 상태를 보고 판단하는 동작이므로 `Subscription` Entity에 모을게요. NestJS나 ORM의 decorator 없이 작성한 클래스예요. ```ts // subscription.ts export class Subscription { #state: SubscriptionState; constructor(state: SubscriptionState) { // 전달받은 객체를 나중에 수정해도 구독 상태가 바뀌지 않도록 복사해요. this.#state = structuredClone(state); } get id(): string { return this.#state.id; } createRenewalInvoice(now: Date): InvoiceDraft | null { if (!this.#state.autoRenewalEnabled || now < this.#state.trialEndsAt) { return null; } const plan = PLAN_PRICES[this.#state.billingCycle]; // 첫 청구일에서 이미 반영한 유료 기간만큼 건너뛰어요. const monthsAfterFirstBilling = this.#state.completedBillingPeriods * plan.months; const periodStartsAt = getBillingDate(this.#state.firstBillingDate, monthsAfterFirstBilling); const periodEndsAt = getBillingDate( this.#state.firstBillingDate, monthsAfterFirstBilling + plan.months, ); // 청구 시점이 아직 오지 않았거나 해당 이용 기간이 모두 지났으면 청구하지 않아요. if (now < periodStartsAt || now >= periodEndsAt) { return null; } return { subscriptionId: this.#state.id, accountId: this.#state.accountId, paymentMethodId: this.#state.paymentMethodId, billingPeriodIndex: this.#state.completedBillingPeriods, amountKrw: plan.amountKrw, description: plan.description, periodStartsAt, periodEndsAt, }; } applyPaidInvoice(invoice: Invoice): void { const isExpectedInvoice = invoice.subscriptionId === this.#state.id && invoice.billingPeriodIndex === this.#state.completedBillingPeriods; if (!isExpectedInvoice) { throw new Error("현재 구독 기간에 해당하는 청구서가 아닙니다."); } // 결제 확인이 늦어져도 이용 종료일은 청구서에 정한 날짜를 유지해요. this.#state.paidUntil = new Date(invoice.periodEndsAt); this.#state.completedBillingPeriods += 1; } getAccessLevel(now: Date): AccessLevel { if (now < this.#state.trialEndsAt) { return "TRIAL"; } if (this.#state.paidUntil && now < this.#state.paidUntil) { return "PAID"; } return "FREE"; } // 저장용 데이터도 사본으로 반환해 내부 객체의 참조를 노출하지 않아요. toState(): SubscriptionState { return structuredClone(this.#state); } } ``` Entity는 외부 API를 호출하거나 DB에 저장하지 않아요. 현재 구독 상태와 전달받은 시각으로 청구서를 만들 수 있는지 판단하고, 결제가 확인되면 그 청구서의 기간을 적용해요. 상태는 JavaScript의 [private field](https://www.typescriptlang.org/docs/handbook/2/classes.html#caveats)인 `#state`에 보관해요. `id`는 조회만 가능한 getter로 공개하고, 이용 기간은 `applyPaidInvoice()`로만 바꿀 수 있어요. `paidUntil`에 원하는 날짜를 바로 대입하는 setter는 두지 않았어요. `getAccessLevel(now)`는 전달받은 시각으로 권한을 판단하므로 getter 대신 메서드로 유지해요. 필드를 숨기는 것만으로 객체의 참조까지 분리되는 것은 아니에요. 생성자로 받은 상태와 `toState()`가 반환하는 상태는 `structuredClone()`으로 복사해요. 이 상태는 일반 객체와 `Date`로 구성되어 있어서, 중첩된 날짜를 수정해도 Entity 내부에는 영향을 주지 않아요. `completedBillingPeriods`는 반영이 끝난 유료 기간의 개수예요. 첫 결제에서는 `0`이고, 결제된 기간을 반영할 때 하나씩 증가해요. `firstBillingDate`는 가입일에 14일을 더한 체험 종료일이에요. 가입할 때 한 번 정해 두고, 이후 청구일은 모두 이 날짜에서 계산해요. 한 청구 기간이 통째로 지난 구독은 밀린 요금을 자동으로 청구하지 않아요. 다시 구독하려면 새 청구 기간을 정하는 별도 흐름이 필요해요. ```ts // subscription.ts import { getBillingDate, type BillingDate } from "./billing-date"; import type { Invoice, InvoiceDraft } from "./contracts"; export type BillingCycle = "MONTHLY" | "YEARLY"; export type AccessLevel = "TRIAL" | "PAID" | "FREE"; export interface SubscriptionState { id: string; accountId: string; paymentMethodId: string; billingCycle: BillingCycle; firstBillingDate: BillingDate; completedBillingPeriods: number; autoRenewalEnabled: boolean; trialEndsAt: Date; paidUntil: Date | null; } const PLAN_PRICES = { MONTHLY: { amountKrw: 10_000, months: 1, description: "월간 구독" }, YEARLY: { amountKrw: 100_000, months: 12, description: "연간 구독" }, } as const; ``` ```ts // contracts.ts export interface InvoiceDraft { subscriptionId: string; accountId: string; paymentMethodId: string; billingPeriodIndex: number; amountKrw: number; description: string; periodStartsAt: Date; periodEndsAt: Date; } export interface Invoice extends InvoiceDraft { id: string; status: "OPEN" | "PAID"; } ``` ```ts // billing-date.ts export interface BillingDate { year: number; month: number; day: number; } export function getBillingDate(firstBillingDate: BillingDate, monthsAfter: number): Date { const targetMonth = new Date( Date.UTC(firstBillingDate.year, firstBillingDate.month - 1 + monthsAfter, 1), ); const year = targetMonth.getUTCFullYear(); const month = targetMonth.getUTCMonth(); const lastDay = new Date(Date.UTC(year, month + 1, 0)).getUTCDate(); const day = Math.min(firstBillingDate.day, lastDay); // 한국 시간 자정을 UTC로 변환해 저장해요. return new Date(Date.UTC(year, month, day, -9)); } ``` 첫 청구일에서 매번 계산하기 때문에 1월 31일에 첫 청구한 구독은 2월 말일 다음에 3월 31일로 돌아와요. 한 달을 30일로 바꾸거나, 보정된 2월 날짜에 계속 한 달씩 더하지 않아요. `trialEndsAt`은 가입 시 저장하고 체험 사용 이력도 따로 보존해요. 결제수단을 다시 등록했다고 무료 체험이 시작되어서는 안 돼요. 예제에서는 가입 후 요금제 변경은 다루지 않아요. 구독 Service에서는 조회와 저장을 연결해요. ```ts // subscription.service.ts import { Injectable } from "@nestjs/common"; import type { Invoice } from "./contracts"; import { SubscriptionRepository } from "./subscription.repository"; @Injectable() export class SubscriptionService { constructor(private readonly subscriptionRepository: SubscriptionRepository) {} async prepareRenewal(subscriptionId: string): Promise { const subscription = await this.subscriptionRepository.getById(subscriptionId); const invoiceDraft = subscription.createRenewalInvoice(new Date()); if (!invoiceDraft) { return null; } // 같은 구독 기간의 청구서가 이미 있으면 저장된 금액과 기간을 그대로 사용해요. return this.subscriptionRepository.getOrCreateInvoice(invoiceDraft); } async applyPayment(invoiceId: string, paymentId: string): Promise { await this.subscriptionRepository.transaction(async (transaction) => { const invoice = await transaction.getInvoiceForUpdate(invoiceId); // 이 청구서와 연결된 결제인지, 금액·통화가 맞고 성공했는지 확인해요. await transaction.assertSuccessfulPayment(invoice, paymentId); // 복구 작업이 반복돼도 같은 이용 기간을 두 번 반영하지 않아요. if (invoice.status === "PAID") { return; } const subscription = await transaction.getSubscriptionForUpdate(invoice.subscriptionId); subscription.applyPaidInvoice(invoice); // 이용 기간 변경과 청구서의 결제 완료 처리를 함께 저장해요. await transaction.saveSubscription(subscription); await transaction.markInvoicePaid(invoice.id, paymentId); }); } } ``` `prepareRenewal()`은 Entity의 판단을 받아 같은 구독 기간의 청구서를 한 번만 만들어요. 금액과 이용 기간은 청구서에 저장한 값을 사용해요. 나중에 가격표가 바뀌어도 이미 만든 청구서의 금액이 바뀌지는 않아요. `applyPayment()`는 실제 성공 기록이 이 청구서와 일치하는지 확인한 다음 구독을 변경해요. 청구서와 구독을 잠그고, 구독 저장과 청구서의 결제 완료 처리를 하나의 transaction으로 묶어요. 외부 결제를 기다리는 동안 DB transaction을 열어 두지는 않아요. ```ts // subscription.repository.ts import type { Invoice, InvoiceDraft } from "./contracts"; import type { Subscription } from "./subscription"; export interface SubscriptionTransaction { getInvoiceForUpdate(invoiceId: string): Promise; getSubscriptionForUpdate(subscriptionId: string): Promise; assertSuccessfulPayment(invoice: Invoice, paymentId: string): Promise; saveSubscription(subscription: Subscription): Promise; markInvoicePaid(invoiceId: string, paymentId: string): Promise; } export abstract class SubscriptionRepository { abstract getById(subscriptionId: string): Promise; abstract getOrCreateInvoice(draft: InvoiceDraft): Promise; abstract transaction(work: (transaction: SubscriptionTransaction) => Promise): Promise; } ``` `getOrCreateInvoice()`는 구독 ID와 기간 번호의 unique constraint를 사용해요. `assertSuccessfulPayment()`는 내부 결제 ID, 청구서 연결, 금액·통화, 성공 상태를 확인해요. 이미 결제된 청구서라면 연결된 결제 ID도 같아야 해요. 이 계약의 잠금과 원자성은 실제 DB 구현이 보장해야 해요. Entity만으로 동시 실행을 막을 수 있는 것은 아니에요. 결제 Service와 Repository 구현 ```ts // payment.service.ts import { Inject, Injectable } from "@nestjs/common"; import { PAYMENT_GATEWAY, type Invoice, type PaymentGateway, type PaymentResult, type GatewayPaymentResult, } from "./contracts"; import { PaymentRepository, type PaymentExecution } from "./payment.repository"; @Injectable() export class PaymentService { constructor( private readonly paymentRepository: PaymentRepository, @Inject(PAYMENT_GATEWAY) private readonly paymentGateway: PaymentGateway, ) {} async payInvoice(invoice: Invoice): Promise { // 저장된 결제 시도를 확인해 새 승인, 기존 결제 조회, 결과 반환 중 하나를 정해요. const execution = await this.paymentRepository.prepare(invoice); return this.execute(execution); } async reconcile(paymentId: string): Promise<{ invoiceId: string; result: PaymentResult }> { const payment = await this.paymentRepository.getById(paymentId); const execution = await this.paymentRepository.prepareReconciliation(paymentId); const result = await this.execute(execution); return { invoiceId: payment.invoiceId, result }; } private async execute(execution: PaymentExecution): Promise { if (execution.action === "RETURN_RESULT") { return execution.result; } const payment = execution.payment; let result: GatewayPaymentResult; try { if (execution.action === "LOOKUP") { // 승인 응답을 놓쳤을 수 있으므로 저장된 주문번호로 기존 결제를 조회해요. result = await this.paymentGateway.findPayment(payment.request); } else { result = await this.paymentGateway.charge(payment.request); } } catch (error) { // 자동으로 처리할 수 없는 연동 오류는 운영 확인 대상으로 기록해요. await this.paymentRepository.markForReview(payment); throw error; } // 승인 후 저장 실패를 외부 결제 실패로 바꾸지 않아요. return this.paymentRepository.saveResult(payment, result); } } ``` 처리한 결과가 있으면 그대로 반환하고, 결과를 놓친 요청은 조회해요. 새 결제를 실행할 때만 `charge()`를 호출해요. `action`은 실행할 동작이고 `status`는 결제 결과예요. `LOOKUP`은 기존 결제를 조회하라는 지시이고, `PENDING`은 아직 결과가 확정되지 않았다는 뜻이에요. `saveResult()`를 외부 호출의 `try/catch` 밖에 둔 것도 이유가 있어요. 승인 후 DB 저장에 실패했다고 결제까지 실패한 것은 아니에요. 그 경우 기존 결제를 조회해 복구해야 해요. ```ts // payment.repository.ts import type { GatewayPaymentResult, Invoice, PaymentRequest, PaymentResult } from "./contracts"; export interface PaymentAttempt { id: string; invoiceId: string; lockToken: string; request: PaymentRequest; } export type PaymentExecution = | { action: "RETURN_RESULT"; result: PaymentResult } | { action: "CHARGE"; payment: PaymentAttempt } | { action: "LOOKUP"; payment: PaymentAttempt }; export abstract class PaymentRepository { abstract prepare(invoice: Invoice): Promise; abstract getById(paymentId: string): Promise; abstract prepareReconciliation( paymentId: string, ): Promise>; abstract saveResult( payment: PaymentAttempt, result: GatewayPaymentResult, ): Promise; abstract markForReview(payment: PaymentAttempt): Promise; } ``` `prepare()`는 청구서와 연결된 결제 시도를 저장하고 실행을 선점해요. 이미 완료된 시도는 저장된 결과를, 다른 작업이 실행 중이면 `PENDING`을 반환해요. 응답을 놓쳤거나 실행이 중단된 시도는 `LOOKUP`으로 넘겨요. 금액·주문번호·멱등키·결제수단 ID는 처음 저장한 값을 유지해요. 시도마다 내부 결제 ID를 미리 발급하고, 승인 기록에도 같은 ID를 사용해요. 카드가 바뀌어도 진행 중인 시도는 기존 결제수단을 참조해요. 선점에는 만료 가능한 잠금과 `lockToken`을 사용해요. 저장 시에도 token을 검사해, 오래된 작업이 최신 결과를 덮어쓰지 못하게 해요. 승인 요청을 보낸 적이 있는 작업은 잠금이 만료됐다고 바로 다시 청구하지 않아요. 카드 거절이 확인된 뒤 다시 청구할 때는 별도의 시도를 만들어요. 이때도 기존 청구서에 성공한 결제가 없는지 먼저 확인해야 하죠. 예제에서는 재청구를 생략했지만, 실제 모여는 첫 실패 뒤 7일 유예를 두고 그 안에서 1일·3일·6일째에 자동으로 다시 청구해요. 모든 실패를 다시 청구하지는 않아요. 정지되거나 만료된 카드처럼 결제수단을 바꿔야 하는 거절은 같은 카드로 몇 번을 시도해도 성공하지 않으니 자동 재청구에서 빼요. 실패 사유를 `CARD_DECLINED`와 `INVALID_PAYMENT_METHOD`로 나눠 둔 이유이기도 해요. ## 토스의 응답은 결제 모듈 안에서 정리해요 `PaymentService`는 토스를 직접 호출하는 대신 `PaymentGateway` 계약을 사용해요. 토스 연동을 담당하는 `TossPaymentGateway`가 이 계약을 구현하고요. ```ts // contracts.ts export interface PaymentGateway { charge(request: PaymentRequest): Promise; findPayment(request: PaymentRequest): Promise; } export const PAYMENT_GATEWAY = Symbol("PAYMENT_GATEWAY"); ``` Gateway는 내부 요청을 토스 규격으로 바꾸고, 응답도 내부 결과로 돌려줘요. 예를 들어 승인 응답은 주문번호·금액·통화와 카드 승인 정보를 확인한 뒤 다음처럼 변환해요. ```ts // toss-payment.mapper.ts return { status: "SUCCEEDED", providerPaymentId: response.paymentKey, approvedAt: new Date(response.approvedAt), }; ``` 토스의 `DONE`이나 오류 코드는 여기서 해석해요. `providerPaymentId`는 결제 모듈에서 보관하고, `PaymentService`가 결과를 저장한 뒤 내부 `paymentId`를 반환해요. 구독 쪽에서는 토스의 거래 ID를 사용할 필요가 없어요. 외부 요청과 응답은 Zod로 검증해요. 응답의 형식이 올바른지 확인하는 것과, 그 결제가 우리 청구서와 일치하는지 판단하는 것은 구분해 두었어요. 토스 연동 흐름, Zod 검증과 Gateway 구현 먼저 실제 자동결제 흐름을 확인해 볼게요. 카드 등록과 구독료 청구는 별개의 과정이에요. 무료 체험은 앞서 정한 서비스 규칙대로 가입 시 시작해요. ```mermaid sequenceDiagram participant U as 사용자 participant W as 웹앱 participant S as 우리 서버 participant T as 토스페이먼츠 U->>W: 카드 등록 선택 W->>S: 등록 시작 요청 S-->>W: customerKey · successUrl(state 포함) · 브라우저 cookie W->>T: requestBillingAuth T-->>U: 카드 인증 후 successUrl로 redirect U->>S: successUrl 요청(authKey · customerKey · state) S->>S: 로그인 세션 · cookie · state 확인 S->>T: 빌링키 발급 요청 T-->>S: billingKey S->>S: 결제수단 저장 S-->>U: 303 redirect로 웹 화면 복귀 Note over S,T: 체험 중에는 승인 요청 없음 S->>S: 청구일에 갱신 Worker 실행 S->>T: 자동결제 승인 요청 T-->>S: 승인 결과 또는 오류 S->>S: 결제 기록 · 성공한 기간 반영 ``` [토스 자동결제 연동 가이드](https://docs.tosspayments.com/guides/v2/billing/integration)처럼 서버에서 빌링키를 발급받아 고객과 연결해 두고, 청구할 때 이 키를 사용해요. 자동결제는 별도 계약이 필요한 기능이고, 이 예제는 카드 자동결제를 기준으로 해요. `customerKey`는 서버에서 UUID처럼 추측하기 어려운 값으로 생성해요. `successUrl`도 웹 화면이 아니라 서버 API 주소(`/api/v1/billing/payment-method-authorizations/{id}/callbacks/toss-payments/success?state=...`)로 정했어요. 토스가 브라우저를 이 주소로 보내면 서버가 로그인 세션, 등록을 시작한 브라우저에 심어 둔 cookie, 주소의 `state`를 저장된 등록 기록과 대조해요. 모두 맞을 때만 빌링키를 발급받고, 끝나면 웹 화면으로 303 redirect해요. 웹앱이 `authKey`를 받아 서버로 넘기는 방식도 있지만, 모여는 서버가 콜백을 직접 받아 확인까지 한 번에 끝내요. 브라우저가 전달한 값만 보고 다른 계정에 카드를 연결하는 일이 없어야 하니까요. | 목적 | 요청 | 핵심 입력 | | ---------- | --------------------------------------- | ----------------------------------------------- | | 인증한 카드 등록 | `POST /v1/billing/authorizations/issue` | `authKey`, `customerKey` | | 등록된 카드로 청구 | `POST /v1/billing/{billingKey}` | `customerKey`, `amount`, `orderId`, `orderName` | | 기존 결제 조회 | `GET /v1/payments/orders/{orderId}` | 저장된 `orderId` | 토스가 구독 요금이나 청구 일정을 관리해 주는 것은 아니에요. 무료 체험, 월간·연간 요금, 다음 청구일은 우리 서버가 결정하고 그 시점에 승인 API를 호출해요. Gateway가 주고받는 내부 계약과, 토스 요청·응답을 검증하는 Zod 스키마예요. `PaymentGateway`는 앞에서 본 그대로라 생략했어요. ```ts // contracts.ts export interface PaymentRequest { accountId: string; paymentMethodId: string; orderId: string; amountKrw: number; description: string; idempotencyKey: string; } export type GatewayPaymentResult = | { status: "SUCCEEDED"; providerPaymentId: string; approvedAt: Date } | { status: "FAILED"; failureCode: PaymentFailureCode } | { status: "PENDING" }; ``` ```ts // toss.schema.ts import { z } from "zod"; export const tossBillingBodySchema = z.object({ // 2~50자이고, 특수문자(-, _, =, ., @)를 하나 이상 포함해야 해요. customerKey: z.string().regex(/^(?=.{2,50}$)(?=.*[-_=.@])[-A-Za-z0-9_=.@]+$/), amount: z.number().int().min(100), orderId: z.string().regex(/^[A-Za-z0-9_-]{6,64}$/), orderName: z.string().min(1).max(100), }); export const tossChargeRequestSchema = z.object({ billingKey: z.string().min(1).max(200), idempotencyKey: z.string().min(1).max(300), body: tossBillingBodySchema, }); export const tossErrorSchema = z.object({ code: z.string().min(1), message: z.string(), }); export const tossPaymentSchema = z.object({ paymentKey: z.string().min(1).max(200), orderId: z.string().min(1), type: z.string(), currency: z.string(), totalAmount: z.number().int().nonnegative(), status: z.string(), approvedAt: z.iso.datetime({ offset: true }).nullable(), card: z.object({}).nullable(), failure: tossErrorSchema.nullish(), }); export type TossChargeRequest = z.infer; export type TossPaymentResponse = z.infer; ``` 요청에서는 카드 결제의 최소 금액, 주문번호와 키의 형식을 확인해요. 응답에서는 우리가 사용하는 필드만 검증해요. 새로운 필드가 추가됐다고 실패시키지는 않지만, 금액이 문자열로 오거나 날짜가 잘못되면 그대로 사용하지 않아요. `card`는 카드 자동결제 승인인지 확인할 때 사용해요. 여기서는 상세 카드 정보를 읽지 않으므로 객체 여부만 확인해요. [Zod의 `safeParse()`](https://zod.dev/basics#handling-errors)로 검증 결과를 분기하고, `ZodError`를 구독 쪽으로 그대로 넘기지 않아요. Gateway는 필요한 값만 변환해요. ```ts // toss-payment.gateway.ts import { Injectable } from "@nestjs/common"; import type { GatewayPaymentResult, PaymentGateway, PaymentRequest } from "./contracts"; import { TossBillingClient } from "./toss-billing.client"; import { TossPaymentMethodRepository } from "./toss-payment-method.repository"; import { mapTossError, mapTossPayment } from "./toss-payment.mapper"; import type { TossPaymentResponse } from "./toss.schema"; @Injectable() export class TossPaymentGateway implements PaymentGateway { constructor( private readonly tossBillingClient: TossBillingClient, private readonly paymentMethodRepository: TossPaymentMethodRepository, ) {} async charge(request: PaymentRequest): Promise { const paymentMethod = await this.paymentMethodRepository.findForAccount( request.paymentMethodId, request.accountId, ); if (!paymentMethod) { // 이 계정의 결제수단을 찾지 못했으므로 토스에 승인 요청을 보내지 않아요. return { status: "FAILED", failureCode: "INVALID_PAYMENT_METHOD" }; } return this.send(request, "CHARGE", () => this.tossBillingClient.charge({ billingKey: paymentMethod.billingKey, idempotencyKey: request.idempotencyKey, body: { customerKey: paymentMethod.customerKey, amount: request.amountKrw, orderId: request.orderId, orderName: request.description, }, }), ); } findPayment(request: PaymentRequest): Promise { return this.send(request, "LOOKUP", () => this.tossBillingClient.findByOrderId(request.orderId), ); } private async send( request: PaymentRequest, operation: "CHARGE" | "LOOKUP", sendRequest: () => Promise, ): Promise { let response: TossPaymentResponse; try { response = await sendRequest(); } catch (error) { return mapTossError(error, operation); } return mapTossPayment(response, request); } } ``` 이 안에서는 `billingKey`와 `customerKey`를 사용해도 돼요. 실제 토스 API에 맞추는 위치니까요. 반대로 구독 Entity나 Facade까지 이 필드를 전달할 필요는 없어요. `TossPaymentMethodRepository`는 내부 결제수단 ID와 계정 ID로 키를 조회해요. 카드 변경 시에는 새 결제수단 레코드를 만들고 기존 결제 시도의 참조는 보존해요. ```ts // toss-payment.mapper.ts import { PaymentIntegrationError, type GatewayPaymentResult, type PaymentFailureCode, type PaymentRequest, } from "./contracts"; import { TossApiError, TossInvalidRequestError, TossUnconfirmedResponseError, } from "./toss-billing.client"; import type { TossPaymentResponse } from "./toss.schema"; const CARD_FAILURE_CODES = new Map([ ["REJECT_CARD_PAYMENT", "CARD_DECLINED"], ["REJECT_CARD_COMPANY", "CARD_DECLINED"], ["INVALID_REJECT_CARD", "CARD_DECLINED"], ["INVALID_STOPPED_CARD", "INVALID_PAYMENT_METHOD"], ["INVALID_CARD_EXPIRATION", "INVALID_PAYMENT_METHOD"], ]); export function mapTossPayment( response: TossPaymentResponse, request: PaymentRequest, ): GatewayPaymentResult { const matchesInvoice = response.orderId === request.orderId && response.totalAmount === request.amountKrw && response.currency === "KRW" && response.type === "BILLING"; if (!matchesInvoice) { throw new PaymentIntegrationError("승인 내역이 청구서와 일치하지 않습니다."); } switch (response.status) { case "DONE": { if (!response.approvedAt || !response.card) { throw new PaymentIntegrationError("카드 승인 정보를 확인할 수 없습니다."); } return { status: "SUCCEEDED", providerPaymentId: response.paymentKey, approvedAt: new Date(response.approvedAt), }; } case "ABORTED": return { status: "FAILED", failureCode: CARD_FAILURE_CODES.get(response.failure?.code ?? "") ?? "PAYMENT_FAILED", }; case "EXPIRED": return { status: "FAILED", failureCode: "PAYMENT_FAILED" }; case "READY": case "IN_PROGRESS": return { status: "PENDING" }; default: // 취소·부분 취소·예상하지 못한 상태는 운영 확인 대상으로 남겨요. throw new PaymentIntegrationError("별도 확인이 필요한 결제 상태입니다."); } } export function mapTossError(error: unknown, operation: "CHARGE" | "LOOKUP"): GatewayPaymentResult { if (error instanceof TossUnconfirmedResponseError) { // timeout이나 응답 해석 실패만으로 실제 승인까지 실패했다고 판단하지 않아요. return { status: "PENDING" }; } if (error instanceof TossInvalidRequestError) { throw new PaymentIntegrationError("결제 요청 값이 올바르지 않습니다.", { cause: error }); } if (!(error instanceof TossApiError)) { throw error; } const failureCode = CARD_FAILURE_CODES.get(error.code); if (operation === "CHARGE" && failureCode) { return { status: "FAILED", failureCode }; } const needsConfirmation = error.httpStatus >= 500 || error.code === "IDEMPOTENT_REQUEST_PROCESSING" || error.code === "DUPLICATED_ORDER_ID" || (operation === "LOOKUP" && error.code === "NOT_FOUND_PAYMENT"); if (needsConfirmation) { return { status: "PENDING" }; } throw new PaymentIntegrationError(undefined, { cause: error }); } ``` `DONE`인지 보기 전에 주문번호·금액·통화·결제 유형을 대조해요. 실패가 확인된 `ABORTED`·`EXPIRED`를 미확정 상태로 바꾸지 않고, 취소·부분 취소는 이 예제의 승인 흐름에서 성공 처리하지 않아요. [Payment 상태 정의](https://docs.tosspayments.com/reference#payment-객체)를 기준으로 별도 확인 대상으로 남겨요. 시크릿 키 오류, 고객 키 불일치, `INVALID_BILL_KEY_REQUEST`는 카드 거절로 단정하지 않아요. 특히 마지막 코드는 빌링 인증이나 거래의 유효성 문제도 뜻하므로 연동을 먼저 확인해야 해요. 분류는 [자동결제 오류 목록](https://docs.tosspayments.com/reference/error-codes#카드-자동결제-승인)을 기준으로 했어요. API의 5xx나 읽을 수 없는 응답은 보수적으로 조회 대상으로 남겨요. 알 수 없는 거래 상태와 연동 오류는 내부 `PaymentIntegrationError`로 전달하고, 해당 결제 시도를 운영 확인 대상으로 기록해요. ```ts // contracts.ts export class PaymentIntegrationError extends Error { constructor(message = "결제 연동을 확인해야 합니다.", options?: ErrorOptions) { super(message, options); this.name = "PaymentIntegrationError"; } } ``` ```ts // toss-payment-method.repository.ts export interface TossPaymentMethod { billingKey: string; customerKey: string; } export abstract class TossPaymentMethodRepository { abstract findForAccount( paymentMethodId: string, accountId: string, ): Promise; } ``` 운영 로그에는 내부 결제 ID와 오류 코드를 남기고, 인증 헤더나 빌링키가 들어간 URL 전체는 기록하지 않아요. 내부 오류의 `cause`도 API 응답으로 직렬화하지 않아요. ### 승인 요청 timeout을 60초로 둔 이유 [토스의 자동결제 승인 문서](https://docs.tosspayments.com/reference#자동결제-승인)는 승인에 최대 60초가 걸릴 수 있으니 timeout을 최소 60초로 설정하라고 안내해요. 그래서 **승인 요청은 60초**로 맞췄어요. 모여의 토스 Adapter는 승인 timeout이 60초보다 짧게 설정되면 생성 단계에서 거절해요. 누군가 값을 줄여도 문서의 하한 아래로 내려가지 않게 하려는 장치예요. 조회는 별도 요청이므로 10초로 정했어요. Worker의 제한 시간도 승인 대기와 결과 저장을 마칠 수 있게 잡아야 해요. 일반 HTTP 요청 전체에 같은 timeout을 적용하거나, 브라우저가 60초 동안 연결을 유지해야 한다고 가정하지는 않아요. ```ts // toss-billing.client.ts import { Inject, Injectable } from "@nestjs/common"; import { tossBillingBodySchema, tossChargeRequestSchema, tossErrorSchema, tossPaymentSchema, type TossChargeRequest, type TossPaymentResponse, } from "./toss.schema"; export class TossApiError extends Error { constructor( public httpStatus: number, public code: string, ) { super("Toss API request failed"); } } export class TossInvalidRequestError extends Error {} export class TossUnconfirmedResponseError extends Error {} export const TOSS_SECRET_KEY = Symbol("TOSS_SECRET_KEY"); const TOSS_API_URL = "https://api.tosspayments.com"; const TOSS_CHARGE_TIMEOUT_MS = 60_000; const TOSS_LOOKUP_TIMEOUT_MS = 10_000; @Injectable() export class TossBillingClient { constructor(@Inject(TOSS_SECRET_KEY) private readonly secretKey: string) {} async charge(request: TossChargeRequest): Promise { const validation = tossChargeRequestSchema.safeParse(request); if (!validation.success) { throw new TossInvalidRequestError(); } const { billingKey, idempotencyKey, body } = validation.data; return this.request( `/v1/billing/${encodeURIComponent(billingKey)}`, { method: "POST", headers: { "Idempotency-Key": idempotencyKey }, body: JSON.stringify(body), }, TOSS_CHARGE_TIMEOUT_MS, ); } async findByOrderId(orderId: string): Promise { const validation = tossBillingBodySchema.shape.orderId.safeParse(orderId); if (!validation.success) { throw new TossInvalidRequestError(); } return this.request( `/v1/payments/orders/${encodeURIComponent(validation.data)}`, { method: "GET", }, TOSS_LOOKUP_TIMEOUT_MS, ); } private async request( path: string, options: RequestInit, timeoutMs: number, ): Promise { const headers = new Headers(options.headers); const credentials = Buffer.from(`${this.secretKey}:`).toString("base64"); headers.set("Authorization", `Basic ${credentials}`); headers.set("Content-Type", "application/json"); let response: Response; let body: unknown; try { response = await fetch(`${TOSS_API_URL}${path}`, { ...options, headers, signal: AbortSignal.timeout(timeoutMs), }); body = await response.json(); } catch { throw new TossUnconfirmedResponseError(); } if (!response.ok) { const validation = tossErrorSchema.safeParse(body); if (!validation.success) { throw new TossUnconfirmedResponseError(); } throw new TossApiError(response.status, validation.data.code); } const validation = tossPaymentSchema.safeParse(body); if (!validation.success) { throw new TossUnconfirmedResponseError(); } return validation.data; } } ``` Client는 시크릿 키 뒤에 콜론을 붙여 Basic 인증 헤더를 만들어요. 요청 후 timeout이 발생해도 결제 실패로 단정하지 않고, 결과를 확정할 수 없다는 오류로 변환해요. ```ts // billing.module.ts import { Module } from "@nestjs/common"; import { PAYMENT_GATEWAY } from "./contracts"; import { PaymentService } from "./payment.service"; import { SubscriptionService } from "./subscription.service"; import { SubscriptionBillingFacade } from "./subscription-billing.facade"; import { TossBillingClient, TOSS_SECRET_KEY } from "./toss-billing.client"; import { TossPaymentGateway } from "./toss-payment.gateway"; import { BillingPersistenceModule } from "./billing-persistence.module"; @Module({ imports: [BillingPersistenceModule], providers: [ SubscriptionBillingFacade, SubscriptionService, PaymentService, TossBillingClient, { provide: PAYMENT_GATEWAY, useClass: TossPaymentGateway }, { provide: TOSS_SECRET_KEY, useFactory: () => { const secretKey = process.env.TOSS_SECRET_KEY; if (!secretKey) { throw new Error("TOSS_SECRET_KEY is required"); } return secretKey; }, }, ], exports: [SubscriptionBillingFacade], }) export class BillingModule {} ``` `BillingPersistenceModule`은 구독·결제·토스 결제수단 Repository의 DB 구현을 제공하는 모듈이에요. 외부에는 Facade를 공개하고, Gateway는 [NestJS Custom Provider](https://docs.nestjs.com/fundamentals/custom-providers)로 연결해요. ## 결제사를 바꿔도 구독 갱신 흐름은 유지돼요 처음에 던진 질문으로 돌아가서, 신규 결제를 포트원 연동으로 전환한다고 해 볼게요. 새 Gateway가 `PaymentGateway`를 구현하도록 만들고, 주입할 구현을 바꿀 수 있어요. ```ts ins={5} del={4} // BillingModule에서 신규 결제에 사용할 Gateway를 교체해요. const paymentGatewayProvider = { provide: PAYMENT_GATEWAY, useClass: TossPaymentGateway, useClass: PortOnePaymentGateway, }; ``` 새 연동의 요청과 응답 변환은 Gateway와 Client에서 구현해요. Facade의 청구 준비·결제·구독 반영 순서와 Entity의 요금·기간 계산은 유지할 수 있고요. 기존 거래는 원래 결제사에서 조회해야 해요. 그래서 전환할 때는 결제 시도에 결제사를 함께 저장하고, 그에 맞는 Gateway로 보내야 해요. 기존 빌링키가 그대로 이전되는 것도 아니라서 결제수단을 다시 등록받아야 할 수도 있고요. ### 실제로 바뀐 것은 결제사가 아니었어요 다행히 모여는 결제사를 바꾸지 않았어요. 심사를 기다리는 동안 바뀐 것은 계약 뒤쪽이었어요. 먼저 9월 25일에 토스 Adapter를 정리했어요. 청구, 카드 인증, 빌링키 발급과 해지, 결제 조회로 나뉘어 있던 Adapter 다섯 개를 `toss-payment.adapter.ts`의 `TossPaymentGateway` 하나로 합쳤어요. 이제 이 클래스가 `PaymentGateway` port 전체를 구현해요. 결제 환경도 live와 test로 나눴어요. `PaymentGatewayResolver`가 환경마다 다른 토스 키로 만든 Gateway를 골라 주는데, 운영자나 Tester가 소유한 워크스페이스는 test 환경으로 결제해요. 덕분에 카드사 심사관도 실제 청구 없이 카드 등록부터 해지까지 확인할 수 있어요. 이때 호출하는 쪽은 요청 값이 아니라 저장된 결제 기록의 환경을 넘겨요. 다른 환경의 키로 조회하거나 청구하는 일을 막으려는 선택이에요. 가장 큰 변화는 결제를 닫은 채로 출시한 일이에요. 앞에서 말한 카드사 심사가 출시일까지 끝나지 않았거든요. 결제 기능은 모두 만들어 뒀지만 `BILLING_CHECKOUT_ENABLED`의 기본값이 `false`라서 live 환경의 결제 시작은 잠겨 있어요. (이미지: 모여 요금제 화면의 Free, Pro, Team 카드와 결제는 곧 열린다는 안내) 지금 모여 요금제 화면이에요. 유료 요금제 버튼은 결제가 아니라 "Pro 신청", "Team 신청"이고, 아래에는 "결제는 곧 열려요. 가입한 뒤 워크스페이스에서 신청하면 확인하고 열어 드려요."라는 안내가 붙어 있어요. 결제가 닫혀 있는 동안 유료 요금제는 신청으로 받아요. `RequestWorkspacePlan`이 신청을 남기면 운영자가 확인해 이행하거나 거절하는 식이에요. 결제를 시작할 수 있는지는 `CheckoutAvailability` 한 곳에서만 판단해요. 구독 갱신 흐름은 이 판단을 몰라도 되니, 심사가 끝나면 코드를 고치지 않고 플래그만 켜서 결제를 열 수 있어요. ## 테스트에서는 결제 결과를 Stub으로 바꿔요 Facade 테스트에 토스의 `Payment` 객체를 만들 필요는 없어요. 결제 Service와 같은 계약을 따르는 Stub을 넣고, 성공·실패·미확정 중 어떤 결과를 반환할지만 정하면 돼요. ```ts // payment-service.stub.ts import type { Invoice, PaymentResult } from "./contracts"; import type { PaymentService } from "./payment.service"; export class PaymentServiceStub implements Pick { constructor(private result: PaymentResult | Error) {} async payInvoice(_invoice: Invoice): Promise { if (this.result instanceof Error) { throw this.result; } return this.result; } } ``` `PaymentServiceStub`은 갱신에 필요한 `payInvoice()`만 제공해요. 전달받은 결과를 그대로 반환하고, 오류를 전달하면 그 오류를 던져요. 토스의 키나 응답 구조는 전혀 필요하지 않아요. 구독 쪽은 실제 `SubscriptionService`와 Entity를 사용하고, 저장소는 데이터를 메모리에 보관하는 Fake로 바꿀게요. [Stub과 Mock의 차이](https://martinfowler.com/articles/mocksArentStubs.html)는 어떤 도구로 만들었는지보다 무엇을 대신하고 어떻게 검증하는지에 있어요. 여기서는 메서드의 호출 순서 대신, 갱신 후 청구서 상태와 이용 가능한 기간을 확인해요. Vitest로 Given/When/Then을 나누면 다음처럼 읽혀요. `createTestContext()`는 결제 Stub과 메모리 저장소를 연결하는 테스트 준비 함수예요. ```ts // subscription-billing.facade.spec.ts import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import type { PaymentResult } from "./contracts"; import { createTestContext } from "./subscription-billing.fixture"; const renewalDate = new Date("2026-10-05T00:00:00+09:00"); const periodEndsAt = new Date("2026-11-05T00:00:00+09:00"); beforeEach(() => { // 날짜에 따라 결과가 달라지지 않도록 현재 시각을 고정해요. vi.useFakeTimers(); vi.setSystemTime(renewalDate); }); afterEach(() => { vi.useRealTimers(); }); describe("구독 갱신", () => { it("무료 체험 중에는 청구하지 않는다", async () => { // Given vi.setSystemTime(new Date("2026-10-04T23:59:59+09:00")); // 결제를 시도하면 즉시 실패하는 Stub으로 불필요한 청구를 잡아요. const { facade, repository } = await createTestContext( new Error("무료 체험 중에는 결제를 요청하면 안 됩니다."), ); // When await facade.renewSubscription("subscription_001"); // Then expect(repository.invoice).toBeNull(); const subscription = await repository.getById("subscription_001"); expect(subscription.getAccessLevel(new Date())).toBe("TRIAL"); }); it("결제에 성공하면 청구한 한 달 동안 유료 기능을 이용할 수 있다", async () => { // Given const { facade, repository } = await createTestContext({ status: "SUCCEEDED", paymentId: "payment_001", }); // When await facade.renewSubscription("subscription_001"); // Then const subscription = await repository.getById("subscription_001"); expect(repository.invoice?.status).toBe("PAID"); expect(subscription.getAccessLevel(renewalDate)).toBe("PAID"); expect(subscription.getAccessLevel(new Date(periodEndsAt.getTime() - 1))).toBe("PAID"); expect(subscription.getAccessLevel(periodEndsAt)).toBe("FREE"); }); it.each([ { status: "FAILED", failureCode: "CARD_DECLINED" }, { status: "PENDING" }, ])("결과가 $status이면 유료 이용 기간을 부여하지 않는다", async (paymentResult) => { // Given const { facade, repository } = await createTestContext(paymentResult); // When await facade.renewSubscription("subscription_001"); // Then const subscription = await repository.getById("subscription_001"); expect(repository.invoice?.status).toBe("OPEN"); expect(subscription.getAccessLevel(renewalDate)).toBe("FREE"); }); }); ``` 성공하면 청구서가 결제 완료 상태가 되고, 청구한 기간 동안 유료 기능을 이용할 수 있어요. 실패하거나 결과를 확정하지 못했다면 무료 상태를 유지해요. 무료 체험 중에는 결제를 요청하면 오류가 나는 Stub을 넣어, 불필요한 청구도 잡아내요. 이렇게 계약이 정리되어 있으면 AI로 테스트 초안을 만들 때도 편해요. Facade 코드와 `PaymentResult`를 보여 주고, 결제 결과별로 어떤 상태가 되어야 하는지 알려 주면 돼요. 토스의 복잡한 응답을 매번 설명할 필요 없이, Stub의 반환값을 바꾸며 성공·거절·미확정 시나리오를 작성할 수 있어요. 생성된 테스트를 읽는 기준도 분명해져요. 결제에 성공한 기간만 유료로 열리는지, 미확정 결제에 권한을 부여하지 않는지 보면 되니까요. **계약과 기대 결과**가 분명할수록 AI가 만든 테스트도 검토하고 고치기 쉬워요. `vi`는 현재 시각을 고정하는 데만 사용했어요. `vi.fn()`이나 호출 횟수 검증 없이도 구독 갱신의 결과를 확인할 수 있어요. 요금과 날짜 계산은 Entity 테스트에서 따로 검증해요. Gateway와 Client에서는 승인·거절·미확정 응답, Zod 검증, 금액 불일치, 토스 오류 변환을 따로 확인해요. 저장소의 잠금과 unique constraint는 실제 DB를 사용하는 integration test가 필요해요. 메모리 Fake로 검증하는 범위에는 DB의 동시성이 포함되지 않아요. Stub 연결, 메모리 저장소와 Vitest 설정 `SubscriptionService`는 실제 객체를 사용하고 `PaymentService`만 Stub으로 주입해요. 성공 시나리오에는 성공한 결제 기록도 미리 준비해요. `SUCCEEDED`가 내부 결제 기록까지 저장된 상태라는 계약에 맞추기 위해서예요. ```ts // subscription-billing.fixture.ts import { Test } from "@nestjs/testing"; import { onTestFinished } from "vitest"; import type { Invoice, InvoiceDraft, PaymentResult } from "./contracts"; import { PaymentService } from "./payment.service"; import { PaymentServiceStub } from "./payment-service.stub"; import { Subscription } from "./subscription"; import { SubscriptionService } from "./subscription.service"; import { SubscriptionRepository, type SubscriptionTransaction } from "./subscription.repository"; import { SubscriptionBillingFacade } from "./subscription-billing.facade"; interface SavedPayment { id: string; invoiceId: string; amountKrw: number; currency: "KRW"; } // 상태를 메모리에 보관하는 Fake예요. DB의 잠금과 transaction은 재현하지 않아요. class InMemorySubscriptionRepository extends SubscriptionRepository { invoice: Invoice | null = null; constructor( private subscription: Subscription, private successfulPayment: SavedPayment | null, ) { super(); } async getById(subscriptionId: string): Promise { if (subscriptionId !== this.subscription.id) { throw new Error("구독을 찾을 수 없습니다."); } return this.subscription; } async getOrCreateInvoice(draft: InvoiceDraft): Promise { this.invoice ??= { ...draft, id: "invoice_001", status: "OPEN" }; return this.invoice; } async transaction(work: (transaction: SubscriptionTransaction) => Promise): Promise { const transaction: SubscriptionTransaction = { getInvoiceForUpdate: async (invoiceId) => { if (!this.invoice || this.invoice.id !== invoiceId) { throw new Error("청구서를 찾을 수 없습니다."); } return this.invoice; }, getSubscriptionForUpdate: (subscriptionId) => this.getById(subscriptionId), assertSuccessfulPayment: async (invoice, paymentId) => { const payment = this.successfulPayment; if ( !payment || payment.id !== paymentId || payment.invoiceId !== invoice.id || payment.amountKrw !== invoice.amountKrw || payment.currency !== "KRW" ) { throw new Error("청구서와 일치하는 성공한 결제가 없습니다."); } }, saveSubscription: async (subscription) => { this.subscription = subscription; }, markInvoicePaid: async (invoiceId, paymentId) => { if ( !this.invoice || this.invoice.id !== invoiceId || this.successfulPayment?.id !== paymentId ) { throw new Error("청구서에 결제를 연결할 수 없습니다."); } this.invoice.status = "PAID"; }, }; return work(transaction); } } export async function createTestContext(paymentResult: PaymentResult | Error) { const subscription = new Subscription({ id: "subscription_001", accountId: "account_001", paymentMethodId: "method_001", billingCycle: "MONTHLY", // 9월 21일 가입, 14일 체험 뒤 10월 5일이 첫 청구일이에요. firstBillingDate: { year: 2026, month: 10, day: 5 }, completedBillingPeriods: 0, autoRenewalEnabled: true, trialEndsAt: new Date("2026-10-05T00:00:00+09:00"), paidUntil: null, }); // SUCCEEDED는 내부 결제 기록까지 저장한 결과이므로 해당 기록도 준비해요. const successfulPayment: SavedPayment | null = !(paymentResult instanceof Error) && paymentResult.status === "SUCCEEDED" ? { id: paymentResult.paymentId, invoiceId: "invoice_001", amountKrw: 10_000, currency: "KRW", } : null; const repository = new InMemorySubscriptionRepository(subscription, successfulPayment); const module = await Test.createTestingModule({ providers: [ SubscriptionBillingFacade, SubscriptionService, { provide: SubscriptionRepository, useValue: repository }, { provide: PaymentService, useValue: new PaymentServiceStub(paymentResult) }, ], }).compile(); onTestFinished(() => module.close()); return { repository, facade: module.get(SubscriptionBillingFacade), }; } ``` 메모리 저장소는 이번 시나리오에 필요한 조회·저장만 구현했어요. transaction의 rollback이나 동시 실행까지 흉내 내지는 않아요. [NestJS의 Vitest 안내](https://docs.nestjs.com/recipes/swc#vitest)에 따라 SWC로 decorator metadata를 처리해요. 타입 검사는 별도로 실행하고요. ```ts // vitest.config.ts import { defineConfig } from "vitest/config"; import swc from "unplugin-swc"; export default defineConfig({ test: { environment: "node", globals: false, }, plugins: [ swc.vite({ jsc: { parser: { syntax: "typescript", decorators: true }, transform: { legacyDecorator: true, decoratorMetadata: true }, }, module: { type: "es6" }, }), ], }); ``` 이 예제는 작성 당시(2026년 9월) NestJS 12.0.1과 Vitest로 확인했어요. 지금 모여는 NestJS 12.1.3과 Vitest 5.0.4를 써요. `reflect-metadata`는 NestJS가 내부에서 불러오므로 테스트마다 import할 필요는 없어요. 패키지 의존성과 SWC의 decorator metadata 설정은 유지해요. ## 빠르게 만드는 것과 계속 빠르게 만드는 것 AI로 개발하면서 이 차이를 자주 생각해요. 눈에 보이는 기능을 만드는 일은 이제 AI가 저보다 빠를 때가 많아요. 다만 제가 구조를 이해하지 못한 채 결과만 받아들이면, 서비스가 커졌을 때 어디를 고쳐야 할지 모르는 순간이 올 것 같아요. 당장의 구현 속도에 만족하는 사이 기술 부채도 빠르게 쌓일 수 있고요. 초기 스타트업은 PMF를 찾으려고 빨리 만들고 검증해야 해요. 처음부터 완벽한 설계를 하는 건 불가능하고, 무엇을 완벽하다고 보는지도 사람과 서비스마다 다를 거예요. 그래도 결제처럼 돈과 이용 권한이 걸린 로직은 흐름을 설명하고 고칠 수 있을 만큼은 구조를 잡아 둬야 한다고 생각해요. 요구사항이 바뀌거나 결제에서 장애가 났을 때 원인을 찾고 영향 범위를 확인해 수정할 수 있어야 하니까요. 처음에 구조를 고민하는 시간은 조금 더 들어도, 이후의 변경과 장애 대응에 드는 시간은 줄어든다고 봐요. (이미지: 시간이 흐르며 달라지는 두 개발 방식의 누적 구현량) 곡선의 기울기는 개발 속도, 높이는 그동안 구현한 양이에요. 구조를 미룬 쪽은 처음에 빠르게 올라가지만, 변경 비용이 쌓이면서 점점 평평해져요. 실제로 측정한 값이 아니라 이 차이를 설명하려고 그린 개념도예요. 이 예제에서는 그 출발점으로 Facade를 도입했어요. AI가 코드를 빠르게 작성해 주더라도, **무엇이 바뀔 때 어디를 고쳐야 하는지**는 제가 이해하고 싶었어요. 언젠가는 이런 판단까지 AI가 더 잘할지도 모르겠지만, 지금은 제가 설명할 수 있는 구조 안에서 함께 개발하려고 해요. ## Facade를 만들 때 놓치기 쉬운 것들 ### 외부 API를 그대로 옮겨 놓기 `issueBillingKey()`, `approveBillingPayment()`를 같은 클래스에 모아도 호출자가 실행 순서를 알아야 한다면 단순화한 범위가 작아요. 이 글에서는 `renewSubscription()`처럼 호출자가 하려는 일을 표현했어요. ### 관련 기능을 전부 넣기 구독 갱신에 필요하다고 할인, 이메일, 통계, 환불까지 한 Facade에 넣을 필요는 없어요. 이 Facade는 청구와 구독 반영이라는 응집된 흐름을 맡고, 계산과 저장은 해당 객체에 남겨요. ### 꼭 구분할 차이까지 숨기기 카드 거절과 timeout을 모두 `false`로 반환하면 다음 행동을 정할 수 없어요. 내부 계약을 단순하게 만들더라도 확인된 실패와 미확정 결과는 구분해야 해요. 그래서 `PENDING`을 따로 두었어요. 승인 결과를 놓쳤다면 기존 결제를 조회하고, 성공을 확인한 뒤 같은 구독 반영 경로로 보내요. 이때 이용 기간은 확인한 시각이 아니라 원래 청구서를 기준으로 적용해요. 이용 기간 만료와 미확정 결제의 복구 예를 들어 9월 21일에 가입했다면 14일 체험은 10월 5일 `00:00`에 끝나요. 월간 결제가 성공하면 11월 5일 `00:00`까지, 연간 결제가 성공하면 다음 해 10월 5일 `00:00`까지 이용할 수 있어요. 결제 시각부터 정확히 30일을 더하는 방식은 아니에요. 예제에서는 첫 청구일의 한국 시간 자정을 기준으로 정했으므로 화면에도 종료 시각을 안내해요. 자정 배치가 유료 여부를 바꿀 때까지 기다리는 대신, 서버의 권한 검사에서 `subscription.getAccessLevel(now)`로 종료 시각을 확인해요. `<`로 비교하므로 종료 시각에 도달하면 기존 권한은 끝나요. 예제는 유예 없이 단순화했으므로, 갱신 승인을 아직 확인하지 못했다면 무료 플랜을 적용해요. 그래서 승인 확인 전까지 잠깐 무료로 보일 수 있어요. 실제 모여는 결제가 실패해도 바로 낮추지 않고 7일 유예를 둬요. 유예 동안은 유료 한도를 유지하면서 자동으로 다시 청구하고, 그래도 결제되지 않은 채 유예가 끝나면 이용을 제한해요. 이용 권한이 끝났다고 진행 중인 결제까지 실패한 것은 아니에요. 미확정 결제는 별도 Worker가 조회하고, 확인된 승인은 같은 구독 반영 경로로 보내요. ```ts // reconcile-payment.job.ts // 미확정 결제를 조회하는 Worker에서 호출해요. await subscriptionBillingFacade.reconcilePayment(paymentId); ``` 앞서 만든 `reconcilePayment()`를 Worker가 내부 결제 ID로 호출해요. 갱신을 해제했거나 기존 이용 기간이 끝났어도 이미 보낸 결제의 확인은 계속되어야 해요. 결제 결과는 토스가 보내는 webhook으로도 들어와요. webhook 주소에는 환경별 endpoint token을 넣어 두고, 컨트롤러가 이 token부터 검증해요. 결제 상태 변경(`PAYMENT_STATUS_CHANGED`)과 빌링키 삭제(`BILLING_DELETED`)는 각각의 Use Case가 provider event inbox에 넣고, 같은 주문·상태로 다시 온 알림은 inbox에서 한 건으로 묶어요. 결제 상태 변경 알림에는 서명이 없어요. 그래서 알림에 적힌 상태를 그대로 믿지 않고, Worker가 토스 조회로 사실을 확인한 뒤에만 결제 기록을 바꿔요. 반대로 승인 기록은 저장됐는데 구독 반영만 실패했다면, 성공한 결제와 미반영 청구서를 찾아 `SubscriptionService.applyPayment()`를 다시 실행해요. 결제를 다시 요청할 필요는 없어요. 복구된 권한의 종료일은 확인한 시각에 한 달을 더한 값이 아니라 원래 청구서의 `periodEndsAt`이에요. 이미 그 기간까지 지났다면 권한을 새로 늘리지 않고, 결제·서비스 제공 내역을 운영자가 확인해요. [토스의 멱등키 규칙](https://docs.tosspayments.com/reference/using-api/authorization#멱등키-헤더)에 따르면 같은 키로 동일한 요청을 재전송할 수 있고, 키는 최초 사용일부터 15일간 유효해요. 이 예제는 미확정 요청을 먼저 조회하는 방식으로 처리해요. 새 키로 바로 재청구하지 않아요. `DUPLICATED_ORDER_ID`도 기존 승인·취소 거래가 있다는 신호이므로 먼저 내역을 확인해요. 조회 한 번에 결제가 없다고 나왔다고 해서 즉시 미승인으로 확정하지 않아요. 조회 횟수와 간격을 제한하고 계속 확인되지 않는 시도는 운영 확인 대상으로 남겨요. ## 마지막으로, Facade와 Adapter는 목적이 달라요 둘 다 다른 객체를 감싸지만 사용하는 목적은 달라요. | 패턴 | 목적 | 이 예제에서 하는 일 | | ------- | ------------------ | ------------------------------------ | | Facade | 복잡한 사용 과정을 단순하게 제공 | 구독 Service와 결제 Service를 조합해 갱신 기능 제공 | | Adapter | 서로 다른 인터페이스를 맞춤 | 토스 규격을 `PaymentGateway` 계약에 맞게 변환 | 코드로 보면 차이가 더 분명해요. Facade를 사용하는 쪽에서는 다음 호출 하나로 구독을 갱신해요. ```ts // 청구 준비 → 결제 → 구독 반영 순서는 Facade가 조합해요. await subscriptionBillingFacade.renewSubscription(subscriptionId); ``` 반면 Adapter는 호출자가 기대하는 인터페이스에 다른 객체를 맞춰 줘요. 앞서 만든 `TossPaymentGateway`에서 조회 기능만 간추려 볼게요. ```ts {10,17} // adapter-example.ts class TossPaymentGateway { constructor(private readonly tossBillingClient: TossBillingClient) {} async findPayment(request: PaymentRequest): Promise { let response: TossPaymentResponse; try { // 내부 요청에서 주문번호를 꺼내 토스 Client의 조회 방식에 맞춰요. response = await this.tossBillingClient.findByOrderId(request.orderId); } catch (error) { // 토스의 오류도 내부 결제 결과나 연동 오류로 변환해요. return mapTossError(error, "LOOKUP"); } // 토스의 응답을 검증한 뒤 우리 결제 계약으로 바꿔요. return mapTossPayment(response, request); } } ``` `PaymentService`는 `findPayment(request)`라는 내부 계약을 사용해요. Gateway는 그 요청을 받아 토스 Client의 `findByOrderId(orderId)`를 호출하고, 응답과 오류를 우리 계약에 맞춰 돌려줘요. 이처럼 메서드와 입력·출력의 차이를 맞추는 것이 Adapter의 역할이에요. 예를 들어 토스의 `DONE`은 `SUCCEEDED`로, `paymentKey`는 결제 모듈에서 사용하는 `providerPaymentId`로 바뀌어요. 앞서 작성한 `mapTossPayment()`가 주문번호·금액을 대조하고 이 변환을 처리해요. 구독 기간을 계산하거나 갱신 순서를 조합하지는 않아요. 그래서 `TossPaymentGateway`는 Adapter 역할을 한다고 볼 수 있어요. 실제 모여 코드에서도 이 클래스는 `toss-payment.adapter.ts`에 있어요. 결제사를 바꾸면 새 연동도 같은 `PaymentGateway` 계약에 맞추고, Facade는 청구 준비·결제·구독 반영이라는 흐름을 그대로 사용해요. 정리하면 Facade는 **사용 과정을 단순하게** 만들고, Adapter는 **서로 다른 인터페이스를 맞춰요**. 함께 쓸 수 있지만 목적이 다른 패턴이에요. 모여의 결제는 지금도 카드사 심사를 기다리며 닫혀 있어요. 그사이 토스 Adapter를 합치고 live와 test 환경을 나눴지만, 구독을 다루는 Use Case는 여전히 `PaymentGateway` 계약만 알아요. 기능이 늘어도 사용하는 쪽은 내부 사정을 몰라도 되게 하는 것, Facade로 얻고 싶었던 것도 그거였어요. --- # API 요청 한 번에도 연결 비용이 있다 — 실무에서 이해하는 HTTP Keep-Alive > 안녕하세요. 최근 NestJS 서버에서 외부 API 호출 구조를 살펴보면서 HTTP Keep-Alive를 공부하게 되었어요. 처음에는 Keep-Alive를 단순히 “연결을 오래 유지하는 옵션” 정도로 생각했어요. 하지만 실제 서버 구조를 떠올려 보면 Keep-Alive는 단순한 미... - 원문: https://www.yolog.co.kr/post/http-keep-alive - 카테고리: HTTP - 발행: 2026-09-05 - 수정: 2026-10-01 안녕하세요. 최근 NestJS 서버에서 외부 API 호출 구조를 살펴보면서 HTTP Keep-Alive를 공부하게 되었어요. 처음에는 Keep-Alive를 단순히 “연결을 오래 유지하는 옵션” 정도로 생각했어요. 하지만 실제 서버 구조를 떠올려 보면 Keep-Alive는 단순한 미세 최적화가 아니에요. 우리가 만드는 서버는 보통 혼자 동작하지 않거든요. ```mermaid flowchart LR U[사용자] --> API[우리 API 서버] API --> AUTH[인증 서버] API --> MEMBER[회원 서버] API --> PAYMENT[결제 API] API --> NOTI[알림 서버] API --> SOCIAL[소셜 플랫폼 API] API --> AI[AI API] ``` 사용자 요청 하나를 처리하면서 여러 서버에 HTTP 요청을 보낼 수도 있어요. 이때 요청마다 TCP 연결을 새로 만든다면 실제 비즈니스 로직과 관계없는 연결 비용이 계속 쌓일 수 있어요. 이번 글에서는 TCP 연결부터 시작해 HTTP Keep-Alive가 왜 필요한지 알아볼게요. 그런 다음 NestJS와 Axios로 직접 실행할 수 있는 작은 예제를 만들고, 코드가 어떤 결과를 만드는지 순서대로 확인해 보려고 해요. ## HTTP 요청을 보내기 전에 일어나는 일 HTTP/1.1 요청은 일반적으로 TCP 연결 위에서 전달돼요. 클라이언트가 서버에 HTTP 요청을 보내려면 먼저 둘 사이에 TCP 연결이 만들어져야 하죠. ```mermaid flowchart TB HTTP["HTTP
URL, Method, Header, Body"] TLS["TLS
인증과 암호화 · HTTPS인 경우"] TCP["TCP
연결, 순서 보장, 재전송"] IP["IP
목적지까지 패킷 전달"] HTTP --> TLS --> TCP --> IP ``` HTTP는 어떤 URL에 어떤 메서드와 데이터를 보낼지 정의하고, TCP는 그 HTTP 메시지가 이동할 수 있는 안정적인 통신 경로를 만들어요. 전화 통화로 비유하면 IP 주소는 회사 건물의 주소, Port는 내선번호, TCP 연결은 실제 전화 연결, HTTP 요청은 전화가 연결된 뒤 나누는 대화에 가까워요. TCP는 연결을 만들 때 3-way handshake를 수행해요. ```mermaid sequenceDiagram participant C as Client participant S as Server Note over C,S: TCP 3-way handshake C->>S: SYN S-->>C: SYN + ACK C->>S: ACK Note over C,S: TCP 연결 준비 완료 C->>S: HTTP Request S-->>C: HTTP Response ``` 클라이언트가 연결을 요청하는 `SYN`을 보내고, 서버가 `SYN + ACK`로 응답한 뒤, 클라이언트가 다시 `ACK`를 보내면 비로소 데이터를 주고받을 준비가 끝나요. 이 과정에는 네트워크 왕복이 필요해요. HTTPS라면 TCP 연결 뒤에 TLS handshake도 추가되기 때문에 연결을 준비하는 비용은 더 커지고요. API 요청을 한 번만 보낼 때는 크게 느껴지지 않을 수 있지만, 서버 사이에서 짧은 요청이 계속 발생한다면 이야기가 달라져요. ## Round Trip은 무엇일까요? 네트워크를 공부하다 보면 **Round Trip** 또는 \*\*RTT(Round-Trip Time)\*\*라는 표현을 자주 만나게 돼요. 데이터가 클라이언트에서 서버로 갔다가 다시 클라이언트로 돌아오는 왕복과 그 시간을 뜻해요. ```mermaid sequenceDiagram participant C as Client participant S as Server C->>S: 30ms S-->>C: 30ms Note over C,S: RTT ≈ 60ms ``` 새 TCP 연결에서 첫 HTTP 요청을 보낼 때 드는 비용을 단순화하면 다음과 같아요. ```text TCP 연결을 만들기 위한 왕복 + HTTP 요청과 응답을 위한 왕복 + 서버의 실제 처리 시간 ``` HTTPS라면 서버 인증과 암호화 정보를 교환하는 TLS handshake도 필요해요. 반대로 기존 TCP 연결을 재사용하면 TCP 연결을 만드는 단계는 건너뛸 수 있어요. Keep-Alive가 HTTP 요청 자체의 왕복이나 서버의 처리 시간을 없애주는 것은 아니에요. **같은 서버에 요청할 때마다 TCP 연결을 다시 만드는 비용**을 줄여주는 기능이에요. ## 요청마다 연결을 새로 만든다면? 한 서버가 같은 외부 API를 세 번 호출한다고 가정해 볼게요. 각 요청이 독립된 TCP 연결을 사용한다면 아래와 같은 흐름이 반복돼요. ```mermaid sequenceDiagram participant C as Client participant S as Server rect rgb(255, 245, 245) Note over C,S: 첫 번째 요청 C->>S: TCP 연결 생성 C->>S: HTTP 요청 1 S-->>C: HTTP 응답 1 C-xS: TCP 연결 종료 end rect rgb(255, 245, 245) Note over C,S: 두 번째 요청 C->>S: TCP 연결 생성 C->>S: HTTP 요청 2 S-->>C: HTTP 응답 2 C-xS: TCP 연결 종료 end rect rgb(255, 245, 245) Note over C,S: 세 번째 요청 C->>S: TCP 연결 생성 C->>S: HTTP 요청 3 S-->>C: HTTP 응답 3 C-xS: TCP 연결 종료 end ``` HTTP 요청 자체는 금방 처리되더라도, 매번 TCP handshake를 기다려야 해요. 연결을 만들고 닫는 과정에서 클라이언트와 서버의 CPU도 사용하고, 짧은 연결이 한꺼번에 늘어나면 소켓과 포트 같은 운영체제 자원에도 부담을 줄 수 있어요. 예를 들어 주문 상세 API가 회원, 주문, 결제 서버를 각각 호출한다면 사용자 요청 하나가 여러 TCP 연결 생성으로 이어질 수 있어요. 트래픽이 갑자기 늘거나 새 서버 인스턴스들이 빈 연결 풀에서 동시에 시작하면 새 연결 생성도 한꺼번에 증가할 수 있고요. 이런 현상을 흔히 connection storm이라고 불러요. 그렇다면 이미 만든 연결을 다음 요청에서도 사용할 수는 없을까요? ## HTTP Keep-Alive로 연결 재사용하기 HTTP Keep-Alive는 하나의 HTTP 요청과 응답이 끝난 뒤에도 TCP 연결을 바로 닫지 않고, 다음 요청에서 다시 사용하는 방식이에요. ```mermaid sequenceDiagram participant C as Client participant S as Server C->>S: TCP 연결 생성 rect rgb(242, 250, 245) C->>S: HTTP 요청 1 S-->>C: HTTP 응답 1 Note over C,S: 연결을 닫지 않고 유지 C->>S: HTTP 요청 2 S-->>C: HTTP 응답 2 Note over C,S: 같은 연결을 다시 사용 C->>S: HTTP 요청 3 S-->>C: HTTP 응답 3 end C-xS: TCP 연결 종료 ``` 이제 TCP 연결은 처음에 한 번만 만들면 돼요. 두 번째 요청부터는 이미 준비된 연결을 가져와 바로 데이터를 보낼 수 있죠. 같은 서버로 요청을 자주 보내는 서비스일수록 이 차이가 쌓여 응답 지연과 연결 생성 비용을 줄이는 데 도움이 돼요. 여기서 한 가지 주의할 점이 있어요. HTTP/1.1은 지속 연결을 기본으로 사용하지만, 애플리케이션에서 실제로 연결이 재사용되려면 클라이언트가 사용 가능한 소켓을 보관하고 관리해야 해요. Node.js에서는 이 역할을 `http.Agent`와 `https.Agent`가 담당해요. ## Keep-Alive는 연결 하나만 사용하는 기능이 아니에요 Keep-Alive를 처음 접하면 모든 요청을 TCP 연결 하나로 처리한다고 생각하기 쉬워요. 하지만 정확한 의미는 **필요한 만큼 연결을 만들되, 사용이 끝난 연결을 바로 버리지 않고 이후 요청에서 재사용하는 것**이에요. 요청을 하나씩 순차 실행하면 연결 하나로 충분할 수 있어요. ```ts await api.get('/users'); await api.get('/posts'); await api.get('/comments'); ``` ```text /users → TCP #1 생성 /posts → TCP #1 재사용 /comments → TCP #1 재사용 ``` 반면 세 요청을 동시에 실행하면 첫 번째 소켓이 사용 중인 동안 다른 요청을 처리할 소켓이 더 필요할 수 있어요. ```ts await Promise.all([ api.get('/users'), api.get('/posts'), api.get('/comments'), ]); ``` ```text /users → TCP #1 /posts → TCP #2 /comments → TCP #3 ``` 요청이 끝난 뒤 TCP #1, #2, #3은 다음 요청에서 다시 쓸 수 있는 free socket이 돼요. Keep-Alive는 “연결 하나만 사용하기”가 아니라 “만들어진 연결을 버리지 않고 풀에서 재사용하기”에 가까워요. ## HTTP Keep-Alive와 TCP Keepalive는 달라요 이름이 비슷해서 자주 혼동되는 개념도 있어요. * **HTTP Keep-Alive**는 여러 HTTP 요청이 하나의 TCP 연결을 재사용하도록 해요. * **TCP Keepalive**는 오랫동안 데이터가 오가지 않는 TCP 연결이 아직 살아 있는지 운영체제 수준에서 확인해요. 즉, HTTP Keep-Alive의 관심사는 **연결 재사용**이고 TCP Keepalive의 관심사는 **죽은 연결 감지**예요. Node.js Agent의 `keepAlive: true`는 소켓을 재사용할 수 있도록 관리하며, `keepAliveMsecs`는 TCP keepalive probe를 시작할 때 사용하는 초기 지연값이에요. 이름만 보고 `keepAliveMsecs`를 “소켓을 풀에 30초 동안 보관하는 설정”으로 이해하면 안 돼요. ## Node.js에서 연결 풀 만들기 Node.js에서는 `http.Agent`와 `https.Agent`가 소켓을 관리해요. 쉽게 말하면 Agent는 TCP connection pool 관리자예요. ```mermaid flowchart TD R[새 HTTP 요청] --> F{같은 목적지의
free socket이 있는가?} F -->|있다| REUSE[기존 socket 재사용] F -->|없다| CAP{새 socket을
만들 수 있는가?} CAP -->|있다| NEW[새 TCP 연결 생성] CAP -->|없다| WAIT[Agent 대기열에서 기다림] ``` Agent 내부에는 현재 요청에 사용 중인 active socket, 요청을 마치고 기다리는 free socket, 소켓을 기다리는 pending request가 있어요. 이제 HTTP와 HTTPS 요청에 사용할 Agent를 한 번 만들어 재사용해 볼게요. ```ts import http from 'node:http'; import https from 'node:https'; export const httpAgent = new http.Agent({ keepAlive: true, keepAliveMsecs: 30_000, maxSockets: 128, maxFreeSockets: 32, }); export const httpsAgent = new https.Agent({ keepAlive: true, keepAliveMsecs: 30_000, maxSockets: 128, maxFreeSockets: 32, }); ``` 각 설정의 역할은 다음과 같아요. * `keepAlive`: 요청이 끝난 소켓을 바로 없애지 않고 다음 요청에서 재사용해요. * `keepAliveMsecs`: 유휴 소켓에 TCP keepalive probe를 시작할 초기 지연값을 지정해요. * `maxSockets`: 대상 호스트 하나에 동시에 열 수 있는 소켓 수를 제한해요. * `maxFreeSockets`: 요청을 처리하지 않고 풀에서 기다릴 수 있는 유휴 소켓 수를 제한해요. `maxSockets`를 무조건 크게 잡는 것이 좋은 것은 아니에요. 값이 너무 크면 순간적으로 많은 연결이 만들어져 상대 서버에 부담을 줄 수 있고, 너무 작으면 요청이 소켓을 기다리며 대기할 수 있어요. 트래픽과 상대 서버의 처리 용량을 함께 보고 정해야 해요. ## Axios가 같은 Agent를 사용하게 만들기 Agent를 만들기만 해서는 충분하지 않아요. Axios 인스턴스에 Agent를 연결하고, 이 인스턴스를 애플리케이션에서 계속 공유해야 해요. ```ts import axios from 'axios'; import { httpAgent, httpsAgent } from './agents'; export const apiClient = axios.create({ baseURL: 'http://localhost:3000', timeout: 3_000, httpAgent, httpsAgent, }); ``` HTTP 요청에는 `httpAgent`, HTTPS 요청에는 `httpsAgent`가 사용돼요. 여기서 중요한 점은 요청마다 Agent나 Axios 인스턴스를 새로 만들지 않는 거예요. 위 코드처럼 모듈의 최상위에서 한 번 만든 `apiClient`를 공유해야 이전 요청이 남긴 소켓을 다음 요청에서 사용할 수 있어요. 여기서 `keepAliveMsecs`의 단위는 밀리초이므로 `30_000`은 30초예요. 다만 이 값은 HTTP 연결을 풀에 30초 동안 보관한다는 뜻이 아니라 TCP keepalive probe의 초기 지연값이에요. Axios의 `timeout: 3_000`도 연결의 수명이 아니에요. 현재 진행 중인 HTTP 요청을 최대 3초 기다린다는 뜻이에요. 요청이 끝난 뒤 free socket이 얼마나 살아 있을지는 Agent, 서버, 중간 네트워크 장비의 별도 생명주기에 따라 결정돼요. 또한 Agent는 목적지별로 소켓 풀을 구분해요. 단순화하면 프로토콜, 호스트, 포트가 달라지면 서로 다른 연결을 사용해요. ```text http://localhost:3000 http://localhost:3001 https://localhost:3000 https://api.example.com:443 ``` 결제 API에 연결한 소켓을 소셜 플랫폼 API 요청에 재사용할 수는 없어요. ## 정말 같은 소켓을 사용할까? 이제 연결이 실제로 재사용되는지 확인할 차례예요. 먼저 호출을 받을 upstream 역할의 간단한 API를 만들게요. ```ts @Controller('upstream') export class UpstreamController { @Get('ping') ping() { return { ok: true, at: new Date().toISOString() }; } } ``` 다음으로 테스트를 시작할 `/demo/keepalive` API를 만들어요. 이 API는 앞에서 만든 공유 `apiClient`로 `/upstream/ping`을 순차적으로 다섯 번 호출해요. 각 요청이 끝나면 Node.js의 `reusedSocket` 값을 읽어 기존 소켓을 사용했는지 기록하고요. ```ts @Controller('demo') export class DemoController { @Get('keepalive') async keepalive(@Query('count') count = '5') { const results = []; for (let i = 0; i < Number(count); i++) { const start = Date.now(); const response = await apiClient.get('/upstream/ping'); results.push({ i: i + 1, ms: Date.now() - start, reusedSocket: Boolean(response.request.reusedSocket), }); } return results; } } ``` 마지막으로 두 Controller를 애플리케이션 모듈에 등록해요. ```ts @Module({ controllers: [DemoController, UpstreamController], }) export class AppModule {} ``` 이제 서버를 실행하면 준비가 끝나요. 예제를 간단하게 유지하기 위해 upstream도 같은 프로세스에 두었지만, Axios는 `localhost:3000`으로 실제 HTTP 요청을 보내요. 이 예제의 연결 구조를 정확히 보면 TCP 연결이 두 개 있어요. ```mermaid flowchart TD CLIENT[API Client] DEMO[DemoController
GET /demo/keepalive] AXIOS[공유 apiClient와 Agent] UPSTREAM[UpstreamController
GET /upstream/ping] CLIENT -->|TCP Connection A| DEMO DEMO --> AXIOS AXIOS -->|TCP Connection B| UPSTREAM ``` 두 Controller가 같은 NestJS 프로세스에 있어도 운영체제의 TCP 소켓을 사용해요. 로그의 `reusedSocket`은 API Client가 만든 Connection A가 아니라, 내부 Axios 요청에 사용된 Connection B의 재사용 여부예요. 서버를 실행한 뒤 다른 터미널에서 API를 호출하면 돼요. ```bash pnpm start ``` ```bash curl 'http://localhost:3000/demo/keepalive?count=5' ``` 이제 응답을 확인해 볼게요. 실행 환경에 따라 시간은 달라질 수 있지만, 한 번 실행했을 때는 아래와 같은 결과가 나왔어요. ```json [ { "i": 1, "ms": 10, "reusedSocket": false }, { "i": 2, "ms": 1, "reusedSocket": true }, { "i": 3, "ms": 1, "reusedSocket": true }, { "i": 4, "ms": 0, "reusedSocket": true }, { "i": 5, "ms": 1, "reusedSocket": true } ] ``` 처음 요청이 시작될 때는 Agent에 `localhost:3000`으로 연결된 소켓이 없어요. 그래서 새 TCP 연결을 만들고 `reusedSocket=false`가 돼요. Keep-Alive가 활성화됐다는 것은 첫 요청 전부터 연결이 미리 존재한다는 뜻이 아니라, **첫 요청에서 만든 연결을 다음 요청을 위해 남겨둔다는 뜻**이에요. 첫 응답이 끝나면 소켓은 Agent의 free socket 풀로 돌아가요. 두 번째 요청은 같은 목적지의 소켓을 찾아 TCP handshake 없이 HTTP 요청을 전송할 수 있어요. 그래서 이후 요청의 `reusedSocket`은 `true`가 돼요. ```text #1 → TCP #1 생성 → false #2 → TCP #1 재사용 → true #3 → TCP #1 재사용 → true #4 → TCP #1 재사용 → true #5 → TCP #1 재사용 → true ``` 다만 `10ms - 1ms = 9ms`를 TCP handshake 시간이라고 해석하면 안 돼요. 측정값에는 소켓 생성뿐 아니라 Axios 요청 생성, 운영체제 scheduling, Node.js 이벤트 루프, NestJS 라우팅, JSON 직렬화와 파싱 같은 과정이 모두 포함돼요. 첫 실행의 초기화나 런타임 warm-up도 영향을 줄 수 있고요. 응답 시간은 실행 환경에 따라 달라지므로 숫자 자체보다 `reusedSocket`의 변화를 보는 것이 중요해요. 성능을 비교하려면 충분히 반복한 뒤 평균과 함께 p95, p99도 살펴봐야 해요. 같은 `/demo/keepalive` API를 바로 다시 호출하면 두 번째 실행의 첫 내부 요청부터 `true`가 나올 수도 있어요. Controller의 반복문에서는 첫 번째 요청이지만, 애플리케이션에서 공유되는 Agent의 관점에서는 이미 기존 요청이 남긴 free socket이 있기 때문이에요. 물론 서버가 유휴 연결을 닫았거나 프로세스가 재시작됐다면 다시 `false`가 될 수 있어요. ## 클라이언트만 설정하면 끝일까? Keep-Alive는 클라이언트와 서버가 함께 연결을 유지할 수 있어야 제대로 동작해요. 클라이언트의 풀에 소켓이 남아 있더라도 서버가 먼저 연결을 닫았다면 그대로 재사용할 수 없어요. 실제 요청은 애플리케이션 서버까지 곧바로 도착하지 않고 여러 계층을 통과하는 경우가 많아요. ```mermaid flowchart LR C[HTTP Client
Agent 연결 풀] L[Load Balancer
idle timeout] P[Reverse Proxy
keep-alive timeout] A[Application Server
keepAliveTimeout] C -->|TCP 연결| L L -->|TCP 연결| P P -->|TCP 연결| A ``` 각 구간은 서로 다른 TCP 연결과 타임아웃을 가질 수 있어요. 그래서 어느 한 곳에서 연결을 먼저 닫으면 다른 계층의 연결 재사용에도 영향을 줄 수 있죠. 예제 서버에는 아래와 같이 요청과 연결에 관한 타임아웃을 설정할 수 있어요. ```ts const httpServer = app.getHttpServer() as Server; httpServer.keepAliveTimeout = 65_000; httpServer.headersTimeout = 66_000; httpServer.requestTimeout = 30_000; ``` * `keepAliveTimeout`: 응답을 마친 뒤 다음 요청을 기다리며 유휴 연결을 유지하는 시간이에요. * `headersTimeout`: 요청 헤더 전체가 도착하기까지 기다리는 시간이에요. * `requestTimeout`: 요청 전체를 받기까지 기다리는 시간이에요. 여기서는 `headersTimeout`을 `keepAliveTimeout`보다 조금 크게 설정했어요. 실제 운영 환경에서는 애플리케이션 서버만 볼 것이 아니라 로드 밸런서, 프록시, API Gateway의 idle timeout도 함께 확인해야 해요. 중간 장비가 더 일찍 연결을 끊을 수 있기 때문이에요. ## 운영 환경에서 함께 생각할 것들 HTTP Keep-Alive를 켜는 것만으로 모든 문제가 해결되지는 않아요. 연결을 오래 재사용하는 만큼 풀의 크기와 타임아웃을 서비스 상황에 맞게 관리해야 해요. ### 1. 연결 수에 상한을 두기 트래픽이 갑자기 늘었을 때 연결도 끝없이 늘어나면 상대 서버와 우리 서버 모두 부담을 받아요. `maxSockets`로 동시 연결 수를 제한하고, 대기 시간이 길어지는지도 함께 관찰하는 것이 좋아요. ### 2. 유휴 소켓을 지나치게 많이 남기지 않기 다시 쓸 가능성이 낮은 연결까지 풀에 많이 보관하면 파일 디스크립터와 메모리를 차지해요. `maxFreeSockets`를 조정해 필요한 만큼만 유지해야 해요. ### 3. 타임아웃의 순서를 맞추기 클라이언트, 서버, 로드 밸런서가 서로 다른 타임아웃을 가지고 있으면 한쪽은 살아 있다고 생각한 연결을 다른 쪽은 이미 닫은 상황이 생길 수 있어요. 각 계층의 타임아웃을 확인하고 의도한 순서로 연결이 정리되도록 설계해야 해요. ### 4. 재시도와는 별개의 문제로 보기 Keep-Alive는 연결 생성 비용을 줄이는 기능이지, 실패한 요청을 성공으로 바꾸는 기능은 아니에요. 이미 닫힌 소켓을 재사용하는 과정에서 오류가 발생할 수도 있어요. 재시도가 필요하다면 요청의 멱등성, 재시도 횟수, 지수 백오프를 따로 고려해야 해요. ### 5. 지표로 효과 확인하기 평균 응답 시간만 보면 연결 재사용의 효과나 문제를 놓치기 쉬워요. 가능하다면 소켓 생성 수, 현재 사용 중인 소켓과 유휴 소켓 수, 연결 오류, p95·p99 지연 시간을 함께 살펴보는 것이 좋아요. | 관찰할 값 | 확인하려는 문제 | | ----------------- | -------------------------- | | 요청 p50, p95, p99 | 연결 재사용 후 지연이 개선됐는지 | | 새 소켓 생성 수 | 연결이 지나치게 자주 만들어지는지 | | active socket 수 | upstream으로 동시 연결이 얼마나 열리는지 | | free socket 수 | 유휴 연결을 너무 많이 보관하는지 | | pending request 수 | `maxSockets` 때문에 요청이 대기하는지 | | `ECONNRESET` 수 | 클라이언트와 서버의 연결 생명주기가 충돌하는지 | | reused socket 비율 | 실제로 연결이 재사용되는지 | Node.js Agent는 사용 중인 소켓, free socket, 대기 중인 요청을 각각 `agent.sockets`, `agent.freeSockets`, `agent.requests`로 노출해요. 애플리케이션에서 직접 수정하지 않고 관찰용 지표로 활용할 수 있어요. ## HTTP Client는 upstream별로 나누기 모든 외부 API가 같은 특성을 가지지는 않아요. 결제 API는 실패에 민감하고, 분석 API는 요청량이 많으며, AI API는 한 요청이 오래 걸릴 수 있어요. 그래서 하나의 거대한 전역 클라이언트보다 upstream별 클라이언트를 구성하는 편이 관리하기 좋아요. ```text PaymentHttpClient → 짧은 timeout, 작은 maxSockets, 보수적인 retry AnalyticsHttpClient → 큰 처리량, 비교적 큰 maxSockets AiHttpClient → 긴 timeout, 엄격한 동시 요청 제한 ``` 이렇게 나누면 분석 API의 요청 폭증이 결제 API의 연결 풀까지 차지하는 일을 막을 수 있어요. 서버 인스턴스 수도 함께 계산해야 해요. 예를 들어 인스턴스가 20개이고 각 인스턴스의 `maxSockets`가 128이라면, 한 upstream에 이론상 최대 2,560개의 active connection이 만들어질 수 있어요. Worker에서도 같은 원칙이 적용돼요. 작업마다 Agent를 새로 만들면 `keepAlive: true`여도 이전 작업의 소켓을 재사용할 수 없어요. ```ts // 애플리케이션 시작 시 한 번 생성해 공유해요. const httpsAgent = new HttpsAgent({ keepAlive: true, maxSockets: 20, maxFreeSockets: 5, }); const paymentClient = axios.create({ baseURL: 'https://payments.example.com', timeout: 3_000, httpsAgent, }); async function processJob(paymentId: string) { return paymentClient.get(`/payments/${paymentId}`); } ``` 기존 프로젝트가 Axios 중심이라면 지금처럼 Axios와 custom Agent를 공유하는 방식이 자연스러워요. NestJS의 공식 Axios 모듈을 사용한다면 DI로 서비스별 클라이언트를 제공할 수도 있고, 새로운 Node.js 프로젝트라면 Undici의 `Pool`이나 `Agent`도 선택지가 될 수 있어요. 어떤 도구를 고르든 핵심은 클라이언트의 생명주기와 연결 풀의 경계를 명확히 하는 거예요. ## Keep-Alive만으로 운영 환경이 완성되지는 않아요 Keep-Alive는 정상적인 연결을 효율적으로 재사용해요. 하지만 느린 upstream, 일시적인 네트워크 오류, 지속적인 장애, 배포 중인 서버의 연결 정리까지 해결해 주지는 않아요. ```mermaid flowchart TD B[비즈니스 로직] --> CB[Circuit Breaker] CB --> RT[Retry + Timeout] RT --> HC[Axios / HTTP Client] HC --> AG[HTTP Agent] AG --> POOL[TCP Connection Pool] POOL --> UP[Upstream API] ``` 예제를 운영 환경에 가깝게 확장한다면 `axios-retry`, `opossum`, `lil-http-terminator` 같은 도구를 함께 검토할 수 있어요. 이 글의 Keep-Alive 코드에는 적용하지 않았지만, 각 도구의 역할은 다음처럼 구분할 수 있어요. * `axios-retry`: 네트워크 오류처럼 잠깐 실패한 요청을 정해진 조건으로 다시 시도해요. * `opossum`: 실패가 계속되는 upstream 호출을 잠시 차단하는 Circuit Breaker를 만들 수 있어요. * `lil-http-terminator`: 서버 종료 시 새 요청을 막고 처리 중인 요청과 연결을 정리하는 graceful shutdown을 도와줘요. 재시도는 특히 조심해야 해요. 결제나 주문 생성 요청은 서버에서 처리됐지만 응답만 유실됐을 수 있어요. 쓰기 요청을 재시도하려면 `Idempotency-Key`, 중복 요청 식별자, 데이터베이스 unique constraint처럼 중복 처리를 막는 장치가 필요해요. ```text Keep-Alive → 연결 재사용 Timeout → 너무 느린 요청 제한 Retry → 일시적인 오류 복구 Circuit Breaker → 지속적으로 실패하는 upstream 보호 Graceful Shutdown → 배포 시 연결을 안전하게 정리 ``` ## 마치며 처음에는 HTTP 요청 한 번을 보내는 코드가 단순해 보여요. ```ts await axios.get('/users'); ``` 하지만 이 한 줄 아래에서는 TCP 연결을 만들고, 데이터를 주고받고, 연결을 정리하는 일이 일어나요. 요청마다 이 과정을 반복하면 불필요한 네트워크 왕복과 시스템 비용이 쌓일 수 있어요. HTTP Keep-Alive와 연결 풀을 사용하면 이미 만든 TCP 연결을 여러 HTTP 요청이 나누어 쓸 수 있어요. Node.js에서는 공유되는 `http.Agent`와 `https.Agent`를 만들고, Axios 인스턴스에 주입해 이 구조를 구현할 수 있고요. 이번 글의 핵심을 정리하면 다음과 같아요. * HTTP/1.1 요청은 일반적으로 TCP 연결 위에서 전달돼요. * 새 TCP 연결에는 handshake 비용이 들어요. HTTPS라면 TLS 연결 비용도 추가돼요. * HTTP Keep-Alive는 요청이 끝난 TCP 연결을 풀에 보관했다가 다음 요청에서 재사용해요. * HTTP Keep-Alive와 TCP Keepalive는 서로 다른 문제를 해결해요. * Keep-Alive는 연결 하나만 고집하는 것이 아니라, 필요한 연결을 만들고 재사용하는 방식이에요. * Agent는 요청마다 만들지 않고 애플리케이션에서 공유해야 해요. * 실제 실험에서는 시간 차이보다 `reusedSocket`이 연결 재사용의 더 직접적인 증거예요. * 운영 환경에서는 연결 수, 유휴 소켓 수, 서버와 중간 장비의 타임아웃, 재시도와 종료 전략을 함께 설계해야 해요. HTTP Keep-Alive의 핵심은 첫 번째 요청에서 만든 TCP 연결을 바로 버리지 않고 connection pool에 남겨두어, 같은 서버로 향하는 후속 요청이 연결 수립 과정을 건너뛰게 하는 것이에요. 하지만 연결을 무작정 많이, 오래 유지한다고 좋은 것은 아니에요. 필요한 연결은 만들고, 만들어진 연결은 재사용하고, 동시 연결 수는 제한하고, 사용하지 않는 연결은 정리해야 해요. 여기에 안전한 재시도와 Circuit Breaker, graceful shutdown까지 더해져야 운영 환경의 연결 생명주기가 완성돼요. 이 흐름을 이해하고 나면 Keep-Alive는 단순한 성능 옵션이 아니라, **TCP 연결이라는 유한한 자원을 효율적으로 관리하기 위한 연결 생명주기 전략**으로 보이기 시작할 거예요. --- # 프레임워크 없이 살펴보는 React CSR, SSG와 SSR > React 애플리케이션을 만들다 보면 CSR, SSG, SSR, Hydration 같은 용어를 자주 만나게 돼요. Next.js나 Astro 같은 프레임워크를 사용하면 대부분의 과정이 자동으로 처리되지만, 추상화가 걷히면 React가 언제 실행되고 어떤 결과가 브라우저로 전달되는지... - 원문: https://www.yolog.co.kr/post/react-render-mode - 카테고리: 개발 - 발행: 2026-07-29 - 수정: 2026-07-30 React 애플리케이션을 만들다 보면 CSR, SSG, SSR, Hydration 같은 용어를 자주 만나게 돼요. Next.js나 Astro 같은 프레임워크를 사용하면 대부분의 과정이 자동으로 처리되지만, 추상화가 걷히면 React가 언제 실행되고 어떤 결과가 브라우저로 전달되는지 헷갈릴 때가 있었어요. 그래서 이번에는 프레임워크 없이 작은 SSG와 SSR을 직접 만들어봤어요. JSX도 잠시 내려놓고 `createElement`, `renderToStaticMarkup`, `renderToString`, `hydrateRoot`가 각각 어떤 일을 하는지 하나씩 확인했어요. 직접 구현해 보니 두 방식의 차이는 생각보다 단순했어요. * SSG는 빌드할 때 React를 실행하고 결과를 HTML 파일로 저장해요. * SSR은 요청이 들어올 때 React를 실행하고 결과를 HTML 응답으로 보내요. * SSR로 전달한 화면에 상호작용을 붙이려면 브라우저에서 Hydration이 한 번 더 일어나요. 이 글에서는 이 흐름을 실제 코드와 함께 정리해볼게요. ## React 렌더링 모드 이해하기 여기서는 React가 화면을 만드는 여러 방식을 편의상 **렌더링 모드**(Rendering Mode)라고 부를게요. React의 공식 분류명이라기보다, 실행 시점과 장소를 구분하기 위한 표현에 가까워요. 중요한 점은 이 방식들이 완전히 배타적이지 않다는 거예요. 페이지 바깥 틀은 정적으로 만들고 내부 애플리케이션은 서버에서 렌더링할 수도 있고, 정적 페이지의 일부에만 클라이언트 React를 붙일 수도 있어요. 결국 애플리케이션 전체가 아니라 페이지와 기능의 특성에 맞게 선택하는 문제예요. ### CSR: 브라우저에서 화면 만들기 일반적인 React SPA는 CSR(Client-Side Rendering)로 동작해요. 서버는 보통 React 루트가 비어 있는 최소한의 `index.html`과 JavaScript 번들을 전달하고, 브라우저가 번들을 다운로드하고 실행한 뒤 화면을 만들어요. 구조가 단순하고 브라우저 API를 자유롭게 사용할 수 있다는 장점이 있어요. 반면 JavaScript 다운로드와 실행이 끝나기 전까지 의미 있는 화면이 늦게 보일 수 있어요. 번들이 크거나 사용자의 기기와 네트워크가 느릴수록 이 차이가 커져요. ### SSG: 빌드할 때 HTML 만들기 SSG(Static Site Generation)는 배포 전에 React 컴포넌트를 HTML 파일로 만들어두는 방식이에요. 요청이 들어올 때는 CDN이나 정적 서버가 해당 경로에 맞춰 미리 생성한 파일을 전달해요. 블로그, 문서, 마케팅 페이지처럼 콘텐츠가 자주 바뀌지 않는 페이지에 잘 맞아요. 요청마다 React를 실행할 서버가 필요하지 않고, GitHub Pages 같은 정적 호스팅에도 배포할 수 있어요. ### SSR: 요청할 때 HTML 만들기 SSR(Server-Side Rendering)은 사용자의 요청이 들어올 때 서버에서 React를 실행해 HTML을 만들어요. 브라우저는 완성된 마크업을 먼저 표시하고, JavaScript가 준비되면 그 화면에 이벤트와 상태를 연결해요. 세 방식의 차이는 React가 실행되는 위치와 HTML을 만드는 시점을 중심으로 보면 한눈에 들어와요. ```mermaid flowchart TB subgraph CSR["CSR · 브라우저"] direction LR C1["HTML·JS 전달"] --> C2["브라우저에서 React 실행"] --> C3["화면 표시·상호작용"] end subgraph SSG["SSG · 빌드"] direction LR S1["빌드에서 React 실행"] --> S2["HTML 파일 생성·배포"] --> S3["정적 HTML 전달·표시"] end subgraph SSR["SSR · 요청"] direction LR R1["요청·서버에서 React 실행"] --> R2["HTML 먼저 전달·표시"] --> R3["Hydration·상호작용"] end CSR ~~~ SSG SSG ~~~ SSR ``` 서버 렌더링이 항상 더 빠른 것은 아니에요. 서버의 렌더링 시간이 추가되고, SSR에서는 서버와 브라우저 양쪽에서 React를 실행해야 해요. 빠른 기기와 네트워크에서는 CSR이 더 단순하고 충분히 빠를 수 있어요. 반대로 저사양 기기나 느린 네트워크를 사용하는 사람이 많다면 HTML을 먼저 보여주는 방식이 체감 성능에 큰 도움이 될 수 있어요. 따라서 처음부터 모든 페이지를 SSR로 만들기보다 실제 사용자의 환경과 페이지 성격을 보고 선택하는 편이 좋아요. 도입 전후의 성능도 함께 측정해야 하고요. ## SSG를 직접 만들어보기 먼저 React 컴포넌트를 정적 HTML 파일로 바꾸는 작은 빌드 스크립트를 만들어볼게요. 완성되는 과정은 다음과 같아요. ```text App.js → renderToStaticMarkup() → HTML 문자열 index.html + HTML 문자열 → dist/index.html ``` ### 프로젝트 준비하기 React와 React DOM만 설치한 Node.js 프로젝트를 만들었어요. ```bash mkdir ssg cd ssg npm init -y npm install react react-dom ``` `package.json`에는 ES Module 문법을 사용하기 위해 `"type": "module"`을 추가했어요. ```json { "name": "ssg", "version": "1.0.0", "type": "module", "dependencies": { "react": "^19.2.8", "react-dom": "^19.2.8" } } ``` 이번 예제에서는 일부러 JSX를 사용하지 않았어요. JSX 변환을 생략하면 Babel, Vite, Webpack 없이 Node.js와 React만으로 SSG의 핵심 동작을 볼 수 있거든요. ### HTML 템플릿 만들기 React가 만든 결과를 넣을 `index.html`부터 준비했어요. ```html React SSG
``` ``는 특별한 문법이 아니라 일반 HTML 주석이에요. 빌드 스크립트가 React의 결과를 어디에 넣어야 하는지 찾기 위한 표식으로 사용했어요. ### `createElement`로 컴포넌트 만들기 `App.js`에서는 JSX 대신 `createElement`를 사용했어요. ```js import { createElement as h } from "react"; function App() { return h( "div", null, h("h1", null, "Hello Matthew"), h("p", null, "This page was generated with SSG") ); } export default App; ``` `createElement`를 `h`라는 짧은 이름으로 가져왔어요. 과거 Hyperscript 스타일에서 자주 사용하던 관례일 뿐, `h()`와 `createElement()`는 같은 함수예요. 기본 형태는 다음과 같아요. ```js createElement(type, props, ...children); ``` * `type`에는 `"div"`, `"h1"` 같은 HTML 태그 이름이나 `App` 같은 React 컴포넌트가 들어가요. * `props`에는 `{ className: "title" }`처럼 속성을 전달해요. 속성이 없으면 `null`을 사용해요. * `children`에는 문자열, 숫자, 다른 React 엘리먼트, 배열 등을 필요한 만큼 전달할 수 있어요. 예를 들어 아래 코드는 `

Hello Matthew

`이라는 구조를 설명해요. ```js h("h1", null, "Hello Matthew"); ``` 여기서 `createElement`가 실제 DOM이나 HTML 문자열을 즉시 만드는 것은 아니에요. React가 나중에 무엇을 렌더링해야 하는지 나타내는 **React 엘리먼트 객체**를 반환해요. 위의 `App`은 JSX로 쓰면 다음과 같은 구조예요. ```jsx

Hello Matthew

This page was generated with SSG

``` ### 빌드 스크립트의 import 살펴보기 이제 `build.js`에서 React 엘리먼트를 HTML 문자열로 바꾸고 파일로 저장할게요. 먼저 사용한 모듈의 역할부터 한 줄씩 살펴봤어요. ```js import { renderToStaticMarkup } from "react-dom/server"; ``` `renderToStaticMarkup(reactNode)`은 React 노드를 정적인 HTML 문자열로 바꿔요. 결과를 클라이언트 React가 Hydration하도록 만들어진 API가 아니기 때문에, 블로그나 이메일처럼 상호작용이 필요 없는 HTML 생성에 잘 맞아요. ```js import { createElement as h } from "react"; ``` `App`이라는 함수 컴포넌트를 `h(App)` 형태의 React 엘리먼트로 만들기 위해 가져왔어요. ```js import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from "node:fs"; ``` `node:fs`는 Node.js의 파일 시스템 내장 모듈이에요. `node:` 접두사를 붙이면 외부 패키지가 아니라 Node.js 표준 라이브러리라는 사실이 분명해져요. * `existsSync(path)`는 경로가 존재하는지 확인해요. * `mkdirSync(path)`는 디렉터리를 만들어요. * `readFileSync(path, encoding)`는 파일 전체를 읽어요. 인코딩을 지정하면 문자열을 반환해요. * `readdirSync(path)`는 디렉터리 안의 항목 이름을 배열로 반환해요. * `unlinkSync(path)`는 파일이나 심볼릭 링크를 삭제해요. 디렉터리를 지우는 API는 아니에요. * `writeFileSync(path, data)`는 파일을 만들거나 기존 파일을 덮어써요. 모두 이름에 `Sync`가 붙은 동기 API예요. 각 단계가 끝난 다음 다음 단계로 넘어가므로 작은 빌드 스크립트를 이해하기 쉬워요. 반면 요청을 계속 처리하는 웹 서버에서 사용하면 이벤트 루프를 막을 수 있으므로, 그런 코드에서는 `node:fs/promises` 같은 비동기 API를 우선 고려하는 편이 좋아요. ```js import path, { dirname } from "node:path"; ``` `node:path`는 운영체제에 맞게 파일 경로를 다루는 내장 모듈이에요. `path.join()`은 여러 경로 조각을 운영체제에 맞는 구분자로 연결하고, `dirname()`은 파일 경로에서 디렉터리 부분만 가져와요. 다만 사용자 입력으로 인한 경로 탐색 공격까지 막아주는 보안 API는 아니에요. ```js import { fileURLToPath } from "node:url"; ``` ES Module의 `import.meta.url`은 `/Users/...` 같은 파일 경로가 아니라 `file:///Users/...` 형태의 URL이에요. `fileURLToPath()`는 이 값을 운영체제에서 사용할 수 있는 파일 경로로 바꿔줘요. URL 인코딩이나 Windows 경로까지 처리하므로 `new URL(...).pathname`을 직접 사용하는 것보다 안전해요. ```js import App from "./App.js"; ``` 마지막으로 정적 HTML로 만들 `App` 컴포넌트를 가져와요. Node.js의 ES Module에서는 로컬 모듈을 가져올 때 `.js` 확장자를 명시하는 편이 안전해요. ### `build.js` 완성하기 전체 빌드 스크립트는 다음과 같아요. ```js import { renderToStaticMarkup } from "react-dom/server"; import { createElement as h } from "react"; import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from "node:fs"; import path, { dirname } from "node:path"; import { fileURLToPath } from "node:url"; import App from "./App.js"; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const distPath = path.join(__dirname, "dist"); const shell = readFileSync( path.join(__dirname, "index.html"), "utf8" ); const app = renderToStaticMarkup(h(App)); const html = shell.replace("", app); if (!existsSync(distPath)) { mkdirSync(distPath); } else { const files = readdirSync(distPath); for (const file of files) { unlinkSync(path.join(distPath, file)); } } writeFileSync(path.join(distPath, "index.html"), html); ``` 핵심 로직을 순서대로 보면 어렵지 않아요. ```js const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); ``` CommonJS에는 `__filename`과 `__dirname`이 기본으로 있지만 ES Module에는 없어요. 현재 모듈의 URL을 파일 경로로 변환해 같은 값을 직접 만들었어요. Node.js 20.11.0과 21.2.0부터는 `import.meta.dirname`을 사용할 수 있고, Node.js 22.16.0과 24.0.0부터 실험 표시가 제거됐어요. 여기서 사용한 변환 패턴은 그보다 오래된 Node.js에서도 동작해요. ```js const distPath = path.join(__dirname, "dist"); ``` 빌드 결과를 저장할 `dist` 디렉터리의 절대 경로를 만들어요. 스크립트를 어느 디렉터리에서 실행하더라도 파일 위치를 안정적으로 찾을 수 있어요. ```js const shell = readFileSync( path.join(__dirname, "index.html"), "utf8" ); ``` HTML 템플릿을 문자열로 읽어요. 인코딩을 생략하면 `Buffer`가 반환되므로 `"utf8"`을 지정했어요. ```js const app = renderToStaticMarkup(h(App)); ``` `h(App)`이 `App` 컴포넌트를 React 엘리먼트로 만들고, `renderToStaticMarkup()`이 그 엘리먼트를 HTML 문자열로 바꿔요. ```js const html = shell.replace("", app); ``` 템플릿의 표식을 React가 만든 문자열로 교체해 완성된 HTML을 만들어요. 표식이 없으면 조용히 원본 문자열이 반환되므로, 실제 빌드 도구라면 표식의 존재 여부를 검사하고 오류를 내는 편이 안전해요. ```js if (!existsSync(distPath)) { mkdirSync(distPath); } else { const files = readdirSync(distPath); for (const file of files) { unlinkSync(path.join(distPath, file)); } } ``` `dist`가 없으면 만들고, 이미 있으면 이전 결과 파일을 비워요. 이 코드는 `dist` 바로 아래의 **파일만** 처리해요. Vite처럼 하위 디렉터리를 만드는 빌드라면 `unlinkSync()`만으로는 부족하므로 `rmSync(distPath, { recursive: true, force: true })`처럼 디렉터리까지 고려해야 해요. ```js writeFileSync(path.join(distPath, "index.html"), html); ``` 마지막으로 완성된 문자열을 `dist/index.html`에 저장해요. ### 빌드 결과 확인하기 아래 명령을 실행하면 정적 HTML 파일이 생겨요. ```bash node build.js ``` 생성된 `dist/index.html`에는 React 런타임이 남지 않아요. ```html

Hello Matthew

This page was generated with SSG

``` 이 작은 스크립트가 SSG의 핵심이에요. 실제 프레임워크는 여기에 라우팅, 데이터 로딩, 여러 페이지 생성, 에셋 최적화, 캐시 무효화 같은 기능을 더해요. 예를 들어 경로와 컴포넌트, props의 조합을 목록으로 관리하고 반복해서 파일을 만들면 작은 정적 사이트 생성기의 출발점이 돼요. 다만 원리를 이해한 뒤에는 직접 만든 빌드 도구를 계속 확장하기보다 Astro나 Next.js 같은 검증된 도구를 사용하는 편이 대체로 효율적이에요. 직접 구현한 경험은 프레임워크가 어디에서 무엇을 대신하는지 이해하고, 문제가 생겼을 때 원인을 좁히는 데 도움이 됐어요. ## SSR이 필요한 이유 SSG가 빌드 시점의 렌더링이라면 SSR은 요청 시점의 렌더링이에요. 사용자별 데이터나 자주 바뀌는 내용을 요청마다 HTML에 반영해야 할 때 사용할 수 있어요. CSR에서는 브라우저가 JavaScript를 실행하기 전까지 화면을 만들 수 없어요. SSR은 이 두 시점을 분리해요. 1. 서버가 만든 HTML을 먼저 보여줘요. 2. 브라우저가 JavaScript를 준비해 Hydration을 마치면 상호작용할 수 있어요. 즉, **화면이 보이는 시점**과 **화면을 조작할 수 있는 시점** 사이에 간격이 생겨요. 상호작용 가능 시점이 반드시 빨라지는 것은 아니지만, 사용자는 내용을 먼저 읽고 다음 행동을 생각할 수 있어서 더 빠르다고 느낄 수 있어요. ```mermaid sequenceDiagram participant B as 브라우저 participant S as Node 서버 B->>S: GET / S->>S: React를 HTML로 렌더링 S-->>B: head 먼저 전송 B->>B: JavaScript 다운로드 시작 S-->>B: React HTML과 나머지 문서 전송 B->>B: HTML 표시 B->>B: hydrateRoot()로 상호작용 연결 ``` SSR의 비용도 분명해요. * 요청마다 서버 CPU와 응답 시간이 들어가요. * 같은 컴포넌트가 서버와 브라우저 양쪽에서 실행될 수 있어야 해요. * 서버에는 `window`, `document`, `localStorage` 같은 브라우저 API가 없어요. * 서버와 클라이언트의 첫 렌더링 결과가 다르면 Hydration 오류가 발생해요. * 서버, 클라이언트 번들, 정적 파일 제공, 캐시와 모니터링까지 운영 범위가 넓어져요. 그래서 SSR은 무료 성능 최적화가 아니라 복잡성과 서버 비용을 지불하고 초기 화면을 앞당기는 선택에 가까워요. Lighthouse와 Chrome DevTools에서 FCP, LCP, INP 같은 사용자 중심 지표를 확인하고, 서버의 TTFB와 렌더링 시간도 함께 측정해야 전체 효과를 알 수 있어요. ## SSR을 직접 만들어보기 이번에는 Fastify가 요청을 받고, React가 HTML을 만든 다음, 브라우저가 그 화면을 Hydration하는 최소한의 SSR을 구성해볼게요. ### 프로젝트 준비하기 ```bash mkdir ssr cd ssr npm init -y npm install react react-dom fastify @fastify/static vite ``` `package.json`에는 ES Module 설정과 빌드·실행 스크립트를 추가했어요. ```json { "name": "ssr", "version": "1.0.0", "type": "module", "scripts": { "build": "vite build", "start": "node server.js" }, "dependencies": { "@fastify/static": "^10.1.2", "fastify": "^5.10.0", "react": "^19.2.8", "react-dom": "^19.2.8", "vite": "^8.1.5" } } ``` 패키지의 메이저 버전이 바뀌면 API나 지원하는 Node.js 버전도 달라질 수 있어요. 예제와 다른 오류가 난다면 먼저 설치된 버전을 확인하는 편이 좋아요. ### 서버와 브라우저가 함께 사용하는 `App.js` SSR에서는 `App`과 그 자식들이 서버의 첫 렌더링과 브라우저의 첫 렌더링에서 모두 실행돼요. 실제로 Hydration이 끝났는지 확인할 수 있도록 카운터를 넣었어요. ```js import { createElement as h, useState } from "react"; function App() { const [count, setCount] = useState(0); return h( "div", null, h("h1", null, "Hello Matthew"), h("p", null, "This page was rendered with SSR"), h( "button", { onClick: () => setCount((value) => value + 1) }, `Count: ${count}` ) ); } export default App; ``` 서버는 버튼의 HTML까지 만들 수 있지만 클릭 이벤트를 HTML에 담아 보낼 수는 없어요. `onClick`이 실제로 동작하려면 브라우저에서 React가 같은 `App`을 실행하고 기존 DOM에 이벤트를 연결해야 해요. 상태를 이전 값으로 갱신할 때는 `setCount(count + 1)`도 동작하지만, 연속 업데이트에 안전하도록 함수형 업데이트인 `setCount((value) => value + 1)`을 사용했어요. ### HTML 템플릿과 클라이언트 진입점 `index.html`은 SSG의 템플릿과 비슷하지만 브라우저에서 실행할 `client.js`를 포함해요. ```html React SSR Example
``` 모듈 스크립트는 기본적으로 HTML 파싱을 막지 않고 지연 실행돼요. 그래서 `type="module"`에는 일반 스크립트의 `defer`와 비슷한 동작이 내장돼 있고, `defer`를 별도로 적어도 효과가 없어요. 원본 실습 코드에는 ``가 들어 있었어요. 하지만 `async` 모듈은 모듈 그래프의 다운로드가 끝나는 즉시 실행될 수 있고, HTML 파싱이 끝날 때까지 기다리지 않아요. 그러면 ``의 `#root`가 만들어지기 전에 `hydrateRoot()`가 호출될 수 있어요. 이 진입점은 DOM이 준비된 뒤 실행되어야 하므로 `async`를 제거하고 모듈 스크립트의 기본 지연 실행을 사용하는 편이 안전해요. 또한 원본 파일명은 `Client.js`처럼 대문자로 시작하지만, 여기서는 일반적인 관례에 맞춰 `client.js`로 통일했어요. macOS의 기본 파일 시스템에서는 두 경로가 같은 것처럼 동작할 수 있지만, Linux처럼 대소문자를 구분하는 환경에서는 `src`와 실제 파일명의 대소문자가 정확히 일치해야 해요. 브라우저 전용 진입점인 `client.js`는 아주 짧아요. ```js import { createElement as h } from "react"; import { hydrateRoot } from "react-dom/client"; import App from "./App.js"; hydrateRoot(document.getElementById("root"), h(App)); ``` `hydrateRoot(container, reactNode)`는 서버가 만든 기존 HTML을 가능한 한 재사용하면서 React의 상태와 이벤트를 연결해요. `createRoot()`와의 차이도 중요해요. * `createRoot()`는 빈 컨테이너에 새로운 클라이언트 React 트리를 렌더링할 때 사용해요. * `hydrateRoot()`는 서버가 이미 만든 HTML이 있을 때 그 DOM을 이어받기 위해 사용해요. 이 파일은 `server.js`가 import하지 않고 브라우저 번들의 진입점으로만 사용해요. 따라서 Google Analytics처럼 브라우저에서만 실행해야 하는 초기화 코드나 `window`를 사용하는 코드는 이 경계 안에 둘 수 있어요. 다만 이것은 **실행 환경의 경계**이지 **보안 경계**는 아니에요. 클라이언트 번들에 포함된 코드와 값은 사용자가 내려받아 볼 수 있으므로 비밀 키나 서버 전용 로직을 넣으면 안 돼요. ### 서버 진입점 만들기 `server.js`는 템플릿을 읽고, 정적 에셋을 제공하고, 요청마다 React를 HTML로 렌더링해 응답해요. ```js import fastify from "fastify"; import fastifyStatic from "@fastify/static"; import { readFileSync } from "node:fs"; import path, { dirname } from "node:path"; import { fileURLToPath } from "node:url"; import { createElement as h } from "react"; import { renderToString } from "react-dom/server"; import App from "./App.js"; const __filename = fileURLToPath(import.meta.url); const __dirname = dirname(__filename); const shell = readFileSync( path.join(__dirname, "dist", "index.html"), "utf8" ); const [beforeRoot, afterRoot] = shell.split(""); const app = fastify(); app.register(fastifyStatic, { root: path.join(__dirname, "dist"), prefix: "/", }); app.get("/", (_request, reply) => { reply.hijack(); reply.raw.setHeader("Content-Type", "text/html; charset=utf-8"); reply.raw.write(beforeRoot); reply.raw.write(renderToString(h(App))); reply.raw.end(afterRoot); }); await app.listen({ port: 3000 }); ``` Fastify 대신 Express, Koa, Node.js의 `http` 모듈을 사용해도 SSR의 원리는 같아요. 여기서는 라우팅과 정적 파일 제공을 간단하게 만들기 위해 Fastify를 사용했어요. import를 제외한 핵심 코드를 나눠서 살펴볼게요. ```js const shell = readFileSync( path.join(__dirname, "dist", "index.html"), "utf8" ); ``` 원본이 아니라 Vite가 만든 `dist/index.html`을 읽어요. 빌드된 HTML에는 `/assets/index-해시.js`처럼 최적화되고 해시가 붙은 실제 클라이언트 번들 경로가 들어 있기 때문이에요. ```js const [beforeRoot, afterRoot] = shell.split(""); ``` 표식을 기준으로 문서를 두 조각으로 나눠요. * `beforeRoot`에는 ``부터 `root` 내부의 표식 직전까지 들어가요. * `afterRoot`에는 표식 직후부터 닫는 태그까지 들어가요. 실무 코드라면 분할 결과가 정확히 두 조각인지 검사해야 해요. 표식이 없거나 두 번 이상 들어가면 잘못된 문서를 보낼 수 있거든요. ```js app.register(fastifyStatic, { root: path.join(__dirname, "dist"), prefix: "/", }); ``` Vite가 만든 JavaScript와 그 밖의 정적 에셋을 `dist`에서 제공해요. HTML만 서버가 만들어도 Hydration에 필요한 클라이언트 번들은 별도로 내려받아야 해요. ```js app.get("/", (_request, reply) => { reply.hijack(); reply.raw.setHeader("Content-Type", "text/html; charset=utf-8"); reply.raw.write(beforeRoot); reply.raw.write(renderToString(h(App))); reply.raw.end(afterRoot); }); ``` `reply.raw`는 Node.js의 원시 응답 객체예요. Fastify의 일반 응답 생명주기를 건너뛰고 직접 응답을 끝낼 것이므로 `reply.hijack()`으로 제어권을 가져왔어요. 응답이 서버에서 만들어지고 브라우저로 전달되는 순서를 그림으로 보면 다음과 같아요. (이미지: SSR 응답 조각과 Hydration 흐름) 첫 조각이 실제로 네트워크까지 전달되면 브라우저는 서버가 React를 렌더링하는 동안 ``를 파싱하고 에셋 다운로드를 시작할 수 있어요. 다만 압축 미들웨어, 리버스 프록시, CDN이 작은 청크를 버퍼링하면 브라우저가 즉시 받지 못할 수도 있어요. 작은 예제에서는 차이가 거의 없지만 애플리케이션과 네트워크가 커질수록 일을 겹쳐 진행하는 의미가 생겨요. 다만 `renderToString()` 자체는 전체 React 트리의 렌더링이 끝난 뒤 문자열 하나를 반환해요. React 결과까지 점진적으로 보내는 진짜 스트리밍 SSR은 아니에요. 이 차이는 뒤에서 다시 살펴볼게요. ### `renderToStaticMarkup`과 `renderToString` SSG에서는 `renderToStaticMarkup()`을 사용했고, SSR에서는 `renderToString()`을 사용했어요. | API | 주된 용도 | Hydration | | -------------------------- | ------------------------------------ | --------------------------- | | `renderToStaticMarkup()` | 상호작용이 필요 없는 정적 HTML 생성 | 지원하지 않아요 | | `renderToString()` | 서버에서 HTML을 문자열로 만든 뒤 클라이언트가 이어받는 SSR | `hydrateRoot()`로 이어받을 수 있어요 | | `renderToPipeableStream()` | Node.js 환경의 스트리밍 SSR | Suspense와 스트리밍을 지원해요 | `renderToString()`으로 만든 HTML을 Hydration하지 않아도 화면은 보여요. 다만 클라이언트 상호작용이 생기지 않고, 정적 결과만 필요했다면 `renderToStaticMarkup()`이 의도를 더 분명하게 나타내요. 현재 React의 Node.js SSR에서는 가능하면 `renderToPipeableStream()` 사용이 권장돼요. 다만 지금처럼 즉시 끝나는 작은 트리는 결과가 사실상 한 덩어리라 스트리밍의 장점이 거의 없어요. 원리를 확인하는 예제에서는 `renderToString()`이 훨씬 간결해서 선택했어요. ### 빌드하고 실행하기 먼저 Vite가 클라이언트 코드를 번들링하고 `dist/index.html`을 만들도록 빌드해요. ```bash npm run build npm run start ``` 이제 `http://localhost:3000`을 열면 서버가 만든 화면이 보이고, Hydration이 끝난 뒤 버튼도 동작해요. 브라우저의 **페이지 소스 보기**에서 `Hello Matthew`가 포함된 완성된 마크업을 확인할 수 있다면 서버 렌더링도 제대로 된 거예요. 이 예제에는 개발 서버나 watch 모드가 없어요. `App.js`나 `client.js`를 바꾸면 다시 빌드해야 하고, `server.js`나 서버가 메모리에 읽어둔 템플릿이 바뀌면 서버도 다시 시작해야 해요. 실제 프로젝트에서는 프레임워크와 개발 도구가 이 과정을 자동화해줘요. ## 직접 구현하며 만난 함정 SSR의 핵심 코드 자체는 짧았지만, 서버와 브라우저가 같은 화면을 함께 책임지기 시작하면서 지켜야 할 조건이 늘어났어요. ### Hydration은 무엇을 하는가 Hydration을 “정적 HTML에 이벤트 리스너를 붙이는 과정”이라고 설명하는 경우가 많아요. 큰 방향에서는 맞지만 실제로는 조금 더 많은 일을 해요. 브라우저의 React는 서버가 만든 DOM을 기준으로 컴포넌트 트리를 다시 계산하고, 기존 노드와 대응시키며, 상태와 이벤트 시스템을 연결해요. 이 과정이 성공하려면 서버의 HTML과 클라이언트의 첫 렌더링 결과가 같아야 해요. ```text 서버: renderToString() → HTML 클라이언트: 첫 번째 렌더링 → 같은 트리여야 함 ``` React가 단순히 HTML 문자열의 해시만 비교하는 것은 아니에요. 기존 DOM과 클라이언트가 기대하는 트리를 Hydration하면서 불일치를 감지해요. 차이가 생기면 경고를 출력하고, 해당 부분을 클라이언트에서 다시 만들 수 있어요. 그러면 서버 렌더링으로 얻으려던 이점 일부를 잃고 예상하지 못한 화면 변화도 생길 수 있어요. ### 표식 주변의 공백도 DOM 노드가 돼요 템플릿은 아래처럼 표식을 `root`에 붙여 작성했어요. ```html
``` 이를 보기 좋게 만들겠다며 다음처럼 줄을 바꾸면 문제가 생길 수 있어요. ```html
``` 서버가 표식만 React HTML로 교체하면 줄바꿈과 들여쓰기가 `root` 안에 그대로 남아요. ```html
...
``` HTML에서 이 공백은 상황에 따라 텍스트 노드가 돼요. 서버 DOM과 클라이언트가 기대하는 첫 트리를 나란히 놓으면 차이가 더 선명하게 보여요. (이미지: 공백 텍스트 노드로 인한 Hydration 불일치) 왼쪽 서버 DOM의 첫 번째 자식은 줄바꿈과 들여쓰기로 생긴 공백 텍스트 노드예요. 반면 클라이언트의 `h(App)`은 `root` 바로 아래에 `App`의 `
` 하나만 있을 것으로 기대하므로 Hydration 불일치가 발생할 수 있어요. 공백 자체가 언제나 문제인 것은 아니에요. Hydration 대상인 `root` 내부에서 **서버와 클라이언트의 첫 결과를 다르게 만드는 공백**이 문제예요. 다른 JavaScript 파일의 들여쓰기나 `root` 바깥의 공백은 이 비교와 관계없어요. Prettier 같은 포매터가 표식 주변을 자동으로 줄바꿈할 수도 있어요. 템플릿을 직접 조립한다면 해당 줄이 변경되지 않도록 설정하거나, 문자열 치환 대신 HTML을 안전하게 조립하는 전용 로직을 두는 편이 좋아요. 프레임워크를 사용하면 보통 이 민감한 경계를 내부에서 관리해줘요. ### 더 흔한 Hydration 불일치 원인 공백 외에도 서버와 클라이언트의 첫 결과를 다르게 만드는 코드는 모두 원인이 될 수 있어요. * 렌더링 중 `Date.now()`, `Math.random()`처럼 실행할 때마다 달라지는 값을 사용한 경우 * 서버와 브라우저의 시간대나 로케일이 다른 경우 * 렌더링 중 `window.innerWidth` 같은 브라우저 API로 분기한 경우 * 서버가 사용한 초기 데이터와 클라이언트의 초기 데이터가 다른 경우 * 잘못 중첩된 HTML을 브라우저가 자동으로 교정한 경우 * 브라우저 확장 프로그램이 React 실행 전에 DOM을 바꾼 경우 해결 원칙은 서버와 클라이언트의 **첫 렌더링을 결정론적으로 만드는 것**이에요. 브라우저에서만 알 수 있는 값은 `useEffect` 이후에 읽고, 서버에서 사용한 데이터는 클라이언트에도 같은 초기값으로 전달해야 해요. 예를 들어 카운터의 시작값을 `5`로 바꾸고 싶다면 서버와 클라이언트가 공유하는 `App`의 초기값을 함께 바꿔야 해요. ```js const [count, setCount] = useState(5); ``` 서버에서는 `0`, 클라이언트에서는 `5`를 사용하도록 나누면 첫 버튼 텍스트가 달라져 Hydration 불일치가 발생해요. ### 브라우저 API는 경계 밖에서 사용하기 `App`은 서버에서도 실행되므로 렌더링 경로에서 아래 코드를 바로 사용하면 서버가 실패해요. ```js const theme = localStorage.getItem("theme"); ``` 브라우저에서만 필요한 작업은 `client.js`에서 초기화하거나 컴포넌트의 `useEffect` 안에서 실행해야 해요. ```js useEffect(() => { const theme = localStorage.getItem("theme"); // 브라우저에서만 필요한 처리 }, []); ``` 다만 `useEffect` 이후 화면을 바꾸면 초기 화면과 Hydration 이후 화면이 달라질 수 있어요. 테마처럼 첫 화면부터 정확해야 하는 값은 쿠키를 서버에서 읽어 초기 HTML에 반영하는 등 별도의 전략이 필요해요. ### 표식을 어디에서 나눌까 이 예제에서는 React 애플리케이션이 들어갈 위치 바로 앞에서 문서를 나눴어요. ```text [doctype + head + root 시작] → [React HTML] → [root 종료 + 문서 나머지] ``` 첫 조각에 ``가 포함되어 있어야 브라우저가 CSS, 폰트, JavaScript 같은 리소스를 빨리 발견할 수 있어요. React를 모두 렌더링한 다음 완성된 문자열 하나를 보내면 구현은 더 단순하지만, 그동안 브라우저는 아무 작업도 시작하지 못해요. 페이지에 독립적인 React 영역이 여러 개 있는 아일랜드나 마이크로 프런트엔드 구조라면 표식도 여러 개일 수 있어요. 각 영역 직전까지 문서를 보내고 렌더링 결과를 채우는 방식으로 확장할 수 있지만, 순서와 오류 처리, Hydration 진입점 관리가 빠르게 복잡해져요. ### `renderToPipeableStream`은 언제 필요한가 `renderToString()`은 전체 트리가 끝날 때까지 기다렸다가 문자열 하나를 반환해요. 반면 `renderToPipeableStream()`은 준비된 HTML을 여러 청크로 나눠 Node.js 응답 스트림에 보낼 수 있어요. Suspense를 사용하는 큰 애플리케이션에서는 빠르게 준비되는 셸을 먼저 보내고, 데이터가 필요한 영역을 나중에 보낼 수 있어요. ```text 레이아웃과 내비게이션 → 먼저 전송 빠른 콘텐츠 → 준비되는 대로 전송 느린 데이터 영역 → Suspense fallback 뒤에 전송 ``` 하지만 스트리밍을 도입하면 오류 처리, 응답 상태 코드, 봇 처리, 중단과 타임아웃 같은 고려사항도 늘어나요. 지금 만든 카운터처럼 모든 렌더링이 즉시 끝나는 페이지에서는 얻는 이점보다 코드 복잡성이 더 커요. ## CSR·SSG·SSR 중 무엇을 선택할까 직접 만들어본 뒤에는 “어떤 방식이 가장 좋은가”보다 “언제 실행해야 하는가”가 더 중요한 질문이라는 생각이 들었어요. | 상황 | 먼저 고려할 방식 | 이유 | | ---------------------- | ----------------------- | --------------------------------- | | 로그인 후 사용하는 대시보드나 내부 도구 | CSR | SEO와 초기 정적 콘텐츠보다 상호작용이 중심이에요 | | 블로그, 문서, 마케팅 페이지 | SSG | 콘텐츠를 빌드 때 만들고 CDN에서 빠르게 제공할 수 있어요 | | 요청마다 달라지는 공개 페이지 | SSR | 최신·개인화된 HTML을 요청 시점에 만들 수 있어요 | | 정적 콘텐츠에 일부 상호작용만 필요 | SSG + 클라이언트 아일랜드 | 전체 Hydration 비용을 줄일 수 있어요 | | 복잡한 공개 애플리케이션 | SSR + Hydration 또는 스트리밍 | 초기 콘텐츠와 상호작용을 모두 제공할 수 있어요 | 선택할 때는 다음 질문을 함께 봐야 해요. 1. 콘텐츠는 빌드할 때 알 수 있나요, 요청이 와야 알 수 있나요? 2. 검색 엔진과 링크 미리보기에 완성된 HTML이 중요한가요? 3. 사용자의 기기와 네트워크 환경은 어떤가요? 4. 첫 화면과 상호작용 중 무엇이 더 중요한가요? 5. 서버 렌더링과 캐시를 운영할 복잡성을 감당할 수 있나요? 6. 실제 측정에서 FCP, LCP, INP, TTFB가 개선됐나요? SSR이나 서버 컴포넌트가 새롭다는 이유만으로 모든 프로젝트에 도입할 필요는 없어요. CSR로 충분한 애플리케이션은 여전히 많고, 정적 콘텐츠라면 SSG가 더 단순하고 저렴할 수 있어요. 이번 구현에서 가장 크게 느낀 점은 프레임워크가 마법을 부리는 것이 아니라는 거예요. 결국 컴포넌트를 실행해 HTML을 만들고, 적절한 시점에 파일이나 응답으로 내보내고, 필요하면 브라우저가 그 화면을 이어받는 과정이었어요. 물론 실제 서비스에서는 이 경계에 라우팅, 데이터 로딩, 캐시, 코드 분할, 오류 복구, 보안이 더해져요. 그래서 원리를 이해한 다음에는 Next.js나 Astro 같은 프레임워크에 맡기는 편이 좋아요. 내부 흐름을 알고 사용하면 문제가 생겼을 때 어느 단계부터 확인해야 하는지도 훨씬 선명해져요. ### 참고 자료 * [React: createElement](https://react.dev/reference/react/createElement) * [React: renderToStaticMarkup](https://react.dev/reference/react-dom/server/renderToStaticMarkup) * [React: renderToString](https://react.dev/reference/react-dom/server/renderToString) * [React: renderToPipeableStream](https://react.dev/reference/react-dom/server/renderToPipeableStream) * [React: hydrateRoot](https://react.dev/reference/react-dom/client/hydrateRoot) * [Node.js: File system](https://nodejs.org/api/fs.html) * [Node.js: ECMAScript modules](https://nodejs.org/api/esm.html) * [Node.js: URL](https://nodejs.org/api/url.html) * [Fastify: Reply](https://fastify.dev/docs/latest/Reference/Reply/) * [Fastify: Static plugin](https://github.com/fastify/fastify-static) * [Vite: Building for production](https://vite.dev/guide/build) * [MDN: ` ``` 파일명이 바뀌었으므로 브라우저는 기존 캐시를 사용하지 않고 새 파일을 다운로드한다. 이를 \*\*캐시 버스팅(Cache Busting)\*\*이라고 한다. ### HTML은 짧게 캐시하기 그런데 HTML 파일은 어떻게 해야 할까? HTML은 JavaScript 파일의 경로를 담고 있으므로 이름이 고정되어야 한다. `index.html`이 배포할 때마다 `index.abc123.html`로 바뀌면 브라우저가 어떤 파일을 요청해야 할지 알 수 없다. 따라서 HTML은 항상 최신 버전을 제공해야 한다. `no-cache`로 설정해서 매번 서버에 확인하도록 하는 것이 좋다. ```js if (ext === '.js' || ext === '.css') { res.setHeader('Cache-Control', 'max-age=31536000'); } else if (ext === '.html') { res.setHeader('Cache-Control', 'no-cache'); } ``` `no-cache`를 설정하면 브라우저는 HTML 파일을 캐시에 저장하되, 사용하기 전에 매번 서버에 신선도를 확인한다. 서버는 `If-None-Match`나 `If-Modified-Since`를 확인해서 304를 응답하거나 새로운 HTML을 보낸다. ### 캐싱 전략 정리 정리하면 다음과 같은 전략을 사용하면 된다: 1. **정적 자원 (JS, CSS, 이미지)**: `Cache-Control: max-age=31536000` + 파일명 해싱 * 장점: 서버 접속 없이 즉시 로딩 * 배포: 파일명이 바뀌므로 자동으로 갱신됨 2. **HTML**: `Cache-Control: no-cache` * 장점: 항상 최신 JavaScript 경로 제공 * 단점: 매번 서버 확인 필요 (하지만 304 응답은 빠름) 3. **API 응답**: 상황에 따라 다름 * 자주 바뀌는 데이터: `Cache-Control: no-cache` 또는 `max-age=60` (짧은 시간) * 거의 안 바뀌는 데이터: `max-age=3600` (1시간) 등 이런 전략을 사용하면 성능과 최신성을 모두 만족할 수 있다. *** ## 핵심 정리 * **시간 기반 캐싱**: `Last-Modified`와 `If-Modified-Since` 헤더를 활용하여 파일의 수정 시간을 기준으로 캐시 신선도를 판단한다 * **내용 기반 캐싱**: `ETag`와 `If-None-Match` 헤더를 활용하여 파일의 해시값을 기준으로 캐시 신선도를 판단한다 * **캐시 제어**: `Cache-Control` 헤더로 캐싱 정책을 세밀하게 제어할 수 있다 * `max-age`: 일정 기간 동안 서버에 접속하지 않고 캐시 사용 * `no-cache`: 매번 서버에 캐시 신선도 확인 * `no-store`: 캐시를 저장하지 않음 * **캐싱 전략**: 정적 자원(JS, CSS)은 긴 캐시 기간 설정, HTML은 `no-cache`로 설정하여 최신 버전 제공 * **파일 버전 관리**: 번들링 시 파일명에 해시값을 포함하여 배포 시마다 캐시 갱신 --- # Tanstack Query 효율적으로 Key 관리해보기 > 🙆🏻‍♂️ 아마 대부분의 프론트엔드 개발자 분들은 Tanstack-Query라는 도구를 활용해서 비동기 상태 관리를 할 것입니다. 실제로 Tanstack-Query는 현재 (2025년 10월 15일 기준) 약 1150만회 이상 다운받아질 정도로 프론트엔드 개발자에게 있어서 필수... - 원문: https://www.yolog.co.kr/post/query-key-factory - 카테고리: 개발 - 발행: 2025-10-15 - 수정: 2025-10-15 ## 사건의 발단 > 🙆🏻‍♂️ 아마 대부분의 프론트엔드 개발자 분들은 Tanstack-Query라는 도구를 활용해서 비동기 상태 관리를 할 것입니다. 실제로 Tanstack-Query는 현재 (2025년 10월 15일 기준) 약 1150만회 이상 다운받아질 정도로 프론트엔드 개발자에게 있어서 필수 불가결한 라이브러리 중 하나입니다. (물론 SWR도... 있기는 한다 ^ㅁ^) (이미지: 놀라운 query-key-factory 설치 수) 현재 운영중인 서비스에서도 Tanstack-Query를 매우 알차게 사용하고 있다. 많은 분들이 아시겠지만 Tanstack-Query를 도입하면 아래와 같은 장점을 얻게 된다. 1. 데이터 캐싱 및 상태 관리 2. 자동화된 데이터 동기화 3. 로딩/에러처리 (데이터 상태를) 쉽게 관리 4. 서버 상태와 클라이언트 상태를 분리 5. `QueryKey`를 활용함으로써 중복 요청을 방지 6. `Optimistic Update`, `Background Update`와 같은 최적화된 데이터 업데이트 (사용자 경험과 연관) 7. 개발 편의성 (`Query`, `Mutation`을 통한 직관적인 코드 작성, DevTool의 유용함) 물론 이 외에도 정말 많은 장점이 있겠지만, Tanstack Query를 도입하면 비동기 데이터 요청 및 캐싱이 많이 필요한 프로젝트에서 개발 속도와 유지보수성을 크게 향상시킬 수 있다. *** ## 그래서, 말하고자 하는게 뭐야? 위의 Tanstack-Query에 대한 장점을 잘 보면 `QueryKey`가 매우 중요한 역할을 하고 있다는 것을 알 수 있다! 실제로 아래 공식문서에서도 `QueryKey`의 중요성을 설명하고 있다! (이미지: 공식문서에서의 QueryKey의 중요성) ### 쿼리 키 (Query Keys) TanStack Query는 쿼리 키를 기반으로 쿼리 캐싱을 관리한다. `QueryKey`는 최상위 수준에서 `배열(Array)` 형태를 가져야 하며, 단순히 문자열 하나로 구성된 배열일 수도 있고 여러 문자열과 중첩된 객체로 이루어진 복잡한 배열일 수도 있다. `QueryKey`가 `직렬화 가능(serializable)`하고 쿼리 데이터에 고유하다면 어떤 형태로든 사용할 수 있다! **뭐 대충, 엄청 중요하다는 의미입니다.** 사실 처음 개발을 할 때에는 `QueryKey`에 대한 중요성이 크게 느껴지지 않았다. 1. 전체 조회를 한다. ```js const queryKeys = { todos: 'todos', challenges: 'challenges', }; ``` 전체 조회만 있으면 이렇게 하면 괜찮을 것 같았다! 2. 상세 조회도 한다. 여기서 살짝 고민이 생겼다. 물론 일반적으로 `[todos, 1]` 이런식으로 `QueryKey`를 관리해도 되지 않을까 라는 생각을 했지만, 이러면 상세 페이지만 `invalidate(새로고침)`을 하고 싶은 경우가 대응이 어려워집니다. 그래서 생각한 `QueryKey`의 구조는 아래와 같아졌다. ```js const queryKeys = { todos: { all: ['todos', 'all'], detail: (id: number) => ['todos', 'detail', id], }, challenges: { all: ['challenges', 'all'], detail: (id: number) => ['challenges', 'detail', id], }, }; ``` 뭐, 여기까지는 그래도 대응 할 만 했다. 3. challenge의 종류가 생긴 경우? (영상 챌린지, 녹음 챌린지 등등) 여기서부터 이제 혼란이 오기 시작했다. 어떤식으로 관리해야지?? ```js const queryKeys = { challenges: { general: { all: ['challenges', 'all', 'general'], detail: (id: number) => ['todos', 'detail', 'general', id], }, recording: { all: ['challenges', 'all', 'recording'], detail: (id: number) => ['todos', 'detail', 'recording', id], }, }, }; ``` 물론 `filters`라는 파라미터를 전달받아서 `{ filters }` 형태로 `QueryKey`를 관리해도 될 것 같다고 생각했다! 그러나 현재 저희 서비스 뿐만 아니라 대부분의 서비스들은 계속 늘어나는 고객들의 요구사항과 편리함을 충족하기 위해서 기능을 추가할 것이고, 그에 따라 `QueryKey`의 변동이 정말 많이 일어날 것 같다고 생각했다. 현재 서비스의 크기 정도면 충분히 이런식으로 관리가 가능하다고 생각했지만, 앞으로 많은 직원들이 들어오거나 협업을 하는데에 있어서 `QueryKey`를 효율적으로 관리하는 기준을 잡는 것이 매우 필요하다고 생각했다. (이미지: 매번, 리팩토링 하려고 했지만 쉽지 않았다는 핑계..) ### 자기 반성 🙇🏻‍♂️ `QueryKey`를 한번 빠르게 정리하고 싶었으나... 서비스 출시 이후 늘어나는 요구사항과 유저 에러들을 즉각 대응하느라 (핑계) 정말 시간이 남지 않아서 리팩토링을 하지 못했다. > 이제는 진짜 할 것이다... (아래로...) *** ## 공식문서, 너는 어떻게 추천해주니? 자 진짜 리팩토링 한다... 일단 모를때는 공식문서부터 봐봅시다... (이미지: 공식문서에서의 QueryKey의 중요성) > For tips on organizing Query Keys in larger applications, have a look at Effective React Query Keys and check the Query Key Factory Package from the Community Resources. **참고 자료**: * [Effective React Query Keys](https://tkdodo.eu/blog/effective-react-query-keys) * [Query Key Factory Package](https://www.npmjs.com/package/query-key-factory) 당연히 저말고도 많은 사람들이 비슷한 고민을 겪고 있고, 공식문서에서는 크게 2가지 방식을 추천해주셨다. 하나씩 알아보고자 한다. *** ## 1. Effective React Query Keys Effective React Query Keys에서는 먼저 저의 뼈를 찌르는 문장으로 시작했다. ### 1. Colocate (코드 근처에 배치) 모든 `QueryKey`를 `/src/utils/queryKeys.ts`와 같은 글로벌 파일에 저장하는 것이 좋은 선택이라고 생각하지 않다. 대신 `QueryKey`를 관련된 쿼리와 가까운 위치에 배치한다. 예를 들면, 다음과 같은 구조입니다: ```js src ├─ features │ ├─ Profile │ │ ├─ index.tsx │ │ ├─ queries.ts │ ├─ Todos │ ├─ index.tsx │ ├─ queries.ts ``` 각 `queries.ts` 파일은 React Query와 관련된 모든 내용을 포함하며, 일반적으로 커스텀 훅만 export한다. 쿼리 함수와 `Query Key`는 지역적으로 관리된다. 이를 보며 일단 폴더 구조를 features 중심으로 변경해야겠다고 생각했다. *** ### 2. 항상 배열 형태의 Query Key 사용하기 `QueryKey`는 문자열 하나로도 정의할 수 있지만, 통일성을 위해 항상 `배열(Array)`을 사용하는 것이 좋다. React Query는 내부적으로 문자열도 배열로 변환하므로 아래처럼 작성하는 것이 더 좋다: ```js // 🚨 React Query가 내부적으로 ['todos']로 변환함 useQuery({ queryKey: 'todos' }); // ✅ 배열 형태로 작성 useQuery({ queryKey: ['todos'] }); ``` **업데이트**: React Query v4부터는 모든 `Query Key`가 배열 형태여야 한다. ### 3. Query Key 구조 설계 `QueryKey`는 일반적인 수준에서부터 구체적인 수준까지 단계적으로 구조화하는 것이 좋다. 필요에 따라 세부적인 레벨을 추가하세요. 예를 들어, 필터링 가능한 ToDo 리스트와 세부 조회를 제공하는 경우는 아래와 같이 설계할 수 있다: ```js ['todos', 'list', { filters: 'all' }], ['todos', 'list', { filters: 'done' }], ['todos', 'detail', 1], ['todos', 'detail', 2]; ``` 이러한 구조를 사용하면 다음과 같은 이점이 있다: 1. `['todos']`: ToDo와 관련된 모든 데이터를 무효화할 수 있음 2. `['todos', 'list']`: 모든 리스트를 무효화할 수 있음 3. 특정 키를 지정하여 특정 리스트나 데이터를 갱신 가능 ### 4. Mutation에서 유연한 업데이트 #### 1. 상세 정보와 리스트 업데이트 ```js function useUpdateTitle() { return useMutation({ mutationFn: updateTitle, onSuccess: (newTodo) => { // ✅ 상세 데이터를 업데이트 queryClient.setQueryData(['todos', 'detail', newTodo.id], newTodo); // ✅ 이 ToDo가 포함된 모든 리스트를 업데이트 queryClient.setQueriesData(['todos', 'list'], (previous) => previous.map((todo) => (todo.id === newTodo.id ? newTodo : todo)) ); }, }); } ``` #### 2. 모든 리스트 무효화 구체적인 키를 설정하기 어려운 경우, 모든 리스트를 무효화하는 방식도 가능한다: ```js function useUpdateTitle() { return useMutation({ mutationFn: updateTitle, onSuccess: (newTodo) => { queryClient.setQueryData(['todos', 'detail', newTodo.id], newTodo); // ✅ 모든 리스트를 무효화 queryClient.invalidateQueries({ queryKey: ['todos', 'list'], }); }, }); } ``` #### 3. 활성 리스트를 제외한 무효화 URL에서 현재 필터를 읽어와 활성화된 리스트만 업데이트하고, 나머지 리스트는 무효화하는 방식: ```js function useUpdateTitle() { // URL에서 현재 필터를 읽어오는 커스텀 훅 const { filters } = useFilterParams(); return useMutation({ mutationFn: updateTitle, onSuccess: (newTodo) => { queryClient.setQueryData(['todos', 'detail', newTodo.id], newTodo); // ✅ 현재 보고 있는 리스트를 업데이트 queryClient.setQueryData(['todos', 'list', { filters }], (previous) => previous.map((todo) => (todo.id === newTodo.id ? newTodo : todo)) ); // 🥳 활성화된 리스트는 제외하고, 나머지 리스트를 무효화 queryClient.invalidateQueries({ queryKey: ['todos', 'list'], refetchType: 'none', // v4에서 사용 }); }, }); } ``` *** ## 2. Query Key Factory 사실 1번의 방법을 통해 `QueryKey`의 효율적 관리를 위해 기능별 폴더구조를 잡는게 중요한 것을 알 수 있게 되었지만, 개인적으로 `QueryKey`를 효율적으로 관리하는 부분에 대한 궁금증은 아직 해소되지 않았다. 공식문서에서 아래와 같은 라이브러리를 활용하는 것을 추천해주었기에 한번 바로 사용해보고자 했다. > **참고 자료**: [Query Key Factory](https://github.com/lukemorales/query-key-factory) (이미지: Query Key Factory 라이브러리) #### 1. 표준화된 키 생성 (Standardized Keys) `query-key-factory`를 사용하면 모든 키가 배열 형태로 표준화된다. 또한 직렬화 가능한 객체를 포함한 키를 생성할 수 있다. ```ts export const todos = createQueryKeys('todos', { detail: (todoId: string) => [todoId], list: (filters: TodoFilters) => ({ queryKey: [{ filters }], }), }); ``` ```ts // createQueryKeys 출력: { _def: ['todos'], detail: (todoId: string) => { queryKey: ['todos', 'detail', todoId], }, list: (filters: TodoFilters) => { queryKey: ['todos', 'list', { filters }], }, } ``` `queryKey`가 필요하지 않은 경우에는 `null`로 설정할 수도 있다: ```ts export const users = createQueryKeys('users', { list: { queryKey: null, queryFn: () => api.getUsers(), }, }); ``` *** #### 2. Query Key와 Query Option 동시 선언 (Generate the Query Options You Need) `queryKey`와 `queryFn`을 함께 선언하여 필요한 Query Option을 바로 생성할 수 있다. ```ts export const users = createQueryKeys('users', { detail: (userId: string) => ({ queryKey: [userId], queryFn: () => api.getUser(userId), }), }); export function useUserDetail(id: string) { return useQuery(users.detail(id)); } ``` *** #### 3. 문맥 기반 쿼리 생성 (Generate Contextual Queries) 특정 컨텍스트에 종속된 쿼리를 생성할 수 있다. 예를 들어 사용자의 좋아요 데이터를 가져오는 쿼리를 생성할 때 유용한다. ```ts export const users = createQueryKeys('users', { detail: (userId: string) => ({ queryKey: [userId], queryFn: () => api.getUser(userId), contextQueries: { likes: { queryKey: null, queryFn: () => api.getUserLikes(userId), }, }, }), }); // => createQueryKeys output: // { // _def: ['users'], // detail: (userId: string) => { // queryKey: ['users', 'detail', userId], // queryFn: (ctx: QueryFunctionContext) => api.getUser(userId), // _ctx: { // likes: { // queryKey: ['users', 'detail', userId, 'likes'], // queryFn: (ctx: QueryFunctionContext) => api.getUserLikes(userId), // }, // }, // }, // } export function useUserLikes(userId: string) { return useQuery(users.detail(userId)._ctx.likes); } ``` *** #### 4. 직렬화 가능한 키 스코프 정의 (Access to Serializable Keys Scope) 전체 키 스코프를 쉽게 액세스하고, 해당 컨텍스트의 캐시를 무효화할 수 있다. ```js users.detail(userId).queryKey; // => ['users', 'detail', userId] users.detail._def; // => ['users', 'detail'] ``` *** #### 5. 단일 파일에서 Query Keys 선언 (Declare Your Query Keys in a Single File) 하나의 파일에서 QueryKeys를 선언하고 관리할 수 있다. ```ts export const queries = createQueryKeyStore({ users: { all: null, detail: (userId: string) => ({ queryKey: [userId], queryFn: () => api.getUser(userId), }), }, todos: { detail: (todoId: string) => [todoId], list: (filters: TodoFilters) => ({ queryKey: [{ filters }], queryFn: (ctx) => api.getTodos({ filters, page: ctx.pageParam }), }), }, }); ``` *** #### 6. 기능별로 Query Keys 선언 (Declare Your Query Keys by Feature) 기능별로 세분화하여 QueryKeys를 선언하고, 이를 하나의 객체로 병합할 수 있다. ```ts // queries/users.ts export const users = createQueryKeys('users', { all: null, detail: (userId: string) => ({ queryKey: [userId], queryFn: () => api.getUser(userId), }), }); // queries/todos.ts export const todos = createQueryKeys('todos', { detail: (todoId: string) => [todoId], list: (filters: TodoFilters) => ({ queryKey: [{ filters }], queryFn: (ctx) => api.getTodos({ filters, page: ctx.pageParam }), }), }); // queries/index.ts export const queries = mergeQueryKeys(users, todos); ``` *** #### 7. TypeScript 기반의 강력한 타입 안전성 (Type Safety and Smart Autocomplete) 타입스크립트와 통합되어 IDE에서 자동완성 및 강력한 타입 지원을 제공한다. 키의 구조나 출력 타입을 쉽게 확인할 수 있다. **스토어의 Query Keys 타입 추론** ```ts import { createQueryKeyStore, inferQueryKeyStore, } from '@lukemorales/query-key-factory'; export const queries = createQueryKeyStore({ /* ... */ }); export type QueryKeys = inferQueryKeyStore; ``` **특정 기능의 Query Keys 타입 추론** ```ts import { createQueryKeys, inferQueryKeys, } from '@lukemorales/query-key-factory'; export const todos = createQueryKeys('todos', { detail: (todoId: string) => [todoId], list: (filters: TodoFilters) => ({ queryKey: [{ filters }], queryFn: (ctx) => api.getTodos({ filters, page: ctx.pageParam }), }), }); export type TodosKeys = inferQueryKeys; ``` *** ## 이젠 실전이다 항상 사내 프로젝트에 도입 이전에 직접 서버를 만들면서 개인적으로 먼저 작업을 한 후 효율적인 구조를 찾아보는 편입니다. 물론 제가 만든 구조가 정확한 정답은 아닐지라도, 이전보다 확실하게 개발하는데에 있어서 효율적이면 최대한 빠르게 리팩토링을 진행하고자 한다. 아래는 앞으로 사내 코드 도입에 진행 할 예시입니다. 1. 도메인을 기준으로 폴더 구조를 나누자. 이름은 중요하지 않다. 기능별 폴더 구조를 나누는게 중요하다고 느꼈다. `features`든 `domains`든 기능을 기준으로 폴더 구조를 나누어야 겠다. (이미지: 도메인을 기준으로, 폴더 구조를 나누자.) 2. 기능별 쿼리키를 분리하여 `QueryKeyFactory`를 사용하는 구조로 변경하자. ```ts import { createQueryKeyStore } from '@lukemorales/query-key-factory'; import { getAllTodos, getTodo } from '../services/todo.service'; export const todoKeys = createQueryKeyStore({ todos: { getAll: (search?: string, limit?: number) => ({ queryKey: [{ search }], queryFn: (ctx) => getAllTodos({ search, cursor: ctx.pageParam as number, limit, }), }), getById: (id: number) => ({ queryKey: [id] as const, queryFn: () => getTodo(id), }), }, }); ``` 이렇게 라이브러리를 활용하면 매우 효율적으로 쿼리키를 관리할 수 있다. 3. 해당 키를 활용하여 hooks를 생성하자 일단은 `useQuery` / `useInfiniteQuery`를 활용하는 `queries` 폴더와, `useMutation`을 활용하는 `mutations` 폴더로 크게 나누었다. ```ts // queries/todo.query.ts import { useQuery } from '@tanstack/react-query'; import { todoKeys } from '../todo.key'; export const useGetTodoList = (search?: string, limit?: number) => { return useQuery({ queryKey: todoKeys.todos.getAll(search, limit).queryKey, queryFn: todoKeys.todos.getAll(search, limit).queryFn, }); }; export const useGetTodo = (id: string) => { const parseIntId = parseInt(id); return useQuery({ queryKey: todoKeys.todos.getById(parseIntId).queryKey, queryFn: todoKeys.todos.getById(parseIntId).queryFn, }); }; ``` ```ts // mutations/todo.mutation.ts import { useMutation } from '@tanstack/react-query'; import { deleteTodo, postTodo, updateTodoDoneStatus, } from '../../services/todo.service'; import { queryClient } from '../../../../common/containers/QueryClientProvider'; import { todoKeys } from '../todo.key'; export function useCreateTodoMutation() { return useMutation({ mutationFn: postTodo, onSuccess: () => { queryClient.invalidateQueries({ queryKey: todoKeys.todos.getAll().queryKey, }); }, }); } export function useDeleteTodoMutation() { return useMutation({ mutationFn: deleteTodo, onSuccess: () => { queryClient.invalidateQueries({ queryKey: todoKeys.todos._def, }); }, }); } export function useUpdateTodoDoneStatusMutation() { return useMutation({ mutationFn: updateTodoDoneStatus, }); } export function useTodo() { const create = useCreateTodoMutation(); const remove = useDeleteTodoMutation(); const updateStatus = useUpdateTodoDoneStatusMutation(); return { create, remove, updateStatus, }; } ``` 4. 잘 사용해보자, 전체 키를 invalidate 할지, 특정 게시글만 invalidate 할지, 효율적으로 쿼리키를 활용하자. ```ts import { useNavigate } from 'react-router-dom'; import { useGetTodoList } from '../features/todo/hooks/queries/todo.queries'; import { useState } from 'react'; import { useTodo } from '../features/todo/hooks/mutations/todo.mutation'; import { queryClient } from '../common/containers/QueryClientProvider'; import { todoKeys } from '../features/todo/hooks/todo.key'; export default function TodosPage() { const navigate = useNavigate(); const [title, setTitle] = useState < string > ''; const [search, setSearch] = (useState < string) | (undefined > undefined); const { data: todos } = useGetTodoList(search); const { create, remove, updateStatus } = useTodo(); return (
setSearch(e.target.value)} placeholder='검색어를 입력해주세요.' />
setTitle(e.target.value)} placeholder='투두 제목 입력 해주세요.' />
{todos?.data.todos.map((todo) => (
navigate(`/${todo.id}`)} style={{ cursor: 'pointer', padding: 10, border: '1px solid black', margin: 10, display: 'flex', justifyContent: 'center', alignItems: 'center', }} >

{todo.title}

{todo.content}

{ e.stopPropagation(); updateStatus.mutate(todo.id); }} />
))}
); } ``` *** ## 마무리 그동안 `QueryKey` 관리에 대한 많은 고민이 있었는데 공식문서와 다양한 블로그, 라이브러리들을 탐방하며 다양한 해결책을 알아낼 수 있었다. 효율적인 `QueryKey` 관리에 대해 고민하며 기존 서비스의 폴더 구조의 유지보수 어려움에 대한 문제점도 발견하여 고칠 수 있는 소중한 기회가 되었다. 더 나아가 `Optimistic Update`를 통한 User Experience를 향상 시키기 위한 작업을 진행하려고 했는데, 이때 `QueryKey`에 대한 문제가 있었는데 이번 기회에 이를 쉽게 해결하고 원하던 `Optimistic Update`를 조금 더 쉽게 적용할 수 있게 될 것 같다. 저처럼 혹시라도 `QueryKey` 관리에 대해서 많은 고민을 한 사람에게 조금이나마 이 게시글이 도움이 되셨으면 좋겠다! 효율적인 `QueryKey` 관리에 대해 (폴더구조 등) 좋은 경험을 갖고 계신다면 댓글은 언제나 환영입니다!! 아래는 직접 사내 프로젝트 도입전 혼자 Nest.js로 서버를 만들어가며 QueryKeyFactory 테스트를 해보는 영상이니, 위의 블로그 글이 이해가 안간다면 조금씩 참고해보셔도 좋을 것 같다! --- # React Query 알고 쓰기 > Tanstack Query 흔히 React Query라고 불리는 서버상태 관리 툴에 대해서 유사하게 직접 구현을 해보며 왜 이런 기술이 개발자에게 편의성을 주는지 이해해보겠다. 요즘은 대부분 회사가 React Query를 도입하기도 하고, 대부분의 서버 데이터를 불러오는 강의들은... - 원문: https://www.yolog.co.kr/post/react-query - 카테고리: 개발 - 발행: 2025-10-12 - 수정: 2025-10-12 [Tanstack Query](https://tanstack.com/query/latest) 흔히 [React Query](https://tanstack.com/query/latest)라고 불리는 서버상태 관리 툴에 대해서 유사하게 직접 구현을 해보며 왜 이런 기술이 개발자에게 편의성을 주는지 이해해보겠다. (이미지: React Query 알고 쓰기) 요즘은 대부분 회사가 React Query를 도입하기도 하고, 대부분의 서버 데이터를 불러오는 강의들은 모두 React Query를 기반으로 진행하기 때문에 나처럼 늦게 개발을 시작한 사람에게는 React Query 말고 다른 것을 경험해보기가 쉽지 않다. React Query가 지금처럼 주류의 기술로 떠오르기 이전에는 서비스의 특성과 개발자의 취향에 따라, [redux-thunk](https://github.com/reduxjs/redux-thunk), [redux-saga](https://redux-saga.js.org/) 등 다양한 비동기 미들웨어를 채택하며 사용했고 더 효율적인 업무를 위하여 미들웨어 자체를 직접 커스텀하며 사용했다고 한다. 또 [SWR](https://swr.vercel.app/) 같은 라이브러리를 활용하기도 한다. 물론, 오늘 구현해 볼 내용 또한 강의 영상을 통해 확인할 수 있다. [👉🏻 유튜브 바로 가기 (구독해주세요)](https://youtu.be/kMaiDlYvua0?si=pwe2g7FGE2TcW2T-) *** ## useEffect만을 활용하여 서버 데이터 사용하기 React에서 서버로부터 데이터를 가져오는 작업은 컴포넌트의 주된 임무인 UI 렌더링과는 별개의 작업 즉, `부수 효과(Side Effect)`로 분류된다. React는 이러한 부수 효과를 처리하기 위해 내장 훅인 `useEffect`를 제공하며, 이를 통해 네트워크 통신과 같은 비동기 작업을 안전하게 수행하도록 한다. 하지만, 실제 서비스를 운영하다 보면 네트워크 요청을 상당히 많이한다. 개발자는 반복하는 것을 극도로 싫어하기 때문에 데이터를 가져오는 로직을 캡슐화하고 재사용성을 높이기 위해 `커스텀 훅(Custom Hook)`을 생성한다. 아래 `useCustomFetch`가 바로 그 기본적인 형태다. ```ts import { useEffect, useState } from 'react'; const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); useEffect(() => { const fetchData = async () => { // fetch API를 사용하여 서버에 데이터 요청 const response = await fetch(url); // 응답을 JSON 형태로 파싱 const data = await response.json(); // 파싱된 데이터를 상태에 저장 setData(data); }; fetchData(); }, [url]); // url이 변경될 때마다 새로운 데이터 요청 return { data }; }; ``` `useCustomFetch` 훅은 **서버 URL**을 인자로 받아, 해당 URL로 비동기 네트워크 요청을 보내고 그 결과를 `컴포넌트의 상태(State)`로 관리하여 반환한다. 물론, `fetch` 같은 경우는 HTTP 에러 상태(4xx, 5xx)가 발생한 경우에도 처리가 가능하도록 추가 로직을 작성해야하나 이는 오늘 전달하고자하는 주제와 다르기에 생략하고 진행하고자 한다. ```ts import { useCustomFetch } from '../hooks/useFetchData'; interface WelcomeData { id: number; name: string; email: string; } export const WelcomeData = () => { const { data } = useCustomFetch('url'); return (

{data?.name}

{data?.email}

); }; ``` `useCustomFetch` 훅 덕분에, 데이터를 표시해야 하는 `WelcomeData` 컴포넌트는 복잡한 데이터 패칭 로직 대신, 서버 데이터의 **타입**과 **URL**만 명시하여 필요한 데이터를 간결하게 얻어 이를 활용할 수 있다. *** ## 근데, 데이터가 무거우면? 데이터 통신 과정에서 발생하는 지연 시간은 사용자 경험(UX)을 저해하는 주된 요인이다. 사용자들은 단 몇 초의 지연에도 민감하게 반응하며, 서비스 이탈로 이어지기 쉽다. 따라서 서버 응답을 기다리는 동안 **적절한 시각적 피드백**을 제공하여 사용자에게 현재 상황을 명확히 전달하는 것이 매우 중요하다. 이러한 피드백 전략은 단순히 '기다리게' 하는 것이 아니라, 서비스가 정상적으로 작동 중이며 곧 콘텐츠가 제공될 것임을 알려 **불안감을 해소**하고 **체감 속도를 향상**시키는 데 목적이 있다. 프론트엔드 개발에서는 주로 **로딩 스피너**나 `스켈레톤 UI(Skeleton UI)` 등을 활용하여 이 문제를 해결한다. 특히 **스켈레톤 UI**는 콘텐츠의 윤곽을 미리 보여주어 사용자에게 기대감을 형성하고 지루함을 줄여주는 효과적인 방법으로 각광받고 있다. 이를 위해 아까 만든 데이터 요청 로직을 캡슐화한 `커스텀 훅(Custom Hook)`에 로딩 상태를 추가하여 관리해보겠다. ```ts import { useEffect, useState } from 'react'; export const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); // 데이터 로딩 중 여부를 나타내는 상태 const [isPending, setIsPending] = useState(false); useEffect(() => { // 데이터 요청 시작 전 로딩 상태 true로 설정 setIsPending(true); const fetchData = async () => { try { const response = await fetch(url); const data = await response.json(); setData(data); } catch (error) { // 에러 발생 시 로딩 상태 종료 setIsPending(false); throw error; } finally { // 성공/실패 여부와 관계없이 로딩 상태 종료 setIsPending(false); } }; fetchData(); }, [url]); // url이 변경될 때마다 새로운 데이터 요청 return { data, isPending }; }; ``` 데이터 패치 로직을 담당하는 `useCustomFetch` 훅에 **로딩 상태**를 관리하는 `isPending` 상태를 추가했다. 이 상태를 통해 데이터 요청 시작부터 완료까지의 과정을 사용자 인터페이스에 반영할 수 있다. ```ts import { useCustomFetch } from '../hooks/useFetchData'; interface WelcomeData { id: number; name: string; email: string; } export const WelcomeData = () => { const { data, isPending } = useCustomFetch('url'); if (isPending) { return
Loading...
; } return (

{data?.name}

{data?.email}

); }; ``` 이제 `useCustomFetch` 훅이 반환하는 `isPending` 상태를 사용하여, 데이터 로딩 중일 때 사용자에게 로딩 피드백을 제공하고, 로딩이 완료된 후에만 실제 콘텐츠를 렌더링하도록 컴포넌트를 구성한다. *** ## 응 요청 실패야. 모든 소프트웨어 개발에서 `요청 실패(Failure)`는 피할 수 없는 현실이다. 개발자의 실수, 인프라 문제(AWS, Google Cloud 등), 혹은 네트워크 불안정 등 다양한 외부 요인으로 인해 서버 요청에 `오류(Error)`가 발생할 수 있다. 이러한 오류 상황에 대해 **적절한 피드백**이 없다면, 사용자들은 텅 빈 화면을 보거나 하염없이 대기해야 하는 최악의 경험을 하게 된다. 이는 충성 고객의 이탈로 이어질 수 있으므로, 개발자는 오류 상태를 명시적으로 관리하고 이에 맞는 UI를 제공해야 한다. 앞서 구현했던 커스텀 훅에 **오류 상태 관리** 로직을 추가하여 사용자에게 명확한 피드백을 제공해보겠다. ```ts import { useEffect, useState } from 'react'; export const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); // 데이터 로딩 중 여부를 나타내는 상태 const [isPending, setIsPending] = useState(false); // 에러 발생 여부를 나타내는 상태 const [isError, setIsError] = useState(false); useEffect(() => { // 데이터 요청 시작 setIsPending(true); const fetchData = async () => { try { const response = await fetch(url); const data = await response.json(); setData(data); } catch { // 에러 발생 시 로딩 종료 및 에러 상태 설정 setIsPending(false); setIsError(true); } finally { // 성공/실패 여부와 관계없이 로딩 상태 종료 setIsPending(false); } }; fetchData(); }, [url]); // url이 변경될 때마다 새로운 데이터 요청 return { data, isPending, isError }; }; ``` 데이터 로딩 상태(`isPending`)와 마찬가지로, 오류 상태를 저장하고 반환하는 `isError` 상태를 추가하여 훅을 확장한다. ```ts import { useCustomFetch } from '../hooks/useFetchData'; interface WelcomeData { id: number; name: string; email: string; } export const WelcomeData = () => { const { data, isPending, isError } = useCustomFetch('url'); if (isPending) { return
Loading...
; } if (isError) { return
Error Occurred
; } return (

{data?.name}

{data?.email}

); }; ``` `useCustomFetch` 훅이 반환하는 `isError` 상태를 사용하여, 오류가 발생했을 때 사용자에게 상황을 알리는 적절한 UI를 제공한다. **데이터 흐름 및 사용자 경험** 1. **시작:** 컴포넌트 마운트 → `isPending` = `true` → `"Loading..."` 화면 표시 2. **성공 시:** 로딩 완료 → `isPending` = `false`, `isError` = `false` → **실제 데이터** 렌더링 3. **실패 시:** 네트워크/서버 오류 발생 → `isPending` = `false`, `isError` = `true` → `"Error Occurred"` 화면 표시 이러한 명시적인 오류 처리는 사용자가 서비스가 멈춘 것이 아니라, **일시적인 문제**가 발생했음을 인지하게 하여 당황을 줄이고, 나아가 **고객 지원 문의** 등 다음 행동을 유도할 수 있는 기반을 마련해 줄 수 있다. 안정적인 서비스 제공을 위해 오류 상황에 대한 피드백은 필수적인 요소다. *** ## 훌륭하다만… 현재 `useCustomFetch` 훅은 **캐싱 기능 부재**로 인해 심각한 비효율성을 안고 있다. 동일한 데이터에 대해 컴포넌트가 재렌더링되거나 여러 번 마운트될 때마다 불필요한 네트워크 요청이 반복적으로 발생하며, 이는 **서버 부하 증가**와 **네트워크 비용 상승**으로 이어진다. **React Query**가 주류 기술로 자리 잡은 핵심은 바로 이 캐싱 문제를 `staleTime` 등의 개념을 통해 효과적으로 해결한다는 점이다. 이는 곧 우리가 프론트엔드 단에서 직접 캐싱 로직을 구현할 수 있음을 의미한다. 이번에는 `로컬 스토리지(localStorage)`를 활용하여 React Query의 `staleTime` 원칙을 모방한 캐싱 메커니즘을 도입해 보겠다. 로컬 스토리지 기반 캐싱은 브라우저를 닫아도 데이터가 유지되어 캐싱 결과를 더 명확하게 확인할 수 있다. 물론 인메모리 메커니즘으로 구현해도 상관없다. 하지만 눈에 보이는 효율적인 실습을 위해 로컬 스토리지를 사용한다. `staleTime` 정의 ```ts const STALE_TIME = 5 * 60 * 1_000; // 5분 ``` 로컬스토리지에 저장될 캐시 데이터 구조를 정의한다. ```ts interface CacheEntry { data: T; lastFetched: number; } ``` 실제로 이를 활용하여 아래와 같이 구현할 수 있다. ```ts import { useEffect, useMemo, useState } from 'react'; // 데이터가 오래된(Stale) 상태가 되기까지의 시간 (5분) const STALE_TIME = 5 * 60 * 1_000; // 로컬 스토리지에 저장될 캐시 데이터의 구조 interface CacheEntry { data: T; // 실제 서버 데이터 lastFetched: number; // 마지막으로 데이터를 가져온 시점의 타임스탬프 } export const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); // 데이터 로딩 중 여부를 나타내는 상태 const [isPending, setIsPending] = useState(false); // 에러 발생 여부를 나타내는 상태 const [isError, setIsError] = useState(false); // URL을 localStorage 키로 사용 (useMemo로 불필요한 재계산 방지) const storageKey = useMemo(() => url, [url]); useEffect(() => { // 에러 상태 초기화 setIsError(false); const fetchData = async () => { const currentTime = new Date().getTime(); const cachedItem = localStorage.getItem(storageKey); // 1. 캐시 데이터 확인 및 신선도 검증 if (cachedItem) { try { // 로컬 스토리지에서 가져온 문자열을 객체로 역직렬화 const cachedData: CacheEntry = JSON.parse(cachedItem); // 캐시가 신선한 경우 (STALE_TIME 이내) 네트워크 요청 생략 if (currentTime - cachedData.lastFetched < STALE_TIME) { setData(cachedData.data); setIsPending(false); console.log(`[Cache Hit] Using fresh data for: ${url}`); return; // 네트워크 요청 없이 함수 종료 } // 캐시가 오래된 경우: 먼저 보여주고 백그라운드에서 새 데이터 가져오기 // 이를 통해 사용자에게 즉시 콘텐츠를 보여주며 UX 개선 setData(cachedData.data); console.log(`[Cache Stale] Refetching data for: ${url}`); } catch { // JSON 파싱 오류 발생 시 (캐시 데이터 손상) localStorage.removeItem(storageKey); console.warn( `[Cache Error] Corrupted cache for: ${url}. Cache cleared.` ); } } // 2. 네트워크 요청 (캐시가 없거나, 데이터가 오래된 경우) setIsPending(true); try { const response = await fetch(url); if (!response.ok) { throw new Error(`HTTP Status: ${response.status}`); } const newData: T = await response.json(); // 3. 성공 시 데이터 상태 갱신 및 캐시에 저장 setData(newData); const newCacheEntry: CacheEntry = { data: newData, lastFetched: new Date().getTime(), // 현재 시간을 타임스탬프로 저장 }; // 캐시 항목을 문자열로 직렬화하여 localStorage에 저장 localStorage.setItem(storageKey, JSON.stringify(newCacheEntry)); } catch (error) { setIsError(true); console.error('Fetch Failed:', error); } finally { setIsPending(false); } }; fetchData(); }, [url, storageKey]); // url이나 storageKey가 변경되면 useEffect 재실행 return { data, isPending, isError }; }; ``` 업데이트된 `useCustomFetch` 훅은 데이터 요청 전에 `localStorage`를 확인한다. `STALE_TIME`을 기준으로 데이터의 신선도를 판단하여 네트워크 요청 여부를 결정한다. 캐시가 `STALE_TIME` 이내일 경우 네트워크 요청을 완전히 생략한다. 로컬 스토리지의 데이터를 즉시 반환하여 **사용자 체감 속도와 성능을 대폭 향상**시킬 수 있다. *** ## 네트워크 요청 취소 앞서 캐싱을 통해 불필요한 네트워크 요청을 줄이는 **효율성**을 확보했지만, 아직 해결되지 않은 문제가 있다. 바로 `경쟁 상태(Race Condition)`와 **리소스 낭비**다. **React Query**는 이 문제를 해결하기 위해 웹 표준 API인 `AbortController`를 적극적으로 활용한다. `AbortController`는 **진행 중인 비동기 요청을 중간에 취소**할 수 있게 해주는 핵심 메커니즘으로, React Query가 백그라운드에서 데이터를 안정적으로 관리하는 기반이 된다. 1. `useCustomFetch`에 Abort Controller 구현 ```ts export const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); // 데이터 로딩 중 여부를 나타내는 상태 const [isPending, setIsPending] = useState(false); // 에러 발생 여부를 나타내는 상태 const [isError, setIsError] = useState(false); // URL을 localStorage 키로 사용 (useMemo로 불필요한 재계산 방지) const storageKey = useMemo(() => url, [url]); // fetch 요청을 취소하기 위한 AbortController 저장 // useRef를 사용하여 리렌더링 시에도 동일한 참조 유지 const abortControllerRef = useRef(null); useEffect(() => { // useEffect가 실행될 때마다 새로운 AbortController 생성 abortControllerRef.current = new AbortController(); // 에러 상태 초기화 setIsError(false); const fetchData = async () => { const currentTime = new Date().getTime(); const cachedItem = localStorage.getItem(storageKey); // 1. 로컬 스토리지에 캐시가 있는지 확인 if (cachedItem) { try { const cachedData: CacheEntry = JSON.parse(cachedItem); // 캐시가 신선한 경우 (STALE_TIME 이내) 네트워크 요청 생략 if (currentTime - cachedData.lastFetched < STALE_TIME) { setData(cachedData.data); setIsPending(false); console.log(`[Cache Hit] Using fresh data for: ${url}`); return; // 네트워크 요청 없이 함수 종료 } // 캐시가 오래된 경우 먼저 보여주고 백그라운드에서 새 데이터 가져오기 setData(cachedData.data); console.log(`[Cache Stale] Refetching data for: ${url}`); } catch { // JSON 파싱 실패 시 손상된 캐시 제거 localStorage.removeItem(storageKey); } } // 2. 네트워크 요청 시작 setIsPending(true); try { // AbortController의 signal을 fetch에 전달하여 취소 가능하게 만듦 const response = await fetch(url, { signal: abortControllerRef.current?.signal, }); if (!response.ok) { throw new Error(`HTTP Status: ${response.status}`); } const newData: T = await response.json(); setData(newData); // 3. 성공 시 새 데이터를 캐시에 저장 const newCacheEntry: CacheEntry = { data: newData, lastFetched: new Date().getTime(), }; localStorage.setItem(storageKey, JSON.stringify(newCacheEntry)); } catch (error) { // 요청이 취소된 경우는 정상 동작이므로 에러로 처리하지 않음 if (error instanceof Error && error.name === 'AbortError') { console.log(`[Fetch Cancelled] Request for ${url} was cancelled.`); return; } // 실제 네트워크 에러인 경우 에러 상태 설정 setIsError(true); console.error('Fetch Failed:', error); } finally { setIsPending(false); } }; fetchData(); // cleanup 함수: 컴포넌트 언마운트 또는 URL 변경 시 실행 return () => { // 진행 중인 fetch 요청을 취소하여 불필요한 네트워크 활동 중단 // 이를 통해 경쟁 상태(Race Condition)를 방지하고 리소스 낭비 방지 abortControllerRef.current?.abort(); }; }, [url, storageKey]); // url이나 storageKey가 변경되면 useEffect 재실행 return { data, isPending, isError }; }; ``` `Abort Controller` 구현의 핵심 목적은 아래와 같다. 1. `경쟁 상태(Race Condition)` 방지 * `url` 값이 빠르게 변경되어 여러 개의 요청이 순차적으로 발생했을 때, `useEffect`의 **cleanup 함수**는 이전 요청을 즉시 `abort()` 시킨다. 이로 인해 응답이 늦게 도착한 **오래된 요청의 결과**가 상태를 덮어쓰는 문제를 원천적으로 차단할 수 있다. 2. 리소스 최적화 * 컴포넌트가 데이터를 불러오는 도중에 언마운트(화면에서 제거)되면, cleanup 함수가 불필요한 네트워크 요청을 중단시켜 서버 자원 및 클라이언트 메모리 낭비를 방지한다. 이런식으로 간단하게 구현할 수 있을 것이다. ```ts import { useState } from 'react'; import { useCustomFetch } from '../hooks/useFetchData'; interface WelcomeData { id: number; name: string; email: string; } export const WelcomeData = () => { const [userId, setUserId] = useState(1); const [isVisible, setIsVisible] = useState(true); const handleChangeUser = () => { const randomId = Math.floor(Math.random() * 10) + 1; setUserId(randomId); }; return (
{isVisible && }
); }; const UserDataDisplay = ({ userId }: { userId: number }) => { const { data, isPending, isError } = useCustomFetch( `https://jsonplaceholder.typicode.com/users/${userId}` ); if (isPending) { return
Loading... (User ID: {userId})
; } if (isError) { return
Error Occurred
; } return (

{data?.name}

{data?.email}

User ID: {data?.id}

); }; ``` 간단하게 테스트를 해볼 수 있다. 1. **URL 변경 테스트** * `"다른 사용자 불러오기"` 버튼을 빠르게 연달아 클릭한다. 콘솔에서 `[Fetch Cancelled]` 메시지가 출력되는지 확인해보자. 이는 마지막 요청을 제외한 모든 중간 요청이 `abort()` 호출로 인해 중단되었음을 의미한다. 2. **언마운트 테스트** * 데이터가 로딩 중일 때 `"컴포넌트 토글"` 버튼을 클릭하여 `UserDataDisplay` 컴포넌트를 강제 언마운트한다. 이 경우에도 콘솔에서 취소 메시지를 확인할 수 있다. 불필요한 네트워크 활동이 즉시 멈춘다. 이로써 `useCustomFetch` 훅은 **캐싱**을 통한 효율성 확보와 `Abort Controller`를 통한 **안정성**까지 갖추게 되었다. *** ## 나에게 기회를 줘.. 데이터 요청 과정에서 발생하는 네트워크 불안정이나 일시적인 서버 장애는 흔한 일이다. 비록 오류 화면을 통해 사용자에게 피드백을 줄 수 있지만, **단순히 몇 초 후에 해결될 일시적인 에러**로 인해 사용자에게 실패 화면을 보여주는 것은 최적의 경험이 아니다. 만약 일시적 오류 발생 시 자동으로 `요청을 재시도(Retry)`한다면 어떨까? 사용자에게는 오류 없이 한 번에 성공한 것처럼 보이게 되어 서비스의 복원력과 신뢰도가 크게 향상된다. 이는 React Query가 기본적으로 제공하는 중요한 기능 중 하나다. 우리는 `useCustomFetch` 훅에 **최대 재시도 횟수**와 `지수 백오프(Exponential Backoff)` 전략을 적용하여 유사하게 재시도 기능을 구현해보겠다. *** ### 자동 재시도 로직이 적용된 `useCustomFetch` `MAX_RETRIES`와 `INITIAL_RETRY_DELAY` 상수를 정의하고, `fetchData` 함수에 재귀 호출을 통해 오류 시 자동으로 재시도하는 로직을 추가했다. ```ts import { useEffect, useMemo, useRef, useState } from 'react'; // 최대 재시도 횟수 const MAX_RETRIES = 3; // 초기 재시도 지연 시간 (밀리초) const INITIAL_RETRY_DELAY = 1000; export const useCustomFetch = (url: string) => { // 서버에서 가져온 데이터를 저장하는 상태 const [data, setData] = useState(null); // 데이터 로딩 중 여부를 나타내는 상태 const [isPending, setIsPending] = useState(false); // 에러 발생 여부를 나타내는 상태 const [isError, setIsError] = useState(false); // URL을 localStorage 키로 사용 const storageKey = useMemo(() => url, [url]); // fetch 요청을 취소하기 위한 AbortController 저장 const abortControllerRef = useRef(null); // 재시도 타이머 ID를 저장 (cleanup 시 타이머 취소에 사용) const retryTimeoutRef = useRef(null); useEffect(() => { // 새로운 요청을 위한 AbortController 생성 abortControllerRef.current = new AbortController(); setIsError(false); // currentRetry: 현재까지 재시도한 횟수 (기본값 0) const fetchData = async (currentRetry = 0) => { const currentTime = new Date().getTime(); const cachedItem = localStorage.getItem(storageKey); // 1. 캐시 확인 로직 if (cachedItem) { try { const cachedData: CacheEntry = JSON.parse(cachedItem); // 캐시가 신선한 경우 네트워크 요청 생략 if (currentTime - cachedData.lastFetched < STALE_TIME) { setData(cachedData.data); setIsPending(false); return; } // 캐시가 오래된 경우 먼저 보여주고 백그라운드에서 새 데이터 가져오기 setData(cachedData.data); } catch { // 손상된 캐시 제거 localStorage.removeItem(storageKey); } } // 2. 네트워크 요청 setIsPending(true); try { // signal을 전달하여 요청 취소 가능하게 설정 const response = await fetch(url, { signal: abortControllerRef.current?.signal, }); if (!response.ok) { throw new Error(`HTTP Status: ${response.status}`); } const newData: T = await response.json(); setData(newData); // 캐시에 새 데이터 저장 const newCacheEntry: CacheEntry = { data: newData, lastFetched: new Date().getTime(), }; localStorage.setItem(storageKey, JSON.stringify(newCacheEntry)); setIsPending(false); } catch (error) { // 요청이 취소된 경우는 정상 동작이므로 에러로 처리하지 않음 if (error instanceof Error && error.name === 'AbortError') { console.log('[Fetch Cancelled] Request cancelled.'); return; } // 3. 재시도 로직 if (currentRetry < MAX_RETRIES) { // 지수 백오프: 1초 → 2초 → 4초 → 8초... const retryDelay = INITIAL_RETRY_DELAY * Math.pow(2, currentRetry); console.log( `[Retry ${ currentRetry + 1 }/${MAX_RETRIES}] Retrying in ${retryDelay}ms...` ); // 지연 후 재귀적으로 fetchData 호출 (재시도 횟수 증가) retryTimeoutRef.current = window.setTimeout(() => { fetchData(currentRetry + 1); }, retryDelay); } else { // 최대 재시도 횟수 초과 시 최종 에러 처리 setIsError(true); setIsPending(false); console.error( `[Fetch Failed] Maximum retries (${MAX_RETRIES}) exceeded:`, error ); } } }; fetchData(); // cleanup 함수: 컴포넌트 언마운트 또는 의존성 변경 시 실행 return () => { // 진행 중인 fetch 요청 취소 abortControllerRef.current?.abort(); // 예약된 재시도 타이머 취소 // 이를 통해 컴포넌트가 사라진 후에도 불필요한 재시도가 실행되는 것을 방지 if (retryTimeoutRef.current !== null) { clearTimeout(retryTimeoutRef.current); retryTimeoutRef.current = null; } }; }, [url, storageKey]); return { data, isPending, isError }; }; ``` ### 재시도 로직의 핵심 원리 1. `지수 백오프(Exponential Backoff)`: 재시도 간의 간격을 2n (1초, 2초, 4초...) 형태로 늘려 연속적인 서버 부하를 줄이고 서버가 복구될 시간을 벌어준다. 2. **안전한 취소**: `retryTimeoutRef`에 `setTimeout` ID를 저장하고 `useEffect`의 **cleanup 함수**에서 이를 `clearTimeout`하여, 컴포넌트가 언마운트되거나 URL이 변경될 때 **불필요한 재시도**가 계속 실행되는 것을 방지한다. *** ### 재시도 기능 테스트 컴포넌트 새로 추가된 `"재시도 테스트 (404 에러)"` 버튼을 통해 의도적으로 오류를 발생시키고 자동 재시도 과정을 확인할 수 있다. ```ts import { useState } from 'react'; import { useCustomFetch } from '../hooks/useFetchData'; interface WelcomeData { id: number; name: string; email: string; } export const WelcomeData = () => { const [userId, setUserId] = useState(1); const [isVisible, setIsVisible] = useState(true); const handleChangeUser = () => { const randomId = Math.floor(Math.random() * 10) + 1; setUserId(randomId); }; const handleTestRetry = () => { setUserId(999999); }; return (
{isVisible && }
); }; const UserDataDisplay = ({ userId }: { userId: number }) => { const { data, isPending, isError } = useCustomFetch( `https://jsonplaceholder.typicode.com/users/${userId}` ); if (isPending) { return
Loading... (User ID: {userId})
; } if (isError) { return
Error Occurred
; } return (

{data?.name}

{data?.email}

User ID: {data?.id}

); }; ``` ### 테스트 결과 확인 1. `"재시도 테스트"` 버튼을 클릭한다. 2. **콘솔(Console)** 탭을 관찰한다 * 요청 실패 후 `[Retry 1/3] Retrying in 1000ms...`와 같은 메시지가 **최대 3회** 출력되는지 확인한다. * 3회 재시도 후에도 실패하면 최종적으로 `[Fetch Failed] Maximum retries (3) exceeded` 메시지가 출력되고 화면에 `"Error Occurred"`가 표시된다. 이로써 `useCustomFetch` 훅은 **캐싱**, **요청 취소**, 그리고 **자동 재시도**라는 React Query의 핵심 기능을 모두 갖추게 되어, 높은 성능과 안정성을 확보한 서버 상태 관리 훅으로 React Query와 유사하게 개선해보았다. *** ## 응 수고했어 그냥 리액트 쿼리 써. 우리가 100줄이 넘는 코드로 구현해야 했던 복잡한 로직들(캐시 타임스탬프 관리, `setTimeout`/`clearTimeout` 처리, `AbortController` 연결 및 에러 분기 처리 등)은 React Query를 사용하면 **단 하나의 훅**과 **선언적인 설정**으로 대체된다. React Query는 이 모든 상태 관리와 네트워크 최적화를 개발자가 직접 구현할 필요 없이 **자동으로 처리**해주는 강력한 라이브러리다. React Query를 사용한 `useCustomFetch` 구현 다음 코드는 우리가 수동으로 구현했던 모든 기능을 포함하여, 오히려 **더 안정적인** 서버 상태 관리 기능을 제공한다. ```ts import { useQuery } from '@tanstack/react-query'; export const useCustomFetch = (url: string) => { return useQuery({ // 쿼리 키: 데이터를 식별하고 캐싱하는 고유 키 // url이 같으면 같은 캐시를 공유하고, url이 다르면 별도로 관리 queryKey: [url], // 쿼리 함수: 실제로 데이터를 가져오는 비동기 함수 // React Query가 자동으로 signal을 제공하여 요청 취소 지원 queryFn: async ({ signal }) => { const response = await fetch(url, { signal }); if (!response.ok) { throw new Error(`HTTP Status: ${response.status}`); } return response.json() as Promise; }, // 재시도 설정: 실패 시 최대 3회 자동 재시도 retry: 3, // 재시도 지연 시간: 지수 백오프 전략 // 0회차: 1초, 1회차: 2초, 2회차: 4초 (최대 30초 제한) retryDelay: (attemptIndex) => Math.min(1000 * Math.pow(2, attemptIndex), 30000), // 데이터 신선도 관리: 5분 동안은 네트워크 요청 없이 캐시 사용 staleTime: 5 * 60 * 1000, // 가비지 컬렉션: 쿼리가 사용되지 않은 채로 10분이 지나면 캐시에서 제거 gcTime: 10 * 60 * 1000, }); }; ``` 이처럼 React Query는 서버 상태 관리에 필요한 모든 복잡한 **절차적** 로직을 추상화하고 **선언적**인 API를 제공함으로써, 개발자가 비즈니스 로직에만 집중할 수 있도록 돕는 현대 React 개발의 표준이라고 할 수 있다. *** ## 마치며 서비스 개발을 통해 고객에게 기쁨을 주는 경험은 내가 개발을 좋아하는 가장 큰 이유다. 직접 서버와 프론트엔드를 구현하며 프로젝트를 배포하여 이것들을 누군가 좋아해주는 과정에서 큰 보람을 느꼈다. 최근 Vue.js와 Vite를 만든 Evan You와 같은 개발자들을 보며, 개발자들에게 편리함을 제공하는 프레임워크, 라이브러리, 번들러를 만드는 일 역시 사용자에게 직접적인 가치를 전달하는 것만큼이나 가치 있는 일이라고 생각하게 되었다. 아직 실력이 부족하지만, 개발의 방향을 도구의 창조자로 확장하고자 한다. 1. **기술의 원리 분석**: 현재 사용하고 있는 라이브러리와 프레임워크들을 분해하고 분석하는 과정을 통해, 그들이 해결하고자 했던 근본적인 문제와 설계 의도를 깊이 이해하는 데 집중하고자 한다. 2. **생태계 기여**: 오픈 소스 프로젝트에 기여하며 경험을 쌓고, 궁극적으로 개발 커뮤니티에 유용하고 혁신적인 번들러나 라이브러리를 직접 만들어 제공할 수 있는 실력을 갖추고자 한다. 많이 힘들겠지만, 서비스 개발의 보람과 개발 환경 개선의 가치를 모두 추구하며, 기술 생태계에 긍정적인 영향을 미치는 개발자로 성장해 보고 싶다. ## 핵심 정리 * **useEffect의 한계**: 서버 데이터 패칭 시 로딩, 에러, 캐싱, 재시도 등 반복적인 로직 필요 * **직접 구현의 복잡성**: * 캐싱: 타임스탬프 관리, staleTime/gcTime 설정 * 요청 취소: AbortController로 불필요한 네트워크 요청 방지 * 재시도: 지수 백오프 전략, 최대 재시도 횟수 관리 * 경쟁 상태: 여러 요청의 순서 보장 * **React Query의 장점**: * 선언적 API로 복잡한 절차적 로직 추상화 * queryKey로 자동 캐싱 및 중복 요청 제거 * signal로 자동 요청 취소 * retry, retryDelay로 자동 재시도 * staleTime, gcTime으로 캐시 관리 * **핵심 개념**: * `queryKey`: 데이터 식별 및 캐싱 키 * `queryFn`: 실제 데이터 패칭 함수 * `staleTime`: 데이터 신선도 유지 시간 * `gcTime`: 캐시 가비지 컬렉션 시간 **React Query는 마치 전문 비서와 같다. 데이터를 언제 가져올지, 얼마나 보관할지, 실패하면 몇 번 재시도할지 모두 알아서 관리해준다. 개발자는 비즈니스 로직에만 집중하면 된다.** --- # Webpack이 등장한 이유 > JavaScript에서 ES2015(ES6)부터 문법 수준에서 모듈을 지원하기 시작했다. import와 export 키워드가 도입되었지만 모든 브라우저에서 이를 사용할 수 있게 된 것은 Webpack과 같은 번들러가 등장하면서부터다. Webpack이 등장하기 이전에는 어떤 방식으로... - 원문: https://www.yolog.co.kr/post/webpack - 카테고리: 개발 - 발행: 2025-10-11 - 수정: 2025-10-11 ## Webpack이 필요한 이유 JavaScript에서 `ES2015(ES6)`부터 문법 수준에서 모듈을 지원하기 시작했다. `import`와 `export` 키워드가 도입되었지만 모든 브라우저에서 이를 사용할 수 있게 된 것은 `Webpack`과 같은 번들러가 등장하면서부터다. Webpack이 등장하기 이전에는 어떤 방식으로 모듈을 관리했는지 살펴보자. (이미지: 웹팩 너는 무엇이냐..) *** ### 모듈 시스템의 역사 **모듈 시스템 이전의 JavaScript** 과거에는 여러 JavaScript 파일을 HTML에 순서대로 로드하는 방식으로 코드를 구성했다. 간단한 예제를 통해 살펴보자. ```js // calculator.js function multiply(a, b) { return a * b; } function divide(a, b) { return a / b; } ``` ```js // app.js console.log(multiply(5, 3)); // 15 console.log(divide(10, 2)); // 5 ``` HTML 파일에서 이 스크립트들을 로드할 때는 순서가 매우 중요하다. `calculator.js`를 먼저 로드해야 `app.js`에서 함수를 사용할 수 있다. ```html Module Example ``` `open index.html` 명령어로 브라우저에서 실행하면 콘솔에 다음과 같이 출력된다. ``` 콘솔 출력: 15 5 ``` **전역 스코프 오염 문제** 과거에는 `index.html`에 여러 JavaScript 파일을 순서대로 로드하여 다른 파일의 함수를 사용했다. 하지만 이 방식에는 **전역 스코프 오염**이라는 심각한 문제가 있다. `calculator.js`에서 정의한 `multiply` 함수는 해당 파일 안에서만 유효한 것이 아니라, 애플리케이션 전역에서 접근할 수 있다. 브라우저 개발자 도구 콘솔에서 확인해보자. ``` > multiply ƒ multiply(a, b) { return a * b; } > window.multiply ƒ multiply(a, b) { return a * b; } ``` 전역 스코프 `window` 객체에 함수가 등록된 것을 확인할 수 있다. ``` > multiply(10, 4) 40 ``` 함수를 바로 호출할 수도 있다. 하지만 JavaScript는 동적 타입 언어이기 때문에 함수 변수에 다른 값을 할당할 수 있다. ``` > multiply = 2 2 > multiply(10, 4) Uncaught TypeError: multiply is not a function ``` 이렇게 전역 스코프가 오염되면 애플리케이션이 예측 불가능해지고, 결국 런타임 에러가 발생하게 된다. *** **IIFE 방식의 모듈** `IIFE(Immediately Invoked Function Expression)`는 즉시 실행 함수 표현식이다. 함수를 정의하자마자 실행하는 패턴으로, 함수 내부에 독립적인 스코프를 생성한다. 이를 통해 내부에서 정의한 변수나 함수가 외부에서 접근할 수 없도록 하여 전역 스코프 오염을 예방할 수 있다. 앞서 만들었던 `calculator` 모듈을 IIFE 방식으로 변경해보자. ```js // calculator.js // 전역 네임스페이스 calculator 생성 // 이미 존재하면 기존 것을 사용하고, 없으면 빈 객체 할당 var calculator = calculator || {}; // 즉시 실행 함수 (function () { // 이 안에서 정의된 함수는 외부에서 접근 불가 function multiply(a, b) { return a * b; } function divide(a, b) { return a / b; } // 전역 네임스페이스에 필요한 함수만 노출 calculator.multiply = multiply; calculator.divide = divide; })(); ``` 이 패턴의 동작 원리를 단계별로 살펴보자. **1단계: 전역 네임스페이스 생성** ```js var calculator = calculator || {}; ``` `calculator`라는 전역 네임스페이스를 만들고, 이미 존재하면 기존 것을 사용하고 없으면 빈 객체를 할당한다. **2단계: IIFE로 독립적인 스코프 생성** ```js (function () { // 외부로부터 독립적인 스코프 })(); ``` 함수를 즉시 정의하고 실행하면, 이 함수 내부의 스코프는 외부로부터 완전히 독립된다. **3단계: 필요한 함수만 네임스페이스에 노출** 함수 내부에서 `multiply`와 `divide`를 정의하고, 이 함수들을 외부에서 사용할 수 있도록 전역 네임스페이스 `calculator`에 할당한다. 이제 `app.js`에서는 다음과 같이 사용해야 한다. ```js // 잘못된 사용 - multiply는 전역 스코프에 없음 // console.log(multiply(5, 3)); // ReferenceError // 올바른 사용 - calculator 네임스페이스를 통해 접근 console.log(calculator.multiply(5, 3)); // 15 console.log(calculator.divide(10, 2)); // 5 ``` 브라우저 콘솔에서 확인하면 `multiply` 함수는 전역에 직접 노출되지 않고, `calculator` 네임스페이스를 통해서만 접근할 수 있다. ``` > multiply Uncaught ReferenceError: multiply is not defined > calculator.multiply ƒ multiply(a, b) { return a * b; } > calculator.multiply(10, 4) 40 ``` *** **다양한 모듈 스펙** JavaScript 모듈을 구현하는 대표적인 명세가 `AMD`와 `CommonJS`이다. **CommonJS** `CommonJS`는 JavaScript를 사용하는 모든 환경에서 모듈을 사용하는 것을 목표로 한다. `exports` 키워드로 모듈을 만들고, `require()` 함수로 모듈을 불러온다. ```js // calculator.js exports.multiply = function (a, b) { return a * b; }; exports.divide = function (a, b) { return a / b; }; // app.js const calculator = require('./calculator.js'); console.log(calculator.multiply(5, 3)); // 15 console.log(calculator.divide(10, 2)); // 5 ``` 대표적으로 서버 사이드 플랫폼인 `Node.js`에서 `CommonJS`를 사용한다. `calculator`라는 모듈을 만들 때 `exports` 키워드로 함수를 내보내고, `require()` 함수로 모듈의 경로를 전달하면 해당 모듈을 가져올 수 있다. **AMD와 UMD** `AMD(Asynchronous Module Definition)`는 비동기로 로딩되는 환경에서 모듈을 사용하는 것을 목표로 한다. 주로 브라우저 환경에서 사용된다. 브라우저처럼 외부에서 JavaScript를 로딩해야 하는 비동기 환경에서는 `AMD` 스펙을 사용한다. `CommonJS`와 `AMD` 두 가지를 모두 지원하는 것이 `UMD` 스펙이다. **ES2015 표준 모듈** 이후 `ES2015`에서 표준 모듈 시스템이 만들어졌다. 현재는 `Babel`이나 `Webpack`을 이용해서 표준 모듈 시스템을 사용하는 것이 일반적이다. ```js // calculator.js export function multiply(a, b) { return a * b; } export function divide(a, b) { return a / b; } // app.js // 모든 export를 가져오기 import * as calculator from './calculator.js'; // 필요한 것만 가져오기 // import { multiply, divide } from './calculator.js'; console.log(calculator.multiply(5, 3)); // 15 console.log(calculator.divide(10, 2)); // 5 ``` `export` 구문으로 모듈을 만들고, `import` 구문으로 가져올 수 있다. **브라우저의 모듈 지원** 모든 브라우저가 ES 모듈을 지원하는 것은 아니다. `Internet Explorer`를 포함한 몇몇 모바일 브라우저는 모듈 시스템을 지원하지 않는다. 최신 브라우저(Chrome, Firefox, Safari 등)에서는 모듈 시스템을 어떻게 사용하는지 살펴보자. ```html ES Module Example ``` 스크립트 태그를 로드할 때 `type="text/javascript"` 대신 `type="module"`을 사용하면 `app.js`에서 모듈을 사용할 수 있다. 그러나 브라우저에 무관하게 모듈을 사용하고 싶다면 바로 여기서 **Webpack**이 필요한다. **로컬 파일 실행 시 CORS 문제** 위 코드를 그대로 실행하면 `CORS` 에러가 발생할 수 있다. 브라우저가 파일을 직접 읽지 않고 HTTP 서버를 통해 로드해야 하기 때문이다. 이를 해결하기 위해 간단한 개발 서버를 실행해보자. ```bash npx light-server ``` 서버가 실행되면 다음과 같이 출력된다. ``` Light server is listening at http://localhost:4000 serving static dir: ./ when file changes, reload the page ``` 이제 `http://localhost:4000`에 접속하여 모듈이 제대로 동작하는지 확인할 수 있다. *** ## Webpack 설치 및 기본 사용 ### 설치 및 CLI 사용법 모듈로 개발하게 되면 모듈 간의 의존 관계가 생긴다. 하나의 JavaScript 모듈에서 다른 모듈을 `import`하는 방식이다. 예를 들어 다음과 같은 의존 관계를 생각해볼 수 있다. ``` app.js (엔트리 포인트) ├─ calculator.js ├─ formatter.js └─ utils.js └─ helpers.js ``` 이렇게 만든 구조가 우리가 만든 `app.js`와 `calculator.js`의 관계와 유사하다. Webpack은 모듈로 연결된 여러 개의 JavaScript 파일을 하나로 합쳐주는 역할을 한다. 이렇게 하나로 합쳐진 파일을 `번들(Bundle)`이라고 하고, 이 작업을 하는 도구를 `번들러(Bundler)`라고 한다. Webpack이 바로 이런 번들링 작업을 수행하는 대표적인 번들러이다. *** 번들러 작업을 하는 `webpack` 패키지와, Webpack을 터미널 명령어로 사용할 수 있게 해주는 `webpack-cli`를 설치해보자. ```bash npm install -D webpack webpack-cli ``` 이 글에서는 다음 버전을 기준으로 진행한다. ```json { "devDependencies": { "webpack": "^5.102.0", "webpack-cli": "^6.0.1" } } ``` 먼저 `--help` 옵션으로 Webpack을 어떻게 사용하는지 알아보자. ```bash node_modules/.bin/webpack --help ``` Webpack을 실행할 때 필수적인 옵션은 3가지이다. **1. mode 옵션** 개발 환경(`development`) 또는 운영 환경(`production`)을 지정한다. **2. entry 옵션** 모듈의 시작점(엔트리 포인트)을 지정한다. Webpack은 이 파일부터 시작해서 연결된 모든 모듈을 찾아간다. **3. output 옵션** 엔트리 포인트를 통해 웹팩이 모든 모듈을 합친 결과물을 저장하는 경로를 설정한다. **Webpack 4 vs 5 차이점** Webpack 4에서는 `--output` 뒤에 경로와 파일명을 함께 지정할 수 있었다. ```bash # Webpack 4 node_modules/.bin/webpack --mode development --entry ./src/app.js --output dist/main.js ``` Webpack 5부터는 `--output`이 디렉토리 경로만 받을 수 있고, 파일명은 별도 옵션으로 지정해야 한다. * `--output-path`: 빌드 산출물이 저장될 폴더 경로 * `--output-filename`: 출력될 파일 이름 ```bash # Webpack 5 node_modules/.bin/webpack --mode development --entry ./src/app.js --output-path dist --output-filename main.js ``` 빌드가 성공하면 다음과 같은 메시지가 출력된다. ``` asset main.js 4.5 KiB [emitted] (name: main) ./src/app.js 150 bytes [built] [code generated] ./src/calculator.js 120 bytes [built] [code generated] webpack 5.102.0 compiled successfully in 150 ms ``` *** **빌드 결과 사용하기** 이제 `index.html`에서 빌드된 파일을 로드해보자. ```html Webpack Example ``` 이제 모든 브라우저에서 모듈 시스템을 사용할 수 있다. 콘솔에 다음과 같이 정상적으로 출력되는 것을 확인할 수 있다. ``` 콘솔 출력: 15 5 ``` Webpack은 이렇게 여러 개의 모듈을 하나의 파일로 만들어주는 역할을 한다. **설정 파일 만들기** Webpack 설정을 할 때 매번 터미널에 긴 옵션을 입력하는 것은 비효율적이다. 설정 파일을 만들어서 관리하는 것이 좋다. `--help` 문서를 보면 `--config` 옵션이 있는데, 이를 통해 Webpack 설정 파일을 지정할 수 있다. 기본 파일명은 `webpack.config.js`이다. 프로젝트 루트에 `webpack.config.js` 파일을 생성하자. ```js // webpack.config.js const path = require('path'); // Node의 모듈 시스템 사용 module.exports = { mode: 'development', entry: { main: './src/app.js', // 엔트리가 여러 개일 경우 // sub: './src/sub.js', }, output: { // path는 절대 경로로 지정 path: path.resolve('./dist'), // 엔트리 키 값으로 동적 파일명 생성 // main.js, sub.js 형태로 생성됨 filename: '[name].js', }, }; ``` 설정을 자세히 살펴보자. **mode**: `development`로 설정 **entry**: 시작점을 지정하는데, 객체 형태로 지정한다. `entry` 포인트의 경로뿐만 아니라 `main`이라는 키도 설정했다. 이 키는 다음에 나올 `output` 설정에서 사용된다. **output**: `path`와 `filename`을 설정한다. * `path`: 절대 경로를 지정한다. `path.resolve()`를 사용하여 현재 디렉토리 기준으로 `dist` 폴더의 절대 경로를 생성한다. * `filename`: `[name].js`로 지정했다. `[name]` 부분이 엔트리에서 설정한 키 값(`main`)으로 치환된다. 이렇게 설정한 이유는 엔트리가 여러 개일 수 있기 때문이다. 엔트리가 여러 개면 그에 맞는 output도 여러 개여야 하는데, 파일명을 동적으로 생성할 수 있다. 예를 들어 엔트리가 다음과 같다면: ```js entry: { main: './src/app.js', sub: './src/sub.js', }, ``` `main.js`와 `sub.js`가 각각 output으로 생성된다. **npm 스크립트 등록** `npm`은 프로젝트를 관리하는 도구로, 스크립트를 자동화하는 기능이 있다. Webpack으로 코드를 번들링하는 과정을 npm 스크립트에 등록해보자. `package.json`에서 `scripts` 부분을 다음과 같이 수정한다. ```json { "scripts": { "build": "webpack" } } ``` 이제 다음 명령어로 빌드할 수 있다. ```bash npm run build ``` *** ## 로더(Loader) Webpack은 모든 파일을 모듈로 바라본다. JavaScript로 만든 모듈뿐만 아니라 CSS, 이미지, 폰트까지 전부 모듈로 처리한다. 따라서 `ES6`의 `import` 키워드를 사용하면 이런 파일들을 JavaScript 코드 안으로 가져와서 사용할 수 있다. 이것이 가능한 이유는 Webpack의 `로더(Loader)` 때문이다. Webpack의 로더는 모든 파일을 JavaScript 모듈처럼 만들어준다. 예를 들어 CSS 파일을 JavaScript에서 직접 로딩해서 사용할 수 있게 해준다. 또한 이미지 파일을 Data URL 형식의 문자열로 변환한 다음, JavaScript에서 이미지 파일을 사용할 수 있게 해주는 것이 로더의 역할이다. 로더를 사용하기 전에 직접 로더를 만들어보면서 동작 원리를 살펴보자. ### 커스텀 로더 만들기 프로젝트 루트에 `console-to-alert-loader.js` 파일을 생성한다. ```js // console-to-alert-loader.js module.exports = function consoleToAlertLoader(content) { console.log('console-to-alert 로더가 동작한다'); // console.log를 alert로 변경 return content.replace('console.log(', 'alert('); }; ``` 로더는 함수 형태로 작성한다. 로더가 파일을 읽으면 파일의 내용이 `content` 인자로 전달된다. 여기서는 로더가 동작했는지 확인하기 위해 `console.log`만 출력하고, `console.log`를 `alert`로 변경하는 간단한 작업을 수행한다. 이제 만든 로더를 Webpack 설정에 연결해야 한다. ```js // webpack.config.js const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { // 로더가 처리해야 하는 파일들의 패턴 (정규표현식) // .js로 끝나는 모든 파일 처리 test: /\.js$/, use: [path.resolve('./console-to-alert-loader.js')], }, ], }, }; ``` `module.rules` 배열에 로더 규칙을 추가했다. * `test`: 로더가 처리할 파일의 패턴을 정규표현식으로 지정한다. `/\.js$/`는 `.js`로 끝나는 모든 파일을 의미한다. * `use`: 사용할 로더의 경로를 지정한다. JavaScript 파일이 아닌 파일들은 이 로더가 처리하지 않는다. 빌드하면 `console.log` 대신 `alert`가 실행되는 것을 확인할 수 있다. ``` 터미널 출력: console-to-alert 로더가 동작한다 asset main.js 4.8 KiB [emitted] (name: main) ``` 브라우저에서 실행하면 `alert` 창이 뜬다. *** ### 주요 로더 사용법 이제 실무에서 자주 사용되는 대표적인 로더 몇 가지를 살펴보자. **css-loader와 style-loader** CSS 파일에 로더를 설정하면 JavaScript 파일에서 CSS 파일을 모듈로 불러올 수 있다. ```js // app.js import './app.css'; ``` 일반적으로는 이 코드가 동작하지 않는다. Webpack의 로더를 사용하면 `ES6`의 `import` 구문으로 CSS 코드를 JavaScript 코드로 가져와서 사용할 수 있다. CSS 파일이 모듈이 되려면 Webpack의 로더가 CSS 파일을 JavaScript 모듈로 변환해주어야 한다. 스타일 코드를 작성해보자. ```css /* app.css */ body { background-color: #f0f0f0; font-family: Arial, sans-serif; } h1 { color: #333; text-align: center; } ``` `app.js`에서 이 CSS 파일을 import한다. ```js // app.js import './app.css'; import * as calculator from './calculator.js'; console.log(calculator.multiply(5, 3)); console.log(calculator.divide(10, 2)); ``` 빌드를 하면 오류가 발생한다. ``` ERROR in ./src/app.css 1:4 Module parse failed: Unexpected token (1:4) You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. ``` Webpack이 CSS 파일을 읽다가 문법을 이해하지 못해서 에러를 발생시킨 것이다. Webpack이 CSS 파일을 JavaScript에서 모듈로 가져올 수 있도록 CSS 파일을 처리해주는 것이 `css-loader`이다. 로더를 사용하려면 먼저 설치해야 한다. ```bash npm install -D css-loader ``` Webpack 설정에 로더를 추가한다. ```js // webpack.config.js const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { // CSS 파일을 처리하는 로더 test: /\.css$/, use: ['css-loader'], }, ], }, }; ``` Webpack은 엔트리 포인트부터 시작해서 연결된 모든 모듈을 검색한다. 그러다가 CSS 파일을 만나면 이 패턴(`/\.css$/`)에 의해 `css-loader`가 동작한다. 빌드가 성공한다. ``` asset main.js 7.2 KiB [emitted] (name: main) ./src/app.js 180 bytes [built] [code generated] ./src/calculator.js 140 bytes [built] [code generated] ./src/app.css 250 bytes [built] [code generated] webpack 5.102.0 compiled successfully in 280 ms ``` `dist` 폴더를 보면 CSS 파일이 별도로 있는 것이 아니라 `main.js`에 포함되어 있다. JavaScript 문자열로 CSS 코드가 변환된 것을 확인할 수 있다. 하지만 브라우저에서 확인해보면 스타일이 적용되지 않는다. HTML 코드가 DOM으로 변환되어야 브라우저에 문서가 보이듯이, CSS 코드도 CSSOM(CSS Object Model)으로 변환되어야 브라우저에서 스타일이 적용된다. 그러려면 HTML 파일에서 CSS 코드를 직접 불러오거나, 인라인 스타일로 넣어줘야 한다. 아직 그런 처리를 하지 않고 JavaScript 파일에만 CSS 코드가 있어서 브라우저에 적용되지 않는 것이다. `style-loader`는 JavaScript로 변경된 스타일 코드를 HTML에 삽입해주는 로더이다. CSS 코드를 모듈로 사용하고 Webpack으로 번들링하려면 `css-loader`와 `style-loader` 두 가지를 함께 사용해야 한다. 먼저 `style-loader`를 설치한다. ```bash npm install -D style-loader ``` Webpack 설정을 수정한다. ```js // webpack.config.js const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { // CSS 파일을 처리하는 로더 test: /\.css$/, // 로더는 오른쪽에서 왼쪽으로 실행됨 // css-loader로 CSS를 JavaScript로 변환 → style-loader로 HTML에 삽입 use: ['style-loader', 'css-loader'], }, ], }, }; ``` `use` 배열에 여러 로더를 지정할 때는 **오른쪽에서 왼쪽으로 실행**된다. 먼저 `css-loader`가 CSS 파일을 JavaScript 모듈로 변환하고, 그 다음 `style-loader`가 변환된 스타일을 HTML에 삽입한다. 다시 빌드하고 브라우저에서 확인하면 스타일이 제대로 적용된 것을 볼 수 있다. 개발자 도구에서 확인하면 `` 태그 안에 ` ``` *** **file-loader와 Asset Modules** 로더는 CSS뿐만 아니라 이미지 파일도 처리할 수 있다. `import` 구문으로 이미지 파일을 JavaScript로 가져와서 사용할 수 있다. CSS 파일도 모듈로 처리하기 때문에 CSS 파일에서 이미지 파일을 가져올 수 있다. 실습을 위해 이미지 파일을 프로젝트에 추가하자. `src` 폴더에 `background.jpg` 이미지를 추가한다. Webpack 4에서는 `file-loader`를 사용했다. ```bash npm install -D file-loader ``` ```js // webpack.config.js (Webpack 4) const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { // 이미지 파일을 처리하는 로더 test: /\.(png|jpe?g|gif)$/, loader: 'file-loader', options: { // 파일을 모듈로 사용했을 때 경로 앞에 추가되는 문자열 // output 경로가 dist이므로 같은 값 지정 publicPath: './dist/', // 파일이 output에 복사될 때 사용하는 파일 이름 // 원본 파일명.확장자?해시값 형태 name: '[name].[ext]?[hash]', }, }, ], }, }; ``` CSS 파일에서 이미지를 배경으로 사용해보자. ```css /* app.css */ body { background-image: url('./background.jpg'); background-size: cover; background-position: center; } ``` 빌드하면 `dist` 폴더에 이미지 파일이 복사되고, CSS에서 올바른 경로로 참조된다. Webpack 5부터는 `file-loader` 대신 내장 Asset Modules를 사용한다. ```js // webpack.config.js (Webpack 5) const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { // 이미지 파일을 처리하는 Asset Module test: /\.(png|jpe?g|gif)$/, type: 'asset/resource', }, ], }, }; ``` `type: 'asset/resource'`로 지정하면 파일을 별도로 복사하고 URL을 반환한다. 빌드하면 `dist` 폴더에 해시값이 포함된 파일명으로 이미지가 저장된다. ``` 📦 dist/ ┣ 📜 main.js ┗ 📜 a1b2c3d4e5f6g7h8i9j0.jpg ``` 파일명이 해시값으로 변경되는 이유는 **캐시 갱신**을 위해서이다. Webpack은 빌드할 때마다 유니크한 해시값을 생성한다. 정적 파일의 경우 브라우저에서 캐싱하는 경우가 많다. JavaScript, CSS, 이미지, 폰트 등을 성능을 위해 캐싱한다. 파일 내용이 변경되어도 이름이 같으면 브라우저가 이전 캐시를 사용할 수 있다. 이를 방지하는 방법 중 하나가 파일 이름을 변경하는 것이다. 실제로 실행시켜보면 이미지가 배경으로 잘 표시된다. Webpack 5에서도 파일명과 경로를 커스터마이즈할 수 있다. ```js // webpack.config.js (Webpack 5 - 상세 설정) const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { test: /\.(png|jpe?g|gif|svg|webp)$/i, type: 'asset/resource', generator: { // 브라우저에서 접근할 때 사용할 경로 publicPath: './dist/', // 파일 이름 형식 // [name]: 원본 파일명 // [contenthash]: 파일 내용 기반 해시 // [ext]: 확장자 filename: '[name].[contenthash][ext]', }, }, ], }, }; ``` *** **url-loader와 Asset Modules (inline)** 사용하는 이미지 개수가 많아지면 네트워크 요청 수가 늘어나 사이트 성능에 영향을 줄 수 있다. 만약 한 페이지 안에서 작은 이미지를 여러 개 사용한다면 `Data URL` 스키마를 이용하는 방법이 더 효율적이다. Data URL은 파일 경로 대신 파일 데이터를 직접 Base64로 인코딩한 문자열을 사용하는 방식이다. ```html 1x1 red pixel ``` 이렇게 하면 별도의 HTTP 요청 없이 HTML에 이미지를 직접 삽입할 수 있다. 작은 파일들은 이렇게 인라인으로 포함하는 것이 더 효율적이다. 실습을 위해 작은 이미지를 추가하자. `src` 폴더에 `icon.png` (5KB 미만)를 추가한다. ```js // app.js import './app.css'; import * as calculator from './calculator.js'; import icon from './icon.webp'; document.addEventListener('DOMContentLoaded', () => { document.body.innerHTML = `

Webpack Example

Icon `; }); console.log(calculator.multiply(5, 3)); console.log(calculator.divide(10, 2)); ``` Webpack 4에서는 `url-loader`를 사용했다. ```bash npm install -D url-loader ``` ```js // webpack.config.js (Webpack 4) module.exports = { // ... module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { test: /\.(png|jpe?g|gif)$/, loader: 'url-loader', options: { publicPath: './dist/', name: '[name].[ext]?[hash]', // 20KB 이하는 Data URL로 변환 // 그 이상은 파일로 복사 limit: 20000, }, }, ], }, }; ``` Webpack 5에서는 `type: 'asset'`을 사용하면 파일 크기에 따라 자동으로 인라인 또는 파일로 처리한다. ```js // webpack.config.js (Webpack 5) const path = require('path'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { test: /\.(png|jpe?g|gif|svg|webp)$/i, type: 'asset', // 자동으로 inline/resource 선택 parser: { dataUrlCondition: { maxSize: 20000, // 20KB 이하는 inline }, }, generator: { filename: '[name].[contenthash][ext]', }, }, ], }, }; ``` 빌드하면 다음과 같은 결과를 얻을 수 있다. ``` 📦 dist/ ┣ 📜 main.js (icon.png가 Base64로 포함됨) ┗ 📜 background.a1b2c3d4.jpg (20KB 이상이므로 파일로 복사) ``` `main.js` 내부를 확인하면 작은 이미지는 Data URL로 변환되어 있다. ```js // main.js 일부 const icon = 'data:image/png;base64,iVBORw0KGgoAAAANS...'; ``` 브라우저에서 Network 탭을 확인하면 작은 이미지는 별도의 HTTP 요청이 발생하지 않는 것을 볼 수 있다. *** ## 플러그인(Plugin) 로더가 각 파일 단위로 처리했던 것에 반해, **플러그인은 번들된 결과물 전체를 처리**한다. JavaScript 코드를 난독화한다거나 특정 텍스트를 추출하는 용도로 플러그인이 사용된다. 로더의 원리를 이해하기 위해 커스텀 로더를 만들어봤듯이, 플러그인도 직접 만들어보면서 동작 원리를 이해해보겠다. ### 커스텀 플러그인 만들기 Webpack 문서의 "Writing a Plugin"을 참고하여 플러그인을 만들어보겠다. 플러그인은 로더가 함수로 정의된 것과 다르게 **클래스로 정의**한다. `banner-add-plugin.js` 파일을 생성한다. ```js // banner-add-plugin.js (Webpack 5) class BannerAddPlugin { // apply 메서드를 구현하면 Webpack이 compiler 객체를 전달함 apply(compiler) { // emit 훅은 파일이 생성되기 직전에 실행됨 compiler.hooks.emit.tapAsync('BannerAddPlugin', (compilation, callback) => { // compilation 객체를 통해 번들된 결과물에 접근 가능 if (compilation.assets['main.js']) { // 기존 소스 코드 가져오기 const source = compilation.assets['main.js'].source(); // 파일 상단에 추가할 배너 const banner = [ '/**', ' * 이것은 BannerAddPlugin이 처리한 결과입니다.', ' * Build Date: ' + new Date().toLocaleDateString(), ' */', ].join('\n'); const newContent = banner + '\n\n' + source; // 기존 파일을 새 내용으로 교체 compilation.assets['main.js'] = { source: () => newContent, size: () => newContent.length, }; } // 비동기 작업 완료를 Webpack에 알림 callback(); }); } } module.exports = BannerAddPlugin; ``` Webpack 4 이하에서는 `compiler.plugin()` 메서드를 사용했지만, Webpack 4 이상에서는 **Tapable Hooks API**로 변경되었다. ```js // Webpack 3 이하 (더 이상 사용하지 않음) compiler.plugin('emit', (compilation, callback) => { // ... }); // Webpack 4 이상 (권장) compiler.hooks.emit.tapAsync('PluginName', (compilation, callback) => { // ... }); ``` 만든 플러그인을 Webpack 설정에 추가한다. ```js // webpack.config.js const path = require('path'); const BannerAddPlugin = require('./banner-add-plugin'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { test: /\.(png|jpe?g|gif|svg|webp)$/i, type: 'asset', parser: { dataUrlCondition: { maxSize: 20000, }, }, generator: { filename: '[name].[contenthash][ext]', }, }, ], }, // 플러그인 배열에 인스턴스 추가 plugins: [new BannerAddPlugin()], }; ``` 빌드하고 `dist/main.js` 파일을 열어보면 상단에 배너가 추가된 것을 확인할 수 있다. ```js /** * 이것은 BannerAddPlugin이 처리한 결과입니다. * Build Date: 2025/10/11 */ /******/ (() => { // webpackBootstrap ... ``` 로더가 여러 파일 각각에 대해 실행되는 것과 달리, 플러그인은 번들된 결과물에 대해 한 번만 실행되는 것을 확인할 수 있다. *** ### 주요 플러그인 사용법 커스텀으로 만들었던 플러그인과 유사한 것이 실제로 존재한다. 대표적인 플러그인들을 살펴보겠다. **BannerPlugin** 빌드한 결과물에 빌드 정보나 커밋 버전 같은 것을 추가할 수 있는 플러그인입니다. `BannerPlugin`은 Webpack이 기본으로 제공하는 내장 플러그인입니다. ```js // webpack.config.js const path = require('path'); const webpack = require('webpack'); module.exports = { mode: 'development', entry: { main: './src/app.js', }, output: { filename: '[name].js', path: path.resolve('./dist'), }, module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, { test: /\.(png|jpe?g|gif|svg|webp)$/i, type: 'asset', parser: { dataUrlCondition: { maxSize: 20000, }, }, generator: { filename: '[name].[contenthash][ext]', }, }, ], }, plugins: [ new webpack.BannerPlugin({ banner: '이것은 BannerPlugin이 처리한 결과입니다.', }), ], }; ``` 빌드하고 `dist/main.js`를 확인하면 상단에 배너가 추가된 것을 볼 수 있다. ```js /*! 이것은 BannerPlugin이 처리한 결과입니다. */ /******/ (() => { // webpackBootstrap ... ``` 배너에 더 자세한 정보를 추가해보겠다. ```js // webpack.config.js const childProcess = require('child_process'); plugins: [ new webpack.BannerPlugin({ banner: ` Build Date: ${new Date().toLocaleDateString()} Commit Version: ${childProcess.execSync('git rev-parse --short HEAD').toString().trim()} Author: ${childProcess.execSync('git config user.name').toString().trim()} `, }), ], ``` Node의 `child_process` 모듈을 사용하여 터미널 명령어를 실행할 수 있다. * `git rev-parse --short HEAD`: 현재 커밋의 짧은 해시값 * `git config user.name`: Git 사용자 이름 빌드하면 다음과 같은 배너가 생성된다. ```js /*! Build Date: 2025/10/11 Commit Version: a1b2c3d Author: John Doe */ ``` 빌드된 결과물에 이런 배너 정보를 추가하는 이유는, 배포 후 실제 정적 파일이 제대로 배포되었는지, 또는 캐시로 인해 갱신되지 않았는지 확인할 때 유용하기 때문입니다. *** **DefinePlugin** 프론트엔드 소스 코드는 개발 환경과 운영 환경으로 나눠서 운영한다. 환경에 따라 API 주소가 다를 수 있다. 배포할 때마다 코드를 수정하면 휴먼 에러가 발생하기 쉽고 장애가 날 위험이 있다. API 주소처럼 환경 의존적인 정보를 소스가 아닌 다른 곳에서 관리하는 것이 좋다. 이런 환경 변수를 애플리케이션에 제공하기 위해 `DefinePlugin`을 사용한다. `DefinePlugin`도 Webpack의 기본 내장 플러그인입니다. ```js // webpack.config.js plugins: [new webpack.DefinePlugin({})]; ``` 이렇게 빈 객체로 설정해도 `DefinePlugin`이 기본적으로 주입하는 환경 변수가 있다. 바로 Node의 환경 변수인 `process.env.NODE_ENV`입니다. Webpack이 Node 환경에서 실행되기 때문에, 빌드될 때 이 `NODE_ENV` 환경 변수를 번들에 포함시킵니다. ```js // app.js import './app.css'; import * as calculator from './calculator.js'; console.log(calculator.multiply(5, 3)); console.log(calculator.divide(10, 2)); console.log('Environment:', process.env.NODE_ENV); ``` 빌드하고 실행하면 다음과 같이 출력된다. ``` 콘솔 출력: 15 5 Environment: development ``` `development`가 출력되는 이유는 `webpack.config.js`에서 `mode: 'development'`로 설정했기 때문입니다. 직접 환경 변수를 추가할 수도 있다. ```js // webpack.config.js plugins: [ new webpack.DefinePlugin({ TWO: '1+1', }), ], ``` 애플리케이션에서는 `TWO`라는 전역 변수로 접근할 수 있다. ```js console.log(TWO); // 2 ``` `'1+1'`은 문자열이 아니라 JavaScript 코드로 평가되어 `2`가 된다. 만약 문자열 값을 넣고 싶다면 `JSON.stringify()`를 사용한다. ```js plugins: [ new webpack.DefinePlugin({ TWO: JSON.stringify('1+1'), 'api.domain': JSON.stringify('http://dev.api.domain.com'), }), ], ``` ```js console.log(TWO); // "1+1" (문자열) console.log(api.domain); // "http://dev.api.domain.com" ``` 객체 형식으로 정의하면 `api.domain`처럼 점 표기법으로 접근할 수 있다. *** **HtmlWebpackPlugin** `HtmlWebpackPlugin`은 Webpack의 기본 플러그인은 아니지만, 널리 사용되는 서드파티 플러그인입니다. HTML 파일을 빌드 과정에 포함시켜 처리한다. 지금까지는 HTML 파일을 프로젝트 루트에 직접 만들고, 빌드한 결과물의 경로를 수동으로 입력했다. ```html Document ``` HTML도 빌드 과정에 포함시키고 싶다면 이 플러그인을 사용한다. 먼저 패키지를 설치한다. ```bash npm install -D html-webpack-plugin ``` `index.html`을 `src/index.html`로 이동하고, JavaScript 로딩 코드는 제거한다. ```html Document ``` Webpack 설정에 플러그인을 추가한다. ```js // webpack.config.js const HtmlWebpackPlugin = require('html-webpack-plugin'); plugins: [ new HtmlWebpackPlugin({ template: './src/index.html', }), ], ``` 빌드하면 `dist` 폴더에 `index.html`이 생성된다. ``` 📦 dist/ ┣ 📜 main.js ┗ 📜 index.html ``` 생성된 `index.html`을 확인하면 스크립트 태그가 자동으로 추가되어 있다. Webpack 4에서는 `` 태그 하단에 ` ``` 이제 `http://127.0.0.1:5500/dist/index.html`로 접속하면 된다. `HtmlWebpackPlugin`을 사용하면 동적으로 HTML을 생성할 수 있다. EJS 템플릿 문법을 사용하여 환경에 따라 다른 값을 넣을 수 있다. ```html Document <%= env %> ``` Webpack 설정에서 `templateParameters`로 값을 전달한다. ```js // webpack.config.js plugins: [ new HtmlWebpackPlugin({ template: './src/index.html', templateParameters: { env: process.env.NODE_ENV === 'development' ? '(개발)' : '(운영)', }, }), ], ``` 환경 변수를 설정하여 빌드한다. ```bash NODE_ENV=development npm run build # 개발 환경 NODE_ENV=production npm run build # 운영 환경 ``` 개발 환경에서는 `Document (개발)`, 운영 환경에서는 `Document (운영)`로 생성된다. 개발 환경에서 타이틀에 "(개발)" 표시를 하면 휴먼 에러를 줄일 수 있다. 운영 환경에서는 HTML을 압축하고 주석을 제거하는 것이 좋다. ```js // webpack.config.js plugins: [ new HtmlWebpackPlugin({ template: './src/index.html', templateParameters: { env: process.env.NODE_ENV === 'development' ? '(개발)' : '(운영)', }, minify: process.env.NODE_ENV === 'production' ? { collapseWhitespace: true, // 빈칸 제거 removeComments: true, // 주석 제거 } : false, }), ], ``` 운영 환경에서 빌드하면 HTML이 한 줄로 압축된다. ```html Document (운영) ``` *** **CleanWebpackPlugin** `CleanWebpackPlugin`은 output 폴더를 자동으로 삭제해주는 플러그인입니다. 지금까지는 필요할 때마다 `dist` 폴더를 수동으로 삭제했는데, 이 플러그인을 추가하면 빌드할 때마다 `dist` 폴더를 자동으로 정리하고 새로운 파일을 생성한다. ```bash npm install -D clean-webpack-plugin ``` ```js // webpack.config.js const { CleanWebpackPlugin } = require('clean-webpack-plugin'); plugins: [ new CleanWebpackPlugin(), // ... 다른 플러그인들 ], ``` 주의할 점은 `default export`가 아니라 `named export`이므로 중괄호로 import해야 한다. 빌드하면 기존 `dist` 폴더가 삭제되고 새로운 빌드 결과물이 생성된다. *** **MiniCssExtractPlugin** 스타일시트가 많아지면 JavaScript 파일 하나에 모두 포함시키는 것이 부담스러울 수 있다. 브라우저에서 큰 파일 하나를 로드하는 것보다 여러 작은 파일을 동시에 로드하는 것이 성능에 유리한다. 번들 결과에서 스타일시트 코드만 따로 뽑아서 CSS 파일을 별도로 만들어 역할에 따라 파일을 분리하는 것이 좋다. 최종 결과물이 JavaScript 하나, CSS 파일 하나로 분리되면 각각의 용량이 줄어들고, 브라우저가 병렬로 다운로드할 수 있어 페이지 로딩 성능이 향상된다. 이 플러그인도 서드파티 패키지이므로 설치가 필요한다. ```bash npm install -D mini-css-extract-plugin ``` ```js // webpack.config.js const MiniCssExtractPlugin = require('mini-css-extract-plugin'); module.exports = { // ... module: { rules: [ { test: /\.css$/, use: [ // 운영 환경에서는 MiniCssExtractPlugin.loader 사용 // 개발 환경에서는 style-loader 사용 process.env.NODE_ENV === 'production' ? MiniCssExtractPlugin.loader : 'style-loader', 'css-loader', ], }, // ... 다른 rules ], }, plugins: [ // 운영 환경에서만 플러그인 활성화 ...(process.env.NODE_ENV === 'production' ? [ new MiniCssExtractPlugin({ filename: '[name].[contenthash].css', }), ] : []), // ... 다른 플러그인들 ], }; ``` 이 플러그인은 로더와 플러그인 설정을 모두 추가해야 한다. * 로더 설정: `style-loader` 대신 `MiniCssExtractPlugin.loader` 사용 * 플러그인 설정: CSS 파일명 지정 개발 환경에서는 빠른 빌드를 위해 JavaScript 파일 하나로 처리하고, 운영 환경에서만 CSS를 분리하는 것이 일반적입니다. 운영 환경으로 빌드하면: ``` 📦 dist/ ┣ 📜 main.js ┣ 📜 main.a1b2c3d4.css ┗ 📜 index.html ``` `index.html`을 확인하면 CSS도 자동으로 로드된다. ```html Document (운영) ``` *** ## 개발 환경 구성 지금까지 실습한 환경에서는 HTML, JavaScript, CSS, 이미지 파일들을 직접 브라우저에 올려서 결과를 확인했다. 실제 웹 서비스가 제공되려면 인터넷 어딘가에 게시되어야 한다. 인터넷에 연결된 컴퓨터에서 서버 프로그램이 정적 파일을 제공하는 형식이어야 한다. 개발 환경에서도 이와 유사한 환경을 갖추는 것이 좋다. 운영 환경과 동일하게 맞춤으로써 운영 환경에 배포했을 때 발생할 수 있는 문제를 개발 단계에서 미리 확인할 수 있다. 또한 AJAX 방식의 API 연동을 하게 되면 `CORS(Cross-Origin Resource Sharing)` 브라우저 보안 정책 때문에 개발 환경에서 API를 사용하는 것이 불가능할 수 있다. 이런 이유로 개발 환경에서도 서버가 반드시 필요한다. Webpack은 이런 개발 서버를 제공하는 `webpack-dev-server`를 제공한다. ### webpack-dev-server 설정 ```bash npm install -D webpack-dev-server ``` `package.json`에 스크립트를 추가한다. ```json { "scripts": { "build": "webpack", "start": "webpack-dev-server" } } ``` 개발 서버를 실행한다. ```bash npm start ``` 서버가 실행되면 다음과 같은 메시지가 출력된다. ``` [webpack-dev-server] Project is running at: [webpack-dev-server] Loopback: http://localhost:8080/ [webpack-dev-server] On Your Network (IPv4): http://192.168.0.10:8080/ [webpack-dev-server] Content not from webpack is served from 'public' directory ``` 이제 `http://localhost:8080`에 접속하여 결과물을 확인할 수 있다. Webpack 개발 서버는 파일 변화를 감지하여 자동으로 브라우저를 새로고침해주는 기능도 제공한다. 예를 들어 `app.css`를 수정하면: ```css /* app.css */ body { background-color: #e0f7fa; /* 색상 변경 */ } ``` 저장하면 Webpack 개발 서버가 변경을 감지하고 자동으로 브라우저에 반영한다. 브라우저를 수동으로 새로고침할 필요가 없다. 이렇게 Webpack 개발 서버를 사용하면 개발 서버를 제공할 뿐만 아니라, 코드 변화를 감지해서 결과물을 실시간으로 브라우저에 보여주는 매우 편리한 기능을 제공한다. **devServer 상세 설정** Webpack 개발 서버의 설정을 살펴보겠다. ```js // webpack.config.js (Webpack 4) const path = require('path'); module.exports = { // ... devServer: { // 정적 파일을 제공할 경로 (기본값: output 경로) contentBase: path.join(__dirname, 'dist'), // 브라우저를 통해 접근하는 경로 publicPath: '/', // 개발 환경 도메인 설정 // 쿠키 기반 인증은 인증 서버와 동일한 도메인이어야 함 host: 'dev.domain.com', // 빌드 시 에러나 경고를 브라우저 화면에 표시 overlay: true, // 개발 서버 포트 port: 8081, // 메시지 수준 설정 stats: 'errors-only', // 'none', 'errors-only', 'minimal', 'normal', 'verbose' // History API를 사용하는 SPA 개발 시 설정 // 404 발생 시 index.html로 리다이렉트 historyApiFallback: true, }, }; ``` Webpack 5에서는 일부 옵션이 변경되었다. ```js // webpack.config.js (Webpack 5) const path = require('path'); module.exports = { // ... devServer: { // 정적 파일 제공 경로 static: { directory: path.join(__dirname, 'dist'), publicPath: '/', }, // 개발 도메인 설정 host: 'dev.domain.com', // 개발 포트 port: 8081, // SPA의 History API 지원 historyApiFallback: true, // 브라우저 오버레이 설정 client: { overlay: { errors: true, warnings: false, }, logging: 'error', }, // HMR 활성화 (기본값 true) hot: true, // 터미널 메시지 레벨 조정 infrastructureLogging: { level: 'error', }, // 서버 구동 시 자동으로 브라우저 열기 open: true, }, }; ``` *** ### API 서버 연동 및 CORS 해결 API 없이 개발하게 되면 프론트엔드 개발할 때 난감할 때가 있다. 목업(Mock) 데이터를 제공하는 목업 API를 만들어서 화면을 개발하면 더 수월한다. Webpack 개발 서버는 목업 API를 제공하는 기능도 있다. ```js // webpack.config.js (Webpack 4) module.exports = { devServer: { overlay: true, stats: 'errors-only', // before 함수로 Express 앱에 접근 before: (app) => { // app은 Express 서버 인스턴스 app.get('/api/users', (req, res) => { res.json([ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }, ]); }); }, }, }; ``` Webpack 5부터는 `setupMiddlewares`를 사용한다. ```js // webpack.config.js (Webpack 5) module.exports = { devServer: { client: { overlay: true, logging: 'error', }, setupMiddlewares: (middlewares, devServer) => { if (!devServer) { throw new Error('webpack-dev-server is not defined'); } // Express 인스턴스 접근 const app = devServer.app; // 목업 API 엔드포인트 등록 app.get('/api/users', (req, res) => { res.json([ { id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }, { id: 3, name: 'Charlie' }, ]); }); // middlewares 반환 필수 return middlewares; }, }, }; ``` `app.get`, `app.post`, `app.use` 등 Express의 모든 메서드를 사용할 수 있다. 이제 Webpack 개발 서버로 API 요청을 날려보겠다. ```bash npm install axios ``` ```js // app.js import axios from 'axios'; import './app.css'; import * as calculator from './calculator.js'; document.addEventListener('DOMContentLoaded', async () => { try { const res = await axios.get('/api/users'); console.log('API 응답:', res.data); } catch (error) { console.error('API 오류:', error); } console.log(calculator.multiply(5, 3)); console.log(calculator.divide(10, 2)); }); ``` 개발 서버를 실행하고 브라우저 콘솔을 확인하면: ``` 콘솔 출력: API 응답: [{id: 1, name: "Alice"}, {id: 2, name: "Bob"}, {id: 3, name: "Charlie"}] 15 5 ``` 데이터를 성공적으로 받아온 것을 확인할 수 있다. 실제 프로젝트에서는 `connect-api-mocker` 같은 전용 패키지를 사용하는 것이 더 편리한다. API 응답값을 JSON 파일로 만들어 놓고 개발 서버에 연동시킬 수 있다. ```bash npm install -D connect-api-mocker ``` 프로젝트에 `mocks/api/users/GET.json` 파일을 생성한다. ``` mocks/ └─ api/ └─ users/ └─ GET.json ``` ```json [ { "id": 1, "name": "Alice" }, { "id": 2, "name": "Bob" }, { "id": 3, "name": "Charlie" } ] ``` Webpack 5 설정: ```js // webpack.config.js (Webpack 5) const ConnectApiMocker = require('connect-api-mocker'); module.exports = { devServer: { setupMiddlewares: (middlewares, devServer) => { if (!devServer) { throw new Error('webpack-dev-server is not defined'); } // /api 요청을 mocks/api 폴더의 파일로 매핑 devServer.app.use(ConnectApiMocker('/api', 'mocks/api')); return middlewares; }, }, }; ``` 이제 `/api/users` 요청은 자동으로 `mocks/api/users/GET.json` 파일을 반환한다. **CORS 문제 해결하기** 실제 API 서버가 만들어졌다고 가정해보겠다. 현재 Webpack 개발 서버는 `http://localhost:8080`에서 실행되고 있고, API 서버가 `http://localhost:8081`에 있다면 어떻게 될까요? 이 경우 Ajax 요청을 하면 `CORS` 에러가 발생한다. 브라우저의 `동일 출처 정책(Same-Origin Policy)` 때문입니다. 서버에서 `Access-Control-Allow-Origin` 헤더를 추가하는 방법이 있다. ```js // server/index.js app.get('/api/keywords', (req, res) => { res.header('Access-Control-Allow-Origin', '*'); // 모든 도메인 허용 res.json(keywords); }); ``` 서버 응답 헤더를 수정할 필요 없이, Webpack 개발 서버에서 API 서버로 프록시하는 방법도 있다. 이 방법이 개발 환경에서 더 편리한다. ```js // webpack.config.js module.exports = { devServer: { proxy: { '/api': 'http://localhost:8081', }, }, }; ``` 이 설정은 개발 서버에 들어온 모든 HTTP 요청 중 `/api`로 시작하는 요청을 `http://localhost:8081`로 프록시한다. 클라이언트 코드에서는 상대 경로만 사용하면 된다. ```js // API 호출 코드 import axios from 'axios'; // 전체 URL 대신 상대 경로 사용 const { data } = await axios.get('/api/keywords'); ``` 이렇게 설정하면 CORS 에러 없이 정상적으로 API를 호출할 수 있다. > **참고**: Next.js에서는 `rewrites` 속성으로, Webpack에서는 `proxy` 속성으로 동일한 기능을 제공한다. **Hot Module Replacement (HMR)** `Hot Module Replacement(HMR)`는 애플리케이션이 실행되는 동안 변경된 모듈만 교체하는 기능입니다. 예를 들어 폼 데이터에 무언가 입력한 상태에서 관련 없는 다른 모듈을 수정했을 때, 폼에 입력한 데이터가 날아가지 않도록 해줍니다. Webpack 5에서는 `hot` 옵션이 기본적으로 `true`로 설정되어 있다. ```js // webpack.config.js (Webpack 5) module.exports = { devServer: { hot: true, // 기본값이 true이므로 생략 가능 }, }; ``` HMR을 제대로 사용하려면 모듈이 HMR 인터페이스를 구현해야 한다. ```js // app.js if (module.hot) { console.log('HMR이 활성화되었다'); // calculator 모듈 변경 감지 module.hot.accept('./calculator', () => { console.log('calculator 모듈이 변경되었다'); // 모듈 다시 로드 }); } ``` 이렇게 HMR을 사용하면 코드가 변경될 때 전체 화면을 새로고침하지 않고 변경된 모듈만 교체된다. 개발 속도를 크게 향상시킬 수 있다. 많이 사용되는 로더들은 HMR을 기본적으로 지원한다. 대표적인 예로 `style-loader`가 있다. CSS 파일을 수정하면 페이지 새로고침 없이 스타일만 즉시 반영된다. `style-loader` 내부적으로는 다음과 같은 HMR 코드가 구현되어 있다. ```js // style-loader 내부 구현 예시 if (module.hot) { module.hot.accept(); module.hot.dispose(() => { // 스타일 업데이트 로직 }); } ``` *** ## 최적화 Webpack에서 번들 결과물을 최적화하는 방법을 알아보겠다. 코드가 많아지면 번들된 결과물인 JavaScript 파일이 메가바이트 단위까지 커질 수 있다. 브라우저에서 큰 파일을 다운로드하는 것은 성능에 큰 영향을 줍니다. Webpack으로 번들 결과를 압축하고, 상황에 따라 작은 파일 여러 개로 분리하는 방법을 살펴보겠다. *** ### 번들 크기 최적화 **mode 설정** 가장 간단한 방법은 `mode` 값을 설정하는 것입니다. ```js // webpack.config.js module.exports = { mode: 'production', // 운영 환경에서는 production 사용 }; ``` 개발 환경에서는 디버깅 편의를 위해 다음 플러그인들을 사용한다. * `NamedChunksPlugin` * `NamedModulesPlugin` 또한 `DefinePlugin`을 통해 `process.env.NODE_ENV` 값이 `"development"`로 설정되어 애플리케이션 전역 변수로 주입된다. `mode`를 `"production"`으로 설정하면 JavaScript 결과물을 최소화하기 위해 다음 플러그인들을 자동으로 사용한다. * `FlagDependencyUsagePlugin` * `FlagIncludedChunksPlugin` * `ModuleConcatenationPlugin` * `NoEmitOnErrorsPlugin` * `OccurrenceOrderPlugin` * `SideEffectsFlagPlugin` * `TerserPlugin` `process.env.NODE_ENV` 값이 `"production"`으로 설정된다. 환경 변수 `NODE_ENV` 값에 따라 자동으로 모드를 설정하도록 구성할 수 있다. ```js // webpack.config.js const mode = process.env.NODE_ENV || 'development'; module.exports = { mode, }; ``` `package.json`의 스크립트를 다음과 같이 설정한다. ```json { "scripts": { "build": "NODE_ENV=production webpack --progress", "start": "webpack-dev-server --progress" } } ``` 이제 `npm run build`를 실행하면 production 모드로 빌드된다. 빌드된 파일을 확인하면 코드가 난독화되고 압축된 것을 볼 수 있다. *** **optimization 속성** `optimization` 속성을 사용하면 빌드 과정을 더욱 세밀하게 커스터마이징할 수 있다. `HtmlWebpackPlugin`이 HTML 파일을 압축하는 것처럼, CSS 파일도 공백을 제거하여 압축할 수 있다. 먼저 플러그인을 설치한다. ```bash npm install -D css-minimizer-webpack-plugin ``` Webpack 설정에 플러그인을 추가한다. ```js // webpack.config.js const CssMinimizerPlugin = require('css-minimizer-webpack-plugin'); const mode = process.env.NODE_ENV || 'development'; module.exports = { mode, // ... optimization: { minimizer: mode === 'production' ? [new CssMinimizerPlugin()] : [], }, }; ``` `optimization.minimizer`는 Webpack이 결과물을 압축할 때 사용할 플러그인 배열입니다. 위 설정을 통해 빌드 결과물 중 CSS 파일이 압축된다. `mode=production`일 때 자동으로 사용되는 `TerserWebpackPlugin`은 JavaScript 코드를 난독화하고 `debugger` 구문을 제거한다. 기본 설정 외에도 콘솔 로그를 제거하는 옵션을 추가할 수 있다. 배포 버전에서는 보안을 위해 콘솔 로그를 제거하는 것이 좋다. 먼저 플러그인을 설치한다. ```bash npm install -D terser-webpack-plugin ``` `optimization.minimizer` 배열에 플러그인을 추가한다. ```js // webpack.config.js const TerserPlugin = require('terser-webpack-plugin'); module.exports = { optimization: { minimizer: mode === 'production' ? [ new TerserPlugin({ terserOptions: { compress: { drop_console: true, // 콘솔 로그 제거 }, }, }), new CssMinimizerPlugin(), ] : [], }, }; ``` > **참고**: 개발 환경에서는 디버깅을 위해 콘솔 로그가 필요하지만, 운영 환경에서는 민감한 정보 노출을 방지하기 위해 제거하는 것이 좋다. *** ### 코드 스플리팅 (Code Splitting) 코드를 압축하는 것 외에도, 결과물을 여러 개로 분리하면 브라우저 다운로드 속도를 높일 수 있다. 큰 파일 하나를 다운로드하는 것보다 작은 파일 여러 개를 동시에 다운로드하는 것이 더 빠르기 때문입니다. 가장 단순한 방법은 엔트리를 여러 개로 분리하는 것입니다. ```js // webpack.config.js module.exports = { entry: { main: './src/app.js', sub: './src/sub.js', }, }; ``` 빌드하면 `dist` 폴더에 `main.js`와 `sub.js` 두 개의 파일이 생성된다. `HtmlWebpackPlugin`이 HTML 파일에 두 스크립트를 자동으로 포함시킵니다. 그런데 `main.js`와 `sub.js` 모두 `axios` 라이브러리를 사용한다면, 같은 코드가 두 파일에 중복으로 포함된다. 이럴 때 `splitChunks`를 사용하면 중복 코드를 별도 파일로 분리할 수 있다. ```js // webpack.config.js module.exports = { optimization: { splitChunks: { chunks: 'all', }, }, }; ``` 빌드하면 다음과 같은 파일들이 생성된다. ``` 📦 dist/ ┣ 📜 main.js # main 엔트리 고유 코드 ┣ 📜 sub.js # sub 엔트리 고유 코드 ┗ 📜 vendors-main-sub.js # 공통으로 사용하는 코드 (axios 등) ``` 전체 용량이 줄어든 것을 확인할 수 있다. ```bash ls -lh dist ``` 엔트리 포인트를 수동으로 분리하는 것은 관리가 어렵다. Dynamic Import를 사용하면 Webpack이 자동으로 코드를 분리해줍니다. 기존의 정적 import 대신 동적 import를 사용한다. **변경 전** (정적 import): ```js import calculator from './calculator'; ``` **변경 후** (동적 import): ```js document.addEventListener('DOMContentLoaded', async () => { // 동적으로 모듈 불러오기 const module = await import( /* webpackChunkName: "calculator" */ './calculator.js' ); const calculator = module.default || module; console.log(calculator.multiply(5, 3)); console.log(calculator.divide(10, 2)); }); ``` `/* webpackChunkName: "calculator" */` 주석은 Webpack이 생성할 청크 파일의 이름을 지정하는 매직 코멘트입니다. 이를 통해 생성되는 파일명을 제어할 수 있다. Dynamic Import를 사용하면 멀티 엔트리 포인트 설정을 제거할 수 있다. ```js // webpack.config.js module.exports = { entry: { main: './src/app.js', // calculator 엔트리는 더 이상 필요하지 않음 }, // splitChunks 설정도 제거 가능 }; ``` 빌드하면 다음과 같은 파일들이 생성된다. ``` 📦 dist/ ┣ 📜 main.js # 메인 번들 ┣ 📜 calculator.js # Dynamic Import로 분리된 청크 ┗ 📜 vendors-calculator.js # calculator에서 사용하는 외부 라이브러리 ``` Dynamic Import를 사용하면 엔트리 포인트를 수동으로 관리하지 않아도 Webpack이 자동으로 코드를 분리해줍니다. *** **externals로 번들 최적화** 번들 크기를 줄이는 마지막 방법은 애초에 번들에 포함하지 말아야 할 라이브러리를 빌드 범위에서 제외하는 것입니다. `axios`와 같은 외부 라이브러리는 npm에서 다운로드한 이미 빌드된 파일입니다. 이런 라이브러리를 Webpack으로 다시 빌드할 필요가 없다. `externals` 설정을 사용하면 특정 라이브러리를 번들에서 제외하고 전역 변수로 사용하도록 설정할 수 있다. ```js // webpack.config.js module.exports = { externals: { axios: 'axios', // axios 모듈을 전역 변수 axios로 대체 }, }; ``` 이제 Webpack은 코드에서 `axios`를 발견해도 번들에 포함시키지 않고, 전역 변수 `axios`를 사용하도록 빌드한다. `externals`로 제외한 라이브러리는 직접 HTML에서 로드해야 하므로, 빌드된 파일을 `dist` 폴더로 복사해야 한다. `copy-webpack-plugin`을 설치한다. ```bash npm install -D copy-webpack-plugin ``` ```js // webpack.config.js (Webpack 5) const CopyPlugin = require('copy-webpack-plugin'); module.exports = { externals: { axios: 'axios', }, plugins: [ new CopyPlugin({ patterns: [ { from: './node_modules/axios/dist/axios.min.js', to: './axios.min.js', }, ], }), ], }; ``` `src/index.html`에 axios를 로드하는 스크립트 태그를 추가한다. ```html Document ``` 빌드하면 `dist` 폴더에 `axios.min.js`가 복사되고, `index.html`에서 이를 로드하는 것을 확인할 수 있다. ```bash npm run build ls dist # axios.min.js 파일 확인 ``` externals의 장점은 다음과 같다. * **번들 크기 감소**: 이미 빌드된 라이브러리를 제외하여 번들 크기가 줄어듭니다. * **빌드 속도 향상**: 외부 라이브러리를 빌드하지 않아 빌드 시간이 단축된다. * **개발/운영 환경 모두 개선**: 개발 서버 시작 시간과 운영 빌드 시간 모두 단축된다. 이처럼 이미 빌드된 외부 라이브러리는 `externals`로 빼서 관리하는 것이 효율적입니다. *** ### 핵심 정리 **Webpack 학습 핵심 포인트** 1. **모듈 시스템의 필요성**: 전역 스코프 오염을 방지하고 코드를 체계적으로 관리하기 위해 모듈 시스템이 필요한다. 2. `Webpack의 역할`: 여러 모듈을 하나의 번들 파일로 합쳐주는 번들러다. 모든 파일(JS, CSS, 이미지)을 모듈로 처리한다. 3. `로더`: 각 파일을 JavaScript 모듈로 변환한다. (`css-loader`, `style-loader`, Asset Modules 등) 4. `플러그인`: 번들된 결과물 전체를 후처리한다. (BannerPlugin, DefinePlugin, HtmlWebpackPlugin 등) 5. `개발 서버`: `webpack-dev-server`로 개발 환경을 운영 환경과 유사하게 구성하고 HMR로 개발 속도를 향상시킬 수 있다. 6. `최적화`: * `mode` 설정으로 자동 최적화 * CSS/JS 압축 * 코드 스플리팅으로 파일 분리 * `externals`로 외부 라이브러리 제외 7. `Webpack 4 vs 5`: Output 옵션, Asset Modules, devServer 설정 등에서 차이가 있으므로 버전에 맞는 설정을 사용해야 한다. *** ### 마치며: 현대 번들러 생태계 이제 Webpack의 핵심 개념과 활용 방법을 모두 살펴보았다. 하지만 말씀드리고 싶은 부분이 있다. 요즘은 Webpack뿐만 아니라 다양한 번들러가 등장했고 프로젝트마다 사용하는 도구가 달라지고 있다. `Vite`가 최근에는 거의 표준처럼 자리잡았다고 볼 수 있다. 대부분의 신규 프로젝트에서 Vite를 사용하고 있는데 개발 서버 속도가 매우 빠르고 개발 환경에서는 `esbuild`를, 프로덕션 빌드에서는 `Rollup`을 사용해 안정성도 유지하는 구조 덕분이라고 생각한다. `Rollup`은 UI 컴포넌트 라이브러리를 제작할 때 가장 많이 사용된다. 디자인 시스템이나 내부 공용 컴포넌트를 개발할 때 Rollup의 깔끔한 번들링과 Tree-shaking이 큰 장점으로 작용한다. `Webpack`은 오래된 프로젝트에서 여전히 많이 사용되고 있다. 다양한 플러그인 생태계의 이점도 있고 수년간 유지해온 설정을 쉽게 바꿀 수 없다는 현실적인 이유도 있다. 이 글의 내용이 최신 트렌드와 다소 차이가 있는 것은 사실이다. 하지만 `"번들러의 동작 원리"를 이해하는 것`이 가장 중요하다. Webpack을 통해 로더와 플러그인의 개념, 모듈 시스템의 필요성, 최적화 방법을 익히면 이 지식을 Vite, Rollup, esbuild 등 최신 도구에도 그대로 적용할 수 있다. 도구는 계속 변하지만 번들러가 해결하려는 근본적인 문제는 동일하다. 이러한 원리를 이해하고 직접 최신 도구에 적용하는 과정에서 크게 성장할 수 있다고 생각한다. 이것이 바로 실무 감각을 키우는 방법이기도 하다. 실제 프로젝트에서 번들러를 선택하고 설정할 때 이 글에서 배운 개념들을 토대로 각 도구의 특성을 비교하고 활용해보시기 바란다. --- # Component 직접 만들며 생각해보기 > 필자는 2023년 멋쟁이 사자처럼 11기, UMC 4기를 계기로 웹 개발을 본격적으로 시작했다. 당시 커리큘럼은 React 없이 HTML, CSS, JavaScript만으로 서비스를 구축하는 방식이었다. 머리가 커서 그랬을까, 커리큘럼에 대한 불만이 많았다. 당시에 JS 강의를 마... - 원문: https://www.yolog.co.kr/post/component - 카테고리: 개발 - 발행: 2025-10-08 - 수정: 2025-10-08 필자는 2023년 멋쟁이 사자처럼 11기, UMC 4기를 계기로 웹 개발을 본격적으로 시작했다. 당시 커리큘럼은 React 없이 HTML, CSS, JavaScript만으로 서비스를 구축하는 방식이었다. 머리가 커서 그랬을까, 커리큘럼에 대한 불만이 많았다. 당시에 JS 강의를 마치고 React 강의를 듣던 시기라, 순수 JS로만 개발하는 과정이 비효율적으로 느껴져 답답했다. 물론, JS만으로 개발하는 게 불만족스럽기보다는, 내가 배운 JS로 React를 어떤 식으로 만드는지 항상 궁금함이 있었는데 이를 해소하지 못해서 그런 것 같다. *** 이제는 상황이 조금 달라졌다. 오히려, 약 2년간 1,000명의 챌린저 분들을 내가 알려주는 입장이고 조금 더 잘 알려줄 수 있는 방향성에 대해 항상 고민하고 있다. 또 회사를 다니며 다른 사람들의 코드를 보고 다른 회사들의 테크 블로그에 더 관심을 가지면서 내가 공부하는 방향성도 최근에 많이 달라졌다. 매 기수마다 워크북을 개선하고자 노력하며 커리큘럼을 어떤 방향성에 맞춰야 할지 고민이 많다. 필자가 고민하는 두 가지 중점은 다음과 같다. 1. 웹 개발의 원론적인 이해 2. 실제 서비스를 직접 만들어보면서 흥미를 우선적으로 얻기 필자는 2번을 중요하게 생각한다. 어떠한 일이든 잘하기 위해서는 흥미를 가져야 한다고 생각한다. 눈에 보이는 결과물이 생기면 자연스럽게 동기와 학습 의욕이 붙는다. 반면, 기초만 깊게 파다가 실전에서 주도적 역할을 못하면 흥미가 떨어지고, 결국 AI에 의존(AI-Driven Development)하거나 개발을 포기하기도 한다. 물론, 1번 과정 역시나 중요하다. 단, 순서의 차이라고 생각한다. 흥미를 기반으로 성장한 학습자는 결국 이론의 필요성을 절감하게 된다. 원리는 결코 무시할 수 없으며, 단지 학습의 순서와 접근 방식이 다를 뿐이다. 최근에 더더욱 1번의 중요성을 많이 느끼면서 이번 커리큘럼에서도 강의 영상뿐만 아니라 나 또한 함께 학습하며 키워드 부분에 최대한 개념적인 설명에 초점을 맞추고 있다. 그리고 내가 강의를 듣거나 다양한 블로그나 자료들을 찾아보면서 학습한 내용을 바탕으로 블로그 글을 작성하며 공유하고자 노력하고 있다. 서론이 길었다. 이번에는 우리가 너무 당연하게 사용하는 React의 컴포넌트 개념을 직접 구현하며, 그 원리를 근본부터 이해하고자 한다. *** ## 1. 왜 컴포넌트 기반 개발인가? ### 1.1 jQuery 시대의 개발 필자가 처음 개발을 배울 당시, 조금 비싼 가격이었지만 Vanilla JavaScript 강의로 시작했다. > 개발의 시작이 중요하다고 생각하는데, 정말 좋은 강의였다. 요즘은 `useRef`, `useEffect` 같은 React Hooks를 먼저 배우는 경우가 많은 것 같다. 하지만 필자는 `document.querySelector`, `document.getElementById`, `document.getElementsByClassName` 같은 기본기부터 배웠다. React가 없던 시대에는 Vanilla JavaScript로 개발하기에 너무 어려웠기에, 대부분의 개발자들이 `jQuery`를 사용했다. 필자 역시 순수 JavaScript로 개발하면서 어려움을 느껴 jQuery를 사용했다. 사실 깊게 사용해본 건 아니지만, 인터넷을 검색해보니 아래와 같은 장점이 있다고 한다. **jQuery의 장점** * DOM 조작이 너무 쉬움 (`$('.button').click(...)`) * 크로스 브라우징 문제 자동 해결 * 간결하고 풍부한 API 하지만 프로젝트가 커질수록 문제가 생겼다. ```javascript // jQuery 스타일: DOM을 직접 조작 $('#addButton').click(function () { $('#todoList').append('
  • 새 할일
  • '); }); // 문제점: // 1. 어디서든 DOM을 수정할 수 있어서 코드가 꼬임 // 2. 데이터와 화면이 따로 놀아서 동기화 어려움 // 3. 같은 기능을 여러 곳에 복붙하게 됨 ``` *** ### 1.2 패러다임의 전환 웹 개발의 패러다임이 바뀌기 시작했다. **이전 방식 (명령형)**: "이 버튼을 찾아서, 클릭하면, 이 요소를 추가해" ```javascript // DOM을 직접 조작 element.appendChild(newElement); ``` **현대 방식 (선언형)**: "데이터가 이러면, 화면은 이렇게 보여줘" ```javascript // 상태만 변경하면 화면은 자동으로 업데이트 setState({ todos: [...todos, newTodo] }); ``` *** ### 1.3 프레임워크의 등장 이러한 패러다임의 전환을 위해 각종 프레임워크들이 등장했다. 대표적으로 3개의 프로젝트가 있다. **AngularJS (2010)**: CSR의 시작 * 클라이언트에서 렌더링한다는 개념 도입 * 양방향 데이터 바인딩 (편하지만 복잡해지면 추적 어려움) **React (2013)**: 컴포넌트의 시작 * "UI = f(state)" - UI는 상태의 함수다 * 단방향 데이터 흐름으로 예측 가능한 코드 * 컴포넌트 재사용 **Vue (2014)**: 실용성의 균형 * React + Angular의 장점 결합 * 배우기 쉽고 직관적 **결론**: 현대 웹은 `상태(State)`를 중심으로 돌아간다 *** ## 2. 상태 기반 렌더링 위에서 설명한 것처럼, 이전에는 DOM을 직접 다루는 것이 당연했다. 그러나 프레임워크들의 등장으로 패러다임이 변경되었다. 이제는 `상태(State)`를 기준으로 DOM을 렌더링하는 시대가 된 것이다. 즉, `DOM`은 더 이상 직접 조작의 대상이 아니라 상태의 결과물로서 존재하게 되었다. 쉽게 말하면, 상태가 변경되지 않으면 DOM도 변하지 않는다. 이 개념이 정착되면서 프론트엔드 개발자들은 자연스럽게 `Client Side Rendering(CSR)`과 `State Management(상태 관리)`라는 개념을 받아들이게 되었다. *** ### 2.1 상태 기반 렌더링 직접 구현하기 보통 우리가 알고 있는 `useState`의 흐름은 크게 3단계로 나뉜다. 1. `상태(state)` 선언 2. `상태(state)` 변경 → `setState` 3. 렌더링 물론 React는 성능 개선을 위해 Batching, Virtual DOM 등의 기술을 사용하지만, 이번 블로그의 목표는 **컴포넌트를 어떻게 구현해야 하는지 생각해보는 것**이기에 너무 상세한 내용은 제외하고 진행하겠다. 일단 실습을 위해 직접 DOM을 조작하여 간단한 `Todo List`를 구현해보자. ```html Todo 앱
    ``` 약간의 스타일링을 더한 `TodoList` 코드이다. *** ## 3. 재사용 가능한 컴포넌트 만들기 이제 DOM을 직접 조작하는 방식을 아래의 규칙을 지켜가며 만들어보자. 1. `상태(state)`가 모든 것의 중심 2. `setState`로만 상태를 변경 3. 상태가 변하면 **자동으로 `render()` 실행** 4. DOM을 직접 조작하지 않음 위에서 만든 `TodoList` 코드를 재사용 가능하게 만들어보자! *** ### 3.1 setState 기반으로 상태 변경 시 자동 렌더링 구현 ```html Todo 앱
    ``` 핵심 구조: `state → setState() → render()` 변경 사항: 1. `Component` 클래스 제거 2. `addTodo`, `toggleTodo`, `deleteTodo` 함수 제거 3. 이벤트 핸들러에서 직접 `setState()` 호출 4. `setState()` 호출 시 자동으로 `render()` 실행 모든 상태 변경은 `setState()`를 통해서만 이루어지며, `setState()`가 자동으로 리렌더링을 트리거한다. *** ### 3.2 Component 추상화 매번 컴포넌트를 만들 때마다 이렇게 코드를 작성하는 것은 너무 번거롭다. 따라서 **컴포넌트를 추상화하여 재사용 가능하게 만들어보자**. ```javascript /** * Component 기본 클래스 * - 모든 컴포넌트가 상속받을 베이스 클래스 */ class Component { constructor($target, initialState) { this.$target = $target; // 컴포넌트가 렌더링될 DOM 요소 this.state = initialState; // 컴포넌트의 상태 this.setup(); // 초기 설정 this.render(); // 초기 렌더링 } /** * 초기 설정 메서드 * - 하위 클래스에서 오버라이드 */ setup() {} /** * HTML 템플릿 생성 * - 하위 클래스에서 반드시 구현 */ template() { return ''; } /** * 상태 업데이트 * - React의 setState와 동일한 역할 */ setState(newState) { this.state = { ...this.state, ...newState }; this.render(); } /** * 렌더링 */ render() { this.$target.innerHTML = this.template(); this.setEvent(); } /** * 이벤트 등록 * - 하위 클래스에서 오버라이드 */ setEvent() {} } ``` 이제 이 Class를 활용하여 코드를 리팩토링 할 수 있다. ```html Todo 앱
    ``` 동작 방식: 1. `new TodoApp($app)` 실행 2. `Component`의 `constructor`가 `setup() → render()` 호출 3. `render()`가 `template() → setEvent()` 호출 4. `setState()` 호출 시 자동으로 `render()` 재실행 *** ## 4. 모듈화하여 작성하기 하나의 파일에 모든 코드를 작성하는 것은 번거롭다. 개발은 많은 사람들과 함께 하는 것이기 때문에, **최대한 모듈화하여 작성하는 것이 서로를 위해 좋다**. *** ### 4.1 폴더 구조 ``` 📦todo-app ┣ 📂src ┃ ┣ 📂core ┃ ┃ ┗ 📜Component.js // 기본 컴포넌트 클래스 ┃ ┣ 📂components ┃ ┃ ┗ 📜TodoApp.js // Todo 앱 컴포넌트 ┃ ┗ 📜main.js // 앱 실행 ┣ 📜index.html ┗ 📜package.json ``` *** ### 4.2 파일 분리 #### `src/core/Component.js` ```javascript // core/Component.js /** * 기본 Component 클래스 * - 모든 컴포넌트의 기반 * - 상태 관리, 렌더링, 이벤트 처리의 기본 구조 제공 */ export default class Component { constructor($target, initialState) { this.$target = $target; // 컴포넌트가 마운트될 DOM 요소 this.state = initialState; // 컴포넌트의 상태 this.setup(); // 초기 설정 this.render(); // 초기 렌더링 } setup() {} template() { return ''; } setState(newState) { this.state = { ...this.state, ...newState }; this.render(); } render() { this.$target.innerHTML = this.template(); this.setEvent(); // 렌더링 후 이벤트 재등록 } setEvent() {} } ``` #### `src/components/TodoApp.js` ```javascript // components/TodoApp.js import Component from '../core/Component.js'; /** * TodoApp 컴포넌트 * - 할일 목록 관리 애플리케이션 */ export default class TodoApp extends Component { setup() { this.state = { todos: [ { id: 1, text: '아침 운동하기', completed: false }, { id: 2, text: '블로그 글 쓰기', completed: true }, ], }; } template() { const { todos } = this.state; return `

    📝 Todo List

    ${todos .map( (todo) => `
    ${todo.text}
    ` ) .join('')}
    `; } setEvent() { // 추가 버튼 this.$target.querySelector('.addBtn').addEventListener('click', () => { const input = this.$target.querySelector('.todoInput'); if (input.value.trim()) { this.addTodo(input.value); input.value = ''; } }); // 완료 체크박스 this.$target.querySelectorAll('.toggleCheckbox').forEach((checkbox) => { checkbox.addEventListener('change', (e) => { this.toggleTodo(Number(e.target.dataset.id)); }); }); // 삭제 버튼 this.$target.querySelectorAll('.deleteBtn').forEach((btn) => { btn.addEventListener('click', (e) => { this.deleteTodo(Number(e.target.dataset.id)); }); }); } addTodo(text) { const newTodo = { id: Date.now(), text, completed: false }; this.setState({ todos: [...this.state.todos, newTodo] }); } toggleTodo(id) { const todos = this.state.todos.map((todo) => todo.id === id ? { ...todo, completed: !todo.completed } : todo ); this.setState({ todos }); } deleteTodo(id) { const todos = this.state.todos.filter((todo) => todo.id !== id); this.setState({ todos }); } } ``` #### `src/main.js` ```javascript // main.js import TodoApp from './components/TodoApp.js'; // 앱 실행 new TodoApp(document.querySelector('#app')); ``` #### `index.html` ```html Todo 앱
    ``` 물론 스타일 코드도 분리하면 더 좋겠지만, 이 포스트의 주제는 컴포넌트 개발이기 때문에 생략했다. 훨씬 더 깔끔하게 코드를 작성할 수 있다. *** ## 5. 이벤트를 효율적으로 다루기 위의 코드대로 작성하면 의식하고 보지 않으면 찾기 힘들지만, **문제점이 존재한다**. *** ### 문제: 이벤트가 계속 쌓인다 현재 코드의 문제점: ```javascript render() { this.$target.innerHTML = this.template(); this.setEvent(); // 렌더링할 때마다 이벤트 재등록! ❌ } ``` 시나리오: 1. 할일 추가 → render() 실행 → 이벤트 3개 등록 2. 또 추가 → render() 실행 → 이벤트 6개 등록 (중복!) 3. 계속 추가 → 이벤트가 계속 쌓임 → 메모리 누수! *** ### 해결: 이벤트 위임 (Event Delegation) 핵심 아이디어: 부모에게 한 번만 이벤트를 등록하고, 자식이 누군지 판별하자 *** ### Component.js 수정 ```diff export default class Component { $target; state; constructor($target) { this.$target = $target; this.setup(); + this.setEvent(); // constructor에서 한 번만 실행 this.render(); } setup() {} template() { return ''; } render() { this.$target.innerHTML = this.template(); - this.setEvent(); // 제거! } setEvent() {} setState(newState) { this.state = { ...this.state, ...newState }; this.render(); } } ``` *** ### TodoApp.js 수정 ```javascript export default class TodoApp extends Component { setup() { /* 생략 */ } template() { /* 생략 */ } /** * 이벤트 위임 패턴 사용 * - 부모 요소($target)에 한 번만 등록 * - 이벤트 버블링을 활용: 자식 요소의 클릭이 부모로 전파됨 * - classList.contains()로 실제 클릭된 요소 구분 */ setEvent() { // 모든 클릭 이벤트를 한 곳에서 처리 this.$target.addEventListener('click', (e) => { // 추가 버튼 클릭 // e.target.classList.contains()로 클릭된 요소가 addBtn인지 확인 if (e.target.classList.contains('addBtn')) { const input = this.$target.querySelector('.todoInput'); if (input.value.trim()) { this.addTodo(input.value); input.value = ''; } } // 삭제 버튼 클릭 // 부모에 등록된 이벤트지만, deleteBtn이 클릭되었을 때만 실행 if (e.target.classList.contains('deleteBtn')) { this.deleteTodo(Number(e.target.dataset.id)); } }); // 체크박스는 change 이벤트 사용 this.$target.addEventListener('change', (e) => { if (e.target.classList.contains('toggleCheckbox')) { this.toggleTodo(Number(e.target.dataset.id)); } }); } addTodo(text) { /* 생략 */ } toggleTodo(id) { /* 생략 */ } deleteTodo(id) { /* 생략 */ } } ``` 장점: * 이벤트가 딱 1번만 등록됨 * 할일이 100개여도 이벤트는 2개 (click, change) * 메모리 효율적 *** ### 더 나아가기: addEvent 헬퍼 메서드 매번 `if (e.target.classList.contains(...))` 쓰기 귀찮으니 헬퍼를 만들자. `classList.contains` vs `closest`의 차이 ```html ``` * `classList.contains('deleteBtn')`: 정확히 `
    ${filteredTodos .map( (todo) => `
    ${todo.text}
    ` ) .join('')}
    남은 할일: ${activeCount}개
    `; } setEvent() { // 추가 this.addEvent('click', '.addBtn', () => { const input = this.$target.querySelector('.todoInput'); if (input.value.trim()) { this.addTodo(input.value); input.value = ''; } }); // 삭제 this.addEvent('click', '.deleteBtn', (e) => { this.deleteTodo(Number(e.target.dataset.id)); }); // 토글 this.addEvent('change', '.toggleCheckbox', (e) => { this.toggleTodo(Number(e.target.dataset.id)); }); // 필터 this.addEvent('click', '.filterBtn', (e) => { this.setFilter(e.target.dataset.filter); }); } addTodo(text) { /* 생략 */ } toggleTodo(id) { /* 생략 */ } deleteTodo(id) { /* 생략 */ } setFilter(filter) { this.setState({ filter }); } } ``` 문제: 하나의 컴포넌트가 너무 많은 책임을 가짐 *** ### 6.2 컴포넌트 분리 계획 ``` TodoApp (상태 관리) ├─ TodoInput (입력) ├─ TodoList (목록 표시) ├─ TodoFilter (필터 버튼) └─ TodoStats (통계) ``` *** ### 6.3 폴더 구조 ``` 📦todo-app ┣ 📂src ┃ ┣ 📂core ┃ ┃ ┗ 📜Component.js ┃ ┣ 📂components ┃ ┃ ┣ 📜TodoInput.js // 입력 컴포넌트 ┃ ┃ ┣ 📜TodoList.js // 목록 컴포넌트 ┃ ┃ ┣ 📜TodoFilter.js // 필터 컴포넌트 ┃ ┃ ┗ 📜TodoStats.js // 통계 컴포넌트 ┃ ┣ 📜App.js // 최상위 앱 컴포넌트 ┃ ┗ 📜main.js ┣ 📜index.html ┗ 📜package.json ``` *** ### 6.4 Component Core 변경 자식 컴포넌트에게 데이터를 전달하려면 `props`가 필요하다. ```diff export default class Component { $target; + props; state; - constructor($target) { + constructor($target, props) { this.$target = $target; + this.props = props; // 부모로부터 받은 props this.setup(); this.setEvent(); this.render(); } setup() {} + mounted() {} // render 후 실행되는 라이프사이클 template() { return ''; } render() { this.$target.innerHTML = this.template(); + this.mounted(); // 자식 컴포넌트 마운트 시점 (render 후에 실행) } setEvent() {} setState(newState) { /* 생략 */ } addEvent(eventType, selector, callback) { /* 생략 */ } } ``` * `props`: 부모 → 자식으로 데이터/함수 전달 * `mounted`: render 후 자식 컴포넌트를 마운트할 때 사용 *** ### 6.5 컴포넌트 구현 #### `src/App.js` ```javascript // App.js import Component from './core/Component.js'; import TodoInput from './components/TodoInput.js'; import TodoList from './components/TodoList.js'; import TodoFilter from './components/TodoFilter.js'; import TodoStats from './components/TodoStats.js'; /** * App 컴포넌트 * - 전체 상태 관리 * - 자식 컴포넌트에게 데이터와 메서드 전달 */ export default class App extends Component { setup() { this.state = { todos: [ { id: 1, text: '아침 운동하기', completed: false }, { id: 2, text: '블로그 글 쓰기', completed: true }, ], filter: 'all', }; } template() { return `

    📝 Todo List

    `; } /** * render 후 자식 컴포넌트 마운트 */ mounted() { const { todos, filter } = this.state; // 필터링된 할일 const filteredTodos = this.getFilteredTodos(); // 각 자식 컴포넌트 마운트 const $input = this.$target.querySelector('[data-component="todo-input"]'); const $list = this.$target.querySelector('[data-component="todo-list"]'); const $filter = this.$target.querySelector( '[data-component="todo-filter"]' ); const $stats = this.$target.querySelector('[data-component="todo-stats"]'); new TodoInput($input, { onAddTodo: this.addTodo.bind(this), }); new TodoList($list, { todos: filteredTodos, onToggleTodo: this.toggleTodo.bind(this), onDeleteTodo: this.deleteTodo.bind(this), }); new TodoFilter($filter, { currentFilter: filter, onChangeFilter: this.setFilter.bind(this), }); new TodoStats($stats, { activeCount: todos.filter((t) => !t.completed).length, }); } getFilteredTodos() { const { todos, filter } = this.state; if (filter === 'active') return todos.filter((t) => !t.completed); if (filter === 'completed') return todos.filter((t) => t.completed); return todos; } addTodo(text) { const newTodo = { id: Date.now(), text, completed: false }; this.setState({ todos: [...this.state.todos, newTodo] }); } toggleTodo(id) { const todos = this.state.todos.map((todo) => todo.id === id ? { ...todo, completed: !todo.completed } : todo ); this.setState({ todos }); } deleteTodo(id) { const todos = this.state.todos.filter((todo) => todo.id !== id); this.setState({ todos }); } setFilter(filter) { this.setState({ filter }); } } ``` #### `src/components/TodoInput.js` ```javascript // components/TodoInput.js import Component from '../core/Component.js'; /** * TodoInput 컴포넌트 * - 할일 입력 담당 */ export default class TodoInput extends Component { template() { return `
    `; } setEvent() { const { onAddTodo } = this.props; this.addEvent('click', '.addBtn', () => { const input = this.$target.querySelector('.todoInput'); if (input.value.trim()) { onAddTodo(input.value); input.value = ''; } }); // Enter 키 지원 this.addEvent('keypress', '.todoInput', (e) => { if (e.key === 'Enter') { const input = e.target; if (input.value.trim()) { onAddTodo(input.value); input.value = ''; } } }); } } ``` #### `src/components/TodoList.js` ```javascript // components/TodoList.js import Component from '../core/Component.js'; /** * TodoList 컴포넌트 * - 할일 목록 표시 */ export default class TodoList extends Component { template() { const { todos } = this.props; return `
    ${ todos.length === 0 ? '

    할 일이 없다.

    ' : todos .map( (todo) => `
    ${todo.text}
    ` ) .join('') }
    `; } setEvent() { const { onToggleTodo, onDeleteTodo } = this.props; this.addEvent('change', '.toggleCheckbox', (e) => { onToggleTodo(Number(e.target.dataset.id)); }); this.addEvent('click', '.deleteBtn', (e) => { onDeleteTodo(Number(e.target.dataset.id)); }); } } ``` #### `src/components/TodoFilter.js` ```javascript // components/TodoFilter.js import Component from '../core/Component.js'; /** * TodoFilter 컴포넌트 * - 필터 버튼 제공 */ export default class TodoFilter extends Component { template() { const { currentFilter } = this.props; const buttonStyle = (filter) => ` padding: 8px 16px; margin: 5px; cursor: pointer; border: 1px solid #ddd; border-radius: 4px; background: ${currentFilter === filter ? '#2196f3' : 'white'}; color: ${currentFilter === filter ? 'white' : '#333'}; `; return `
    `; } setEvent() { const { onChangeFilter } = this.props; this.addEvent('click', '.filterBtn', (e) => { onChangeFilter(e.target.dataset.filter); }); } } ``` #### `src/components/TodoStats.js` ```javascript // components/TodoStats.js import Component from '../core/Component.js'; /** * TodoStats 컴포넌트 * - 통계 정보 표시 */ export default class TodoStats extends Component { template() { const { activeCount } = this.props; return `
    남은 할일: ${activeCount}개
    `; } } ``` #### `src/main.js` ```javascript // main.js import App from './App.js'; // 앱 실행 new App(document.querySelector('#app')); ``` #### `index.html` ```html Todo 앱
    ``` *** ## 마치며 최근 프레임워크의 코어 기능을 직접 구현해보는 이유는 명확한다. 완벽한 재현이 아닌, 그 근본 원리를 이해하기 위함입니다. AI 시대에는 라이브러리를 '잘 활용하는 능력'이 중요해졌지만, 견고한 기본기 없이는 복잡한 문제를 유연하게 해결할 수 없다. 오히려 AI 시대가 되면서 기본기의 중요성을 더욱 절감하게 되었다. 이번 상태 기반 컴포넌트 제작 경험을 통해 프레임워크 뒤에 숨겨진 상태 관리와 렌더링 최적화를 생각해 보는 시간을 갖었다. 실무에서는 빠른 구현에 집중하느라 놓치기 쉬운 부분들을 천천히 되짚어보는 시간을 갖었고, 정말 많은 부족함을 느꼈다. (물론 매번 느낍니다 ^-^) 그래도, 이번 경험을 통해 나 리액트 없이 컴포넌트 개발 해봤어 라고 말할 수 있지 않을까? 이번 기회에 `React` 말고도, 다른 프레임워크에 대해 한번 공부해보고 싶다. 특히, `Angular`에 대해 한번 공부해보고 싶다. ## 핵심 정리 * **jQuery 시대**: DOM 직접 조작의 한계 (코드 꼬임, 데이터-화면 동기화 어려움) * **패러다임 전환**: * 명령형 → 선언형 * DOM 직접 조작 → 상태 기반 렌더링 * **현대 프레임워크**: * AngularJS (2010): CSR 개념 도입 * React (2013): "UI = f(state)", 컴포넌트 재사용 * Vue (2014): React + Angular의 실용적 균형 * **상태 기반 렌더링**: * `state → setState() → render()` 흐름 * 상태가 변경되어야 DOM이 변경됨 * CSR과 State Management의 핵심 * **컴포넌트 추상화**: * `setup()`: 초기 설정 * `template()`: HTML 생성 * `setState()`: 상태 업데이트 및 리렌더링 * `render()`: DOM 업데이트 * `setEvent()`: 이벤트 등록 * **이벤트 최적화**: * 문제: 렌더링마다 이벤트 재등록 → 메모리 누수 * 해결: 이벤트 위임 (부모 요소에 한 번만 등록) * `closest()`: 버튼 내부 요소 클릭도 감지 * **컴포넌트 조합**: * `props`: 부모 → 자식 데이터/함수 전달 * `mounted()`: 렌더링 후 자식 컴포넌트 마운트 * 단일 책임 원칙: 각 컴포넌트는 하나의 역할만 **컴포넌트는 레고 블록과 같다. 작은 블록들을 조합해서 큰 구조물을 만들고, 필요하면 블록을 교체하거나 재사용할 수 있다. 상태(state)는 블록을 어떻게 조립할지 정하는 설계도이며, setState()는 설계도를 변경하면 자동으로 블록을 재조립해주는 마법사다.** --- # Babel로 배우는 현대 JavaScript 호환성 > 개발을 시작하고 나서 나는 비전공자이기에 주변에서 얻을 인사이트가 많이 부족하여 정말 많은 개발자들의 글과 경험담을 찾아보았다. 심지어 아직도 매일 러닝할 때 해외 개발자들의 팟캐스트를 들으며 달리고있다. 요즘은 AI가 문제 해결을 돕는 시대지만, 결국 핵심은 질문하는 사람의 수준... - 원문: https://www.yolog.co.kr/post/babel - 카테고리: 개발 - 발행: 2025-10-07 - 수정: 2025-10-07 개발을 시작하고 나서 나는 비전공자이기에 주변에서 얻을 인사이트가 많이 부족하여 정말 많은 개발자들의 글과 경험담을 찾아보았다. 심지어 아직도 매일 러닝할 때 해외 개발자들의 팟캐스트를 들으며 달리고있다. 요즘은 AI가 문제 해결을 돕는 시대지만, 결국 핵심은 질문하는 사람의 수준이라는 걸 점점 더 느낀다. 나처럼 이제 2년 차 개발자가 던지는 질문과, 수많은 프로젝트와 이슈를 겪은 선배 개발자들이 하는 질문은 다를 수밖에 없다. 그 차이는 결국 경험에서 비롯된 통찰이고, 그 경험을 간접적으로라도 쌓기 위해 과거 기술과 문제 해결 과정을 꾸준히 공부하고 정리하려고 한다. 프론트엔드 개발 영역이 오래되지는 않았지만 선배 개발자분들이 가장 괴롭다고 느끼는 건 크로스 브라우징 이슈이고, 그중에서도 한때는 `IE(Internet Explorer)` 였다는 것이다. 물론 나는 IE 호환성의 시대를 직접 피부로 겪진 못했다. 하지만 최근에 비슷하게 나를 괴롭히는 건 `Safari`다. 앱 개발 중 `Safari`의 예외적인 동작 때문에 애를 먹은 적이 많았고, 그걸 계기로 이번 추석에는 `Babel`과 `Polyfill`을 집중적으로 공부해보았다. *** ## 바벨탑과 브라우저 고대 히브리 신화에 보면 '바벨탑' 이야기가 있다. 사람들이 하늘 높이 올라가기 위해서 바벨탑을 하나씩 쌓아 올라가고 있었는데, 이것을 본 신이 위기감을 느꼈는지 그들의 언어를 모두 뒤섞어 서로 소통하지 못하게 만들었다. 결국에는 탑을 완성하지 못하게 되었다. (이미지: 신이 분노하셨다..!) 고대 히브리 신화와 마찬가지로 브라우저의 세계도 매우 유사하다. `Chrome`, Safari, Edge, Firefox, 그리고 이미 역사 속으로 사라진 IE까지 각 브라우저는 `ECMAScript` 표준을 조금씩 다르게 지원한다. 그 결과, 같은 `JavaScript` 코드가 브라우저마다 다르게 동작하는 문제가 생긴다. 예를 들어, 몇 년 전까지만 해도 `Safari` 최신 버전에서조차 `Promise.prototype.finally()`를 지원하지 않았다. 즉, 다음과 같은 간단한 코드일지라도 `Safari`는 이를 이해하지 못해 `런타임 오류`를 발생시켰다. 특히 이러한 `크로스 브라우징 이슈`는 프론트엔드 개발을 할 때 처음 입문하는 사람에게는 크게 와닿지 않을 수 있지만, 점차 연차가 쌓여갈수록 개발을 곤란하게 만드는 원인 유발자이다. ```js Promise.resolve(1).finally(() => console.log('송편')); ``` 이런 문제를 해결하기 위해 등장한 것이 바로 Babel이다. 이름처럼, 서로 다른 언어를 사용하는 브라우저들을 이해하게 만드는 통역가의 역할을 한다고 보면 된다. *** ### Babel 이란? Babel은 총 3개의 단계를 거쳐 코드를 변환한다. 1. Parsing (파싱) 코드를 읽어서 토큰(token)으로 분리하고, `AST(Abstract Syntax Tree)` 형태로 구조화한다. > **AST란?** 코드를 트리 구조로 표현한 것으로, 브라우저와 빌드 도구가 코드를 이해하고 조작하기 위해 사용하는 중간 표현 형식입니다. 2. Transforming (변환) AST를 순회하면서 새로운 문법 규칙에 맞게 변경한다. 예: `const` → `var`, `() => {}` → `function () {}` 3. Printing (출력) 변환된 AST를 다시 문자열 코드로 출력한다. 이 과정을 통해 브라우저가 이해하지 못하는 문법을 과거 버전의 `JavaScript`로 재작성하는 것이다. *** ## Babel 설치 및 기본 동작 이제 실제로 Babel이 어떻게 동작하는지 살펴보자. ### 1. Babel 설치 ```bash npm install @babel/core @babel/cli ``` ### 2. 코드 작성 `app.js` 파일을 생성하자 ```js // const, arrow function 모두 es6 // es6를 지원하지 않는 브라우저 IE는 인식하지 못함. // babel을 통해서 IE를 포함한 모든 브라우저에서 인식할 수 있게끔 변환하는 과정이 필요함. const alert = (msg) => window.alert(msg); ``` ### 3. Babel 실행 실행 ```bash npx babel app.js ``` 실행 결과 ```js // const, arrow function 모두 es6 // es6를 지원하지 않는 브라우저 IE는 인식하지 못함. // babel을 통해서 IE를 포함한 모든 브라우저에서 인식할 수 있게끔 변환하는 과정이 필요함. const alert = (msg) => window.alert(msg); ``` 이 코드를 실행하면, 무언가 변화가 일어나야 하는데 **실제로 아무런 변화가 없다.** 왜냐하면, Babel은 "변환을 담당할 플러그인"이 지정되지 않았기 때문이다. 즉, 지금은 `Parsing`과 `Printing`만 수행하고 실제 마지막 단계인 `Transform` 단계는 비어 있는 상태다. *** ## Babel 플러그인 이해하기 Babel은 `플러그인(plugin)`을 통해 실제 변환 작업을 수행한다. 플러그인은 일종의 미들웨어로, `AST`를 순회하며 특정 노드를 변환한다. ### 직접 만들어 보는 Babel 커스텀 플러그인 아래와 같이 한번 커스텀할 바벨 플러그인을 만들어보자. ```js module.exports = function myBabelPlugin() { return { // 커스텀 플러그인을 만들 때는 visitor라는 객체를 갖고 있는 객체를 반환해야 함. visitor: { // visitor 객체 안에 Identifier라는 키가 있음. // Identifier 노드를 방문할 때 호출되는 함수 Identifier(path) { // 바벨이 넣어주는 path를 갖음. const name = path.node.name; // 바벨이 만든 AST 노드를 출력 console.log('Identifier() name:', name); // 변환 작업: 코드 문자열을 역순으로 변환 path.node.name = name.split('').reverse().join(''); }, }, }; }; ``` Babel의 help 문서를 통해 어떤 식으로 plugin을 실행시킬 수 있는지 알 수 있다. ```bash npx babel --help ``` 실제로 이를 한번 실행해보자. ```bash npx babel app.js --plugins './my-babel-plugin.js' ``` (이미지: Custom Babel 플러그인 실행 결과) 터미널에는 각 토큰이 출력되며, 변환된 코드가 표시된다. 이제 Babel이 `AST`를 방문(visit)하며 변환을 수행한다는 것을 눈으로 확인했고, 각각 모든 단어를 우리가 reverse를 해준다고 했기에 `parsing` 되어진 토큰들이 뒤집어진 형태로 `transform` 된 것을 확인할 수 있다. *** ## const → var로 변경하는 플러그인 만들기 이제 실제로 우리는 브라우저 호환성을 유지하기 위해 `ES6` 문법을 `ES5`로 바꿔야 한다. 한번 `const` 키워드를 `var`로 변환하는 플러그인을 만들어보자. ```js module.exports = function myBabelPlugin() { return { visitor: { VariableDeclaration(path) { // path.node.kind를 가보면 const가 출력됨. console.log('VariableDeclaration() kind:', path.node.kind); // const // const -> var로 변환 if (path.node.kind === 'const') { // path.node.kind를 가보면 var가 출력됨. path.node.kind = 'var'; } }, }, }; }; ``` 실제로 한번 실행을 해보자. ```bash npx babel app.js --plugins './my-babel-plugin.js' ``` 결과: ```js var alertMessage = (msg) => window.alert(msg); ``` 아직 화살표 함수는 변환하지 않았지만, `const`는 `var`로 `ES5` 형태로 변경하는 작업을 했다. *** ## 언제까지 만드냐, 공식 플러그인 사용하기 물론, 정말 미세한 조정이 필요한 경우에는 직접 커스텀한 플러그인을 만들어야 하지만, 필요한 대부분의 변환 기능을 Babel에서 플러그인 형태로 제공하고 있다. 예를 들어, `@babel/plugin-transform-block-scoping`은 위의 플러그인과 동일하게 동작한다. ```bash npm install -D @babel/plugin-transform-block-scoping npx babel app.js --plugins @babel/plugin-transform-block-scoping ``` 결과는 당연히 위에서 만든 커스텀 플러그인과 동일하다. 여기에 화살표 함수도 `ES5`까지만 호환하는 브라우저에서는 이해할 수 없기 때문에 이를 변경해주어야 한다. 물론, 이런 플러그인도 만들어져 있다. ```bash npm install -D @babel/plugin-transform-arrow-functions npx babel app.js --plugins @babel/plugin-transform-block-scoping --plugins @babel/plugin-transform-arrow-functions ``` 출력: ```js var alertMessage = function (msg) { return window.alert(msg); }; ``` 이제 대부분의 브라우저에서 문제없이 실행할 수 있을 것이다. *** ## babel.config.js로 설정 관리하기 그리고 브라우저가 인식 못하는 것은 아니지만, `ECMAScript 5`에서부터 지원하는 `strict mode`를 사용하는 것이 안전하기 때문에 브라우저에서 `use strict` 구문을 추가하는 것이 좋다. 이 또한 바벨에서 플러그인으로 제공해준다. 근데 지금처럼, 여러 플러그인을 매번 CLI로 지정하는 것은 비효율적이다. 무엇이 비효율적인지는 아래 코드를 보자. 우리는 이제 3개의 플러그인을 실행시켜야 한다. 1. const → var로 변환 2. 화살표 함수 → ES5로 인식할 수 있는 함수 형태로 변환 3. `strict mode` 추가 ```bash npx babel app.js \ --plugins @babel/plugin-transform-block-scoping \ --plugins @babel/plugin-transform-arrow-functions \ --plugins @babel/plugin-transform-strict-mode ``` 이렇게 계속 매번 추가해주는 것은 비효율적이다. 당연히 우리가 있는 개발 씬에서는 반복하는 일이 많이 발생하면 이를 해결하는 대부분의 해결책을 제시하고 있다. ```js // babel.config.js module.exports = { plugins: [ '@babel/plugin-transform-block-scoping', '@babel/plugin-transform-arrow-functions', '@babel/plugin-transform-strict-mode', ], }; ``` 이제 단순히 아래 명령어만 실행하면 된다. ```bash npx babel app.js ``` *** ## Preset(프리셋) 이해하기 `ES6` 문법은 플러그인이 매우 많다. 따라서 매번 모든 플러그인을 나열하기보다는 preset을 사용한다. 프리셋은 플러그인 세트를 하나의 이름으로 묶은 것이다. 예를 들어, 우리가 방금 사용한 플러그인 3개를 하나의 프리셋으로 만들어보자. ```js // my-babel-preset.js module.exports = function myBabelPreset() { return { plugins: [ '@babel/plugin-transform-block-scoping', '@babel/plugin-transform-arrow-functions', '@babel/plugin-transform-strict-mode', ], }; }; ``` 그리고 설정 파일을 이렇게 변경한다. ```js // babel.config.js module.exports = { presets: ['./my-babel-preset'], }; ``` 결과는 동일하지만, 구조는 훨씬 깔끔하다. *** ## @babel/preset-env — 실무의 핵심 프리셋 그래서 이제 우리는 preset-env로 해당 프리셋을 사용할 수 있다. * preset-env * preset-flow * preset-react * preset-typescript 실무에서는 위와 같은 커스텀 preset 대신 Babel이 공식적으로 제공하는 @babel/preset-env를 사용한다. 이 preset은 `ES2015` 이후 모든 기능을 자동으로 변환해준다. preset-env는 `ECMAScript 2015+`를 변환할 때 사용한다. 바벨 7 이전 버전에는 연도별로 각 프리셋을 제공했지만(`babel-preset-es2015`, `babel-preset-es2016`, `babel-preset-es2017`, `babel-preset-latest`) 지금은 env 하나로 합쳐졌다. (얼마나 간편한가. 진작 이럴 것이지) ```bash npm install -D @babel/preset-env ``` ```js // babel.config.js module.exports = { presets: ['@babel/preset-env'], }; ``` ```bash npx babel app.js ``` 이제 Babel이 자동으로 최신 문법을 브라우저 친화적으로 변환한다. *** ## 브라우저 타겟 지정하기 preset-env의 강점은 지원할 브라우저 범위를 설정할 수 있다는 것이다. 예를 들어, `Chrome 79` 이상만 지원한다면 다음처럼 설정한다. ```js // babel.config.js module.exports = { presets: [ [ '@babel/preset-env', { targets: { chrome: '79', }, }, ], ], }; ``` ```js 'use strict'; // const, arrow function 모두 es6 // es6를 지원하지 않는 브라우저 IE는 인식하지 못함. // babel을 통해서 IE를 포함한 모든 브라우저에서 인식할 수 있게끔 변환하는 과정이 필요함. const alert = (msg) => window.alert(msg); ``` (이미지: Can I Use const 호환성 결과) 이 경우, `Chrome 79` 이상에서 이미 지원하는 문법(`const`, `=>`)은 변환하지 않는다. 즉, 필요한 변환만 적용하여 빌드 성능을 최적화할 수 있다. `IE 11`까지 지원하려면 이렇게 추가한다. ```js module.exports = { presets: [ [ '@babel/preset-env', { targets: { chrome: '79', ie: '11', }, }, ], ], }; ``` **출력** ```js 'use strict'; // const, arrow function 모두 es6 // es6를 지원하지 않는 브라우저 IE는 인식하지 못함. // babel을 통해서 IE를 포함한 모든 브라우저에서 인식할 수 있게끔 변환하는 과정이 필요함. var alert = function alert(msg) { return window.alert(msg); }; ``` 이제 Babel은 두 브라우저 모두에서 동작 가능한 코드를 생성한다. *** ## Babel과 Webpack의 통합 현대 프론트엔드 빌드 환경에서는 Babel이 보통 `Webpack`과 함께 사용된다. `babel-loader`를 통해 빌드 과정에서 자동으로 코드 변환을 수행한다. ```bash npm install -D babel-loader ``` ```js // webpack.config.js module.exports = { module: { rules: [ { test: /\.js$/, exclude: /node_modules/, use: 'babel-loader', }, ], }, }; ``` `Webpack`이 JS 파일을 읽을 때마다 `Babel`이 자동으로 변환해준다. ## 마무리 오늘날의 프론트엔드 환경에서는 `Webpack`뿐 아니라 `Vite`, `Rollup`, `esbuild`, `tsup` 같은 다양한 빌드 도구가 등장했다. 이들 각각은 번들링과 트랜스파일링을 조금씩 다르게 처리하지만 근본적으로는 `Babel`이 다루는 문제와 같은 지점을 해결하고 있다. 즉 "최신 문법을 사용하되 실행 환경이 이해할 수 있도록 안전하게 변환하는 일"이다. `Webpack`이 `Babel`과 함께 쓰이는 이유도 여기에 있다. `Webpack`은 모듈을 하나로 묶는 번들러이고 `Babel`은 언어 수준의 호환성을 보장하는 변환기이기 때문이다. 반면 `Vite`나 `esbuild`, `Rollup`도 내부적으로는 `Babel`과 유사한 트랜스파일링 파이프라인을 포함하거나 `Babel` 플러그인을 그대로 활용할 수 있게 설계되어 있다. 따라서 `Webpack`을 배운다는 것은 단순히 오래된 도구를 배우는 게 아니라 "빌드 시스템이 어떻게 코드를 읽고 변환하는지"를 이해하는 일이다. 이 감각이 잡히면 어떤 빌드 도구를 만나더라도 `Babel`이 어디서 어떤 역할을 하는지 자연스럽게 파악할 수 있을 것이다. *** ## 핵심 정리 * **Babel의 역할**: * 최신 JavaScript를 구형 브라우저가 이해할 수 있는 코드로 변환 * ES6+ 문법 → ES5 문법 트랜스파일 * 브라우저 호환성 문제 해결 * **트랜스파일링 vs 컴파일**: * 트랜스파일: 같은 수준의 언어로 변환 (ES6 → ES5) * 컴파일: 다른 수준의 언어로 변환 (TypeScript → JavaScript) * **Babel 동작 원리**: 1. Parsing: 코드를 AST(Abstract Syntax Tree)로 변환 2. Transform: AST를 플러그인으로 수정 3. Generate: 수정된 AST를 코드로 재생성 * **Polyfill**: * 문법은 Babel로 변환, 기능은 Polyfill로 추가 * `Promise`, `Array.from` 같은 새 API 구현 * core-js + regenerator-runtime 조합 * 필요한 Polyfill만 선택적으로 로드 * **@babel/preset-env**: * 타겟 브라우저 설정 (browserslist) * 필요한 변환만 자동 선택 * 번들 크기 최적화 * `useBuiltIns: 'usage'`로 필요한 Polyfill만 포함 * **Webpack + Babel**: * Webpack: 모듈 번들러 * Babel: 언어 변환기 * babel-loader로 연동 * JS 파일을 읽을 때마다 Babel이 자동 변환 * **현대 빌드 도구**: * Vite: esbuild (개발) + Rollup (프로덕션) * Rollup: 라이브러리 번들링에 특화 * esbuild: Go로 작성된 초고속 빌드 도구 * 모두 Babel과 유사한 트랜스파일링 포함 * **크로스 브라우징**: * IE 시대: 가장 큰 호환성 문제 * 현재: Safari의 예외적 동작 * Babel로 문법 호환, Polyfill로 기능 보완 * **실무 권장 설정**: * @babel/preset-env 사용 * browserslist로 타겟 지정 * useBuiltIns: 'usage' (자동 Polyfill) * corejs: 3 (최신 Polyfill) **Babel은 통역사와 같다. 최신 언어(ES6+)를 구형 브라우저가 이해할 수 있는 언어(ES5)로 통역해준다. Polyfill은 번역기에 없는 단어를 사전에 추가하는 것과 같다. 새로운 단어(Promise, Array.from)를 구형 브라우저도 이해할 수 있도록 정의를 추가한다.** --- # 렌더링 최적화 > 브라우저가 웹 페이지를 렌더링하려면 이미지, 글꼴, 스타일시트 같은 추가 자원이 필요하다. 이 자원들은 대부분 원격 서버에 있어서 HTTP 요청으로 불러와야 한다. 이런 추가 요청은 렌더링 성능에 큰 영향을 준다. 웹 페이지가 빠르게 로드되려면 이러한 HTTP 요청을 효율적으로 제... - 원문: https://www.yolog.co.kr/post/http-rendering-optimization - 카테고리: 개발 - 발행: 2025-09-24 - 수정: 2025-09-24 브라우저가 웹 페이지를 렌더링하려면 이미지, 글꼴, 스타일시트 같은 추가 자원이 필요하다. 이 자원들은 대부분 원격 서버에 있어서 HTTP 요청으로 불러와야 한다. 이런 추가 요청은 렌더링 성능에 큰 영향을 준다. 웹 페이지가 빠르게 로드되려면 이러한 HTTP 요청을 효율적으로 제어해야 한다. 이번 포스팅에서는 브라우저의 렌더링 과정을 이해하고, 외부 리소스의 로드 시점을 조절해서 웹 성능을 최적화하는 기법들을 살펴보겠다. (이미지: 렌더링 최적화) *** ## 1. 렌더링 과정 사용자가 주소창에 URL을 입력하면 브라우저는 먼저 DNS(도메인 네임 서버)에서 IP 주소를 얻다. 이 IP 주소로 서버와 연결한 뒤 HTTP 통신을 시작한다. 브라우저는 URL 경로에 해당하는 문서를 요청하고, 서버는 준비된 문서를 응답한다. 문서를 받은 브라우저는 이를 화면에 그릴 수 있는 형태로 변환해야 한다. 이 과정을 Critical Rendering Path(CRP)라고 한다. CRP는 다음 5단계로 진행된다. 먼저 **파싱 단계**입니다. HTML 문서를 파싱해서 DOM을 만들고, CSS 코드는 CSSOM으로 만듭니다. 다음은 **렌더 트리 생성**입니다. DOM과 CSSOM을 합쳐서 렌더 트리를 만듭니다. **레이아웃 단계**에서는 각 요소의 크기와 위치를 계산한다. 마지막으로 **페인팅 단계**에서 계산된 레이아웃을 기반으로 실제 픽셀로 화면에 그립니다. ``` Critical Rendering Path(CRP) 과정: HTML 파싱 ──────→ DOM 생성 ↓ CSS 파싱 ───────→ CSSOM 생성 ↓ 렌더 트리 생성 ↓ 레이아웃 (Reflow) ↓ 페인팅 (Repaint) ``` 파싱 단계를 자세히 살펴보겠다. HTML은 개발자가 이해할 수 있는 마크업 코드입니다. 브라우저가 이를 화면에 그리려면 자신이 이해할 수 있는 형태로 변환해야 한다. 파싱은 코드를 한 줄씩 읽으면서 의미 있는 단위로 분석하는 과정입니다. 그런데 파싱 중에 특정 코드를 만나면 브라우저는 파싱을 멈추고 그 코드를 먼저 처리한다. 예를 들면 아래와 같은 자바스크립트를 로딩하는 코드입니다. ```html ``` HTML 문서에서 이런 스크립트 태그를 만나면 브라우저는 파싱을 멈춥니다. 자바스크립트를 다운로드하기 위한 HTTP 요청을 보내고, 응답받은 파일을 실행한다. 자바스크립트 다운로드와 실행이 완료되면 중단했던 지점으로 돌아가 파싱을 재개한다. 이처럼 스크립트 태그는 파싱을 중단시켜 렌더링 시간을 늘립니다. 자바스크립트 파일이 많거나 무거울수록 페이지 로드 속도가 느려집니다. ## 핵심 정리 브라우저의 렌더링 과정은 파싱 → DOM/CSSOM → 렌더 트리 → 레이아웃 → 페인팅의 5단계를 거치며, ` ``` 서버에서 제공할 자바스크립트 파일을 만들어보겠다. script-big.js는 콘솔에 파일명을 출력한다. ```js console.log('script-big.js'); ``` script-small.js도 마찬가지입니다. ```js console.log('script-small.js'); ``` 두 스크립트는 각자 파일명을 콘솔에 출력한다. 파일 크기를 시뮬레이션하기 위해 응답 시간을 다르게 설정해보겠다. serve-static.js 파일을 보면 다음과 같다. ```js const fs = require('fs'); const path = require('path'); const serveStatic = (root) => { return (req, res) => { const filepath = path.join(root, req.url === '/' ? '/index.html' : req.url); fs.readFile(filepath, (err, data) => { if (err) { if (err.code === 'ENOENT') { res.statusCode = 404; res.write('Not Found\n'); res.end(); return; } res.statusCode = 500; res.write('Internal Server Error\n'); res.end(); return; } const ext = path.extname(filepath).toLowerCase(); let contentType = 'text/html'; switch (ext) { case '.html': contentType = 'text/html'; break; case '.js': contentType = 'text/javascript'; break; case '.css': contentType = 'text/css'; break; case '.webp': contentType = 'image/png'; break; case '.json': contentType = 'application/json'; break; case '.otf': contentType = 'font/otf'; break; default: contentType = 'application/octet-stream'; } res.setHeader('Content-Type', contentType); // 인터페이스 추가 if (res.delayMs) { setTimeout(() => { res.write(data); res.end(); }, res.delayMs); return; } res.write(data); res.end(); }); }; }; module.exports = serveStatic; ``` 이 핸들러는 public 폴더의 파일들을 읽어서 응답한다. `res.delayMs` 속성으로 응답 지연 시간을 설정할 수 있게 인터페이스를 추가했다. server.js에서 파일명에 따라 지연 시간을 설정해보겠다. ```js const http = require('http'); const path = require('path'); const static = require('../shared/serve-static'); const handler = (req, res) => { // filename 가져오기 const filename = path.basename(req.url); if (filename === 'script-big.js') { // 3초 후 응답 res.delayMs = 3_000; } if (filename === 'script-small.js') { // 1초 후 응답 res.delayMs = 1_000; } static(path.join(__dirname, 'public'))(req, res); }; const server = http.createServer(handler); const port = process.env.PORT || 3000; server.listen(port, () => console.log(`server is running ::${port}`)); ``` script-big.js는 3초, script-small.js는 1초 후에 응답하도록 설정했다. Firefox에서 테스트하려면 `about:config`에서 `network.http.max-persistent-connections-per-server`를 6에서 0으로 변경해야 한다. 이 설정은 서버당 동시 연결 수를 제한하는 옵션으로, 0으로 설정하면 스크립트가 순차적으로 로드되는 것을 확인할 수 있다. (이미지: network.http.max-persistent-connections-per-server을 6 -> 0으로 변경) 그리고 로컬호스트 3000번에 접속을 해보겠다. (이미지: 로컬호스트 3000번에 접속) script-big.js가 로딩되고 이어서 script-small.js가 로딩됐다. 브라우저가 HTML을 파싱하다가 첫 번째 스크립트 태그를 만나면 파싱을 멈춥니다. script-big.js를 다운로드하기 위해 네트워크 요청을 보내고, 3초 후 파일을 받아 실행한다. 다시 파싱을 재개하다가 두 번째 스크립트 태그를 만나면 또 파싱을 멈추고 script-small.js를 요청한다. (이미지: script-big.js, script-small.js를 가져오기 위한 네트워크 요청을 만든다) 스크립트 로딩을 완료한 후 파싱을 재개해서 DOM을 완성한다. 두 스크립트를 순차적으로 처리하는 데 약 4초가 걸렸다. 정확한 시간을 측정하기 위해 Performance API를 사용해보겠다. `performance.mark`로 측정 시작 시점을 표시한다. ```html ``` `performance.mark`로 종료 시점을 표시하고, `performance.measure`로 실제 시간을 측정한다. ```js console.log('script-big.js'); // 측정 종료 시각 표기 performance.mark('script-big-end'); performance.measure( 'script-big execution time', 'script-big-start', 'script-big-end' ); ``` ```js console.log('script-small.js'); // 측정 종료 시각 표기 performance.mark('script-small-end'); performance.measure( 'script-small execution time', 'script-small-start', 'script-small-end' ); ``` 브라우저는 모든 리소스 로딩이 완료되면 load 이벤트를 발생시킵니다. 이 이벤트에서 측정 결과를 확인해보겠다. ```html ``` (이미지: performance.mark를 통해 측정 시각을 표기할 수 있음) 결과를 보면 script-big은 45ms에 시작해서 3초, script-small은 3초쯤 시작해서 1초가 걸렸다. 총 4초가 소요됐다. 스크립트가 없었다면 1초 안에 렌더링이 완료됐을 것입니다. 스크립트 태그가 파싱을 중단시켜 렌더링 성능에 영향을 준 것입니다. *** ## 3. Async 스크립트 렌더링 성능을 개선하려면 파싱이 중단되지 않아야 한다. 파싱과 HTTP 요청을 하나의 메인 스레드가 처리하기 때문에 파싱이 멈춥니다. 하지만 브라우저에는 I/O 스레드라는 별도 스레드가 있어서 네트워크 작업을 처리할 수 있다. async 속성을 사용하면 I/O 스레드가 스크립트를 다운로드하는 동안 메인 스레드는 파싱을 계속할 수 있다. ```html ``` 브라우저는 script-big과 script-small을 동시에 다운로드하면서 파싱을 계속 진행한다. 브라우저 설정을 복구하고 확인해보겠다. (이미지: 위에서 6으로 바꾼 것을 다시 0으로 변경) (이미지: 위와 다르게 async 속성 시 스크립트 파일을 동시에 다운로드 함.) 스크립트 파일들이 29ms에 동시에 다운로드를 시작했다. 메인 스레드가 DOM을 먼저 만들고, 더 가벼운 script-small.js가 먼저 다운로드 완료되어 1초쯤 실행됐다. 이어서 script-big도 다운로드가 완료되면 실행된다. (이미지: 기존 1초 + 3초 = 4초 이지만, async 속성시 3초 소요) 총 시간이 4초에서 3초로 줄었다. `async`는 스크립트를 동시에 다운로드하고 완료된 순서대로 실행한다. script-big.js를 먼저 작성했지만, script-small.js가 빨리 다운로드되어 먼저 실행됐다. `async`는 DOM과 무관하고 서로 독립적인 스크립트에 적합한다. 광고 스크립트나 분석 도구처럼 애플리케이션과 무관한 스크립트에 사용하면 좋다. ``` async vs defer 실행 순서 비교: 일반 스크립트: HTML 파싱 → [중단] → 스크립트 다운로드 → 스크립트 실행 → [파싱 재개] async 스크립트: HTML 파싱 ────────────────────────→ DOM 생성 ↓ (병렬) 스크립트 다운로드 → [다운로드 완료 시 즉시 실행] defer 스크립트: HTML 파싱 ────────────────────────→ DOM 생성 → [순서대로 실행] ↓ (병렬) 스크립트 다운로드 ─────────────────┘ ``` ## 핵심 정리 `async` 속성은 스크립트를 병렬로 다운로드하고 완료된 순서대로 실행한다. DOM과 무관하고 서로 독립적인 스크립트(광고, 분석 도구 등)에 적합한다. *** ## 4. Defer 스크립트 `async`는 빠르지만 실행 순서를 보장하지 않다. 스크립트가 서로 의존적일 때는 문제가 될 수 있다. script-big.js에 `foo` 함수를 정의해보겠다. ```js console.log('script-big.js'); // 전역 객체에 함수 등록 (다른 스크립트에서 사용 예정) window.foo = () => console.log('foo is executed'); performance.mark('script-big-end'); performance.measure( 'script-big execution time', 'script-big-start', 'script-big-end' ); ``` script-small.js에서 이 `foo` 함수를 호출하도록 해보겠다. ```js console.log('script-small.js'); // 전역 객체에 등록된 함수 호출 foo(); performance.mark('script-small-end'); performance.measure( 'script-small execution time', 'script-small-start', 'script-small-end' ); ``` script-small.js는 `foo` 함수가 이미 정의되어 있다고 가정한다. 실행해보겠다. (이미지: async 시 스크립트 크기가 작은 것을 먼저 로드하기 때문에, 에러가 발생) 코드에서는 big을 먼저 작성했지만, `async`로 인해 small이 먼저 실행됐다. small이 실행될 때 `foo` 함수가 아직 없어서 오류가 발생했다. 다운로드는 동시에 하면서도 실행 순서를 보장하려면 `defer` 속성을 사용해야 한다. `defer`는 파일을 동시에 다운로드하지만 DOM이 생성될 때까지 실행을 미룹니다. `defer`를 추가해보겠다. ```html ``` 다시 브라우저를 실행해보겠다. (이미지: defer 시 스크립트 파일을 동시에 다운로드 함. async와 다르게 코드 순서대로 실행) 브라우저는 두 스크립트를 40ms쯤 동시에 다운로드 시작한다. DOM이 만들어진 후 코드에 작성된 순서대로 big-script를 먼저, small-script를 나중에 실행한다. `defer`는 빨리 다운로드되더라도 코드 순서를 지켜서 실행한다. (이미지: 동일하게 총 3초 정도 걸리며 순서대로 실행됨을 확인할 수 있음.) `defer`는 서로 의존적인 스크립트에 적합한다. webpack 같은 번들러는 chunk라고 부르는 작은 자바스크립트 파일들로 애플리케이션을 분할한다. 이 chunk들은 의존성 때문에 순서대로 실행되어야 한다. 그래서 [webpack이 HTML에 chunk를 추가](https://webpack.js.org/guides/code-splitting/#prefetchingpreloading-modules)할 때 `defer` 속성을 사용한다. ## 핵심 정리 `defer` 속성은 스크립트를 병렬로 다운로드하되, DOM 생성 후 코드에 정의된 순서대로 실행한다. 서로 의존적인 스크립트나 webpack chunk 파일에 적합한다. *** ## 5. Preload 링크 HTTP 요청이 필요한 리소스는 자바스크립트뿐만이 아닙니다. 글꼴, 스타일시트, 이미지도 서버에서 다운로드해야 한다. `preload` 속성을 사용하면 이런 리소스들을 미리 다운로드할 수 있다. 이미지를 동적으로 로드하는 예제를 만들어보겠다. ```html ``` server.js에서 goguma.jpg 응답을 1초 지연시켜보겠다. ```js const handler = (req, res) => { // filename 가져오기 const filename = path.basename(req.url); if (filename === 'goguma.jpg') { // 1초 후 응답 res.delayMs = 1_000; } static(path.join(__dirname, 'public'))(req, res); }; ``` 서버를 실행하면 버튼이 나타나고, 클릭하면 1초 후에 이미지가 표시된다. (이미지: 버튼 클릭 후 1초 후에 고구마 이미지가 보일 것이다.) 이미지가 크면 사용자는 버튼 클릭 후 오래 기다려야 한다. `preload`를 사용하면 이미지를 미리 다운로드해서 즉시 표시할 수 있다. head 태그에 다음과 같이 추가한다. ```html ``` 브라우저는 이 태그를 만나면 파싱을 멈추지 않고 리소스를 동시에 다운로드한다. (이미지: 미리 이미지를 preload 함) 버튼 클릭 전에 이미지가 미리 다운로드되어, 클릭하면 즉시 표시된다. `preload`는 이미지, 비디오, 스타일시트, 폰트, 자바스크립트 등 모든 리소스에 사용할 수 있다. ## 핵심 정리 `preload`는 현재 페이지에서 곧 사용될 중요한 리소스를 미리 다운로드하여 실제 사용 시점의 로딩 시간을 제거한다. *** ## 6. Prefetch 링크 `preload`로 현재 페이지의 리소스 로딩을 최적화했다. `prefetch`는 다음 페이지의 리소스를 미리 다운로드한다. 사용자가 이동할 가능성이 높은 페이지를 개발자가 예측해서 설정한다. 하이퍼링크를 추가해보겠다. ```html Goguma들이 모인 Page ``` goguma.html 파일을 만들어보겠다. ```html Goguma들이 모인 페이지

    Goguma들이 모인 페이지

    ``` 서버 핸들러에서 3초 지연과 Firefox를 위한 캐시 헤더를 추가한다. ```js if (filename === 'goguma.html') { // 3초 후 응답 res.delayMs = 3_000; // prefetch를 위한 캐싱 헤더 추가 // Firefox는 prefetch하기 위해 캐싱 헤더가 필요함 res.setHeader('Cache-Control', 'max-age=3600'); } ``` 서버를 다시 실행해보겠다. (이미지: Goguma들이 모인 Page 버튼이 보임) 링크를 클릭하면 3초 후에 페이지가 표시된다. (이미지: 클릭 후 3초 후에 Goguma들이 모인 페이지가 보임) 페이지가 크거나 응답이 느리면 사용자는 오래 기다려야 한다. `prefetch`로 다음 페이지를 미리 다운로드할 수 있다. ```html ``` 브라우저는 유휴 시간에 `prefetch`로 설정한 파일을 다운로드한다. (이미지: 이제 다음 페이지의 자원을 미리 다운로드 함) 이제 3초 지연 없이 즉시 페이지가 표시된다. 브라우저가 유휴 시간에 미리 다운로드했기 때문입니다. `prefetch`는 브라우저 호환성에 제한이 있다. (이미지: prefetch는 can i use를 보면 브라우저별 제한이 있음) Firefox는 캐시 헤더가 필요하고, Chrome은 별도 설정 없이 동작한다. [Can I Use에서 브라우저 호환성](https://caniuse.com/link-rel-prefetch)을 확인하세요. [Next.js](https://nextjs.org/docs/api-reference/next/link), [Gatsby](https://www.gatsbyjs.com/docs/how-to/performance/link-prefetching/), webpack 등 많은 프레임워크가 `prefetch`를 활용한다. webpack에서는 주석으로 간단히 설정할 수 있다. ```js import(/* webpackPrefetch: true */ './path/to/LoginModal.js'); ``` 빌드 시 자동으로 link prefetch 태그를 추가한다. Next.js의 Link 컴포넌트도 prefetch를 기본 제공한다. ## 핵심 정리 `prefetch`는 다음 페이지에서 사용될 리소스를 유휴 시간에 미리 다운로드한다. 브라우저 호환성을 확인하고, 다음 페이지 예측이 가능한 경우에 사용하면 효과적입니다. *** ## 7. 이미지 지연 로딩 이미지가 많으면 그만큼 HTTP 요청이 늘어나 로딩이 느려집니다. 여러 이미지를 로드하는 예제를 만들어보겠다. ```html 고구마1 이미지 고구마2 이미지 ``` 서버 핸들러에서 두 이미지 모두 1초씩 지연시킵니다. ```js const handler = () => { if (filename === 'goguma.jpg') { // 1초 후 응답 res.delayMs = 1_000; } if (filename === 'goguma2.jpg') { // 1초 후 응답 res.delayMs = 1_000; } }; ``` 두 번째 이미지를 뷰포트 밖으로 밀어내보겠다. ```html 고구마1 이미지
    빈 박스
    고구마2 이미지 ``` 두 번째 이미지는 뷰포트 밖에 있어 보이지 않다. (이미지: 2번째 고구마 이미지는 뷰포트 밖으로 밀려나서 보이지 않음, 굳이 이걸 로딩할 필요가 있을까?) 네트워크 탭을 보면 두 이미지 모두 다운로드됐다. 사용자가 보지 않을 수도 있는 두 번째 이미지까지 다운로드하는 것은 비효율적입니다. 뷰포트 밖의 이미지는 스크롤할 때 로드하면 된다. 이미지 태그에 `loading` 속성을 추가해보겠다. ```html 고구마1 이미지
    빈 박스
    고구마2 이미지 ``` `loading` 속성의 기본값은 `eager`로, 모든 이미지를 즉시 다운로드한다. ```html 고구마1 이미지
    빈 박스
    고구마2 이미지 ``` `lazy`로 변경하면 뷰포트에 들어올 때만 이미지를 다운로드한다. (이미지: 뷰포트 안에 들어올 때 HTTP 요청을 만듬) 첫 번째 이미지만 로드되고, 두 번째 이미지는 스크롤해서 뷰포트에 가까워질 때 로드된다. 이미지가 많은 사진첩이나 블로그, 특히 모바일 환경에서 효과적입니다. ## 핵심 정리 이미지 태그의 `loading="lazy"` 속성을 사용하면 뷰포트에 들어올 때만 이미지를 로드하여 초기 렌더링 성능을 크게 개선할 수 있다. *** ## 마치며 이번 포스팅에서는 브라우저의 렌더링 과정과 최적화 기법들을 알아보았다. 웹 페이지 성능은 사용자 경험에 직접적인 영향을 미친다. 로딩 시간이 1초 늘어날 때마다 전환율이 감소한다는 연구 결과도 있다. 이러한 최적화 기법들을 적절히 활용하면 웹 페이지의 로딩 성능을 크게 개선할 수 있다. 특히 모바일 환경이나 네트워크가 느린 환경에서 더욱 효과적이다. ## 핵심 정리 * **Critical Rendering Path**: 파싱 → DOM/CSSOM → 렌더 트리 → 레이아웃 → 페인팅의 5단계 * **script 태그 최적화**: * 일반 script: 파싱 차단, 다운로드 및 실행 후 재개 * `async`: 파싱과 병렬 다운로드, 다운로드 완료 시 즉시 실행 * `defer`: 파싱과 병렬 다운로드, 파싱 완료 후 실행 (순서 보장) * **리소스 프리로딩**: * ``: 현재 페이지에서 곧 필요한 리소스 미리 다운로드 * ``: 다음 페이지에서 사용할 리소스 유휴 시간에 다운로드 * **이미지 최적화**: `loading="lazy"`로 뷰포트 외부 이미지 지연 로드 * **선택 기준**: * async: 독립적인 스크립트 (분석 도구, 광고) * defer: DOM 의존 스크립트, 순서 중요 * preload: 즉시 필요한 중요 리소스 * prefetch: 다음 페이지 리소스 **렌더링 최적화는 마치 교통 신호를 조절하는 것과 같다. 중요한 차량(리소스)은 빠르게 통과시키고, 덜 급한 차량은 나중에 보내면 전체 흐름이 빨라진다.** **참고 자료**: * [MDN - 리소스 힌트](https://developer.mozilla.org/ko/docs/Web/HTML/Attributes/rel/preload) * [Google Web.dev - 리소스 우선순위 지정](https://web.dev/articles/prioritize-resources) * [webpack Prefetch 공식 문서](https://webpack.js.org/guides/code-splitting/#prefetchingpreloading-modules) --- # 악명 높은 CORS(교차 출처 리소스 공유) 쉽게 이해하기 > CORS(Cross-Origin Resource Sharing)는 브라우저에서 다른 출처에 있는 리소스를 사용할 수 있는 규칙이다. 지난 장에서 살펴본 것처럼 브라우저의 동일 출처 정책(Same-Origin Policy)으로 인해 출처가 다른 리소스에 접근할 수 없는 상황에 직면하... - 원문: https://www.yolog.co.kr/post/http-cors - 카테고리: HTTP - 발행: 2025-09-23 - 수정: 2025-09-23 ## CORS란? `CORS(Cross-Origin Resource Sharing)`는 브라우저에서 다른 출처에 있는 리소스를 사용할 수 있는 규칙이다. (이미지: CORS) 지난 장에서 살펴본 것처럼 브라우저의 `동일 출처 정책(Same-Origin Policy)`으로 인해 출처가 다른 리소스에 접근할 수 없는 상황에 직면하게 된다. 이번 장에서는 CORS의 원리와 문제 상황, 그리고 이를 해결할 수 있는 방법을 알아본다. ### 핵심 용어 정리 #### 1. 출처(Origin) URL의 프로토콜, 호스트, 포트 세 가지를 조합한 것을 출처라고 한다. * 이 세 가지가 **모두 같으면** 출처가 같다고 표현한다 * 하나라도 **다르면** 출처가 다르다고 표현한다 #### 2. 교차 출처 요청(Cross-Origin Request) 다른 출처의 자원을 사용하기 위해 네트워크 요청을 만드는 것을 말한다. 마치 다른 동네에 있는 편의점에 가서 물건을 사려는 것과 같다. 내가 사는 동네가 아니기 때문에, 그 편의점 주인이 "당신에게 팔아도 되나요?"라고 먼저 확인하는 것이다. 브라우저는 실행 중인 애플리케이션의 출처와 다른 출처의 자원을 요청하면 이를 차단한다. 앞서 공부한 `동일 출처 정책`이 동작하기 때문이다. 이를 허용하려면 서버와 특별한 약속을 지켜야 하는데, 그것이 바로 `CORS`다. *** ## CORS의 동작 원리 간단하게 DOM이 생성되면 스크립트를 실행시켜본다. ```ts const init = async () => { // DOM이 만들어지면 init 함수를 실행한다 const response = await fetch('/resource.json'); const data = await response.text(); const jsonElement = document.createElement('pre'); jsonElement.textContent = data; document.body.appendChild(jsonElement); }; document.addEventListener('DOMContentLoaded', init); ``` ```js const http = require('http'); const path = require('path'); const static = require('../shared/serve-static'); const handler = (req, res) => { static(path.join(__dirname, 'public'))(req, res); }; const server = http.createServer(handler); server.listen(8080, () => console.log('server is running ::8080')); ``` (이미지: 제대로 데이터를 받아오는 사진) 실제로 서버를 실행하고 `localhost:8080`으로 접속하면 `GET http://localhost:8080/resource.json` 네트워크 요청을 만들고, 응답값인 JSON 문자열을 화면에 출력한다. ### 교차 출처 요청 테스트 이제는 교차 출처 요청을 만들 차례다. 브라우저에서 실행되는 애플리케이션은 `8080`번 포트에서 자원을 가져온다. 이번에는 `8081`번 포트를 사용해서 다른 출처로 서버를 하나 만들어본다. 먼저 서버 코드에서 포트를 외부 인자로 받도록 수정한다: ```js const http = require('http'); const path = require('path'); const static = require('../shared/serve-static'); const handler = (req, res) => { static(path.join(__dirname, 'public'))(req, res); }; const server = http.createServer(handler); const port = process.env.PORT || 8080; server.listen(port, () => console.log(`server is running ::${port}`)); ``` 이제 서버를 두 번 실행시켜준다: ```bash node server # 8080번 포트로 실행 PORT=8081 node server # 8081번 포트로 실행 ``` 브라우저에서 실행되는 스크립트를 수정하여 `localhost:8081`로 다른 출처에 요청을 보내본다: ```ts const init = async () => { // 8081번 포트로 요청을 보냄 const response = await fetch('http://localhost:8081/resource.json'); const data = await response.text(); const jsonElement = document.createElement('pre'); jsonElement.textContent = data; document.body.appendChild(jsonElement); }; document.addEventListener('DOMContentLoaded', init); ``` 이제 `localhost:8080`에 접속해본다. (이미지: 요청은 보냈고, 응답도 받았지만, 스크립트에는 응답 본문을 사용할 수 없음이라고 표기) `8081`번 포트로 요청을 보내고 응답도 받았지만, **스크립트에서 응답 본문을 사용할 수 없다**는 메시지가 표시된다. (이미지: 콘솔에서도 교차 출처 요청 차단이라는 경고 문구 표시) #### CORS 에러 분석 콘솔을 확인하면 "교차 출처 요청 차단"이라는 경고가 표시된다. `동일 출처 정책`으로 인해 `8080`번 포트가 아닌 `8081`번 포트를 사용하는 서버의 리소스가 차단된 것이다. 원인은 [`Access-Control-Allow-Origin`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) CORS 헤더가 없기 때문이다. 브라우저는 다른 출처로 요청을 보낼 때: 1. 응답 헤더 중 `Access-Control-Allow-Origin`을 확인한다 2. 이 헤더에 **현재 출처가 포함되어 있는지** 검사한다 3. 서버가 해당 출처를 **허용했는지** 판단한다 서버 `8081`은 아직 이에 대해 명시하지 않았기 때문에, 브라우저는 자원 사용을 허용하지 않은 것으로 판단하여 네트워크 오류를 발생시킨 것이다. ### CORS 헤더 설정하기 서버 `8081`이 다른 출처에게 자원을 공유하려면 `Access-Control-Allow-Origin` 헤더를 설정해야 한다. 서버 코드를 수정해본다: ```js const handler = (req, res) => { // localhost:8080 출처를 허용 res.setHeader('Access-Control-Allow-Origin', 'http://localhost:8080'); static(path.join(__dirname, 'public'))(req, res); }; ``` 다시 서버를 두 개 실행해본다: (이미지: 정상적으로 데이터를 서버로부터 받아오는 사진) 이번에는 정상적으로 네트워크 요청이 전송되었다. 서버 `8081`로 요청을 보냈고, 응답도 받았으며, 브라우저가 이 응답을 차단하지도 않았다. 그 이유는 응답 헤더의 `Access-Control-Allow-Origin`에 현재 애플리케이션이 실행되는 `localhost:8080`이 명시되어 있기 때문이다. 브라우저는 "서버가 `8080`번 포트의 출처도 이 자원을 사용할 수 있다고 허락했구나"라고 판단하여 응답 사용을 허용한 것이다. *** ## 단순 요청(Simple Request) 교차 출처 요청 중에도 특정 조건을 만족하는 요청을 `단순 요청(Simple Request)`이라고 부른다. ### 단순 요청의 조건 단순 요청이 되기 위해서는 **두 가지 조건**을 만족해야 한다: #### 1. 허용된 HTTP 메소드 사용 * [`GET`](https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/GET) * [`POST`](https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/POST) * [`HEAD`](https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/HEAD) #### 2. 안전한 헤더 사용 교차 출처 요청에서 사용할 수 있는 헤더를 **안전한 헤더**라고 한다. 방금 우리가 사용한 `GET` 메소드는 단순 요청에 해당한다. 브라우저는 다른 출처의 자원을 사용하기 위해 HTTP 요청을 만들 때 [`Origin`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Origin) 헤더에 현재 출처를 실어서 보낸다. (이미지: 요청 헤더의 Origin에 이 애플리케이션을 실행한 URL이 담겨있음을 확인할 수 있는 사진) 요청 헤더의 `Origin`에 현재 애플리케이션이 실행된 URL이 담겨있는 것을 확인할 수 있다. 이것이 바로 **현재 출처**다. 브라우저가 서버에게 "나의 출처는 이곳이니, 당신의 자원을 사용해도 되나요?"라고 묻는 것이다. 서버는 자원을 제공하겠다는 의미로 응답 헤더에 `Access-Control-Allow-Origin`을 포함시킨다: (이미지: Access-Control-Allow-Origin 여기에 내 출처를 실어준다.) 응답을 받은 브라우저는 이 헤더에 **자신의 출처가 포함되어 있는지** 확인한다. 포함되어 있다면 "서버가 자원 사용을 허락했다"고 판단하여 응답을 사용한다. ### 안전한 헤더 목록 (이미지: CORS 허용 목록에 있는 요청 헤더) 안전한 헤더 목록: * [`Accept`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept) * [`Accept-Language`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept-Language) * [`Content-Language`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Content-Language) * [`Content-Type`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Content-Type) * [`Range`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Range) > **참고 자료**: [MDN - CORS 안전한 요청 헤더](https://developer.mozilla.org/ko/docs/Glossary/CORS-safelisted_request_header) 브라우저에서 교차 출처 요청을 할 때 **이외의 헤더를 사용**하면, 출처 확인과 마찬가지로 **헤더 사용 여부**도 서버에게 확인받아야 한다. #### 커스텀 헤더 테스트 브라우저에서 동작하는 스크립트에 커스텀 헤더를 추가해본다: ```ts const init = async () => { const response = await fetch('http://localhost:8081/resource.json', { // 안전하지 않은 헤더를 보냄 headers: { 'X-Goguma': 'goguma', }, }); const data = await response.text(); const jsonElement = document.createElement('pre'); jsonElement.textContent = data; document.body.appendChild(jsonElement); }; document.addEventListener('DOMContentLoaded', init); ``` 브라우저를 새로고침하면 다음과 같은 에러가 발생한다: (이미지: 커스텀 헤더를 보냈지만, 동일 출처 정책으로 인해 응답을 받을 수 없음) `동일 출처 정책`으로 인해 원격 리소스가 차단되었다. [`Access-Control-Allow-Headers`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Access-Control-Allow-Headers)에 헤더 `X-Goguma`가 허용되지 않았다고 표시된다. #### 커스텀 헤더 허용하기 안전하지 않은 헤더를 사용하려면 서버가 `Access-Control-Allow-Headers` 응답 헤더에 허용할 헤더 이름을 명시해야 한다: ```js const handler = (req, res) => { res.setHeader('Access-Control-Allow-Origin', 'http://localhost:8080'); // X-Goguma 헤더를 허용 res.setHeader('Access-Control-Allow-Headers', 'X-Goguma'); static(path.join(__dirname, 'public'))(req, res); }; ``` 서버를 재시작하면 이제 정상적으로 요청이 처리된다: (이미지: 제대로 응답을 받을 수 있는 사진) 요청 헤더에 `X-Goguma`가 정상적으로 포함되어 전송된 것을 확인할 수 있다. *** ## 사전 요청(Preflight Request) 단순한 요청에 해당하는 `GET`, `POST`, `HEAD` 메소드가 아닌 `PUT`, `PATCH`, `DELETE` 메소드를 사용하는 경우가 있다. 이런 경우 서버는 "요청을 보낸 측이 브라우저가 아닐 수도 있다"고 판단한다. 따라서 브라우저와 서버는 서로를 확인하기 위한 **사전 요청**을 먼저 주고받는다. 이를 `사전 요청(Preflight Request)`이라고 부른다. 마치 중요한 회의 전에 사전 미팅으로 서로를 확인하는 것과 같다. ### PUT 메소드로 사전 요청 테스트 브라우저에서 동작하는 스크립트의 메소드를 [`PUT`](https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/PUT)으로 변경해본다: ```ts const init = async () => { // PUT 메소드로 요청 const response = await fetch('http://localhost:8081/resource.json', { method: 'PUT', }); const data = await response.text(); const jsonElement = document.createElement('pre'); jsonElement.textContent = data; document.body.appendChild(jsonElement); }; document.addEventListener('DOMContentLoaded', init); ``` 브라우저에서 다음과 같은 오류가 발생한다: (이미지: 동일 출처 정책으로 인해 8080에 있는 리소스를 차단했다. Access-Control-Allow-Methods에 PUT 메소드가 없다고 출력한다.) `동일 출처 정책`으로 인해 리소스가 차단되었으며, [`Access-Control-Allow-Methods`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Access-Control-Allow-Methods)에 `PUT` 메소드가 없다고 표시된다. 네트워크 탭을 확인하면 더 자세한 정보를 볼 수 있다: (이미지: 네트워크 탭에도 오류가 발생함) #### Preflight 요청 분석 사전 요청은 다음과 같은 특징을 가진다: * **메소드**: [`OPTIONS`](https://developer.mozilla.org/ko/docs/Web/HTTP/Methods/OPTIONS)를 사용 * **URL**: 실제 요청과 동일한 주소 (`resource.json`) * **요청 헤더**: [`Access-Control-Request-Method`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Access-Control-Request-Method)에 사용하려는 메소드(`PUT`)를 명시 브라우저는 "교차 출처로 `PUT` 메소드를 사용해도 되나요?"라고 서버에게 먼저 확인하는 것이다. ### PUT 메소드 허용하기 서버가 다른 출처에서 `PUT` 메소드를 허용하려면 `Access-Control-Allow-Methods` 응답 헤더를 설정해야 한다: ```js const handler = (req, res) => { res.setHeader('Access-Control-Allow-Origin', 'http://localhost:8080'); res.setHeader('Access-Control-Allow-Headers', 'X-Goguma'); // PUT 메소드를 허용 res.setHeader('Access-Control-Allow-Methods', 'PUT'); static(path.join(__dirname, 'public'))(req, res); }; ``` 서버를 재시작하면 정상적으로 동작한다: (이미지: PUT 요청 응답을 브라우저에서 허용해줌) #### 사전 요청과 실제 요청의 흐름 1. **사전 요청(OPTIONS)**: * 요청: `Access-Control-Request-Method: PUT` * 응답: `Access-Control-Allow-Methods: PUT` * 서버가 `PUT` 메소드 사용을 허용함을 알림 2. **실제 요청(PUT)**: (이미지: 실제로 PUT 요청이 보내지고, 응답 본문이 실려옴) 실제 `PUT` 요청이 전송되고, 응답 본문도 정상적으로 수신되었다. 브라우저는 "서버가 `PUT` 메소드를 허용했구나"라고 판단하여 애플리케이션에서 응답을 사용할 수 있도록 허용한 것이다. ### 사전 요청 캐싱 매번 `OPTIONS` 메소드를 사용하는 사전 요청을 보내는 것은 **네트워크 비용이 추가로 발생**한다. 이를 최적화하기 위해 브라우저는 사전 요청의 응답을 **캐시**할 수 있다. [`Access-Control-Max-Age`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Access-Control-Max-Age) 헤더를 설정하면 된다: ```js const handler = (req, res) => { res.setHeader('Access-Control-Allow-Origin', 'http://localhost:8080'); res.setHeader('Access-Control-Allow-Headers', 'X-Goguma'); res.setHeader('Access-Control-Allow-Methods', 'PUT'); // 10초 동안 사전 요청 결과를 캐시 res.setHeader('Access-Control-Max-Age', '10'); static(path.join(__dirname, 'public'))(req, res); }; ``` 서버를 재시작한 후 테스트해본다: #### 첫 번째 요청 (이미지: 첫 요청은 당연히 캐싱한 데이터가 없으므로 OPTIONS 요청이 날라감) 처음에는 `OPTIONS` 사전 요청이 발생한다. #### 10초 이내 재요청 (이미지: 10초 이내의 요청은 당연히 캐싱한 데이터가 있으므로 OPTIONS 요청이 날라가지 않음) 10초 이내에 다시 요청하면 `OPTIONS` 요청이 **생략**된다. 캐시된 사전 요청 결과를 사용하기 때문이다. 10초가 지나면 캐시가 만료되어 다시 사전 요청이 발생한다. *** ## CORS를 사용하는 요청들 CORS를 사용하는 요청은 특정 API와 리소스에 한정된다. (이미지: CORS를 사용하는 요청) ### 주요 CORS 사용 요청 * [`Fetch API`](https://developer.mozilla.org/ko/docs/Web/API/Fetch_API): 우리가 다룬 fetch 함수 * [`XMLHttpRequest(XHR)`](https://developer.mozilla.org/ko/docs/Web/API/XMLHttpRequest): 비동기 HTTP 요청 * [`@font-face`](https://developer.mozilla.org/ko/docs/Web/CSS/@font-face): CSS에서 웹 폰트를 로드할 때 * [`WebGL 텍스처`](https://developer.mozilla.org/ko/docs/Web/API/WebGL_API): 다른 도메인의 이미지를 텍스처로 사용할 때 * [`Canvas drawImage`](https://developer.mozilla.org/ko/docs/Web/API/CanvasRenderingContext2D/drawImage): 다른 출처의 이미지를 캔버스에 그릴 때 > **참고 자료**: [MDN - 어떤 요청이 CORS를 사용합니까?](https://developer.mozilla.org/ko/docs/Web/HTTP/Guides/CORS#%EC%96%B4%EB%96%A4_%EC%9A%94%EC%B2%AD%EC%9D%B4_cors%EB%A5%BC_%EC%82%AC%EC%9A%A9%ED%95%A9%EB%8B%88%EA%B9%8C) ### 웹 폰트 CORS 테스트 웹 폰트를 통해 CORS가 어떻게 동작하는지 확인해본다: ```html ``` 실행 결과, `동일 출처 정책`으로 인해 `http://localhost:8081/myfont.otf`가 차단된다. 웹 폰트도 CORS를 사용하는 자원이므로, 다른 출처에서 폰트를 로드하려면 서버에서 적절한 CORS 헤더를 설정해야 한다. *** ### 마치며 CORS는 웹 보안의 핵심 메커니즘으로, 브라우저가 다른 출처의 리소스를 안전하게 사용할 수 있도록 한다. ### 핵심 정리 * **출처(Origin)**: 프로토콜, 호스트, 포트 세 가지를 조합한 것 * **단순 요청**: GET, POST, HEAD 메소드와 안전한 헤더만 사용하는 요청 * **사전 요청**: PUT, PATCH, DELETE 같은 메소드나 커스텀 헤더를 사용할 때 먼저 확인하는 OPTIONS 요청 * **CORS 헤더**: * `Access-Control-Allow-Origin`: 허용할 출처 지정 * `Access-Control-Allow-Methods`: 허용할 메소드 지정 * `Access-Control-Allow-Headers`: 허용할 헤더 지정 * `Access-Control-Max-Age`: 사전 요청 결과 캐시 시간 * **보안과 편의성의 균형**: CORS는 보안을 위해 필요하지만, 개발 시 불편함을 초래할 수 있다. 개발 환경과 프로덕션 환경에서 적절한 CORS 정책을 설정하는 것이 중요하다. --- # 웹 보안의 핵심, Same Origin Policy(동일 출처 정책) 쉽게 이해하기 > Same Origin Policy(SOP)는 브라우저가 자체적으로 적용하는 핵심 보안 메커니즘이다. CSP(Content Security Policy)가 서버에서 정책을 설정하고 브라우저가 수행하는 보안 시스템이라면, SOP(Same Origin Policy)는 브라우저가 스스로... - 원문: https://www.yolog.co.kr/post/http-same-origin-policy - 카테고리: HTTP - 발행: 2025-09-22 - 수정: 2025-09-22 ## Same Origin Policy(동일 출처 정책)란? `Same Origin Policy(SOP)`는 브라우저가 자체적으로 적용하는 핵심 보안 메커니즘이다. (이미지: Same Origin Policy) [`CSP(Content Security Policy)`](https://www.yolog.co.kr/post/http-content-security-policy)가 서버에서 정책을 설정하고 브라우저가 수행하는 보안 시스템이라면, `SOP(Same Origin Policy)`는 **브라우저가 스스로 자원의 출처를 관리하는 정책**이다. 이 정책의 목적은 악의적인 웹사이트가 사용자 데이터를 무단으로 접근하거나 유출하는 것을 방지하는 것이다. 예를 들어, [`Session Hijacking(세션 하이재킹)`](https://www.yolog.co.kr/post/security-session-hijacking)처럼 사용자가 로그인한 세션 쿠키를 다른 사이트로 보내지 못하게 차단한다. 마치 아파트 출입구에서 단지 주민증을 확인하는 것과 같다. 같은 단지 주민만 들어갈 수 있고, 다른 곳에서 온 사람은 기본적으로 차단되는 것이다. *** ## SOP의 기본 원칙 `SOP(Same Origin Policy)`의 핵심 원칙은 간단하다: * **같은 출처의 자원만 접근 가능**: 웹 문서와 같은 출처의 자원만 로드할 수 있음 * **다른 출처의 자원은 기본적으로 차단**: 교차 출처 자원은 특별한 허가 없이 접근 불가 ### 출처(Origin)란 무엇인가? 출처는 다음 세 가지 요소의 조합으로 결정된다: * **프로토콜** (`http`, `https`) * **호스트** (도메인) * **포트** (`80`, `443`, `8080` 등) 이 세 가지가 모두 일치해야 **같은 출처**로 간주된다. > **참고 자료**: [MDN - Same-origin policy](https://developer.mozilla.org/ko/docs/Web/Security/Same-origin_policy) *** ## `Session Hijacking` 공격과 SOP 실제 공격 시나리오를 통해 `SOP(Same Origin Policy)`가 어떻게 보안을 강화하는지 살펴보겠다. (이미지: input에 악성 스크립트 주입) 위 코드에서 [`fetch`](https://developer.mozilla.org/ko/docs/Web/API/Fetch_API) 함수는 다른 출처의 사이트로 네트워크 요청을 보내려고 시도한다. **하지만 중요한 점은:** * 네트워크 요청은 전송되지만 * **응답 데이터는 사용할 수 없음** * 브라우저가 오류를 발생시킴 브라우저는 "동일 출처 정책으로 인해 `hacker.com`에 있는 원격 리소스를 차단했다"라는 오류 메시지를 표시한다. 이것이 바로 `SOP(Same Origin Policy)`가 동작하는 방식이다. *** ## SOP가 차단하는 리소스들 `SOP(Same Origin Policy)`는 **AJAX 호출**뿐만 아니라 다양한 리소스에 적용된다. ### 웹 폰트 차단 예시 HTML 문서 헤더에 다음과 같은 웹 폰트를 로드하는 코드를 추가해보겠다: ```js res.write(` `); ``` (이미지: 교차 출처 웹 폰트 차단 에러) 결과는 동일하다. "교차 출처 요청 차단" 오류가 발생하며, 브라우저는 "동일 출처 정책으로 인해 `MyCustomFont`에 있는 원격 리소스를 차단했다"라고 알려준다. ### SOP(Same Origin Policy)가 차단하는 주요 자원들 브라우저에서 **반드시 동일 출처에서만 사용해야 하는 자원들**: * [`fetch()`](https://developer.mozilla.org/ko/docs/Web/API/Fetch_API) API * [`XMLHttpRequest`](https://developer.mozilla.org/ko/docs/Web/API/XMLHttpRequest) * [`@font-face`](https://developer.mozilla.org/ko/docs/Web/CSS/@font-face) 웹 폰트 *** ## 교차 출처가 허용되는 리소스들 모든 리소스가 차단되는 것은 아니다. 웹의 기본적인 동작을 위해 **일부 리소스는 교차 출처 접근이 허용**된다: (이미지: 교차 출처로 삽입할 수 있는 리소스 예시) #### 허용되는 교차 출처 리소스 * **` ``` (이미지: 악성 스크립트 입력) ### CSP 차단 결과 분석 네트워크 탭을 확인하면 `hacker.com`으로 네트워크 요청이 발생하지 않은 것을 확인할 수 있다: (이미지: 네트워크 요청이 발생하지 않음) 브라우저 콘솔에는 **Content Security Policy** 경고가 표시된다. "다음 지시자를 위반했기 때문에 인라인 스크립트가 실행되지 않도록 차단했다"라는 메시지를 볼 수 있다. 이는 브라우저가 CSP 정책을 올바르게 이행한 것이다. 마치 건물 출입구의 보안 요원이 출입증이 없는 사람을 막는 것과 같다. 허가되지 않은 스크립트는 애초에 실행되지 않는다. #### 인라인 스타일도 차단됨 흥미로운 점은 인라인 스타일도 차단된다는 것이다: (이미지: 인라인 스타일이 적용되지 않도록 차단했다) 실제로 우리 문서에 있는 인라인 스타일(`width:600px`)도 제대로 적용되지 않는다: (이미지: width:600px이 있지만, 제대로 적용이 안되어 있을 것이다.) CSP는 인라인 스크립트뿐만 아니라 **인라인 스타일까지 차단**하여 보안을 강화한다. *** ## CSP 세부 설정하기 실제 서비스에서는 다른 출처의 리소스를 사용해야 하는 경우가 많다. 예를 들어 **CDN에서 제공하는 CSS 라이브러리**, **외부 이미지**, **폰트** 등은 다른 출처에서 가져오기 마련이다. CSP는 이런 상황을 고려하여 **자원 종류별로 보안 정책을 세분화**할 수 있다. ### CSP 정책 예시 #### 1. 기본 정책 - 자체 출처만 허용 ```http Content-Security-Policy: default-src 'self' ``` 모든 콘텐츠가 사이트 자체의 출처(하위 도메인 제외)에서만 오도록 설정한다. #### 2. 신뢰할 수 있는 도메인 추가 ```http Content-Security-Policy: default-src 'self' example.com *.example.com ``` 신뢰할 수 있는 도메인 및 하위 도메인의 콘텐츠를 허용한다. CSP가 설정된 도메인과 동일할 필요는 없다. #### 3. 리소스별 세분화된 정책 ```http Content-Security-Policy: default-src 'self'; img-src *; media-src example.org example.net; script-src userscripts.example.com ``` 이 정책의 의미: * **default-src 'self'**: 기본적으로 현재 출처(`matthew.com`)의 리소스만 허용 * **[`img-src`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Content-Security-Policy/img-src) \***: 이미지는 모든 출처에서 허용 * **[`media-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/media-src)**: 오디오/비디오는 `example.org`와 `example.net`에서만 허용 * **[`script-src`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)**: 자바스크립트는 `userscripts.example.com`에서만 허용 > **참고 자료**: CSP에 대한 더 자세한 정보는 [MDN - Content Security Policy](https://developer.mozilla.org/ko/docs/Web/HTTP/CSP)에서 확인할 수 있다. #### CSP 적용 시 주의사항 CSP를 너무 엄격하게 설정하면 정상적인 기능까지 제한될 수 있다. **실제 발생할 수 있는 문제들:** * **구글 애널리틱스** 같은 외부 분석 도구가 작동하지 않음 * **카카오맵**, **네이버맵** 등 외부 API가 차단됨 * **소셜 로그인** 버튼이 작동하지 않음 * **웹폰트**가 로드되지 않아 디자인이 깨짐 이는 마치 건물 보안을 강화한다고 모든 출입문을 막아버려서, 정작 직원들도 출입하지 못하는 상황과 같다. 따라서 CSP는 **단계적으로 적용**하면서 서비스에 미치는 영향을 **지속적으로 모니터링**해야 한다. *** ## CSP Report-Only 모드 CSP를 단계적으로 적용하기 위한 방법으로 **Report-Only 모드**가 있다. 이 모드에서는: 1. 브라우저가 정책 위반을 **진단만** 하고 2. 리소스 로드는 **차단하지 않고** 그대로 실행 3. 진단 결과를 **서버로 보고** 이를 통해 실제 서비스에 영향을 주지 않으면서 잠재적인 보안 위협을 파악할 수 있다. 마치 건물에 CCTV를 먼저 설치해서 출입 패턴을 분석한 다음, 그 데이터를 바탕으로 보안 규칙을 만드는 것과 같다. ### Report-Only 모드 설정하기 [`Content-Security-Policy-Report-Only`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) 응답 헤더를 사용한다: ```ts res.setHeader( 'Content-Security-Policy-Report-Only', "default-src 'self'; report-uri /report" ); ``` 이 설정은 정책 위반을 진단만 하고 실행은 허용한다. 대신 리포트를 `/report` 경로로 전송한다. ### 서버에서 리포트 받기 서버는 CSP 위반 리포트를 받을 준비를 해야 한다: ```ts const report = (req, res) => { let body = ''; req.on('data', (chunk) => { body = body + chunk.toString(); }); req.on('end', () => { // JSON 형태의 본문을 받는다 const report = JSON.parse(body); // 리포트를 출력한다 console.log('CSP Report:', report); res.end(); }); }; ``` 라우팅에 리포트 핸들러를 추가한다: ```ts const server = http.createServer((req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/product') return postProduct(req, res); if (pathname === '/login') return login(req, res); if (pathname === '/logout') return logout(req, res); if (pathname === '/report') return report(req, res); index(req, res); }); server.listen(8080, () => { console.log('Server is running on port 8080'); }); ``` ### Report-Only 모드 테스트 사이트에 접속하면 즉시 `/report` 경로로 리포트가 전달된다: (이미지: /report 경로로 리포트가 전달됨) #### 리포트 내용 분석 요청 본문에는 JSON 형식의 데이터가 포함된다. `effective-directive`를 보면 `style-src-elem`이라고 되어 있는데, 이는 **인라인 스타일이 정책을 위반**했다는 의미다. 서버 콘솔에서도 CSP 리포트를 확인할 수 있다: (이미지: 서버에서 보고서를 받아볼 수 있다.) #### Report-Only vs 일반 CSP의 차이 * **일반 CSP**: 진단하고 실행을 **차단** * **Report-Only**: 진단만 하고 실행은 **허용** Report-Only 모드에서는 인라인 스타일도 정상 동작하고, 심지어 악성 스크립트도 실행된다. ### 악성 스크립트 테스트 로그인 후 input에 아래 스크립트를 입력해본다: ```ts ``` (이미지: 스크립트가 주입이 됨을 확인할 수 있음 CSP가 진단만 하기 때문) 입력하면 `hacker.com`에 쿠키 값이 **실제로 유출**된다. Report-Only 모드는 진단만 하고 스크립트 실행은 허용하기 때문이다. 대신 이런 보안 위반 사항들이 서버로 리포트된다: (이미지: 서버에 쿠키 관련 리포트가 보고됨) *** ## 실제 서비스에서의 CSP 활용 ### Google의 CSP 사례 분석 CSP가 현업에서 어떻게 활용되는지 Google의 사례를 살펴본다. Google 문서를 요청하면 응답 헤더에 CSP 관련 헤더가 포함되어 있다: (이미지: 구글의 CSP 사례) Google은 **Report-Only 모드**를 사용하여 진단만 하고 리소스 로딩은 허용한다: (이미지: 구글의 CSP 리포트 보고서) #### Google의 접근 방식 분석 Google이 Report-Only를 사용하는 이유: * **보안 정책 위반 모니터링**: 실시간으로 잠재적 위협 감지 * **단계적 정책 적용**: 서비스에 영향을 주지 않으면서 정책 테스트 * **문제 사전 발견**: 실제 정책 적용 전 예상치 못한 문제 파악 *** ## CSP의 한계와 종합적인 보안 전략 ### CSP만으로는 충분하지 않다 CSP는 **크로스 사이트 스크립팅(XSS) 공격 방어**에는 효과적이지만, **CSRF와 같은 다른 유형의 공격**은 막지 못한다. 따라서 진정한 웹 보안을 위해서는 CSP와 함께 다양한 보안 조치를 종합적으로 적용해야 한다. ### 추가적인 보안 조치들 #### 1. 쿠키 보안 설정 * **[`SameSite`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Set-Cookie/SameSite) 속성**: CSRF 공격 방어 * **[`HttpOnly`](https://developer.mozilla.org/ko/docs/Web/HTTP/Cookies#httponly_%EC%BF%A0%ED%82%A4) 속성**: 클라이언트 측 스크립트의 쿠키 접근 차단 * **[`Secure`](https://developer.mozilla.org/ko/docs/Web/HTTP/Cookies#secure_%EC%BF%A0%ED%82%A4) 속성**: HTTPS 연결에서만 쿠키 전송 #### 2. 입력 데이터 검증 * **Sanitize**: 악성 코드 제거 * **Escape**: 특수 문자 이스케이프 처리 * **Validation**: 데이터 형식 및 범위 검증 #### 3. 추가 보안 헤더 * **[`X-Frame-Options`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Frame-Options)**: 클릭재킹 방어 * **[`X-Content-Type-Options`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/X-Content-Type-Options)**: MIME 타입 스니핑 방지 * **[`Strict-Transport-Security`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Strict-Transport-Security)**: HTTPS 강제 *** ### 마치며 끊임없이 새로운 보안 공격들이 개발되고 있기 때문에, 단일 보안 조치만으로는 충분하지 않다. `다층 방어(Defense in Depth)` 전략을 통해 여러 보안 계층을 구축하고, 기본적인 보안 지식을 바탕으로 꾸준히 학습하며 실무에 적용하는 것이 중요하다. ### 핵심 정리 * **CSP란**: XSS 공격을 방어하기 위한 HTTP 응답 헤더 기반 보안 메커니즘 * **기본 설정**: `Content-Security-Policy: default-src 'self'`로 현재 출처만 허용 * **세부 설정**: `script-src`, `img-src`, `style-src` 등으로 리소스별 정책 지정 가능 * **Report-Only 모드**: 정책 위반을 차단하지 않고 보고만 하여 단계적 적용 가능 * **종합적 보안**: CSP만으로는 부족하며, 쿠키 보안, 입력 검증, 추가 보안 헤더 등을 함께 적용해야 한다 **보안은 기능이 아니라 프로세스다.** 지속적인 모니터링, 업데이트, 그리고 개선이 필요한 영역이다. --- # React Router — History API를 활용한 SPA 라우팅 구현 > 리액트가 부드럽고 빠르게 화면을 전환하는 이유를 묻는다면 많은 사람들이 Single Page Application(SPA)를 떠올린다. 그리고 그 중심에는 언제나 라우터가 있다. 어떤 기능을 만들 때 "핵심을 먼저 정의하고 구현하는 습관"은 특히 사용자 경험(UX)이 중요한 서비스... - 원문: https://www.yolog.co.kr/post/react-spa - 카테고리: 개발 - 발행: 2025-09-16 - 수정: 2025-09-16 리액트가 부드럽고 빠르게 화면을 전환하는 이유를 묻는다면 많은 사람들이 `Single Page Application(SPA)`를 떠올린다. 그리고 그 중심에는 언제나 `라우터`가 있다. 어떤 기능을 만들 때 "핵심을 먼저 정의하고 구현하는 습관"은 특히 `사용자 경험(UX)`이 중요한 서비스 개발에서 큰 힘을 발휘한다. 이번 글에서는 `History API`를 활용해 "브라우저 주소에 맞는 화면을 제공하는 라우터"를 직접 만들어 보면서 React Router의 내부 동작 방식을 차근차근 이해해본다. 물론 잘 만들어진 라이브러리를 가져다 쓰는 것도 좋은 선택이지만, 원리를 알면 * 예상치 못한 문제 상황에서 유연하게 대응할 수 있고 * 서비스에 맞게 `커스터마이징`하여 더 나은 사용자 경험을 줄 수 있다 사실 처음 리액트를 배울 때는 `라이브러리를 빨리 적용하는 것`만 신경 썼다. 하지만 시간이 지나면서 깨달은 건 `"내부 동작 원리를 이해하는 습관"이 결국 더 단단한 개발 실력을 만든다`는 점이었다. 그래서 이제는 조금 더 천천히 메커니즘 자체를 파고드는 연습을 하고 있다. *** ## 웹 서비스의 발전과 History API의 등장 (이미지: History API) 웹은 원래 `문서와 문서가 링크로 연결된 구조`였다. 링크를 클릭하면 브라우저는 새로운 URL로 요청을 보내고, 서버가 새로운 HTML을 내려주면 화면 전체가 리렌더링됐다. 하지만 웹이 점점 애플리케이션화되면서 한계가 드러났다. * 매번 새 문서를 받아오니 속도가 느리고 * 동일한 리소스를 반복적으로 로드하며 * 화면 전환이 매끄럽지 않았다 이를 해결하기 위해 `HTML5에서 History API`가 등장했다. 이제는 `주소창의 URL은 바꾸되, 전체 리로드는 막고 필요한 부분만 교체`할 수 있게 된 것이다. *** ### pushState와 History Stack `history.pushState`는 브라우저의 `히스토리 스택(history stack)`에 새로운 상태를 쌓는 동작이다. 주소창은 바뀌지만, 네트워크 요청은 발생하지 않는다. 1. **초기 상태** ```markdown | /matthew | <- 현재 ``` 2. **pushState('/aeong') 호출** ```markdown | /aeong | <- 현재 | /matthew | ``` 3. **pushState('/joy') 호출** ```markdown | /joy | <- 현재 | /aeong | | /matthew | ``` 4. **뒤로가기 클릭 → popstate 이벤트 발생** ```markdown | /joy | | /aeong | <- 현재 | /matthew | ``` 즉 `pushState`는 새로운 경로를 스택에 추가하고, `뒤로가기/앞으로가기(popstate 이벤트)` 시에는 스택 항목이 사라지는 게 아니라 `현재 위치 포인터만 이동`한다. *** ## SPA 라우팅의 실제 동작 흐름 🎮 SPA 라우팅은 사실 단순한 트릭이다. * `링크 클릭 시` 1. 원래 서버에 요청하려는 동작을 `preventDefault()`로 막는다 2. `history.pushState()`로 주소창만 변경한다 3. “경로가 바뀌었어”라는 신호를 커스텀 이벤트로 앱에 전달한다 * `뒤로가기 / 앞으로가기 시` 1. 브라우저가 자동으로 URL을 바꾼다 2. `popstate` 이벤트가 발생한다 3. 이 이벤트를 감지해 화면을 교체한다 겉보기에는 여러 HTML 페이지를 오가는 것 같지만 실제로는 `한 페이지에서 주소와 컴포넌트만 바뀌는 것`이다. 덕분에 전체 리로드 없이 `빠르고 부드러운 전환`이 가능하다. ✨ *** ## 핵심 원칙 1. 경로마다 다른 화면을 보여주기 라우터의 본질은 간단하다. `URL 경로에 따라 다른 컴포넌트를 렌더링`하는 것. ```tsx const MatthewPage = () =>

    매튜 페이지

    ; const AeongPage = () =>

    애옹 페이지

    ; const JoyPage = () =>

    조이 페이지

    ; const NotFound = () =>

    Not Found

    ; function App() { const { pathname } = window.location; switch (pathname) { case '/matthew': return ; case '/aeong': return ; case '/joy': return ; default: return

    404

    ; } } export default App; ``` `window.location.pathname`을 읽어 요청된 주소와 맞는 컴포넌트를 보여줄 수 있다. (이미지: /matthew와 일치하는 컴포넌트를 보여줌) 일치하는 경로가 없다면 404 페이지를 내려준다. (이미지: /not-found는 일치하는 경로가 없어 404 페이지를 내려줌) *** ## 핵심 원칙 2. 페이지 이동 ### 전통적인 방식 ```tsx const Header = () => { return ( ); }; ``` `` 태그를 클릭하면 브라우저가 서버로 요청을 보내고 새로운 HTML 문서를 받아와 전체를 다시 렌더링한다. 즉 `라우팅의 주체는 서버`다. *** ### 우리가 원하는 방식 (SPA) SPA 라우팅은 `프론트엔드가 직접 URL을 제어`하고, 필요한 컴포넌트만 갈아끼운다. 이를 위해서는 크게 3가지 작업을 해주면 된다. 1. 서버 요청을 막고 2. `pushState()`로 URL만 바꾸며 3. 상태 변화를 감지해 리렌더링을 트리거 이를 위한 `Link` 구현은 다음과 같다: ```tsx import type { MouseEvent } from 'react'; import type { LinkProps } from './types'; import { getCurrentPath, navigateTo } from './utils'; export const Link = ({ to, children }: LinkProps) => { const handleClick = (e: MouseEvent) => { e.preventDefault(); if (getCurrentPath() === to) return; navigateTo(to); }; return ( {children} ); }; ``` *** ## 핵심 원칙 3. 경로를 상태로 관리하기 `window.location.pathname`은 값만 읽을 뿐 변경돼도 리렌더링을 유발하지 않는다. 따라서 경로를 `state로 관리`해야 한다. ```tsx const MatthewPage = () => { const path = useCurrentPath(); // 경로 변경 감지 return
    현재 경로: {path}
    ; }; ``` `useCurrentPath` 훅은 커스텀 이벤트(`PUSHSTATE_EVENT`, `POPSTATE_EVENT`)를 구독해 상태를 갱신한다. *** ## 핵심 원칙 4. 선언적이고 확장 가능해야 한다 경로마다 `if/switch` 문을 계속 늘리면 관리가 어렵다. 따라서 `Route`로 라우팅 테이블을 정의하고 `Router`가 매칭되는 경로를 찾아 렌더링하도록 만든다. ```tsx // Route.tsx export const Route = ({ component: Component }: RouteProps) => { return ; }; ``` ```tsx // Router.tsx export const Routes: FC = ({ children }) => { const currentPath = useCurrentPath(); const activeRoute = useMemo(() => { const routes = Children.toArray(children).filter(isRouteElement); return routes.find((route) => route.props.path === currentPath); }, [children, currentPath]); if (!activeRoute) return null; return cloneElement(activeRoute); }; ``` *** ## 실제 사용 예시 ```tsx import './App.css'; import { Link, Route, Routes } from './router'; const MatthewPage = () =>

    매튜 페이지

    ; const AeongPage = () =>

    애옹 페이지

    ; const JoyPage = () =>

    조이 페이지

    ; const NotFoundPage = () =>

    404

    ; const Header = () => { return ( ); }; function App() { return ( <>
    ); } export default App; ``` *** ## 마치며 실제로 지금까지 만든 라우터는 아래와 같이 잘 동작한다. (이미지: 내가 만든 라우터) 물론 실제 React Router는 훨씬 다양한 기능(중첩 라우팅, 동적 세그먼트, 데이터 로딩 등)을 제공하니 우리가 라이브러리를 사용한다. 하지만 이번 과정을 통해 SPA 라우팅의 원리를 직접 구현하며 체득할 수 있었다. ## 핵심 정리 * **History API의 등장**: HTML5에서 등장하여 전체 리로드 없이 URL만 변경 가능 * **pushState**: 히스토리 스택에 새로운 상태를 추가, 네트워크 요청 발생 안 함 * **popstate 이벤트**: 뒤로가기/앞으로가기 시 발생, 스택 포인터만 이동 * **SPA 라우팅 원리**: * Link 컴포넌트: preventDefault()로 새로고침 방지, pushState()로 URL 변경, 커스텀 이벤트로 알림 * Router 컴포넌트: pushstate/popstate 이벤트 감지, 현재 URL에 맞는 컴포넌트 렌더링 * **핵심 개념**: * `history.pushState()`: URL 변경 (네트워크 요청 X) * `popstate 이벤트`: 브라우저 뒤/앞으로 가기 감지 * `preventDefault()`: 기본 동작 방지 (페이지 새로고침) * 커스텀 이벤트: 앱 전역에 경로 변경 알림 * **React Router vs 직접 구현**: * React Router: 중첩 라우팅, 동적 세그먼트, 데이터 로딩 등 고급 기능 * 직접 구현: 핵심 원리 이해, 문제 상황 대응력 향상 **SPA 라우팅은 마치 책의 목차와 같다. 페이지를 넘기지 않고(새로고침 없이) 목차만 보고(URL만 변경) 원하는 내용으로 바로 이동할 수 있다.** *** --- # useState 대신 useReducer를 선택해야 하는 순간 > React 개발을 하다 보면 대부분의 상태 관리는 useState로 충분하다. 하지만 프로젝트가 커지고 단순한 컴포넌트여도 내부의 상태가 점점 복잡해질수록, useState만으로는 관리가 어려워지는 순간이 온다. 오늘은 실제 사내 서비스 개발 중 겪었던 문제를 사례로 들어, 왜 u... - 원문: https://www.yolog.co.kr/post/when-to-use-usestate-vs-usereducer - 카테고리: 개발 - 발행: 2025-09-13 - 수정: 2025-09-14 React 개발을 하다 보면 대부분의 상태 관리는 `useState`로 충분하다. 하지만 프로젝트가 커지고 단순한 컴포넌트여도 내부의 상태가 점점 복잡해질수록, `useState`만으로는 관리가 어려워지는 순간이 온다. (이미지: useState 대신 useReducer를 선택해야 하는 순간) 오늘은 실제 사내 서비스 개발 중 겪었던 문제를 사례로 들어, 왜 `useReducer`가 필요한지 이야기해보겠다. *** ## 언제 useReducer가 필요한가 `useReducer`를 사용해야 하는 시점은 명확하다. 1. 복잡한 상태 구조로 여러 하위 값들을 관리해야 할 때 2. 새로운 상태 값이 이전 상태를 기반으로 결정될 때 두 번째 상황이 특히 핵심이다. 이전 상태에 의존적인 복잡한 상태 변경은 `setState`의 개별적인 업데이트만으로는 안전하게 처리하기 힘들다. *** ## 실제 사례: NumberPad 컴포넌트 저희 사내 서비스의 금액 입력 패드(NumberPad) 큰 기능은 아래와 같은 요구사항을 가지고 있었다. (이미지: 실제 서비스와 대략적으로 비슷하게 동작하는 영상) * 숫자 패드를 통한 금액 입력 * 천 단위 콤마 자동 포맷팅 * 최소 금액(1,000원) / 최대 금액(10억 원) 검증 * 빠른 금액 입력 버튼 (+1만, +5만, +10만, +100만) * 입력 히스토리 관리 * 00으로 시작하는 입력 방지 언뜻 단순해 보이지만, 실제로는 상태 관리가 꽤나 복잡했다. 이를 `useState`로만 구현하면 무려 6개의 상태가 필요했다. ```tsx const [displayAmount, setDisplayAmount] = useState('0'); const [rawValue, setRawValue] = useState(''); const [isError, setIsError] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [history, setHistory] = useState([]); const [isFirstInput, setIsFirstInput] = useState(true); ``` *** ## 문제점 1. 상태 간 동기화 지옥 한 번의 사용자 액션이 6개의 상태 업데이트를 일으켰다. ```tsx const handleNumberClick = (num: string) => { let newRawValue; if (isFirstInput) { if (num === '0') return; // 0으로 시작 방지 newRawValue = num; setIsFirstInput(false); } else if (rawValue === '0') { newRawValue = num; // 0 다음 숫자는 교체 } else { if (rawValue.length >= 10) return; newRawValue = rawValue + num; } setRawValue(newRawValue); setDisplayAmount(formatWithComma(newRawValue)); const numValue = parseInt(newRawValue); if (numValue > MAX_AMOUNT) { setIsError(true); setErrorMessage('최대 금액 초과'); return; } // 히스토리 업데이트 누락 위험 const formatted = formatWithComma(newRawValue); if (history[history.length - 1] !== formatted) { setHistory([...history, formatted]); } }; ``` 여기서 발생하는 문제는: * 상태 업데이트 순서가 조금이라도 잘못되면 UI가 깨진다. * 상태들이 서로 강하게 얽혀 있어서, 하나를 빠뜨리면 예기치 못한 버그가 터진다. * `“displayAmount가 왜 이 값이지?”`라는 질문에 답하려면 모든 이벤트 핸들러 코드를 뒤져야 한다. *** ## 문제점 2. 일관성 없는 상태 관리 비슷한 목적의 함수조차 상태 업데이트 순서가 들쭉날쭉했다. ```tsx const handleDelete = () => { const newRawValue = rawValue.slice(0, -1); if (!newRawValue) { // 초기 상태로 리셋 setRawValue(''); setDisplayAmount('0'); setIsFirstInput(true); setIsError(false); setErrorMessage(''); } else { // 한 글자 삭제 setRawValue(newRawValue); setDisplayAmount(formatWithComma(newRawValue)); setIsError(false); setErrorMessage(''); } }; const handleClear = () => { setDisplayAmount('0'); setRawValue(''); setIsError(false); setErrorMessage(''); setIsFirstInput(true); }; ``` 두 함수 모두 "초기화"라는 목적을 가지지만, 상태 업데이트 순서와 처리 방식이 다르다. 이 작은 차이가 버그를 만들어낸다. > 이 문제를 useReducer로 해결한 방법은 [useReducer로 일관성 문제 해결하기](#usereducer로-일관성-문제-해결하기) 섹션을 참고하자. *** ## 문제점 3. 복잡한 규칙 관리의 어려움 추가로 이런 상황도 있었다: * **빠른 금액 버튼 처리의 복잡함** 사용자가 입력한 금액을 교체해야 하는데, 개발자가 실수로 덧셈으로 구현하거나, 각종 검증 로직을 빠뜨리는 경우가 자주 발생한다. 6개의 상태를 동시에 업데이트해야 하는데, `useState`로는 하나라도 놓치기 쉽다. ```tsx // useState로 구현한 빠른 금액 버튼 - 여러 버그 포함 const handleQuickAmount = (amount: number) => { // ❌ 버그 1: 덧셈 연산 (교체가 아닌 누적) const newAmount = parseInt(rawValue || '0') + amount; setRawValue(String(newAmount)); // ❌ 버그 2: 화면 표시 누락 // setDisplayAmount(formatWithComma(String(newAmount))); if (newAmount > MAX_AMOUNT) { setIsError(true); setErrorMessage('최대 금액 초과'); } // ❌ 버그 3: 히스토리 미기록 // ❌ 버그 4: 첫 입력 상태 미변경 }; ``` 이 코드의 문제점들: * **버그 1**: 빠른 금액 버튼(+1만, +5만 등)은 현재 금액을 "교체"해야 하는데 "덧셈"으로 구현되어 있다. 사용자가 "3,000원"을 입력한 상태에서 "+1만" 버튼을 누르면 "10,000원"이 되어야 하지만, 이 코드는 "13,000원"이 된다. * **버그 2**: `displayAmount` 업데이트가 누락되어 화면에 표시되는 금액과 실제 저장된 값이 달라집니다. * **버그 3**: 입력 히스토리가 기록되지 않아 undo 기능이나 입력 추적이 불가능한다. * **버그 4**: `isFirstInput` 플래그가 업데이트되지 않아 이후 숫자 입력 시 예상치 못한 동작이 발생할 수 있다. * **00 입력 방지와 첫 입력 처리** 첫 입력이 "00"일 때는 무시하지만, "1"을 입력한 후 "00" 버튼은 허용해야 한다. 더 심각한 문제는 개발자마다 이 로직을 다르게 구현한다는 점입니다. 어떤 곳에서는 "0" 입력을 막고, 어떤 곳에서는 허용하는 일관성 없는 동작이 발생했다. 이런 **컨텍스트에 따른 규칙**을 `useState`로 관리하면, 매번 다른 조건문이 생기고 버그의 온상이 된다. ```tsx // useState로 구현 - 일관성 없는 00 처리 const handleDoubleZero = () => { // 첫 입력이거나 0일 때 00 방지 if (isFirstInput || rawValue === '0') { return; } // 길이 체크 (임의의 조건) if (rawValue.length >= 9) { return; } const newValue = rawValue + '00'; setRawValue(newValue); setDisplayAmount(formatWithComma(newValue)); // ❌ isError, errorMessage, history, isFirstInput 업데이트 누락! }; // 다른 핸들러에서는 또 다른 방식으로 처리 - 일관성 없음 const handleNumberClick = (num: string) => { // 조건이 미묘하게 다름 (rawValue === '' vs isFirstInput) if (num === '0' && (isFirstInput || rawValue === '')) { return; // 단일 0도 막아버림 } // ... }; ``` *** ## useReducer로 해결하기 이럴 때는 `useReducer`가 답이다. `dispatch`로 "무엇을 할지(action)"만 전달하고, 상태 변경의 "어떻게(reducer)"는 한 곳에서 관리한다. ```tsx type NumberPadAction = | { type: 'INPUT_NUMBER'; payload: string } | { type: 'INPUT_DOUBLE_ZERO' } | { type: 'DELETE_DIGIT' } | { type: 'CLEAR' } | { type: 'SET_QUICK_AMOUNT'; payload: number } | { type: 'CONFIRM' }; interface NumberPadState { displayAmount: string; rawValue: string; isError: boolean; errorMessage: string; history: string[]; isFirstInput: boolean; } ``` 리듀서는 모든 상태를 일관성 있게 갱신한다. ```tsx export const numberPadReducer = ( state: NumberPadState, action: NumberPadAction ): NumberPadState => { switch (action.type) { case 'INPUT_NUMBER': { const { rawValue, displayAmount, error } = validateAndFormat( state.isFirstInput ? '' : state.rawValue, action.payload ); if (error) { return { ...state, isError: true, errorMessage: error }; } return { ...state, rawValue, displayAmount, isFirstInput: false, isError: false, errorMessage: '', history: [...state.history, displayAmount], }; } case 'SET_QUICK_AMOUNT': { const rawValue = action.payload.toString(); const displayAmount = formatWithComma(rawValue); return { ...state, rawValue, displayAmount, isFirstInput: false, isError: false, errorMessage: '', history: [...state.history, displayAmount], }; } case 'DELETE_DIGIT': { const newRawValue = state.rawValue.slice(0, -1); if (!newRawValue) { return { ...initialState, history: state.history }; } return { ...state, rawValue: newRawValue, displayAmount: formatWithComma(newRawValue), isError: false, errorMessage: '', }; } case 'CLEAR': return { ...initialState, history: state.history }; default: return state; } }; ``` 핸들러는 이제 간단해진다. ```tsx const [state, dispatch] = useReducer(numberPadReducer, initialState); const handleNumberClick = (num: string) => dispatch({ type: 'INPUT_NUMBER', payload: num }); const handleClear = () => dispatch({ type: 'CLEAR' }); ``` ### 컴포넌트 코드 비교: useState vs useReducer 실제 컴포넌트에서 사용할 때의 차이를 보면 더욱 명확해진다. useState를 사용한 컴포넌트 - 복잡하고 산만함: ```tsx function NumberPadComponent() { const [displayAmount, setDisplayAmount] = useState('0'); const [rawValue, setRawValue] = useState(''); const [isError, setIsError] = useState(false); const [errorMessage, setErrorMessage] = useState(''); const [history, setHistory] = useState([]); const [isFirstInput, setIsFirstInput] = useState(true); const handleNumberClick = (num: string) => { // 30줄 이상의 복잡한 로직... let newRawValue; if (isFirstInput) { if (num === '0') return; newRawValue = num; setIsFirstInput(false); } else if (rawValue === '0') { newRawValue = num; } else { if (rawValue.length >= 10) return; newRawValue = rawValue + num; } setRawValue(newRawValue); setDisplayAmount(formatWithComma(newRawValue)); const numValue = parseInt(newRawValue); if (numValue > MAX_AMOUNT) { setIsError(true); setErrorMessage('최대 금액 초과'); return; } const formatted = formatWithComma(newRawValue); if (history[history.length - 1] !== formatted) { setHistory([...history, formatted]); } }; const handleQuickAmount = (amount: number) => { // 또 다른 복잡한 로직... setRawValue(amount.toString()); setDisplayAmount(formatWithComma(amount.toString())); setIsFirstInput(false); setIsError(false); setErrorMessage(''); setHistory([...history, formatWithComma(amount.toString())]); }; const handleDelete = () => { // 삭제 로직도 복잡... const newRawValue = rawValue.slice(0, -1); if (!newRawValue) { setRawValue(''); setDisplayAmount('0'); setIsFirstInput(true); setIsError(false); setErrorMessage(''); } else { setRawValue(newRawValue); setDisplayAmount(formatWithComma(newRawValue)); setIsError(false); setErrorMessage(''); } }; const handleClear = () => { setDisplayAmount('0'); setRawValue(''); setIsError(false); setErrorMessage(''); setIsFirstInput(true); }; return ( <> ); } ``` useReducer를 사용한 컴포넌트 - 깔끔하고 명확함: ```tsx function NumberPadComponent() { const [state, dispatch] = useReducer(numberPadReducer, initialState); // 모든 핸들러가 한 줄로 끝! const handleNumberClick = (num: string) => dispatch({ type: 'INPUT_NUMBER', payload: num }); const handleQuickAmount = (amount: number) => dispatch({ type: 'SET_QUICK_AMOUNT', payload: amount }); const handleDelete = () => dispatch({ type: 'DELETE_DIGIT' }); const handleClear = () => dispatch({ type: 'CLEAR' }); return ( <> ); } ``` 차이점 요약: | 항목 | useState | useReducer | | ---------- | -------------- | ------------ | | 상태 선언 | 6개의 개별 상태 | 1개의 통합 상태 | | 핸들러 코드 | 각각 10-30줄 | 모두 1줄 | | 비즈니스 로직 위치 | 컴포넌트에 산재 | 리듀서에 집중 | | 컴포넌트 크기 | 100줄 이상 | 30줄 이하 | | 가독성 | 로직과 UI가 섞임 | UI에만 집중 가능 | | 테스트 범위 | 컴포넌트 전체 테스트 필요 | 리듀서만 테스트하면 됨 | 이렇게 `useReducer`를 사용하면 컴포넌트는 "무엇을 보여줄지"에만 집중하고, "어떻게 상태를 변경할지"는 리듀서가 담당하게 된다. 이것이 바로 관심사의 분리(Separation of Concerns)다. ### useReducer로 일관성 문제 해결하기 [앞서 언급한 초기화 함수의 일관성 문제](#문제점-2-일관성-없는-상태-관리)를 `useReducer`로 완벽하게 해결할 수 있다: ```tsx // 모든 초기화 로직이 리듀서 한 곳에 집중 case 'DELETE_DIGIT': { const newRawValue = state.rawValue.slice(0, -1); if (!newRawValue) { // CLEAR와 동일한 방식으로 초기화 - 일관성 보장 return { ...initialState, history: state.history }; } return { ...state, rawValue: newRawValue, displayAmount: formatWithComma(newRawValue), isError: false, errorMessage: '' }; } case 'CLEAR': return { ...initialState, history: state.history }; ``` 이제 상태 업데이트 순서를 고민할 필요가 없다. 모든 상태가 한 번에, 일관된 방식으로 업데이트되기 때문이다. *** ## useReducer로 얻은 이점 ### 1. 예측 가능한 상태 변경 * `useState` → 여러 곳의 함수를 뒤져야 원인을 찾음 * `useReducer` → 리듀서에서 해당 action만 보면 끝 ### 2. 완벽한 타입 안정성 ```tsx dispatch({ type: 'INPUT_NUMBER' }); // ❌ payload 필요 dispatch({ type: 'INPUT_NUMBER', payload: '1' }); // ✅ 정상 dispatch({ type: 'INVALID_ACTION' }); // ❌ 에러 ``` ### 3. 테스트 용이성 useState를 사용한 경우: ```tsx it('숫자 입력 시 천 단위 콤마 추가', () => { const { result } = renderHook(() => useNumberPad()); act(() => { result.current.handleNumberClick('1'); }); expect(result.current.displayAmount).toBe('1'); act(() => { result.current.handleNumberClick('0'); result.current.handleNumberClick('0'); result.current.handleNumberClick('0'); }); expect(result.current.displayAmount).toBe('1,000'); // 상태 간 동기화 검증이 복잡함 expect(result.current.rawValue).toBe('1000'); expect(result.current.isError).toBe(false); expect(result.current.history).toContain('1,000'); }); ``` useReducer를 사용한 경우: ```tsx it('숫자 입력 시 천 단위 콤마 추가', () => { let state = initialState; // 1 입력 state = numberPadReducer(state, { type: 'INPUT_NUMBER', payload: '1', }); expect(state.displayAmount).toBe('1'); expect(state.rawValue).toBe('1'); // 000 입력하여 1,000 만들기 ['0', '0', '0'].forEach((digit) => { state = numberPadReducer(state, { type: 'INPUT_NUMBER', payload: digit, }); }); // 모든 상태가 자동으로 동기화됨 expect(state).toEqual({ displayAmount: '1,000', rawValue: '1000', isError: false, errorMessage: '', history: ['1', '10', '100', '1,000'], isFirstInput: false, }); }); ``` 리듀서는 순수 함수이므로 React 환경 없이도 테스트 가능하며, 모든 상태 변경이 한 곳에서 일어나므로 검증이 간단하다. ### 4. 디버깅과 유지보수성 React 18부터는 이벤트 핸들러 내의 여러 `setState` 호출이 자동으로 배칭되므로 성능 차이는 크지 않다. 하지만 `useReducer`의 진짜 강점은 다른 곳에 있다: ```tsx // useReducer는 모든 액션을 로깅하기 쉬움 const withLogging = (reducer: typeof numberPadReducer) => { return (state: NumberPadState, action: NumberPadAction) => { console.log('Previous State:', state); console.log('Action:', action); const nextState = reducer(state, action); console.log('Next State:', nextState); return nextState; }; }; // 사용 예시 const [state, dispatch] = useReducer( withLogging(numberPadReducer), initialState ); ``` 콘솔 출력 예시 - 사용자가 "1"을 입력했을 때: ```javascript Previous State: { displayAmount: '0', rawValue: '', isError: false, errorMessage: '', history: [], isFirstInput: true } Action: { type: 'INPUT_NUMBER', payload: '1' } Next State: { displayAmount: '1', rawValue: '1', isError: false, errorMessage: '', history: ['1'], isFirstInput: false } ``` 이렇게 모든 상태 변화가 자동으로 추적되어 디버깅이 매우 쉬워진다. * 명확한 액션 흐름: 어떤 액션이 언제 발생했는지 추적 가능 * 상태 변경 이력: 이전 상태로 되돌리기 쉬움 * 미들웨어 패턴: Redux처럼 로깅, 에러 리포팅 등 확장 가능 *** ## 결론: 언제 useReducer를 선택해야 할까 ### 판단 기준 useState를 사용해도 충분한 경우: * 독립적인 단순 상태 (예: 토글, 카운터) * 상태 간 연관성이 없거나 적은 경우 * 비즈니스 로직이 단순한 경우 useReducer를 고려해야 하는 경우: * 하나의 액션이 여러 상태를 동시에 변경해야 할 때 * 상태 변경 로직이 복잡하고 조건이 많을 때 * 상태가 서로 긴밀하게 연결되어 있을 때 * 테스트 코드 작성이 중요한 경우 ### 실무에서의 교훈 `useReducer`는 코드의 일관성, 예측 가능성, 테스트 용이성을 높여준다. 특히 금융 서비스처럼 정확성이 중요한 도메인에서는 `useReducer`가 더 안전한 선택이다. 모든 상태 변경이 한 곳에서 관리되기 때문에, 버그를 찾고 수정하기가 훨씬 쉽다. 처음에는 `useState`로 빠르게 시작하고, 복잡도가 높아지면 `useReducer`로 리팩토링하는 것도 좋은 전략이다. 중요한 것은 개발 속도, 안정성, 유지보수성 사이의 균형이다. 무조건 완벽한 코드보다는 현재 상황에 맞는 최적의 선택이 필요하다. *** ## 더 자세한 설명은 영상으로 이 포스트에서 다룬 내용을 실제 코드와 함께 더 자세히 설명한 영상을 준비했다. `useState`에서 `useReducer`로 리팩토링하는 과정을 라이브 코딩으로 보여준다. 영상이 도움이 되었다면 구독과 좋아요 부탁드린다. ## 핵심 정리 * **useState의 한계**: * 복잡한 상태 구조에서 여러 하위 값 관리 어려움 * 상태 간 동기화 지옥 (6개 상태 → 6개 업데이트) * 일관성 없는 상태 관리 (함수마다 다른 업데이트 순서) * 복잡한 규칙 관리 어려움 (빠른 금액 버튼, 00 입력 방지 등) * **useReducer의 장점**: * 예측 가능한 상태 변경 (모든 로직이 리듀서에 집중) * 완벽한 타입 안정성 (TypeScript와 함께 사용 시) * 테스트 용이성 (순수 함수로 React 없이 테스트) * 디버깅 편의성 (모든 액션 로깅 가능) * **선택 기준**: * useState: 독립적 단순 상태, 연관성 적음, 단순 로직 * useReducer: 여러 상태 동시 변경, 복잡한 로직, 긴밀한 연결, 테스트 중요 * **핵심 패턴**: * `dispatch({ type, payload })`: 무엇을 할지 전달 * `reducer(state, action)`: 어떻게 할지 정의 * 컴포넌트는 "무엇을 보여줄지"만, 리듀서는 "어떻게 상태를 변경할지"만 **useReducer는 교통 정리와 같다. useState는 각자 알아서 길을 건너는 것이고 (여러 setState 호출), useReducer는 신호등에서 한 번에 모든 차량을 통제하는 것이다 (한 곳에서 모든 상태 변경). 복잡한 교차로일수록 신호등이 필수다.** *** --- # type vs interface 어떤 것을 사용해야 할까? > 우리가 사용하는 언어는 TypeScript인데, 실제로 리액트 개발을 하다보면 왜인지는 모르겠지만 InterfaceScript 같은 느낌이 드는 경우가 있다. type 보다 왜인지 모르겠지만, interface를 쓰는 경우가 자연스럽게 더 많았기 때문입니다. 신규 프로젝트를 시작하... - 원문: https://www.yolog.co.kr/post/ts-interface-type - 카테고리: 개발 - 발행: 2025-09-09 - 수정: 2025-09-09 ## 끊이지 않는 논쟁, Type vs Interface 우리가 사용하는 언어는 **TypeScript**인데, 실제로 리액트 개발을 하다보면 왜인지는 모르겠지만 **InterfaceScript** 같은 느낌이 드는 경우가 있다. `type` 보다 왜인지 모르겠지만, `interface`를 쓰는 경우가 자연스럽게 더 많았기 때문입니다. (이미지: Type vs Interface) 신규 프로젝트를 시작하면서 팀 내 개발 컨벤션을 만들어야 하는데, 막상 저부터도 `type`과 `interface`의 차이와 장단점을 명확하게 설명하기 어려웠다. 그래서, 이번 블로그를 통해서 그동안 다양한 자료들을 통해 학습한 내용을 정리하며, 우리팀은 어떠한 방식을 선택했는지 공유하려고 한다. ## 일관성만 있으면 아무거나 사용해도 상관이 없는 것일까? 성능 차이가 크게 없다면 아무거나 사용해도 된다고는 하지만, 실제로는 성능 차이가 없지는 않다. (이미지: 이 아저씨는 아닙니당..!) 실제로, 아래는 흔히 빡빡이 아저씨라고 불리는 타입스크립트에서 유명하신 [Matt Pocock씨가 작성한 내용](https://www.totaltypescript.com/type-vs-interface-which-should-you-use)을 토대로 한번 설명해보겠다. ## 실제 성능 사례: Sentry의 경험 Matt Pocock의 [Type vs Interface에 대한 블로그 포스트](https://www.totaltypescript.com/type-vs-interface-which-should-you-use)를 보면, 실제 성능 문제점에 대해서 Sentry의 경험을 공유해주었다. Sentry 팀이 교차 타입(`&`)을 인터페이스 `extends`로 바꿨더니 **컴파일 성능이 눈에 띄게 개선되었다**고 보고했다. 구체적인 수치는 프로젝트마다 다르지만, 대규모 코드베이스에서는 확실히 체감할 수 있는 차이가 있었다고 한다. 우리가 보통 버튼 컴포넌트를 만든다고 할 때, 버튼에서 활용할 수 있는 props들을 모두 일일이 선언하는 게 불가능하기 때문에 우리는 이를 확장한다. ### 타입으로 확장하는 경우 (intersection 활용) ```tsx type ButtonProps = React.ButtonHTMLAttributes & { variant: 'primary' | 'secondary'; loading?: boolean; }; ``` ### 인터페이스로 확장하는 경우 (extends 활용) ```tsx interface ButtonProps extends React.ButtonHTMLAttributes { variant: 'primary' | 'secondary'; loading?: boolean; } ``` [TypeScript 성능 위키](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections)에서도 명시적으로 권장한다: > `interface Foo extends Bar, Baz {}`가 `type Foo = Bar & Baz & {...}`보다 타입 체킹 성능이 좋다. ## 그러면 왜 interface의 extends가 빠를까? 이를 이해하기 위해서는 TypeScript 컴파일러가 타입을 처리하는 방식을 알아야 한다. (세부 메커니즘은 복합적이지만, 핵심 차이점을 설명하겠다) ### 1. interface extends의 동작 방식 (빠름 ⚡) ```tsx // 실무 예제: 유저 관련 인터페이스 interface BaseUser { id: string; email: string; createdAt: Date; } interface UserProfile { nickname: string; avatar?: string; bio?: string; } // Interface extends - 캐싱 가능 interface AuthenticatedUser extends BaseUser, UserProfile { accessToken: string; refreshToken: string; expiresAt: number; } ``` **왜 빠른가?** 1. **이름 기반 캐싱**: TypeScript는 `AuthenticatedUser`라는 이름으로 이 타입을 내부 레지스트리에 저장한다 2. **재사용 시 빠른 참조**: 다른 곳에서 `AuthenticatedUser`를 사용할 때, 컴파일러는 캐시된 타입을 바로 가져옵니다 3. **계층적 체크**: 각 부모 인터페이스를 독립적으로 체크할 수 있어 효율적입니다 ### 2. type intersection의 동작 방식 (느림 🐢) ```tsx // Type intersection - 매번 재계산 type AuthenticatedUser = BaseUser & UserProfile & { accessToken: string; refreshToken: string; expiresAt: number; }; ``` **왜 느린가?** 1. **익명 타입 생성**: 매번 새로운 "익명" 타입을 만듭니다 2. **캐싱 제한**: 구조적으로 매번 재계산이 필요한다 3. **플래튼(Flatten) 과정**: 모든 속성을 하나의 평면 구조로 합쳐야 한다 ### 실제 성능 차이 예시 ```tsx // 대규모 컴포넌트 라이브러리에서의 사용 // ❌ 느림 - 매번 재계산 type SlowButton = HTMLButtonElement & BaseComponentProps & ThemeProps; type SlowInput = HTMLInputElement & BaseComponentProps & ThemeProps; type SlowSelect = HTMLSelectElement & BaseComponentProps & ThemeProps; // ✅ 빠름 - 한 번 계산 후 캐싱 interface FastButton extends HTMLButtonElement, BaseComponentProps, ThemeProps {} interface FastInput extends HTMLInputElement, BaseComponentProps, ThemeProps {} interface FastSelect extends HTMLSelectElement, BaseComponentProps, ThemeProps {} ``` ## interface와 type 각각 존재하는 독특한 특징들 ### interface의 특징 #### 1. Declaration Merging (선언 병합) ```tsx // 라이브러리 타입 확장 시나리오 interface Window { // 기존 Window 인터페이스에 추가 gtag: (command: string, ...args: any[]) => void; kakao: any; } // 두 interface가 자동으로 병합됨! window.gtag('config', 'GA_MEASUREMENT_ID'); // ✅ 타입 체크 통과 ``` 이것은 `interface`의 명과 암을 잘 보여주는 특징입니다. 의도적으로 사용하면 강력하지만, 실수로 같은 이름을 선언하면 문제가 된다. 우리는 이러한 문제를 방지할 수 있다: * **ESLint**: [`@typescript-eslint/no-unsafe-declaration-merging`](https://typescript-eslint.io/rules/no-unsafe-declaration-merging/) * **Biome**: [`noRedeclare`](https://biomejs.dev/linter/rules/no-redeclare/), [`noUnsafeDeclarationMerging`](https://biomejs.dev/linter/rules/no-unsafe-declaration-merging/) #### 2. 인덱스 시그니처 차이 **타입 별칭은 "닫힌(closed)" 특성**을 가지고, **인터페이스는 선언 병합으로 "열린(open)" 특성**을 가집니다. 이로 인해 인터페이스는 암묵적 인덱스 시그니처를 가정하기 어렵다. ```tsx interface UserInterface { name: string; age: number; } type UserType = { name: string; age: number; }; const userI: UserInterface = { name: 'Kim', age: 30 }; const userT: UserType = { name: 'Lee', age: 25 }; // Record에 할당 type AnyRecord = Record; const record1: AnyRecord = userT; // ✅ OK - `type`은 가능 const record2: AnyRecord = userI; // ❌ Error - `interface`는 불가능 ``` ### type의 특별한 기능들 (interface가 할 수 없는 것들) #### 1. Union Types - 실무에서 가장 많이 쓰는 패턴 ```tsx // API 상태 관리 type ApiStatus = 'idle' | 'loading' | 'success' | 'error'; // HTTP 메서드 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH'; // 비동기 상태 관리 (제네릭과 함께) type AsyncState = | { status: 'idle' } | { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }; // 실제 사용 function useApiCall(): AsyncState { // 구현... return { status: 'idle' }; } ``` #### 2. Discriminated Union (판별 유니온) - 타입 안정성의 핵심 ```tsx // 폼 액션 타입 type FormAction = | { type: 'SET_FIELD'; field: string; value: string } | { type: 'SET_ERROR'; field: string; error: string } | { type: 'RESET_FORM' } | { type: 'SUBMIT_START' } | { type: 'SUBMIT_SUCCESS'; data: any } | { type: 'SUBMIT_FAILURE'; error: Error }; // 리듀서에서 완벽한 타입 추론 function formReducer(state: FormState, action: FormAction) { switch (action.type) { case 'SET_FIELD': return { ...state, [action.field]: action.value }; // field, value 자동 추론 case 'SET_ERROR': return { ...state, errors: { ...state.errors, [action.field]: action.error }, }; case 'SUBMIT_SUCCESS': return { ...state, data: action.data }; // data 자동 추론 // ... } } ``` #### 3. Branded Types - 타입 안정성 강화 ```tsx // 단순 string이 아닌 구별되는 타입 type UserId = string & { __brand: 'UserId' }; type PostId = string & { __brand: 'PostId' }; type Email = string & { __brand: 'Email' }; // API 함수에서 타입 안정성 보장 async function fetchUser(id: UserId): Promise { return api.get(`/users/${id}`); } async function fetchPost(id: PostId): Promise { return api.get(`/posts/${id}`); } // 사용 const userId = 'user_123' as UserId; const postId = 'post_456' as PostId; fetchUser(postId); // ❌ 컴파일 에러! 타입 안정성 보장 ``` #### 4. Template Literal Types - 동적 타입 생성 ```tsx // 반응형 브레이크포인트 type Breakpoint = 'sm' | 'md' | 'lg' | 'xl'; type ResponsiveProperty = T | `${T}-${Breakpoint}`; type Spacing = ResponsiveProperty<'m' | 'p'>; // 결과: 'm' | 'p' | 'm-sm' | 'm-md' | 'm-lg' | 'm-xl' | 'p-sm' | ... // CSS-in-JS 스타일 props interface BoxProps { m?: Spacing; p?: Spacing; display?: ResponsiveProperty<'block' | 'flex' | 'none'>; } // 사용 ; // 타입 체크 완벽! ``` #### 5. Conditional Types - 타입 레벨 프로그래밍 ```tsx // React 컴포넌트 Props 추출 type ComponentProps = T extends React.ComponentType ? P : never; // 사용 예시 type ButtonProps = ComponentProps; // Button의 props 타입 추출 // API 응답 래퍼 type ApiWrapper = T extends { error: true } ? { success: false; error: string } : { success: true; data: T }; // 조건부 Required type ConditionalRequired = T & Required>; interface UserForm { name?: string; email?: string; password?: string; } // 회원가입 시 모든 필드 필수 type SignupForm = ConditionalRequired; ``` #### 6. Utility Types 실무 활용 ```tsx // API 응답과 폼 데이터 분리 interface User { id: string; email: string; password: string; createdAt: Date; updatedAt: Date; } // 생성 시: id와 timestamp 제외 type CreateUserDto = Omit; // 업데이트 시: 모든 필드 선택적, password 제외 type UpdateUserDto = Partial>; // 응답 시: password 제외 type UserResponse = Omit; // 함수 파라미터 타입 추출 function createUser(data: CreateUserDto) { /* ... */ } type CreateUserParams = Parameters[0]; ``` #### 7. 고급 매핑 타입 ```tsx // Getter 자동 생성 타입 type Getters = { [K in keyof T as `get${Capitalize}`]: () => T[K]; }; interface State { name: string; age: number; isActive: boolean; } type StateGetters = Getters; // 결과: { // getName: () => string; // getAge: () => number; // getIsActive: () => boolean; // } // Deep Partial (중첩 객체도 모두 선택적으로) type DeepPartial = { [P in keyof T]?: T[P] extends object ? DeepPartial : T[P]; }; // 실제 사용: 설정 객체 업데이트 interface AppConfig { api: { baseUrl: string; timeout: number; retry: { count: number; delay: number; }; }; } function updateConfig(partial: DeepPartial) { // 어떤 깊이의 속성도 선택적으로 업데이트 가능 } updateConfig({ api: { retry: { count: 5 } } }); // ✅ OK ``` ## 그래서 우리 팀은 어떤 걸 선택했나? 우리 팀은 **`interface`를 기본으로 사용하고, `type`의 특별한 기능이 필요할 때만 `type`을 사용**하기로 정했다. TypeScript 공식 문서에서도 "`interface`는 열림(open), `type`은 닫힘(closed)"의 특성 차이를 강조하며, 용도에 따라 선택하라고 권장한다. ### 선택 이유 1. **성능**: `interface`의 `extends`는 `type`의 intersection보다 확실히 빠릅니다 2. **위험 관리 가능**: Declaration Merging 같은 `interface`의 위험성은 린터로 관리 가능 3. **드문 문제**: 인덱스 시그니처 문제는 실제 개발에서 매우 드물게 발생 ### 우리 팀의 컨벤션 ```tsx // ✅ Good - 객체 타입 정의는 `interface` interface UserDto { id: string; email: string; name: string; } // ✅ Good - React 컴포넌트 Props는 `interface` + `extends` interface ButtonProps extends React.ButtonHTMLAttributes { variant: 'primary' | 'secondary' | 'danger'; size: 'small' | 'medium' | 'large'; loading?: boolean; } // ✅ Good - API 응답은 `interface` interface ApiResponse { data: T; status: number; message: string; } // ✅ Good - Union, Conditional 등이 필요한 경우만 `type` type ButtonVariant = 'primary' | 'secondary' | 'danger'; type AsyncStatus = 'idle' | 'loading' | 'success' | 'error'; // ✅ Good - 유틸리티 타입 활용 type PartialUser = Partial; type RequiredUser = Required; // ✅ Good - Discriminated Union은 `type` type Action = | { type: 'FETCH_START' } | { type: 'FETCH_SUCCESS'; payload: UserDto[] } | { type: 'FETCH_ERROR'; error: Error }; ``` ### ESLint 설정 예시 ```json { "rules": { "@typescript-eslint/consistent-type-definitions": ["error", "interface"], "@typescript-eslint/no-unsafe-declaration-merging": "error", "@typescript-eslint/prefer-interface": "error" } } ``` ## 마무리 `type` vs `interface` 논쟁은 계속될 것이다. 하지만 중요한 것은 팀 내에서 일관된 컨벤션을 유지하고 각각의 장단점을 이해한 상태에서 적절히 활용하는 것이다. 우리 팀은 성능과 확장성을 고려하여 `interface`를 기본으로 선택했지만 `type`의 강력한 기능이 필요한 순간을 놓치지 않고 활용하고 있다. 더 자세한 내용은 다음 자료들을 참고하시기 바란다: * [Matt Pocock의 원문](https://www.totaltypescript.com/type-vs-interface-which-should-you-use) * [TypeScript 공식 문서](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#differences-between-type-aliases-and-interfaces) * [TypeScript 성능 위키](https://github.com/microsoft/TypeScript/wiki/Performance#preferring-interfaces-over-intersections) 여러분의 팀도 프로젝트 특성에 맞는 최적의 선택을 하시길 바란다. *** ## 핵심 정리 * **성능 차이**: * Interface가 교차 타입(&)보다 컴파일 성능 우수 * Sentry 사례: intersection → extends 전환으로 성능 개선 * 대규모 프로젝트에서 체감 가능한 차이 * **Interface 장점**: * Declaration Merging (선언 병합) 가능 * 확장성이 뛰어남 (extends) * 컴파일 성능 우수 * 객체 타입 정의에 최적화 * **Type 장점**: * Union, Intersection, Mapped Type 가능 * Conditional Type 지원 * Utility Type 활용 (Pick, Omit 등) * Primitive, Tuple, Function도 정의 가능 * **권장 사용 패턴**: * 객체 구조 정의: interface 사용 * Props, State: interface * Union Type: type 사용 * 복잡한 타입 조작: type 사용 * **성능 최적화**: * 교차 타입(&) 대신 extends 사용 * 중첩된 intersection 피하기 * Interface 병합보다 extends 선호 * **실무 가이드라인**: * 기본: interface 사용 * Union/Intersection 필요: type 사용 * 라이브러리 확장: interface (Declaration Merging) * 복잡한 타입 연산: type 사용 * **ESLint 규칙**: * `@typescript-eslint/consistent-type-definitions` * `@typescript-eslint/no-unsafe-declaration-merging` * `@typescript-eslint/prefer-interface` * **팀 컨벤션의 중요성**: * 일관성이 가장 중요 * 각 도구의 장단점 이해 필수 * 프로젝트 특성에 맞게 선택 **Type vs Interface는 연필 vs 볼펜과 같다. Interface는 볼펜처럼 명확하고 일관된 선을 그린다(객체 정의). Type은 연필처럼 다양한 표현이 가능하다(Union, Conditional). 일반 글쓰기는 볼펜으로, 디자인 스케치는 연필로 하듯, 객체는 Interface로, 복잡한 타입 연산은 Type으로 작성하면 된다.** --- # BEM CSS 방법론 실전 가이드 - 예제로 배우는 네이밍 규칙 > "왜 내 CSS는 점점 스파게티 코드가 되어가는 걸까?" ".button 클래스를 수정했더니 전혀 다른 페이지의 버튼이 깨졌어요..." 이런 경험이 있다면, BEM(Block, Element, Modifier) 방법론이 답이 될 수 있다. BEM은 CSS 클래스 이름을 체계적으로... - 원문: https://www.yolog.co.kr/post/css-bem-methodology - 카테고리: 개발 - 발행: 2025-09-08 - 수정: 2025-09-08 "왜 내 CSS는 점점 스파게티 코드가 되어가는 걸까?" "`.button` 클래스를 수정했더니 전혀 다른 페이지의 버튼이 깨졌어요..." 이런 경험이 있다면, `BEM(Block, Element, Modifier)` 방법론이 답이 될 수 있다. `BEM`은 CSS 클래스 이름을 체계적으로 작성하는 방법론으로, 2009년 러시아의 [Yandex](https://en.bem.info/)에서 개발되어 현재 전 세계적으로 사용되고 있다. 이번 포스트에서는 `BEM`의 세 가지 핵심 개념인 `Block`, `Element`, `Modifier`를 실제 예제와 함께 완벽하게 마스터해보겠다. (이미지: BEM 방법론 구조 다이어그램) *** ## BEM이란 무엇인가? `BEM`은 `Block`, `Element`, `Modifier`의 약자로, CSS 클래스 이름을 짓는 규칙입니다. ```css /* BEM 구조 */ .block { } .block__element { } .block--modifier { } .block__element--modifier { } ``` ### 왜 BEM을 사용해야 할까? | 문제 상황 | `BEM`이 제공하는 해결책 | | --------- | --------------- | | 클래스 이름 충돌 | 네임스페이스로 완전히 분리 | | 스타일 덮어쓰기 | 독립적인 블록으로 격리 | | 코드 이해 어려움 | 명확한 관계 표현 | | 재사용 불가능 | 컴포넌트 단위 설계 | *** ## 1. Block: 독립적인 컴포넌트 ### Block이란? `Block`은 그 자체로 의미를 가지는 **독립적인 컴포넌트**입니다. 페이지 어디에든 재사용할 수 있는 기능적 단위입니다. (이미지: BEM Block 예시) ### Block 작명 규칙 ```css /* ✅ 좋은 예: 명확한 의미 */ .header { } .menu { } .search-form { } .user-profile { } /* ❌ 나쁜 예: 모호하거나 일반적인 이름 */ .content { } /* 너무 일반적 */ .big-block { } /* 스타일 기반 이름 */ .block1 { } /* 의미 없는 이름 */ ``` ### Block 실전 예제 **카드 컴포넌트를 Block으로 만들기:** ```html
    상품

    상품 이름

    상품 설명

    ``` ```css .card { border: 1px solid #ddd; padding: 20px; border-radius: 8px; background: white; } ``` ### Block의 특징 1. **독립성**: 다른 블록에 의존하지 않음 2. **재사용성**: 어디서든 사용 가능 3. **이동 가능**: 위치가 바뀌어도 동작 4. **중첩 가능**: 블록 안에 다른 블록 포함 가능 ```html
    ``` *** ## 2. Element: Block의 구성 요소 ### Element란? `Element`는 `Block`의 일부분으로, **Block 안에서만 의미를 가지는 구성 요소**입니다. `Block`과 `Element`는 `__` (더블 언더스코어)로 연결한다. (이미지: BEM Element 구조) ### Element 작명 규칙 ```css /* Block__Element 형식 */ .card__image { } .card__title { } .card__description { } .card__button { } .menu__item { } .menu__link { } .search-form__input { } .search-form__button { } ``` ### Element 실전 예제 **카드 컴포넌트에 Element 적용:** ```html
    상품

    상품 이름

    상품 설명

    ``` ```css .card { border: 1px solid #ddd; padding: 20px; border-radius: 8px; } .card__image { width: 100%; height: 200px; object-fit: cover; } .card__title { font-size: 18px; font-weight: bold; margin: 10px 0; } .card__description { color: #666; line-height: 1.5; } .card__button { background: #007bff; color: white; padding: 10px 20px; border: none; border-radius: 4px; cursor: pointer; } ``` ### Element 주의사항 #### ❌ 잘못된 사용: Element의 Element ```css /* 절대 이렇게 사용하지 마세요! */ .card__header__title { } /* ❌ Element의 Element */ /* 대신 이렇게 사용하세요 */ .card__header { } .card__title { } /* ✅ 모두 card의 직접적인 Element */ ``` #### ✅ 올바른 HTML 구조와 `BEM` ```html

    제목

    NEW

    내용

    ``` *** ## 3. Modifier: 상태와 테마 변형 ### Modifier란? `Modifier`는 `Block`이나 `Element`의 **모양, 상태, 동작을 변경**한다. `--` (더블 대시)로 연결한다. (이미지: BEM Modifier 예시) ### Modifier 작명 규칙 ```css /* Block--Modifier */ .card--featured { } .button--large { } .menu--vertical { } /* Block__Element--Modifier */ .card__button--disabled { } .form__input--error { } .menu__item--active { } ``` ### Modifier 실전 예제 #### 버튼의 다양한 상태 표현 ```html ``` ```css /* 기본 버튼 스타일 */ .button { padding: 8px 16px; border: 1px solid #ddd; background: white; border-radius: 4px; font-size: 14px; cursor: pointer; } /* Modifier: 크기 변형 */ .button--large { padding: 12px 24px; font-size: 16px; } /* Modifier: 스타일 변형 */ .button--primary { background: #007bff; color: white; border-color: #007bff; } /* Modifier: 상태 변형 */ .button--disabled { opacity: 0.5; cursor: not-allowed; } ``` ### Modifier 활용 패턴 #### 1. Boolean Modifier (상태) ```css /* 활성/비활성 같은 on/off 상태 */ .menu__item--active { } .form__input--disabled { } .card--hidden { } ``` #### 2. Key-Value Modifier (속성-값) ```css /* 특정 값을 가지는 수정자 */ .button--size-large { } .button--color-red { } .card--theme-dark { } ``` *** ## 4. 실전: 완전한 카드 컴포넌트 만들기 이제 `Block`, `Element`, `Modifier`를 모두 활용해 실제 사용 가능한 카드 컴포넌트를 만들어보겠다. (이미지: 완전한 BEM 카드 컴포넌트) ### HTML 구조 #### 기본 카드 구조 ```html
    노트북 SALE

    최신형 노트북

    1,500,000원 1,200,000원

    고성능 프로세서와 긴 배터리 수명

    ``` #### Modifier 적용 예시 ```html
    태블릿 SOLD OUT
    ``` ### CSS 스타일 #### Block 스타일 ```css /* 기본 카드 블록 */ .product-card { border: 1px solid #e0e0e0; border-radius: 8px; overflow: hidden; background: white; transition: transform 0.2s; } .product-card:hover { transform: translateY(-4px); box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); } ``` #### Element 스타일 ```css /* 이미지 영역 */ .product-card__image-wrapper { position: relative; height: 200px; overflow: hidden; } .product-card__image { width: 100%; height: 100%; object-fit: cover; } .product-card__badge { position: absolute; top: 10px; right: 10px; padding: 4px 8px; background: #ff5252; color: white; font-size: 12px; font-weight: bold; border-radius: 4px; } /* 콘텐츠 영역 */ .product-card__content { padding: 16px; } .product-card__title { font-size: 18px; font-weight: bold; margin: 0 0 8px 0; } .product-card__price-original { color: #999; text-decoration: line-through; margin-right: 8px; } .product-card__price-sale { color: #ff5252; font-size: 20px; font-weight: bold; } /* 버튼 영역 */ .product-card__actions { padding: 16px; border-top: 1px solid #e0e0e0; display: flex; gap: 8px; } .product-card__button { flex: 1; padding: 10px; border: none; border-radius: 4px; font-size: 14px; font-weight: bold; cursor: pointer; } ``` #### Modifier 스타일 ```css /* Block Modifiers */ .product-card--featured { border: 2px solid #ffd700; background: linear-gradient(135deg, #fffef5 0%, #fff 100%); } .product-card--sold-out { opacity: 0.6; pointer-events: none; } /* Element Modifiers */ .product-card__badge--hot { background: #ff9800; } .product-card__badge--sold-out { background: #757575; } .product-card__button--primary { background: #007bff; color: white; } .product-card__button--secondary { background: white; color: #007bff; border: 1px solid #007bff; } .product-card__button--disabled { background: #e0e0e0; color: #999; cursor: not-allowed; } ``` *** ## 5. Modifier 재사용 패턴 ### 기본 스타일 + Modifier 조합 `BEM`의 핵심은 **기본 스타일을 유지하면서 `Modifier`로 변형**하는 것입니다. ```html ``` ```css /* 기본 버튼 스타일 (공통) */ .card__button { padding: 10px 20px; border-radius: 4px; font-size: 14px; font-weight: bold; cursor: pointer; transition: all 0.3s; border: none; } /* Modifier: submit 버튼만의 스타일 */ .card__button--submit { background: #28a745; color: white; } .card__button--submit:hover { background: #218838; } /* Modifier: cancel 버튼만의 스타일 */ .card__button--cancel { background: #dc3545; color: white; } .card__button--cancel:hover { background: #c82333; } ``` (이미지: Modifier 재사용 패턴) ### Modifier 조합하기 여러 Modifier를 동시에 적용할 수도 있다: ```html ``` *** ## 6. BEM 사용 시 주의사항 ### 자주 하는 실수와 해결책 #### 1. Element의 Element 만들기 ```css /* ❌ 잘못된 예 */ .card__header__title { } /* ✅ 올바른 예 */ .card__header { } .card__title { } ``` #### 2. Modifier만 단독 사용 ```html ``` #### 3. 의미 없는 이름 사용 ```css /* ❌ 피해야 할 이름 */ .card__div { } .card__span { } .card__element1 { } /* ✅ 의미 있는 이름 */ .card__wrapper { } .card__label { } .card__content { } ``` ### BEM과 CSS 전처리기 SASS/SCSS를 사용하면 `BEM`을 더 효율적으로 작성할 수 있다: ```scss .card { border: 1px solid #ddd; &__title { font-size: 18px; } &__button { padding: 10px; &--primary { background: blue; } &--secondary { background: gray; } } &--featured { border-color: gold; } } ``` ### BEM 네이밍 컨벤션 변형 프로젝트에 따라 구분자를 다르게 사용하기도 한다: ```css /* 클래식 BEM */ .block__element--modifier { } /* 카멜케이스 변형 */ .blockName__elementName--modifierName { } /* 싱글 대시 변형 */ .block__element-modifier { } ``` *** ## 7. BEM 적용 전후 비교 ### Before: BEM 없이 작성한 CSS ```css /* 충돌 위험이 높은 일반적인 이름들 */ .header { background: blue; } .title { font-size: 24px; } .button { padding: 10px; } /* 점점 복잡해지는 선택자 */ .page .header .nav .menu .item .link { color: white; } .sidebar .widget .title { font-size: 16px; } /* title 충돌! */ /* 어디에 쓰이는지 알 수 없는 클래스 */ .large { font-size: 20px; } .red { color: red; } .mt-10 { margin-top: 10px; } ``` ### After: BEM으로 작성한 CSS ```css /* 명확한 네임스페이스 */ .site-header { background: blue; } .site-header__title { font-size: 24px; } .site-header__button { padding: 10px; } /* 단순하고 명확한 선택자 */ .navigation__link { color: white; } .sidebar-widget__title { font-size: 16px; } /* 충돌 없음! */ /* 용도가 명확한 Modifier */ .button--large { font-size: 20px; } .text--danger { color: red; } .card--spacing-medium { margin-top: 10px; } ``` *** ## 8. BEM 도입 전후의 변화 ### BEM 도입 전의 고통 프로젝트가 커질수록 CSS 관리는 악몽이 되어갔다: * **"이 클래스 지워도 되나?"** - 어디서 쓰이는지 확신할 수 없어 방치 * **"왜 스타일이 안 먹지?"** - 다른 곳의 더 구체적인 선택자에 덮어써짐 * **"이름이 겹치네..."** - `.title`, `.button` 같은 이름이 수십 개 * **CSS 파일 크기만 계속 증가** - 지우기 무서워서 계속 추가만 함 ### BEM 도입 후의 변화 `BEM`을 적용하고 나서 달라진 점들: * **클래스명만 봐도 구조 파악** - `.card__title`은 card 컴포넌트의 제목 * **안심하고 삭제 가능** - 영향 범위가 명확해서 리팩토링이 쉬워짐 * **새 개발자도 바로 이해** - 일관된 규칙으로 누구나 코드 파악 가능 * **CSS 충돌 제로** - 더 이상 `!important` 남발하지 않음 ### 코드 비교 ```css /* BEM 전: 3개월 후 아무도 건드리지 못하는 코드 */ .container .box .title { } /* 이게 어느 페이지의 title? */ .active { } /* 뭐가 active? */ .btn-2 { } /* btn-1은 어디에? */ /* BEM 후: 1년 후에도 명확한 코드 */ .product-card__title { } /* 상품 카드의 제목 */ .navigation__item--active { } /* 네비게이션의 활성 아이템 */ .button--size-large { } /* 큰 사이즈 버튼 */ ``` *** ## 정리 `BEM`은 CSS 클래스 이름을 체계적으로 작성하는 강력한 방법론입니다. **핵심 개념:** * **Block**: 독립적인 컴포넌트 (`.card`) * **Element**: Block의 구성 요소 (`.card__title`) * **Modifier**: 상태나 테마 변형 (`.card--featured`) **`BEM`의 가치:** 1. 클래스 이름 충돌 완전 방지 2. 코드만 봐도 구조와 관계 파악 가능 3. 안전한 리팩토링과 유지보수 4. 팀 협업 시 일관된 코드 스타일 "**명확한 것이 간결한 것보다 낫다**"는 `BEM`의 철학을 기억하세요. ## AI 시대, BEM이 더 중요하다고 생각하는 개인적인 이유 실무에서 AI 도구들과 함께 개발하면서, 예전에 학습했던 `BEM` 방법론을 다시 돌아보게 되었다. 처음 `BEM`을 배울 때는 솔직히 `.card__button--primary` 같은 긴 클래스명이 불필요하게 복잡해 보였다. "그냥 `.btn`으로 써도 되는데..." 라고 생각했었죠. 그런데 최근 `Claude`나 `Cursor` 같은 AI 도구를 활용해 개발하면서 깨달은 점이 있다. **체계적인 규칙이 AI와의 협업을 얼마나 효율적으로 만드는지** 말이죠. ```css /* AI에게 "card 컴포넌트의 버튼 스타일 수정해줘" 라고 요청할 때 */ /* BEM 없는 코드: AI가 어떤 버튼인지 모호함 */ .btn { } /* 이게 어느 버튼? */ .button { } /* 이것도 버튼? */ /* BEM 적용 코드: AI가 정확히 찾아서 수정 */ .card__button { } /* 명확하게 card의 버튼 */ .modal__button { } /* 명확하게 modal의 버튼 */ ``` 실무에서 AI 도구를 사용하며 느낀 건, **AI도 결국 명확한 컨텍스트가 있을 때 가장 정확한 결과를 낸다**는 것입니다. `BEM`으로 작성된 코드는 구조와 관계가 명확해서, AI가 제 의도를 훨씬 잘 이해하고 정확한 수정을 해줍니다. 이제 와서 생각해보니, 예전에 배웠던 `BEM` 같은 좋은 규칙 하나하나가 결국 AI를 더 잘 활용할 수 있는 기반이 되더라구요. 특히 이제 막 개발을 시작하는 분들이라면, 처음부터 이런 체계적인 방법론을 익히는 것이 AI 시대에 더 경쟁력 있는 개발자가 되는 지름길이 아닐까 싶다. **"명확한 코드는 인간뿐만 아니라 AI와의 소통도 원활하게 만든다"** - 이것이 제가 실무에서 AI와 함께 일하며 얻은 깨달음입니다. *** ## 참고 자료 * [BEM 공식 문서](https://en.bem.info/methodology/) * [BEM 101 by CSS-Tricks](https://css-tricks.com/bem-101/) * [GetBEM 가이드](http://getbem.com/) * [Yandex의 BEM 방법론 소개](https://en.bem.info/methodology/quick-start/) *** 여러분도 `BEM`을 사용하면서 느낀 점이 있거나, AI 도구와 함께 개발하며 겪은 경험이 있다면 댓글로 나눠주세요. 함께 더 좋은 개발 문화를 만들어가면 좋겠다! --- # 프론트엔드·백엔드 개발자라면 꼭 알아야 할 CSRF 공격과 방어법 > "로그인한 사용자가 모르는 사이에 자동으로 송금이 되었다면?" 웹 개발자라면 꼭 알아야 할 심각한 보안 취약점 CSRF(Cross-Site Request Forgery)에 대해 알아보겠다. 이번 포스트에서는 직접 공격 서버를 구축하고 실제 공격을 시연한 후 SameSite 쿠키와... - 원문: https://www.yolog.co.kr/post/security-csrf - 카테고리: HTTP - 발행: 2025-09-06 - 수정: 2025-09-06 "로그인한 사용자가 모르는 사이에 자동으로 송금이 되었다면?" 웹 개발자라면 꼭 알아야 할 심각한 보안 취약점 `CSRF(Cross-Site Request Forgery)`에 대해 알아보겠다. 이번 포스트에서는 직접 공격 서버를 구축하고 실제 공격을 시연한 후 `SameSite 쿠키`와 `CSRF 토큰`으로 방어하는 방법까지 단계별로 실습해보겠다. (이미지: CSRF 공격) ## 1. CSRF 공격이란? 피해자 모르게 실행되는 위험한 요청 ### CSRF 공격의 핵심 원리 `CSRF`는 **인증된 사용자의 권한을 도용**하여 원하지 않는 작업을 수행하게 만드는 공격입니다: 1. **피해자가 은행 사이트에 로그인** (세션 쿠키 발급) 2. **공격자 사이트 방문** (악성 링크 클릭) 3. **자동으로 은행 API 호출** (송금, 비밀번호 변경 등) 4. **브라우저가 쿠키를 자동 전송** (인증된 요청으로 처리) 이제 직접 간단하게 공격을 구현해보면서 CSRF의 위험성을 체험해보겠다. *** ## 2. CSRF 공격 서버 구축하기 ### 공격 시나리오 설정 이전 포스트의 [세션 하이재킹](https://www.yolog.co.kr/post/security-session-hijacking) 실습 환경을 활용한다. `matthew.com`이 결제 기능을 제공한다고 가정하고, 공격자가 이를 악용하는 상황을 재현해보겠다. ### 악성 웹 서버 구현 **attacker-csrf.js** ```javascript const http = require('http'); // csrf 라는 핸들러 함수를 만듬 const csrf = (req, res) => { // 간단한 HTML 을 제공 res.setHeader('Content-Type', 'text/html'); res.write(` CSRF `); res.end(); }; const server = http.createServer(csrf); server.listen(8082, () => { console.log('Attacker server is running on port 8082'); }); ``` ### 공격 코드 분석 간단한 HTML을 제공하고, HTML을 보면 바디에 이미지가 하나 있다. 그런데 이 이미지는 바로 공격 대상인 `matthew.com`으로 네트워크 요청을 보내는 이미지 태그입니다. 이 악성 HTML의 핵심 트릭: 1. **자동 실행**: 페이지 로딩만으로 요청 발생 2. **보이지 않는 요청**: `1x1 픽셀` + `display:none` 3. **다중 공격**: 송금, 비밀번호 변경 동시 시도 4. **사회공학적 미끼**: "무료 쿠폰" 으로 클릭 유도 공격용 웹 페이지를 제공하는 공격 서버에서 이 URL로 요청을 보내면, 다른 사용자의 결제를 대신 해버릴 수도 있다. 만약 `matthew.com`이 결제할 수 있는 URL을 제공한다고 하면, 문제가 더 심각해질 수 있다. ### 브라우저 보안 설정 해제 (실습용) 실습을 위해 일시적으로 브라우저 보안을 해제한다. `Firefox`의 향상된 추적 방지 부분에서 사용자 지정으로 해서 쿠키 체크박스를 해제할 것입니다. > \[!WARNING] > **경고: 실습 후 반드시 원래 설정으로 복구하세요!** **Firefox 설정 변경:** 1. 설정 → 개인정보 및 보안 2. 향상된 추적 방지 → 사용자 지정 3. 쿠키 체크박스 해제 4. 세이프 브라우징을 보호되지 않게 설정 기본적으로 브라우저가 조치해주는 보안 기능을 끈 것입니다. (이미지: Firefox 브라우저 보안 설정 해제) > \[!NOTE] > **왜 브라우저 설정을 변경하나요?** > 최신 브라우저들은 기본적으로 `CSRF 공격`을 어느 정도 방어한다. > 실습을 위해 이러한 보호 기능을 일시적으로 해제한다. *** ## 3. CSRF 공격 시연 ### 공격 준비 **1단계: 정상 사이트 로그인** (인증 된 상태) 먼저 `matthew.com`에 정상적으로 로그인한다: (이미지: matthew\.com 로그인 및 세션 쿠키 발급) * `http://matthew.com:8080/login` 접속 * 세션 ID가 쿠키로 저장됨 * 인증된 상태로 홈페이지 리다이렉트 **2단계: 공격 사이트 방문** (인증 되지 않은 상태) 이제 다른 탭에서 공격자 사이트를 방문해보겠다: (이미지: hacker.com:8082 접속 화면) ### 공격 메커니즘 분석 브라우저가 공격 페이지를 렌더링하는 과정: 1. **HTML 파싱**: 브라우저가 화면을 렌더링하다가 이미지 태그를 만남 2. **img 태그 발견**: 이미지에 등록된 주소로 네트워크 요청을 보냄 3. **자동 요청**: 이것이 바로 `matthew.com:8080`으로 요청을 보내는 것 4. **쿠키 자동 전송**: 이때 중요한 것은 쿠키 값도 똑같이 보낸다는 것입니다! 🚨 (이미지: CSRF 공격: 인증 쿠키가 자동으로 전송됨) ### 공격 성공! 무슨 일이 일어났나? **네트워크 탭을 확인해보면:** ```http GET http://matthew.com:8080/transfer?amount=10000&to=hacker Cookie: sid=session-id-1756852495508 ← 자동으로 포함됨! ``` > \[!WARNING] > **핵심 문제점** 🚨 방금 다른 탭인 `matthew.com`에서 로그인해서 발급받은 쿠키인데, `hacker.com`에서도 이 쿠키를 실어서 `matthew.com` 쪽으로 요청을 보낸 것입니다. 1. `hacker.com`에서 발생한 요청인데 2. `matthew.com`의 세션 쿠키가 자동 전송됨 3. `matthew.com` 측에서는 이 요청이 인증된 요청이라고 판단하고, 비즈니스 로직을 수행할 것입니다 4. 만약 이 요청이 결제 프로세스라면 `matthew.com`에서는 인증된 요청이라고 생각하고 실행할 수도 있다는 것을 보았다! *** 이렇게 **서로 다른 사이트 간의 요청을 위조해서 공격하는 기법을 교차 사이트 요청 위조**라고 부릅니다. `Cross Site Request Forgery`라고 해서 `CSRF`라고도 부릅니다. 이것도 마찬가지로 잘못된 요청에 쿠키가 전달되는 것이 원인입니다. `matthew.com`에서 사용할 쿠키인데 `hacker.com`에서 발생한 네트워크 요청에도 이 쿠키가 실립니다. *** ## 4. CSRF 방어 전략 ### 방법 1: SameSite 쿠키 (가장 간단한 해결책) 간단한 해결방법은 쿠키 디렉티브를 설정하는 것입니다. 이전 [쿠키 편](https://www.yolog.co.kr/post/http-cookie)에서 본 것처럼 `SameSite` 디렉티브를 사용하면 쿠키를 사용할 수 있는 사이트를 제한할 수 있다. `SameSite` 속성은 쿠키가 전송되는 조건을 제한한다: ```javascript // ❌ 취약한 쿠키 설정 res.setHeader('Set-Cookie', `sid=${sid}`); // ✅ SameSite로 보호된 쿠키 res.setHeader('Set-Cookie', `sid=${sid}; SameSite=Strict`); ``` `SameSite=Strict` 속성으로 인해 브라우저는 이 쿠키를 받으면, 이 서버인 `matthew.com`으로 요청할 때만 이 쿠키를 사용할 것입니다. **SameSite 옵션 비교:** | 옵션 | 동작 | 사용 시나리오 | 보안 수준 | | ---------- | -------------------------- | ---------- | ----- | | **Strict** | 같은 사이트에서만 쿠키 전송 | 은행, 결제 시스템 | ⭐⭐⭐ | | **Lax** | 일부 크로스 사이트 허용 (GET, 링크 클릭) | 일반 웹사이트 | ⭐⭐ | | **None** | 모든 요청에 쿠키 전송 (Secure 필수) | 임베드 위젯 | ⭐ | ### SameSite 적용 후 테스트 **서버 코드 수정:** ```javascript const login = (req, res) => { // ... 세션 생성 로직 ... // SameSite=Strict 추가 res.setHeader('Set-Cookie', `sid=${sid}; SameSite=Strict; HttpOnly`); res.setHeader('Location', '/'); res.statusCode = 302; res.end(); }; ``` (이미지: SameSite=Strict 쿠키 설정 확인) ### 공격 재시도 이렇게 `SameSite=Strict` 속성이 잘 들어감을 확인할 수 있다. 다시 `hacker.com:8082`로 들어가서 요청을 보내보겠다: (이미지: SameSite 적용 후: 쿠키가 전송되지 않음) 이미지 태그를 발견하고 `matthew.com` 쪽으로 요청을 보내는데, 이때 쿠키 값을 보면 SID 쿠키가 없다. **네트워크 요청 분석:** ```http GET http://matthew.com:8080/transfer?amount=10000&to=hacker Cookie: (비어있음) ← 쿠키가 전송되지 않음! ✅ ``` 더이상 브라우저는 `matthew.com`이 아닌 곳에서는 이 쿠키를 보내지 않다. > \[!NOTE] > `SameSite=Strict`의 효과 > 브라우저가 자동으로 쿠키 전송을 차단한다: > > * `matthew.com` → `matthew.com`: 쿠키 전송 ⭕ > * `hacker.com` → `matthew.com`: 쿠키 차단 ❌ *** ### SameSite의 한계점 이 `SameSite` 쿠키는 MDN 문서에서 한 번 자세하게 읽어보는 것이 좋다. (이미지: MDN: SameSite 쿠키 문서) 이런 식으로, 아직 실험 중인 기법입니다. 아직은 여전히 실험 중이면서 모든 브라우저에 제공되지 않고 있다고 한다. **주의사항:** * 2020년 이후 대부분 브라우저가 지원하지만 레거시 브라우저 고려 필요 * `Chrome` 80부터 기본값이 `Lax`로 변경됨 * Safari는 일부 버그가 있을 수 있음 (이미지: Can I Use: SameSite 브라우저 지원 현황) *** ## 5. CSRF 토큰: 더 강력한 방어 ### CSRF 토큰의 작동 원리 그래서 다른 예방책이 있다. 특별한 토큰을 `HTML` 문서에 주입하고, 다음 요청 시에 이 토큰이 HTTP 요청에 들어오는지 서버가 확인하는 방식입니다. 예를 들어서, 인증을 하고 나서 HTML 문서를 응답할 때 이런 식으로 할 수 있을 것입니다. `SameSite`만으로 부족할 때 사용하는 전통적이면서도 강력한 방법입니다: 1. **서버가 고유 토큰 생성** 2. **`HTML` 폼에 토큰 삽입** 3. **요청 시 토큰 검증** 4. **토큰 불일치 시 요청 거부** ### CSRF 토큰 구현 **서버 측 구현:** ```javascript const crypto = require('crypto'); // `CSRF` 토큰 생성 및 세션에 저장 const generateCSRFToken = (sessionId) => { const token = crypto.randomBytes(32).toString('hex'); database.session[sessionId].csrfToken = token; return token; }; // `HTML` 응답에 토큰 포함 const index = (req, res) => { const sid = parseCookie(req).sid || ''; const userAccount = database.session[sid]; // CSRF 토큰 생성 const csrfToken = userAccount ? generateCSRFToken(sid) : ''; res.write(`
    `); }; // 요청 검증 const validateCSRFToken = (req) => { const sid = parseCookie(req).sid; const session = database.session[sid]; // 헤더 또는 바디에서 토큰 추출 const receivedToken = req.headers['x-csrf-token'] || req.body.csrf_token; // 세션의 토큰과 비교 // matthew.com에서 제공한 HTML에만 요 토큰이 있을 것이다 if (!session || session.csrfToken !== receivedToken) { throw new Error('❌ CSRF 토큰 검증 실패!'); } // 서버가 민감한 요청을 처리할 때 이 토큰이 요청 헤더에 실렸는지 확인하고 // 비즈니스 로직을 실행하도록 예방하는 것이다 return true; }; ``` 이렇게 `matthew.com`에서 제공한 HTML에만 있는 토큰을 네트워크 헤더에 실어서 보내면, 서버는 정상적인 요청이라고 판단할 수 있다. *** ### CSRF 토큰의 장점과 단점 실제로 CSRF 토큰을 구현하면서 느낀 장단점을 정리해보면: **✅ 장점 - 강력하고 유연한 보안** • **모든 브라우저 지원**: 레거시 브라우저에서도 완벽하게 작동\ • **이중 방어 가능**: SameSite 쿠키와 함께 사용하면 더욱 견고한 보안\ • **세밀한 제어**: 특정 액션이나 폼별로 다른 토큰 적용 가능\ • **검증된 방법**: 오랜 기간 사용되어 안정성이 입증됨 **❌ 단점 - 구현과 관리의 복잡성** • **구현 복잡도**: 토큰 생성, 저장, 검증 로직이 모두 필요\ • **개발 오버헤드**: 모든 폼과 AJAX 요청에 토큰을 수동으로 추가\ • **토큰 관리**: 세션별 토큰 저장과 만료 처리가 필요\ • **완벽하지 않음**: XSS 공격으로 토큰이 유출될 가능성 존재 *** ## 6. CAPTCHA - "너 로봇 아니지?" 그래서 이게 정말 사람인지 로봇인지 확인해서 사이트를 보호하는 방법이 있는데, 바로 **CAPTCHA**입니다. `CAPTCHA`의 정식 명칭은... **Completely Automated Public Turing test to tell Computers and Humans Apart** 🤯 네, 저도 압니다. 너무 깁니다. 그냥 "사람과 컴퓨터를 구별하는 자동화된 테스트"라고 생각하시면 된다. 여러분도 한 번쯤은 겪어보셨을 거예요: * "신호등이 있는 사진을 모두 선택하세요" * "횡단보도가 보이는 칸을 클릭하세요" * "이 흐릿한 글자가 뭔지 맞춰보세요" (요즘은 거의 안 보이죠) 사용자 입장에선 짜증나지만, 자동화된 봇 공격을 막는 데는 꽤 효과적입니다. 구글의 reCAPTCHA 같은 서비스를 통해 자동화된 공격을 차단할 수 있다: (이미지: Google reCAPTCHA 예시 - CAPTCHA는 이런 것을 의미해요) 사용하는 방법은 아래와 같다. 매우 간단한 예제로 직접 만들어보겠다: **reCAPTCHA v3 구현 예제:** ```javascript // 클라이언트 측 (HTML) const index = (req, res) => { res.write(`
    `); }; // 서버 측 검증 const verifyRecaptcha = async (token) => { const response = await fetch( 'https://www.google.com/recaptcha/api/siteverify', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: `secret=YOUR_SECRET_KEY&response=${token}`, } ); const data = await response.json(); // 점수가 0.5 이상이면 사람으로 판단 if (data.success && data.score > 0.5) { return true; } throw new Error('❌ reCAPTCHA 검증 실패: 봇으로 의심됨'); }; ``` *** ## 7. 마치며 솔직히 CSRF 공격이라는 게 처음엔 "이게 진짜 가능해?"싶었는데 직접 실습해보니 정말 간단한 `img` 태그 하나로도 공격이 가능한 것을 확인할 수 있었다. 무서운 건 사용자는 전혀 눈치채지 못한다는 것이다. 나도 처음엔 보안을 너무 빡빡하게 하려다가 사용자들이 "왜 이렇게 불편해요?"라는 피드백을 많이 받았다. 캡차 넣고 재인증 넣고... 결국 보안과 사용성 사이에서 균형을 찾는 게 제일 어려운 것 같다. 요즘은 AI가 캡차도 뚫는다고 하니 완벽한 보안은 정말 없는 것 같다. 결국 내가 생각하는 좋은 서비스는 사용자가 보안 기능이 있는지도 모르면서 안전하게 쓸 수 있는 서비스인 것 같다. 마치 자동차의 에어백처럼 평소엔 신경 안 쓰다가 필요할 때 알아서 작동하는 그런 보안이다. *** ## 핵심 정리 * **CSRF 공격 원리**: * 로그인한 사용자의 권한을 도용 * 악성 사이트에서 정상 사이트로 요청 전송 * 브라우저가 쿠키를 자동으로 첨부 * 피해자는 전혀 인지하지 못함 * **공격 방법**: * `` * `
    ` 자동 제출 * AJAX 요청 (단순 요청만 가능) * 1x1 픽셀 이미지로 숨김 * **방어 방법 1: SameSite 쿠키**: * `SameSite=Strict`: 같은 사이트에서만 쿠키 전송 * `SameSite=Lax`: GET 요청만 허용 (기본값) * `SameSite=None`: 모든 요청에 쿠키 전송 (Secure 필수) * 가장 간단하고 효과적인 방어법 * **방어 방법 2: CSRF 토큰**: * 서버가 랜덤 토큰 생성 → 세션에 저장 * HTML 폼에 hidden input으로 토큰 삽입 * 요청 시 토큰 검증 * 공격자는 토큰 값을 알 수 없음 * **방어 방법 3: Referer/Origin 검증**: * 요청의 출처 확인 * 다른 도메인에서 온 요청 차단 * 프록시 환경에서 Referer가 없을 수 있음 * **방어 방법 4: reCAPTCHA**: * 사람인지 봇인지 구별 * 중요한 작업(송금, 비밀번호 변경)에만 적용 * 사용자 경험 고려 필요 * **보안과 사용성의 균형**: * 너무 빡빡한 보안은 사용자 이탈 * 너무 느슨한 보안은 공격 위험 * 에어백처럼 필요할 때 자동으로 작동 * **실무 권장 조합**: * 필수: `SameSite=Lax` 쿠키 * 중요 작업: CSRF 토큰 추가 * 의심 행위: reCAPTCHA 적용 **CSRF 공격은 피싱 사기와 같다. 은행 직원을 사칭해서(정상 사이트 요청으로 위장) 피해자 몰래 계좌이체를 실행한다. SameSite 쿠키는 신분증 확인(같은 사이트인지 검증), CSRF 토큰은 일회용 비밀번호(공격자가 알 수 없는 값)와 같다.** --- # 세션 하이재킹 완벽 가이드 - 쿠키 탈취(XSS) 공격과 HttpOnly 방어법 > "로그인된 사용자의 세션을 훔쳐서 그 사람인 것처럼 행동할 수 있다면?" 웹 개발자라면 한 번쯤 이런 질문을 받아보셨을 것이다. 바로 세션 하이재킹(Session Hijacking)이라는 공격 기법이다. 이번 포스트에서는 Node.js로 직접 취약한 인증 시스템을 구현하고 실제 공... - 원문: https://www.yolog.co.kr/post/security-session-hijacking - 카테고리: HTTP - 발행: 2025-09-03 - 수정: 2025-09-03 "로그인된 사용자의 세션을 훔쳐서 그 사람인 것처럼 행동할 수 있다면?" 웹 개발자라면 한 번쯤 이런 질문을 받아보셨을 것이다. 바로 `세션 하이재킹(Session Hijacking)`이라는 공격 기법이다. 이번 포스트에서는 `Node.js`로 직접 취약한 인증 시스템을 구현하고 실제 공격을 시연한 후 방어 방법까지 단계별로 알아보겠다. (이미지: 세션 하이재킹 공격 시나리오) ## 1. 세션과 쿠키: 웹 인증의 기본 이해하기 ### HTTP는 상태가 없다(Stateless) `HTTP` 프로토콜은 **무상태(Stateless)** 특성을 가집니다. 즉, 서버는 이전 요청을 기억하지 못한다. 그렇다면 어떻게 로그인 상태를 유지할까요? **답은 세션(Session)과 [쿠키(Cookie)](https://www.yolog.co.kr/post/http-cookie)입니다.** ### 웹 인증 프로세스 1. **로그인 요청**: 사용자가 아이디/비밀번호 입력 2. **인증 검증**: 서버가 DB와 대조하여 신원 확인 3. **세션 생성**: 인증 성공 시 서버가 고유한 세션 ID 발급 4. **[쿠키](https://www.yolog.co.kr/post/http-cookie) 전송**: 세션 ID를 쿠키에 담아 브라우저로 전송 5. **상태 유지**: 이후 모든 요청에 [쿠키](https://www.yolog.co.kr/post/http-cookie)가 자동으로 포함됨 이제 이 과정을 코드로 직접 구현해보겠다. *** ## 2. 취약한 인증 시스템 구현하기 ### 기본 서버 구조와 세션 저장소 먼저 메모리 기반의 간단한 세션 저장소를 만들어보겠다: ```javascript const database = { products: ['군고구마', '고구마 아이스크림'], // 세션 저장소 추가 - 실제로는 Redis나 DB를 사용한다 session: {}, }; ``` ### 로그인 핸들러 구현 실제 서비스에서는 **bcrypt**, **jose** 같은 해싱 라이브러리를 사용하지만, 이해를 돕기 위해 간단하게 구현하겠다: ```javascript const login = (req, res) => { // 일단은 timestamp로 세션 아이디를 만듬 const createSession = () => `session-id-${Date.now()}`; // 사용자 찾는 함수 const findUser = () => ({ name: 'Matthew', email: 'dydals3440@gmail.com', }); const sid = createSession(); const user = findUser(); // 로그인 완료 -> 세션 정보 저장 database.session = { [sid]: user, }; // 참고: 301은 영구 리다이렉션이라 브라우저가 한 번 받으면 계속 캐시하는 특성이 있다. // 사용자한테는 "/"로 redirection하고 // 세션 아이디를 쿠키에 저장 res.statusCode = 302; res.setHeader('Location', '/'); res.setHeader('Set-Cookie', `sid=${sid}`); res.end(); }; // 라우팅 설정 const server = http.createServer((req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/login') return login(req, res); if (pathname === '/logout') return logout(req, res); if (pathname === '/product') return postProduct(req, res); index(req, res); }); server.listen(8080, () => { console.log('🚀 Server is running on http://localhost:8080'); }); ``` ### 쿠키 파싱 유틸리티 브라우저가 보낸 쿠키를 파싱하는 함수가 필요한다: ```javascript const parseCookie = (req) => { // 없을 수 도 있으니 fallback 처리 // 쿠키가 여러개 올 수 있으니 .split() const cookies = (req.headers.cookie || '').split(';'); // 순회하면서, 오브젝트로 만듬 const cookieObject = {}; cookies.forEach((cookie) => { const [name, value] = cookie.trim().split('='); // 조금 더 정확히할려면 decodeURIComponent 처리 if (name && value) { cookieObject[decodeURIComponent(name)] = decodeURIComponent(value); } }); // 완성된 쿠키 오브젝트 반환 return cookieObject; }; ``` ### 세션 기반 사용자 인증 확인 이제 `index` 페이지에서 세션을 확인하여 사용자 정보를 표시한다: ```javascript const index = (req, res) => { // sid를 쿠키로 부터 뽑아냄 // 쿠키를 객체형식으로 받음 없을 수 도 있으니 fallback 처리 const sid = parseCookie(req).sid || ''; // 그러면 이제 sid를 통해서 서버 DB 에서 세션 저장소를 조회 가능 // 인증된 유저라면 유저 정보가 있음. const userAccount = database.session[sid] || ''; // 이를 기반으로 동적 HTML 을 생성 res.setHeader('Content-Type', 'text/html'); res.write(` ${ userAccount ? `

    안녕하세요, ${userAccount.name}, ${userAccount.email}

    ` : '

    손님

    ' }
      ${database.products.map((product) => `
    • ${product}
    • `).join('')}
    `); res.end(); }; ``` ### 로그아웃 구현 세션을 삭제하고 쿠키를 제거하는 로그아웃 기능을 구현해보겠다: ```javascript // 해당 세션 아이디를 지우면 됨 const logout = (req, res) => { const sid = parseCookie(req)['sid'] || ''; delete database.session[sid]; // 301 으로 redirection 하고 // 쿠키에 있는 sid 삭제 res.statusCode = 302; res.setHeader('Location', '/'); res.setHeader('Set-Cookie', 'sid=;Max-Age=-1'); res.end(); }; ``` ### 실행 결과 서버를 실행하고 테스트해보겠다: ```bash node vulnerable-app.js # http://localhost:8080 접속 ``` **1. 초기 화면 (로그인 전)** (이미지: 루트 경로의 화면) **2. 로그인 후 화면** (이미지: 로그인 후 유저 정보가 보이는 화면) `/login` 경로 접속 시 세션이 생성되고, 사용자 정보가 표시된다. **3. 로그아웃 후 화면** (이미지: 로그아웃 후 유저 정보가 보이지 않는 화면) 로그아웃 시 `Max-Age=-1`로 쿠키가 즉시 만료되어 다시 손님 상태로 돌아갑니다. *** ## 3. 세션 하이재킹 공격 시연 이제 본격적으로 **세션 하이재킹 공격**을 시연해보겠다. ### [XSS](https://www.yolog.co.kr/post/security-xss)를 이용한 쿠키 탈취 시나리오 **공격 시나리오:** 1. 공격자가 [XSS](https://www.yolog.co.kr/post/security-xss) 취약점을 이용해 악성 스크립트 주입 2. 다른 사용자가 페이지 방문 시 스크립트 실행 3. 스크립트가 세션 쿠키를 공격자 서버로 전송 4. 공격자가 탈취한 세션으로 피해자 계정 접근 ### 공격자 서버 구축 먼저 탈취한 쿠키를 수집할 공격자 서버를 만들어보겠다: **attacker-server.js** ```javascript const http = require('http'); // 요청 URL을 로깅 // 탈취한 정보가 요청 URL로 옴. const log = (req, res) => console.log(`${req.method} ${req.url}`); const server = http.createServer((req, res) => { // 모든 요청을 기록한다. log(req, res); // CORS 헤더 추가 (크로스 오리진 요청 허용) res.setHeader('Access-Control-Allow-Origin', '*'); res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS'); res.setHeader('Access-Control-Allow-Headers', 'Content-Type'); // 빈 응답을 보냈다. res.end(); }); // 어플리케이션 서버와 다른 포트를 사용해 요청 대기 server.listen(8081, () => { console.log('Attacker server is running on port 8081'); }); ``` ### 로컬 DNS 설정 (실습 환경) 실제 공격 시나리오를 재현하기 위해 로컬 DNS를 설정한다: ```bash sudo vi /private/etc/hosts # 아래 내용 추가 127.0.0.1 matthew.com 127.0.0.1 hacker.com ``` (이미지: 로컬 DNS 설정) **matthew\.com**: 정상 서비스 도메인 (포트 8080) **hacker.com**: 공격자 서버 도메인 (포트 8081) ### [XSS](https://www.yolog.co.kr/post/security-xss) 취약점 활성화 실습을 위해 일시적으로 **이스케이프 처리를 제거**한다: > \[!WARNING] > **경고: 실제 서비스에서는 절대 이렇게 하지 마세요!** ```javascript const postProduct = (req, res) => { let body = ''; req.on('data', (chunk) => { body = body + chunk.toString(); }); req.on('end', () => { const { product } = queryString.parse(body); //// 임시 제거 // const escapedProduct = product // .replace(/&/g, '&') // .replace(//g, '>'); database.products.push(product); res.statusCode = 302; res.setHeader('Location', '/'); res.end(); }); }; ``` ### 공격 실행 이제 두 서버를 모두 실행하고 공격을 시연해보겠다: ```bash # 터미널 1: 메인 서버 실행 node vulnerable-app.js # 터미널 2: 공격자 서버 실행 node attacker-server.js ``` **1단계: 로그인하여 세션 생성** * `http://matthew.com:8080/login` 접속 * 세션이 생성되고 쿠키가 브라우저에 저장됨 **2단계: 악성 스크립트 주입** 상품 입력란에 다음 악성 스크립트를 입력한다: ```html ``` (이미지: 악성 스크립트 주입) 이 스크립트는: 1. `document.cookie`로 현재 페이지의 **모든 쿠키**를 읽음 2. `fetch()`를 통해 공격자 서버로 **HTTP 요청** 전송 3. 쿠키 값을 **쿼리 파라미터**로 포함시킴 **3단계: 쿠키 탈취 확인** 브라우저 개발자 도구의 네트워크 탭을 확인하면: (이미지: 쿠키가 쿼리 문자열에 담겨 전달) 공격자 서버의 로그를 확인하면: (이미지: 해커 서버에 세션 정보가 로깅됨) > \[!WARNING] > **세션 ID가 성공적으로 탈취되었다!** 🚨 ### 탈취한 세션으로 계정 접근 이제 공격자는 `탈취한 세션 ID`를 사용해 **Matthew**의 세션을 가지고 있는 것처럼 행동할 수 있다: ```bash curl http://matthew.com:8080 -H "Cookie: sid=session-id-1756852495508" ``` 응답 결과: (이미지: 세션 정보를 활용한 무단 접근) **공격자가 Matthew의 계정에 완전히 접근했다!** 😱 이것이 바로 `세션 하이재킹(Session Hijacking)`입니다. > \[!NOTE] > **"하이재킹(Hijacking)"의 어원** > 운항 중인 비행기를 납치하는 것을 하이재킹이라고 부르듯이, 실행 중인 세션을 가로채는 이 공격을 `세션 하이재킹`이라고 부릅니다. *** ## 4. 세션 하이재킹 방어 전략 ### 방법 1: [XSS](https://www.yolog.co.kr/post/security-xss) 취약점 제거 가장 근본적인 해결책은 **[XSS 공격](https://www.yolog.co.kr/post/security-xss) 자체를 차단**하는 것입니다: ```javascript const postProduct = (req, res) => { // ... 생략 ... req.on('end', () => { const { product } = queryString.parse(body); // HTML 특수문자 이스케이프 처리 const escapedProduct = product .replace(/&/g, '&') // & → & .replace(//g, '>'); // > → > database.products.push(escapedProduct); // ... 생략 ... }); }; ``` ### 방법 2: HttpOnly 쿠키 플래그 **HttpOnly** 플래그는 JavaScript에서 쿠키 접근을 차단하는 강력한 방어 메커니즘입니다: **HttpOnly 플래그의 효과:** * `document.cookie`로 접근 불가 * [`XSS` 공격](https://www.yolog.co.kr/post/security-xss)으로부터 세션 쿠키 보호 * `HTTP` 요청에는 정상적으로 포함됨 이제 로그인 함수를 수정해보겠다: ```javascript const login = (req, res) => { const createSession = () => `session-id-${Date.now()}`; const findUser = () => ({ name: 'Matthew', email: 'dydals3440@gmail.com', }); const sid = createSession(); const user = findUser(); database.session = { [sid]: user, }; res.statusCode = 302; res.setHeader('Location', '/'); // HttpOnly 디렉티브 추가 res.setHeader('Set-Cookie', `sid=${sid}; HttpOnly`); res.end(); }; ``` ### HttpOnly 적용 후 결과 동일한 악성 스크립트를 주입해도: (이미지: HttpOnly 적용 후 쿠키 접근 차단) 네트워크 요청은 발생하지만 **쿠키 값이 비어있다**. 공격자 서버 로그: (이미지: 공격자 서버에 쿠키값이 전달되지 않음) **쿼리스트링에 쿠키값이 비어있다는 것을 확인할 수 있다.** *** ## 5. 추가적인 보안 강화 방법 ### 프로덕션에서 필수! 쿠키 보안 완전 정복 위에서 `HttpOnly` 하나만 추가했지만, 실제 서비스에서는 이것만으로는 부족한다. 아래와 같이 다양한 `쿠키 디렉티브`를 추가할 수 있다. ```javascript const login = (req, res) => { // ... 생략 ... // 👉 처음에는 이렇게만 했었는데... // res.setHeader('Set-Cookie', `sid=${sid}`); // 👉 보안 이슈 터지고 난 후... const cookieOptions = [ `sid=${sid}`, 'HttpOnly', // [XSS 공격](https://www.yolog.co.kr/post/security-xss) 방어 'Secure', // HTTPS에서만 전송 (개발 환경에서는 빼세요!) 'SameSite=Strict', // CSRF 공격 방어 'Path=/', // 특정 경로에서만 사용 'Max-Age=3600', // 1시간 후 자동 만료 (너무 길면 위험!) ].join('; '); res.setHeader('Set-Cookie', cookieOptions); res.end(); }; ``` ### 🎯 각 플래그가 막아주는 공격 > ⚠️ **중요**: SameSite는 CSRF를 "어느 정도" 막아주지만, 완벽한 방어는 아닙니다!\ > 진짜 CSRF 방어는 **CSRF 토큰**이나 **Custom Header 검증**이 필요한다. | 플래그 | 언제 쓰나요? | 막아주는 공격 | 주의사항 | | ------------ | ------------- | -------------------------------------------------------- | --------------------- | | **HttpOnly** | 필수! 무조건 써야함 | [XSS](https://www.yolog.co.kr/post/security-xss)로 쿠키 훔치기 | 개발자 도구에서도 안 보임 | | **Secure** | HTTPS 사용 시 필수 | 와이파이 해킹 | localhost에서는 제외 | | **SameSite** | 외부 링크가 있다면 | CSRF 공격 | Strict는 UX에 영향 줄 수 있음 | | **Max-Age** | 민감한 서비스라면 | 세션 고정 | 너무 짧으면 UX 나빠짐 | ### 🛡️ 더 강력한 보안을 위한 3가지 테크닉 #### 1. 예측 불가능한 세션 ID 만들기 ```javascript const crypto = require('crypto'); // ❌ 나쁜 예: timestamp만 사용 (예측 가능!) const badSession = () => `session-${Date.now()}`; // ✅ 좋은 예: 암호학적으로 안전한 랜덤 값 const createSecureSession = () => { return crypto.randomBytes(32).toString('hex'); // 결과: 64자리 랜덤 문자열 // "a4f8c9b2e1d7..." 같은 형태 }; ``` #### 2. 중요한 작업 시 세션 재생성 ```javascript // 💡 예시: 결제 전 세션 재생성 const processPayment = async (req, res) => { // 1. 기존 세션 확인 const oldSid = parseCookie(req).sid; const user = database.session[oldSid]; // 2. 새 세션으로 교체 (세션 고정 공격 방어) delete database.session[oldSid]; const newSid = createSecureSession(); database.session[newSid] = user; // 3. 결제 처리 await processUserPayment(user); // 4. 새 세션 쿠키 발급 res.setHeader('Set-Cookie', `sid=${newSid}; HttpOnly; Secure`); }; ``` #### 3. 비정상 접속 패턴 감지 ```javascript const validateSession = (req, sid) => { const session = database.session[sid]; // 🔍 의심스러운 패턴 체크 const suspicious = [ // IP 변경 (카페 WiFi → 집 WiFi 같은 경우도 있으니 주의) session.ip !== req.connection.remoteAddress, // User-Agent 변경 (브라우저 바뀐) session.userAgent !== req.headers['user-agent'], // 너무 빠른 요청 (봇 가능성) session.lastAccess && Date.now() - session.lastAccess < 100, ]; if (suspicious.some((check) => check)) { console.warn('🚨 의심스러운 세션 활동 감지!'); // 자동 로그아웃 또는 추가 인증 요구 return null; } return session; }; ``` *** ## 6. 실제로 쓰는 방어 전략 ### 실제로 해 볼 수 있는 다양한 방어 전략 **1. AWS WAF 설정 (월 $5부터 시작)** ```javascript // [XSS](https://www.yolog.co.kr/post/security-xss) 패턴 자동 차단 규칙 { "Name": "XSSProtection", "Statement": { "XssMatchStatement": { "FieldToMatch": { "AllQueryArguments": {} }, "TextTransformations": [{ "Type": "HTML_ENTITY_DECODE" }] } } } ``` **2. 세션 이상 행동 모니터링** ```javascript class SessionMonitor { async checkSuspiciousActivity(session) { // 🌍 위치 급변 (서울 → 뉴욕 10분 내?) const locationJump = await this.checkGeoLocation(session); // 📱 디바이스 변경 (iPhone → Android?) const deviceChange = this.checkDeviceFingerprint(session); // ⚡ 비정상 속도 (1초에 100번 요청?) const tooFast = this.checkAccessPattern(session); if (locationJump || deviceChange || tooFast) { // 🔒 자동 로그아웃 + 재인증 요구 this.forceReAuthentication(session); } } } ``` *** ## 마무리 ### 간단하게 정리 ```javascript // 1. 입력값 이스케이프 (필수!) const safe = input.replace(/[<>&"']/g, (c) => escapeMap[c]); // 2. HttpOnly 쿠키 (필수!) res.setHeader('Set-Cookie', 'sid=...; HttpOnly'); // 3. HTTPS 사용 시 Secure 추가 if (process.env.NODE_ENV === 'production') { cookieOptions += '; Secure'; } // 4. CSRF 방어를 위한 SameSite cookieOptions += '; SameSite=Strict'; // 5. 자동 로그아웃 (30분) cookieOptions += '; Max-Age=1800'; ``` ### 궁금한 내용들 정리 **Q: `JWT` 쓰면 세션 하이재킹에 대하여 안전한가요?** > A: 아니다. `JWT`도 쿠키나 `localStorage`에 저장하면 똑같이 탈취 가능하다. **Q: `HTTPS`만 쓰면 세션 하이재킹에 대하여 안전한가요?** > A: `네트워크 스니핑`은 막지만 [`XSS` 공격](https://www.yolog.co.kr/post/security-xss)은 막지 못한다. **Q: 개발 환경에서 `Secure` 플래그 때문에 쿠키가 안 보여요! 때문에 세션 하이재킹에 대하여 안전한가요?** > A: `localhost`는 예외적으로 `Secure` 없이도 동작한다. `개발/프로덕션`을 구분하여 처리할 수 있다. *** ## 핵심 정리 * **세션 하이재킹 원리**: * HTTP는 Stateless → 상태 유지를 위해 세션/쿠키 사용 * 공격자가 세션 ID를 탈취하면 피해자 행세 가능 * JavaScript로 `document.cookie` 접근 시 쿠키 탈취 가능 * **공격 방법**: * XSS 공격으로 악성 스크립트 주입 * `document.cookie`로 세션 쿠키 읽기 * 공격자 서버로 쿠키 전송 * 탈취한 쿠키로 피해자 행세 * **방어 방법 1: HttpOnly 쿠키**: * JavaScript에서 쿠키 접근 차단 * `Set-Cookie: sid=...; HttpOnly` * XSS 공격으로도 쿠키 탈취 불가 * 가장 기본적이고 필수적인 방어법 * **방어 방법 2: Secure 플래그**: * HTTPS에서만 쿠키 전송 * 네트워크 스니핑 공격 방어 * 프로덕션 환경에서 필수 * `Set-Cookie: sid=...; Secure` * **방어 방법 3: SameSite 쿠키**: * CSRF 공격 방어 * `SameSite=Strict`: 같은 사이트에서만 쿠키 전송 * `SameSite=Lax`: GET 요청만 허용 (기본값) * `SameSite=None`: Secure 필수 * **방어 방법 4: 세션 타임아웃**: * 일정 시간 후 자동 로그아웃 * `Max-Age=1800` (30분) * 탈취된 쿠키의 유효 시간 제한 * **JWT는 안전하지 않다**: * JWT도 쿠키/localStorage에 저장하면 탈취 가능 * XSS 공격에는 취약 * HttpOnly 쿠키에 저장하는 것이 안전 * **HTTPS만으로는 부족하다**: * 네트워크 스니핑은 막음 * XSS 공격은 막지 못함 * HttpOnly + Secure + SameSite 조합 필수 * **실무 권장 조합**: * 필수: HttpOnly 쿠키 * 프로덕션: Secure 플래그 * CSRF 방어: SameSite=Lax * 타임아웃: Max-Age 설정 * 추가: XSS 방어 (이스케이프, CSP) **세션 하이재킹은 신분증 도용과 같다. 공격자가 피해자의 신분증(세션 쿠키)을 훔쳐서 피해자인 척한다. HttpOnly는 신분증을 금고에 보관(JavaScript 접근 차단), Secure는 암호화 운송(HTTPS 전송), SameSite는 신분증 사용처 제한(같은 사이트만), 타임아웃은 신분증 유효기간(자동 만료)과 같다.** --- # XSS(Cross-Site Scripting) 크로스 사이트 스크립팅 공격이란? > "우리 서비스에 사용자가 아래와 같은 스크립트를 입력했는데 진짜 알림이 떴어요!" 단순한 CREATE 기능에서 발생한 이 문제는 XSS(Cross-Site Scripting)라는 심각한 보안 취약점이었다. 이번 포스트에서는 웹 개발자라면 반드시 알아야 할 XSS 공격의 원리부터 실... - 원문: https://www.yolog.co.kr/post/security-xss - 카테고리: HTTP - 발행: 2025-08-29 - 수정: 2025-08-29 "우리 서비스에 사용자가 아래와 같은 스크립트를 입력했는데 진짜 알림이 떴어요!" ```html ``` 단순한 `CREATE` 기능에서 발생한 이 문제는 `XSS(Cross-Site Scripting)`라는 심각한 보안 취약점이었다. 이번 포스트에서는 웹 개발자라면 반드시 알아야 할 `XSS` 공격의 원리부터 실제 방어 방법까지 실습을 통해 완벽하게 이해해보겠다. (이미지: XSS 공격으로부터 웹을 지키자) ## 1. XSS가 뭐길래 이렇게 위험한가? ### 간단한 실험: 당신의 웹사이트는 안전한가요? 여러분의 웹사이트 입력 폼에 아래 텍스트를 한 번 입력해보세요: ```html ``` 만약 알림창이 뜬다면? 축하한다. 여러분의 사이트는 `XSS` 공격에 취약한다. 🚨 ### XSS의 정의와 위험성 `XSS(Cross-Site Scripting)`는 공격자가 웹 애플리케이션에 악성 스크립트를 삽입해 다른 사용자의 브라우저에서 실행되도록 하는 공격입니다. **왜 위험한가?** * 🍪 **쿠키 탈취**: 사용자의 [세션 쿠키를 훔쳐 계정 탈취](https://www.yolog.co.kr/post/security-session-hijacking) * 📝 **피싱 공격**: 가짜 로그인 폼을 띄워 비밀번호 수집 * 🎭 **신원 도용**: 사용자 대신 악의적인 행동 수행 * 💣 **웹사이트 변조**: 페이지 내용을 마음대로 수정 *** ## 2. 실습으로 이해하는 XSS 공격 ### 취약한 웹 애플리케이션 만들기 먼저 XSS에 취약한 간단한 상품 목록 앱을 만들어보겠다: ```jsx const http = require('http'); const queryString = require('querystring'); // 메모리에 있는 데이터베이스 const database = { products: ['군고구마', '고구마 아이스크림'], }; // http 추가 요청 처리 const postProduct = (req, res) => { let body = ''; req.on('data', (chunk) => { body = body + chunk.toString(); }); req.on('end', () => { const { product } = queryString.parse(body); database.products.push(product); res.statusCode = 302; res.setHeader('Location', '/'); res.end(); }); }; // 루트 인덱스를 처리 할 핸들러 // index.html을 동적으로 만들 것임 (데이터 베이스 내용갖고) const index = (req, res) => { res.setHeader('Content-Type', 'text/html'); res.write(`
      ${database.products.map((product) => `
    • ${product}
    • `).join('')}
    `); res.end(); }; const server = http.createServer((req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/product') return postProduct(req, res); index(req, res); }); server.listen(8080, () => { console.log('Server is running on port 8080'); }); ``` ### XSS 공격 시연 서버를 실행하고 브라우저에서 접속해보겠다: ```bash node vulnerable-app.js # http://localhost:8080 접속 ``` 정상적으로 상품을 추가하면 잘 작동한다: (이미지: 간단하게 만든 서버에 추가해보기) 하지만 악의적인 사용자가 다음과 같은 스크립트를 입력한다면 어떻게 될까요? ```html ``` 놀랍게도 실제 `JavaScript` 코드가 실행된다! (이미지: 실제로 Input에 스크립트 주입하면 어떻게 될까?) **무슨 일이 일어난 건가요?** 1. 사용자가 입력한 스크립트 태그가 그대로 데이터베이스에 저장됨 2. HTML을 생성할 때 `${product}`로 그대로 출력 3. 브라우저가 이를 실제 `JavaScript` 코드로 해석하여 실행 이것이 바로 **Stored XSS** 공격입니다. 한 번 저장되면 모든 사용자가 영향을 받게 된다. *** ## 3. XSS 방어 전략 ### 방법 1: HTML Sanitization (정화) `Sanitize`는 "살균 처리"라는 뜻으로, 위험한 `HTML` 태그와 `JavaScript`를 제거하는 방법입니다. 가장 신뢰받는 라이브러리인 `DOMPurify`를 사용해보겠다: ```javascript const DOMPurify = require('isomorphic-dompurify'); // 위험한 HTML const dirtyHTML = '

    안녕하세요

    '; // 정화 처리 const cleanHTML = DOMPurify.sanitize(dirtyHTML); console.log(cleanHTML); //

    안녕하세요

    // script 태그가 완전히 제거됨! ``` **DOMPurify Playground에서 직접 테스트해보세요:** (이미지: DOM Purify를 통해서 처리된 결과) ### 방법 2: HTML 이스케이프 처리 하지만 때로는 사용자가 입력한 내용을 그대로 보여주되, `HTML`로 해석되지 않게 하고 싶을 때가 있다. 예를 들어, 사용자가 `

    왕 고구마

    `를 입력했다고 해봅시다: (이미지: HTML 코드를 Input에 입력하면 어떻게 될까?) 브라우저가 이를 `HTML`로 해석해서 큰 제목으로 보여주는데, 이는 우리가 원한 것이 아닙니다. **해결책: 이스케이프(Escape) 처리** `HTML` 특수 문자를 브라우저가 해석할 수 없는 문자로 변환한다: ```html

    왕 고구마

    <h1>왕 고구마</h1> ``` **주요 이스케이프 문자:** * `<` → `<` (Less Than) * `>` → `>` (Greater Than) * `&` → `&` (Ampersand) * `"` → `"` (Quote) * `'` → `'` (Apostrophe) 이제 우리 코드에 이스케이프 처리를 적용해보겠다: ```tsx req.on('end', () => { const { product } = queryString.parse(body); const escapedProduct = product .replace(/&/g, '&') // & 문자를 &로 치환 (반드시 첫 번째로 실행!) .replace(//g, '>'); // > 문자를 >로 치환 database.products.push(escapedProduct); res.statusCode = 302; res.setHeader('Location', '/'); res.end(); }); ``` **왜 `&`를 먼저 치환해야 할까요?** `&`는 `HTML` 엔티티의 시작 문자입니다. 만약 `<`를 먼저 `<`로 치환한 후 `&`를 치환하면: * `<` → `<` → `&lt;` (잘못된 이중 이스케이프!) 올바른 순서로 치환하면: * `&` → `&` (먼저 실행) * `<` → `<` (이미 치환된 & 문자는 영향받지 않음) (이미지: HTML 코드를 이스케이프 처리 후 출력) **결과를 확인해보면:** 이제 `

    왕 고구마

    `가 그대로 텍스트로 출력된다! 이렇게 하면 브라우저가 이를 `HTML`로 해석하지 않고 그대로 텍스트로 출력한다. ### 실무에서 자주 사용하는 이스케이프 함수 **lodash의 `_.escape` 함수 구현:** ```javascript // lodash의 _.escape 함수 구현 방식 const escapeHtmlChar = { '&': '&', '<': '<', '>': '>', '"': '"', "'": ''', }; function lodashEscape(string) { // 정규표현식으로 특수문자를 찾아서 치환 return string && string.replace(/[&<>"']/g, (char) => escapeHtmlChar[char]); } // 사용 예시 console.log(lodashEscape('')); // 출력: <script>alert("XSS")</script> ``` *** ## 4. XSS 공격의 본질 이해하기 ### 왜 "Cross-Site" Scripting인가? `XSS`의 핵심은 신뢰할 수 없는 출처의 스크립트가 신뢰받는 사이트에서 실행되는 것이다. ```javascript // 공격 시나리오 // 1. 해커가 악성 스크립트를 우리 사이트에 주입 // 2. 다른 사용자가 우리 사이트 방문 // 3. 브라우저는 우리 사이트를 신뢰하므로 스크립트 실행 // 4. 사용자 정보 탈취 성공! ``` ### XSS로 가능한 공격들 `XSS`는 단순한 `alert`창을 띄우는 것 이상의 심각한 공격이 가능하다: 1. 🍪 [세션 하이재킹](https://www.yolog.co.kr/post/security-session-hijacking): 쿠키를 훔쳐 사용자 계정 탈취 2. 🎣 피싱 공격: 가짜 로그인 창으로 비밀번호 수집 3. 📸 키로거: 키보드 입력 모니터링 4. 🔄 리다이렉트: 악성 사이트로 자동 이동 5. 💾 정보 유출: 개인정보, 결제정보 등 탈취 이러한 고급 공격 기법들은 [세션 하이재킹](https://www.yolog.co.kr/post/security-session-hijacking) 포스트에서 실습을 통해 자세히 다루고 있다. *** ## 핵심 정리 * **XSS 공격 원리**: * 신뢰할 수 없는 스크립트가 신뢰받는 사이트에서 실행 * 사용자 입력을 그대로 HTML에 삽입하면 취약 * 브라우저는 정상 스크립트와 악성 스크립트를 구별 불가 * **XSS 공격 유형**: * Stored XSS: DB에 저장된 스크립트가 모든 사용자에게 실행 * Reflected XSS: URL 파라미터로 전달된 스크립트가 즉시 실행 * DOM-based XSS: JavaScript로 DOM을 조작할 때 발생 * **공격 가능한 것들**: * 세션 쿠키 탈취 (`document.cookie`) * 가짜 로그인 폼으로 피싱 * 키보드 입력 모니터링 * 악성 사이트로 리다이렉트 * 개인정보, 결제정보 유출 * **방어 방법 1: 이스케이프(Escape)**: * `<` → `<`, `>` → `>` * HTML 특수 문자를 텍스트로 변환 * 스크립트 코드가 실행되지 않음 * **방어 방법 2: 새니타이즈(Sanitize)**: * 허용된 HTML 태그만 남기고 제거 * DOMPurify 같은 라이브러리 사용 * 화이트리스트 방식으로 안전한 태그만 허용 * **방어 방법 3: CSP(Content Security Policy)**: * HTTP 헤더로 허용할 스크립트 출처 지정 * `Content-Security-Policy: default-src 'self'` * 인라인 스크립트 차단 * **React의 자동 방어**: * JSX는 자동으로 값을 이스케이프 * `dangerouslySetInnerHTML`은 예외 (주의 필요) * 사용자 입력을 직접 HTML로 렌더링하지 않음 * **실무 권장 조합**: * 필수: 사용자 입력 이스케이프 * 리치 에디터: 새니타이즈 (DOMPurify) * 추가: CSP 헤더 설정 * 검증: 정기적인 보안 테스트 **XSS 공격은 위조 화폐와 같다. 진짜(정상 스크립트)처럼 보이지만 실제로는 가짜(악성 스크립트)다. 이스케이프는 위조 화폐 감별기(특수 문자 변환), 새니타이즈는 은행의 검수 과정(안전한 것만 허용), CSP는 현금 출처 확인(허용된 출처만 실행)과 같다.** *** --- # WebSocket - 실시간 채팅 구현부터 HTTP와의 차이점까지 > 웹 개발자라면 실시간 채팅, 주식 시세, 게임 같은 기능을 구현할 때 HTTP의 한계를 느껴봤을 것이다. HTTP는 클라이언트가 요청하면 서버가 응답하는 단방향 통신이다. 실시간 양방향 통신이 필요할 때는 어떻게 해야 할까? 이번 포스트에서는 HTTP의 한계를 극복하고 진정한 실시... - 원문: https://www.yolog.co.kr/post/http-websocket - 카테고리: HTTP - 발행: 2025-08-27 - 수정: 2025-08-27 웹 개발자라면 실시간 채팅, 주식 시세, 게임 같은 기능을 구현할 때 HTTP의 한계를 느껴봤을 것이다. HTTP는 클라이언트가 요청하면 서버가 응답하는 단방향 통신이다. 실시간 양방향 통신이 필요할 때는 어떻게 해야 할까? 이번 포스트에서는 HTTP의 한계를 극복하고 진정한 실시간 양방향 통신을 가능하게 하는 WebSocket 프로토콜을 깊이 있게 살펴보겠다. (이미지: 고구마 매출을 올릴려면 웹소켓도 필요해) ## 1. WebSocket이 필요한 이유 ### HTTP의 한계 HTTP는 요청-응답 구조의 단방향 통신이다. 서버는 클라이언트의 요청 없이는 데이터를 보낼 수 없다. 실시간 통신을 위해 [폴링(Polling)](https://www.yolog.co.kr/post/http-polling), [롱 폴링(Long Polling)](https://www.yolog.co.kr/post/http-long-polling), [SSE(Server-Sent Events)](https://www.yolog.co.kr/post/http-sse) 같은 기법들을 사용했지만, 이들은 모두 HTTP의 단방향 특성을 완전히 극복하지는 못한다. ### WebSocket의 등장 WebSocket은 HTTP와 마찬가지로 [TCP](https://www.yolog.co.kr/post/http-tcp) 위에서 동작하는 애플리케이션 계층 프로토콜이다. 하지만 한 가지 큰 차이점이 있다: * **HTTP**: 요청 → 응답 → 연결 종료 (단방향) * **WebSocket**: 연결 유지 → 양방향 통신 가능 마치 편지(HTTP)와 전화(WebSocket)의 차이와 같다. 편지는 보내고 받으면 끝이지만, 전화는 한 번 연결하면 계속 대화할 수 있다. *** ## 2. WebSocket 핸드셰이크: HTTP에서 WebSocket으로 브라우저와 서버는 처음에는 HTTP로 통신을 시작한다. 그리고 서로 합의하에 WebSocket으로 프로토콜을 전환한다. 이 과정을 `WebSocket 핸드셰이크`라고 한다. (이미지: 핸드셰이크 짝 👏🏻) ### 핸드셰이크 과정 상세 분석 먼저 간단한 WebSocket 서버를 만들어보겠다: ```bash npm i ws # WebSocket 라이브러리 설치 ``` ### 기본 WebSocket 서버 구현 ```js // websocket-server.js const { WebSocketServer } = require('ws'); // WebSocket 서버 인스턴스 생성 const wss = new WebSocketServer({ port: 8080 }); // 클라이언트 연결 이벤트 처리 wss.on('connection', (ws) => { console.log('새로운 클라이언트 연결됨'); // 연결 시 환영 메시지 전송 ws.send('환영한다! WebSocket 서버에 연결되었다.'); // 클라이언트로부터 메시지 수신 ws.on('message', (data) => { console.log('받은 메시지:', data.toString()); // 받은 메시지를 그대로 에코백 ws.send(`Echo: ${data.toString()}`); }); // 연결 종료 처리 ws.on('close', () => { console.log('클라이언트 연결 종료'); }); }); console.log('WebSocket 서버가 8080 포트에서 실행 중...'); ``` ### 핸드셰이크 과정 직접 확인하기 WebSocket은 일반 curl로는 테스트하기 어렵다. macOS/Linux에서는 `netcat(nc)` 명령어를 사용해 [TCP](https://www.yolog.co.kr/post/http-tcp) 메시지를 직접 보낼 수 있다: ```bash # netcat 설치 확인 which nc # /usr/bin/nc # WebSocket 핸드셰이크 요청 보내기 nc localhost 8080 -c ``` 직접 HTTP 요청을 입력해 WebSocket 핸드셰이크를 시도해봅시다: ```http GET / HTTP/1.1 Host: localhost:8080 Connection: Upgrade # 연결 업그레이드 요청 Upgrade: websocket # WebSocket으로 전환 Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ== # 보안 키 Sec-WebSocket-Version: 13 # WebSocket 버전 ``` ### 핸드셰이크 응답 분석 서버로부터 다음과 같은 응답을 받게 된다: ```http HTTP/1.1 101 Switching Protocols # 101: 프로토콜 전환 승인 Upgrade: websocket # WebSocket으로 업그레이드 Connection: Upgrade # 연결 업그레이드 확인 Sec-WebSocket-Accept: [해시값] # 클라이언트 키의 검증 값 ``` (이미지: netcat 명령어를 활용한 응답 확인) **핵심 포인트:** * [`101 Switching Protocols`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/101): HTTP 상태 코드 중 100번대는 정보성 응답이다. 101은 프로토콜 전환을 승인한다는 의미 * 이 응답 이후부터는 HTTP가 아닌 WebSocket 프로토콜로 통신 * HTTP는 메시지 단위로 통신하지만, WebSocket은 프레임 단위로 통신 마치 일반 도로(HTTP)를 달리던 차량이 고속도로(WebSocket)로 진입하는 것과 같다. 한 번 진입하면 빠른 속도로 계속 달릴 수 있다. *** ## 3. 브라우저에서 WebSocket 사용하기 브라우저는 WebSocket을 위한 전용 API를 제공한다. 이 API를 사용하면 자동으로 핸드셰이크를 수행하고 실시간 통신을 할 수 있다. ### 브라우저 WebSocket API 기본 사용법 브라우저 콘솔에서 직접 WebSocket 연결을 테스트해보겠다: ```js // 브라우저 콘솔에서 실행 const ws = new WebSocket('ws://localhost:8080'); // 연결 성공 시 ws.onopen = () => { console.log('WebSocket 연결 성공!'); ws.send('안녕하세요, WebSocket 서버!'); }; // 메시지 수신 시 ws.onmessage = (event) => { console.log('받은 메시지:', event.data); }; // 연결 종료 시 ws.onclose = () => { console.log('WebSocket 연결 종료'); }; // 에러 발생 시 ws.onerror = (error) => { console.error('WebSocket 에러:', error); }; ``` (이미지: 브라우저 console에서 웹소켓 연결 요청) ### Network 탭에서 WebSocket 통신 확인 개발자 도구의 Network 탭에서 WebSocket 연결을 아래와 같이 확인할 수 있다. (이미지: 브라우저 network 탭에서 웹소켓 연결 확인) * **Status**: 101 Switching Protocols 확인 가능 * **Headers**: Upgrade: websocket, Sec-WebSocket-Key, Sec-WebSocket-Version 등 확인 * **Messages**: 실시간으로 주고받는 메시지 확인 가능 (이미지: 브라우저 Messages 에서 주고받은 메시지 확인) *** ## 4. HTTP + WebSocket 하이브리드 서버 구현 실제 서비스에서는 HTTP 서버와 WebSocket 서버를 함께 운영하는 경우가 많다. 하나의 포트에서 HTTP와 WebSocket을 모두 처리하는 서버를 만들어보겠다. ### HTTP 서버에 WebSocket 기능 추가하기 WebSocket 라이브러리는 기존 HTTP 서버와 결합할 수 있는 인터페이스를 제공한다: ```js // hybrid-server.js const http = require('http'); const path = require('path'); const { WebSocketServer } = require('ws'); const static = require('../shared/serve-static'); // HTTP 요청 처리 핸들러 const handler = (req, res) => { // 정적 파일 제공 (HTML, CSS, JS 등) static(path.join(__dirname, 'public'))(req, res); }; // HTTP 서버 생성 const server = http.createServer(handler); // 서버 시작 server.listen(8080, () => { console.log('하이브리드 서버 실행 중:'); console.log('- HTTP: http://localhost:8080'); console.log('- WebSocket: ws://localhost:8080'); }); // 기존 HTTP 서버에 WebSocket 기능 추가 const wss = new WebSocketServer({ server }); // WebSocket 연결 처리 wss.on('connection', (ws) => { console.log('새 WebSocket 클라이언트 연결'); // 환영 메시지 전송 ws.send('WebSocket 서버에 연결되었다!'); // 메시지 수신 처리 ws.on('message', (data) => { console.log('받은 메시지:', data.toString()); ws.send(`Echo: ${data.toString()}`); }); // 연결 종료 처리 ws.on('close', () => { console.log('WebSocket 클라이언트 연결 종료'); }); }); ``` **핵심 포인트:** * 하나의 포트(8080)에서 HTTP와 WebSocket 모두 처리 * 초기 연결은 HTTP로 시작, 필요시 WebSocket으로 업그레이드 * 정적 파일 제공과 실시간 통신을 동시에 지원 *** ## 5. 실시간 채팅 애플리케이션 구현 이제 WebSocket의 양방향 통신 특성을 활용해 실시간 채팅 애플리케이션을 만들어보겠다. ### 채팅 서버 구현 여러 클라이언트가 동시에 접속해서 메시지를 주고받을 수 있는 채팅 서버를 구현한다: ```js // chat-server.js const http = require('http'); const path = require('path'); const { WebSocketServer } = require('ws'); const static = require('../shared/serve-static'); const Message = require('../shared/message'); // 연결된 모든 클라이언트를 저장하는 배열 let webSocketClients = []; // HTTP 요청 처리 const handler = (req, res) => { static(path.join(__dirname, 'public'))(req, res); }; // HTTP 서버 생성 및 시작 const server = http.createServer(handler); server.listen(8080, () => { console.log('채팅 서버가 8080 포트에서 실행 중...'); }); // WebSocket 서버 생성 const wss = new WebSocketServer({ server }); // 새로운 클라이언트 연결 처리 wss.on('connection', (ws) => { // 환영 메시지 생성 및 전송 const welcomeMessage = new Message('채팅방에 입장했다.'); ws.send(JSON.stringify(welcomeMessage)); // 연결된 클라이언트 목록에 추가 webSocketClients.push(ws); // 다른 클라이언트들에게 입장 알림 broadcast(ws, '새로운 사용자가 입장했다.', true); // 클라이언트로부터 메시지 수신 ws.on('message', (data) => { const messageText = data.toString('utf-8'); // 모든 클라이언트에게 메시지 전달 (브로드캐스트) for (const client of webSocketClients) { // 연결이 열려있는 클라이언트에게만 전송 if (client.readyState === ws.OPEN) { const prefix = client === ws ? '나' : '상대방'; const text = `${prefix}: ${messageText}`; const message = new Message(text); // JSON 형식으로 메시지 전송 client.send(JSON.stringify(message)); } } }); // 연결 종료 처리 ws.on('close', () => { // 클라이언트 목록에서 제거 webSocketClients = webSocketClients.filter((client) => client !== ws); // 다른 클라이언트들에게 퇴장 알림 broadcast(null, '사용자가 퇴장했다.', true); }); }); // 브로드캐스트 헬퍼 함수 function broadcast(sender, text, isSystemMessage = false) { const message = new Message(isSystemMessage ? `[시스템] ${text}` : text); webSocketClients.forEach((client) => { if (client !== sender && client.readyState === ws.OPEN) { client.send(JSON.stringify(message)); } }); } ``` **코드 설명:** * `webSocketClients`: 연결된 모든 클라이언트를 관리 * `broadcast`: 특정 메시지를 모든 클라이언트에게 전달 * `readyState`: WebSocket 연결 상태 확인 (OPEN, CLOSED 등) * JSON 형식으로 메시지를 구조화하여 전송 ### 채팅 클라이언트 구현 이제 사용자가 실제로 채팅을 할 수 있는 웹 인터페이스를 만들어보겠다. #### HTML 구조 ```html WebSocket 채팅
    ``` #### JavaScript 클라이언트 코드 ```js // script.js let webSocket; let messageContainer; // WebSocket 연결 초기화 const initWebSocket = () => { // 현재 페이지의 호스트를 사용하여 WebSocket 연결 const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:'; webSocket = new WebSocket(`${wsProtocol}//${location.host}`); // 연결 성공 webSocket.addEventListener('open', () => { console.log('WebSocket 연결 성공'); addSystemMessage('서버에 연결되었다.'); }); // 메시지 수신 webSocket.addEventListener('message', (event) => { try { const message = JSON.parse(event.data); renderMessage(message); } catch (error) { console.error('메시지 파싱 에러:', error); } }); // 연결 종료 webSocket.addEventListener('close', () => { console.log('WebSocket 연결 종료'); addSystemMessage('서버와의 연결이 끊어졌다.'); }); // 에러 처리 webSocket.addEventListener('error', (error) => { console.error('WebSocket 에러:', error); addSystemMessage('연결 중 오류가 발생했다.'); }); }; // 메시지 렌더링 const renderMessage = (message) => { const messageElement = document.createElement('div'); messageElement.className = 'message'; // 메시지 내용 const textSpan = document.createElement('span'); textSpan.className = 'message-text'; textSpan.textContent = message.text; // 타임스탬프 const timeSpan = document.createElement('span'); timeSpan.className = 'message-time'; const time = new Date(message.timestamp).toLocaleTimeString(); timeSpan.textContent = time; messageElement.appendChild(textSpan); messageElement.appendChild(timeSpan); messageContainer.appendChild(messageElement); // 스크롤을 최하단으로 messageContainer.scrollTop = messageContainer.scrollHeight; }; // 시스템 메시지 추가 const addSystemMessage = (text) => { const systemElement = document.createElement('div'); systemElement.className = 'system-message'; systemElement.textContent = text; messageContainer.appendChild(systemElement); messageContainer.scrollTop = messageContainer.scrollHeight; }; // 메시지 전송 기능 초기화 const initSendButton = () => { const sendButton = document.querySelector('#send-button'); const textField = document.querySelector('#text-field'); // 전송 함수 const sendMessage = () => { const text = textField.value.trim(); if (!text) return; // WebSocket이 열려있는지 확인 if (webSocket && webSocket.readyState === WebSocket.OPEN) { webSocket.send(text); textField.value = ''; } else { addSystemMessage('연결이 끊어졌다. 새로고침해주세요.'); } }; // 버튼 클릭 이벤트 sendButton.addEventListener('click', sendMessage); // Enter 키 이벤트 textField.addEventListener('keypress', (event) => { if (event.key === 'Enter') { sendMessage(); } }); }; // 초기화 const init = () => { messageContainer = document.querySelector('#messages'); initWebSocket(); initSendButton(); }; // DOM 로드 완료 후 실행 document.addEventListener('DOMContentLoaded', init); ``` **코드 설명:** * `initWebSocket()`: WebSocket 연결을 초기화하고 이벤트 핸들러 등록 * `renderMessage()`: 받은 메시지를 화면에 표시 * `addSystemMessage()`: 연결/종료 등 시스템 메시지 표시 * `sendMessage()`: 메시지 전송 및 연결 상태 확인 * Enter 키로도 메시지 전송 가능 ### 실행 결과 채팅 애플리케이션을 실행하면 다음과 같은 화면을 볼 수 있다: (이미지: 만든 웹 사이트로, 연결된 것을 확인) 여러 브라우저 탭이나 창을 열어서 실시간 채팅을 테스트할 수 있다: (이미지: 고구마를 좋아하는지 여부를 채팅으로 나누는 이야기 확인) 개발자 도구의 Network 탭 > WS(WebSocket) 필터를 선택하면 실시간으로 주고받는 메시지를 확인할 수 있다: (이미지: Messages 탭에서 메시지들을 확인할 수 있다.) 마치 카카오톡처럼 메시지를 보내는 즉시 상대방 화면에 표시된다. 이것이 바로 WebSocket의 양방향 실시간 통신이다. *** ## 6. WebSocket의 특징과 장단점 ### WebSocket의 핵심 특징 | 특징 | 설명 | | ---------- | ------------------------- | | **양방향 통신** | 클라이언트와 서버가 언제든지 메시지 전송 가능 | | **실시간성** | 프레임 단위로 즉시 메시지 전달 | | **효율성** | HTTP 헤더 오버헤드 없이 데이터만 전송 | | **지속 연결** | 한 번 연결하면 명시적으로 종료할 때까지 유지 | ### 장점 1. **낮은 레이턴시**: 연결이 유지되므로 즉각적인 데이터 전송 가능 2. **적은 오버헤드**: HTTP 헤더를 반복해서 보내지 않음 3. **실시간 양방향**: 서버 푸시와 클라이언트 요청이 자유로움 4. **TCP 연결 재사용**: [3-Way Handshake](https://www.yolog.co.kr/post/http-tcp)를 한 번만 수행 ### 단점 1. **재연결 로직 필요**: 연결이 끊기면 자동 재연결 기능을 직접 구현해야 함 2. **서버 리소스**: 각 연결마다 메모리와 CPU 사용 3. **프록시/방화벽 이슈**: 일부 네트워크 환경에서 차단될 수 있음 4. **스케일링 복잡도**: 여러 서버 간 상태 동기화 필요 *** ## 7. HTTP 통신 기법 비교 이제 우리가 학습한 모든 HTTP 통신 기법을 비교해보겠다: | 기법 | 통신 방향 | 실시간성 | 효율성 | 복잡도 | 사용 사례 | | ------------------------------------------------------------------------ | -------- | ----- | ----- | --- | ------------- | | **[폴링(Polling)](https://www.yolog.co.kr/post/http-polling)** | 단방향 | 낮음 | 낮음 | 낮음 | 주기적 데이터 갱신 | | **[롱 폴링(Long Polling)](https://www.yolog.co.kr/post/http-long-polling)** | 단방향 | 중간 | 중간 | 중간 | 실시간 알림 | | **[SSE(Server-Sent Events)](https://www.yolog.co.kr/post/http-sse)** | 서버→클라이언트 | 높음 | 높음 | 낮음 | 실시간 피드, 알림 | | **WebSocket** | 양방향 | 매우 높음 | 매우 높음 | 높음 | 채팅, 게임, 협업 도구 | ### 각 기법의 선택 기준 #### [폴링](https://www.yolog.co.kr/post/http-polling)을 선택해야 할 때 * 실시간성이 크게 중요하지 않은 경우 * 구현이 간단해야 하는 경우 * 서버 부하가 예측 가능해야 하는 경우 #### [롱 폴링](https://www.yolog.co.kr/post/http-long-polling)을 선택해야 할 때 * 실시간 알림이 필요하지만 빈도가 낮은 경우 * WebSocket을 지원하지 않는 환경 * 단방향 서버 푸시만 필요한 경우 #### [SSE](https://www.yolog.co.kr/post/http-sse)를 선택해야 할 때 * 서버에서 클라이언트로의 단방향 스트리밍이 필요한 경우 * 자동 재연결이 필요한 경우 * 텍스트 기반 데이터를 전송하는 경우 #### WebSocket을 선택해야 할 때 * 진정한 실시간 양방향 통신이 필요한 경우 * 채팅, 게임 등 즉각적인 상호작용이 중요한 경우 * 바이너리 데이터 전송이 필요한 경우 *** ## 마치며 WebSocket은 2011년 RFC 6455로 표준화된 이후, 웹 애플리케이션의 실시간 통신 패러다임을 완전히 바꿔놓았다. HTTP의 요청-응답 모델이라는 근본적 한계를 극복하고, 진정한 양방향 통신을 가능하게 만든 것이다. 이번 시리즈를 통해 살펴본 4가지 실시간 통신 기법은 각각의 진화 과정을 보여준다: 1. **[폴링](https://www.yolog.co.kr/post/http-polling)**: 단순하지만 비효율적인 첫 번째 시도 2. **[롱 폴링](https://www.yolog.co.kr/post/http-long-polling)**: 리소스를 절약하려는 개선된 접근 3. **[SSE](https://www.yolog.co.kr/post/http-sse)**: 서버 푸시에 특화된 표준화된 솔루션 4. **WebSocket**: 완전한 양방향 통신을 위한 프로토콜 레벨의 혁신 실제 프로덕션 환경에서는 "가장 좋은 기술"이 아닌 "가장 적합한 기술"을 선택해야 한다. 실시간 통신이 정말 필요한지, 필요하다면 어느 정도의 실시간성이 요구되는지를 먼저 고민해보는 자세가 중요하다. 이 시리즈가 여러분의 실시간 웹 애플리케이션 개발 여정에 나침반이 되었기를 바란다. ## 핵심 정리 * **WebSocket이란**: TCP 위에서 동작하는 양방향 실시간 통신 프로토콜 * **핸드셰이크**: HTTP로 시작해서 101 Switching Protocols로 WebSocket으로 전환 * **핵심 특징**: * 양방향 통신: 클라이언트와 서버가 언제든지 메시지 전송 가능 * 실시간성: 프레임 단위로 즉시 메시지 전달 * 지속 연결: 한 번 연결하면 명시적으로 종료할 때까지 유지 * 낮은 오버헤드: HTTP 헤더를 반복해서 보내지 않음 * **브라우저 API**: new WebSocket(), onopen, onmessage, onclose, onerror * **하이브리드 서버**: 하나의 포트에서 HTTP와 WebSocket 모두 처리 가능 * **실무 활용**: 실시간 채팅, 게임, 협업 도구, 주식 시세 * **기술 선택**: * 폴링: 실시간성 낮음, 구현 단순 * 롱 폴링: 레거시 환경, 프록시 제약 * SSE: 서버→클라이언트 단방향 * WebSocket: 양방향, 초저지연, 바이너리 데이터 **WebSocket은 편지(HTTP)와 전화의 차이와 같다. 편지는 보내고 받으면 끝이지만, 전화는 한 번 연결하면 계속 대화할 수 있다. 일반 도로에서 고속도로로 진입하듯, 한 번 연결하면 빠른 속도로 계속 달릴 수 있다.** --- # HTTP 통신 기법 - SSE(Server-Sent Events) 이해와 구현 > Server-Sent Events는 HTML5 명세에 정의된 기술로, 서버가 클라이언트로 단방향 실시간 데이터를 전송하는 프로토콜이다. WebSocket과 달리 여전히 HTTP로 동작하며, 서버에서 클라이언트로만 메시지를 보낼 수 있다. Server-Sent Events는 서버가... - 원문: https://www.yolog.co.kr/post/http-sse - 카테고리: HTTP - 발행: 2025-08-26 - 수정: 2025-08-26 (이미지: SSE) ## SSE란? Server-Sent Events는 HTML5 명세에 정의된 기술로, 서버가 클라이언트로 단방향 실시간 데이터를 전송하는 프로토콜이다. [WebSocket](https://www.yolog.co.kr/post/http-websocket)과 달리 여전히 HTTP로 동작하며, 서버에서 클라이언트로만 메시지를 보낼 수 있다. ### 핵심 개념 Server-Sent Events는 서버가 특별한 HTTP 응답 헤더 값을 응답에 싣는 것으로 시작한다. ```http Content-Type: text/event-stream ``` 브라우저는 [`Content-Type: text/event-stream`](https://developer.mozilla.org/ko/docs/Web/API/Server-sent_events) 헤더를 보고 "서버가 언제든지 메시지를 보낼 수 있구나"라고 이해한다. ### 이벤트 스트림 형식 ```http < data: 고구마 data: 고구마 아이스크림 ``` * 각 이벤트는 개행문자로 구분 * 하나의 이벤트는 빈 줄로 종료 *** ## 이벤트 필드 Server-Sent Events는 다양한 필드를 제공한다 ([MDN 문서](https://developer.mozilla.org/ko-KR/docs/Web/API/Server-sent_events/Using_server-sent_events)): ### 필드별 설명 | 필드 | 설명 | 예시 | | ------- | ------------------ | ------------------------ | | `data` | 전송할 메시지 데이터 | `data: {"msg": "hello"}` | | `id` | 이벤트 식별자 (재연결 시 사용) | `id: 12345` | | `event` | 이벤트 타입 지정 | `event: userconnect` | | `retry` | 재연결 시도 간격 (밀리초) | `retry: 10000` | ```http retry: 10000 id: 1756035473112 event: message data: {"text":"고구마","timestamp":1756035473112} ``` *** ## 비유로 이해하기 라디오 방송을 생각해보자. 방송국(서버)은 계속 전파를 송출하고, 청취자(클라이언트)는 주파수를 맞춰두면 실시간으로 방송을 들을 수 있다. 청취자가 방송국에 요청할 순 없지만, 방송국의 모든 소식을 놓치지 않고 받을 수 있다. ## 효율성과 제약사항 ### 폴링 대비 장점 * **네트워크 효율**: 서버에 변화가 있을 때만 데이터 전송 * **서버 자원 절약**: 불필요한 요청/응답 사이클 제거 * **클라이언트 부담 감소**: 반복 요청 불필요 ### 제약사항 * **단방향 통신**: 서버→클라이언트만 가능 (양방향은 [WebSocket](https://www.yolog.co.kr/post/http-websocket) 필요) * **연결 생명주기**: 브라우저 탭 닫으면 연결 종료 * **유지 비용**: 연결 유지에 따른 리소스 소비는 여전히 존재 실제 구현하면서 한번 알아보겠다. *** ## 서버 구현 ### 기본 구조 ```js const http = require('http'); const path = require('path'); const static = require('../shared/serve-static'); const Message = require('../shared/message'); let waitingClients = []; let message = null; // 클라이언트의 SSE 구독 처리 const subscribe = (req, res) => { // text/event-stream 헤더로 SSE 시작을 알림 res.setHeader('Content-Type', 'text/event-stream'); res.write('\n'); // 빈 줄로 헤더 종료 // response 객체를 대기열에 추가 (새 데이터 생길 때까지 유지) waitingClients.push(res); // 연결 종료 처리 (브라우저 탭 닫기, 네트워크 끊김 등) // 'close' 이벤트 발생 시 대기열에서 해당 클라이언트 제거 // 이렇게 하지 않으면 끊긴 연결에 계속 데이터를 보내려다 에러 발생 req.on('close', () => { waitingClients = waitingClients.filter((client) => client !== res); }); }; ``` 이렇게 구현을 해봤고, curl로 한번 요청을 해보겠다. ```bash curl http://localhost:8080/subscribe -v ``` ``` * Host localhost:8080 was resolved. * IPv6: ::1 * IPv4: 127.0.0.1 * Trying [::1]:8080... * Connected to localhost (::1) port 8080 > GET /subscribe HTTP/1.1 > Host: localhost:8080 > User-Agent: curl/8.7.1 > Accept: */* > * Request completely sent off < HTTP/1.1 200 OK < Content-Type: text/event-stream < Date: Sun, 24 Aug 2025 11:31:35 GMT < Connection: keep-alive < Keep-Alive: timeout=5 < Transfer-Encoding: chunked < ``` 응답으로 [`200 OK`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/200)를 받았고, `Content-Type`은 `text/event-stream`으로 되어있다. 서버가 응답 본문을 다 보내지 않아서, 계속 연결을 유지하고 있다. ### 메시지 업데이트 및 브로드캐스트 이번에는 새 메시지를 추가할 수 있는 update 함수를 만들어보겠다. ```js const update = (req, res) => { let body = ''; req.on('data', (chunk) => { body = body + chunk.toString(); }); req.on('end', () => { const { text } = JSON.parse(body); if (!text) { res.statusCode = 400; res.setHeader('Content-Type', 'application/json'); res.write(JSON.stringify({ error: 'text 필드를 채워주세요' })); res.end(); return; } message = new Message(text); // 대기 중인 모든 클라이언트에게 이벤트 전송 for (const waitingClient of waitingClients) { // 메시지를 이벤트 스트림 형식(data 필드)으로 전송 // 개행문자 2개로 이벤트 하나를 종료 waitingClient.write([`data: ${message}\n\n`].join('')); } // update 요청한 클라이언트에게는 일반 응답 res.write(`${message}`); res.end(); }); }; // 라우팅 핸들러 const handler = (req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/subscribe') return subscribe(req, res); if (pathname === '/update') return update(req, res); static(path.join(__dirname, 'public'))(req, res); }; const server = http.createServer(handler); server.listen(8080, () => console.log('server is running ::8080')); ``` ### 테스트 이렇게 구현을 하고 서버를 재실행하여, 한번 다시 subscribe로 구독을 해보겠다. ```bash curl http://localhost:8080/subscribe -v ``` 클라이언트는 아까와 동일하게 `text/event-stream`으로 응답을 받는다: ``` * Request completely sent off < HTTP/1.1 200 OK < Content-Type: text/event-stream < Date: Sun, 24 Aug 2025 11:36:46 GMT < Connection: keep-alive < Keep-Alive: timeout=5 < Transfer-Encoding: chunked < ``` 본문이 올 때까지 기다리고 있다. 다른 클라이언트를 하나 더 열어서 update API를 호출해보겠다: ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"고구마"}' -v ``` 그러면 기다리고 있던 첫번째 클라이언트에 본문이 도착한다: ``` data: {"text":"고구마","timestamp":1756035473112} ``` update API를 호출한 클라이언트도 JSON 응답을 받는다: ``` < HTTP/1.1 200 OK < Date: Sun, 24 Aug 2025 11:37:53 GMT < Connection: keep-alive < Keep-Alive: timeout=5 < Transfer-Encoding: chunked < {"text":"고구마","timestamp":1756035473112} ``` *** ## 클라이언트 구현 브라우저는 [`EventSource`](https://developer.mozilla.org/ko/docs/Web/API/EventSource) 클래스를 제공한다: ```js const subscribe = () => { // EventSource로 서버와 연결 (브라우저가 SSE 이벤트 수신 준비) const eventSource = new EventSource('/subscribe'); // 서버에서 data 필드 전송 시 message 이벤트 발생 eventSource.addEventListener('message', (event) => { // JSON 문자열 파싱 후 렌더링 render(JSON.parse(event.data)); }); }; const render = (message) => { const messageElement = document.createElement('div'); const { text } = message; const timestamp = new Date(message.timestamp).toLocaleTimeString(); messageElement.textContent = `${text} (${timestamp})`; document.body.appendChild(messageElement); }; const init = () => { subscribe(); }; // DOM 생성 완료 시 SSE 구독 시작 document.addEventListener('DOMContentLoaded', init); ``` (이미지: SSE 연결 성공) (이미지: 실제로 메시지를 받고도 계속해서 SSE 연결이 유지 됨) 브라우저에서는 서버로부터 새로운 알림이 도착했고, 네트워크 요청도 끊어지지 않고 계속 유지되고 있다. 클라이언트에서 한번 더 메시지를 보내보겠다: ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"고구마 아이스크림"}' -v ``` 응답: ``` < HTTP/1.1 200 OK < Date: Sun, 24 Aug 2025 11:47:01 GMT < Connection: keep-alive < Keep-Alive: timeout=5 < Transfer-Encoding: chunked < {"text":"고구마 아이스크림","timestamp":1756036021866} ``` (이미지: 두번째 메시지도 정상 수신됨을 확인할 수 있음) [폴링](https://www.yolog.co.kr/post/http-polling)이나 [롱폴링](https://www.yolog.co.kr/post/http-long-polling)과 비교했을 때, Server-Sent Events는 더 간단하게 구현할 수 있다. 한번 연결하면 계속 메시지를 받을 수 있다. 마치 구독한 유튜브 채널에서 새 영상이 올라오면 자동으로 알림을 받는 것과 같다. 계속 확인할 필요 없이 서버가 알아서 보내준다. *** ## 자동 재연결 기능 ### fetch와의 차이점 fetch를 사용할 때는 클라이언트의 요청으로 시작해서, 서버의 응답으로 HTTP 통신이 종료된다. 다시 연결하려면 fetch 함수를 다시 호출하는 코드를 직접 작성해야 한다. 하지만 `EventSource`는 연결이 끊기면 자동으로 재접속을 시도한다. 브라우저가 네트워크 문제로 서버와 연결이 끊기면, 이 객체는 일정 시간 후에 스스로 HTTP 요청을 다시 만든다. ### 1. 자동 재연결 동작 서버와 연결된 상태에서 서버를 종료시켜보겠다. (이미지: 서버 종료 후 자동 재연결 시도) 서버를 종료하면 브라우저는 기존 연결이 끊긴 것을 감지하고, 자동으로 새로운 요청을 생성한다. 서버가 꺼져있으니 실패하지만, 브라우저는 포기하지 않고 계속 재연결을 시도한다. (이미지: 서버 재실행 시 자동으로 연결 복구) 서버를 다시 실행하면 대기 중이던 요청이 성공하며 연결이 자동 복구된다. ### 2. 재연결 간격 설정 서버에서 `retry` 필드로 재연결 간격을 지정할 수 있다: ```js for (const waitingClient of waitingClients) { waitingClient.write( [ `retry: 10000\n`, // 10초 후 재연결 시도 `data: ${message}\n\n`, ].join('') ); } ``` 이제 서버를 다시 종료하면 기본값보다 늦게(10초 후) 재연결을 시도한다. ### 3. 누락 메시지 복구 (Last-Event-ID) 연결이 끊긴 동안 놓친 메시지를 받을 수 있는 방법이 있다. #### 서버: 이벤트 ID 전송 ```js for (const waitingClient of waitingClients) { waitingClient.write( [ `retry: 10000\n`, `id: ${message.timestamp}\n`, // 이벤트 식별자 `data: ${message}\n\n`, ].join('') ); } ``` #### 서버: 재연결 시 Last-Event-ID 처리 ```js const subscribe = (req, res) => { const lastEventId = req.headers['last-event-id']; if (lastEventId) { // 재연결: 놓친 메시지들을 전송 console.log('재연결 - 마지막 이벤트 ID:', lastEventId); // 실무에서는 lastEventId 이후의 메시지를 DB에서 조회하여 전송 } res.setHeader('Content-Type', 'text/event-stream'); res.write('\n'); waitingClients.push(res); }; ``` #### 동작 흐름 1. **첫 연결 시**: 서버 콘솔에 `lastEventId undefined` 출력 2. **서버 종료 후 재시작** 3. **브라우저 재연결 시도**: (이미지: Last-Event-ID 헤더 전송) 브라우저가 재연결할 때 Request Headers에 [`Last-Event-ID: 1756036714406`](https://developer.mozilla.org/ko/docs/Web/API/Server-sent_events/Using_server-sent_events#last_event_id)를 포함시킨다. 이는 마지막으로 받은 이벤트의 ID로, 서버가 놓친 메시지를 파악하는 기준이 된다. 4. **서버 콘솔 출력**: ```bash server is running ::8080 lastEventId 1756036714406 # 클라이언트가 마지막으로 받은 이벤트 ID ``` 서버는 이 ID 이후의 메시지들을 조회하여 클라이언트에게 전송하면 된다. *** ## 통신 기법 비교: Polling vs Long Polling vs Server-Sent Events | 구분 | [Polling](https://www.yolog.co.kr/post/http-polling) | [Long Polling](https://www.yolog.co.kr/post/http-long-polling) | Server-Sent Events | | ----------- | ---------------------------------------------------- | -------------------------------------------------------------- | ------------------------ | | **통신 방향** | 양방향 | 양방향 | 서버→클라이언트 단방향 | | **연결 유지** | 매번 새 연결 | 응답까지 유지 | 지속적 연결 유지 | | **실시간성** | 주기에 따라 지연 | 즉시 전달 | 즉시 전달 | | **네트워크 효율** | 낮음 (불필요한 요청 많음) | 중간 | 높음 (필요시만 전송) | | **서버 부담** | 낮음 | 중간 (연결 유지) | 중간 (연결 유지) | | **구현 복잡도** | 매우 간단 | 중간 | 간단 (EventSource API) | | **자동 재연결** | 수동 구현 | 수동 구현 | 자동 지원 | | **브라우저 지원** | 모든 브라우저 | 모든 브라우저 | IE 제외 대부분 | | **프로토콜** | HTTP | HTTP | HTTP (text/event-stream) | *** ## SSE 실무 활용 사례 ### 1. 실시간 알림 시스템 ```js // 서버: 새 알림 발생 시 eventSource.write( `data: ${JSON.stringify({ type: 'notification', title: '새 메시지', body: '김철수님이 메시지를 보냈다', })}\n\n` ); ``` ### 2. 대시보드 실시간 업데이트 * **주식 시세**: 실시간 가격 변동 스트리밍 * **모니터링**: 서버 메트릭, 에러 로그 실시간 표시 * **분석 대시보드**: 실시간 방문자 수, 매출 현황 ### 3. 라이브 피드 * **소셜 미디어**: Twitter, Facebook의 실시간 타임라인 * **뉴스 속보**: 실시간 뉴스 업데이트 * **스포츠 중계**: 실시간 점수 업데이트 ### 4. 진행 상태 알림 ```js // 서버: 파일 업로드 진행률 for (let progress = 0; progress <= 100; progress += 10) { client.write( `data: ${JSON.stringify({ type: 'progress', value: progress, })}\n\n` ); } ``` ### 5. 협업 도구 * **Google Docs**: 다른 사용자의 커서 위치, 편집 내용 * **Trello**: 카드 이동, 댓글 알림 * **Slack**: 타이핑 인디케이터, 온라인 상태 *** ## Server-Sent Events가 적합한 경우 vs 다른 기술 선택 ### Server-Sent Events를 선택해야 할 때 * ✅ **서버→클라이언트 단방향 통신**만 필요 * ✅ **HTTP 인프라**만 사용 가능한 환경 * ✅ **자동 재연결**이 중요한 서비스 * ✅ **텍스트 기반** 데이터 전송 * ✅ 구현 **단순성**이 중요 ### [WebSocket](https://www.yolog.co.kr/post/http-websocket)을 선택해야 할 때 * ⚡ **양방향 실시간 통신** 필요 (채팅, 게임) * ⚡ **바이너리 데이터** 전송 * ⚡ **초저지연**이 중요한 서비스 * ⚡ 높은 메시지 **빈도** (초당 수십\~수백 개) ### [Long Polling](https://www.yolog.co.kr/post/http-long-polling)을 선택해야 할 때 * 🔄 **레거시 브라우저** 지원 필요 (IE 등) * 🔄 **간헐적 업데이트**만 필요 * 🔄 **프록시/방화벽**이 엄격한 환경 *** ## 장단점 정리 ### 장점 * ✅ **구현 간단**: EventSource API로 쉽게 구현 * ✅ **자동 재연결**: 네트워크 문제 자동 복구 * ✅ **표준 HTTP**: 특별한 프로토콜 불필요 * ✅ **효율적**: 필요시에만 데이터 전송 * ✅ **순서 보장**: 이벤트 ID로 순서 관리 ### 단점 * ❌ **단방향 통신**: 서버→클라이언트만 가능 * ❌ **텍스트만 전송**: 바이너리 데이터 불가 * ❌ **연결 제한**: 브라우저당 6개 연결 제한 * ❌ **IE 미지원**: Internet Explorer 호환성 없음 *** ## 마치며 Server-Sent Events는 서버에서 클라이언트로 실시간 데이터를 푸시하는 가장 간단한 방법이다. * [Polling](https://www.yolog.co.kr/post/http-polling)의 네트워크 낭비 해결 * [Long Polling](https://www.yolog.co.kr/post/http-long-polling)의 구현 복잡도 개선 * [WebSocket](https://www.yolog.co.kr/post/http-websocket)보다 간단한 구현 특히 실시간 알림, 대시보드, 라이브 피드 같은 단방향 스트리밍에 최적화되어 있다. 양방향 통신이 필요 없다면, Server-Sent Events는 여전히 훌륭한 선택지다. 다음 포스트에서는 진정한 양방향 실시간 통신을 가능하게 하는 [**WebSocket**](https://www.yolog.co.kr/post/http-websocket)을 다루겠다. ## 핵심 정리 * **SSE란**: HTML5에 정의된 서버→클라이언트 단방향 실시간 데이터 전송 프로토콜 * **핵심 헤더**: `Content-Type: text/event-stream`으로 SSE 스트림 시작 * **이벤트 필드**: * `data`: 전송할 메시지 데이터 * `id`: 이벤트 식별자 (재연결 시 사용) * `event`: 이벤트 타입 지정 * `retry`: 재연결 시도 간격 (밀리초) * **자동 재연결**: EventSource가 연결 끊김 시 자동으로 재접속 시도 * **Last-Event-ID**: 재연결 시 놓친 메시지 복구 가능 * **실무 활용**: 실시간 알림, 대시보드, 라이브 피드, 진행 상태 알림 * **선택 기준**: * SSE: 서버→클라이언트 단방향, 자동 재연결 중요, 구현 단순성 * WebSocket: 양방향 통신, 바이너리 데이터, 초저지연 * Long Polling: 레거시 브라우저, 간헐적 업데이트 **SSE는 라디오 방송과 같다. 방송국(서버)이 전파를 송출하면 청취자(클라이언트)는 주파수만 맞춰두면 실시간으로 방송을 들을 수 있다. 구독한 채널에서 자동으로 알림을 받는 것처럼 서버가 알아서 보내준다.** --- # HTTP 통신 기법 - 롱 폴링(Long Polling) 이해와 구현 > 롱 폴링(Long Polling)은 응답을 기다리는 방식으로 실시간 데이터를 전달한다. 서버·클라이언트 구현과 타임아웃, 요청 흐름을 살펴보고 일반 폴링과 지연 시간·서버 부하를 비교한다. - 원문: https://www.yolog.co.kr/post/http-long-polling - 카테고리: HTTP - 발행: 2025-08-25 - 수정: 2025-08-25 (이미지: Long Polling) HTTP는 본질적으로 `비연결성(stateless, connectionless)`을 가진 프로토콜이다. 즉, 클라이언트가 요청을 보내고 서버가 응답을 반환하면 연결은 곧바로 끊어진다. 이 특성은 많은 경우 문제가 되지 않지만, **실시간성이 필요한 서비스**—예를 들어 **채팅 애플리케이션**—에서는 곤란한 제약이 된다. [이전 포스트](https://www.yolog.co.kr/post/http-polling)에서는 이 한계를 극복하기 위한 단순한 방법인 `폴링(Polling)`을 살펴봤다. 이번에는 그보다 발전된 기법인 **롱 폴링**을 이해하고 구현해보겠다. *** ## 1. 왜 롱 폴링인가? 폴링은 주기적으로 서버에 요청을 보내 "새 데이터가 있나요?"라고 묻는다. 하지만 서버에 새 데이터가 없을 때도 "없어요"라는 응답이 오기 때문에, **불필요한 네트워크 낭비**가 발생한다. 이를 개선한 방식이 **롱 폴링**이다. 서버가 클라이언트의 요청을 받았을 때, 새로운 데이터가 있을 때까지 응답을 보류하는 방식이다. "아무것도 없다"는 응답조차 네트워크 자원을 소모하니까, 정말 전달할 데이터가 생길 때만 응답하자는 아이디어다. **비유로 이해하기** 음식 배달 앱에서 주문 상태를 확인하는 상황을 생각해보자. * **폴링**: 5초마다 앱을 열어서 "배달 왔나요?" → "아직이요" 반복 * **롱 폴링**: 가게에 전화해서 "배달 도착하면 바로 알려주세요"라고 하고 전화를 끊지 않고 대기 즉, **서버가 새로운 데이터가 있을 때까지 연결을 유지했다가, 데이터가 준비되면 응답하는 방식**이다. *** ## 2. 롱 폴링의 동작 원리 롱 폴링은 다음과 같은 흐름으로 동작한다: 1. **클라이언트**가 `/longpoll`로 요청을 보낸다. 2. **서버**는 새 데이터가 없다면 응답을 보류하고 연결을 유지한다. 3. 새 데이터가 생기면 **즉시 응답**을 보낸다. 4. 클라이언트는 응답을 받은 직후 다시 `/longpoll` 요청을 보내 연결을 유지한다. 5. 만약 일정 시간(예: 10초) 동안 새 데이터가 없으면 서버가 타임아웃 응답을 보내고 연결을 종료한다. 클라이언트는 다시 요청을 시도한다. 이런 방식으로 **실시간성을 확보**하면서도 **불필요한 요청을 줄일 수** 있다. *** ## 3. 서버 구현하기 Node.js `http` 모듈로 롱 폴링 서버를 구성해보자. ### 메시지 객체 먼저 주고받을 메시지를 정의한다: ```js class Message { constructor(text) { this.text = text; this.timestamp = Date.now(); } toString() { return JSON.stringify({ text: this.text, timestamp: this.timestamp, }); } } ``` ### 서버 코드 상세 분석 ```js const http = require('http'); // 핵심 데이터 구조 let waitingClients = []; // 응답을 기다리는 클라이언트들의 response 객체 배열 let messageQueue = []; // 메시지 큐 (실무에서는 Redis Pub/Sub 등 사용) // 롱 폴링 요청 핸들러 const longPoll = (req, res) => { const WAITING_MS = 10_000; // 최대 대기 시간 10초 if (messageQueue.length === 0) { // 전달할 메시지가 없으면 클라이언트를 대기열에 추가 waitingClients.push(res); // 무한정 기다릴 수 없으므로 타임아웃 설정 res.setTimeout(WAITING_MS, () => { // 타임아웃 응답 방식 선택 가능(사내 선택사항): // 1. 408 Request Timeout (명시적 타임아웃) // 2. 200 OK + 빈 데이터 (정상 흐름으로 처리) // 3. 204 No Content (컨텐츠 없음 명시) res.statusCode = 204; // 여기서는 204 사용 res.end(); }); return; } // 메시지가 있다면 즉시 전송 const message = messageQueue.shift(); // 큐에서 메시지 꺼내기 res.setHeader('Content-Type', 'application/json'); res.end(`${message}`); }; // 메시지 업데이트 핸들러 (새로운 채팅 메시지 전송) const update = (req, res) => { let body = ''; // POST 데이터를 청크 단위로 수신 req.on('data', (chunk) => (body += chunk.toString())); req.on('end', () => { const { text } = JSON.parse(body); // 유효성 검사 if (!text) { res.statusCode = 400; return res.end(JSON.stringify({ error: 'text 필드를 채워주세요' })); } // 새 메시지 생성 및 큐에 추가 const message = new Message(text); messageQueue.push(message); // 중요: 대기 중인 모든 클라이언트에게 메시지 전달 for (const client of waitingClients) { client.setHeader('Content-Type', 'application/json'); client.end(`${message}`); } waitingClients = []; // 대기열 초기화 // 업데이트 요청한 클라이언트에게도 응답 res.setHeader('Content-Type', 'application/json'); res.end(`${message}`); }); }; // 라우팅 const handler = (req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/longpoll') return longPoll(req, res); if (pathname === '/update') return update(req, res); res.statusCode = 404; res.end('Not Found'); }; http.createServer(handler).listen(8080, () => { console.log('server running ::8080'); }); ``` **코드의 핵심 포인트:** 1. **`waitingClients` 배열**: 서버가 즉시 응답하지 않고 대기 중인 클라이언트들의 response 객체를 저장한다. * ⚠️ **주의**: 메모리에만 저장되므로 서버 재시작 시 유실된다. 실무에서는 Redis Pub/Sub 등 외부 메시지 브로커 사용이 필수다. 2. **타임아웃 처리**: 무한정 연결을 유지할 수 없으므로 10초 제한을 둔다. 서버 리소스를 보호하는 중요한 장치다. 3. **메시지 큐**: 단일 메시지 변수 대신 큐를 사용하여 여러 메시지를 순차적으로 처리할 수 있다. 4. **브로드캐스트**: 새 메시지가 오면 대기 중인 모든 클라이언트에게 동시에 전달한다. 실시간 채팅의 핵심이다. *** ## 4. 요청 흐름 살펴보기 ### 1) 롱 폴링 요청 보내기 ```bash curl http://localhost:8080/longpoll -v ``` → 응답이 바로 오지 않고 대기 상태에 들어간다. 10초가 지나면 다음과 같은 응답이 온다: ``` < HTTP/1.1 204 No Content ``` > **타임아웃 응답 코드 선택** > > * [`408 Request Timeout`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/408): 명시적으로 타임아웃임을 표현 > * [`200 OK`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/200) + 빈 배열/객체: 정상 흐름으로 처리 (클라이언트 로직 단순화) > * [`204 No Content`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/204): 컨텐츠가 없음을 명시 (권장) ### 2) 메시지 업데이트 보내기 10초 이내에 다른 터미널에서: ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"고구마"}' -v ``` 응답: ``` < HTTP/1.1 200 OK {"text":"고구마","timestamp":1756026935210} ``` → 동시에 `/longpoll` 요청으로 대기 중이던 클라이언트들에게도 메시지가 전달된다. *** ## 5. 클라이언트 구현하기 브라우저에서 `/longpoll`을 지속적으로 호출하여 메시지를 받아보겠다. ```js const longPollServer = async () => { const response = await fetch('/longpoll'); if (response.status === 204 || response.status === 408) { // 타임아웃 발생 → 즉시 재연결 // 재귀 호출로 끊김 없는 연결 유지 return longPollServer(); } // 정상 메시지 수신 const message = await response.json(); render(message); // 핵심: 응답을 받자마자 즉시 다시 요청 // 이렇게 해야 다음 메시지도 놓치지 않고 받을 수 있음 longPollServer(); }; const render = (message) => { const div = document.createElement('div'); div.textContent = `${message.text} (${new Date( message.timestamp ).toLocaleTimeString()})`; document.body.appendChild(div); }; // 페이지 로드 시 롱 폴링 시작 document.addEventListener('DOMContentLoaded', longPollServer); ``` **클라이언트 구현의 핵심:** 1. **재귀 호출**: 타임아웃이든 정상 응답이든, 항상 다시 요청을 보내 연결을 유지한다. 2. **즉시 재연결**: 응답을 받자마자 다시 요청해야 메시지를 놓치지 않는다. 3. **타임아웃 처리**: 204/408 응답을 받으면 에러가 아니라 정상 흐름으로 처리한다. 이제 다른 클라이언트에서 메시지를 업데이트하면, 즉시 화면에 반영되는 것을 확인할 수 있다: ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"고구마"}' -v ``` *** ## 6. 롱 폴링의 장단점 ### 장점 * **네트워크 효율성**: 데이터가 있을 때만 응답하므로 불필요한 트래픽 감소 * **실시간성**: 새 데이터가 생기면 즉시 전달 (폴링의 주기적 지연 없음) * **구현 간단함**: 특별한 프로토콜 없이 기존 HTTP 인프라 활용 가능 * **방화벽 친화적**: HTTP/HTTPS를 사용하므로 대부분 환경에서 동작 ### 단점 * **서버 리소스 부담**: * 연결을 오래 유지 = 메모리/스레드 점유 * Node.js의 단일 스레드 모델에서는 많은 대기 클라이언트가 쌓이면 이벤트 루프에 부하가 걸릴 수 있음 * Nginx + 애플리케이션 서버 조합에서는 커넥션 풀이 금방 고갈될 수 있음 * **확장성 문제**: 동시 접속자가 많으면 서버 부하 급증 * **연결 관리 복잡**: 타임아웃, 재연결, 에러 처리 등 고려사항 많음 * **서버 주도 통신의 제약**: * 서버가 클라이언트에게 먼저 "말을 걸 수 없다"는 것이 주요 제약 * 클라이언트→서버는 언제든 요청 가능하지만, 서버→클라이언트는 클라이언트의 요청이 있을 때만 가능 *** ## 7. 폴링 vs 롱 폴링 비교 | 구분 | [폴링(Polling)](https://www.yolog.co.kr/post/http-polling) | 롱 폴링 | | ------- | -------------------------------------------------------- | -------------------- | | 요청 방식 | 일정 주기마다 요청 | 요청 후 새 데이터 생길 때까지 대기 | | 응답 시점 | 즉시(데이터 없어도) | 데이터 생길 때 응답 | | 네트워크 효율 | 불필요한 요청 많음 | 요청 횟수 감소 | | 실시간성 | 요청 주기에 따라 지연 | 데이터 발생 시 즉시 전달 | | 서버 부담 | 비교적 적음 | 연결 유지로 리소스 부담 증가 | | 구현 복잡도 | 매우 단순 | 타임아웃, 재연결 처리 필요 | 실제 서비스에서의 선택: * **롱 폴링이 여전히 사용되는 경우**: * HTTP 인프라만 있는 환경 ([`WebSocket`](https://www.yolog.co.kr/post/http-websocket) 지원 불가) * 프록시/방화벽이 엄격한 기업 환경 * 간헐적인 업데이트만 필요한 서비스 * Facebook, Gmail 등이 초창기에는 롱 폴링을 주력으로 사용했으며, 현재도 일부 제약 환경에서 폴백으로 사용 * **[`SSE`](https://www.yolog.co.kr/post/http-sse)나 [`WebSocket`](https://www.yolog.co.kr/post/http-websocket)을 선택하는 경우**: * 양방향 실시간 통신이 필요한 경우 (게임, 협업 도구) * 높은 빈도의 데이터 스트리밍 (주식 시세, 스포츠 중계) * 수천\~수만 명의 동시 접속자 처리 결국 **만능 해결책은 없다**가 정답이다. 각 기술의 트레이드오프를 이해하고 상황에 맞게 선택해야 한다. *** ## 8. 마치며 이번 글에서는 `롱 폴링`의 개념과 구현을 다뤘다. 롱 폴링은 폴링의 **실시간성 문제를 해결**했지만, **서버 리소스 부담**이라는 새로운 과제를 안게 되었다. 특히 많은 사용자가 동시에 접속하는 서비스에서는 각 연결이 서버의 메모리와 CPU를 점유하므로, 확장성 측면에서 한계가 명확하다. 다음 글에서는 롱 폴링의 한계를 극복하는 기술, [`SSE(Server-Sent Events)`](https://www.yolog.co.kr/post/http-sse)와 [`WebSocket`](https://www.yolog.co.kr/post/http-websocket)을 살펴보겠다. 이들은 더 효율적인 실시간 통신을 가능하게 하는 현대적인 해결책이다. ## 핵심 정리 * **롱 폴링이란**: 클라이언트 요청에 대해 서버가 새 데이터가 생길 때까지 응답을 보류하는 방식 * **동작 원리**: 요청 → 대기 → 데이터 생성 시 즉시 응답 → 타임아웃 시 204 반환 → 재요청 * **장점**: 네트워크 효율성, 실시간성, 구현 간단, 방화벽 친화적 * **단점**: 서버 리소스 부담 (연결 유지), 확장성 문제, 복잡한 연결 관리 * **폴링과의 차이**: 폴링은 주기적 요청, 롱 폴링은 데이터 있을 때까지 대기 * **실무 활용**: WebSocket 미지원 환경, 방화벽 제약, 간헐적 업데이트 서비스 **롱 폴링은 "배달 도착하면 알려주세요" 하고 전화를 끊지 않는 것과 같다. 폴링보다 효율적이지만 서버 부담이 크므로 현대적 대안(SSE, WebSocket)을 고려해야 한다.** --- # HTTP 통신 기법 - 폴링(Polling) 이해와 구현 > 폴링(Polling)이란 무엇이며 실시간 데이터 갱신에 어떻게 사용할까? HTTP 폴링의 요청 흐름, 서버·클라이언트 구현, 요청 주기와 부하, 장단점을 코드와 비유로 설명한다. - 원문: https://www.yolog.co.kr/post/http-polling - 카테고리: HTTP - 발행: 2025-08-24 - 수정: 2025-08-24 (이미지: Polling) HTTP는 본질적으로 `비연결성(stateless, connectionless)`을 가진 프로토콜이다. 즉, 클라이언트가 요청을 보내고 서버가 응답을 반환하면 연결은 곧바로 끊어진다. 이 특성은 많은 웹 애플리케이션에서 문제가 되지 않지만, **실시간성이 요구되는 서비스**—대표적으로 **채팅 애플리케이션**—에서는 곤란한 제약이 된다. 사용자가 메시지를 주고받을 때는 서버와 지속적으로 연결이 유지되어야 하기 때문이다. 이번 포스트에서는 이 한계를 극복하기 위한 가장 단순한 기법인 `폴링(Polling)`을 살펴보고, 직접 서버와 클라이언트 구현 예제를 만들어보겠다. *** ## 1. 왜 폴링이 필요한가? 실시간 통신을 하려면 서버의 데이터를 계속 확인해야 한다. 하지만 HTTP의 비연결성 때문에 한 번의 요청으로는 지속적인 확인이 불가능하다. 이를 극복하는 가장 단순한 방법은 **주기적으로 서버에 요청을 보내는 것**이다. 마치 버스가 올 때까지 계속 정류장에서 "지금 버스 왔나요?" 하고 묻는 것과 같다. 버스가 오지 않았더라도 물어보는 행위는 반복된다. 이 단순한 방식이 바로 `폴링(Polling)`이다. *** ## 2. 폴링의 동작 원리 폴링은 다음과 같은 흐름으로 동작한다: 1. **클라이언트**는 일정 주기마다 서버에 HTTP 요청을 보낸다. 2. **서버**는 새로운 데이터가 있다면 응답 본문에 전달한다. 3. 데이터가 없다면 \*\*[`204 No Content`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/204)\*\*와 같은 상태 코드를 반환한다. 4. 클라이언트는 일정 시간 대기 후 다시 요청을 반복한다. 즉, 클라이언트는 "서버의 데이터를 당겨온다(Pull)"는 개념이다. *** ## 3. 폴링 서버 구현하기 Node.js `http` 모듈을 사용해 간단한 채팅 서버를 만들어보겠다. ### 메시지 객체 정의 `메시지 본문(text)`과 `생성 시각(timestamp)`을 함께 저장해, 단순 문자열이 아닌 구조화된 데이터로 관리한다. `toString()` 메서드를 통해 이 객체를 `JSON 문자열로 직렬화`하여 `클라이언트-서버` 간 전송에 활용할 수 있다. ```js class Message { constructor(text) { this.text = text; this.timestamp = Date.now(); } toString() { return JSON.stringify({ text: this.text, timestamp: this.timestamp, }); } } ``` ### 서버 구성 HTTP 서버를 열고 `/poll`로는 신규 메시지 조회, `/update`로는 메시지 등록을 처리하도록 구성했다. 라우팅에 따라 적절한 핸들러를 실행하며, 없는 경로 요청에는 [`404`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/404)를 반환한다. ```js const http = require('http'); let message = null; // 신규 메시지 조회 const poll = (req, res) => { if (!message) { res.statusCode = 204; // No Content res.end(); return; } res.setHeader('Content-Type', 'application/json'); res.end(`${message}`); message = null; }; // 메시지 등록 const update = (req, res) => { let body = ''; req.on('data', (chunk) => (body += chunk.toString())); req.on('end', () => { const { text } = JSON.parse(body); if (!text) { res.statusCode = 400; res.end(JSON.stringify({ error: 'text 필드를 채워주세요' })); return; } message = new Message(text); res.end(`${message}`); }); }; // 라우팅 const handler = (req, res) => { const { pathname } = new URL(req.url, `http://${req.headers.host}`); if (pathname === '/poll') return poll(req, res); if (pathname === '/update') return update(req, res); res.statusCode = 404; res.end('Not Found'); }; http.createServer(handler).listen(8080, () => { console.log('server running ::8080'); }); ``` *** ## 4. 요청 흐름 살펴보기 ### 1) 메시지가 없을 때 ```bash curl http://localhost:8080/poll -v ``` 응답: ``` < HTTP/1.1 204 No Content ``` ### 2) 메시지 등록하기 ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"hello"}' -v ``` 응답: ``` < HTTP/1.1 200 OK {"text":"hello","timestamp":...} ``` ### 3) 메시지 조회하기 ```bash curl http://localhost:8080/poll -v ``` 응답: ``` < HTTP/1.1 200 OK {"text":"hello","timestamp":...} ``` 다시 요청을 보내면 [`204`](https://developer.mozilla.org/ko/docs/Web/HTTP/Status/204)가 반환된다. 이미 메시지를 소비했기 때문이다. *** ## 5. 클라이언트 구현 브라우저에서 5초마다 `/poll` 요청을 보내도록 구성한다. ```js const pollServer = async () => { const INTERVAL_MS = 5_000; const response = await fetch('/poll'); if (response.status === 204) { setTimeout(pollServer, INTERVAL_MS); return; } const message = await response.json(); render(message); setTimeout(pollServer, INTERVAL_MS); }; const render = (message) => { const div = document.createElement('div'); div.textContent = `${message.text} (${new Date( message.timestamp ).toLocaleTimeString()})`; document.body.appendChild(div); }; document.addEventListener('DOMContentLoaded', pollServer); ``` 일단 네트워크 탭을 보면 계속 요청을 5초마다 보내고 있지만, 실제로 데이터들이 화면에 표시되어있지는 않다. 이는 우리가 당연히 서버에서 클라이언트에게 데이터를 보내지 않았기 때문이다. ```bash curl http://localhost:8080/update \ -H "Content-Type: application/json" \ -d '{"text":"hello"}' -v ``` 이제 서버에 메시지를 업데이트하면 클라이언트 화면에 새로운 메시지가 표시된다. (이미지: 클라이언트 폴링) *** ## 6. 폴링의 장단점 ### 장점 * 구현이 단순하다 * 특별한 프로토콜이나 라이브러리 없이 HTTP로 가능하다 * 빠르게 테스트하거나 프로토타입을 만들 때 유용하다 ### 단점 * **비효율적**: 데이터가 없어도 주기적으로 요청을 발생 * **네트워크 비용 증가**: 불필요한 요청이 많음 * **실시간성 한계**: 요청 주기에 따라 지연 발생 * **서버 부하**: 클라이언트 수가 많으면 서버에 부담 *** ## 7. 비유로 이해하기 `폴링(Polling)`은 카톡에서 계속 "새 메시지 있어?"라고 물어보는 것과 같다. 메시지가 없어도 주기적으로 확인하기 때문에 데이터(요금)가 낭비되고, 서버 입장에서도 불필요한 요청이 쌓여 부담이 커진다. 구현은 간단하지만 효율이 떨어지는 방식이므로, 보통은 `푸시 알림`, [`WebSocket`](https://www.yolog.co.kr/post/http-websocket), `서버 푸시` 같은 대안이 더 선호된다. *** ## 8. 마치며 `폴링`은 HTTP의 비연결성을 극복하기 위한 가장 단순한 기법이다. 그러나 **실시간성이 중요한 시스템에서는 효율적이지 못하다.** 그래서 다음 포스트에서는 폴링보다 진보된 방식인 [`롱 폴링(Long Polling)`](https://www.yolog.co.kr/post/http-long-polling)을 살펴보겠다. 또한 [`서버 푸시(Server-Sent Events)`](https://www.yolog.co.kr/post/http-sse)와 [`양방향 통신(WebSocket)`](https://www.yolog.co.kr/post/http-websocket)까지 다루며, 실시간 통신 기술의 발전 과정을 정리해 보겠다. ## 핵심 정리 * **폴링이란**: 클라이언트가 주기적으로 서버에 요청을 보내 데이터를 확인하는 방식 * **동작 원리**: 일정 주기마다 HTTP 요청을 보내고, 새 데이터가 있으면 응답, 없으면 204 반환 * **장점**: 구현이 단순하고 특별한 프로토콜 불필요 * **단점**: 비효율적 (불필요한 요청 발생), 네트워크 비용 증가, 실시간성 한계, 서버 부하 * **실제 활용**: 프로토타입이나 간단한 테스트용으로 적합 * **대안**: Long Polling, Server-Sent Events, WebSocket 등이 더 효율적 **폴링은 "버스 왔나요?"를 계속 묻는 것과 같다. 간단하지만 비효율적이므로 실시간 통신에는 더 나은 대안을 고려해야 한다.** --- # HTML 렌더링과 리소스 요청 과정 > 이번 포스트에서는 사용자가 URL을 입력한 순간부터 HTML 문서가 렌더링되는 과정, 그리고 HTML 안에서 발생하는 다양한 리소스 요청과 Form 요청까지를 예시와 함께 살펴보겠다. 사용자가 브라우저 주소창에 https://example.com을 입력한다. 브라우저는 해당 서버로... - 원문: https://www.yolog.co.kr/post/http-network-request - 카테고리: HTTP - 발행: 2025-08-23 - 수정: 2025-08-23 이번 포스트에서는 사용자가 URL을 입력한 순간부터 HTML 문서가 렌더링되는 과정, 그리고 HTML 안에서 발생하는 다양한 리소스 요청과 Form 요청까지를 예시와 함께 살펴보겠다. (이미지: HTML 렌더링과 리소스 요청 과정) *** ## 1. HTML 문서 요청과 렌더링 과정 1. 사용자가 브라우저 주소창에 `https://example.com`을 입력한다. 2. 브라우저는 해당 서버로 HTTP 요청을 보낸다. 3. 서버는 요청을 처리하고 HTML 문서를 응답한다. 4. 브라우저는 받은 HTML을 파싱하고 렌더링한다. 이때 **브라우저는 HTML 문서만 처리하는 것이 아니라**, 문서 안에 포함된 다양한 리소스(CSS, JS, 이미지, 글꼴 등)를 해석하면서 추가 HTTP 요청을 발생시킨다. 마치 요리할 때 레시피를 보며 필요한 재료들을 하나씩 가져오는 것과 같다. HTML은 레시피이고, CSS, JS, 이미지는 재료다. *** ## **2. HTML 외 요청들** **2-1. 스타일시트 요청** ```html ``` 브라우저는 \*\*`style.css`\*\*를 가져오기 위해 **[`Accept: text/css`](https://developer.mozilla.org/ko/docs/Web/HTTP/Headers/Accept)** 헤더를 포함한 새로운 HTTP 요청을 보낸다. **2-2. 글꼴 요청** ```html ``` 구글 폰트 CSS 파일을 불러오기 위해 또 다른 HTTP 요청이 만들어진다. 이 CSS 안에는 실제 폰트 파일 요청도 추가로 포함될 수 있다. **2-3. 자바스크립트 요청** ```html ``` ```html ``` 2) **CSS 클래스 토글 활용**: 스타일 변경이 필요할 때 `element.classList.toggle('active')`처럼 한 번만 바꾸면 `리플로우`가 적게 일어납니다. 반면, `element.style.width = '100px'` 같은 **직접 속성 변경을 반복**하면 `리플로우`가 자주 발생한다. *** ## 2.5 페인트(Paint) 단계 * `페인트(Paint)`는 레이아웃 계산이 끝난 후, 각 노드를 실제 픽셀 단위로 “어떻게 색칠할지” 결정하는 과정입니다. * 배경색, 텍스트 색, 그림자, 테두리, 이미지 등 모든 시각적 요소가 이 단계에서 처리된다. * GPU나 CPU를 이용해 렌더링 버퍼에 드로잉을 수행한다. * **레이어 분할(Layer Splitting)** 브라우저는 성능 최적화를 위해, 자주 변경될 것으로 예상되는 요소(애니메이션, 트랜스폼 등)를 별도 레이어로 분리한다. 예를 들어, 스크롤할 때 고정 헤더가 있고, 그 아래에 움직이는 콘텐츠가 있다면, 이 둘을 각각 별도 레이어로 처리해 “헤더만 다시 그리고 콘텐츠는 따로 다시 그리는 식”으로 최적화한다. * **페인트 비용이 큰 속성** * `box-shadow`, `filter: blur()`, `border-radius` 등 복잡한 그래픽 효과 * 대용량 이미지, 고해상도 텍스처 > Tip! > > * **`will-change` 속성 남용 주의** > > * `will-change: transform` 같은 CSS를 붙이면 브라우저가 미리 레이어를 확보하고, > GPU 가속을 준비하겠다는 신호를 보냅니다. > > * 그러나 너무 많은 레이어를 생성하면 > GPU 메모리를 과도하게 사용하게 되어 오히려 성능이 떨어질 수 있다. > 꼭 필요한 곳에만 최소 범위로 사용하는걸 권장한다. > > * **단순 속성으로 대체** > 복잡한 애니메이션이나 그래픽 효과 대신, `transform: translate()`나 `opacity` 같은 GPU 친화적 속성을 활용하면 `리페인트·리플로우` 비용을 크게 낮출 수 있다. *** ## 2.6 컴포지팅(Compositing) 단계 * `컴포지팅(Compositing)`은 최종적으로 `레이어(Layer)끼리 합쳐서(Compose) 화면에 표시`하는 단계입니다. 예를 들어, 배경 레이어, 텍스트 레이어, 애니메이션 레이어, 고정 헤더 레이어 등이 각각 독립적으로 준비되어 있다가, 한 번에 합쳐져서 최종 화면이 만들어집니다. * **GPU 가속** 각 레이어가 별도 텍스처(texture)로 GPU 메모리에 올라가 있다가, 셰이더(shader)가 조합해 한 프레임을 렌더링한다. * **컴포지팅 비용** * 해상도가 높거나 레이어가 너무 많으면, 합성 과정에서 GPU에 큰 부하가 걸립니다. * 불필요하게 레이어를 분리하면 메모리 점유와 드로우콜(draw call)이 증가하여 오히려 FPS가 떨어질 수 있다. > Tip! > > * **레이어 플래트닝(Layer Flattening)** > 브라우저가 퍼포먼스를 위해 자동으로 > 레이어를 합치는 과정을 거치기도 하지만, 개발자가 의도치 않게 너무 많은 레이어를 > 만들면 합치는 과정에서 오버헤드가 발생한다. 예를 들어, `position: fixed`나 `will-change`를 남용하지 말고, 꼭 필요한 곳에만 사용하세요. > > - **고해상도 기기 대응** > 넷플릭스 같은 서비스는 4K, Retina 디스플레이에서도 동영상 자막이나 초당 프레임(FPS) 저하 없이 부드럽게 보여야 한다. 이를 위해 컴포지팅 단계를 최대한 최적화하고, 불필요한 레이어 분리를 최소화해야 한다. *** ## 번외. 자바스크립트 로딩과 렌더링 차단 브라우저는 렌더링 파이프라인을 따라가던 중 ` ``` **2️⃣ ` ``` 4. 어쩔 때 **defer?** 어쩔 때 **async?** * **중요 로직은 `defer`**: 페이지 렌더링과 밀접하게 연관된 초기화 코드는 `defer`를 사용해 문서 파싱이 끝난 후 실행되도록 하는게 좋다. * **서드파티 스크립트는 `async`**: 외부 광고, 통계, SNS 위젯 등 렌더링과 순서 관계가 없는 스크립트는 `async`로 로드해 렌더링 차단을 피할 수 있다. * **인라인 스크립트 최소화**: 인라인 스크립트는 캐싱 이점이 적어 로드 성능에 부담이 될 수 있으므로, 가능하면 외부 파일로 분리하고 `defer` 또는 `async`로 로드하는게 좋다. *** ## 3. 브라우저 렌더링 최적화 지금까지 브라우저 내부 구조와 렌더링 파이프라인을 살펴봤다. 이제 **렌더링 속도와 사용자 경험을 높이기 위해 할 수 있는 몇가지 최적화 기법**을 정리해보겠다. *** ## 3.1 Critical Rendering Path(CRP) 줄이기 **Critical Rendering Path**는 `HTML 파싱 → CSSOM 생성 → 렌더 트리 구성 → 레이아웃 → 페인트`에 이르는 과정을 말하며, 이 경로가 짧을수록 `First Contentful Paint(FCP)`나 `Largest Contentful Paint(LCP)` 같은 중요한 렌더링 지표가 빨라집니다. * **크리티컬 CSS 인라인(Inlining Critical CSS)** 페이지 상단에 보이는 최소한의 스타일만 ` ``` * **JS 번들 크기 최소화 & 코드 스플리팅(Code Splitting)** **Webpack**, **Vite** 같은 빌드 도구에서 “페이지별 번들”을 만들어, 사용자가 방문하지 않을 페이지까지 미리 다운로드하지 않도록 한다. `Tree Shaking`으로 사용하지 않는 라이브러리 코드를 제거해 번들 파일 용량을 줄이고, 서드파티 라이브러리는 가능하면 CDN을 활용하거나 HTTP/3을 활성화해 네트워크 레이턴시를 최소화한다. * **이미지 최적화** JPEG, PNG 대신 **WebP**, **AVIF** 같은 차세대 이미지 포맷을 사용하면 파일 크기를 30–50% 정도 줄일 수 있다. `srcset`과 `sizes`를 활용해 디바이스 해상도에 맞는 이미지를 로드하고, `loading="lazy"` 속성을 추가해 화면에 보여질 때까지 이미지 다운로드를 미뤄 초기 로딩을 빠르게 할 수 있다. ```html ohtani Image ``` * **폰트 로딩 최적화** `@font-face`를 사용할 때 `font-display: swap;` 옵션을 지정하면 커스텀 폰트 로딩 전에는 시스템 폰트를 먼저 보여줘 `FOIT` 없이 텍스트”를 바로 볼 수 있다. 구글 폰트 같은 CDN을 통해 제공되는 폰트를 직접 가져오면 네트워크 레이턴시를 줄이고, 브라우저 캐싱 이점도 얻을 수 있다. *** ## 3.2 레이지 로딩(Lazy Loading) 적극 활용 * **이미지 & 비디오 Lazy Loading** HTML5에서 지원하는 ``를 사용하면, 사용자가 화면을 스크롤해 해당 이미지가 뷰포트에 가까워질 때 다운로드를 시작한다. 보다 정밀한 제어가 필요하다면 **Intersection Observer API**를 이용해 `화면에 가까워질 때 미리 로드`하는 방식을 구현할 수 있다. 동영상의 경우, 모바일 데이터 사용량이나 네트워크 상태에 따라 해상도(360p, 720p, 1080p)를 자동으로 조절하며 로드하는 **어댑티브 스트리밍(Adaptive Streaming)** 기법을 고려해보면 좋다. * **JS/컴포넌트 Lazy Loading** React, Vue, Angular 등 프레임워크에서는 라우트 기반으로 컴포넌트를 동적으로 불러오는 코드를 쉽게 만들 수 있다. ```tsx const HomePage = React.lazy(() => import('./pages/HomePage')); const AboutPage = React.lazy(() => import('./pages/AboutPage')); ``` 이렇게 하면 사용자가 방문하지 않는 페이지의 JS 코드를 초기 번들에 포함하지 않아 메인 번들 크기를 작게 유지할 수 있다. *** ## 3.3 리플로우(Reflow) & 리페인트(Repaint) 최소화 * **읽기(Read)와 쓰기(Write) 분리** 예를 들어, `getBoundingClientRect()` 같은 레이아웃 읽기 메서드와 `style.width = '100px'` 같은 쓰기를 섞어 쓰면, 매번 레이아웃 계산이 강제되어 **Layout Thrashing**이 발생한다. 해결책은 “한 번에 읽고 → 한 번에 쓰기”로 나누는 것입니다. ```tsx // 나쁜 예 divs.forEach((div) => { const h = div.getBoundingClientRect().height; div.style.height = `${h}px`; // 읽기 → 쓰기 → 읽기 → 쓰기 → 리플로우 반복 }); // 좋은 예 const heights = divs.map((div) => div.getBoundingClientRect().height); divs.forEach((div, i) => { div.style.height = `${heights[i]}px`; }); // 먼저 읽기만, 그다음에 쓰기만 → 리플로우 최소화 ``` * **CSS 클래스 토글 활용** 스타일 변경이 필요할 때 여러 속성을 직접 쓰는 대신, 미리 정의된 CSS 클래스를 한 번에 바꾸면 리플로우를 최소화할 수 있다. ```css /* 예시: 미리 정의된 클래스 */ .box { width: 100px; height: 100px; background: red; } .box.active { width: 150px; background: blue; } ``` ```jsx // JS boxElement.classList.toggle('active'); ``` * **GPU 친화적 애니메이션** 애니메이션을 만들 때 `top`, `left` 같은 레이아웃 속성을 변경하면 리플로우가 발생하기 때문에, 대신 `transform: translate()`나 `opacity` 같은 속성을 사용하는 것이 좋다. 예를 들어, `element.style.left = '100px'` 대신 `element.style.transform = 'translateX(100px)'`을 쓰면 리플로우 없이 GPU 레이어에서 애니메이션이 이루어집니다. *** ## 마무리 프론트엔드 개발의 재미는 코드가 화면에 바로 반영되는 즉각적인 피드백에 있지만, 나는 보이지 않는 최적화가 사용자 경험을 바꾸는 순간에 더 큰 가치를 느낀다. 예를 들어 `페이지 로딩 속도를 0.1초씩 줄이는 작업을 100번 반복하면 사용자는 총 10초를 절약할 수 있다.` 이 10초는 웹 서비스의 첫인상과 체류 시간, 이탈률 같은 핵심 지표에 분명한 변화를 만들어낸다. 사용자가 그 차이를 명확히 인식하지 못하더라도 서비스가 더 빠르고 자연스럽게 느껴지는 경험은 분명히 남는다. 아직 많이 배우고 있는 개발자지만 앞으로도 작은 최적화를 꾸준히 쌓아 더 쾌적한 웹 환경을 만드는 일에 집중하고 싶다. *** ## 핵심 정리 * **브라우저 아키텍처**: * UI, 브라우저 엔진, 렌더링 엔진, JS 엔진, 네트워킹, UI 백엔드, 스토리지 * 각 구성 요소가 협업하여 HTML/CSS/JS를 화면으로 변환 * **렌더링 파이프라인**: 1. HTML 파싱 → DOM 트리 2. CSS 파싱 → CSSOM 트리 3. 렌더 트리 생성 (display:none 제외) 4. 레이아웃(Reflow): 위치와 크기 계산 5. 페인트(Repaint): 픽셀 색칠 6. 컴포지팅: 레이어 합성 * **JS 로딩 최적화**: * `