<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[NAVER Pay Dev Blog - Medium]]></title>
        <description><![CDATA[네이버페이 기술·개발 블로그 - Medium]]></description>
        <link>https://medium.com/naverfinancial?source=rss----c7c775a7cf0b---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>NAVER Pay Dev Blog - Medium</title>
            <link>https://medium.com/naverfinancial?source=rss----c7c775a7cf0b---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 09:27:26 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/naverfinancial" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[AI 테스트의 허수를 걸러내기]]></title>
            <link>https://medium.com/naverfinancial/ai-%ED%85%8C%EC%8A%A4%ED%8A%B8%EC%9D%98-%ED%97%88%EC%88%98%EB%A5%BC-%EA%B1%B8%EB%9F%AC%EB%82%B4%EA%B8%B0-588b724a6002?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/588b724a6002</guid>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[dev]]></category>
            <dc:creator><![CDATA[olaf]]></dc:creator>
            <pubDate>Fri, 13 Nov 2026 07:04:25 GMT</pubDate>
            <atom:updated>2026-11-13T07:04:24.356Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요. 포인트혜택FE팀 고석진입니다.</p><p>요즘은 코드도, 그 코드를 검증할 테스트도 AI를 이용해 짭니다.</p><p>AI가 만든 코드는 양이 많아서 사람이 한 줄씩 다 읽기 어렵습니다. 그래서 PR을 볼 때도 코드보다 CI의 테스트 결과를 먼저 보게 되고, 테스트가 통과했으면 일단 믿고 넘어가기 쉽습니다.</p><p>결국 코드를 믿을지 말지를 테스트 통과 여부가 대신 정해 주고 있습니다.</p><p>그런데 그 테스트까지 AI가 짰다면, 테스트가 통과했다는 건 과연 무엇을 확인해 준 걸까요?</p><p>AI가 짠 테스트 중에는 통과는 하지만 정작 아무것도 확인하지 않는 테스트가 섞여 있을 수 있습니다. 이 글에서는 이런 테스트를 <strong>허수 테스트</strong>라고 부르겠습니다. 어떤 모양으로 생기는지, 어떻게 찾고 막을 수 있는지 정리해 보겠습니다.</p><blockquote><strong><em>TL;DR</em></strong><em> AI가 짠 테스트는 통과해도 아무것도 검증하지 않을 수 있습니다. 진짜 검증인지는 기대값이 어디서 왔는지 보면 알 수 있습니다. 명세에서 온 값이면 검증이고, 코드를 돌려 보고 받아 적은 값이면 구현을 복사해 둔 것에 가깝습니다.</em></blockquote><blockquote>찾을 때는 비용이 싼 방법부터 씁니다. 정규식으로 의심스러운 코드 모양을 뽑고, 실행된 expect가 0개인 테스트를 세고, E2E는 API 응답을 일부러 망가뜨려 봅니다. 그래도 애매하면 뮤테이션 테스트로 코드를 일부러 틀리게 바꿔 봅니다. 애초에 막으려면 AI에게 테스트를 맡길 때 구현 대신 명세를 먼저 주면 됩니다.</blockquote><h3>1. AI가 쓴 테스트는 왜 허수가 되는가</h3><p>AI 덕분에 테스트를 쓰는 비용은 거의 사라졌습니다. 그런데 줄어든 건 테스트를 짜는 비용이지, 그 테스트가 제대로 검증하게 만드는 비용은 아니었습니다.</p><p>AI에게 “테스트 써 줘”라고 하면 AI는 명세보다 눈앞의 코드를 보고 테스트를 씁니다. 테스트가 실패하면 가장 빨리 통과시킬 수 있는 쪽을 고릅니다. 확인을 건너뛰는 조건문을 넣거나, 기대값을 지금 구현에 맞추거나, 검증을 아예 지워 버립니다.</p><h4>작은 예시: 전화번호 마스킹</h4><p>“전화번호 마스킹하는 함수 만들어 줘”라고 하면 AI는 대략 이런 코드와 테스트를 내놓습니다.</p><pre>const maskPhone = (phone: string): string =&gt; {<br>    return `${phone.slice(0, 3)}-****-${phone.slice(-4)}`<br>}</pre><pre>it(&#39;전화번호를 마스킹한다&#39;, () =&gt; {<br>    expect(maskPhone(&#39;010-1234-5678&#39;)).toBe(&#39;010-****-5678&#39;)<br>})</pre><p>테스트는 통과합니다. 그런데 “가운데 네 자리를 가린다”는 규칙은 누가 정했을까요?</p><p>요구사항에는 “전화번호를 마스킹한다”고만 적혀 있었습니다. 몇 자리를 어느 쪽에서 가릴지는 아무도 정하지 않았습니다. 테스트의 기대값, 즉 toBe() 안에 적어 둔 &#39;010-****-5678&#39;은 이 코드를 한 번 돌려 보고 나온 결과를 그대로 받아 적은 것입니다. 규칙은 코드를 짠 AI가 정했고, 테스트는 그걸 받아 적었고, 사람은 테스트가 통과한 것만 보고 넘어갔을 뿐입니다.</p><h4>기대값이 어디서 왔는가</h4><p>그래서 저는 테스트를 볼 때 기대값이 어디서 왔는지를 봅니다. 명세 문장에서 나온 값이라면 명세를 검증하는 테스트입니다. 코드를 실행해서 얻은 값이라면 구현을 복사해 둔 것에 가깝습니다.</p><p>기대값이 명세에서 나왔다면 코드가 틀리는 순간 테스트가 실패합니다. 코드에서 나왔다면 테스트도 같은 틀린 값을 기대하고 있으니 늘 통과합니다. 이런 테스트는 차라리 없는 게 나을 때도 있습니다. 테스트가 있다는 이유로 다들 안심하게 되니까요.</p><h3>2. 허수 테스트 패턴 8가지</h3><p>실제 프로젝트에서 찾은 케이스를 여덟 가지로 묶었습니다. 1~5는 확인 자체를 건너뛰는 경우, 6은 실패하면 기준을 코드 쪽으로 옮기는 경우, 7은 기대값을 구현에서 베끼는 경우, 8은 판정을 목에 맡기는 경우입니다.</p><h4>패턴 1. 결과를 기다리지 않고 끝낸다</h4><pre>it(&#39;품절 상품에는 품절 배지가 보인다&#39;, async () =&gt; {<br>    render(&lt;ProductCard product={soldOutProduct} /&gt;)<br>    screen.findByText(&#39;품절&#39;)   // await 없음, 배지가 없어도 대개 통과<br>})</pre><p>findByText는 Promise를 돌려주는데 await가 없으면 테스트가 결과를 기다리지 않고 끝납니다. 그래서 배지가 없어도 대부분 통과합니다. AI가 async는 붙여 놓고 await는 빼먹으면 이렇게 되는데, 눈으로 찾기보다 린트로 막는 게 낫습니다.</p><h4>패턴 2. 없으면 건너뛴다</h4><pre>// 배너가 없으면 테스트가 통과가 아니라 &quot;건너뜀&quot;이 된다. 실패할 방법이 없다<br>test.skip(!(await isVisible(firstBanner)), &#39;배너가 없음&#39;)<br>await expect(firstBanner).toBeVisible()</pre><p>배너가 안 보이면 건너뛰고, 보이면 “보인다”고 검증합니다. 배너 로직이 완전히 깨져도 조용히 건너뛸 뿐이라 실패할 방법이 없습니다. 게다가 Playwright의 isVisible()은 기다리지 않고 바로 값을 돌려줘서, 배너가 조금 늦게 뜨는 환경에서는 테스트 전체가 건너뛰어지기도 합니다.</p><h4>패턴 3. 없으면 그냥 통과한다</h4><p>상세 페이지의 작가 링크를 확인하는 E2E 테스트입니다.</p><pre>if (!page.url().includes(&#39;/articles/&#39;)) {<br>    return // 가드: URL이 틀려도 여기서 끝나고 &quot;통과&quot;로 찍힌다<br>}<br>if ((await authorLink.count()) &gt; 0) {<br>    await expect(authorLink).toBeVisible() // 링크가 없으면 이 검증은 한 번도 실행되지 않는다<br>}</pre><p>skip은 리포트에 &quot;건너뜀&quot;이라도 남는데, 이건 그냥 &quot;통과&quot;로 찍힙니다. 기대값이 틀린 테스트는 언젠가 어긋나면서 드러나지만, 확인을 안 한 테스트는 흔적이 없습니다.</p><h4>패턴 4. 검증 코드가 하나도 없다</h4><pre>it(&#39;차단된 사용자면 토스트를 표시한다&#39;, async () =&gt; {<br>    const {result} = renderHook(() =&gt; useUserMenu())<br>    await result.current.onProfileClick({id: &#39;user1&#39;})<br>    // 검증(expect)이 하나도 없다. 크래시만 잡는다<br>})</pre><p>테스트 이름은 결과를 약속하는데 본문은 함수를 호출하고 끝납니다. 이름은 명세에서 가져오고 검증문은 빼먹은 경우입니다. 이 테스트가 잡을 수 있는 건 크래시 정도입니다.</p><h4>패턴 5. 아무것도 안 떠도 통과한다</h4><pre>// 없어야 할 것만 확인한다. 화면이 통째로 깨져도 통과한다<br>await expect(page.getByText(&#39;서비스 점검 중&#39;)).not.toBeVisible()</pre><p>화면이 통째로 깨져도 통과합니다. “없어야 할 것”을 확인할 때는 상품 목록처럼 “있어야 할 것”도 같이 확인해야 화면이 깨진 건지, 정말 배너만 없는 건지 구분할 수 있습니다.</p><h4>패턴 6. 실패하면 테스트 쪽을 고친다</h4><p>AI에게 실패한 테스트를 고쳐 달라고 할 때 생기는 패턴입니다. 사람이라면 “명세가 틀린 건가?”부터 물을 텐데, “이 테스트 고쳐 줘”라고만 하면 AI가 볼 수 있는 건 코드와 실패 메시지뿐입니다. 그러니 가장 빨리 통과시킬 수 있는 기대값 쪽을 고치기 쉽습니다.</p><p>상품명이 길면 잘라서 뒤에 “...”을 붙여 주는 truncate 함수로 예를 들어 보겠습니다. 구현에 버그가 하나 있습니다.</p><pre>// 명세: 10자 이하는 그대로, 10자를 넘으면 10자까지만 보여 주고 &#39;...&#39;을 붙인다<br>function truncate(name) {<br>    if (name.length &gt;= 10) {   // 버그: &gt; 10이어야 한다. 딱 10자도 잘린다<br>        return name.slice(0, 10) + &#39;...&#39;<br>    }<br>    return name<br>}</pre><p>그래서 딱 10자인 &#39;가나다라마바사아자차&#39;를 넣으면 자를 게 없는데도 뒤에 “...”이 붙어 나옵니다. 명세대로 쓴 테스트는 당연히 실패하고, 이걸 AI에게 고쳐 달라고 하면 테스트가 이렇게 바뀔 수 있습니다.</p><pre>// 원래 테스트: 딱 10자는 그대로 나와야 한다 (명세 기준, 실패)<br>- expect(truncate(&#39;가나다라마바사아자차&#39;)).toBe(&#39;가나다라마바사아자차&#39;)<br>// AI가 고친 테스트: 구현이 돌려준 값을 그대로 기대값에 적었다 (통과)<br>+ expect(truncate(&#39;가나다라마바사아자차&#39;)).toBe(&#39;가나다라마바사아자차...&#39;)</pre><p>테스트는 다시 통과하지만, 명세가 바뀐 게 아니라면 틀린 건 여전히 구현입니다. 고쳐야 할 건 구현의 &gt;= 하나였는데 기대값을 구현에 맞춰 버렸습니다. 그래서 나중에 누가 버그를 고치면 오히려 이 테스트가 실패합니다.</p><h4>패턴 7. 구현을 베낀다</h4><p>앞에서 본 maskPhone 테스트를 AI가 이렇게 쓰기도 합니다.</p><pre>// 기대값을 구현과 같은 식으로 계산 (명세 검증이 안 됨)<br>const raw = &#39;010-1234-5678&#39;<br>expect(maskPhone(raw)).toBe(`${raw.slice(0, 3)}-****-${raw.slice(-4)}`)</pre><p>기대값을 구현과 똑같은 식으로 계산하고 있습니다. 코드를 그대로 비출 뿐이라 그 코드가 맞는지는 알려 주지 않습니다. 구현이 바뀌면 실패하긴 하지만, AI가 그 실패를 고칠 때 기대값을 또 코드에서 가져오니 결국 다시 통과합니다.</p><p>제대로 쓴 테스트는 이렇게 생겼습니다.</p><pre>// 자산: 기대값은 명세의 결과 그대로 (&quot;휴대전화번호는 가운데 4자리를 가린다&quot;)<br>expect(maskPhone(&#39;010-1234-5678&#39;)).toBe(&#39;010-****-5678&#39;)</pre><p>앞에서 본 마스킹 테스트와 겉모습은 똑같습니다. 다른 건 기대값을 명세 문장에서 가져왔다는 것 하나입니다. AI에게 명세 없이 코드만 주면 참고할 게 코드밖에 없으니, 이건 AI 잘못이라기보다 명세를 안 준 쪽의 문제에 가깝습니다.</p><h4>패턴 8. 판정은 목이 하고, 테스트는 확인만 한다</h4><pre>import {isBefore} from &#39;@lib/date&#39;<br>import {isShowBadge} from &#39;./isShowBadge&#39;<br> <br>vi.mock(&#39;@lib/date&#39;, () =&gt; ({isBefore: vi.fn()}))<br> <br>it(&#39;종료일이 지났으면 배지를 숨긴다&#39;, () =&gt; {<br>    vi.mocked(isBefore).mockReturnValue(false) // 목이 false를 준비<br>    expect(isShowBadge({endAt: &#39;2020-01-01&#39;})).toBe(false) // 그 false를 다시 확인할 뿐, 판정 자체는 검증 안 됨<br>})</pre><p>목(mock)이 돌려준 false를 다시 false인지 확인하고 있을 뿐입니다. isShowBadge가 isBefore에 인자를 거꾸로 넘겨도 통과합니다. 네트워크나 시간처럼 바깥 경계를 목으로 바꾸는 건 괜찮지만, 검증하려는 판정 자체를 목이 내리고 있다면 허수입니다.</p><p>꼭 목이 필요하다면 expect(isBefore).toHaveBeenCalledWith(endAt, now)처럼 호출을 검증해 주세요. 날짜라면 vi.setSystemTime(...)으로 실제 로직을 태우는 게 더 낫습니다. 목으로 바꾼 모듈을 다른 테스트가 직접 검증하고 있는지도 확인해 보면 좋습니다. 다들 목을 믿고 지나가면 그 모듈은 한 번도 검증되지 않은 채 남습니다.</p><h3>3. 허수 테스트를 찾아내는 5가지 방법</h3><p>비용이 싼 것부터 정리하면 이렇습니다.</p><ol><li>정규식으로 코드 모양을 보고 후보를 뽑는다</li><li>실제로 실행된 검증 개수를 센다</li><li>API 응답을 망가뜨려 본다</li><li>코드를 일부러 틀리게 바꿔 본다</li><li>명세와 나란히 놓고 사람이 판정한다</li></ol><p>최종 판정은 마지막에 명세를 놓고 사람이 합니다. 구현과 테스트가 같은 방향으로 틀려 있으면 도구로는 못 찾기 때문입니다.</p><h4>3.1 정규식으로 후보 뽑기</h4><p>await이 빠졌거나 skip이 붙어 있는 것처럼 코드만 봐도 티가 나는 패턴은 정규식으로 후보를 뽑을 수 있습니다. 어디까지나 후보라서 걸린 줄은 하나씩 열어 봐야 합니다.</p><pre># await 없이 호출한 findBy (await 있는 줄은 빠지므로 눈으로 한 번 확인)<br>grep -rn &#39;screen\.findBy\w*(&#39; --include=&#39;*.test.*&#39; src | grep -v &#39;await&#39;<br> <br># 조건부 skip까지 전부 나열한 뒤, 하나씩 열어서 사유 확인<br>rg -P &#39;test\.(skip|fixme)\(&#39; e2e<br> <br># 부정 검증이 있는 테스트를 찾아, 긍정 검증이 같이 있는지 확인<br>rg -P &#39;\.not\.toBe(Visible|InTheDocument)\(&#39; -g &#39;*.{spec,test}.{ts,tsx}&#39;<br> <br># 판정 함수의 반환값을 목으로 고정한 줄 (Once, Resolved 변형 포함)<br>git ls-files &#39;*.spec.ts*&#39; &#39;*.test.ts*&#39; | xargs grep -nE \<br>  &quot;(is[A-Z][A-Za-z]*|has[A-Z][A-Za-z]*|compare[A-Za-z]*|check[A-Za-z]*)[^.]*\.mock(Return|Resolved)?Value(Once)?\((true|false)\)&quot;</pre><h4>3.2 실행된 expect 개수 세기</h4><p>조건이 안 맞으면 return으로 끝내는 가드는 코드 모양만으로는 잘 안 보입니다. 이런 테스트를 예로 들어 보겠습니다.</p><pre>test(&#39;가격 필터를 적용하면 상품 목록이 바뀐다&#39;, async ({page}) =&gt; {<br>    const emptyNotice = page.getByText(&#39;조건에 맞는 상품이 없습니다&#39;)<br>    if (await emptyNotice.isVisible()) {<br>        return // 결과가 비면 여기서 끝난다<br>    }<br>    await expect(page.locator(&#39;.product-item&#39;).first()).toBeVisible()<br>})</pre><p>필터 결과가 늘 비어 있으면 return으로 끝나고 expect는 한 번도 실행되지 않습니다. 리포트에는 &quot;통과&quot;로 찍히고, 나중에 필터가 아예 고장 나도 여전히 통과합니다.</p><p>찾는 방법은 테스트마다 실제로 실행된 expect 개수를 세는 겁니다. 0인데 통과한 테스트가 후보입니다. Playwright는 expect 호출을 step으로 기록하기 때문에 리포터 몇 줄이면 됩니다.</p><pre>// assert-count-reporter.ts<br>const countExpect = (steps: TestStep[]): number =&gt; {<br>    return steps.reduce((sum, step) =&gt; {<br>        return sum + (step.category === &#39;expect&#39; ? 1 : 0) + countExpect(step.steps)<br>    }, 0)<br>}<br> <br>export default class AssertCountReporter implements Reporter {<br>    onTestEnd(test: TestCase, result: TestResult) {<br>        if (result.status === &#39;passed&#39; &amp;&amp; countExpect(result.steps) === 0) {<br>            console.log(`[검증 0회 통과] ${test.titlePath().filter(Boolean).join(&#39; &gt; &#39;)}`)<br>        }<br>    }<br>}</pre><p>npx playwright test --reporter=list,./assert-count-reporter.ts로 돌리면 일반 출력은 그대로 두고 걸린 목록만 따로 찍힙니다. CI를 실패시키지 않고 사람이 읽는 용도입니다.</p><p>빈틈과 오탐도 있습니다. test.skip()으로 건너뛴 테스트는 통과로 집계되지 않아서 여기에 안 찍히니 정규식 스캔과 같이 써야 합니다. 헬퍼 안에서 호출한 expect는 제대로 셉니다. 다만 헬퍼가 expect 대신 waitFor나 직접 던지는 에러로 확인하면 검증을 하고 있어도 0회로 찍힙니다.</p><h4>3.3 API를 일부러 망가뜨려 보기 (장애 주입)</h4><p>“서버가 실패하면 화면이 어떻게 되는가”는 서버부터 화면까지 다 도는 E2E에서만 확인할 수 있습니다. 그렇다고 E2E에 뮤테이션 테스트를 돌리기엔 너무 무거우니, 코드 대신 바깥을 망가뜨립니다. API 응답을 500 에러나 빈 객체({})로 바꿨는데도 통과하는 테스트가 있다면, 에러나 빈 데이터를 가드로 숨기고 있을 가능성이 큽니다.</p><p>Playwright에서는 page.route로 API 응답을 바꿔 끼울 수 있습니다.</p><pre>// API 응답을 전부 500 에러로 바꾼다<br>await page.route(/\/api\//, (route) =&gt; route.fulfill({status: 500, body: &#39;{}&#39;}))</pre><p>테스트 시작 부분에 이 줄을 넣고 돌렸는데도 통과하면 후보입니다. status를 200으로 바꾸면 빈 객체가 왔을 때도 확인할 수 있습니다.</p><p>처음에는 GET 요청만 가로채는 게 안전합니다. 결제나 글쓰기처럼 데이터를 바꾸는 요청까지 건드리면 공유 테스트 서버의 데이터가 바뀔 수 있으니, GET이 아닌 요청은 route.continue()로 그대로 보내면 됩니다. 또 route는 브라우저가 보내는 요청만 가로채기 때문에, SSR로 서버에서 미리 받아 온 데이터는 그대로 나온다는 점도 알아 두면 좋습니다.</p><h4>3.4 코드를 일부러 틀리게 바꿔 보기 (뮤테이션 테스트)</h4><p>커버리지는 “이 줄이 실행됐는가”를 봅니다. 뮤테이션 테스트는 “이 줄을 틀리게 바꾸면 테스트가 실패하는가”를 봅니다.</p><pre>// 원래 코드<br>if (name.length &lt;= 10) {<br>    return name<br>}<br>// 도구가 만든 변이(mutant) 예시<br>if (name.length &lt; 10) { ... }   // 경계값 바꾸기<br>if (true) { ... }               // 항상 참으로</pre><p>변이마다 테스트를 돌려서 실패하면 잡았다(killed), 통과하면 살아남았다(survived)고 합니다. JavaScript와 TypeScript에서는 Stryker를 쓸 수 있는데, 변이 수만큼 테스트를 돌려서 속도가 느립니다. 그래서 작은 폴더 하나에서 시작해 변이 종류를 조금씩 늘려 가는 걸 추천합니다.</p><ol><li>먼저 BlockStatement만 켭니다. 함수 본문을 통째로 비우는 변이라서, 본문을 비워도 아무 테스트도 실패하지 않는 함수가 바로 드러납니다.</li><li>조건 변이인 ConditionalExpression, EqualityOperator, LogicalOperator를 켭니다. 조건을 true나 false로 고정하거나 &lt;=를 &lt;로, &amp;&amp;를 ||로 바꿔서 분기와 경계값을 테스트가 확인하는지 봅니다.</li><li>나머지 변이를 켭니다. +를 -로, true를 false로, 배열을 빈 배열로 바꾸는 식이라 계산 결과와 데이터를 테스트가 확인하는지 드러납니다. 다만 문구를 바꾸는 StringLiteral은 꺼 둔 채로 둬도 됩니다.</li><li>한 폴더가 정리되면 폴더를 넓힙니다. 범위가 커지면 --incremental로 돌려서 지난 결과를 재사용하고 바뀐 부분만 다시 테스트합니다.</li></ol><p>Stryker에는 켤 변이만 고르는 옵션이 없어서, 설정의 mutator.excludedMutations에 끌 변이 이름을 적습니다. 처음에는 BlockStatement를 뺀 나머지 이름을 다 적어 두고, 다음 단계로 넘어갈 때마다 목록에서 지우면 됩니다.</p><p>살아남은 변이를 보면 고칠지 넘어갈지 정해야 합니다. 기준은 간단합니다. 사용자에게 차이가 보이는데도 통과했다면 테스트를 추가하고, 안 보인다면 그 변이를 끄거나 코드를 지웁니다.</p><ul><li>total + bonus를 total - bonus로 바꿨는데 통과했다면 포인트 합계를 확인하는 테스트가 없다는 뜻입니다. 테스트를 추가합니다.</li><li>&#39;저장되었습니다&#39;를 &#39;저징되었습니다&#39;로 바꿨는데 통과했다면, 문구까지 테스트로 강제할 필요는 없으니 이런 변이는 꺼 둡니다.</li></ul><p>애매한 경우도 있습니다. 아래 함수에서 Stryker가 첫 번째 조건을 false로 바꿔도 테스트는 다 통과합니다.</p><pre>function formatPrice(price?: number) {<br>    if (price === undefined) return &#39;&#39;      // 이 조건을 false로 바꿔도<br>    if (!Number.isFinite(price)) return &#39;&#39;  // undefined는 여기서 걸린다<br>    return price.toLocaleString() + &#39;원&#39;<br>}</pre><p>price가 undefined여도 두 번째 조건에서 똑같이 빈 문자열을 돌려주기 때문입니다. 테스트에 빈틈이 있는 게 아니라 두 조건이 같은 일을 하고 있는 겁니다. 그래도 그냥 두면 돌릴 때마다 같은 survived가 계속 나옵니다. 겹치는 가드라면 지우고, 일부러 남기는 이중 방어라면 그 줄만 제외 주석으로 꺼 둡니다.</p><pre>// Stryker disable next-line ConditionalExpression: isFinite 검사와 겹치지만 일부러 남긴 이중 방어<br>if (price === undefined) return &#39;&#39;</pre><p>제외 주석에는 위처럼 사유를 꼭 적고, 파일 전체나 변이 종류 전체를 끄지는 않습니다. 이렇게 켜고 끈 기록이 쌓이면 설정 파일과 주석이 그대로 “우리 팀은 여기까지 검증한다”는 합의가 됩니다.</p><h4>3.5 명세와 나란히 놓고 보기</h4><p>앞의 방법들은 모두 지금의 코드를 기준으로 봅니다. 구현과 테스트가 같은 방향으로 틀려 있으면 뮤테이션 점수도 높고 장애 주입도 통과합니다. 이건 명세를 기준으로 놓아야 보입니다.</p><p>기획서나 QA 테스트 케이스의 항목마다 테스트가 무엇을 확인하는지 적어 나가면 됩니다.</p><ul><li>품절 상품은 구매 버튼 비활성: 구현에도 테스트에도 없음. 바꿔 볼 코드가 없으니 뮤테이션 테스트로는 찾을 수 없습니다.</li><li>포인트는 결제 금액의 1%, 1원 미만 버림: 테스트는 calcPoint(1550)이 16이라고 기대함. 구현이 반올림을 하고, 기대값도 구현을 돌려서 나온 값을 그대로 옮겼습니다. 명세대로면 15여야 합니다.</li></ul><p>이런 목록의 초안은 AI에게 맡겨도 됩니다. 다만 구현 코드는 빼고 명세와 테스트만 주는 게 좋습니다. 구현까지 보여 주면 AI도 구현을 정답으로 보고 같은 착각을 할 수 있습니다. 어긋난 항목이 구현 버그인지, 기획이 바뀌었는데 문서가 안 따라온 건지는 사람이 판정합니다.</p><h3>4. 허수 테스트가 생기지 않게 하려면</h3><p>찾는 것보다 애초에 안 생기게 하는 쪽이 싸고 확실합니다.</p><h4>도구부터 켜 두기</h4><p>기계가 걸러 줄 수 있는 건 먼저 걸러 두는 게 좋습니다.</p><ul><li>await 누락: typescript-eslint의 no-floating-promises. 타입 정보가 필요해서 parserOptions.project 설정이 있어야 합니다.</li><li>skip, only: Biome의 noSkippedTests 같은 규칙. 조건부 return은 못 잡으니 정규식 스캔과 같이 씁니다.</li><li>검증문이 없는 유닛 테스트: vitest의 expect: {requireAssertions: true}. Playwright에는 같은 옵션이 없어서 E2E는 앞에서 만든 expect 개수 리포터로 봅니다.</li></ul><h4>AI에게 맡길 때는 명세를 먼저 주기 (SDD)</h4><p>명세를 먼저 쓰고 코드와 테스트가 그 명세를 따라가게 하는 방식을 스펙 주도 개발(SDD, Spec-Driven Development)이라고 합니다.</p><pre>// 전: 기대값을 AI가 정하게 두는 요청<br>maskPhone 함수에 대한 테스트를 써 줘<br> <br>// 후: 기대값을 사람이 정해 주는 요청<br>아래 명세를 검증하는 테스트를 써 줘. 구현은 보여 주지 않을게요.<br>- 휴대전화번호는 가운데 4자리를 *로 가린다<br>- 가운데 4자리 외의 문자(하이픈 등)는 그대로 둔다<br>- 번호 형식이 아니면 원본을 그대로 돌려준다</pre><p>앞의 요청은 눈앞의 구현이 기준이 되고, 뒤의 요청은 명세가 기준이 됩니다. 업무 흐름으로 풀면 다섯 단계 정도입니다.</p><p><strong>1. 명세를 문장으로 먼저 씁니다.</strong> 초안은 AI가 써도 되지만 내용이 맞는지는 사람이 봅니다. 명세가 틀리면 틀린 명세를 열심히 검증하는 테스트가 나올 뿐입니다.</p><p><strong>2. AI에게는 구현 대신 인터페이스와 명세를 줍니다.</strong> 그러면 이런 테스트가 나옵니다.</p><pre>it(&#39;번호 형식이 아니면 원본을 돌려준다&#39;, () =&gt; {<br>    expect(maskPhone(&#39;not-a-phone&#39;)).toBe(&#39;not-a-phone&#39;)<br>})</pre><p>처음에 본 구현으로는 이 테스트가 실패합니다. 예외 처리가 없어서 not-****-hone을 돌려주거든요. 여기서는 실패하는 게 맞습니다. 테스트가 명세 위반을 먼저 잡았으니 구현을 고치면 됩니다.</p><p><strong>3. 실패한 테스트의 기대값은 사람이 승인하기 전까지 못 고치게 합니다.</strong> 다섯 단계 중 제일 중요하다고 생각합니다. 앞에서 본 truncate처럼 기대값을 구현에 맞춰 버리는 일을 여기서 막을 수 있습니다.</p><p><strong>4. 예시로 주는 기존 테스트도 점검합니다.</strong> AI는 예시 테스트의 불안정한 부분까지 그대로 따라 합니다.</p><p><strong>5. 생성된 테스트는 받기 전에 걸러 냅니다.</strong> 통과하는지, 여러 번 돌려도 매번 통과하는지 보고, 여유가 있다면 뮤테이션 테스트의 변이까지 잡아내는 테스트만 받습니다.</p><h4>리뷰에서는 기대값의 출처를 묻기</h4><p>PR 리뷰에서 “이 검증이 맞나?”를 묻는 건 조금 늦습니다. AI가 이미 정해 버린 기대값을 뒤늦게 다시 따지는 일이 되니까요. 대신 이런 걸 봅니다.</p><ul><li>기대값이 명세에 적힌 결과 그대로인가, 코드를 실행해서 계산한 값인가</li><li>명세에는 있는데 테스트가 없는 문장이 남아 있지는 않은가</li><li>실패한 테스트를 고쳤다면 구현을 고쳤는가, 기대값을 고쳤는가</li><li>지워진 it 블록이 있다면 그 검증이 다른 곳으로 옮겨 갔는가</li></ul><p>테스트를 고치는 커밋과 구현 커밋을 나눠 두면 이 확인이 훨씬 쉬워집니다.</p><h4>팀의 루틴으로 만들기</h4><ul><li>빌드를 막을 것과 코멘트로 남길 것 나누기: no-floating-promises 같은 lint 규칙과 requireAssertions처럼 걸리면 바로 고쳐야 하는 건 빌드를 실패시킵니다. 정규식 스캔, expect 개수 리포터, 살아남은 변이에는 오탐이나 일부러 남긴 코드가 섞여 있어서 빌드를 막지 않고 걸린 줄을 PR 코멘트로 남깁니다.</li><li>뮤테이션은 PR에서 바뀐 파일만: 저장소 전체를 매번 돌리기에는 느리니 PR에서 바뀐 파일 목록을 Stryker의 --mutate에 넘겨서 돌립니다. 점수만 보면 어디를 보강할지 알 수 없지만, 살아남은 변이를 PR 코멘트로 달면 리뷰하는 사람이 어떤 테스트가 비었는지 그 자리에서 짚을 수 있습니다.</li><li>E2E에 if가 생기면 컴포넌트 테스트로 옮기기: if가 있으면 분기에 따라 아무것도 확인하지 않고 통과하는 실행이 생깁니다. 화면이 데이터에 따라 달라진다면 목 데이터를 넣은 컴포넌트 테스트에서 경우마다 하나씩 확인합니다.</li><li>절차를 스킬로 남기기: 테스트를 쓰는 에이전트에게는 명세를 먼저 받고 실패한 테스트의 기대값은 고치지 않는다는 규칙을, 리뷰 에이전트에게는 정규식 스캔, expect 개수, 살아남은 변이, 기대값의 출처 순서로 보는 절차를 스킬이나 AGENTS.md로 줍니다. AI가 지시를 따르지 않을 수도 있으니 최종 판정은 사람이 합니다.</li></ul><h3>5. 마치며</h3><p>이 글에서 계속 물은 건 “이 테스트의 기대값은 누가 정했나”였습니다. 값을 코드에서 가져오고, 실패하면 기준을 코드에 맞추고, 확인을 건너뛰는 건 모두 그 값을 AI가 정하게 둔 결과입니다. AI 덕분에 테스트 쓰는 시간은 아꼈지만, 그 과정에서 무엇이 맞는지 정하는 일까지 같이 넘겨 버린 건 아닌가 싶습니다.</p><p>테스트가 통과했다는 건 실패 없이 끝까지 돌았다는 뜻이지, 무언가를 확인했다는 뜻은 아닙니다. 기대값은 사람이 명세를 보고 적고, 리뷰에서 놓친 부분을 걸러 줄 안전장치를 둡니다. 그래야 AI의 속도는 살리면서도 믿을 수 있고 가치 있는 테스트를 만들 수 있습니다.</p><p>긴 글 읽어 주셔서 감사합니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=588b724a6002" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/ai-%ED%85%8C%EC%8A%A4%ED%8A%B8%EC%9D%98-%ED%97%88%EC%88%98%EB%A5%BC-%EA%B1%B8%EB%9F%AC%EB%82%B4%EA%B8%B0-588b724a6002">AI 테스트의 허수를 걸러내기</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hilt Custom Component 활용하기]]></title>
            <link>https://medium.com/naverfinancial/hilt-custom-component-%ED%99%9C%EC%9A%A9%ED%95%98%EA%B8%B0-a0452fe2566a?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/a0452fe2566a</guid>
            <category><![CDATA[custom-scope]]></category>
            <category><![CDATA[dagger-2]]></category>
            <category><![CDATA[custom-component]]></category>
            <category><![CDATA[android]]></category>
            <category><![CDATA[hilts]]></category>
            <dc:creator><![CDATA[Myungpyo Shim]]></dc:creator>
            <pubDate>Wed, 11 Nov 2026 06:41:35 GMT</pubDate>
            <atom:updated>2023-02-23T12:52:29.449Z</atom:updated>
            <content:encoded><![CDATA[<h4>Hilt 를 활용한 로그인 스코프 관리하기</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PJlXgYDN8gGEZE7XhB4igg.jpeg" /><figcaption><a href="https://unsplash.com/photos/hfWM_tQCUNc">unsplash.com</a></figcaption></figure><p>안녕하세요. NaverFinancial 앱 개발팀의 심명표 입니다.</p><p>Disclaimer❗️<br>이 글은 Hilt나 Dagger의 기본 사용법에 대해 다루지는 않지만 관련해서 참고할 링크를 본문에 기록하였습니다.<br>DI 가 무엇인지 이미 알고 있고 Custom Component의 사용에 대해서 바로 보고 싶으신 분은 Custom Component로 바로 스크롤 해도 됩니다.</p><h4>DI (Dependency Injection)</h4><p>의존성 주입(DI)이란 무엇이며 왜 사용할까요? 우리가 객체지향으로 어떤 프로그램을 디자인한다고 생각해 봅시다. 아마도 모든 기능을 제공하는 거대한 단일 클래스를 만들어 프로그램을 완성할 수도 있지만 누구도 이런 식으로 프로그램을 만들지는 않습니다. 이런 식의 설계는 본인과 동료 그리고 후임자를 괴롭게 만드는 행동입니다 (물론 오직 나만 다룰 수 있는 프로그램을 만들어 조직에서 대체불가의 직원이 될 수도 있겠죠. <a href="https://m.hanbit.co.kr/store/books/book_view.html?p_code=E2375873090">#유지 보수하기 어렵게 코딩하는 방법</a> 😁).</p><p>그래서 우리는 나와 내 동료의 오후와 행복한 휴일을 위해서 객체지향 디자인 원칙에 따라서 적절하게 클래스를 설계하고 클래스 간의 관계를 정의합니다 (SOLID 원칙에 대해 그림으로 설명하는 <a href="https://medium.com/backticks-tildes/the-s-o-l-i-d-principles-in-pictures-b34ce2f1e898">재미있는 미디엄 글</a>이 있습니다).</p><blockquote>현실 세계를 모델링 한 객체지향은 프로그램 세계에는 맞지 않으며 실패한 패러다임이라는 의견도 있지만 이는 지금 이야기하고자 하는 것과는 다른 주제이며, 이 의견 역시 코드를 한 덩어리로 만들어도 된다는 말은 당연히 아닙니다. 😅</blockquote><p>여러분이 각 클래스를 역할에 따라 세분화하여 디자인하면 클래스 간에는 참조 관계가 생깁니다. 우리는 이것을 의존성이라 부릅니다. 여러분이 프로그램으로 냉온 정수기를 디자인한다고 가정해 봅시다. 정수기 클래스는 물을 데우기 위한 가열기, 물을 냉각하기 위한 냉각기, 그리고 본연의 기능인 물을 정화하기 위한 필터 등의 내부 부속품들이 필요합니다. 이 부속품들은 모두 냉온 정수기의 의존 객체라고 할 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*W0kItWvJaUVVRgyjdIGSfA.png" /></figure><p>이렇게 한 객체(정수기)가 의존하는 객체들(부속)을 개별적으로 정의하고, 각 부속의 기능을 인터페이스로 정의하면 우리는 매우 유연하고 테스트가 용이한 정수기 클래스를 갖게 됩니다. 예를 들면 다음과 같이 정수기 클래스 WaterPurifier 클래스를 정의하면 우리는 다양한 타입의 가열기, 냉각기, 필터 등을 갖는 정수기를 생성할 수 있습니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/2cd9be333fb7383af4054290cef7c698/href">https://medium.com/media/2cd9be333fb7383af4054290cef7c698/href</a></iframe><p>위 샘플 코드에서 WaterTank, Heater, Cooler 등은 모두 각 기능이 정의된 인터페이스이므로 어떤 구현체라도 프로토콜(인터페이스)만 지키면 생성자로 전달될 수 있습니다. 물론 아주 팬시한 구현체가 전달되면 정수기의 성능이 좋아지겠지만 가격 또한 올라가겠죠 😅? 그리고 이렇게 인터페이스를 클래스 생성자로 전달받도록 구현하여 얻게 된 유연성은 이 클래스를 테스트 친화적으로 만들어 줍니다. 클래스를 테스트할 때 각종 부속품 인터페이스의 구현체로 Mock 객체를 전달하여 다양한 상황에서 정수기의 상태를 테스트해 볼 수 있습니다.</p><p>이 정수기 클래스를 생성하면서 각종 부속품의 구현체들을 직접 생성하여 주입하는 방식을 수동 주입(Manual Injection)이라고 합니다. 이처럼 의존성 주입을 하기 위해서 특정 툴이 필요한 것은 아니며 원한다면 직접 구현하는 것도 가능합니다. 하지만 의존성 관리 도구를 사용하면 보다 편리하고 안정적으로 의존성을 주입하고 관리할 수 있습니다. 의존성 관리 도구를 사용하여 얻을 수 있는 장점으로는 손쉬운 의존 오브젝트들의 수명(Scope) 관리를 예로 들 수 있습니다. 여러분이 의존성 주입 방식으로 프로그램을 만들 때, 어떤 의존성들은 애플리케이션과 동일한 스코프를 갖지만 다른 의존성들은 그렇지 못할 수 있습니다. 이런 의존성들의 스코프 관리를 수동으로 하는 것은 다소 번거롭고 실수로 인한 에러가 발생할 수도 있습니다. 의존성 관리 도구를 이용하면 도구에서 정의한 방식에 따라서 손쉽게 의존 오브젝트의 수명을 정의할 수 있습니다.</p><p>이번 포스팅에서는 이러한 의존성 관리 도구들 중에서 안드로이드 플랫폼에서 최근 많이 이용되고 있는 Hilt에 대해 알아보려고 합니다. Hilt는 의존성 관리 도구 중 하나인 Dagger를 보다 편리하게 사용할 수 있도록 지원해 주는 도구입니다. 이 글은 Dagger나 Hilt의 기본적인 사용법은 알고 있다고 가정하고 작성되어 있습니다. Hilt에 대한 보다 자세한 내용은 <a href="https://dagger.dev/hilt/">공식 사이트</a>나 <a href="https://developer.android.com/training/dependency-injection/hilt-android">안드로이드 가이드</a>에서 확인하실 수 있습니다.</p><p>이번 글에서는 Hilt가 제공하는 다양한 기능 중에서도 조금은 고급(?) 주제라고 할 수 있는 Custom Component에 대해 알아보려고 합니다.</p><h4>Custom Component</h4><p>Dagger에는 Component라는 개념이 있습니다. Component는 동일을 스코프를 갖는 오브젝트들로 이루어진 의존성 트리입니다. 동일한 스코프를 갖는다는 것은 해당 트리에 있는 오브젝트들은 동일한 생명주기를 갖는다는 것을 의미합니다. 또한 Component들 간에는 부모-자식 계층 구조를 가질 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1ndsYsU5ce9e1lOUJsixlA.png" /></figure><p>위 그림을 보면 Parent Component에 다수의 오브젝트들의 의존 관계를 나타내는 트리가 정의되어 있습니다. 그리고 Parent Component를 상속하는 Child Component에도 여러 오브젝트들의 의존성 트리가 정의되어 있습니다. Child Component의 오브젝트들은 Parent Component의 오브젝트들을 참조 가능하지만 그 역은 불가능합니다.</p><p>Android 앱 개발 시 Dagger의 Component를 이용하여 의존 오브젝트들이 적절한 스코프를 갖도록 정의하기 위해서는 많은 양의 보일러 플레이트 코드가 필요합니다. 이를 인지한 Android 프레임워크 팀에서는 Android에 필요한 다양한 Dagger Component 들과 유용한 기능들을 묶어 Hilt라는 툴을 제공하였습니다. Hilt에 정의된 컴포넌트들을 잘 활용하면 의존 오브젝트의 생명주기를 세밀하게 관리함으로써 보다 효율적으로 메모리 관리를 할 수 있습니다(Dagger 가 칼의 종류 중 하나이고 Hilt는 칼집을 의미하므로 이번 작명 센스는 정말 놀라웠습니다 😍).</p><p>안드로이드 공식 사이트의 Hilt 관련 페이지에서는 다음과 같이 미리 정의된 컴포넌트들과 스코프들을 소개하고 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*T6NuyyXR77HRIzdINQlXtw.png" /></figure><p>안드로이드를 개발하지 않는 분이라면 SingletonComponent가 애플리케이션 스코프의 컴포넌트이고, ActivityComponent는 각각의 화면 스코프, FragmentComponent는 화면 내부의 보다 작은 영역의 스코프(예를 들어 탭 구조의 화면에서 각 탭의 콘텐츠 영역)라고 생각하시면 될 것 같습니다.</p><p>예를 들어 Singleton Component에 컴포넌트 스코프(Singleton)로 위치한 오브젝트들은 애플리케이션이 종료될 때까지는 계속 동일할 것이고, Activity Component(UI)에 컴포넌트 스코프(ActivityScope)로 위치한 오브젝트들은 해당 화면이 종료되기 전까지만 동일할 것입니다.</p><p>그런데 만약 Hilt가 제공하지 않는 스코프가 필요한 상황이 생긴다면 어떻게 해야 할까요? 다행히 Hilt는 Custom Component를 정의할 수 있는 방법을 제공하고 있으며 다음과 같이 정의할 수 있습니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e909fc064d9c48a90c0813f5c4ef6177/href">https://medium.com/media/e909fc064d9c48a90c0813f5c4ef6177/href</a></iframe><p>Custom Component를 정의할 때는 다음의 두 가지 제약이 있습니다.</p><ul><li>SingletonComponent 혹은 그 하위 컴포넌트를 상속해야 함</li><li>Hilt에 미리 정의된 컴포넌트들 중간에 위치할 수 없음</li></ul><p>이런 Custom Component는 어떤 경우 필요할까요? 대표적인 예로는 로그인 한 사용자의 스코프에 대응되는 컴포넌트가 필요할 경우입니다. 다음의 컴포넌트 트리를 살펴봅시다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_a1kh3i1P2knehLOCMVpxQ.png" /></figure><p>이미 알고 있듯이 Singleton, Activity, Fragment 컴포넌트들은 Hilt 가 미리 정의하여 제공하는 컴포넌트들입니다. Singleton Component, Activity Component, Fragment Component는 각각 애플리케이션, Activity UI, Fragment UI의 시작부터 종료까지의 스코프를 갖는 의존성 트리들입니다. 왼쪽에 User Component는 사용자 정의 스코프를 갖는 의존성 트리로 앞서 언급한 로그인을 예로 들자면 로그인 된 사용자를 스코프로 갖는 트리라고 할 수 있습니다. 이 의존성 트리는 사용자 A가 로그인되어 있으면 A를 위한 객체를 주입할 것이고, 사용자 B로 사용자가 변경되면 의존성 트리를 다시 만들어 사용자 B를 위한 객체를 주입할 것입니다. 물론 아무도 로그인되어 있지 않다면 유효하지 않은 객체를 주입하여 오류를 발생시킬 것입니다.</p><p>여기서 잠시 한 가지 헷갈릴 수 있는 부분을 짚고 넘어가겠습니다. Singleton Component에 의존성을 제공하는 모듈이라고 해서 모듈이 제공하는 모든 의존성이 Singleton인 것은 아닙니다. 예를 들어 다음과 같이 어떤 모듈이 Singleton Component에 설치(Install) 된 경우 MyRepository1은 @Singleton으로 제공되므로 Singleton Component 의존성 트리에서 유일하게 존재하게 되지만 MyRepository2 은 호출될 때마다 새로운 객체가 생성되어 주입됩니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3660672de850b537a001baed2f431ce4/href">https://medium.com/media/3660672de850b537a001baed2f431ce4/href</a></iframe><p>의존성 트리가 다음과 같이 Activity Component였다면 어떨까요?</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3e71734216d96d6dd53290066fa5d78e/href">https://medium.com/media/3e71734216d96d6dd53290066fa5d78e/href</a></iframe><p>MyRepository1은 @Singleton으로 제공되지만 이는 어디까지나 Activity Component 의존성 트리에서 Singleton인 것입니다. Activity 가 종료되고 다시 시작하면 새로운 MyRepository1객체를 주입받게 됩니다. MyRepository2의 경우에는 마찬가지로 항상 새로운 객체를 주입받게 됩니다.</p><p>이제 실제로 이러한 Custom Component를 이용하여 로그인 된 사용자 스코프의 컴포넌트를 정의하여 사용하는 예제를 만들어 보겠습니다. 예제는 아주 단순한 할 일 관리 앱(ToDo)이며 Mock API로 로그인 된 사용자의 할 일 목록을 조회, 추가, 삭제하는 기능을 제공합니다. 아래는 샘플 앱의 몇 가지 화면들입니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GyRRex62oIwNPr2TwTaz9g.png" /></figure><p>A : 로그인 되지 않은 화면<br>B : test1 사용자로 로그인 된 화면<br>C : test1 사용자 할 일 입력 화면<br>D : test2 사용자 할 일 화면</p><blockquote>이 샘플 앱의 전체 코드는 아래 Git Repository에서 확인하실 수 있습니다.<br>(<a href="https://github.com/myungpyo/HiltCustomComponentSample">https://github.com/myungpyo/HiltCustomComponentSample</a>)</blockquote><p>이 샘플 앱은 Dagger와 Hilt를 이용한 DI를 적용할 것이며, 특히 사용자의 할 일 데이터를 관리하는 레이어는 로그인 된 사용자마다 자신의 데이터를 관리할 수 있어야 하기 때문에 사용자 정의 컴포넌트인 AuthUserComponent를 정의하여 사용할 것입니다. 다음 이미지는 이 샘플 앱의 대략적인 컴포넌트 관계를 보여줍니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zlt7S4fIWDhtF0QVjIoE3Q.png" /></figure><p>앞서 언급했듯이 Singleton, Activity, Fragment Component는 Hilt가 자체적으로 정의하여 제공하는 컴포넌트입니다. 샘플 앱에서는 사용자 로그인 상태를 나타내는 UserAuth 클래스를 Sealed class로 다음과 같이 정의하였습니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/49ed73b924383086a3af784f1a3e23a3/href">https://medium.com/media/49ed73b924383086a3af784f1a3e23a3/href</a></iframe><p>그리고 이 데이터 클래스를 관리하기 위한 UserAuthSession이라는 클래스를 정의하고 Singleton Component에 위치시킵니다. login() 함수가 호출되면 로그인을 수행하고 currentAuth 상태를 Authenticated로 변경하고, logout()함수가 호출되면 currentAuth 상태를 Unauthenticated로 변경합니다. currentAuth 속성을 구독 중인 Flow Collector들은 로그인, 로그아웃 상태 변경에 따라 이를 수신합니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/75c14392e1ab5e93ae3a81281151668d/href">https://medium.com/media/75c14392e1ab5e93ae3a81281151668d/href</a></iframe><p>다음 그림은 샘플 프로젝트에서 UserAuthSession에 로그인, 로그아웃 이벤트가 발생함에 따라 AuthUserComponent(Custom Component)를 다시 빌드 하여 관련된 오브젝트들이 재생성 되도록 하는 모습을 나타냅니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mGM9m8iicV5Sku6RimiNKQ.png" /></figure><p>가운데 샘플 앱의 화면에서 시작해 봅시다.</p><p>가장 위에는 사용자 정보를 표시하는 뷰가 있습니다. 이 뷰는 왼쪽에 표시된 UserAuthSession을 구독하여 로그인, 로그아웃 이벤트에 따라 상태를 표시합니다.</p><p>그 아래는 사용자의 할 일 목록을 보여주는 프래그먼트(MainFragment)가 있습니다. 이 프래그먼트는 ViewModel을 통해서 현재 로그인 된 사용자의 할 일 데이터를 가져와 보여줍니다. ViewModel은 ToDoRepository를 이용하는데 이 Repository는 다양한 DataSource로부터 사용자 할 일 데이터를 가져옵니다. 만약 다른 사용자가 로그인하면 MainFragment를 포함한 빨간색 박스 영역이 모두 변경된 사용자에 맞추어 재생성 됩니다 (AuthUserComponentManager는 잠시 뒤에 알아봅시다).</p><p>우리는 ToDoRepository 및 다양한 DataSource들을 로그인 된 사용자 스코프로 주입되도록 할 것입니다. 다시 말하면 앱이 시작되어 특정 사용자로 로그인되면 계속 동일한 ToDoRepository 및 DataSource 오브젝트들을 사용하다가 로그아웃 혹은 다른 사용자로 로그인되면 새로운 사용자를 위한 오브젝트들을 사용하도록 할 것입니다.</p><p>그러기 위해서 먼저 ToDoRepository와 DataSource들이 제공될 Custom Component를 만들어 봅시다. 먼저 우리가 정의할 컴포넌트를 나타낼 스코프를 정의합니다 (필수는 아닙니다).</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/85c4e70ad4edad90882514433fcf9016/href">https://medium.com/media/85c4e70ad4edad90882514433fcf9016/href</a></iframe><p>그리고 위에서 생성한 스코프를 이용하는 Custom Component를 다음과 같이 정의합니다 (Builder는 별도의 파일에 생성하는 것이 권장 사항입니다).</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d97f35393d8d137663648b234ab46748/href">https://medium.com/media/d97f35393d8d137663648b234ab46748/href</a></iframe><p>이제 Repository와 DataSource들이 Custom Component에 제공될 수 있도록 모듈을 생성해 봅시다 (샘플 앱에서는 간결하게 하고자 InMemoryDataSource만을 사용하고 있습니다).</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/4da32d3792e6eeab0f6c021c327fc02c/href">https://medium.com/media/4da32d3792e6eeab0f6c021c327fc02c/href</a></iframe><p>ToDoModule은 앞서 정의한 Custom Component인 AuthUserComponent에 설치(@InstallIn) 되고 있습니다. 이 모듈은 DataSource와 Repository를 바인딩 형식으로 정의하는데 Repository에는 @AuthUserScope가 추가되어 있습니다. 이 경우 두 바인더의 차이는 무엇일까요? @AuthUserScope가 붙은 Repository는 AuthUserComponent 의존성 트리가 소멸할 때까지 유지되지만 DataSource는 주입 시마다 재생성 됩니다. 예제에서 ViewModel은 데이터를 조작하기 위해서 Repository로만 접근할 것이고 Repository는 내부적으로 DataSource들을 이용하므로 이렇게 해도 괜찮지만 만약 DataSource가 여러 곳에서 주입되어 이용되는 상황에서 로그인 된 사용자 당 하나의 객체만 유지하고 싶다면 @AuthUserScope를 사용해야 합니다.</p><p>자, 이제 UI 코드 레벨에서 AuthUserComponent에 정의된 오브젝트들을 주입 받아야 할 차례입니다. Hilt에서 기본적으로 제공하는 Singleton, Activity, Fragment 등의 컴포넌트에서 제공하는 의존성들은 별다른 처리 없이 각각의 스코프에서 제공받을 수 있지만 Custom component인 AuthUserComponent에 접근하기 위해서는EntryPoint가 필요합니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/badc94dcff82a9991711f412bc552073/href">https://medium.com/media/badc94dcff82a9991711f412bc552073/href</a></iframe><p>AuthUserComponent 의존성 트리에서 ToDoRepository를 제공받을 수 있는 EntryPoint를 정의하였습니다. 이제 UI에서 다음과 같이 ToDoRepository를 주입받을 수 있습니다. EntryPoints.get() 함수의 첫 번째 파라미터로는 컴포넌트 또는 @AndroidEntryPoint로 표시된 클래스 오브젝트를 제공해야 하는데, 여기서는 authUserComponentManager를 이용하여 EntryPoint에 접근 후 ToDoRepository를 주입받고 있습니다.</p><blockquote><a href="https://dagger.dev/api/latest/dagger/hilt/android/EntryPointAccessors.html">EntryPointAccessor</a>를 이용하면 Android Entry Point를 가져올 때 보다 타입에 안전하게 가져올 수 있습니다.</blockquote><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/d2248d7c4545221d28e13e254f5c58a2/href">https://medium.com/media/d2248d7c4545221d28e13e254f5c58a2/href</a></iframe><p>AuthUserComponent는 다음과 같이 구현되어 있습니다. EntryPoint가 AuthUserComponent에 접근할 수 있는 것은 AuthUserComponentManager가 GeneratedComponentManager&lt;AuthUserComponent&gt;를 구현하고 있기 때문입니다. 이 인터페이스를 구현한 부분은 31번 라인뿐이며 generatedComponent()가 호출되면 현재 authUserComponent를 반환합니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/3d961456a403564ed88f47d4525fdc4d/href">https://medium.com/media/3d961456a403564ed88f47d4525fdc4d/href</a></iframe><p>AuthUserComponentManager는 한 가지 기능을 더 제공하는데 그것은 주입받은 userAuthSession을 구독하다가 로그인, 로그아웃 이벤트 발생 시 AuthUserComponent를 재생성하는 것 입니다 (14~24 라인). 추가적으로 원하는 시점에 언제든 rebuildComponent() 함수를 호출하면 컴포넌트를 재생성합니다.</p><p>그런데 UI에서 EntryPoint를 통해 접근하는 것이 영 불편하네요. 다음과 같이 AuthUserCompoent로의 브리지를 생성하면 애플리케이션 스코프에서 언제든 현재 사용자 스코프의 오브젝트들을 주입받을 수 있습니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/9f7a41121efc06520c5a6938351654ce/href">https://medium.com/media/9f7a41121efc06520c5a6938351654ce/href</a></iframe><p>저는 실제 프로젝트에서는 UseCase 클래스들에서 Repository 접근을 하도록 설계하고 UseCase 클래스에서 AuthUserComponent의 EntryPoint에 접근하도록 하고 UseCase 구현 클래스들은 @Inject 어노테이션을 통해 필요한 객체를 주입받아 사용할 수 있도록 하였습니다.</p><p>Custom Component는 Hilt에서 지원되지 않는 스코프를 정의하여 의존성 그래프를 좀 더 세밀하게 다룰 수 있게 해주는 장점이 있지만, 컴포넌트가 추가되면서 전체 의존성 그래프를 복잡하게 만들고 그로 인해 성능을 약간 떨어뜨리는 단점도 있습니다. 또한, 비표준 컴포넌트이므로 해당 컴포넌트로 외부 라이브러리와의 연동은 어려울 수 있습니다.</p><p>꼭 필요한 부분에 제한적으로 사용한다면 오브젝트들이 불필요하게 메모리를 차지하지 않도록 더 잘 관리할 수 있게 됩니다.</p><p>끝. 😁</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a0452fe2566a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/hilt-custom-component-%ED%99%9C%EC%9A%A9%ED%95%98%EA%B8%B0-a0452fe2566a">Hilt Custom Component 활용하기</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Playwright E2E 테스트로 자가개선 루프 구축하기]]></title>
            <link>https://medium.com/naverfinancial/playwright-e2e-%ED%85%8C%EC%8A%A4%ED%8A%B8%EB%A1%9C-%EC%9E%90%EA%B0%80%EA%B0%9C%EC%84%A0-%EB%A3%A8%ED%94%84-%EA%B5%AC%EC%B6%95%ED%95%98%EA%B8%B0-43b437b842fa?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/43b437b842fa</guid>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[frontend]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[claude-code]]></category>
            <dc:creator><![CDATA[Hewon Jeong]]></dc:creator>
            <pubDate>Fri, 03 Jul 2026 05:04:00 GMT</pubDate>
            <atom:updated>2026-07-03T05:03:59.422Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kzrSyJwaSeeaUYdStnpc9w.png" /></figure><p>안녕하세요. 네이버페이 금융FE 팀의 정회원입니다. 사내 ENGINEERING DAY 2026에서 발표한 “AI 에이전트를 위한 Playwright E2E 테스트 하네스 구축하기” 내용을 글로 옮기고 일부 설명을 덧붙였습니다. 발표 영상은 <a href="https://d2.naver.com/helloworld/6811215">NAVER D2</a>나 <a href="https://www.youtube.com/watch?v=wo0Rsh9hlTo">YouTube</a>에서 보실 수 있습니다.</p><h3>검증이 병목이다</h3><p>2026년, AI가 코드를 짜는 시대가 되며 코딩은 확실히 빨라졌습니다. 제가 주로 작업하는 코드베이스에서 개발자 한 명이 머지한 PR을 세어봤더니, AI 도구를 본격 도입하기 전 9개월은 227건, 도입 후 9개월은 348건으로 1.5배가 됐습니다.</p><p>그럼 PR이 늘어난 만큼, 검증도 1.5배 더 잘 되고 있을까요? 한번은 에이전트에게 Next.js 버전 업그레이드를 맡겼더니 얼마 뒤 ‘문제없이 완료했습니다.’ 라고 보고하고 PR도 작성했습니다. 그런데 막상 돌려보니 특정 페이지에서 뒤로가기를 눌렀을 때 기존 동작이 깨져 있었습니다. 프레임워크 내부 구현이 바뀌면서 기존 기능이 영향을 받은 것인데, 에이전트는 이걸 확인하지 않은 채 ‘끝났다’고 보고한 것입니다.</p><p>여러분도 누군가가 바이브 코딩하고 검토 없이 올린 PR을 보고 당황하신 적이 있으실 겁니다. PR마다 로컬에 받아 직접 돌려보고, 문제 없는지 확인할 수 있을까요? 쏟아지는 변경을 사람이 일일이 살펴보는 건 현실적으로 불가능합니다.</p><p><strong>즉, 코딩은 빨라졌지만 검증이 병목이 된 것입니다.</strong></p><p>간단한 스크립트나 사내 도구라면 일단 배포하고, 문제가 생기면 그때 손봐도 됩니다. 하지만 수십만 명이 쓰는 서비스라면, 걸러지지 않은 결함이 심각한 사업적 타격으로 이어질 수 있습니다. 그렇다고 전부 QA 팀에 떠넘길 수도 없는 노릇입니다. AI가 쓴 코드, 어떻게 검증해야 할까요?</p><h3>AI에게 검증할 수단을 주자</h3><iframe src="https://cdn.embedly.com/widgets/media.html?type=text%2Fhtml&amp;key=a19fcc184b9711e1b4764040d3dc5c07&amp;schema=twitter&amp;url=https%3A//x.com/bcherny/status/2044847858634064115&amp;image=https%3A//i.embed.ly/1/image%3Furl%3Dhttps%253A%252F%252Fpbs.twimg.com%252Fprofile_images%252F1902044548936953856%252FJ2jeik0t_200x200.jpg%26key%3Da19fcc184b9711e1b4764040d3dc5c07" width="500" height="281" frameborder="0" scrolling="no"><a href="https://medium.com/media/c5f0d8d7e564b7e2b450435729f83521/href">https://medium.com/media/c5f0d8d7e564b7e2b450435729f83521/href</a></iframe><p>Claude Code를 만든 Boris Cherny는 얼마 전 X(트위터)에 ‘<em>Claude에게 자기 작업을 검증할 수단을 줘라. 이건 늘 결과를 2~3배 끌어내는 방법이었다.’ 라고 </em>남겼습니다. 모델에게 검증 수단을 제공하는 것이, 모델이 똑똑해질수록 오히려 더 중요해졌다는 이야기였습니다.</p><p>개발자가 자신이 쓴 코드의 결함을 잘 못 찾듯, 모델도 자기가 짠 코드에 대해서는 관대합니다. ‘이 정도면 잘했네’ 하고 작업을 끝내버립니다.</p><p>모델에게 검증할 수단을 주기 위해 가장 먼저 떠올린 방법은 에이전트가 직접 브라우저를 조작하게 하는 것이었습니다. Vercel의 <a href="https://github.com/vercel-labs/agent-browser">Agent Browser</a>, Claude의 <a href="https://www.anthropic.com/news/claude-for-chrome">Chrome 익스텐션</a>, <a href="https://github.com/microsoft/playwright-mcp">Playwright MCP</a> 같은 도구들이 이미 나와 있었습니다. 이런 도구를 쥐어주면, AI 에이전트도 사람처럼 화면을 확인하고 브라우저를 직접 조작할 수 있습니다. 덕분에 사람이 매번 직접 확인하던 부담은 확실히 줄었습니다.</p><p>문제는 코드를 고칠 때마다 에이전트에게 그 시나리오를 처음부터 다시 시켜야 한다는 점이었습니다. 시나리오를 마크다운에 적어두고 반복하게 할 수는 있었지만, 매번 실행이 오래 걸리고, 토큰도 많이 소모됩니다.</p><p>무엇보다 결과가 비결정론적입니다. 필요한 건 에이전트가 언제 돌려도 똑같이 동작하는 <strong>결정론적인 테스트 코드</strong>였습니다.</p><p><strong>🥵 에이전트에게 매번 건네는 테스트 시나리오</strong></p><pre>1. 대출 비교 페이지(/loan)를 연다<br>2. 한도조회 버튼을 누른다<br>3. 한도조회 결과가 보이는지 확인한다</pre><ul><li>매번 처음부터 다시 실행 → 느리고 토큰을 많이 소모</li><li>에이전트가 매번 새로 해석해 조작 → 비결정론적</li></ul><p><strong>✅ 한 번 짜두는 테스트 코드</strong></p><pre>test(&#39;한도조회 버튼을 누르면 결과가 보인다&#39;, async ({ page }) =&gt; {<br>  await page.goto(&#39;/loan&#39;)<br>  await page.getByRole(&#39;button&#39;, { name: &#39;한도조회&#39; }).click()<br>  await expect(page.getByRole(&#39;heading&#39;, { name: &#39;한도조회 결과&#39; })).toBeVisible()<br>})</pre><ul><li>LLM 없이 즉시 실행 → 빠르고 토큰을 쓰지 않음</li><li>코드가 그대로 실행 → 언제 돌려도 같은 동작(결정론적)</li></ul><h3>유닛 테스트로는 안 될까?</h3><p>E2E 테스트를 도입하기 전부터 저희 코드베이스에는 Vitest와 react-testing-library로 짠 단위/통합 테스트가 이미 갖추어져 있었습니다. 그래서 처음엔 <em>‘단위/통합 테스트를 더 촘촘하게 짜면 되는 것 아닌가?’</em> 라는 의문이 들었습니다. 하지만 에이전트가 코딩 하는 시대에, 이것만으로는 부족했습니다.</p><p>예를 들어 기능 하나가 미들웨어, 서버 로직, UI 컴포넌트, 이렇게 셋으로 나뉘어 있다고 해보겠습니다. 각각의 단위 테스트는 모두 통과합니다. 그런데 실제로 브라우저에서 실행해보면, 미들웨어가 넘긴 데이터 형식이 UI 컴포넌트가 기대한 것과 어긋나 있고, 서버에서 채운 상태가 화면까지 넘어오지 않고, 특정 상황에서 API 호출이 실패합니다.</p><p>셋 다 스펙대로 동작하지만, 합쳐서 실행하면 그 사이 경계에서 틀어집니다. <strong>AI가 코드를 짜는 시대에는 오류의 대부분이 이러한 경계에서 발생했습니다.</strong> 그러니 검증도 사용자의 실제 실행 환경과 유사할 필요가 있었습니다. 그게 바로 Kent C. Dodds가 소개한 <a href="https://kentcdodds.com/blog/write-tests">Testing Trophy</a>의 맨 위에 있는 End-to-End 테스트입니다.</p><figure><img alt="아래에서 위로 Static, Unit, Integration, End to End 순으로 쌓인 테스팅 트로피 도식" src="https://cdn-images-1.medium.com/max/1024/1*DTYdxMvMpXGdCdegeL0fqQ.png" /><figcaption>Kent C. Dodds가 소개한 Testing Trophy. 위로 갈수록 느리고(🐢) 비싸진다(💲).</figcaption></figure><p>E2E 테스트는 실제 브라우저 환경에서 사용자가 보는 UI부터 모킹되지 않은 백엔드 API까지 통째로 검증하는 만큼, 실행도 느리고, 깨지기도 쉽습니다. 그래서 많은 팀에서 일부러 비워두기도 하고, 저희 역시 QA 팀의 검증에 의존하고 있었습니다.</p><p>그런데 AI가 코딩을 하는 시대가 되면서 상황이 바뀌었습니다. 테스트를 짜고 고치는 부담은 AI에게 맡길 수 있으니 작성 비용이 내려갔고, 코드가 쏟아지는 만큼 전체 시스템 수준의 검증은 중요도가 커졌습니다. 이전엔 비싸다는 이유로 미뤄뒀던 자리가, <strong>이제는 비용을 충분히 감수할 만한 가치가 있는 자리가 된 것입니다.</strong></p><h3>End-to-End 테스트 도입하기</h3><p>막상 E2E 테스트 환경을 구축할 때 가장 고민되는 것은 ‘무엇부터 테스트할 것인가’ 일 것입니다.</p><p>저희가 작업하는 코드베이스는 6년 차에 17만 줄, 페이지만 220개가 넘는 대규모 Next.js 프로젝트였습니다. 이러한 상황에서 모든 기능, 모든 분기를 E2E로 검증하는 건 비현실적이었습니다.</p><p>E2E 테스트는 UI부터 백엔드 API까지 넓은 영역을 검증하는 만큼 실행이 느리고, 작은 변경에도 쉽게 깨질 수 있습니다. 그래서 ‘테스트는 많을수록 좋다’로 접근하면 실행 시간이 길어지고, ‘오히려 생산성이 나빠졌다’고 느끼기 십상입니다.</p><blockquote>Write tests. Not too many. Mostly integration. — Guillermo Rauch (<a href="https://x.com/rauchg/status/807626710350839808">원문</a>)</blockquote><p>그래서 저희는 <strong>가장 핵심적인 사용자 플로우(critical user flow)</strong>부터 시작했습니다. 제가 주로 작업하는 <a href="https://loan.pay.naver.com/n/credit">네이버페이의 대출 서비스</a>에서는 사용자가 약관에 동의하고, 인증을 거쳐 대출상품 조회 및 신청까지의 흐름이 여기에 해당합니다.</p><p>그렇게 각 상품(신용, 주담대, 전월세 등)의 주요 플로우 10개(37개 라우트)에 자동화 테스트를 더하는 것으로 출발했습니다. 이 10개 플로우를 개발자가 직접 약관 동의부터 인증, 상품 조회까지 하나씩 클릭해 확인하면 20분이 넘게 걸립니다. 같은 검증을 이제 pnpm e2e 명령어 한 번이면 여러 테스트 계정을 병렬로 돌려 3분 만에 끝낼 수 있게 된 것입니다.</p><figure><img alt="Playwright trace viewer 화면. 상단 타임라인, 좌측 단계별 액션 목록, 우측 각 단계의 화면 스냅샷" src="https://cdn-images-1.medium.com/max/800/1*idIDtDXo8aE767TffV9oSQ.gif" /><figcaption><em>테스트 실행 결과 예시 (</em><a href="https://playwright.dev/docs/trace-viewer"><em>Playwright trace viewer</em></a><em>)</em></figcaption></figure><h3>무엇을 테스트할지, 데이터로 찾기</h3><p>그럼 본격적으로 테스트 범위를 넓혀갈 때는 어떻게 정할까요? 오래 운영된 코드베이스라면 git 히스토리, 과거 QA 이슈처럼 어디가 위험한지 이미 데이터가 쌓여 있습니다. 예를 들면, 다음 네 가지 신호를 활용해 볼 수 있습니다.</p><ul><li><strong>변경 빈도: </strong>자주 바뀌는 곳일수록 회귀 위험이 크다 (데이터 소스: git 커밋 변경 이력)</li><li><strong>결함 밀도: </strong>과거에 결함이 자주 보고된 곳, Critical/Major면 가중 (데이터 소스: QA 이슈 이력)</li><li><strong>비즈니스 중요도: </strong>막히면 매출과 신뢰가 흔들리는 곳 (데이터 소스: 페이지 조회/클릭 로그, 기획 판단)</li><li><strong>커버리지 공백: </strong>아직 E2E 테스트가 없는 곳, 우선순위 배수 (데이터 소스: 기존 E2E 테스트 코드)</li></ul><p>이 신호들을 묶어 위험도를 측정합니다.</p><p><strong>위험도 ≈ (결함 밀도 × 변경 빈도 × 비즈니스 중요도) × 커버리지 공백</strong></p><p>데이터를 모으는 스크립트는 AI의 도움을 받아 빠르게 작성할 수 있고, 비즈니스 중요도처럼 숫자로 떨어지지 않는 신호는 사람이 직관으로 가중치를 조절하여 우선순위를 정할 수 있습니다.</p><h3>테스트를 ‘작성’하지 않고 ‘생성’하기</h3><p>무엇을 테스트할지 정했다면, 다음은 어떻게 짜느냐의 문제입니다. 저희 팀은 대부분이 Playwright을 사용해본 적이 없었고, 테스트 작성 자체가 익숙하지 않은 팀원도 있었습니다. 그래서 시작은 아예 직접 짜지 않는 것을 목표로 하였습니다.</p><p>Playwright는 <a href="https://playwright.dev/docs/codegen">Test Generator(codegen)</a>를 공식으로 제공합니다. 코드를 직접 ‘작성’하는 게 아니라, 브라우저 조작을 녹화하면 테스트 코드를 ‘생성’해 주는 도구입니다.</p><pre>npx playwright codegen -o test.spec.ts https://example.com</pre><p>명령을 실행하면 브라우저 창과 코드가 기록되는 Inspector 창이 열립니다. 브라우저에서 클릭하고 입력하면, 그 동작이 녹화되어 그대로 테스트 코드로 만들어집니다.</p><figure><img alt="Playwright codegen 화면. 왼쪽 브라우저 조작이 오른쪽 Inspector에 테스트 코드로 기록된다" src="https://cdn-images-1.medium.com/max/800/1*0UKPszEpgTQjCpicfZc8uQ.gif" /><figcaption><em>브라우저를 조작하면 그대로 테스트 코드가 생성되는 Playwright codegen</em></figcaption></figure><p>이렇게 생성된 코드는 그대로도 실행되지만, 모든 동작이 한 함수에 평면적으로 나열된 상태입니다.</p><pre>// ⚠️ Test Generator로 생성한 초안<br>test.use({<br>  storageState: &#39;tmp/auth.json&#39;,<br>  viewport: { width: 540, height: 1200 },<br>})<br><br>test(&#39;test&#39;, async ({ page }) =&gt; {<br>  await page.goto(&#39;https://example.com&#39;)<br>  await page.getByRole(&#39;button&#39;, { name: &#39;필수 약관 동의&#39; }).click()<br>  await expect(page.getByRole(&#39;heading&#39;, { name: &#39;본인인증&#39; })).toBeVisible()<br>  await page.getByRole(&#39;textbox&#39;, { name: &#39;이름&#39; }).fill(&#39;홍길동&#39;)<br>  // ...<br>})</pre><p>여기서 에이전트의 도움을 받을 수 있습니다. 테스트 작성에 필요한 유틸과 맥락 문서를 미리 갖춰 두면, 에이전트가 그걸 참고해 기존 테스트 컨벤션에 맞게 정리해 줍니다. 단계를 test.step으로 묶고, 인증이나 상태 초기화는 공통 유틸로 분리하고, 실제로 실행해 실패하지 않는지 검증까지 위임할 수 있습니다.</p><pre>// ✅ 에이전트가 컨벤션에 맞춰 정리한 결과<br>const test = base.extend({ storageState: getAuthState(&#39;신용_개인&#39;) })<br><br>test(&#39;약관 동의 후 본인인증 진입&#39;, async ({ page }) =&gt; {<br>  await test.step(&#39;약관 동의&#39;, async () =&gt; { ... })<br>  await test.step(&#39;본인인증 진입&#39;, async () =&gt; { ... })<br>  await test.step(&#39;이름 입력&#39;, async () =&gt; { ... })<br>})</pre><h3>테스트 작성도 전부 AI에게 맡길 수 있을까?</h3><p>codegen은 사람이 직접 실행하여 초안을 생성하고, AI로 다듬는 방식입니다. 아예 테스트 계획부터 작성, 수정까지 모두 AI에게 맡길 수 있을까요? Playwright는 이를 위해 <a href="https://playwright.dev/docs/test-agents">공식 3개의 에이전트</a>를 제공하고 있습니다.</p><pre># 사용하는 AI 도구를 --loop 옵션으로 전달 (claude, codex, opencode 등)<br>npx playwright init-agents --loop=claude</pre><ul><li><strong>Planner: </strong>무엇을 테스트할지 계획을 세우는 에이전트입니다. 코드베이스와 화면을 직접 탐색해 어떤 플로우를 테스트할지 짚고, 목적과 단계, 검증 포인트를 마크다운 계획서로 정리합니다. 덕분에 코드가 만들어지기 전에 사람이 시나리오를 먼저 검토할 수 있습니다.</li><li><strong>Generator: </strong>그 계획을 기반으로 실제 테스트 코드를 작성하는 에이전트입니다. 각 단계를 실제 브라우저에서 실행해 보며 코드를 만들고, 의도대로 동작하는지 그 자리에서 확인합니다.</li><li><strong>Healer: </strong>실패한 테스트를 고치는 에이전트입니다. 실패한 지점을 다시 실행해 원인을 분석하고, 통과할 때까지 수정과 재실행을 반복합니다.</li></ul><p>LLM에게 계획, 작성, 수정을 한꺼번에 맡기면 잘 안 됩니다. 단계를 쪼개 한 가지에만 집중하게 한 구성이고, 그래서 셋은 따로도, 순차적으로 이어서도, 루프 안에서 계속 도는 형태로도 쓸 수 있습니다.</p><h3>그럼 이 세 에이전트들만 있으면 충분할까?</h3><p>Playwright가 이 세 에이전트에 테스트 계획과 작성에 대한 베스트 프랙티스와 절차를 잘 담아 두었습니다. 그럼 이 에이전트들만 설치하면 알아서 테스트 구축이 자동화될까요? 아쉽게도 처음부터 잘되진 않았습니다. 막상 아무 준비 없이 돌려보면, 인증 setup을 건너뛰고, 자주 나는 API 에러도, 테스트 계정 사용법도 모릅니다. 에이전트는 우리 코드베이스의 맥락이 없기 때문입니다.</p><p>결국 신입 개발자를 온보딩하듯, <strong>에이전트에게도 맥락과 환경을 알려주는 게 필요합니다.</strong> 저희가 주로 구성했던 것은 크게 네 가지입니다.</p><ul><li><strong>AGENTS.md (CLAUDE.md):</strong> 에이전트가 코드베이스에 처음 진입할 때 읽는 안내서. 프로젝트 구조, 컨벤션, 어디서부터 봐야 하는지를 담습니다. 테스트 작성에만 쓰이는 건 아니고, 에이전트가 이 코드베이스에서 일하기 위한 가장 기본적인 맥락이라 평소에도 갖춰두면 좋습니다 (참고: <a href="https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/">How to write a great agents.md — GitHub Blog</a>).</li><li><strong>E2E 테스트 가이드(e2e-testing.md): </strong>현재 코드베이스에서 E2E 테스트를 어떻게 작성하고 실행하는지에 대한 단일 출처 문서. 코드 상으로 드러나지 않는 컨벤션이나, 자주 나오는 에러에 대한 해결책, 테스트 작성 시 유의할 점 등을 담습니다.</li><li><strong>테스트 작성을 위한 유틸/헬퍼: </strong>인증 상태를 재사용하고, 테스트 계정을 초기화하고, 테스트 상태를 세팅하는 함수들. AI 에이전트가 매번 예측하여 짜는 것보다, 이미 짜여 있는 것을 가져다 쓰는 게 훨씬 빠르고 안정적입니다.</li><li><strong>MCP: </strong>GitHub 이슈, Figma 등 사내에서 이미 논의된 맥락, 디자인 스펙에 에이전트가 직접 접근하도록 연결합니다.</li></ul><p>이렇게 맥락과 환경을 갖춰 두면, 이후 테스트 작성은 명령 몇 줄로 끝납니다. Planner에게 “주담대 지역 검색 테스트 계획을 짜줘, 회귀 방지가 목적이야”라고 던지면 이슈와 코드베이스, 팀 가이드를 훑어 단계별 계획서를 내놓습니다. 계획은 AI가 세우고 사람이 검토하며, 환경만 잘 깔아 두면 코드 작성까지 AI가 합니다.</p><p>Planner가 내놓는 계획서를 간략히 표현하면 이런 모습입니다.</p><pre># 주담대 신규 &gt; 지역 검색 스텝 전환 플로우<br>목적: 지역 검색으로 단지를 선택하는 핵심 플로우의 회귀 방지<br><br>## 단계<br>1. 주담대 홈 진입 → 약관 동의<br>2. 대출 목적 &#39;주택 구입&#39; 선택<br>3. &#39;지역으로 찾기&#39; → 시/도 → 시/군/구 → 읍/면/동 선택<br>4. 단지 선택 → 평형 선택 모달 확인<br><br>## 검증 포인트<br>- 각 단계에서 다음 화면이 노출되는가<br>- 단지 선택 시 &#39;평형 선택&#39; 모달이 뜨는가</pre><p>Generator는 이 계획을 받아 Playwright 스킬을 사용하고, 기존 컴포넌트와 훅, e2e 테스트와 가이드 문서 등을 훑으며 팀 컨벤션을 파악하고, 각 단계를 실제 브라우저에서 실행해 셀렉터와 동작을 확인하며 코드를 만듭니다. 그렇게 나온 코드가 type-check와 ESLint, 실제 실행까지 통과하는지 스스로 확인한 뒤 작업을 마칩니다.</p><h3>테스트를 단단하게 만들기</h3><p>사람이든 에이전트든 테스트를 만들 수 있게 됐다면, 다음은 그 테스트가 엉뚱한 이유로 깨지지 않게 단단하게 만드는 일입니다. 테스트끼리 서로 간섭하거나 통제할 수 없는 외부 의존성에 휘둘리면, 정작 검증하려던 것과 무관하게 테스트가 깨집니다. 뒤에서 다룰 자가개선 루프도 이렇게 단단한 테스트 위에서야 헛돌지 않습니다.</p><h4>테스트를 독립적으로 만들기</h4><p>E2E 테스트는 여러 시나리오가 앞 단계를 똑같이 거치는 경우가 많습니다. 저희 대출 서비스도 약관 동의와 휴대폰 인증까지는 똑같이 밟고, 그 뒤로 이전 정보 재사용, 직장 정보 입력, 전자증명서 등으로 사용자마다 갈래가 나뉩니다. 각 갈래마다 이 공통 구간을 처음부터 다시 반복하면, 같은 앞단계가 테스트마다 중복되어 실행이 느려지고, 그 앞부분이 바뀔 때마다 뒤에 의존하는 테스트가 전부 같이 깨집니다.</p><p>게다가 CI에서 여러 워커로 테스트를 병렬 실행하는 경우, 테스트끼리 상태를 공유하면 실행 순서에 묶여 나눌 수 없습니다. <a href="https://playwright.dev/docs/best-practices#make-tests-as-isolated-as-possible">Playwright 공식 문서</a>가 각 테스트를 서로 독립으로 두라고 권장하는 이유입니다. 독립이어야 여러 워커로 병렬 실행할 수 있고, 하나가 깨져도 다른 테스트로 번지지 않아 원인을 바로 짚을 수 있습니다.</p><p>그래서 저희는 공통 앞단계를 매번 반복하는 대신, 각 테스트가 검증할 지점에서 곧장 출발하도록 시작점 상태를 UI 대신 테스트용 API로 미리 세팅하도록 구성했습니다.</p><pre>test.beforeEach(async ({ request }) =&gt; {<br>  // 약관 동의, 휴대폰 인증을 건너뛰고 상품 목록부터 시작<br>  await skipToProductsPage(request);<br>});</pre><p>인증도 마찬가지입니다. 테스트마다 로그인 페이지에서 아이디와 비밀번호를 입력하는 대신, 한 번 로그인한 세션 상태를 Playwright의 <a href="https://playwright.dev/docs/auth">storageState</a>로 저장해 두고 픽스처로 분리해 재사용합니다.</p><pre>import { test as base } from &#39;@playwright/test&#39;;<br><br>const test = base.extend({ storageState: getAuthState(&#39;신용_개인&#39;) });</pre><h3>무엇을 모킹할 것인가</h3><p>앞에서 E2E 테스트는 모킹하지 않은 실제 백엔드까지 통째로 검증한다고 하였습니다. 하지만 네이티브 앱 연동이나 외부 인증처럼 테스트 환경에서 실행 자체가 불가능한 것도 있고, 외부 API 호출처럼 통제할 수 없는 것도 있습니다.</p><p>저희 대출 서비스만 해도 네이버 인증서, 홈택스 전자증명서 같은 외부 의존성이 많습니다. 이런 걸 테스트에서 그대로 호출하면 느려지고, 외부 서비스가 조금만 바뀌어도 우리 코드는 멀쩡한데 테스트가 같이 깨집니다. Playwright 공식 문서도 <a href="https://playwright.dev/docs/best-practices#avoid-testing-third-party-dependencies">통제할 수 있는 것만 테스트하라</a>고 권합니다.</p><p>반대로 백엔드 응답까지 다 모킹하면 실제 시스템을 검증한다는 E2E의 의미가 옅어집니다. 그건 Vitest(혹은 Jest)로 짜는 통합 테스트의 몫이라, 모킹은 통제할 수 없는 것까지만 한정하는 게 좋습니다.</p><p>모킹의 방식은 호출하는 위치에 따라 방법이 갈립니다. 브라우저에서 직접 호출하는 건 Playwright의 <a href="https://playwright.dev/docs/api/class-page#page-route">page.route</a>로 가로챕니다. 서버에서 호출하는 건, 환경변수로 분기하여 값을 고정하거나, 테스트마다 다른 응답이 필요하면 요청 헤더로 분기하도록 할 수 있습니다. 실제 운영 환경에서는 노출되지 않도록 테스트 환경에서만 동작하는 편이 안전합니다.</p><pre>// 브라우저<br>await page.route(&#39;**/cert/**&#39;, (route) =&gt;<br>  route.fulfill({ json: MOCK_CERT })<br>)<br><br>// 서버 - E2E에서만, 고정 응답<br>if (process.env.E2E) return MOCK_CERT<br><br>// 서버 - E2E에서만, 헤더로 시나리오 선택<br>if (process.env.E2E) return MOCK[req.headers[&#39;x-e2e-cert&#39;]] // &#39;success&#39; | &#39;empty&#39; ...</pre><h3>실패한 테스트를 스스로 고치게 하자</h3><p>간헐적 실패까지 잡아 아무리 단단히 짜 두어도, 기능이 바뀌면 결국 테스트는 깨집니다. (그게 바로 테스트가 할 일이니까요.) 하지만 깨질 때마다 사람이 trace를 살펴보고 고쳐야 한다면, 그 일이 결국 또 하나의 병목이 됩니다. 이런 작업도 에이전트에게 위임할 수 있을까요?</p><p>PR이 열리면, CI에서 E2E 테스트가 자동으로 실행됩니다. 실패하면 PR에 실패 코멘트가 달리고, GitHub Actions에 trace 아티팩트가 저장됩니다. 이 trace에는 테스트가 도는 동안 어떤 동작이 일어났는지, 각 단계에서 화면이 어땠는지, 네트워크 요청과 콘솔 로그, 에러 스택까지 통째로 들어 있습니다. 앞 도입하기 부분에서 trace viewer로 살펴봤던 그 정보입니다.</p><figure><img alt="CI 실패 시 GitHub Actions 실행 결과와 PR 결과 코멘트를 좌우로 나란히 보여주는 스크린샷" src="https://cdn-images-1.medium.com/max/1024/1*DhIXNligFnIEt-EeM-KOlw.png" /><figcaption>왼쪽: GitHub Actions에 저장되는 trace 아티팩트, 오른쪽: PR에 달리는 테스트 결과 코멘트</figcaption></figure><p>사람이 직접 아티팩트를 받아 trace를 살펴 디버깅하는 귀찮은 일을 에이전트에게 맡길 수도 있습니다. 저희 팀에서는 이 아티팩트를 내려받아 원인 분석과 처리를 위한 e2e-debug 스킬을 만들어 두었습니다. (이 분석을 CI에서 바로 돌리면 좋겠지만, 프론티어 모델을 보안 정책상 CI에서 직접 호출할 수 없어 로컬에서 실행합니다.)</p><p>Playwright는 MCP도 제공하지만, MCP는 도구 스키마를 매번 컨텍스트에 실어 토큰을 많이 씁니다. 그래서 Playwright 팀은 더 토큰 효율적인 CLI 도구(<a href="https://playwright.dev/agent-cli/introduction">playwright-cli</a>)와, 그 CLI를 위한 <a href="https://playwright.dev/agent-cli/skills">스킬</a>을 최근에 공개했습니다. 에이전트는 e2e-debug로 내려받은 trace를 이 CLI와 playwright-trace 스킬로 열어, 개발자가 브라우저의 개발자 도구로 콘솔과 네트워크 탭을 들여다보듯 짚어가며 디버깅할 수 있습니다.</p><p>앞서 소개한 공식 Healer 에이전트가 그 역할이지만, 모든 수정에 Healer가 필요하진 않습니다. 간단한 실패는 스킬만으로 바로 고치는 게 빠르고, 수정이 복잡할 때는 Healer 같은 서브 에이전트로 분리해 맡깁니다. 서브 에이전트는 컨텍스트가 공유되지 않아 느린 만큼, 작업 크기에 맞춰 고르면 됩니다.</p><h3>자가개선 루프 닫기 (가자! <em>딸-깍</em>의 세계로!)</h3><p>여기까지 에이전트가 테스트를 계획하고, 작성하고, 실행하고, 깨지면 스스로 고치는 과정을 살펴보았습니다. 이렇게 검증 수단을 갖추고 피드백으로 스스로 고쳐 나가는 구조가 <strong>‘자가개선 루프’</strong>, 그 루프를 잘 구축하는 일이 요즘 부쩍 화두인 <a href="https://addyosmani.com/blog/loop-engineering/">루프 엔지니어링(loop engineering)</a>입니다. <a href="https://youtu.be/RkQQ7WEor7w?t=702">“이제 프롬프트가 아니라 루프를 짠다”</a>는 말이 나올 만큼, 결국 이 루프를 만들 수 있느냐가 에이전트에게 어디까지 일을 맡길 수 있는지를 가르는 기준이 되고 있습니다.</p><p>Birgitta Böckeler는 이러한 루프를 떠받치는 환경, 즉 하네스에 <a href="https://martinfowler.com/articles/harness-engineering.html">두 가지 장치가 필요하다고 말합니다</a>. 하나는 AI가 행동하기 전에 방향을 잡아주는 가이드(AGENTS.md, 스킬 등), 다른 하나는 행동한 뒤에 틀린 곳을 짚어 <a href="https://martinfowler.com/articles/sensors-for-coding-agents.html">스스로 교정하게 돕는</a> 센서(린터, 타입 체커 등)입니다. 가이드가 잘 되어 있어도 센서가 없다면 빠르게 검증하기 어렵고, 거꾸로 센서만 있으면 에이전트는 같은 실수를 매번 반복합니다. 이 둘이 맞물려야 비로소 루프가 닫힙니다.</p><figure><img alt="사람이 가이드(행동 전)와 센서(행동 후)를 통해 코딩 에이전트를 조향하는 구조도" src="https://cdn-images-1.medium.com/max/1024/1*nzVcQEAd1HD7C35G69LGuw.png" /><figcaption><em>코딩 에이전트를 감싸는 가이드(AGENTS.md, 스킬 등)와 센서(린터, 타입 체커 등)</em></figcaption></figure><p>그럼 지금까지 저희가 살펴본 E2E 테스트 코드는 가이드일까요, 센서일까요?</p><pre>test(&#39;주담대 정보 입력 페이지에서 뒤로가기 시 확인 모달이 뜬다&#39;, async ({ page }) =&gt; {<br>  await page.goto(&#39;/mortgage/apply&#39;)<br>  await page.getByRole(&#39;textbox&#39;, { name: &#39;대출 희망 금액&#39; }).fill(&#39;30000&#39;)<br>  await page.goBack()<br>  await expect(page.getByText(&#39;입력을 그만할까요?&#39;)).toBeVisible()<br>})</pre><p><strong>정답은 둘 다입니다.</strong> 실행하면 통과와 실패로 피드백을 주는 센서가 되고, 읽으면 이 기능이 어떻게 동작해야 하는지 적힌 명세, 즉 가이드가 됩니다. Böckeler는 <a href="https://martinfowler.com/articles/sensors-for-coding-agents.html">“테스트야말로 궁극의 명세”</a>라고 하였습니다. 테스트 한 벌만 짜 두면 가이드와 센서가 동시에 생기는 셈입니다.</p><pre>test(&#39;주담대 정보 입력 페이지에서 뒤로가기 시 확인 모달이 뜬다&#39;, async ({ page }) =&gt; {<br>  // 1. 주담대 정보 입력 페이지에서,<br>  await page.goto(&#39;/mortgage/apply&#39;)<br>  // 2. 대출 희망 금액을 입력하다가,<br>  await page.getByRole(&#39;textbox&#39;, { name: &#39;대출 희망 금액&#39; }).fill(&#39;30000&#39;)<br>  // 3. 브라우저 뒤로가기를 누르면,<br>  await page.goBack()<br>  // 4. 바로 나가지 않고 &#39;입력을 그만할까요?&#39;를 묻는다.<br>  await expect(page.getByText(&#39;입력을 그만할까요?&#39;)).toBeVisible()<br>})</pre><p>Anthropic은 <a href="https://www.anthropic.com/research/building-effective-agents">Building Effective Agents</a> 글에서 Evaluator-Optimizer라는 패턴으로 비슷한 개념을 설명합니다. 답을 만드는 LLM과 그 답을 채점하는 LLM을 따로 두고, 피드백을</p><p>받아 반복하도록 하는 것이 이 패턴의 핵심입니다. 그런데 채점하는 쪽까지 LLM이면 비싸고, 비결정론적이고, 무엇보다 느립니다. 저희는 그 채점하는 자리를 결정론적이고 LLM보다 빠르고 저렴한 Playwright로 대체한 것입니다. 앞에서 Boris Cherny가 “모델에게 자기 작업을 검증할 수단을 줘라”라고 했던, 그 검증 수단이 바로 Playwright인 셈입니다.</p><figure><img alt="Generator가 만든 답을 결정론적 Playwright가 검증해, 통과하면 내보내고 실패하면 되돌리는 루프 도식" src="https://cdn-images-1.medium.com/max/1024/1*5ysQAzgYl5Cxd9LtBic7Qw.png" /><figcaption>Evaluator-Optimizer 패턴의 채점자 자리에 결정론적 Playwright를 넣은 구조</figcaption></figure><h3>사람의 역할: 설계하고 조향하기</h3><p>지금까지의 내용을 간략히 정리하면 이렇습니다.</p><ul><li><strong>검증이 병목입니다. </strong>AI가 코드를 쏟아낼수록, 사람이 검증을 따라가지 못합니다.</li><li><strong>E2E 테스트가 그 검증 수단입니다.</strong> 실행하면 동작을 검증하는 결정론적 센서이자, 읽으면 스펙을 설명하는 가이드입니다.</li><li><strong>가장 중요한 유저 플로우부터, 테스트를 ‘생성’합니다.</strong> 직접 작성하지 않고, planner와 generator에게 계획과 작성을 맡깁니다.</li><li><strong>실패하면 스스로 고치는 자가개선 루프를 만듭니다. </strong>독립적으로 짜고, 무엇을 모킹할지 정해 흔들림을 줄이고, 실패하면 에이전트가 진단해 고칩니다.</li></ul><p>여기까지 살펴보면, 정작 사람이 설 자리는 어디인가 싶어집니다. 에이전트가 계획부터 작성, 수정까지 다 해낸다면 사람은 무엇을 할까요? 더 이상 할 일이 없을까요?</p><blockquote>사고는 위임할 수 있어도, 이해는 위임할 수 없습니다.</blockquote><blockquote>— Andrej Karpathy (<a href="https://youtu.be/96jN2OCOfLs?t=1686">From Vibe Coding to Agentic Engineering</a>)</blockquote><p>에이전트에게 그 작업을 이해하는 일까지 넘길 수는 없습니다. 테스트가 잡아 주는 건 우리가 예상한 문제뿐입니다. 필요도 없는 기능을 과하게 만들거나, 테스트를 슬쩍 고쳐 통과시키는 일(reward hacking)은 테스트만으로는 가려낼 수 없습니다. CI에서 아무 문제가 없어도, 이 변경이 프로덕션에서 사용자에게 어떤 영향을 줄지 에이전트는 맥락을 모릅니다.</p><p>테스트 인프라를 구축하면서, 어떤 MCP나 스킬을 쥐어줄지, 무엇을 테스트하고 무엇을 모킹할지, 도메인 지식을 어떻게 인코딩해 둘지 같은 결정에 따라 에이전트의 행동이 크게 달라진다는 걸 보았습니다. 무엇이 이 팀에서 ‘좋은’ 코드인지, 어떤 기술 부채는 사업적 이유로 감수되는지, “우리는 원래 이렇게 안 한다”는 직관처럼, 코드에 드러나지 않는 맥락은 사람이 직접 심어주어야 했습니다.</p><p>거창한 인프라부터 갖출 필요는 없습니다. 제품에서 가장 중요한 유저 플로우부터 테스트를 추가하면, 그 테스트가 검증 수단이자 가이드가 되어 루프는 돌기 시작합니다.</p><p>이렇게 사람 없이도 잘 돌아가는 루프를 위해선, 에이전트가 이러한 결정을 잘 할 수 있도록 하네스를 구성하고 조향(steering)하는 사람의 역할이 필요합니다. <strong>결국 <em>딸-깍</em>으로 돌아가는 루프의 품질은, 그 아래에 우리가 무엇을 깔아 두었는지가 결정하는 것입니다.</strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=43b437b842fa" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/playwright-e2e-%ED%85%8C%EC%8A%A4%ED%8A%B8%EB%A1%9C-%EC%9E%90%EA%B0%80%EA%B0%9C%EC%84%A0-%EB%A3%A8%ED%94%84-%EA%B5%AC%EC%B6%95%ED%95%98%EA%B8%B0-43b437b842fa">Playwright E2E 테스트로 자가개선 루프 구축하기</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Composite PK에서 시작된 Spring Boot 4 / Spring Batch 6 업그레이드 기록]]></title>
            <link>https://medium.com/naverfinancial/composite-pk%EC%97%90%EC%84%9C-%EC%8B%9C%EC%9E%91%EB%90%9C-spring-boot-4-spring-batch-6-%EC%97%85%EA%B7%B8%EB%A0%88%EC%9D%B4%EB%93%9C-%EA%B8%B0%EB%A1%9D-6bfc2e2cb65b?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/6bfc2e2cb65b</guid>
            <category><![CDATA[spring-batch]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[spring-boot]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[backend]]></category>
            <dc:creator><![CDATA[오규석]]></dc:creator>
            <pubDate>Mon, 11 May 2026 04:31:56 GMT</pubDate>
            <atom:updated>2026-05-11T04:31:54.573Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><em>Spring Data JDBC Composite PK를 쓰고 싶었을 뿐인데, Batch·Kotlin·Jackson·Gradle까지 함께 정리하게 된 이야기</em></blockquote><p>안녕하세요. 네이버페이 카드 BE 팀 오규석 입니다. 네이버페이에서 카드결제 매입/정산 개발을 담당하고 있습니다.</p><p>이 글은 카드 매입/정산 배치 모듈을 <strong>Spring Boot 3.5.0 → 4.0.1</strong>로 업그레이드하면서 만났던 시행착오와 진행과정을 정리한 기록입니다.</p><blockquote><em>📝 </em><strong><em>용어 한 줄 정리</em></strong></blockquote><blockquote><em>이 글에서는 같은 대상을 두 가지로 부릅니다. </em><strong><em>Composite PK</em></strong><em>는 DB 관점에서 PK가 여러 컬럼으로 구성된 키를 가리키고, </em><strong><em>Composite ID</em></strong><em>는 이 PK를 Spring Data JDBC에서 표현한 ID 클래스 매핑을 가리킵니다. 즉 </em>“DB의 Composite PK를 Spring Data JDBC의 Composite ID로 매핑하는 작업”<em> 이라고 보시면 됩니다.</em></blockquote><h3>먼저 요약하면</h3><ul><li>시작은 Spring Data JDBC의 Composite ID 적용이었습니다.</li><li>실제 작업은 Spring Boot 4 / Spring Framework 7 / Spring Batch 6 / Jackson 3 전환으로 확장되었습니다.</li><li>가장 큰 변경은 <strong>Batch 메타데이터 저장 방식, Job 실행 API, JobParameters 구조, listener·item 패키지 이동</strong>이었습니다.</li><li>운영 반영 전에는 <strong>Spring Batch v5에서 실패한 JobExecution 정리, Batch 메타 스키마 마이그레이션, DB 접근 정책 확인</strong>이 필요했습니다.</li><li>메이저 업그레이드는 “컴파일 통과”보다 “운영에서 기존과 동일하게 동작하는지”를 확인하는 작업에 가까웠습니다.</li></ul><h3>이 글의 전제</h3><p>이 글은 실제 업그레이드 작업 당시 적용한 <strong>Spring Boot 4.0.1 버전 기준의 기록</strong>입니다.</p><p>이 글을 읽으시는 시점에는 더 최신 패치 버전이 있을 수 있고, Spring Boot 4 / Spring Batch 6은 패치 버전에 따라 세부적인 내용이 이 글과 차이가 있을 수 있습니다.</p><p>이 글에서 나오는 코드는 실제 프로젝트 코드가 아닌 상황을 단순화한 예제입니다.</p><p>또한 이 글은 일반적인 Spring WAS 서버가 아니라, Spring Batch Application 모듈 업그레이드이니 일반적인 Spring 서버 업그레이드시에는 추가 사항이 필요할 수 있습니다.</p><p>이 글은 다음 환경을 기준으로 작성했습니다. (화살표(→) 앞은 업그레이드 전, 뒤는 업그레이드 후 버전입니다)</p><ul><li>Spring Boot 3.5.0 → 4.0.1 (Spring Framework 6.2.7 → 7.0.2)</li><li>Spring Batch 5.2.2 → 6.0.1</li><li>Spring Data JDBC 3.5.0 → 4.0.1</li><li>Kotlin 2.1 → 2.3</li><li>Java 21</li><li>ojdbc8 → ojdbc11</li><li>kotest 5.9.1 → 6.0.7</li><li>spring-boot-starter-aop → spring-boot-starter-aspectj</li><li>Oracle DB에 JDBC 기반 Spring Batch 메타데이터 저장</li></ul><blockquote><em>📖 </em><strong><em>이 글을 읽는 법</em></strong></blockquote><blockquote><em>글이 다루는 범위가 꽤 넓습니다. 관심사에 따라 다음 순서로 골라 읽으셔도 됩니다.</em></blockquote><blockquote><strong>- Spring Data JDBC Composite ID</strong>가 뭔지 궁금하다면 → 1장</blockquote><blockquote><strong>- Spring Batch 6 마이그레이션</strong>이 주 목적이라면 → 3장</blockquote><blockquote><strong>- 운영 반영 체크리스트</strong>가 필요하다면 → 5장과 마지막 체크리스트</blockquote><blockquote><strong><em>참고한 공식 문서</em></strong></blockquote><blockquote>- Spring Boot Upgrading Guide — <a href="https://docs.spring.io/spring-boot/upgrading.html#upgrading.from-3x">https://docs.spring.io/spring-boot/upgrading.html#upgrading.from-3x</a></blockquote><blockquote>- Spring Boot 4.0 Migration Guide — <a href="https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide">https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide</a></blockquote><blockquote>- Spring Boot Release Notes — <a href="https://github.com/spring-projects/spring-boot/wiki#release-notes">https://github.com/spring-projects/spring-boot/wiki#release-notes</a></blockquote><blockquote>- Spring Batch 6.0 Migration Guide — <a href="https://github.com/spring-projects/spring-batch/wiki/Spring-Batch-6.0-Migration-Guide">https://github.com/spring-projects/spring-batch/wiki/Spring-Batch-6.0-Migration-Guide</a></blockquote><blockquote>- Kotlin release process — <a href="https://kotlinlang.org/docs/releases.html">https://kotlinlang.org/docs/releases.html</a></blockquote><blockquote>- Features and Changes in Kotest 6.0 — <a href="https://kotest.io/docs/release6">https://kotest.io/docs/release6</a></blockquote><h3>0. 들어가기 앞서</h3><p>시작한 계기는 단순히 도메인 엔티티 모델 개선이었습니다.</p><p>(더 정확히는 <a href="https://spring.io/blog/2025/07/22/spring-data-jdbc-composite-id">Spring Data JDBC에서 Composite ID 지원이 추가</a>된 것을 보고, 이를 적용해보고 싶었습니다.)</p><p>그런데 이를 적용하려다 보니… 아래와 같이 작업들이 불어나게 되었습니다.</p><ul><li>Composite PK 쓰면 편할것 같아. Spring Data JDBC를 3.x -&gt; 4.x 이상으로 업그레이드 하자!</li><li>그런데, Spring Boot Starter Data JDBC 4.x 을 쓰려면 Spring Boot 4.x 이상이 필요하네? 이왕이면 당시 최신 버전 4.0.1로 업그레이드 하자!</li><li>Spring Boot 4.x 로 업그레이드 하려면, Spring Framework도 6.x -&gt; 7.x 버전으로 업그레이드가 되네?</li><li>Spring Framework 7.x 로 업그레이드 하려면, Spring Batch도 6.x 이상으로 업그레이드 해야겠네?</li><li>근데 보니까, Spring Boot 4.x 부터는 Kotlin 2.2 이상이 필요하네? 이왕이면 이번에 새로 나온 Kotlin 2.3으로 업그레이드 하자!</li><li>아니 왜 빌드가 안되지? 아, Gradle 버전이 Spring Boot 4.x 최소 요구사항보다 낮네? 이왕이면 Gradle도 최신 버전으로 업그레이드 하자!</li><li>기존 코드에서 사용중이던 Jackson 2.x 라이브러리가 Spring Boot 4.x 에서 사용하는 Jackson 3.x 버전과 달라서 코드가 깨지네? 자체 종속성 제거하고 Spring하고 버전 맞춰야겠다.</li><li>왜 테스트코드가 안돌아가지? Spring 하고 Kotlin 업그레이드 후 기존 Kotest 5.x + kotest-extensions-spring 조합에서 호환성 문제가 드러나네? Kotest도 6.x로 업그레이드 하자!</li><li>ojdbc 드라이버도 미지원 버전이네? ojdbc8 -&gt; ojdbc11로 업그레이드 하자!</li><li>배치가 안도네? BATCH_JOB_SEQ 시퀀스가 BATCH_JOB_INSTANCE_SEQ로 이름이 바뀌었네? 일단 변경하고 기존 운영배치 호환성 위해 synonym 추가하자.</li><li>등등…</li></ul><p>결국 어쩌다보니 배치 모듈 프로젝트 기술 스택 전반 버전 업그레이드 작업이 되어버렸습니다…</p><p>(그래도 기술 부채를 조금이나마(?) 해결했다고 행복회로 돌려봅니다)</p><h3>1. 왜 시작했나 — Composite PK가 출발점이었습니다</h3><p>발단은 도메인 모델 한 곳이었습니다. 정산 도메인의 한 매핑 테이블에서 PK가 <strong>세 컬럼으로 구성된 복합키</strong>라는 점이었습니다. 그동안 Spring Data JDBC는 Composite PK를 정식으로 지원하지 않아서, 별도 식별자 컬럼을 두거나 커스텀 매핑을 끼워넣는 식으로 우회해 왔습니다.</p><p>(Spring Data JPA는 진작부터 Composite PK 지원해왔는데.. 말이죠..)</p><p>그런데 <strong>Spring Data JDBC 4.0</strong>부터 Composite ID 매핑이 정식 지원에 들어왔습니다!!</p><p>그리고 Spring Data JDBC 4.x 라인은 <strong>Spring Boot 4.0과 묶여 릴리스</strong>됩니다. (이때까지는 작업이 이렇게 커질지 알지 못했습니다..)</p><p>Composite ID 하나만 보면 Spring Data JDBC의 작은 변화처럼 보이지만, 저희 프로젝트에서는 이 기능을 쓰려면 결과적으로 Spring Boot 4 라인으로 올라가야 했습니다. 그래서 처음에는 도메인 모델 개선이었던 일이 자연스럽게 배치 모듈 기술스택 업그레이드로 확장되었습니다.</p><p>저희가 Composite ID를 통해 만들고 싶었던 엔티티는 다음과 같은 모양이었습니다 (테이블·컬럼명은 외부 공개를 위해 일반화했고, ID 클래스는 <strong>독자가 그대로 복사해 쓰기 좋도록 top-level로 분리</strong>했습니다).</p><pre>import org.springframework.data.annotation.Id<br>import org.springframework.data.annotation.Transient<br>import org.springframework.data.domain.Persistable<br>import org.springframework.data.relational.core.mapping.Column<br>import org.springframework.data.relational.core.mapping.Table<br><br>/** 정산 매핑 ID (Composite PK) */<br>data class SettlementMappingId(<br>    @Column(&quot;SERVICE_ID&quot;) val serviceId: String,<br>    @Column(&quot;MERCHANT_ID&quot;) val merchantId: String,<br>    @Column(&quot;TYPE_CODE&quot;)   val typeCode: String,<br>)<br>@Table(&quot;SETTLEMENT_MAPPING&quot;)<br>data class SettlementMapping(<br>    @Id<br>    val mappingId: SettlementMappingId,<br>    @Column(&quot;AGGREGATION_CYCLE&quot;)<br>    val aggregationCycle: String,<br>    @Column(&quot;REPRESENTATIVE_YN&quot;)<br>    val representativeYn: Yn,<br>    // ... 일반 컬럼들 ...<br>) : Persistable&lt;SettlementMappingId&gt; {<br>    /**<br>     * Composite ID는 보통 저장 시점에 이미 모든 ID 컬럼 값이 채워져 있습니다.<br>     * 이 경우 Spring Data JDBC의 기본 신규 판단 전략만으로는<br>     * 신규 INSERT가 필요한 엔티티를 update로 오인할 수 있습니다.<br>     *<br>     * 그래서 이 예제에서는 Persistable을 구현하고,<br>     * &quot;신규 여부&quot;는 애플리케이션이 명시적으로 알려주도록 설계했습니다.<br>     *<br>     *  - 신규 저장 시: 호출 측에서 markNew() 후 save<br>     *  - 기존 엔티티 갱신 시: 기본값 false 그대로 두고 save → update 로 동작<br>     */<br>    @Transient<br>    private var isNewRow = false<br><br>    fun markNew(): SettlementMapping = apply { isNewRow = true }<br><br>    override fun getId() = mappingId<br>    override fun isNew() = isNewRow<br>}</pre><p>@Id 필드의 타입이 String이나 Long이 아니라 SettlementMappingId라는 데이터 클래스이고, 그 안의 각 필드가 그대로 PK 컬럼이 됩니다. 우회 코드 없이 도메인이 그대로 표현되니, 도메인 표현력이 한층 좋아지는 변화였습니다.</p><h4>@Id 단독 vs @Id @Embedded.Nullable</h4><p>단순한 Composite ID 타입은 @Id만으로도 aggregate root 테이블의 ID 컬럼들로 매핑됩니다.</p><p>다만 <strong>컬럼 prefix가 필요하거나, embedded 객체의 null 처리 정책(</strong>onEmpty<strong> 등)을 명시하고 싶다면</strong> @Embedded를 함께 사용할 수 있습니다.</p><p>공식 reference 문서 예제에서도 @Id @Embedded.Nullable 조합을 함께 소개하지만, 이는 <em>&quot;항상 이 형태가 정석이니 이렇게 사용하세요&quot;</em> 라기보다 <em>&quot;상황에 따라 선택하세요&quot;</em> 에 가깝습니다.</p><p>저희 예제는 prefix가 필요 없고 ID 값이 항상 생성자를 통해 채워지는 모델이라 @Id 단독 형태로 단순화했습니다.</p><h4>⚠️ 안티패턴 — Composite PK인데 한 컬럼만 @Id로 매핑하면 어떤 일이 일어날까 (기존 버전에서 우회하기 위한 시도 중 하나)</h4><p>Composite ID 지원이 들어오기 전에 흔히 봤던 우회 방법 중 하나는 <strong>PK 컬럼 중 하나에만 </strong>@Id<strong>를 붙이고 나머지는 일반 컬럼처럼 두는</strong> 것입니다. 컴파일은 되고 단순 조회도 동작하는 것처럼 보이지만, save(), saveAll(), deleteById() 등이 호출되는 순간 <strong>해당 row와 함께 @Id 컬럼값이 같은 다른 row를 덮어쓸 수 있는</strong> 데이터 사고로 이어집니다.</p><pre>// ❌ 안티패턴: DB의 PK는 (SERVICE_ID, MERCHANT_ID, TYPE_CODE) 인데<br>//             @Id 는 한 컬럼에만 붙어 있는 형태<br>@Table(&quot;SETTLEMENT_MAPPING&quot;)<br>data class SettlementMappingBad(<br>    @Id<br>    @Column(&quot;SERVICE_ID&quot;)<br>    val serviceId: String,            // ← PK 일부만 @Id 로 표현<br>    @Column(&quot;MERCHANT_ID&quot;)<br>    val merchantId: String,           // PK 나머지인데 일반 컬럼처럼 취급됨<br>    @Column(&quot;TYPE_CODE&quot;)<br>    val typeCode: String,             // PK 나머지인데 일반 컬럼처럼 취급됨<br>    @Column(&quot;AGGREGATION_CYCLE&quot;)<br>    val aggregationCycle: String,<br>)</pre><p>다음 시나리오를 따라가 보면 위험이 분명히 드러납니다.</p><pre>// 전제: DB 에는 이미 (serviceId=&quot;S1&quot;, merchantId=&quot;M1&quot;, typeCode=&quot;T1&quot;) row 가 있음<br><br>// 새로 (S1, M2, T2) 라는 별개 비즈니스 row 를 만들고 싶다고 가정<br>val newRow = SettlementMappingBad(<br>    serviceId = &quot;S1&quot;,   // ← 같은 serviceId, 다른 (merchantId, typeCode)<br>    merchantId = &quot;M2&quot;,<br>    typeCode = &quot;T2&quot;,<br>    aggregationCycle = &quot;DAILY&quot;,<br>)<br>repository.save(newRow)</pre><p>여기서 일어나는 일:</p><ol><li>Spring Data JDBC는 기본적으로 @Id<strong> 값이 채워져 있으면 </strong>update 로, <strong>비어 있으면 </strong>insert 로 판단합니다. serviceId는 비어 있지 않으므로 update 경로로 들어갑니다.</li><li>update 쿼리는 @Id<strong>만 WHERE 조건</strong>에 들어갑니다. 즉 WHERE SERVICE_ID = &#39;S1&#39; 조건이 그대로 나가고, <strong>DB 입장에서는 (S1, M1, T1) row가 그대로 매칭</strong>됩니다.</li><li>결과적으로 <strong>이미 존재하던 (S1, M1, T1) row의 </strong>MERCHANT_ID<strong>/</strong>TYPE_CODE<strong>/</strong>AGGREGATION_CYCLE<strong> 값이 (S1, M2, T2, &quot;DAILY&quot;)로 덮어쓰여집니다.</strong> 사용자는 새 row를 추가했다고 생각했지만, 다른 비즈니스 row 하나가 조용히 사라진 셈입니다.</li></ol><p>같은 함정은 <strong>조회</strong> 에서도 따라옵니다.</p><ul><li>findFirstById(&quot;S1&quot;)은 WHERE SERVICE_ID = &#39;S1&#39; 한 조건으로만 쿼리하므로, 같은 serviceId를 가진 다른 row가 함께 매칭될 수 있고, 어떤 row가 반환될지 보장되지 않습니다.</li></ul><p>이 위험을 피하는 방법으로 저희가 시도해 보았던 것은 아래 세 가지입니다.</p><ol><li><strong>앞서 살펴본 Composite ID로 PK를 그대로 표현</strong>하기 — @Id val mappingId: SettlementMappingId처럼 ID 클래스가 PK 전체를 담도록 두는 방식입니다. 저희가 선택한 방향입니다. <strong>다만 이 방법은 Spring Data JDBC 4.0 이상에서만 사용할 수 있습니다.</strong></li><li>(저희처럼 레거시로 MyBatis 등을 쓰다가 Spring Data JDBC로 전환한 경우가 해당될 것 같습니다) 어쩔 수 없이 한 컬럼만 @Id로 두어야 한다면, 해당 엔티티는 <strong>절대로</strong> deleteById, save, saveAll 등의 메서드를 사용하지 말라고 주석 및 컨벤션으로 정의하는 방식. 다만, 위험은 그대로 존재하며 한명의 개발자도 빠짐없이 해당 컨벤션을 이해하고 숙지해야 합니다.</li><li>(아마 프로젝트 처음 시작할때부터 Spring Data JDBC 를 사용하셨다면 다들 그렇게 하시겠지만) PK 컬럼이 하나인 테이블로 애초에 설계하고, 복합 PK가 필요한 경우는 PK와는 별도의 unique key로 묶기. (당연하지만 PK는 다른 row와 중복되지 않는 신규 채번되는 값이어야 함)</li></ol><blockquote><em>💡 </em><strong><em>요약하자면</em></strong><em>:</em></blockquote><blockquote><em>Composite PK 테이블에서 </em><em>@Id를 한 컬럼에만 붙이는 우회는 </em>실제 테이블과 엔티티 코드 불일치<em> 라는 어긋난 모델을 만듭니다. 데이터가 적을 때는 우연히 동작하다가, </em><strong><em>운영 데이터에서 한 row가 다른 row를 침범하는 사고</em></strong><em> 가 발생할 수 있습니다. Spring Data JDBC 4.0의 Composite ID 지원이 반가운 이유 중 하나가 이러한 안티패턴 우회를 이제 안해도 된다는 점이었습니다.</em></blockquote><h4>Composite ID와 신규 여부 판단</h4><blockquote><em>⚠️ </em><strong><em>Persistable 상속받은 엔티티 클래스 + </em></strong><em>markNew()</em><strong><em>를 선택한 이유</em></strong></blockquote><blockquote><em>Composite ID는 저장 전에 이미 모든 ID 컬럼 값이 외부 생성자를 통해 채워져 있는 경우가 많습니다. 이 상태에서 Spring Data JDBC의 기본 신규 판단 전략만으로는 INSERT가 필요한 엔티티를 update로 오인할 수 있어, 저희는 </em><em>Persistable을 구현해 신규 여부를 애플리케이션에서 명시했습니다. </em><em>isNewRow는 주 생성자 프로퍼티가 아닌 </em><em>@Transient 내부 상태로 두어, </em><em>copy()로 기존 엔티티를 변경해 저장할 때 기본적으로 update 경로를 타도록 설계했습니다.</em></blockquote><blockquote><em>Kotlin </em><em>data class의 </em><em>copy()는 </em><strong><em>주 생성자 프로퍼티만</em></strong><em> 복사하므로, 본문 안의 </em><em>@Transient 변수인 </em><em>isNewRow는 새 인스턴스에 그대로 따라가지 않고 기본값 </em><em>false로 시작합니다. 신규 객체를 만든 뒤 </em><em>copy()로 내부 값을 보정하는 로직이 있다면, </em><strong><em>모든 보정이 끝난 마지막 시점</em></strong><em>에 </em><em>markNew()를 호출하도록 생성 경로를 고정하는 편이 안전합니다.</em></blockquote><p>신규 판단 전략은 Persistable만 있는 것은 아닙니다. 도메인 특성에 따라 @Version 기반 optimistic locking, BeforeConvertCallback에서 신규 여부 결정, JdbcAggregateTemplate.insert() 직접 호출 같은 방식도 선택지가 될 수 있습니다. 저희는 호출부에서 신규 저장 의도를 드러내는 쪽이 운영 코드와 가장 잘 맞아 Persistable을 선택했습니다.</p><p>아래 예시에서 JdbcAggregateTemplate.insert()와 달리 JdbcAggregateTemplate를 별도로 사용하지 않고 repository만으로 insert 가 가능하면서도, 호출 측 코드에서 신규 row insert 라는 의도가 그대로 보여 간결하면서도 이해가 쉬운 코드가 되었습니다. (라고 생각합니다)</p><pre>// 신규 저장: markNew() 로 의도를 명시한 뒤 save<br>repository.save(<br>    SettlementMapping(<br>        mappingId = SettlementMappingId(serviceId, merchantId, typeCode),<br>        aggregationCycle = &quot;DAILY&quot;,<br>        representativeYn = Yn.Y,<br>        // ...<br>    ).markNew()<br>)<br><br>// 기존 엔티티 갱신: 기본값 isNewRow = false 그대로 두고 save → update 로 동작<br>val existing = repository.findById(id).orElseThrow()<br>repository.save(existing.copy(aggregationCycle = &quot;MONTHLY&quot;))</pre><blockquote><em>ℹ️ </em><strong><em>단점도 분명합니다.</em></strong></blockquote><blockquote><em>신규 엔티티 insert 시 </em><em>markNew() 호출을 빠뜨리면 의도와 다르게 update 쿼리가 발행될 수 있습니다. (물론 그 경우 PK가 겹치는 엔티티가 없을것이므로 update 실패로 예외가 발생하긴 합니다.)</em></blockquote><p>이러한 점 때문에 Spring Data JDBC 업그레이드를 시작했고, 곧 알게 됐습니다.</p><p>이것이 단순히 버전 숫자를 올리는 것이 아니라는 것을..</p><p>버전 숫자를 바꾸는 일과, <strong>업그레이드 후 운영에서 기존과 동일하게 동작하게 만드는 일</strong>은 완전히 다른 작업이었습니다.</p><h3>2. 업그레이드 전략 — 변경의 출처를 커밋 단위로 분리</h3><p>본격적인 작업 전에 한 가지 원칙을 잡았습니다. <strong>변경의 출처를 가능한 한 커밋 단위로 분리한다</strong>는 것이었습니다. Gradle/Kotlin/Spring/Batch/Jackson/Kotest를 한 커밋에 다 섞으면, 이후 빌드가 깨졌을 때 출처를 찾는 데 시간이 크게 늘어납니다.</p><p>전체적인 진행 순서는 다음과 같았습니다.</p><ol><li><strong>Spring Boot 3.5.x 최신 패치 버전까지 먼저 올려서, deprecated API를 미리 정리</strong></li><li>Gradle Wrapper 업데이트 (8.10 → 9.2.1)</li><li>Kotlin 업데이트 (2.1.20 → 2.3.0)</li><li>Spring Boot 3.5.x → 4.0.1 전환</li><li>Spring Batch 6, Spring Framework 7, Jackson 3, Kotest 6 등 부수적 변경 정리</li></ol><h4>2–1. Gradle / 베이스라인 점검</h4><p>Spring Boot 4의 Gradle Plugin은 Gradle <strong>8.14 이상 또는 Gradle 9.x</strong>를 지원합니다. 저희 프로젝트는 당시 <strong>Gradle 8.10</strong>을 사용하고 있어 조건을 만족하지 못했습니다. 단순히 8.x 최신 패치로만 올릴 수도 있었지만, <strong>호환성 검증 범위를 한 번에 정리하기 위해 Gradle 9.2.1</strong>까지 함께 올렸습니다.</p><pre>- distributionUrl=...gradle-8.10-bin.zip<br>+ distributionUrl=...gradle-9.2.1-bin.zip</pre><p>베이스라인은 함께 챙겨주는 편이 좋습니다. Spring Boot 4는 <strong>Java 17 이상</strong>, <strong>Kotlin 2.2 이상</strong>을 요구하고, Spring Framework 7 / Jakarta EE 11 라인으로 올라가면서 javax.* 의존성이 남아 있다면 영향이 있을 수 있습니다.</p><h4>2–2. Kotlin과 Spring Boot 4 전환</h4><pre>plugins {<br>    val kotlinVersion = &quot;2.3.0&quot;<br>    val springBootVersion = &quot;4.0.1&quot;<br>    // ...<br>}</pre><p>이 두 줄을 바꾸자 컴파일 에러가 한꺼번에 다량으로 발생했습니다. 패키지 구조 변경, 시그니처 변경, 사라진 API까지 골고루였고, 이후의 작업은 이 에러들을 카테고리별로 묶어 정리한 결과입니다.</p><blockquote><em>💡 </em><em>Gradle / 베이스라인</em><strong><em>과 </em></strong><em>Kotlin / Spring 업그레이드</em><strong><em> 변경 작업을 분리해서 수행한 이유</em></strong></blockquote><blockquote><em>Spring Boot 버전은 일단 한 단계 마이너만 올려놓은 상태에서 Gradle/Kotlin부터 통과시켰습니다. 빌드를 깨뜨린 변경의 출처를 분리하기 위해서(Gradle문제일지? Spring 및 코틀린 버전 업그레이드 문제일지?)였고, 이게 빌드 오류 추적 시간을 가장 크게 줄여 준 결정이었습니다.</em></blockquote><h3>3. 가장 많이 깨진 곳: Spring Batch 6</h3><p>Composite ID 적용 자체는 작은 변경이었지만, 그 변경을 위해 올라간 Spring Boot 4가 <strong>Batch 실행 인프라까지 함께 바꿨습니다</strong>. 그래서 이후부터는 실제로 가장 많은 수정이 필요했던 Spring Batch 6 전환을 중심으로 정리합니다.</p><p>Spring Batch 6은 단순히 import만 바꾸는 업그레이드가 아니었습니다. 실행 API, listener 모델, reader/writer 구성 방식, 메타데이터 테이블 시퀀스까지 함께 바뀌는 메이저 업그레이드였습니다.</p><p>이번 업그레이드에서 Batch 쪽 핵심은 세 가지였습니다.</p><ol><li>별도의 설정 없이 spring-boot-starter-batch 를 사용하는 것 자체만으로는 JDBC 메타데이터 저장이 되지 않습니다.</li><li>JobParameters, JobOperator, Listener, Item 관련 API가 한꺼번에 바뀝니다. (특히 패키지 구조 변경 + 기존 사용법 deprecated 화)</li><li>메타데이터 테이블용 시퀀스와 Spring Batch 5 버전 배치에서 실패된 JobExecution 재시작 가능 여부는 Spring Batch 6 버전 배치 운영 반영 전에 반드시 정리해야 합니다.</li></ol><p>이후 내용은 실제로 깨진 지점을 기준으로, 코드를 고친 순서대로 정리했습니다. 가장 큰 축은 Spring Boot 4(Spring Framework) 업그레이드에 따른 Spring Batch 6 전환이고, Kotlin/Jackson/Kotest/Oracle 관련 변경 작업은 그 작업 도중 (삽질을 통해) 추가 작업이 필요해서 수행한 변경입니다.</p><h4>3–1. 인프라 설정 변경</h4><p><strong>spring-boot-starter-batch의 기본 동작 변경</strong></p><p>Spring Boot 4부터 spring-boot-starter-batch만 추가했을 때, <strong>기존처럼 자동으로 JDBC JobRepository가 구성되지 않습니다</strong>. 대신 별도 데이터 저장소 없이 동작하는 단순화된 모드(흔히 <em>resourceless</em> 라고 부르는 형태) — 즉 Job 실행 정보를 운영 메타 테이블에 영속화하지 않는 형태 — 가 기본이 됩니다.</p><blockquote><em>Spring Boot 4.0 Migration Guide 인용:</em></blockquote><blockquote>“Spring Batch can now operate without a database (i.e. in memory), and the regular <em>spring-boot-starter-batch</em> uses this simplified mode.&quot;<em> </em>&quot;To restore previous behavior, use <em>spring-boot-starter-batch-jdbc</em> instead.&quot;</blockquote><p>여기서 말하는 “in-memory”는 <em>프로세스 메모리에 기존 메타 테이블이 그대로 들어간다</em>는 의미가 아닙니다. 실행 컨텍스트 안에서만 동작하는 가벼운 형태이며, 잡이 끝나거나 프로세스가 내려가면 이력이 남지 않습니다. 따라서 운영에서 <strong>Job 실행 이력, 재시작, 모니터링을 Spring Batch 메타 테이블에 의존</strong>한다면, 다음 셋 중 한 가지를 명시해야 합니다.</p><ol><li>프로젝트 dependency 설정에 spring-boot-starter-batch 대신 spring-boot-starter-batch-jdbc를 사용한다.</li><li>@EnableJdbcJobRepository를 사용한다.</li><li>저희처럼 JdbcDefaultBatchConfiguration<strong>을 직접 상속해 명시적으로 배치 설정을 구성</strong>한다.</li></ol><p>Spring Batch 6에서는 @EnableBatchProcessing과 JDBC 저장소 구성이 분리되었고, JDBC를 쓰려면 위 세 방식 중 하나를 선택하라고 안내합니다.</p><p>이 사실을 모르고 의존성만 그대로 두면, 잡을 실행해도 Spring Batch 메타 테이블에 기록이 남지 않아 혹시 해당 테이블을 재시도·모니터링·이력 추적 같은 운영 작업에 사용할 경우 문제가 발생할 수 있습니다.</p><p><strong>DefaultBatchConfiguration → </strong><strong>JdbcDefaultBatchConfiguration</strong></p><p>ResourcelessJobRepository를 사용하여 배치 메타데이터를 저장/사용하지 않는 DefaultBatchConfiguration와, JDBC 기반으로 배치 메타데이터를 저장하는 JdbcDefaultBatchConfiguration이 분리되었습니다. (MongoDB 사용 시 MongoDefaultBatchConfiguration도 별도로 제공됩니다.) 저희는 Oracle을 쓰며, 메타데이터를 저장하도록 JDBC 쪽을 상속했습니다.</p><pre>@Configuration<br>class BatchConfig(<br>    val batchDataSource: DataSource,<br>) : JdbcDefaultBatchConfiguration() {<br>    override fun getDataSource(): DataSource = batchDataSource<br><br>    // Batch 인프라가 사용할 기본 transactionManager 로 등록합니다.<br>    // 운영 DB와 별도 메타 DB를 두는 등 multi-DataSource 환경이라면,<br>    // 빈 이름을 &#39;batchTransactionManager&#39; 처럼 명시하고<br>    // Step 구성에서 .transactionManager(batchTransactionManager) 로 가리키는 편이 안전합니다.<br>    @Bean(&quot;transactionManager&quot;)<br>    fun batchTransactionManager(): JdbcTransactionManager =<br>        JdbcTransactionManager(batchDataSource)<br>    override fun getExecutionContextSerializer(): ExecutionContextSerializer =<br>        JacksonExecutionContextStringSerializer()<br>}</pre><p><strong>Jackson2 → Jackson3 ExecutionContext Serializer</strong></p><p>Spring Batch 6에서는 JacksonExecutionContextStringSerializer가 Jackson 3.x를 기본으로 사용하도록 업데이트되었습니다. 저희 Batch ExecutionContext serializer 설정에서는, 기존의 ObjectMapper + JavaTimeModule 보일러플레이트를 제거할 수 있었습니다.</p><pre>- override fun getExecutionContextSerializer(): ExecutionContextSerializer {<br>-     val objectMapper = ObjectMapper().registerModule(JavaTimeModule())<br>-     val defaultSerializer = Jackson2ExecutionContextStringSerializer()<br>-     defaultSerializer.setObjectMapper(objectMapper)<br>-     return defaultSerializer<br>- }<br>+ override fun getExecutionContextSerializer(): ExecutionContextSerializer =<br>+     JacksonExecutionContextStringSerializer()</pre><p>LocalDate/LocalDateTime이 포함된 ExecutionContext가 직렬화 가능한 상태로 그대로 동작하는 것을 테스트를 통해 확인했고, 설정 코드도 크게 줄었습니다.</p><p>다만 ExecutionContext에 애플리케이션 커스텀 타입을 직접 넣는 경우에는, 기본 serializer의 역직렬화 허용 범위에 걸릴 수 있으므로 필요하면 별도 JsonMapper 구성을 검토해야 합니다. 저희는 LocalDate/LocalDateTime 중심의 실제 ExecutionContext 데이터로 회귀 테스트를 진행했습니다.</p><p><strong>Job 실행 진입점: </strong><strong>JobOperator로 정리</strong></p><blockquote><em>Spring Batch 6 What’s New 인용:</em></blockquote><blockquote>“The <em>JobOperator</em> now extends the <em>JobLauncher</em> interface, so there is no need to define a separate <em>JobLauncher</em> bean.&quot;</blockquote><p>JobLauncher는 Spring Batch 6.0부터 deprecated 되었고, 6.2 또는 그 이후 버전에서 제거 예정이라 저희도 JobLauncher를 꺼내 호출하던 코드를 JobOperator.start(Job, JobParameters) 형태로 옮겼습니다.</p><pre>- val launcher = ctx.getBean(JobLauncher::class.java)<br>- val exe = launcher.run(job, jobParameters)<br>+ val jobOperator = ctx.getBean&lt;JobOperator&gt;()<br>+ val exe = jobOperator.start(job, jobParameters)</pre><blockquote><em>⚠️ </em><em>JobParametersIncrementer</em><strong><em>와 함께 쓰는 Job은 별도 검증이 필요합니다</em></strong></blockquote><blockquote><em>JobParametersIncrementer가 붙은 Job에서는 </em><em>JobOperator.start(Job, JobParameters)로 전달한 파라미터가 그대로 쓰이지 않습니다. Spring Batch 6 API 문서 기준으로는 incrementer가 다음 </em><em>JobParameters를 계산하며, 호출자가 넘긴 파라미터는 무시됩니다. 따라서 incrementer를 사용하는 Job은 전환 후 별도 테스트가 필요합니다.</em></blockquote><p><strong>PathResource → </strong><strong>FileSystemResource</strong></p><p>파일 기반 ItemReader 등에서 사용하던 PathResource는 Spring Framework 7 부터 Deprecated 예정입니다. 이에 따라 Spring에서 대체 사용을 권장하는 FileSystemResource로 정리했습니다.</p><pre>- import org.springframework.core.io.PathResource<br>+ import org.springframework.core.io.FileSystemResource<br><br>- reader.setResource(PathResource(qualifiedFile))<br>+ reader.setResource(FileSystemResource(qualifiedFile))</pre><h4>3–2. Spring Batch 6 패키지 경로 대변경</h4><blockquote><em>Spring Batch 6 Migration Guide 인용:</em></blockquote><blockquote>“All APIs defined in the spring-batch-infrastructure module were moved from <em>org.springframework.batch.*</em> to <em>org.springframework.batch.infrastructure.*</em>.&quot;</blockquote><p>패키지 경로 이동은 크게 두 갈래였습니다.</p><ol><li>spring-batch-infrastructure 모듈 API는 org.springframework.batch.* → org.springframework.batch.infrastructure.* 아래로 이동</li><li>core 도메인/리스너 계열은 core → core.step, core.listener처럼 더 세분화된 패키지로 이동</li></ol><p>자주 쓰던 클래스들의 이동 경로를 표로 정리합니다.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a8069c428b2ca6800a9903943a035688/href">https://medium.com/media/a8069c428b2ca6800a9903943a035688/href</a></iframe><p>운영 단의 도메인(Job/Step/Listener)은 core에, <strong>재사용 가능한 인프라(Reader/Writer/Item)</strong> 는 infrastructure에 두겠다는 의도로 읽힙니다. 의미는 분명한 분리지만, 마이그레이션하는 데 가장 많은 수정이 필요했습니다.</p><h4>3–3. Chunk 모델 변경</h4><p><strong>배치 StepBuilder 사용 시 </strong><strong>chunk()와 </strong><strong>transactionManager()가 분리됐습니다</strong></p><pre>StepBuilder(&quot;myStep&quot;, jobRepository)<br>-    .chunk&lt;In, Out&gt;(CHUNK_SIZE, transactionManager)<br>+    .chunk&lt;In, Out&gt;(CHUNK_SIZE)<br>+    .transactionManager(transactionManager)<br>     .reader(...)</pre><p>chunk()는 chunk 크기 선언에, transactionManager()는 트랜잭션 경계 선언에 집중하게 되어 의도가 더 분명해졌습니다.</p><p><strong>ChunkListener 변경</strong></p><p>ChunkListener의 기존 메서드(beforeChunk(ChunkContext), afterChunk(ChunkContext), afterChunkError(ChunkContext))는 deprecated로 표기되었고, 위치도 core.listener 패키지로 이동했습니다.</p><p>대신 Spring Batch 6에서는 beforeChunk(chunk) 같이 직접 chunk 자체에 접근할 수 있도록 리스너가 변경되었습니다.</p><pre>object : ChunkListener&lt;MyInput, MyOutput&gt; {<br>    override fun beforeChunk(chunk: Chunk&lt;MyInput&gt;) {<br>        // ...<br>    }<br><br>    override fun afterChunk(chunk: Chunk&lt;MyOutput&gt;) {<br>        // ...<br>    }<br><br>    override fun onChunkError(exception: Exception, chunk: Chunk&lt;MyOutput&gt;) {<br>        // ...<br>    }<br>}</pre><blockquote><em>📌 </em><strong><em>호출 시점 주의 — </em></strong><em>beforeChunk(Chunk&lt;I&gt;)</em><strong><em>는 &quot;ItemReader 등을 통해 읽기 전&quot;이 아닙니다</em></strong></blockquote><blockquote><em>메서드 이름만 보면 “읽기 전”처럼 느껴질 수 있지만, API 문서상 </em><em>beforeChunk(Chunk&lt;I&gt;)는 chunk가 read 된 뒤 process 전에 호출되는 콜백에 가깝습니다. 기존 </em><em>ChunkContext 기반 콜백과 호출 시점에 기대가 있다면 단순히 메서드 이름만 보고 옮기지 말고, 반드시 테스트로 호출 시점을 확인해야 합니다.</em></blockquote><p>이 예제는 저희가 사용한 Spring Batch 6.x 패치 버전을 기준으로 단순화한 코드입니다. onChunkError<strong>의 두 번째 인자 </strong>Chunk<strong> 제네릭 타입을 포함해</strong>, 패치 버전마다 시그니처가 미세하게 다를 수 있으므로 사용 중인 버전의 API 문서와 컴파일 결과를 기준으로 확인해 주세요. 저희는 listener 등록 방식과 콜백 호출 시점을 테스트로 검증했습니다.</p><p>또한 새 ChunkListener는 <strong>concurrent step에서는 호출되지 않는 제약</strong>이 API 문서에 함께 명시되어 있습니다. 병렬 처리나 partitioning 기반 Step에 listener로 부가 로직을 얹고 있다면, 동일한 동작이 그대로 호출되리라 가정하지 말고 별도로 검증하시는 편이 안전합니다.</p><p><strong>AsyncItemProcessor/</strong><strong>AsyncItemWriter — 생성자 기반으로 이동</strong></p><p>Spring Batch 6에서 가장 큰 컨셉 변경 중 하나는 <strong>필수적으로 필요한 파라미터는 파라미터 set 이후 afterPropertiesSet()으로 검증하는 패턴 대신 처음부터 생성자를 통해 필수로 받도록 API가 다듬어졌다</strong>는 점입니다. 그동안 흔하게 쓰던 “기본 생성자 → setter 주입 → afterPropertiesSet() 호출&quot; 패턴이 많이 줄어듭니다.</p><p>(실제로 afterPropertiesSet() 메서드 자체가 제거된 클래스도 있습니다. AsyncItemProcessor가 대표적입니다.)</p><pre>- val asyncItemProcessor = AsyncItemProcessor&lt;In, Out&gt;()<br>- asyncItemProcessor.setDelegate { ... }<br>- asyncItemProcessor.setTaskExecutor(executor)<br>- asyncItemProcessor.afterPropertiesSet()      // ← 잊지 말고!<br><br>+ val asyncItemProcessor = AsyncItemProcessor&lt;In, Out&gt; { ... }<br>+ asyncItemProcessor.setTaskExecutor(executor)<br>+ // 생성자에서 delegate를 받기 때문에, 별도의 afterPropertiesSet() 수동 호출이 필요 없습니다.</pre><pre>  val resultFileReader = salesPurchaseFileService<br>      .getSalesPurchaseSendFileItemReader(qualifiedFile)<br>- resultFileReader.afterPropertiesSet()<br>  resultFileReader.open(ExecutionContext())</pre><p>저희 코드에는 명시적으로 afterPropertiesSet()을 호출하는 부분들도 있었는데, 생성자 기반으로 옮기는 과정에서 자연스럽게 제거되었습니다.</p><h4>3–4. JobParameters — 컬렉션 타입 변경과 직렬화 포맷 변경</h4><blockquote><em>Spring Batch 6 Migration Guide 인용:</em></blockquote><blockquote>“the <em>JobParameters</em> class now holds a <em>Set&lt;JobParameter&gt;</em> instead of a Map from &#39;name&#39; → &#39;nameless job parameter&#39;.&quot;</blockquote><p>Spring Batch 6에서 JobParameters의 내부 컬렉션이 Map&lt;String, JobParameter&lt;*&gt;&gt; → Set&lt;JobParameter&lt;out Any&gt;&gt; 로 바뀌었고, 각 JobParameter가 자기 Parameter Name을 직접 갖게 됐습니다.</p><blockquote><em>📌 </em><strong><em>이 예제의 범위</em></strong></blockquote><blockquote><em>아래 코드는 배치 실행 진입점에서 </em><em>key=value 형태의 String 파라미터만 허용하도록 단순화한 예제입니다. Spring Batch 기본 </em><em>DefaultJobParametersConverter의 전체 포맷(타입 표기, identifying 여부 지정 등)을 대체하는 범용 구현은 아닙니다. 다양한 타입을 받아야 한다면 공식 컨버터를 그대로 쓰거나 그 위에 얇게 정책 로직을 얹는 편이 안전합니다.</em></blockquote><ul><li>기존</li></ul><pre>private fun makeJobParameters(jobArgs: List&lt;String&gt;): JobParameters {<br>    val seenNames = mutableSetOf&lt;String&gt;()<br><br>    val paramMap: Map&lt;String, JobParameter&lt;out Any&gt;&gt; =<br>        jobArgs<br>            .map { arg -&gt;<br>                val index = arg.indexOf(&#39;=&#39;)<br>                require(index &gt; 0) {<br>                    &quot;JobParameter는 &#39;key=value&#39; 형식이어야 합니다. 잘못된 인자: &#39;$arg&#39;&quot;<br>                }<br><br>                val name = arg.substring(0, index)<br>                val value = arg.substring(index + 1)<br><br>                require(name.isNotBlank()) { &quot;JobParameter key는 비어 있을 수 없습니다. 잘못된 인자: &#39;$arg&#39;&quot; }<br>                require(value.isNotBlank()) { &quot;JobParameter value는 비어 있을 수 없습니다. 잘못된 인자: &#39;$arg&#39;&quot; }<br>                require(seenNames.add(name)) { &quot;JobParameter key가 중복됩니다: &#39;$name&#39;&quot; }<br><br>                Pair(name, JobParameter(value, String::class.java)) // parameter 이름을 key값으로 갖는 Map 사용<br>            }<br>            .toMap()<br><br>    return if (paramMap.isEmpty()) JobParameters() else JobParameters(paramMap)<br>}</pre><ul><li>신규</li></ul><pre>private fun makeJobParameters(jobArgs: List&lt;String&gt;): JobParameters {<br>    val seenNames = mutableSetOf&lt;String&gt;()<br><br>    val paramSet: Set&lt;JobParameter&lt;out Any&gt;&gt; =<br>        jobArgs<br>            .map { arg -&gt;<br>                val index = arg.indexOf(&#39;=&#39;)<br>                require(index &gt; 0) {<br>                    &quot;JobParameter는 &#39;key=value&#39; 형식이어야 합니다. 잘못된 인자: &#39;$arg&#39;&quot;<br>                }<br><br>                val name = arg.substring(0, index)<br>                val value = arg.substring(index + 1)<br><br>                require(name.isNotBlank()) { &quot;JobParameter key는 비어 있을 수 없습니다. 잘못된 인자: &#39;$arg&#39;&quot; }<br>                require(value.isNotBlank()) { &quot;JobParameter value는 비어 있을 수 없습니다. 잘못된 인자: &#39;$arg&#39;&quot; }<br>                require(seenNames.add(name)) { &quot;JobParameter key가 중복됩니다: &#39;$name&#39;&quot; }<br><br>                JobParameter(name, value, String::class.java) // JobParameter 생성자에 name 추가<br>            }<br>            .toSet()<br><br>    // Spring Batch 6 API 기준으로 JobParameters(Set) 생성자는 null/empty Set 을 허용하지 않으므로,<br>    // 파라미터가 없는 경우에는 기본 생성자를 사용해 빈 JobParameters 를 만듭니다.<br>    return if (paramSet.isEmpty()) JobParameters() else JobParameters(paramSet)<br>}</pre><blockquote><em>📌 </em><strong><em>identifying parameter 주의</em></strong></blockquote><blockquote><em>JobParameter(name, value, String::class.java)로 만든 파라미터는 기본적으로 </em><strong><em>identifying parameter</em></strong><em>입니다. 즉 같은 Job + 같은 파라미터 조합이면 같은 JobInstance로 묶입니다. 실행 식별에 쓰지 않을 reference 성격의 파라미터라면 (파라미터가 다르더라도 동일한 배치 실행이라고 인식시키고 싶다면) </em><em>identifying 여부를 명시하는 생성자 오버로드를 사용해 의도를 분명히 드러내는 편이 안전합니다.</em></blockquote><blockquote><em>만일, 동일한 파라미터로 여러번 다른 실행을 시도해야 한다면 (JobInstance가 달라져야 한다면) 랜덤함수나 UUID 등을 활용하여 겹치지 않는 value를 갖는 파라미터를 추가해주거나 </em><em>JobParametersIncrementer를 활용해 매 실행마다 고유한 파라미터를 자동으로 추가하는 방법도 있습니다.</em></blockquote><blockquote><em>⚠️ </em><strong><em>운영 포인트 — Spring Batch 5.x에서 실패한 JobExecution은 Spring Batch 6.x 에서 그대로 restart할 수 없습니다</em></strong></blockquote><blockquote><em>Spring Batch 6에서는 </em><em>JobParameters의 직렬화 포맷이 달라지므로, </em><strong><em>Spring Batch 5에서 실행되어 실패한 JobExecution을 Spring Batch 6에서 그대로 restart할 수 없습니다.</em></strong><em> Spring Batch 6 반영 전에 미완료 JobExecution을 성공 또는 abandon 처리하고 넘어가는 것이 안전합니다.</em></blockquote><h4>3–5. 전문(FieldSet) 해석 — readString이 nullable로 바뀌었습니다</h4><p>Spring Batch 6.x에서는 전문 파일 파싱에 쓰이는 FieldSet.readString(name) 호출 결과가 @Nullable로 명시화 되었습니다.</p><p>이에 Java라면 컴파일러가 조용히 넘어갔겠지만, Kotlin에서는 NPE 잠재 코드가 모두 컴파일 오류로 뜨는 현상이 발생했습니다.</p><p>해당 메서드 호출부에 ?: &quot;&quot;나 !!로 도배할 수도 있었지만, <strong>코드 베이스 전체에서 일관된 의미를 담을 수 있도록 확장 함수</strong>를 새로 만들었습니다.</p><pre>fun FieldSet.readStringOrEmpty(name: String): String =<br>    this.readString(name) ?: &quot;&quot;<br><br>fun FieldSet.readStringOrThrow(name: String): String =<br>    this.readString(name) ?: error(&quot;Field &#39;$name&#39; is missing.&quot;)<br><br>fun FieldSet.readNonBlankStringOrNull(name: String): String? {<br>    val value = this.readString(name)<br>    return if (value.isNullOrBlank()) null else value<br>}<br><br>// defaultValue 를 넘기더라도 Kotlin 시그니처상 nullable 로 드러나는 API가 있어,<br>// 호출부 의미를 통일하기 위해 확장 함수 내부에서 한 번 더 방어적으로 처리했습니다.<br>fun FieldSet.readBigDecimalOrZero(name: String): BigDecimal =<br>    this.readBigDecimal(name, BigDecimal.ZERO) ?: BigDecimal.ZERO<br><br>fun FieldSet.readBigDecimalOrThrow(name: String): BigDecimal =<br>    this.readBigDecimal(name) ?: error(&quot;Field &#39;$name&#39; is missing or invalid.&quot;)</pre><p>결과적으로 메서드 호출부는 의도가 한결 또렷해졌습니다.</p><pre>- acquisitionId = if (StringUtils.isNotBlank(fieldSet.readString(ACQUISITION_ID.name))) {<br>-     fieldSet.readString(ACQUISITION_ID.name)<br>- } else null,<br><br>+ acquisitionId = fieldSet.readNonBlankStringOrNull(ACQUISITION_ID.name),</pre><blockquote><em>💡 </em><strong><em>느낀 점</em></strong></blockquote><blockquote><em>라이브러리의 nullable 시그니처 변화를 만나면, 호출부 100군데를 일일이 고치기보다 </em><strong><em>그 라이브러리 위에 우리만의 안전한 처리 로직으로 감싸는 확장 함수</em></strong><em>를 만드는 편이 결과적으로 빠르고 깔끔했습니다.</em></blockquote><h4>3–6. Spring Batch 메타 테이블 시퀀스명 변경</h4><p>코드 변경은 아니지만 함께 다뤄야 했던 운영 작업입니다.</p><blockquote><em>Spring Batch 6 Migration Guide 인용:</em></blockquote><blockquote>“The sequence <em>BATCH_JOB_SEQ</em> was renamed to <em>BATCH_JOB_INSTANCE_SEQ</em>.&quot;</blockquote><p>저희는 <strong>Oracle 환경</strong>이었기 때문에 다음 절차로 정리했습니다.</p><ol><li>개발 환경에서 시퀀스 이름을 새 이름으로 변경하고, <strong>synonym</strong>을 통해 옛 이름과의 호환을 임시 유지</li><li>호환 테스트로 운영 코드/스크립트가 옛 이름을 직접 참조하지 않는지 확인</li><li>운영 환경에 동일한 절차 적용</li></ol><p>다른 DB나 운영 정책에서는 rename / 신규 sequence 생성 / 스크립트 수정 중 가능한 방식을 별도로 선택해야 합니다. synonym은 어디서나 쓸 수 있는 도구는 아닙니다.</p><p>시퀀스 이름 변경 외에도 JobParameters 저장 구조가 달라졌기 때문에, BATCH_JOB_EXECUTION_PARAMS<strong>를 포함한 전체 Batch 메타 테이블 스키마 마이그레이션 스크립트</strong>를 함께 확인해야 합니다. 저희도 시퀀스 이주만으로 끝내지 않고, 메타 스키마 차이를 한 번 통째로 비교한 뒤 운영 반영을 진행했습니다.</p><p>(<a href="https://github.com/spring-projects/spring-batch/blob/main/spring-batch-core/src/main/resources/org/springframework/batch/core/migration/6.0/migration-oracle.sql">다행히도, Spring Batch 6.x의 메타 테이블 스키마는 시퀀스명을 제외하고는 Spring Batch 5.x와 달라지지 않았습니다.</a> 다만, 다른 버전에서 업데이트 시에는 꼭 스키마 차이도 함께 확인하는 것을 권장드립니다.)</p><h3>4. 주변 생태계 변경</h3><p>Spring Batch 6 외에도 함께 다듬은 영역들입니다.</p><h4>4–1. Kotlin 2.3 — 제네릭 bound가 더 엄격하게 잡혔습니다</h4><p>Kotlin 2.3 전환 후, 그동안 경고로 지나가던 제네릭 bound 관련 코드가 컴파일 오류로 상향되었습니다. 가장 흔한 케이스는 &lt;T&gt; → &lt;T : Any&gt;였습니다.</p><pre>- fun &lt;T&gt; getBean(clazz: Class&lt;T&gt;) = context?.getBean(clazz)<br>+ fun &lt;T : Any&gt; getBean(clazz: Class&lt;T&gt;) = context?.getBean(clazz)</pre><p>Spring 측 context.getBean&lt;T&gt; 시그니처가 T : Any를 요구하기 때문에, 저희 wrapper도 같이 맞춰줘야 했습니다.</p><p>내부 RPC 유틸이 좋은 예였습니다. 기존엔 Any로 받아서 호출부에서 as Map&lt;...&gt;으로 캐스팅했는데, 컴파일러가 드러낸 문제를 계기로 호출 측 타입 컨텍스트로 추론되도록 다시 짰습니다.</p><pre>- private fun call(...): Any { ... }<br>- fun callForMap(...): Map&lt;String, Any&gt; = call(...) as Map&lt;String, Any&gt;<br><br>+ private fun &lt;T&gt; call(...): T { ... }<br>+ fun callForMap(...): Map&lt;String, Any&gt; = call(...)</pre><h4>4–2. Kotest 5.9 → 6.0</h4><p>Kotlin 2.3 업그레이드에 따라 Kotest 또한 업그레이드 하였습니다.</p><p>이 과정에서 기존 kotest-extensions-spring 확장과의 호환성 문제로 인해 해당 버전도 업그레이드 했는데, 이로 인해 기존에 작동하던 DI 기반 테스트가 모두 깨지는 사태가 발생했습니다.</p><p>이에 따라 spring 확장 관련 설정을 <strong>프로젝트 레벨 설정 클래스</strong> 에 명시적으로 추가하였습니다.</p><p>기본 위치인 io.kotest.provided.ProjectConfig를 그대로 쓸 수도 있고, 다른 위치에 두고 싶다면 kotest.properties 파일을 통해 kotest.framework.config.fqn 프로퍼티로 클래스 위치를 알려줄 수 있습니다.</p><pre>class KotestConfig : AbstractProjectConfig() {<br>    override val extensions: List&lt;Extension&gt; =<br>        listOf(SpringExtension(SpringTestLifecycleMode.Root))<br>}</pre><p>저희는 설정 클래스를 프로젝트 패키지 안에 두기로 해서, Gradle 빌드 스크립트에서 시스템 프로퍼티로 위치를 알려줬습니다.</p><pre>tasks.withType&lt;Test&gt; {<br>    useJUnitPlatform()<br>    systemProperty(<br>        &quot;kotest.framework.config.fqn&quot;,<br>        &quot;com.example.batch.config.KotestConfig&quot;,<br>    )<br>}</pre><h4>4–3. Oracle JDBC / 라이브러리 일제 점검</h4><p>이왕 전체 갈아엎는거, 이번 기회(?)에 모듈 안에서 쓰는 라이브러리를 처음부터 끝까지 한 번 훑었습니다.</p><p>(사서 고생하는 느낌이었지만, 결과적으로는 Spring Batch 6.x 호환성 외에도 여러 가지 개선점이 발견되어 좋았습니다.)</p><pre>- implementation(&quot;org.apache.commons:commons-lang3:3.18.0&quot;)<br>- implementation(&quot;org.apache.commons:commons-text:1.13.1&quot;)<br>- implementation(&quot;com.oracle.database.jdbc:ojdbc8:19.12.0.0&quot;)<br>+ implementation(&quot;org.apache.commons:commons-lang3:3.20.0&quot;)<br>+ implementation(&quot;org.apache.commons:commons-text:1.15.0&quot;)<br>+ implementation(&quot;com.oracle.database.jdbc:ojdbc11:23.26.0.0.0&quot;)</pre><p>JDK 21을 쓰는 김에 ojdbc11로 한 번에 올렸습니다. 코드 변경 없이 적용되었지만, 운영 반영 후에는 다른 형태의 점검 포인트가 함께 드러났습니다(5장에서 따로 다룹니다).</p><h4>4–4. Jackson 3 — 그룹 ID와 클래스 이름 변경</h4><p>Spring Boot 4부터 Jackson 3 채택이 진행되면서, <strong>일부 </strong>jackson-annotations<strong>모듈을 제외한 패키지명이 변경되었습니다</strong>(com.fasterxml.jackson → tools.jackson).</p><p>저희 프로젝트에서는 Spring Batch 6가 이미 Jackson 3 기반의 JacksonExecutionContextStringSerializer를 써주고 있고, Spring Framework를 통해 Jackson을 간접 사용하는 형태로 활용했기에 직접적인 영향이 크지 않았습니다.</p><p>다만 <strong>ObjectMapper 등을 직접 사용하기 위해 Jackson을 별도로 직접 의존성으로 사용하고 있거나, </strong>@JsonComponent<strong>/</strong>@JsonMixin<strong>처럼 Jackson 어노테이션을 쓰는 코드가 있다면</strong> 이 시점에 패키지와 클래스/어노테이션 이름 변경(@JsonComponent → @JacksonComponent 등)을 함께 점검할 필요가 있습니다.</p><h4>4–5. AOP starter 정리: spring-boot-starter-aop → spring-boot-starter-aspectj</h4><blockquote><em>Spring Boot 4.0 Migration Guide 인용:</em></blockquote><blockquote>“To clarify the scope of <em>spring-boot-starter-aop</em>, it has been renamed to <em>spring-boot-starter-aspectj</em>.&quot;</blockquote><p>Spring AOP 자체가 사라지거나 동작 방식이 바뀐 것은 아니고, Spring Boot starter 명이 spring-boot-starter-aop에서 spring-boot-starter-aspectj로 정리되었습니다.</p><p>따라서 기존에 spring-boot-starter-aop를 명시적으로 사용하고 있었다면, spring-boot-starter-aspectj로 옮기는 것이 좋습니다.</p><p>저희 프로젝트에서도 이에 따라 aop starter 의존성 라이브러리를 변경했습니다.</p><pre>- implementation(&quot;org.springframework.boot:spring-boot-starter-aop&quot;)<br>+ implementation(&quot;org.springframework.boot:spring-boot-starter-aspectj&quot;)</pre><h4>4–6. application.yml 정정</h4><p>server.servlet.encoding.charset 과 같은 프로퍼티 키가 spring.servlet.encoding.charset 과 같이 업데이트 되었습니다. 이와 비슷하게 프로퍼티 키값이 변경된 부분이 있는지 전체적으로 점검하고 수정하는 작업이 필요합니다.</p><blockquote><em>💡 Spring Boot가 제공하는 </em><em>spring-boot-properties-migrator 의존성을 임시로 추가하면, 잘못 위치하거나 이름이 바뀐 프로퍼티를 런타임 시점에 로그로 알려줍니다. 마이그레이션 기간 한정으로만 두고, 정리 후에는 반드시 제거해야 합니다.</em></blockquote><h3>5. 운영에서만 드러난 문제 — DB 접근 정책과 client program 식별값</h3><p>검증을 마치고 운영에 반영한 직후, 운영 DB 접속이 막혔습니다. 로컬과 알파환경에서는 모두 정상이었기 때문에 긴장되는 순간이었습니다.</p><h4>5–1. 개발에서는 잘 되었는데 갑자기 문제가 발생했다!</h4><ul><li>운영 DB의 접근 정책 검증 단계 과정에서, <strong>클라이언트 프로그램명</strong>을 화이트리스트 식별값 중 하나로 사용하고 있었습니다.</li><li>이전 환경에서는 세션 식별값이 JDBC Thin Client로 들어왔습니다.</li><li>이번 업그레이드 후에는 세션 식별값이 JarLauncher로 들어와, 정책에 등록된 값과 매칭되지 않아 차단되었습니다.</li></ul><p>이 현상은 <strong>JDBC 드라이버 업그레이드, Spring Framework 업그레이드 및 그에 따른 HikariCP 버전 업그레이드 등</strong> 에 따라 어디선가(?) 변화가 있었던 것으로 보입니다. (위 부분은 추정이며 사실 정확히 어디서 바뀌었는지는 아직도 모르겠습니다. 확실한건 세션 식별값이 바뀌었다는 것뿐입니다.)</p><p>이 세션 식별값 변화가 운영환경 DB 접근 정책과 함께 맞물린 결과로써 운영에서만 드러난 문제였습니다.</p><h4>5–2. 어떻게 풀었나</h4><ol><li>운영 측 정책에 새 클라이언트 식별값을 정식으로 등록 요청.</li><li>등록 반영 이후 정상 접속을 확인.</li><li>이후 운영 반영 체크리스트에 <strong>세션의 client program 값을 미리 확인하는 항목</strong>을 추가.</li></ol><blockquote><em>⚠️ </em><strong><em>운영망 정책은 빌드와 별개의 검증 필요</em></strong></blockquote><blockquote><em>빌드와 개발환경 테스트가 모두 통과해도, 운영환경에서만 적용되는 접근 정책과 같은 부분은 또 다른 문제가 될 수 있습니다. 운영 반영 전에 </em><em>v$session(Oracle) 또는 그에 준하는 세션 모니터링 뷰에서 의도한 클라이언트 식별값이 들어오고 있는지 한 번 확인해 두면 좋습니다.</em></blockquote><h3>6. 마무리 — 그래서 처음의 Composite PK는 어떻게 됐냐면</h3><p>결과적으로 처음 기대했던 모델은 그대로 유지할 수 있었습니다.</p><p>SettlementMappingId를 aggregate root의 @Id로 두고, 신규 저장 여부는 Persistable + markNew()로 호출부에서 명시했습니다.</p><p>처음에는 이 한 모델을 위해 시작한 업그레이드였지만, 결과적으로는 <strong>Spring Boot 4·Spring Framework 7·Spring Batch 6·Spring Data JDBC 4 같은 Spring 계열과, Kotlin 2.3·Jackson 3·Kotest 6·ojdbc11·Gradle 9 같은 주변 도구까지 한 번에 정리된 모듈</strong>을 갖게 되었습니다.</p><p>기술부채가 많이 해결되었고, 앞으로도 유지보수와 확장에 훨씬 유리한 기반이 마련된 것 같아 만족스럽습니다.</p><h4>돌아보며 남는 것들</h4><blockquote><strong>변경의 출처를 분리하라.</strong></blockquote><ul><li>Gradle/Kotlin/Spring/Batch/Jackson/Kotest를 한 커밋에 다 섞으면, 빌드가 깨졌을 때 출처를 찾는 비용이 빠르게 커집니다.</li></ul><blockquote><strong>라이브러리의 nullable 변경은 확장 함수로 받아내라.</strong></blockquote><ul><li>라이브러리 호출부 100군데를 고치는 것보다, 확장 함수 5개를 만들고 호출부에 쓰는 편이 보다 빠르고 코드 베이스 전체의 의도를 또렷하게 만듭니다.</li></ul><blockquote><strong>컴파일러가 까칠해진 곳에 진짜 위험이 있었다.</strong></blockquote><ul><li>Kotlin 2.3 전환 후 그동안 warning 만 띄운 채 묵시적으로 동작하던 몇몇 type cast/null 흐름을 다시 보게 되었습니다.</li></ul><blockquote><strong>운영까지 통과해야 진짜 성공이다.</strong></blockquote><ul><li>운영 접근 정책, 시퀀스, 클라이언트 식별값처럼 운영 측에서 결정되는 항목들은 모듈 내부의 어떤 그린 테스트로도 검증되지 않습니다. 메이저 업그레이드의 마지막 검증 단계에는 운영망 시뮬레이션을 반드시 한 번 끼워주세요.</li></ul><h3>Spring Boot 4 / Batch 6 업그레이드 체크리스트</h3><p>혹시라도 저희와 같은 상황에서 메이저 업그레이드를 준비하시는 분들을 위해 저희의 삽질 경험에 기반해서 짧게 정리해 두었습니다.</p><p>(물론 프로젝트마다 상황이 다르겠지만, 참고가 될 수 있으면 좋겠습니다.)</p><h4>베이스라인</h4><ul><li>런타임 JDK가 Spring Boot 4 지원 범위(Java 17 이상)에 들어가는지 확인한다.</li><li>Gradle 버전이 Spring Boot 4 Gradle Plugin 지원 범위(8.14 이상 또는 9.x)에 들어가는지 확인한다.</li><li>Kotlin 사용 시 2.2 이상 사용 여부를 확인한다.</li><li>Spring Framework 7 / Jakarta EE 11 전환으로 javax.* 의존성, Servlet/JPA/Validation 관련 API 영향이 없는지 확인한다.</li></ul><h4>Batch 인프라 / 메타데이터</h4><ul><li>JDBC 기반 Batch 메타데이터가 필요하면 spring-boot-starter-batch-jdbc, @EnableJdbcJobRepository, 또는 JdbcDefaultBatchConfiguration 중 하나를 명시적으로 구성한다.</li><li>Batch 메타 스키마 마이그레이션 스크립트(시퀀스 변경 + BATCH_JOB_EXECUTION_PARAMS 등 테이블 변경 포함)를 확인한다.</li><li>BATCH_JOB_SEQ 등 옛 시퀀스명을 직접 참조하는 다른 코드/운영 스크립트(혹은 모듈, 서버)가 있는지 검색한다.</li><li><strong>Spring Batch 5에서 실패한 JobExecution은 Spring Batch 6에서 그대로 restart할 수 없다는 점</strong>을 운영자와 공유하고, Spring Batch 6 반영 전에 미완료 JobExecution을 정리한다.</li></ul><h4>Batch 코드 / API</h4><ul><li>JobParameters 생성 로직을 Set&lt;JobParameter&gt; 구조에 맞춰 점검하고, 빈 컬렉션을 만들 가능성이 있다면 JobParameters() 기본 생성자로 분기한다.</li><li>JobParameters 입력 검증 정책(형식·blank·중복 key 등)을 팀 컨벤션으로 정한다.</li><li>JobParametersIncrementer<strong>를 쓰는 Job은 </strong>JobOperator.start(...)<strong> 전환 후 별도 테스트한다.</strong></li><li>JobExplorer, JobRepository, JobOperator를 직접 주입해 사용하는 운영/관리 코드가 있다면 Bean 구성과 호출 API를 함께 확인한다.</li><li>Batch 메트릭/관측을 사용한다면 ObservationRegistry 설정과 기존 Micrometer 연동 지점을 확인한다.</li><li>FieldSet.readString, readBigDecimal 등 nullable 반환 API를 Kotlin 코드에서 어떻게 처리할지 기준을 정한다.</li><li>위치/시그니처가 함께 바뀐 listener/reader는 등록 방식과 콜백 호출 시점을 테스트로 확인한다.</li></ul><h4>도메인 모델</h4><ul><li>Composite ID를 사용하는 엔티티는 신규 여부 판단 전략을 명시한다 (예: Persistable + markNew()).</li><li>Composite ID 사용 도메인은 save/findById뿐 아니라 <strong>derived query / </strong>AggregateReference<strong> 조합</strong>까지 SQL과 동작을 직접 확인한다.</li></ul><h4>진행 / 정리</h4><ul><li>Spring Boot 3.5.x 최신 패치까지 먼저 올려 deprecated API를 정리한다.</li><li>Gradle/Kotlin/Spring/Batch/Jackson/Kotest 변경을 가능한 한 커밋 단위로 분리한다.</li><li>테스트 의존성도 spring-boot-starter-&lt;technology&gt;-test 계열로 바뀐 부분이 없는지 확인한다.</li><li>생성자 파라미터 어노테이션의 use-site target(@param:Value 등)을 통일된 컨벤션으로 정한다.</li><li>spring-boot-properties-migrator 의존성을 임시로 추가해 위치/이름이 바뀐 프로퍼티를 미리 점검한다.</li><li>spring-boot-properties-migrator는 마이그레이션 기간에만 두고, 정리 후 반드시 제거한다.</li></ul><h4>운영 반영</h4><ul><li>운영 DB 세션의 client program/module/action 값이 접근 정책과 충돌하지 않는지 사전 확인한다.</li><li>운영망 ACL, 시퀀스, 배포 스크립트처럼 테스트 코드로 검증되지 않는 항목을 별도 체크리스트로 관리한다.</li></ul><h3>끝으로</h3><p>긴 글 읽어주셔서 감사합니다. 비슷한 업그레이드를 앞두고 계신 분들께 작은 지도 한 장이 되었으면 좋겠습니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6bfc2e2cb65b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/composite-pk%EC%97%90%EC%84%9C-%EC%8B%9C%EC%9E%91%EB%90%9C-spring-boot-4-spring-batch-6-%EC%97%85%EA%B7%B8%EB%A0%88%EC%9D%B4%EB%93%9C-%EA%B8%B0%EB%A1%9D-6bfc2e2cb65b">Composite PK에서 시작된 Spring Boot 4 / Spring Batch 6 업그레이드 기록</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[신입개발자의 역량과 성장에 대해서(feat. Done is better than perfect)]]></title>
            <link>https://medium.com/naverfinancial/%EC%8B%A0%EC%9E%85%EA%B0%9C%EB%B0%9C%EC%9E%90%EC%9D%98-%EC%97%AD%EB%9F%89%EA%B3%BC-%EC%84%B1%EC%9E%A5%EC%97%90-%EB%8C%80%ED%95%B4%EC%84%9C-feat-done-is-better-than-perfect-0e7f3732555f?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/0e7f3732555f</guid>
            <category><![CDATA[newbie]]></category>
            <category><![CDATA[growth]]></category>
            <category><![CDATA[dev]]></category>
            <category><![CDATA[backend]]></category>
            <dc:creator><![CDATA[Sudal]]></dc:creator>
            <pubDate>Thu, 07 Aug 2025 01:30:52 GMT</pubDate>
            <atom:updated>2025-08-07T01:30:51.890Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요. 네이버 파이낸셜 카드 BE 팀의 허수진입니다.</p><p>저는 현재 3년차 서버 개발자로서 Java, Kotlin, Spring을 주로 다루며 성장해나가고 있어요. 이 글에서는 개발자로 일하면서 느낀 성장에 대한 생각과, 신입 개발자가 갖춰야 할 역량에 대해 경험을 바탕으로 공유드리고자 합니다!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/980/1*0hwqhm9id5GE4_woywZnzg.png" /><figcaption>신입사원 첫 출근 짤</figcaption></figure><p>사실 우리가 배운 <strong>국영수가 핵심 역량이라고 </strong>생각합니다.</p><ul><li><strong>국어</strong>: 소통의 도구 — 동료들과 명확하게 의사소통할 수 있는 능력</li><li><strong>영어</strong>: 정보 습득 도구 — 최신 기술 문서를 읽을 수 있는 능력</li><li><strong>수학</strong>: 논리적 사고 도구 — 비즈니스 로직을 체계적으로 분석하는 능력</li></ul><p>우리는 신입개발자가 가져야 할 역량을 충분히 보유하고 있습니다.<br>이를 바탕으로 어떤 성장 전략을 세워나갔는지 단계별로 공유해보겠습니다!</p><h3>그게 그 뜻이었어? 용어 정리하기 — 카드 수수료 예시</h3><p>“카드 수수료”라는 용어 하나만 봐도 여러 의미가 있었습니다.</p><ul><li><strong>가맹점 수수료</strong>: 가맹점이 카드사에 지불하는 수수료</li><li><strong>연회비</strong>: 카드 소지자가 카드사에 지불하는 연간 수수료</li><li><strong>해외 이용 수수료</strong>: 해외 결제 시 발생하는 환전 수수료</li><li><strong>현금서비스 수수료</strong>: ATM에서 현금을 인출할 때 발생하는 수수료</li></ul><pre>// 혼란스러운 초기 코드<br>public class CardFeeService {<br>    // 이 수수료가 정확히 무엇을 의미하는지 불분명<br>    public BigDecimal calculateFee(String cardNumber, BigDecimal amount) {<br>        return amount.multiply(new BigDecimal(&quot;0.03&quot;));<br>    }<br>}</pre><h3>의미에 맞는 용어로 전환하기</h3><p>논의를 할 때 “수수료”라고 하면 각자 다른 것을 생각하고 있어서 혼란스러운 소통을 할 여지가 있습니다. 코드와 문서에 이를 한번 정리하고 넘어간다면 훨씬 수월한 소통을 할 수 있게 되었던 것 같습니다.</p><pre>// 명확한 도메인 용어를 사용한 개선된 코드<br>public class MerchantFeeCalculator {<br>    /**<br>     * 가맹점 수수료 계산<br>     * - 가맹점이 카드사에 지불하는 수수료<br>     * - 업종별로 다른 수수료율 적용<br>     */<br>    public BigDecimal calculateMerchantFee(CardType cardType, MerchantCategory category, BigDecimal amount) {<br>        BigDecimal feeRate = merchantFeeRateRepository.findByCardTypeAndCategory(cardType, category);<br>        return amount.multiply(feeRate);<br>    }<br>}</pre><h3>해석의 여지를 없애기</h3><p>일할 때는 <strong>저맥락 소통</strong>이 중요하다고 생각합니다.</p><ul><li><strong>고맥락 대화</strong>: “그거 처리해 주세요” (무엇을 처리할지 불분명)</li><li><strong>저맥락 대화</strong>: “KB 발급사 카드 코드 변경건 내일까지 처리 가능할까요?”</li></ul><p>(소통할 때는 편하게 하기보다 예의 바르게 소통하는 것이 중요한 것 같습니다. 🙌🏼)</p><h3>다양한 관점에서 정보 찾기</h3><p>좋은 개발자가 되려면 스스로 정보를 찾는 능력이 필수라고 생각합니다. <br>저는 다음과 같은 키워드로 검색하며 균형 잡힌 시각을 기르려고 노력하고 있습니다.</p><p><strong>긍정적 정보뿐만 아니라 부정적 정보도 함께 탐색</strong></p><ul><li>Spring Boot 장점 뿐만 아니라 Spring Boot 단점, Spring Boot 주의할점</li><li>Kotlin cons, Kotlin pitfall, Kotlin gotchas</li><li>JPA when not to use, JPA warns</li></ul><p><strong>구체적인 구글 검색 방법</strong></p><ul><li>site:stackoverflow.com JPA N+1 problem - Stack Overflow에서만 JPA N+1 문제 검색</li><li>&quot;Spring Boot&quot; -tutorial 2024..2025 - Spring Boot 관련 최신 정보 중 튜토리얼 제외</li><li>Kotlin coroutines pitfalls OR gotchas - Kotlin 코루틴의 함정이나 주의사항 검색</li></ul><h3>오픈소스 이슈 트래커 활용</h3><p>라이브러리나 프레임워크의 실제 문제점을 파악하려면 GitHub Issues를 직접 확인하는 것이 좋은 것 같습니다. 매일 직접 찾아보기 번거롭다면 특정 GitHub을 Watch 하거나 자체적으로 운영되는 뉴스레터나 관련 블로그를 구독해두는 것도 좋은 방법입니다!</p><p>예를 들어 <a href="https://kotlinweekly.net/">Kotlin Weekly</a> 같은 뉴스레터를 구독하는 거죠.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HpparaCG4DZPhE0Bl7uhdA.png" /></figure><h3>기록은 학습 전략이자 성장 전략</h3><p>개발하면서 겪은 시행착오와 해결 과정을 꾸준히 기록했습니다. 특히 <strong>변칙적인 부분</strong>에 대해서는 반드시 이유를 남겨 공유하는 것이 좋은 것 같습니다.</p><pre>/**<br> * 카드 번호 마스킹 처리<br> * <br> * 주의사항: 로그에는 절대 원본 카드번호를 남기면 안됨 (PCI DSS 규정)<br> * 마스킹 규칙: 앞 6자리 + 마스킹 + 뒤 4자리 (예: 123456******1234)<br> */<br>@Component<br>public class CardNumberMasker {<br>    <br>    public String maskCardNumber(String cardNumber) {<br>        if (cardNumber == null || cardNumber.length() &lt; 10) {<br>            throw new IllegalArgumentException(&quot;유효하지 않은 카드번호입니다&quot;);<br>        }<br>        <br>        String prefix = cardNumber.substring(0, 6);<br>        String suffix = cardNumber.substring(cardNumber.length() - 4);<br>        String masking = &quot;*&quot;.repeat(cardNumber.length() - 10);<br>        <br>        return prefix + masking + suffix;<br>    }<br>}</pre><h3>Wiki와 코드 리포지토리를 통한 기록</h3><p>팀 Wiki에 개발 과정에서 학습한 내용들을 정리하고, <strong>기존 기록을 지속적으로 보강</strong>하면 좋을 것 같습니다.</p><pre>1.1 타임아웃 오류 (HTTP 408)<br>- 원인: PG사 응답 지연<br>- 해결: 재시도 로직 적용 (최대 3회)<br>- 코드: `PaymentRetryService.java` 참고<br>1.2 카드 한도 초과 (Business Error 1001)<br>- 원인: 사용자 카드 한도 부족<br>- 해결: 사용자에게 한도 확인 안내<br>- 추가된 날짜: 2024.03.20<br>- 관련 이슈: CARD-1234</pre><h3>주석을 (잘) 달아라!! — 코드의 목적과 이유를 기록</h3><p>코드에는 그때의 요구사항이 담겨있지만, 때로는 맥락을 모르면 이해할 수 없는 영역들이 담겨 있습니다. 따라서 단순히 코드가 <strong>무엇을 하는지</strong>가 아니라 <strong>왜 그런 처리가 필요한지</strong>에 대한 이유를 기록하면 좋습니다.</p><pre>/**<br> * 하나카드는 유효성 검증을 Luhn 알고리즘을 통해 진행해야 합니다.<br> * <br> * Luhn 알고리즘을 사용하여 카드번호 유효성 검증<br> * <br> * 주의사항: <br> * - 체크섬 계산 시 우수번째 자리는 2배 후 각 자릿수 합산<br> * - 10 이상인 경우 각 자릿수를 분리해서 더해야 함 (예: 16 -&gt; 1+6=7)<br> * <br> * 참고: https://en.wikipedia.org/wiki/Luhn_algorithm<br> */<br>public boolean validateCardNumber(String cardNumber) {<br>    int sum = 0;<br>    boolean alternate = false;<br>    <br>    for (int i = cardNumber.length() - 1; i &gt;= 0; i--) {<br>        int digit = Character.getNumericValue(cardNumber.charAt(i));<br>        <br>        if (alternate) {<br>            digit *= 2;<br>            if (digit &gt; 9) {<br>                digit = (digit % 10) + 1; // 각 자릿수 합산<br>            }<br>        }<br>        <br>        sum += digit;<br>        alternate = !alternate;<br>    }<br>    <br>    return sum % 10 == 0;<br>}</pre><h3>Batch Job의 시간 의존적 상황</h3><pre>/**<br> * 카드 정산 배치 작업<br> * <br> * 실행 시간: 매일 새벽 2시 (KST)<br> * <br> * 시간 제약사항:<br> * - 새벽 1시~3시: PG사 정산 시스템 점검으로 인한 API 제한<br> * - 새벽 2시: 가장 트래픽이 적은 시간대<br> * - 3시 이전 완료 필수: 오전 업무 시작 전 정산 완료 필요<br> */<br>@Scheduled(cron = &quot;0 0 2 * * *&quot;, zone = &quot;Asia/Seoul&quot;)<br>public void executeCardSettlement() {<br>    log.info(&quot;카드 정산 배치 시작 - {}&quot;, LocalDateTime.now());<br>    <br>    try {<br>        // 전일 카드 거래 정산 처리<br>        settlementService.settleYesterdayTransactions();<br>    } catch (Exception e) {<br>        log.error(&quot;카드 정산 실패&quot;, e);<br>        alertService.sendAlert(&quot;카드 정산 배치 실패&quot;, e.getMessage());<br>    }<br>}</pre><h3>질문해도 된다 — ⭐️ 하지만 댓가를 치뤄라 ⭐️</h3><p>첫 업무가 주어졌을 때가 아직도 기억납니다. “어떻게 개발환경 설정을 해야하지? 내장 톰캣은 버전 몇을 써야하지?..” 등등 막막함 투성이었습니다.</p><p>바빠보이시는 사수님들의 시간을 뺏는 건 아닐까, 혹은 바보같은 질문은 아닐까 망설여지는 분들을 위한 팁입니다!</p><h3>효과적인 질문 방법</h3><p>질문하기 전에 일정 시간 스스로 탐구해야 합니다.</p><ol><li><strong>회사 문서창고(Wiki) 검색</strong></li><li><strong>사내 메신저에서 과거 대화 검색</strong></li><li><strong>관련 코드 분석 (키워드 기반 분석)</strong></li><li><strong>네이버/구글 검색 및 Stack Overflow 확인</strong></li></ol><h3>좋은 질문의 예시</h3><p><strong>나쁜 질문 🙅‍♀️ </strong>: “카드 결제가 안 되는데요?” (맥락 없이 결과만 물어보게 되면 여러 차례 질답을 통해 문제를 파악하는 에너지가 사용됩니다.)</p><p><strong>좋은 질문🙆‍♀️ </strong>: “카드 결제 승인 API에서 문제가 발생했습니다.</p><p><strong>상황</strong>:</p><ul><li>카드번호: 1234<strong> — </strong>-5678 (테스트 카드)</li><li>결제금액: 10,000원</li><li>오류 메시지: “Invalid card number format”</li></ul><p><strong>시도한 것</strong>:</p><ol><li>Wiki의 ‘카드 결제 가이드’ 확인</li><li>CardValidator.java의 유효성 검증 로직 분석</li><li>같은 오류로 검색했으나 명확한 해답 못 찾음</li></ol><p><strong>질문</strong>: 테스트 카드번호 형식이 잘못된 건지, 아니면 다른 이슈인지 확인 부탁드립니다.”</p><p>맥락과 함께 시도했던 방법까지 함께 공유하면 보다 빠른 해결 방안을 모색할 수 있게 됩니다.</p><h3>질문에 대한 값 치루기 ⭐️⭐️⭐️</h3><p>질문을 통해 얻은 답변은 반드시 <strong>다음 사람을 위해 기록</strong>해야 한다고 생각합니다. 팀원들이 시간 내어 공유해준 지식을 휘발시키지 않고, 미래의 같은 고민을 할 사람을 위해서 기록해둔다면 장기적으로 모두의 시간을 절약할 수 있습니다.</p><p>시간을 뺏은 것 같은 미안한 기분이 든다면 <strong>기록하기</strong>!</p><pre>/**<br> * 카드번호 포맷 검증<br> * <br> * Q: 테스트 카드번호도 실제 카드번호와 같은 형식이어야 하나요?<br> * A: 네, Luhn 알고리즘 검증을 통과해야 합니다. <br> *    단, 실제 결제는 PG사에서 차단됩니다.<br> * <br> * 날짜: 2024.03.22<br> */<br>private boolean isValidFormat(String cardNumber) {<br>    // 하이픈 제거 후 숫자만 추출<br>    String cleaned = cardNumber.replaceAll(&quot;-&quot;, &quot;&quot;);<br>    <br>    // 길이 체크 (13-19자리)<br>    if (cleaned.length() &lt; 13 || cleaned.length() &gt; 19) {<br>        return false;<br>    }<br>    <br>    // Luhn 알고리즘 검증<br>    return luhnAlgorithm.validate(cleaned);<br>}</pre><h3>요구사항의 목적/이유를 파악하라</h3><p>제시하는 요구사항에서 <strong>진짜 의도</strong>를 파악하는 것이 중요하다고 생각합니다.</p><p><strong>구체적 구현 요청</strong></p><blockquote><em>“카드 승인 버튼을 빨간색으로 만들어 주세요”</em></blockquote><p><strong>근본적인 목적 파악</strong></p><blockquote><em>“카드 승인 버튼이 잘 보이지 않아서 사용자들이 놓치는 경우가 많아요. 더 눈에 띄게 만들어 주세요”</em></blockquote><h3>더 나은 해결책 제시</h3><p>목적을 이해하면 더 나은 대안을 제시할 수 있습니다!</p><pre>/* 단순한 색상 변경 */<br>.approval-button {<br>    background-color: red; /* 요청사항 그대로 */<br>}</pre><pre>/* 목적을 이해한 개선안 */<br>.approval-button {<br>    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);<br>    box-shadow: 0 4px 15px rgba(102, 126, 234, 0.3);<br>    transform: translateY(-2px);<br>    transition: all 0.3s ease;<br>    <br>    /* 접근성도 고려한 디자인 */<br>    border: 2px solid #4f46e5;<br>    font-weight: 600;<br>}</pre><pre>.approval-button:hover {<br>    transform: translateY(-4px);<br>    box-shadow: 0 8px 25px rgba(102, 126, 234, 0.4);<br>}</pre><h3>예외 처리와 로깅</h3><p>예외가 발생했을 때는 <strong>문제 해결에 필요한 충분한 정보</strong>를 남겨야 합니다.<br>그렇지않으면 급하게 로그를 추가하고 재배포해서 문제를 파악 하는 등 문제 대응에 많은 시간을 쓰게 됩니다 . 😭</p><p><strong>나쁜 로그 🙅‍♀️</strong></p><pre>catch (PaymentException e) {<br>    log.error(&quot;결제 실패&quot;);<br>    throw new RuntimeException(&quot;결제 처리 중 오류 발생&quot;);<br>}</pre><p><strong>좋은 로그 🙆‍♀️</strong></p><pre>catch (PaymentException e) {<br>    log.error(&quot;카드 결제 승인 실패 - 카드번호: {}, 금액: {}, PG사: {}, 오류코드: {}, 오류메시지: {}&quot;, <br>             maskCardNumber(request.getCardNumber()),<br>             request.getAmount(),<br>             request.getPgProvider(),<br>             e.getErrorCode(),<br>             e.getMessage(), e);<br>             <br>    throw new PaymentProcessingException(<br>        String.format(&quot;결제 승인 실패 - 주문번호: %s, 오류: %s&quot;, <br>                     request.getOrderId(), e.getMessage()), e);<br>}</pre><blockquote>TIP : 개발환경에서는 운영환경보다 더 자세한 로그를 debug mode로 남겨서 문제가 발생했을 때 파악할 수 있는 충분한 정보를 제공하면 파악하기 한결 수월해집니다!</blockquote><h3>Done is better than perfect</h3><h3>완벽함을 추구하는 당신에게</h3><p>가장 많이 깨달은 것은 <strong>완벽한 구현/코드는 없다</strong>는 점입니다. 처음에는 완벽한 디자인 패턴, 완벽한 구현을 하려고 많은 시간을 소비했습니다.</p><p>그러다 보니 마감기한 직전에 PR 리뷰를 요청하고 시간에 쫓기며 기능을 구현하고, 마음에 여유가 없으니 배움도 적다고 느꼈습니다.</p><p>그래서 저는 나만의 <strong>MVP (Minimum Viable Product)</strong>를 도출하고<br> 가용 가능한 시간만큼 점진적인 개선을 진행하고 있습니다.</p><p><strong>요구사항</strong>: “카드 결제가 가능하게 해주세요.”</p><p><strong>도출된 MVP</strong></p><ol><li>카드 결제 기능</li><li>카드 결제 기능 예외 처리 및 모니터링을 위한 정보 제공</li><li>성능 최적화 및 캐싱 적용</li><li>유지보수 가능한 아키텍처 개선 및 테스트 코드 작성</li></ol><h3>점진적 개선의 예시</h3><p><strong>1차: 기본 기능 구현</strong></p><pre>@Service<br>public class CardPaymentService {<br>    <br>    public void processPayment(String cardNumber, BigDecimal amount) {<br>        // 일단 동작하는 코드 작성<br>        if (amount.compareTo(BigDecimal.ZERO) &gt; 0) {<br>            // PG사 API 호출<br>            pgApiClient.requestPayment(cardNumber, amount);<br>        }<br>    }<br>}</pre><p><strong>2차: 예외 처리 및 로깅 추가</strong></p><pre>@Service <br>public class CardPaymentService {<br>    private final Logger logger = LoggerFactory.getLogger(CardPaymentService.class);<br>    <br>    public PaymentResult processPayment(PaymentRequest request) {<br>        logger.info(&quot;결제 처리 시작 - 카드번호: {}, 금액: {}&quot;, <br>                   maskCardNumber(request.getCardNumber()), request.getAmount());<br>        <br>        try {<br>            validatePaymentRequest(request);<br>            return executePayment(request);<br>        } catch (PaymentException e) {<br>            logger.error(&quot;결제 실패 - 카드번호: {}, 사유: {}&quot;, <br>                        maskCardNumber(request.getCardNumber()), e.getMessage());<br>            throw e;<br>        }<br>    }<br>    <br>    private void validatePaymentRequest(PaymentRequest request) {<br>        if (request.getAmount().compareTo(BigDecimal.ZERO) &lt;= 0) {<br>            throw new InvalidAmountException(&quot;결제 금액은 0보다 커야 합니다&quot;);<br>        }<br>        <br>        if (!cardValidator.isValid(request.getCardNumber())) {<br>            throw new InvalidCardException(&quot;유효하지 않은 카드번호입니다&quot;);<br>        }<br>    }<br>}</pre><p><strong>3차: 성능 최적화 및 캐싱 적용</strong></p><pre>@Service <br>public class CardPaymentService {<br>    private final Logger logger = LoggerFactory.getLogger(CardPaymentService.class);<br>    private final RedisTemplate&lt;String, Object&gt; redisTemplate;<br>    <br>    @Retryable(value = {PaymentTimeoutException.class}, maxAttempts = 3)<br>    public PaymentResult processPayment(PaymentRequest request) {<br>        logger.info(&quot;결제 처리 시작 - 주문번호: {}, 금액: {}&quot;, <br>                   request.getOrderId(), request.getAmount());<br>        <br>        // 중복 결제 방지를 위한 Redis 락 적용<br>        String lockKey = &quot;payment:lock:&quot; + request.getOrderId();<br>        Boolean lockAcquired = redisTemplate.opsForValue()<br>                .setIfAbsent(lockKey, &quot;LOCKED&quot;, Duration.ofMinutes(5));<br>        <br>        if (!lockAcquired) {<br>            throw new DuplicatePaymentException(&quot;이미 처리 중인 결제입니다&quot;);<br>        }<br>        <br>        try {<br>            validatePaymentRequest(request);<br>            PaymentResult result = executePaymentWithRetry(request);<br>            cachePaymentResult(request.getOrderId(), result);<br>            return result;<br>        } finally {<br>            redisTemplate.delete(lockKey);<br>        }<br>    }<br>}</pre><p><strong>4차: 아키텍처 개선 및 테스트 코드 작성</strong></p><pre>@Service<br>@Transactional<br>public class CardPaymentService {<br>    <br>    private final PaymentValidator paymentValidator;<br>    private final PaymentExecutor paymentExecutor;<br>    private final PaymentEventPublisher eventPublisher;<br>    private final PaymentCacheManager cacheManager;<br>    <br>    public PaymentResult processPayment(PaymentRequest request) {<br>        // 1. 유효성 검증<br>        paymentValidator.validate(request);<br>        <br>        // 2. 중복 결제 체크<br>        preventDuplicatePayment(request.getOrderId());<br>        <br>        // 3. 결제 실행<br>        PaymentResult result = paymentExecutor.execute(request);<br>        <br>        // 4. 이벤트 발행 (비동기)<br>        eventPublisher.publishPaymentCompleted(result);<br>        <br>        // 5. 캐시 업데이트<br>        cacheManager.cacheResult(request.getOrderId(), result);<br>        <br>        return result;<br>    }<br>}</pre><h3>이것 또한 과정을 기록하고 계속 갱신하기</h3><p>각 단계마다 왜 이런 개선을 했는지, 어떤 문제를 해결했는지를 작업 이슈 기록으로 남겨 공유한다면 다음 작업자 혹은 문제가 발생했을 때 원인을 분석하기 한결 수월해지는 것 같습니다.</p><h3>경험을 통한 깨달음</h3><p>DDD, TDD, Hexagonal Architecture… 개발 방법론과 설계를 처음 접하면 무조건 적용해야 멋진 개발자 같은 느낌이 들곤 합니다. 그런데 실제로 해보면 정말 좋다고 느껴지지 않았던 것 같습니다.</p><p>과거, TDD를 완벽하게 적용하려고 했지만, 실제로는 다음과 같은 방식이 더 효율적이었습니다!</p><ol><li><strong>처음부터 테스트를 고민하다 보니 시간이 너무 오래 걸림</strong></li><li><strong>절차적으로 코드를 먼저 짠 후 리팩토링</strong></li><li><strong>이후 테스트 코드를 작성해서 완성</strong></li></ol><pre>// 1단계: 절차적 코드로 빠르게 구현<br>public boolean validateCard(String cardNumber) {<br>    cardNumber = cardNumber.replaceAll(&quot;-&quot;, &quot;&quot;);<br>    if (cardNumber.length() &lt; 13) return false;<br>    if (cardNumber.length() &gt; 19) return false;<br>    <br>    int sum = 0;<br>    for (int i = 0; i &lt; cardNumber.length(); i++) {<br>        // Luhn 알고리즘 구현<br>    }<br>    return sum % 10 == 0;<br>}<br>// 2단계: 리팩토링<br>public boolean validateCard(String cardNumber) {<br>    String cleaned = removeHyphens(cardNumber);<br>    <br>    if (!isValidLength(cleaned)) {<br>        return false;<br>    }<br>    <br>    return luhnAlgorithm.validate(cleaned);<br>}<br>// 3단계: 테스트 코드 작성<br>@Test<br>void 유효한_카드번호_검증() {<br>    assertThat(cardValidator.validateCard(&quot;4532-1234-5678-9012&quot;)).isTrue();<br>}</pre><p>개발 방법론, 완벽한 설계의 목적은 <strong>작동하는 도구</strong>를 만드는 것입니다. 디자인 패턴 또한 반복되는 문제를 해결하기 위한 방법을 정의한 것이라고 이해하고 있습니다.</p><p>그렇기 때문에 많은 문제를 만나보고, 직접 고민해보고 해결방법을 여러 차례 시도해본 뒤 설계나 방법론을 접하게 되었을 때와 느끼는 바가 크게 다른 것 같습니다.</p><p><strong>신입개발자라면 위 개념들의 필요성을 느끼는 것이 우선이라고 생각합니다.</strong> 많은 문제를 만나고, 그것을 치열하게 고민해보세요 ! 🔥</p><h3>너무 자동화에 의존하지 말자</h3><p>때로는 <strong>무념무상으로 단순 반복</strong>하는 것도 필요하다고 생각합니다.</p><pre>// 자동화 도구(fixture monkey) 없이 직접 작성하며 학습<br>@Test void 카드_1234_5678_9012_3456_유효성_검증() { /* ... */ }<br>@Test void 카드_4000_0000_0000_0002_유효성_검증() { /* ... */ }<br>@Test void 카드_5555_5555_5555_4444_유효성_검증() { /* ... */ }<br>// ... 반복적이지만 각각의 케이스를 이해하게 됨</pre><p>반복 작업을 통해 <strong>패턴을 체득</strong>하고, 불편함을 느껴봐야 나중에 자동화도구를 사용하거나 만들 때도 더 좋은 기준이 생기게 됩니다.</p><h3>나의 개발 도구 최적화</h3><p>개인적으로는 <strong>IDE와 개발 환경을 깊이 이해</strong>하고 최적화하는 것이 중요하다고 생각합니다.</p><p>잘하는 개발자들은 마우스가 필요 없다는 농담… 들어보신 적 있으신가요? 엑셀 함수를 사용하는 자와 사용하지 않는 자의 생산성 차이처럼 IDE 또한 편의 기능을 많이 제공하기 때문에 익숙해지면 보다 중요한 업무에 에너지를 사용할 수 있게 됩니다!</p><p><strong>IntelliJ IDEA 단축키</strong></p><ul><li>Ctrl + Shift + F: 전체 검색</li><li>Ctrl + Shift + R: 전체 치환</li><li>Alt + Enter: Quick Fix</li><li>Ctrl + Alt + L: 코드 포맷팅</li><li>Shift + F6: 리팩토링 (이름 변경)</li></ul><p><strong>자주 사용하는 Live Template 설정</strong></p><ul><li>psvm → public static void main(String[] args)</li><li>sout → System.out.println()</li><li>test → @Test void 메서드명() { }</li></ul><h3>반드시 알아야 할 보안 이슈</h3><p>개발을 하다 보면 보안에 대한 인식을 가지고 관련된 노력을 하는 것도 반드시 중요한 영역이라고 생각합니다.</p><h3>1. SQL Injection 방지</h3><p><strong>위험한 코드🙅‍♀️</strong></p><pre>public Card findByCardNumber(String cardNumber) {<br>    String sql = &quot;SELECT * FROM cards WHERE card_number = &#39;&quot; + cardNumber + &quot;&#39;&quot;;<br>    return jdbcTemplate.queryForObject(sql, Card.class);<br>}</pre><p><strong>안전한 코드 🙆‍♀️</strong></p><pre>@Query(&quot;SELECT c FROM Card c WHERE c.cardNumber = :cardNumber&quot;)<br>Optional&lt;Card&gt; findByCardNumber(@Param(&quot;cardNumber&quot;) String cardNumber);</pre><h3>2. XSS(Cross-Site Scripting) 방지</h3><pre>@RestController<br>public class CardController {<br>    <br>    @GetMapping(&quot;/cards/{cardId}&quot;)<br>    public ResponseEntity&lt;CardResponse&gt; getCard(@PathVariable String cardId) {<br>        // Path Variable은 자동으로 HTML 인코딩됨<br>        <br>        // 하지만 직접 HTML 생성 시 주의 필요<br>        String safeCardId = HtmlUtils.htmlEscape(cardId);<br>        <br>        return ResponseEntity.ok(cardService.getCard(safeCardId));<br>    }<br>}</pre><h3>3. PCI DSS 준수</h3><pre>/**<br> * 카드정보 저장 시 PCI DSS 규정 준수<br> * - 카드번호: 암호화 저장<br> * - CVV: 저장 금지<br> * - 로그: 마스킹 처리<br> */<br>@Entity<br>public class Card {<br>    <br>    @Convert(converter = CardNumberEncryptor.class)<br>    @Column(name = &quot;encrypted_card_number&quot;)<br>    private String cardNumber;<br>    <br>    // CVV는 절대 저장하지 않음 (PCI DSS 위반)<br>    @Transient<br>    private String cvv; // 메모리에서만 사용<br>}</pre><h3>OWASP Top 10 학습</h3><p>보안 팀이 존재한다면 지속적으로 관리해주시지만 그렇지 않은 환경에 계신다면 최신 보안 위협에 대해 지속적으로 학습하고 팀과 공유해보면 어떨까요?</p><pre># 보안 체크리스트 (2024 기준)</pre><pre>## A01:2021 – Broken Access Control<br>- [ ] 권한 검증 로직 구현<br>- [ ] URL 직접 접근 차단</pre><pre>## A02:2021 – Cryptographic Failures  <br>- [ ] 카드번호 암호화 저장<br>- [ ] HTTPS 강제 사용</pre><pre>## A03:2021 – Injection<br>- [ ] 모든 쿼리 파라미터화<br>- [ ] 입력값 검증 및 sanitization</pre><h3>요약 — 코드 너머의 가치</h3><ul><li>문제를 해결한 과정과 이유를 문서화하자</li><li>질문시 일의 목적과 맥락을 함께 설명하자.</li></ul><h3>마치며</h3><p>완벽한 개발자는 없지만, 완벽함을 향해 가는 여정에서 <strong>소통을 통해 함께 성장하는 것</strong>이 가장 중요하다고 생각합니다. 기록하고, 공유하고, 질문하고, 답변하면서 팀 전체가 발전해나가는 것이 진정한 성장이라고 믿습니다!!</p><p>신입 개발자분들에게 이 글이 조금이나마 도움이 되었기를 바라며, 혹시 함께 이야기하고 싶은 내용이 있다면 언제든 댓글로 남겨주세요. 함께 성장해나가는 개발자가 되었으면 좋겠습니다. 🙏🏻</p><p><em>이 글을 읽어주셔서 감사합니다!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0e7f3732555f" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/%EC%8B%A0%EC%9E%85%EA%B0%9C%EB%B0%9C%EC%9E%90%EC%9D%98-%EC%97%AD%EB%9F%89%EA%B3%BC-%EC%84%B1%EC%9E%A5%EC%97%90-%EB%8C%80%ED%95%B4%EC%84%9C-feat-done-is-better-than-perfect-0e7f3732555f">신입개발자의 역량과 성장에 대해서(feat. Done is better than perfect)</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[똑같은 코드인데 왜 안 돼? Spring JDBC 컨버터 미궁 탈출기]]></title>
            <link>https://medium.com/naverfinancial/%EB%98%91%EA%B0%99%EC%9D%80-%EC%BD%94%EB%93%9C%EC%9D%B8%EB%8D%B0-%EC%99%9C-%EC%95%88-%EB%8F%BC-spring-jdbc-%EC%BB%A8%EB%B2%84%ED%84%B0-%EB%AF%B8%EA%B6%81-%ED%83%88%EC%B6%9C%EA%B8%B0-9bbe3935fb15?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/9bbe3935fb15</guid>
            <dc:creator><![CDATA[Sudal]]></dc:creator>
            <pubDate>Tue, 05 Aug 2025 06:39:49 GMT</pubDate>
            <atom:updated>2025-08-05T05:19:02.318Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요. 네이버페이에서 카드 BE 담당하고 있는 허수진입니다. 🙂</p><p>저희 팀에서는 <strong>데이터베이스의 실제 저장 형태와 무관하게 애플리케이션에서 타입 안정성을 확보하면서 원하는 형식으로 데이터를 다루기 위해서 Spring Data JDBC에서 커스텀 컨버터</strong>를 사용하고 있습니다.</p><p>e.g.</p><ul><li>DB에는 문자열로 저장되어 있지만 애플리케이션에서는 LocalDate로 다루고 싶거나</li><li>DB의 숫자값을 애플리케이션에서는 Enum으로 처리하고 싶거나</li><li>JSON 문자열을 객체로 자동 변환해서 사용하고 싶을 때</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bS_mIV5nLqqQaqjQqwkUAg.png" /><figcaption>출처 geeksforgeeks</figcaption></figure><p>그런데 똑같은 패턴으로 작성한 컨버터인데 <strong>LocalDateTime은 작동하고 LocalDate는 예상과 다르게 동작</strong>하는 현상을 발견했습니다. 😱</p><p>공부해보니 JDBC 처리 과정에 해답이 있었습니다.</p><p>이 글에서는 JDBC 계층별 동작 원리와 타입 변환 우선순위를 파헤쳐보고, 실제 해결책까지 다뤄보겠습니다!</p><h3>커스텀 컨버터 작성과 등록</h3><p>먼저 일반적인 방식으로 커스텀 컨버터를 작성했습니다.</p><pre>@WritingConverter<br>class LocalDateToStringConverter : Converter&lt;LocalDate, String&gt; {<br>    override fun convert(source: LocalDate): String =<br>        source.format(DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>}<br>@ReadingConverter<br>class StringToLocalDateConverter : Converter&lt;String, LocalDate&gt; {<br>    override fun convert(source: String): LocalDate =<br>        LocalDate.parse(source, DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>}</pre><p>그리고 Spring Data JDBC 설정에서 컨버터를 등록합니다.</p><pre>@Configuration<br>class DatabaseConfig : AbstractJdbcConfiguration() {<br>    <br>    override fun userConverters(): MutableList&lt;Converter&lt;*, *&gt;&gt; =<br>        listOf(<br>            LocalDateToStringConverter(),    // LocalDate → String<br>            StringToLocalDateConverter(),    // String → LocalDate<br>        ).toMutableList()<br>}</pre><p>이렇게 하면 Entity의 LocalDate 필드가 자동으로 문자열로 변환되어 DB에 저장될 것으로 예상했습니다.</p><pre>data class PaymentEntity(<br>    val id: Long,<br>    val paymentDate: LocalDate  // &quot;2024-08-01&quot; 형식으로 저장되길 기대<br>)</pre><p><strong>하지만 실제로는 Oracle의 타임스탬프 형식으로 저장되었습니다.</strong> <br>분명 컨버터를 올바르게 등록했는데 왜 작동하지 않는 걸까요? 🥹</p><pre>-- 기대했던 결과<br>SELECT payment_date FROM payment_entity WHERE id = 1;<br>-- &#39;2024-08-01&#39;<br><br>-- 실제 저장된 결과  <br>SELECT payment_date FROM payment_entity WHERE id = 1;<br>-- &#39;01-AUG-24&#39;  (Oracle 기본 DATE 형식)</pre><p>심지어 VARCHAR 컬럼임에도 불구하고 Oracle의 DATE 타입으로 변환된 결과가 저장되었습니다.</p><p>반면 동일한 방식으로 작성한 LocalDateTime 컨버터는 완벽하게 작동했습니다.</p><pre>@WritingConverter<br>class LocalDateTimeToStringConverter : Converter&lt;LocalDateTime, String&gt; {<br>    override fun convert(source: LocalDateTime): String =<br>        source.format(DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd HH:mm:ss&quot;))<br>}</pre><h3>핵심 문제 발견</h3><p>Spring JDBC 소스코드를 분석한 결과, StatementCreatorUtils.setParameterValue() 메서드에서 Java 타입에 따라 다른 처리 경로를 사용한다는 것을 발견했습니다:</p><pre>// StatementCreatorUtils.java (Spring JDBC 내부)<br>public static void setParameterValue(PreparedStatement ps, int paramIndex, <br>                                   SqlParameter param, Object inValue) {<br>    <br>    if (inValue instanceof LocalDate) {<br>        // LocalDate 특별 처리 경로<br>        LocalDate localDate = (LocalDate) inValue;<br>        ps.setDate(paramIndex, java.sql.Date.valueOf(localDate));<br>    } <br>    else if (inValue instanceof LocalDateTime) {<br>        // LocalDateTime 특별 처리 경로<br>        LocalDateTime localDateTime = (LocalDateTime) inValue;<br>        ps.setTimestamp(paramIndex, java.sql.Timestamp.valueOf(localDateTime));<br>    } <br>    else if (inValue instanceof String) {<br>        // 커스텀 컨버터가 적용된 경우<br>        ps.setString(paramIndex, (String) inValue);<br>    }<br>    // ... 기타 타입들<br>}</pre><h3>setTimestamp vs setDate vs setString의 차이점</h3><p>여기서 중요한 것은 각 메서드가 JDBC 드라이버에게 전달하는 <strong>타입 힌트</strong>가 다르다는 점입니다!!</p><h4>1. setDate(paramIndex, java.sql.Date)</h4><pre>ps.setDate(paramIndex, java.sql.Date.valueOf(localDate));</pre><ul><li>JDBC 드라이버에게 “이것은 DATE 타입이다”라고 알려줌</li><li>Oracle 드라이버는 이를 DATE 타입으로 인식하고 처리</li><li>VARCHAR 컬럼이어도 Oracle은 내부적으로 DATE 변환을 시도</li><li>결과: &#39;01-AUG-24&#39; 같은 Oracle 기본 DATE 형식으로 저장</li></ul><h4>2. setTimestamp(paramIndex, java.sql.Timestamp)</h4><pre>ps.setTimestamp(paramIndex, java.sql.Timestamp.valueOf(localDateTime));</pre><ul><li>JDBC 드라이버에게 “이것은 TIMESTAMP 타입이다”라고 알려줌</li><li>Oracle 드라이버는 이를 TIMESTAMP 타입으로 인식하고 처리</li><li>VARCHAR 컬럼이면 타임스탬프를 문자열로 변환하여 저장</li><li>결과: &#39;2024-08-01 15:30:45.123&#39; 같은 타임스탬프 형식으로 저장</li></ul><h4>3. setString(paramIndex, String)</h4><pre>ps.setString(paramIndex, convertedString);</pre><ul><li>JDBC 드라이버에게 “이것은 문자열이다”라고 알려줌</li><li>드라이버는 별도 변환 없이 문자열을 그대로 컬럼에 저장</li><li>결과: &#39;2024-08-01&#39; 같은 우리가 원하는 형식으로 저장</li></ul><h3>실제로는 LocalDateTime도 커스텀 컨버터가 동작한 게 아니었다. 🔥</h3><p>위에서 코드를 보시면 커스텀 컨버터 처리 순서보다 특별 처리 경로가 먼저 있었습니다. 그렇다면 LocalDateTime도 커스텀 컨버터가 동작하지 않는게 맞는데 어떻게 처리가 되었던 걸까요?</p><h3>실제 동작 과정</h3><p><strong>LocalDate의 경우</strong></p><ol><li>Spring JDBC가 instanceof LocalDate 체크</li><li>커스텀 컨버터 무시하고 ps.setDate(paramIndex, java.sql.Date.valueOf(localDate)) 호출</li><li>Oracle JDBC 드라이버가 java.sql.Date를 받았는데 대상 컬럼이 VARCHAR</li><li><strong>타입 불일치로 오류가 발생했습니다.</strong></li></ol><p><strong>LocalDateTime의 경우</strong></p><ol><li>Spring JDBC가 instanceof LocalDateTime 체크</li><li>커스텀 컨버터 무시하고 ps.setTimestamp(paramIndex, java.sql.Timestamp.valueOf(localDateTime)) 호출</li><li>Oracle JDBC 드라이버가 java.sql.Timestamp를 받았는데 대상 컬럼이 VARCHAR</li><li><strong>Oracle이 관대하게 Timestamp를 문자열로 변환해서 저장하는 것이었습니다.</strong></li></ol><h3>Oracle JDBC 드라이버의 타입 변환 관대함 차이</h3><ul><li>setDate() + VARCHAR 컬럼 = <strong>오류 발생</strong> (엄격함)</li><li>setTimestamp() + VARCHAR 컬럼 = <strong>자동 문자열 변환</strong> (관대함)</li></ul><p>결국 LocalDateTime이 “정상 동작”한 것처럼 보인 건 Oracle JDBC 드라이버의 TIMESTAMP → VARCHAR 자동 변환 덕분이었고, LocalDate는 DATE → VARCHAR 변환에서 오류가 발생했던 것입니다.</p><h3>다양한 해결 시도들 ⭐️</h3><p>이 방법을 해결하기 위해 여러 방법을 시도했습니다.</p><h3>1. @DateTimeFormat 어노테이션 시도</h3><pre>data class SomeEntity(<br>    @DateTimeFormat(pattern = &quot;yyyy-MM-dd&quot;)<br>    private val date: LocalDate<br>)</pre><p><strong>결과</strong>: 실패. @DateTimeFormat은 웹 요청 파라미터 바인딩용이며 데이터베이스 매핑에는 영향을 주지 않습니다.</p><h3>2. JdbcTemplate 직접 사용</h3><pre>@Repository<br>class CustomDateRepository(<br>    private val jdbcTemplate: NamedParameterJdbcTemplate<br>) {<br>    fun save(entity: SomeEntity) {<br>        val sql = &quot;&quot;&quot;<br>            INSERT INTO some_table (id, date_column) <br>            VALUES (:id, :date)<br>        &quot;&quot;&quot;.trimIndent()<br>        <br>        val params = mapOf(<br>            &quot;id&quot; to entity.id,<br>            &quot;date&quot; to entity.date.format(DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>        )<br>        <br>        jdbcTemplate.update(sql, params)<br>    }<br>}</pre><p><strong>결과</strong>: 동작하지만 Spring Data JDBC의 편의성을 포기해야 하며 유지보수성이 떨어집니다.</p><h3>3. String 필드 + 변환 메서드</h3><pre>data class SomeEntity(<br>    @Column(&quot;date_column&quot;)<br>    private val dateString: String<br>) {<br>    val date: LocalDate<br>        get() = LocalDate.parse(dateString, DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>    <br>    companion object {<br>        fun create(date: LocalDate): SomeEntity {<br>            return SomeEntity(<br>                dateString = date.format(DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>            )<br>        }<br>    }<br>}</pre><p><strong>결과</strong>: 기술적으로는 가능하지만 Entity의 의미가 모호해지고 가독성이 떨어집니다.</p><h3>최종 해결책: CustomLocalDate 래퍼 클래스</h3><p>가장 깔끔한 해결책은 LocalDate를 감싸는 래퍼 클래스를 만드는 것이었습니다.</p><pre>data class CustomLocalDate(val value: LocalDate) {<br>    override fun toString(): String = value.format(DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;))<br>    <br>    companion object {<br>        fun now(): CustomLocalDate = CustomLocalDate(LocalDate.now())<br>        fun of(year: Int, month: Int, dayOfMonth: Int): CustomLocalDate = <br>            CustomLocalDate(LocalDate.of(year, month, dayOfMonth))<br>    }<br>}<br><br>@WritingConverter<br>class CustomLocalDateToStringConverter : Converter&lt;CustomLocalDate, String&gt; {<br>    override fun convert(source: CustomLocalDate): String = source.toString()<br>}<br>@ReadingConverter<br>class StringToCustomLocalDateConverter : Converter&lt;String, CustomLocalDate&gt; {<br>    override fun convert(source: String): CustomLocalDate = <br>        CustomLocalDate(LocalDate.parse(source, DateTimeFormatter.ofPattern(&quot;yyyy-MM-dd&quot;)))<br>}</pre><h3>사용 예시</h3><pre>data class PaymentEntity(<br>    val id: Long,<br>    val paymentDate: CustomLocalDate,<br>    val dueDate: CustomLocalDate<br>) {<br>    companion object {<br>        fun create(): PaymentEntity {<br>            val now = CustomLocalDate.now()<br>            return PaymentEntity(<br>                id = 0L,<br>                paymentDate = now,<br>                dueDate = CustomLocalDate(now.value.plusDays(30))<br>            )<br>        }<br>    }<br>}</pre><h3>이 방법의 장점</h3><ol><li><strong>Spring JDBC 우선순위 우회</strong>: CustomLocalDate는 Spring JDBC가 특별 취급하지 않는 커스텀 타입이므로 컨버터가 정상 적용됩니다.</li><li><strong>타입 안정성 보장</strong>: LocalDate와 동일한 타입 안정성을 제공하면서도 데이터베이스 저장 형식을 제어할 수 있습니다.</li><li><strong>Spring Data JDBC 호환성</strong>: Repository 패턴과 자동 매핑 기능을 그대로 사용할 수 있습니다.</li><li><strong>확장 가능성</strong>: 필요시 추가적인 비즈니스 로직이나 유틸리티 메서드를 넣을 수 있습니다.</li><li><strong>가독성 : </strong>사용자로부터 해당 부분이 컨버팅되어 저장된다는 사실을 명시적으로 알릴 수 있습니다.</li></ol><h3>실무에서 주의할 점 ⭐️</h3><h3>1. 양방향 컨버터는 반드시 쌍으로 등록</h3><pre>override fun userConverters(): MutableList&lt;Converter&lt;*, *&gt;&gt; =<br>    listOf(<br>        CustomLocalDateToStringConverter(),    // 저장용<br>        StringToCustomLocalDateConverter(),    // 조회용 - 반드시 필요!<br>    ).toMutableList()</pre><h3>2. 테스트 코드 작성</h3><pre>@Test<br>fun `커스텀 컨버터가 올바르게 동작하는지 확인`() {<br>    // given<br>    val entity = SomeEntity(customDate = CustomLocalDate(LocalDate.of(2024, 8, 1)))<br>    <br>    // when<br>    repository.save(entity)<br>    val saved = repository.findById(entity.id)<br>    <br>    // then<br>    assertThat(saved.customDate.value).isEqualTo(LocalDate.of(2024, 8, 1))<br>    <br>    // DB에서 실제 저장된 형식도 확인<br>    val rawValue = jdbcTemplate.queryForObject(<br>        &quot;SELECT date_column FROM some_table WHERE id = ?&quot;, <br>        String::class.java, <br>        entity.id<br>    )<br>    assertThat(rawValue).isEqualTo(&quot;2024-08-01&quot;)<br>}</pre><h3>3. DB 벤더별 차이점 고려</h3><p>이런 저수준 동작은 DB 벤더나 JDBC 드라이버 버전에 따라 다를 수 있습니다. 프로덕션 적용 전 충분한 테스트가 필요합니다.</p><h3>마무리</h3><p>때로는 프레임워크가 우리 대신 처리해주려다가 예상과 다른 결과가 나올 수 있습니다. 하지만 이런 경험을 통해 Spring JDBC의 내부 동작을 더 깊이 이해하게 되었습니다!</p><p>또한 Spring Data JDBC, Spring JDBC, JDBC API, JDBC 드라이버 각각의 역할과 우선순위를 이해하고 사용하면 예상치 못한 오류를 방지할 수 있을 것 같습니다.</p><p>혹시 비슷한 문제를 겪고 계시거나 궁금한 점이 있으시면 언제든 댓글로 남겨주세요! 긴 글 읽어주셔서 감사합니다.</p><p><strong>참고 자료</strong></p><ul><li><a href="https://docs.spring.io/spring-data/jdbc/docs/current/reference/html/">Spring Data JDBC Reference Documentation</a></li><li><a href="https://docs.oracle.com/en/database/oracle/oracle-database/21/jjdbc/">Oracle JDBC Developer’s Guide</a></li><li><a href="https://docs.oracle.com/javase/8/docs/api/java/sql/package-summary.html">JDBC API Documentation</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9bbe3935fb15" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/%EB%98%91%EA%B0%99%EC%9D%80-%EC%BD%94%EB%93%9C%EC%9D%B8%EB%8D%B0-%EC%99%9C-%EC%95%88-%EB%8F%BC-spring-jdbc-%EC%BB%A8%EB%B2%84%ED%84%B0-%EB%AF%B8%EA%B6%81-%ED%83%88%EC%B6%9C%EA%B8%B0-9bbe3935fb15">똑같은 코드인데 왜 안 돼? Spring JDBC 컨버터 미궁 탈출기</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[MongoDB CQRS 성능 개선기: 예상치 못한 Tomcat NDJSON 병목 해결]]></title>
            <link>https://medium.com/naverfinancial/test-1e8f7bebe35d?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/1e8f7bebe35d</guid>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[dev]]></category>
            <category><![CDATA[mongodb]]></category>
            <category><![CDATA[ndjson]]></category>
            <dc:creator><![CDATA[sungkwon ha]]></dc:creator>
            <pubDate>Thu, 31 Jul 2025 01:15:42 GMT</pubDate>
            <atom:updated>2025-07-31T01:39:06.688Z</atom:updated>
            <content:encoded><![CDATA[<h3>소개</h3><p>안녕하세요. 네이버페이 혜택&amp;정산BE 에서 네이버페이 정산 개발을 담당하고 있는 하성권 입니다.</p><p>최근 대용량 데이터의 조회 성능을 개선하기 위해 <strong>CQRS 패턴 기반의 MongoDB 시스템</strong>을 도입했습니다. 이 과정에서 예상치 못한 성능 병목 현상을 겪었고, 그 해결 과정을 공유하고자 합니다.</p><p>MongoDB와 CQRS 패턴을 적용한 이후 API 조회 속도는 기존 샤딩 DB 대비 40배 이상 향상됐습니다. 하지만, <strong>엑셀 다운로드 성능은 전혀</strong> 개선되지 않았습니다. MongoDB 튜닝도 하고, 엑셀 라이브러리도 변경해봤지만 효과가 없었습니다.</p><p>문제의 원인은 의외로 Tomcat(Spring Web Embedded)에서 Flux 리턴 타입으로 <strong>NDJSON을 스트리밍할 때, 한 줄씩 blocking 되는 구조</strong>에 있었습니다.</p><h3>1. 배경: 대형 가맹점의 고통</h3><p>네이버페이 정산 시스템은 가맹점 기반의 샤딩 DB를 사용 중에 있습니다. 성능 개선 및 스케일아웃에 유리하도록 채택한 샤딩 DB 구조였지만 샤딩 불균형 문제가 발생하고 있습니다.</p><blockquote>상위 1위 가맹점: 전체 데이터의 2%</blockquote><blockquote>상위 1~10위 가맹점 합산: 전체 데이터의 약 7%</blockquote><p>서비스가 확장되고, 쿼리가 날로 복잡해짐에 따라 이런 대형 가맹점들은 조회할 때마다 타임아웃에 시달렸습니다. 그래서 CQRS 패턴을 도입하기로 했습니다.</p><h4>1.1 CQRS 도입: 절반의 성공</h4><p>MongoDB에 미리 가공된 데이터를 저장해 join 없이 빠르게 조회되는 시스템을 구축했습니다.</p><ul><li><strong>API 성능 측정 결과</strong></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/712/1*lpN05vnxv2vhBTcacWn1MQ.png" /><figcaption>기획팀에게 성능 개선 효과 좋다고 자랑하러 가도 되겠다!!</figcaption></figure><ul><li><strong>엑셀 다운로드 성능 측정 결과</strong></li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/712/1*wkIaW3rkXIgilfIpFBt4dg.png" /><figcaption>어….?</figcaption></figure><h3>2. 원인을 찾아서</h3><p>성능 병목을 발생시키는 원인 파악을 위해서 구간별로 성능 테스트를 진행하였습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/937/1*GXC2f_OFy0JtfIQTEH4a5w.png" /><figcaption>대략적인 엑셀 파일 생성 흐름도</figcaption></figure><h4><strong>2.1. MongoDB 조회 성능</strong></h4><ul><li>readConcern 레벨 조정</li><li>projection으로 필요한 필드만 조회</li></ul><p><em>결과: 쿼리 성능 약 10% 내외의 조회 성능 개선이 있었지만 엑셀 파일 생성 성능에 영향은 없었음</em></p><h4><strong>2.2. 엑셀 라이브러리 성능</strong></h4><ul><li>POI SXSSF(현재 사용중) vs EasyExcel vs FastExcel 벤치마킹</li><li>FastExcel 도입 시 약 2배 수준의 엑셀 파일 생성 성능 개선 효과</li></ul><p><em>결과: 엑셀 파일 생성 성능은 여전히 개선되지 않음</em></p><h4><strong>2.3. 네트워크 성능</strong></h4><ul><li>엑셀 결과 파일과 비슷한 용량의 파일 전송 속도 테스트</li></ul><p><em>결과: 8만건 약 1초 내외로 전송 완료되어 네트워크는 전혀 이슈가 되지 않음</em></p><h4><strong>2.4 원인 발견: Tomcat + NDJSON 조합</strong></h4><p>남은 구간(Spring web) 에서 테스트를 하다가 이상한 점을 발견했습니다.</p><pre># JSON 형식 (일반 배열)<br>curl localhost:8080/api/excel/json<br>&gt; Speed: 37.7MB/s<br><br># NDJSON 형식 (줄바꿈으로 구분)<br>curl localhost:8080/api/excel/ndjson  <br>&gt; Speed: 3.7MB/s</pre><h3>3. 원인 분석</h3><p>NDJSON 이란? Newline Delimited JSON의 약자로 각 줄이 JSON 객체 하나를 나타내고, 각 JSON 객체는 개행 문자(\n)로 구분되어 저장되는 데이터 포맷을 의미합니다.</p><pre>// 예시<br>{&quot;name&quot;: &quot;John&quot;, &quot;age&quot;: 30}<br>{&quot;name&quot;: &quot;Jane&quot;, &quot;age&quot;: 25}<br>{&quot;name&quot;: &quot;Peter&quot;, &quot;age&quot;: 40}</pre><p>이러한 NDJSON의 특성으로 인해 spring web에서 Flux 리턴 타입의 NDJSON 응답 형식을 처리 시 아래와 같은 처리를 순서대로 하게 됩니다.</p><ol><li>한 줄 직렬화 → HttpResponse에 write</li><li>Tomcat은 write 완료까지 blocking</li><li>50만 줄 = 50만 번 blocking(사실 개행문 까지 포함하여 100만 번)</li></ol><pre>//  org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitterReturnValueHandler<br><br>private static final class DefaultSseEmitterHandler implements ResponseBodyEmitter.Handler {<br>  // sendInternal 메소드에 의해 위에서 httpResponse가 write &amp; flush가 수행됩니다.<br>  @Override<br>  public void send(Object data, @Nullable MediaType mediaType) throws IOException {<br>   sendInternal(data, mediaType);<br>   this.outputMessage.flush();<br>  }<br>}</pre><pre>// org.springframework.web.servlet.mvc.method.annotation.ResponseBodyEmitterReturnValueHandler.ReactiveTypeHandler<br><br>private static class JsonEmitterSubscriber extends AbstractEmitterSubscriber {<br><br>JsonEmitterSubscriber(<br>  ResponseBodyEmitter emitter, TaskExecutor executor) {<br>  super(emitter, executor, null);<br>}<br><br>// Ndjson 형식의 경우 JsonEmitterSubscriber 가 Flux의 item을 건별로 처리합니다.<br>// 각 item 들은 위에서 정의된 handler에 따라 json 한줄 write &amp; flush 수행 후 <br>// 개행 write &amp; flush 를 수행합니다.<br>@Override<br>protected void send(Object element) throws IOException {<br>   getEmitter().send(element, MediaType.APPLICATION_JSON);<br>   getEmitter().send(&quot;\n&quot;, MediaType.TEXT_PLAIN);<br>  }<br>}</pre><p>반면 JSON 형식으로 응답 시 하나의 배열 형태의 JSON으로 합친 후 한 번만 write &amp; flush 가 발생하여 I/O blocking 시간이 절약되기 때문에 NDJSON에 비해 10배 빠른 성능을 보여주는 것을 확인할 수 있었습니다.</p><p>I/O에 의한 성능 저하가 원인이라면, non-blocking 환경인 Netty에서는 이 부분이 문제가 되지 않을 것으로 보고 테스트를 해보았습니다. 그 결과 아래와 같이 Tomcat 대비 약 7배가량의 처리 속도를 확인할 수 있었습니다.</p><ul><li>Tomcat: 3–4MB/s</li><li>Netty: 19–20MB/s</li></ul><blockquote>이참에 netty 환경으로 전환해 볼까? 하고 살펴봤지만 하나의 기능만을 위해 너무나 변경사항이 생겼고, 그 많은 변경사항을 확인할 리소스 또한 제한적이었습니다.</blockquote><h3>4. 해결책: 버퍼링으로 극복</h3><p>Spring web에서 한 줄씩 처리하도록 Flux&lt;T&gt; 타입으로 리턴하지 않고, HttpServletResponse에서 직접 write &amp; flush 처리를 하도록 확장 함수를 구현 및 적용하였습니다.</p><pre>fun &lt;T&gt; Flux&lt;T&gt;.writeBufferedStreamResponse(<br>    response: HttpServletResponse, <br>    objectMapper: ObjectMapper<br>) {<br>    response.writer.use { writer -&gt;<br>        this.buffer(1000)  // 1000개씩 모아서<br>            .map { buffered -&gt;<br>                buffered.forEach {<br>                    writer.write(&quot;${objectMapper.writeValueAsString(it)}\n&quot;)<br>                }<br>                writer.flush()  // 한번에 flush!<br>            }<br>            .blockLast()<br>    }<br>}</pre><h4>4.1. 최종 결과</h4><p>1000개씩 모아 응답을 write &amp; flush 하도록 한 결과 드디어 기대하던 개선 효과를 볼 수 있었습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/715/1*GCWVIF4xw-Zze4Vpyz563g.png" /><figcaption>드디어 기획팀에게 진짜 성능이 개선되었다고 말할 수 있겠다…!</figcaption></figure><h3>Lesson Learned</h3><ol><li><strong>성능 문제의 원인은 예상 밖의 곳에 있을 수 있다</strong>: DB도 빠르고, 라이브러리도 빠른데 왜 느릴까? → 프레임워크 이슈일 수도있다</li><li><strong>스트리밍 처리는 프레임워크 특성을 고려해야 한다</strong>: Servlet 기반에서 Reactive 스타일 사용 시 주의</li><li><strong>구간별 측정이 중요하다</strong>: 전체가 아닌 각 구간을 측정해야 진짜 병목을 찾을 수 있다</li></ol><blockquote>이제 정말로 CQRS 도입 효과를 자랑할 수 있게 되었습니다! 🎉</blockquote><h4>참고 문헌</h4><ul><li><a href="https://github.com/spring-projects/spring-framework/blob/2e0cc63616c56d9495d23863077b6692916fd462/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ReactiveTypeHandler.java#L138-L187">NDJSON response Emitter를 결정하는 코드</a></li><li><a href="https://github.com/spring-projects/spring-framework/blob/2e0cc63616c56d9495d23863077b6692916fd462/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyEmitterReturnValueHandler.java#L293-L297">EmitterHandler가 write &amp; flush 를 수행하는 코드</a></li><li><a href="https://github.com/spring-projects/spring-framework/blob/2e0cc63616c56d9495d23863077b6692916fd462/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ReactiveTypeHandler.java#L462-L475">NDJSON의 Emitter가 실제 한줄 씩 JSON 데이터를 write 수행하는 코드</a></li><li><a href="https://github.com/spring-projects/spring-framework/blob/2e0cc63616c56d9495d23863077b6692916fd462/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/ResponseBodyEmitterReturnValueHandler.java#L179-L247">NDJSON 형식의 Flux 리턴 타입을 처리하는 전체적인 흐름 코드</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1e8f7bebe35d" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/test-1e8f7bebe35d">MongoDB CQRS 성능 개선기: 예상치 못한 Tomcat NDJSON 병목 해결</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[레거시 시스템 교체기: 실시간 트래픽 미러링을 통한 안정적 전환 사례]]></title>
            <link>https://medium.com/naverfinancial/%EB%A0%88%EA%B1%B0%EC%8B%9C-%EC%8B%9C%EC%8A%A4%ED%85%9C-%EA%B5%90%EC%B2%B4%EA%B8%B0-%EC%8B%A4%EC%8B%9C%EA%B0%84-%ED%8A%B8%EB%9E%98%ED%94%BD-%EB%AF%B8%EB%9F%AC%EB%A7%81%EC%9D%84-%ED%86%B5%ED%95%9C-%EC%95%88%EC%A0%95%EC%A0%81-%EC%A0%84%ED%99%98-%EC%82%AC%EB%A1%80-99222c7362d7?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/99222c7362d7</guid>
            <category><![CDATA[dev]]></category>
            <category><![CDATA[backend]]></category>
            <dc:creator><![CDATA[MINJUN KWEON]]></dc:creator>
            <pubDate>Mon, 30 Jun 2025 02:04:26 GMT</pubDate>
            <atom:updated>2025-06-30T02:04:26.104Z</atom:updated>
            <content:encoded><![CDATA[<p>안녕하세요. 네이버페이 신용서비스BE 개발자 권민준입니다.</p><p>이번 글에서는 네이버페이 서비스 중 하나인 ‘<strong>신용점수 조회</strong>’ 서비스의 레거시 시스템을 새로운 시스템으로 전환하는 과정에 대해서 소개하고자 합니다. <br>이 과정에서 저희 팀은 <strong>Spring WebFlux</strong>에서 <strong>Spring WebMVC</strong>로의 전환을 시도했으며, 이를 위해 <strong>트래픽 미러링</strong> 기법을 활용하여 신규 시스템의 안정성을 검증했습니다. 전환 배경, 기술 스택 선택 이유, 트래픽 미러링 구현 방법, 그리고 전환 과정에서 얻은 교훈 등을 공유하려고 합니다.</p><h3>기술 스택 이전 배경 및 마이그레이션 필요성</h3><p>‘신용점수 조회’ 서비스는 초기부터 Kotlin과 Spring WebFlux 기반으로 개발되어 운영되어 왔습니다. WebFlux는 비동기 스트림 기반 아키텍처로 높은 동시성 처리에 적합하지만, 운영 경험이 쌓이면서 점점 더 많은 문제가 드러났습니다. 운영하는 시간이 지날수록 Reactive 기반의 코드가 점차 복잡해지고, 비즈니스 로직을 구현하는 데 필요한 보일러플레이트 코드가 많아지면서 유지보수가 어려워졌습니다.</p><p>WebFlux는 장점도 많지만, 다음과 같은 문제로 인해 실제 운영에서는 오히려 비효율을 초래했습니다:</p><ol><li>팀원들이 함수형 리액티브 프로그래밍에 익숙하지 않아 <strong>러닝 커브가 높음</strong></li><li><strong>같은 기능을 구현하더라도 표현 방식이 다양</strong>하여 코드 스타일이 통일되지 않음</li><li>Kotlin의 null-safety와 WebFlux 리액티브 타입(Flux/Mono)의 <strong>패러다임 충돌</strong></li></ol><p>예를 들어, 다음과 같이 동일한 기능을 각자 다르게 구현할 수 있었습니다:</p><pre>// 방식 1: flatMap + map 체인<br>userRepository.findById(id)<br>    .flatMap { user -&gt;<br>        Mono.just(UserDto.from(user))<br>    }<br><br>// 방식 2: switchIfEmpty 사용<br>userRepository.findById(id)<br>    .switchIfEmpty(Mono.error(NotFoundException()))<br>    .map { UserDto.from(it) }</pre><p>또한, Mono&lt;T&gt;는 null 값을 담을 수 없기 때문에 다음과 같은 코드 보일러플레이트가 자주 생겼습니다:</p><pre>val name = dto.name ?: &quot;&quot; // 빈 String을 null 대신 사용<br>Mono.just(name) // nullable 타입을 강제로 non-null로 변환하여 처리</pre><p>이러한 경험을 통해 <strong>생산성 저하와 코드 품질 저하</strong>를 체감하게 되었고, 팀 내 회의를 통해 단순히 스키마만 바꾸는 것이 아니라 <strong>시스템 전반을 보다 유지보수하기 쉬운 구조로 개선하자</strong>는 결론에 도달했습니다.<br>그렇게 해서 <strong>Spring WebMVC 기반의 신규 시스템 구축</strong>이 시작되었고, 기존 시스템과 병행 운영을 위한 전략도 함께 수립되었습니다.</p><p>그리고 또한, 도메인 확장과 기능 추가에 따라 기존 MongoDB 컬렉션 구조가 한계를 드러냈습니다. 서비스를 운영하는 동안 점점 요구사항이 복잡해지고 변경되면서, 기존 데이터베이스 스키마로는 이를 수용하기 어려운 상황이 발생했고, 이에 따라 스키마를 대폭 수정해야 하는 <strong>신규 스키마로의 전환 필요성</strong>이 발생했습니다.</p><p>다만 운영 중인 데이터를 한 번에 옮기는 것은 리스크가 컸기 때문에, <strong>데이터 마이그레이션을 동반한 신규 시스템 구축</strong>이 필요했습니다.</p><h3>WebMVC 선택 이유와 기대 성능</h3><p>Spring WebMVC는 전통적인 동기식 요청-응답 기반이며, 대부분의 개발자에게 익숙하고 직관적인 프로그래밍 모델을 제공합니다. 이러한 특성은 팀의 개발 속도와 코드 일관성을 높이는 데 크게 기여했습니다. 더불어 JVM 생태계에서는 Java 21의 <strong>Virtual Threads</strong> 도입 등으로 인해 동기 코드에서도 높은 동시성 처리 성능을 기대할 수 있게 되었습니다.</p><p>기술 스택 전환을 논의하던 시점에, 저희는 <strong>Kotlin Reactor Plugin</strong>을 도입하는 방안도 고려했습니다.</p><p>이 플러그인은 Kotlin에서 Reactor 타입(Flux, Mono 등)을 더 자연스럽게 사용할 수 있도록 DSL 및 확장 기능을 제공하여, 코드의 간결성과 가독성을 어느 정도 높여주는 효과가 있습니다. 예를 들어, awaitSingle() 등의 suspend 함수 지원을 통해 코루틴처럼 비동기 흐름을 구성할 수 있고, Kotlin 스타일에 맞는 체이닝 문법이 가능해집니다.</p><p>하지만 실제로는 다음과 같은 단점들도 존재했습니다:</p><ol><li>플러그인으로 해결할 수 있는 영역이 제한적이고, <strong>기존 복잡한 리액티브 흐름 자체가 단순해지는 것은 아님</strong></li><li>팀원 중 일부가 플러그인을 활용하지 않고 기존 방식대로 Reactor 스타일로 구현할 가능성도 존재하여, 오히려 <strong>코드 일관성이 저하되는 리스크가 여전히 존재함</strong></li><li>팀 전체가 해당 플러그인에 익숙해져야 하며, 신규 입사자의 온보딩 속도에 영향을 줄 수 있음</li></ol><p>결국 Kotlin Reactor Plugin은 기술적으로 유의미한 개선점을 제공하긴 하지만, 본질적인 유지보수성과 코드 일관성 문제를 해결하지는 못한다고 판단했습니다. 대신, Spring WebMVC는 <strong>thread-per-request 모델이지만 직관적인 흐름</strong>을 가지며, 리액티브 흐름에서 겪던 복잡성과 불확실성을 제거하는 효과가 있었습니다.</p><p>과거에는 WebMVC와 같은 thread-per-request 모델이 동시성 처리 측면에서 불리하다는 인식이 있었으나, 최신 JDK의 발전은 이러한 경계를 허물고 있습니다. 실제로 Java 21의 가상 스레드는 수십만 개의 동시 처리를 가능케 하며, 개발자에게 친숙한 코드 스타일을 유지하면서도 고성능을 실현할 수 있습니다.</p><figure><img alt="최근 2개월 TPS 분석" src="https://cdn-images-1.medium.com/max/1024/1*rk9jRXzsc9erLoPf7qXXxQ.png" /></figure><p>저희는 최근 2개월간의 실제 트래픽 로그를 기반으로 TPS 분석을 수행했고, 그 결과 Spring Boot 3 + JDK 17 조합만으로도 충분히 대응 가능하다는 확신을 얻었습니다. 필요 시 가상 스레드 도입이나 코루틴 기반 비동기 처리로 확장 가능한 구조를 설계하여, 추후 트래픽 증가에도 유연하게 대응할 수 있도록 준비했습니다.</p><h3>민감한 서비스의 API 호환성 확보</h3><p>신용점수 조회는 금융 서비스의 핵심 기능 중 하나로, <strong>정확성</strong>과 <strong>안정성</strong>이 최우선입니다. 단 하나의 오류도 허용될 수 없는 영역이기에, 시스템 전환 시 기존 API와 응답 스펙을 100% 동일하게 유지하는 것을 최우선 목표로 삼았습니다.</p><p>이를 위해 신규 시스템은 레거시 동작을 철저히 분석하여 완전히 동일한 방식으로 구현되었고, 일부는 잠재적인 버그까지도 의도적으로 동일하게 재현했습니다. 또한 요청별 응답을 자동 비교하는 미들웨어를 도입하여 기능 동작의 정합성을 지속적으로 확인했습니다.</p><p><strong>신용점수 조회</strong> 서비스는 결과의 정확성과 안정성이 매우 중요한 도메인입니다. 조회 결과가 잘못되거나 서비스가 중단될 경우 치명적인 문제를 일으킬 수 있으므로, 시스템 전환 시 기존 API와 응답 호환성을 100% 유지하는 것이 <strong>절대적인 목표</strong>였습니다. 새로운 기술 스택으로 교체하더라도 기능은 이전과 완벽히 동일하게 동작해야 하고, 외부에 제공하는 API 스펙(요청/응답 형식, 값의 의미 등)도 바뀌어서는 안 되었습니다.</p><p>이를 위해 기존 시스템의 모든 동작을 면밀히 분석하여 신규 시스템에 동일하게 구현했고, 심지어 잠재적인 버그마저도 의도적으로 동일하게 재현할 정도로 신중을 기했습니다.</p><p>또한 서비스 중단 없이 전환하기 위해 <strong>무중단 배포 전략</strong> 이 필요했습니다. 흔히 사용하는 블루-그린 배포나 점진적 롤아웃도 고려해볼 수 있었지만, 저희는 한 걸음 더 나아가 기존 시스템과 신규 시스템을 한동안 동시에 운영하면서 검증하는 접근을 선택했습니다.</p><p>그렇게 하면 신규 시스템이 실서비스 트래픽에서 어떻게 동작하는지 충분히 관찰하고 문제를 발견해도, 사용자 영향 없이 수정할 수 있기 때문입니다. 핵심은 사용자에게는 여전히 기존 시스템이 응답을 주는 상태를 유지하면서, 백엔드 내부적으로 신규 시스템을 실시간으로 시험하는 것이었습니다. 이 조건을 모두 만족하기 위해 여러 대안을 검토하게 되었습니다.</p><h3>트래픽 미러링 도입 배경 및 대안 비교</h3><p>전환 과정에서 신규 시스템을 실제 트래픽에 노출시키지 않고도 검증할 수 있는 방법이 필요했습니다. 이에 따라 다음과 같은 대안들을 고려했습니다:</p><ol><li><strong>Application Layer 복제 방식<br></strong>코드 내부에서 트래픽을 이중 처리하도록 구현하는 방식입니다. 각 요청마다 비즈니스 로직을 두 번 실행해야 하므로 서비스 코드가 복잡해지고, <strong>운영 중인 애플리케이션의 안정성에도 영향을 줄 수 있습니다.</strong></li><li><strong>메시지 큐 기반 테스트 환경 구성<br></strong>실시간 트래픽을 Kafka 등 외부 큐에 저장하고, 별도의 테스트 환경에서 리플레이하여 검증하는 방식입니다. 테스트 결과의 정확도는 높지만, 큐 시스템 구축, 메시지 저장 및 재처리 로직 구현 등 테스트 환경을 구성하기 위한 인프라 비용과 유지비용이 상당히 큽니다. 또한 로그 처리와 환경 동기화가 필요하여 검증 체계를 유지하는 데 지속적인 리소스 투입이 요구됩니다. 이러한 점에서 단기적인 검증에는 부적합하거나 투자 대비 효율성이 낮을 수 있습니다.</li><li><strong>트래픽 미러링 방식<br></strong>프론트 프록시(Nginx 등)에서 클라이언트 요청을 실시간으로 복제하여 기존 시스템과 신규 시스템에 동시에 전달하는 방식입니다. 사용자에게는 오직 레거시 시스템의 응답만 전달되기 때문에 안전하게 실서비스 트래픽 기반으로 신규 시스템을 테스트할 수 있습니다. 장점으로는 설정만으로 손쉽게 도입 가능하며, 실시간 비교가 가능하다는 점이 있습니다. 반면, 복제 요청에 대한 처리 결과는 사용자에게 전달되지 않기 때문에, 검증용 비교 로직이나 로그 수집 시스템을 별도로 구축해야 하는 부담이 있습니다. 또한 신규 시스템이 처리에 실패하거나 느린 응답을 보내더라도, 이를 클라이언트가 인지하지 못하므로 검증의 완전성을 위해 별도의 모니터링 체계가 반드시 필요합니다.</li></ol><p>다음은 위 세 가지 대안에 대한 요약 비교표입니다:</p><figure><img alt="대안 비교 요약" src="https://cdn-images-1.medium.com/max/1024/1*0G_kCf1S-fmeLZ2DTIM39w.png" /></figure><p>이러한 여러 옵션 중에서 가장 현실적이고 운영에 부담을 주지 않는 방안으로 <strong>Nginx 기반의 트래픽 미러링</strong>을 채택하게 되었습니다.</p><h3>트래픽 미러링 구현</h3><p><strong>트래픽 미러링</strong>(일명 Shadow Testing)은 프로덕션의 실제 트래픽을 복제하여 새로운 시스템에서 동시에 처리해보는 기법입니다. 이를 통해 사용자에게 영향을 주지 않고도 새로운 버전의 시스템이 실제 트래픽에서 제대로 동작하는지 검증할 수 있습니다.</p><p>저희는 Nginx의 ngx_http_mirror_module을 활용하여 이 기능을 구현했습니다. 구체적으로, <strong>클라이언트의 요청을 레거시 서버로 전달함과 동시에 동일한 요청을 신규 서버로 복제하도록</strong> Nginx를 설정했습니다. 클라이언트는 항상 <strong>레거시 서버로부터 온 응답만을 받기 때문에</strong> 전환 과정에서 서비스 동작에 변화가 없으며, 복제된 요청에 대한 신규 서버의 응답은 <strong>사용자에게 절대로 전달되지 않습니다.</strong></p><p>대신, 신규 서버의 응답은 별도로 <strong>로그나 모니터링 시스템을 통해 수집하여</strong> 기존 서버 응답과 자동으로 비교되었습니다. 이러한 비교 도구를 통해 두 시스템의 응답 값, 상태 코드, 응답 시간 등을 대조했고, 만약 미세한 차이라도 발견되면 원인을 분석해 신규 시스템을 수정함으로써 점진적으로 완성도를 높였습니다.</p><p>이를 통해 다음과 같은 이점을 얻었습니다:</p><ol><li>신규 시스템의 <strong>실서비스 환경 테스트</strong> 가능</li><li>사용자에게 영향 없이 <strong>정확도 및 응답 비교 자동화</strong></li><li><strong>시간 지연 없이 실시간 응답 로깅 가능</strong></li></ol><h3>Nginx 미러링 설정</h3><p>Nginx 설정에서 mirror 디렉티브를 사용하면 지정된 위치로 <strong>서브요청(Sub-request)</strong>을 보내 트래픽을 복사할 수 있습니다. 서브요청에 대한 응답은 기본적으로 <strong>폐기되며</strong>, 원 요청의 응답 처리 흐름에는 영향을 주지 않습니다. 저희는 다음과 같이 Nginx를 구성했습니다: Nginx에 <strong>primary 업스트림</strong>(레거시 서비스)과 <strong>mirror 업스트림</strong>(신규 서비스)을 정의하고, 기존 요청 경로에 mirror 디렉티브를 추가합니다.</p><pre># 레거시와 신규 서비스 Upstream 설정<br>upstream legacy_backend {<br>    server legacy.api.internal:8080;<br>}<br>upstream new_backend {<br>    server new.api.internal:8081;<br>}<br><br>server {<br>    listen 80;<br>    server_name api.myservice.com;<br><br>    location /api/credit {<br>        mirror /mirror_request;<br>        mirror_request_body on;               # POST Body도 복제<br>        proxy_pass http://legacy_backend;     # 레거시 서비스로 전달<br>    }<br><br>    location = /mirror_request {<br>        internal;<br>        proxy_pass http://new_backend$request_uri;  # 신규 서비스로 전달<br>        proxy_set_header Host $host;<br>        proxy_set_header X-Request-ID $request_id;  # 요청 ID 헤더 주입 (비교용)<br>        proxy_connect_timeout 1ms;<br>        proxy_read_timeout 1ms;<br>    }<br>}</pre><p>위 설정에서 location /api/credit는 클라이언트의 실제 요청을 받는 예시 엔드포인트입니다. 이 위치에 mirror /mirror_request 지시어를 추가하여 동일한 요청을 /mirror_request 경로로 <strong>내부 복제하도록</strong> 했습니다. 그 다음 proxy_pass http://legacy_backend를 통해 원 요청은 기존 레거시 서버로 전달합니다.</p><p>location = /mirror_request 블록은 <strong>미러된 요청을 처리하기 위한 내부 엔드포인트입니다.</strong> internal로 지정하여 외부 클라이언트가 직접 이 경로를 호출하지 못하게 했고, proxy_pass http://new_backend$request_uri를 통해 복제된 요청을 신규 서버로 전달합니다. 이때 $request_uri를 붙여 원본 요청의 경로와 쿼리 파라미터를 그대로 전달하도록 했습니다. (mirror_request_body on 지시어를 사용하면 POST 본문도 함께 복제할 수 있습니다.)</p><p>여기서 핵심은 <strong>타임아웃</strong> 설정입니다. 만약 신규 서버가 지연되거나 응답을 보내지 못하면, Nginx가 그 응답을 기다리느라 원 요청 처리까지 지연될 수 있습니다. 이를 방지하기 위해 proxy_connect_timeout과 proxy_read_timeout을 아주 짧게 (저희의 경우 1ms) 설정했습니다. 이렇게 하면 Nginx는 <strong>미러 요청의 응답을 사실상 기다리지 않고 바로 연결을 종료합니다.</strong></p><p>설정하지 않으면 <strong>기본값으로 60초</strong>로 설정이 되는데, 저희는 안전을 위해 1ms로 설정함으로써 미러 요청으로 인해 본 요청에 <strong>추가 지연이 발생하지 않도록</strong> 했습니다. 결과적으로 레거시 경로의 응답 속도와 안정성에 영향을 주지 않고도, 신규 서버에 동일한 트래픽을 가하며 테스트할 수 있었습니다.</p><h3>미러링 아키텍처 및 동작 흐름</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CdLnz1GqyUEHccd-S76Kzw.png" /></figure><p>위 그림1은 미러링을 도입하기 이전, <strong>기존 시스템만으로 동작하던 서비스 구조</strong>를 나타낸 것입니다. 사용자가 네이버페이 앱을 통해 HTTP 요청을 보내면 Nginx가 이를 받아 레거시 서버(<strong>기존 Backend</strong>)로 프록시합니다. 레거시 서버는 요청을 처리한 후 응답을 Nginx에 보내고, Nginx는 그대로 해당 응답을 클라이언트에게 전달합니다. 이 전통적인 구조에서는 모든 트래픽이 하나의 백엔드 시스템으로만 향하기 때문에 구조가 단순합니다. 그러나 신규 시스템으로 전환하기 위해서는 이 흐름을 변경하여 한 요청이 두 개의 백엔드로 동시에 전달되도록 만들어야 했습니다.</p><p>그림 2는 <strong>트래픽 미러링을 구성한 이후의 아키텍처</strong> 다이어그램입니다. 사용자의 단일 요청이 Nginx에 도달하면, Nginx는 주 요청으로서 레거시 서버에 포워딩하는 한편, 서브 요청으로 <strong>신규 서버에도</strong> 동일한 요청을 전달합니다. 레거시 서버는 예전과 동일하게 응답을 처리하여 사용자에게 반환하고, <strong>사용자는 전혀 달라진 것을 느낄 수 없습니다.</strong> 한편 신규 서버도 동일한 작업을 수행하지만 그 응답은 사용자에게 가지 않고 Nginx 단계에서 버려집니다.</p><p>대신 저희는 신규 서버의 응답을 로그로 기록하거나 별도의 비교 모듈(<strong>비교검증 Middleware</strong>)에 전송하여 레거시 응답과 <strong>1:1로 자동 비교했습니다.</strong> 이 비교 모듈은 요청 식별자별로 두 시스템의 응답 데이터를 대조하여, JSON 필드 값부터 응답 코드, 처리 시간까지 검증했습니다. 만약 두 응답 간에 차이가 발견되면 알람을 보내거나 로그로 남겨 개발자가 즉시 인지하도록 했습니다. 이러한 트래픽 미러링 테스트 방식을 통해 수백만 건의 실제 요청에 대한 신규 시스템의 동작을 검증했고, 사전에 발견되지 못했던 코너 케이스의 이슈들도 다수 발견하여 고칠 수 있었습니다.</p><h3>유지보수성 개선 성과 분석</h3><p>효과를 보다 객관적으로 파악하기 위해 코드 복잡도와 인지 난이도에 대한 정적 분석 지표를 활용했습니다. 기존 WebFlux 기반 시스템과 Spring WebMVC 기반 신규 시스템을 대상으로 각각 <a href="https://detekt.dev/">Detekt</a> 도구를 통해 <a href="https://en.wikipedia.org/wiki/Cyclomatic_complexity"><strong>순환 복잡도(MCC)</strong></a> 및 <a href="https://detekt.dev/docs/rules/complexity/"><strong>인지 복잡도(Cognitive Complexity)</strong></a> 를 측정한 결과는 다음과 같습니다:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/623/1*1vOewRPjbA0aPlfJ0Risow.png" /></figure><figure><img alt="Detekt 분석결과 요약" src="https://cdn-images-1.medium.com/max/954/1*Ib4idBZOgPNovob7-JPb_g.png" /></figure><h3>주요 해석 및 평가</h3><ol><li><strong>전체 MCC가 약 70% 감소<br></strong>복잡한 리액티브 흐름과 분기 로직을 단순화하여 코드 구조가 보다 명확해졌음을 의미합니다.</li><li><strong>Cognitive Complexity가 약 87% 감소<br></strong>실제 개발자 입장에서 코드의 이해 및 유지보수 난이도가 현저히 개선되었음을 보여줍니다.</li><li><strong>코드량 대비 복잡도 비율 개선<br></strong>단순히 코드 라인이 줄었기 때문이 아니라, 같은 기능을 더 명확하고 간결하게 구현한 결과로 해석할 수 있습니다.</li></ol><p>따라서 이 수치의 변화는 단순한 양적 축소가 아니라, <strong>설계의 단순화와 흐름의 명확화로 인한 구조적 개선의 결과</strong>로 평가할 수 있습니다. 단순히 코드 라인이 줄어서가 아니라, <strong>설계의 단순화와 흐름의 명확화로 인한 구조적 개선</strong>이라는 점에서 의미 있는 변화라고 평가할 수 있습니다.</p><h3>전환 과정을 돌아보며</h3><p>이번 프로젝트에서 얻은 주요 교훈은 다음과 같습니다:</p><ol><li>트래픽 미러링을 통해 실서비스 환경에서도 안정적으로 신규 시스템을 검증하고, 단계적으로 전환함으로써 위험을 최소화했습니다.</li><li>응답 자동 비교 도구를 도입해 숨은 버그나 미세한 차이를 조기에 탐지할 수 있었습니다.</li><li>장애 발생 시 레거시 시스템으로 즉시 트래픽을 전환할 수 있는 시나리오를 사전에 마련해 사용자 영향을 최소화했습니다.</li><li><strong>트렌드보다 팀 역량과 서비스 특성에 맞는 기술을 선택하는 것</strong>이 생산성과 안정성에 긍정적임을 확인했습니다.</li></ol><p>무엇보다도 이번 전환을 통해 <strong>팀원들의 개발 효율성</strong>이 체감될 정도로 향상되었고, 코드의 가독성과 일관성도 큰 폭으로 개선되었습니다. 향후 시스템 확장을 고려한 설계를 바탕으로, 저희 팀은 유연하면서도 안정적인 기술 선택을 지속해 나갈 예정입니다. 이를 통해 사용자 경험을 해치지 않으면서도 빠르고 정확한 서비스 제공을 이어나갈 수 있을 것입니다.</p><p>긴 글 읽어주셔서 감사합니다.</p><h4>참고자료</h4><ul><li>ngx_http_mirror_module — NGINX <br><a href="https://nginx.org/en/docs/http/ngx_http_mirror_module.html">https://nginx.org/en/docs/http/ngx_http_mirror_module.html</a></li><li>Reactor WebFlux vs Virtual Threads — GeeksforGeeks<br><a href="https://www.geeksforgeeks.org/reactor-webflux-vs-virtual-threads/">https://www.geeksforgeeks.org/reactor-webflux-vs-virtual-threads/</a></li><li>Do Java 21 virtual threads address the main reason to switch to reactive single-thread frameworks? — Stack Overflow <br><a href="https://stackoverflow.com/questions/78318131/do-java-21-virtual-threads-address-the-main-reason-to-switch-to-reactivesingle">https://stackoverflow.com/questions/78318131/do-java-21-virtual-threads-address-the-main-reason-to-switch-to-reactivesingle</a></li><li>How to make Nginx mirror module not wait for response — Stack Overflow<br><a href="https://stackoverflow.com/questions/51644141/how-to-make-nginx-mirror-module-not-wait-for-response">https://stackoverflow.com/questions/51644141/how-to-make-nginx-mirror-module-not-wait-for-response</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=99222c7362d7" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/%EB%A0%88%EA%B1%B0%EC%8B%9C-%EC%8B%9C%EC%8A%A4%ED%85%9C-%EA%B5%90%EC%B2%B4%EA%B8%B0-%EC%8B%A4%EC%8B%9C%EA%B0%84-%ED%8A%B8%EB%9E%98%ED%94%BD-%EB%AF%B8%EB%9F%AC%EB%A7%81%EC%9D%84-%ED%86%B5%ED%95%9C-%EC%95%88%EC%A0%95%EC%A0%81-%EC%A0%84%ED%99%98-%EC%82%AC%EB%A1%80-99222c7362d7">레거시 시스템 교체기: 실시간 트래픽 미러링을 통한 안정적 전환 사례</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[도메인 Error를 다루는 고민과 Arrow의 Either]]></title>
            <link>https://medium.com/naverfinancial/%EB%8F%84%EB%A9%94%EC%9D%B8-error%EB%A5%BC-%EB%8B%A4%EB%A3%A8%EB%8A%94-%EA%B3%A0%EB%AF%BC%EA%B3%BC-arrow%EC%9D%98-either-2a5d425e56f1?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/2a5d425e56f1</guid>
            <category><![CDATA[functional-programming]]></category>
            <category><![CDATA[kotlin]]></category>
            <category><![CDATA[arrow]]></category>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[dev]]></category>
            <dc:creator><![CDATA[NAMWON CHO]]></dc:creator>
            <pubDate>Tue, 24 Jun 2025 10:09:27 GMT</pubDate>
            <atom:updated>2025-06-24T10:09:27.736Z</atom:updated>
            <content:encoded><![CDATA[<h3>소개</h3><p>안녕하세요. 결제형 BE팀의 조남원입니다. 저희 팀은 복잡한 결제 도메인의 안정성과 코드 명확성을 높이기 위해 끊임없이 고민하고 있습니다. 이 글에서는 도메인 에러를 다루기 위해 어떤 고민을 했고, Arrow 를 도입해서 어떻게 효과적으로 처리하고 있는지, 그 적용 과정과 경험을 공유하고자 합니다.</p><h3>배경</h3><p>저희 팀은 기존의 old protocol 기반 결제 로직을 현대적인 HTTP API 기반의 신규 시스템으로 전환하는 프로젝트를 진행했습니다.</p><p>기존 시스템은 Java 8과 Spring 4 프레임워크를 기반으로 하고 있었으며, 다수의 EOL(End-Of-Life)된 라이브러리들이 복잡하게 얽혀 있어 버전 업그레이드나 기능 확장이 매우 어려운 상황이었습니다.</p><p>내부 논의를 거쳐, 10여 년간 결제 도메인을 지탱해 온 기존 코드를 정리하고 Kotlin과 Spring Boot를 기반으로 한 새로운 결제 시스템을 개발하기로 결정했습니다.</p><h3>도메인 Error, 어떻게 다뤄야 할까요?</h3><p>새로운 시스템을 설계하면서 가장 큰 고민 중 하나는 ‘도메인 로직에서 발생하는 다양한 상황, 특히 오류 상황을 어떻게 명확하고 일관되게 코드로 표현할 것인가?’였습니다.</p><p>기존 시스템에서는 다음과 같은 어려움이 있었습니다:</p><ul><li>도메인 예외가 발생 조건과 처리하는 위치가 구현마다 달라 예외의 근본 원인을 추적하기 어려웠습니다.</li><li>서비스가 성장하며 예외 클래스가 계속 늘어났고, 전체적인 오류 처리 흐름을 파악하기 쉽지 않았습니다.</li></ul><p>저희는 이 문제들을 해결하기 위해, 함수의 결과를 값(Value)으로 다루는 방식을 고민했고, 그 첫 번째 시도로 Kotlin의 Sealed Class를 적극적으로 활용해 보았습니다.</p><h3>Sealed Class로 에러 핸들링 개선하기</h3><p>Kotlin의 sealed class는 타입이 가질 수 있는 여러 상태를 명확하게 정의하고, 컴파일 시점에 하위 클래스의 종류를 제한하여 예측하지 못한 상황 발생 가능성을 크게 줄여주는 강력한 기능입니다.</p><p>실제 ‘결제 승인 API’ 응답을 BillingPaymentResult라는 sealed class로 모델링했습니다. 결제 승인 API는 다양한 resultCode를 반환하는데, 저희 도메인에서는 이 중 특정 케이스들에만 관심을 가집니다.</p><pre>// API 응답 결과를 표현하는 Sealed Class<br>sealed class BillingPaymentResult {<br>    data class Billed(val value: BilledPaymentInfo) : BillingPaymentResult()<br>    data class PgFailed(val resultCode: String, ...) : BillingPaymentResult()<br>    data class BillingFailed(val resultCode: String, ...) : BillingPaymentResult()<br>    // ... 기타 실패 케이스<br>}<br><br>// API 호출 결과를 BillingPaymentResult로 변환<br>fun executeBillingPayment(command: PaymentCommand): BillingPaymentResult {<br>    return kotlin.runCatching {<br>        <br>        val responseEntity = this.client.billingPayment(command.toRequestOrThrow())<br>        <br>        responseEntity.body?.let { body -&gt;<br>            when (body.resultCode) {<br>              // resultCode: &quot;100&quot; 인 경우는 정상 케이스<br>                &quot;100&quot; -&gt; BillingPaymentResult.Billed(value = body.toDomainOrThrow())<br>                // resultCode: &quot;2xx&quot; 인 경우는 비정상 케이스<br>                &quot;200&quot;, &quot;201&quot;, &quot;202&quot; -&gt; BillingPaymentResult.InvalidCommand(exception = IllegalArgumentException(body.resultMessage), resultMessage = body.resultMessage)<br>                // ... 그외 API 결과 코드에 따른 분기 처리 ...<br>            }<br>        } ?: BillingPaymentResult.Failure(IllegalStateException(&quot;[BILLING_SERVICE_EXCEPTION] 2xx status, but empty response body&quot;))<br>    }.getOrElse {<br>        when (it) {<br>            is ResourceAccessException, <br>            is SocketTimeoutException -&gt;<br>                BillingPaymentResult.BillingRemoteError(ClientException(it), it.message ?: &quot;[BILLING_SERVICE_EXCEPTION] Network exception&quot;)<br>            else -&gt; BillingPaymentResult.Failure(Exception(it))<br>        }<br>    }<br>}</pre><p>이처럼 sealed class로 API 응답(성공 또는 다양한 오류 케이스)을 정의하면, when 표현식과 함께 사용할 때 각 케이스별 분기 처리를 직관적이고 가독성 좋게 구현할 수 있습니다.</p><pre>when (val result = billingService.executeBillingPayment(command)) {<br>    is BillingPaymentResult.Billed -&gt; savePaymentInfo(result)<br>    is BillingPaymentResult.PgFailed -&gt; responsePgPaymentFail(result.pgCode, result.pgType, result.pgMessage)<br>    is BillingPaymentResult.BillingFailed -&gt; responsePaymentFail(result.resultMessage)<br>    is BillingPaymentResult.BillingRemoteError -&gt; rollbackPaymentTransaction(command.payId)<br>    is BillingPaymentResult.Failure -&gt; responseUnexpectedFail(result.exception)<br>}</pre><p>Sealed class를 활용하여 얻을 수 있었던 주요 장점은 다음과 같습니다.</p><p><strong>1. 예외 분기의 예측 가능성 향상</strong></p><p>API가 반환하는 수많은 응답 중, 우리 도메인에서 <strong>의미 있는 상태들만 선별하여 </strong><strong>sealed class의 하위 타입으로 명시</strong>할 수 있습니다. 이를 통해 해당 API의 결과를 다루는 처리 로직을 한눈에 파악하고 예측 가능성을 높일 수 있습니다.</p><p><strong>2. 통제된 확장성 제공</strong></p><p>API 명세 변경으로 새로운 오류 타입이 추가되어도, sealed class에 하위 타입을 추가하면 <strong>컴파일러가 </strong><strong>when 표현식에서 이 새로운 타입을 처리하고 있는지 검사</strong>합니다. 덕분에 누락 없이 안전하게 시스템을 확장할 수 있습니다.</p><p>예를 들어, 빌링 결제 응답으로 2xx(parameter 누락, parameter 형식 오류, parameter 조건 오류) resultCode 인 경우는 badRequest 응답을 내려야하는 요구사항이 추가된다면, 다음과 같이 작업할 수 있습니다.</p><pre>sealed class BillingPaymentResult {<br><br>    ...<br>    // 예외 Case 추가<br>    data class InvalidCommand(<br>        val exception: Exception,<br>        val resultMessage: String<br>    ) : BillingPaymentResult()<br>    <br>}<br><br><br>when (val result = billingService.executeBillingPayment(command)) {<br>  ...<br>  <br>  // 유효성 검증 실패 Case 추가<br>  is BillingPaymentResult.InvalidCommand -&gt; badRequest(command, result)<br>}</pre><p><strong>3. 모든 케이스의 분기 처리 강제</strong></p><p>when 표현식 사용 시 모든 가능한 상태(성공 및 정의된 모든 예외)의 처리를 컴파일 시점에서 보장받을 수 있습니다. 이는 기존 중첩된 try-catch 방식의 추적 어려움을 보완하고, 코드의 안정성과 예측 가능성을 크게 향상시킵니다.</p><h3>그럼에도 불편한 점이..</h3><p>하지만 sealed class는 만능이 아니었고, 사용하면서 두 가지 큰 불편함을 느끼게 되었습니다.</p><p><strong>1. 반복적인 </strong><strong>sealed class 선언과 분기</strong></p><p>첫 번째 불편함은 <strong>반복적인 코드 작성</strong>이었습니다. 이는 두 가지 측면에서 나타났습니다.</p><p>먼저, 결과 타입을 표현하기 위한 sealed class 자체의 선언이 반복되었습니다. PaymentResult, UserInfoResult 등 각 비즈니스 로직마다 성공과 실패 케이스를 담는 sealed class를 매번 새로 정의하는 것은, 특히 간단한 분기만 필요한 경우에도 비효율적인 작업이었습니다.</p><p>두 번째는, 이렇게 만든 Result 타입에서 <strong>성공 값을 안전하게 추출하는 과정</strong> 또한 번거롭다는 점이었습니다. 성공 값을 얻으려면 기본적으로 when 분기문을 사용해야 했는데, 이 반복을 피하고자 getOrNull(), getOrThrow()와 같은 셔터컷(shortcut) 함수들을 모든 sealed class에 추가하기 시작했습니다. 결국 이 <strong>헬퍼 함수들마저 또 다른 종류의 반복적인 코드</strong>가 되었습니다.</p><p>실제 사용자 조회 로직에 사용했던 UserInfoResult 예시를 보면 이 문제가 더 명확히 드러납니다.</p><pre>sealed interface UserInfoResult {<br>    data class Success(val value: UserInfo): UserInfoResult<br>    data object NotFound: UserInfoResult<br>    // ...<br><br>    // 함수 추가: 성공 값을 꺼내기 위해 매번 유사한 코드를 작성하게 됨<br>    fun getOrNull(): UserInfo? {<br>        return when (this) {<br>            is Success -&gt; value<br>           else -&gt; null<br>        }<br>    }<br>    <br>  fun getOrThrow(): UserInfo {<br>        return when (this) {<br>            is Success -&gt; value<br>            is NotFound -&gt; throw UserInfoNotFoundException()<br>            //...<br>        }<br>    }<br>}</pre><p><strong>2. 중첩된 </strong><strong>sealed class 형태의 코드</strong></p><p>sealed class를 사용한 함수들을 연속적으로 호출해야 할 때, 문제는 더욱 심각해집니다. 각 함수의 성공 결과 안에서 다음 함수를 호출하는 구조는 코드의 깊이를 감당할 수 없게 만들고, 가독성을 크게 해칩니다.</p><p>아래의 예를 들어보겠습니다.</p><ul><li>예시 요구 사항</li></ul><pre>포인트 결제시, 포인트 금액이 부족하면 1)포인트 충전을 하고, 2)결제 승인를 진행한다.</pre><p>이를 위해 포인트 충전 에 대해서 결과값인 sealed class(Result) 형식으로 추가후, 포인트 결제 흐름을 구현했습니다.</p><pre>fun executePaymentApproval(parameters: PayApprovalParams): PayApprovalResult {<br>    // 포인트 충전이 필요한 경우<br>    return parameters.toPointTopUpCommandOrNull()?.let { command -&gt;<br>		    // 1. 포인트 충전<br>        when (val topUpResult = pointService.topUpPoint(command)) {<br>		        // 1-1. 충전 성공 시<br>            is topUpPointResult.ToppedUp -&gt; {<br>		            // 2. 결제 승인<br>                when (val billingResult = billingService.executeBillingPayment(parameters.toPaymentCommand())) {<br>                    is BillingPaymentResult.Billed -&gt; {<br>		                    // 결제 승인 성공<br>                        PayApprovalResult.Executed(...)<br>                    }<br>                    is BillingPaymentResult.BillingFailed -&gt; ...<br>                    // billingResult 실패 처리<br>                }<br>            }<br>            is topUpPointResult.PointFailed -&gt; ...<br>            // topUpPointResult 실패 처리<br>        }<br>    } ?: run {<br>        // 포인트 충전이 필요없는 경우<br>        // 2. 결제 승인 (위의 로직과 중복 처리)<br>        when (val billingResult = billingService.executeBillingPayment(parameters.toPaymentCommand())) {...}<br>    }<br>}</pre><p>위 코드처럼 topUpPoint의 성공(ToppedUp) 분기 안에서 billingService.payment를 호출하고, 그 안에서 또 when 분기를 타는 구조가 만들어집니다. 여기에 &quot;포인트 충전이 필요 없는 경우&quot;까지 분기되면서 <strong>결제 승인 로직이 중복되는 문제</strong>까지 발생합니다.</p><p>sealed class의 중첩은 코드를 복잡하게 만들고 로직 중복까지 유발하는, 유지보수의 큰 걸림돌이었습니다.</p><h3>함수형 프로그래밍과 Railway Oriented Programming</h3><p>함수형 프로그래밍(FP)의 매력에 끌렸지만, Monad와 같은 어려운 개념들은 종종 높은 진입 장벽으로 다가옵니다. 저 또한 비슷한 어려움을 느끼던 중, 복잡한 이론 대신 명쾌한 비유로 오류 처리를 설명하는 &#39;Railway Oriented Programming(ROP)&#39;을 접하며 새로운 방식으로 문제를 접근하게 되었습니다.</p><p>ROP는 함수가 실패할 수 있는 상황을 <strong>성공과 실패, 두 개의 철도 트랙</strong>에 비유하는 직관적인 모델입니다.</p><ul><li>입력에 따라 항상 예측 가능한 결과를 반환하는 간단한 함수는 단일 트랙(single-track)으로 표현할 수 있습니다.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/734/1*bwHz9HjDo0_uV9SCm0czSA.png" /></figure><ul><li>하지만 실제로는 입력값이 유효하지 않거나, 네트워크 오류가 발생하는 등 다양한 이유로 함수는 성공 또는 실패할 수 있습니다. 이러한 상황은 이중 트랙(two-track), 즉 성공 경로와 실패 경로로 나눌 수 있습니다.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ITpBXlsGCO9-8GQuRI-v3A.png" /></figure><p>ROP에서는 이렇게 두 개의 트랙을 가진 함수들을 마치 철도 노선을 연결하여 전체 로직을 구성합니다. 한 함수에서 실패가 발생하면, 이후의 함수들은 실행되지 않고 전체 흐름은 실패로 처리됩니다. 반대로 성공하면, 그 결과가 다음 함수의 입력으로 전달되어 계속 실행됩니다.</p><p>예를 들어, 입력값 유효성 검사 함수와 데이터베이스 저장 함수가 각각 이중 트랙 함수라고 가정해 봅시다. 이 두 함수를 ROP 방식으로 연결하면 다음과 같이 표현될 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bUYg_YTboMHwDJPzRT4R8w.png" /></figure><p>이처럼 ROP은 함수형 프로그래밍에서 오류를 다루는 방식을 간단하게 보여줍니다. 덕분에 이전에는 다소 추상적이고 어렵게만 느껴졌던 함수형 프로그래밍의 오류 처리 방식들을 직관적으로 받아들일 수 있었습니다**.** 성공과 실패를 명확히 나누어 사고하고 구현할 수 있게 되었습니다.</p><p>ROP 의 기법의 장점으로 느낀 부분은 다음과 같습니다.</p><ul><li>명확성: 함수의 결과값이 성공과 실패를 명확히 표현하여, 로직의 의도를 파악하기 쉽다</li><li>안정성: 함수의 오류가 누락되거나 예외 처리 불분명해지는 상황이 줄어들어 전반적인 안정성 향상된다.</li></ul><p>이런 관점으로 ROP 를 실제 코드로 구현하기 위해서 Arrow 라이브러리를 도입하게 되었습니다.</p><p>(Railway Oriented Programming 에 관심이 있으시면 <a href="https://fsharpforfunandprofit.com/rop/">여기</a> 를 참고하세요.)</p><h3>Arrow를 활용한 Typed Error 적용</h3><p>저희 팀은 여러 함수형 라이브러리 중 Arrow를 선택했습니다. 그 이유는 다음과 같습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NcR-N12i0cZRSd99LQOSIg.jpeg" /></figure><ol><li><strong>신뢰성 및 유지보수</strong>: 특정 개인이 아닌 기업(<a href="https://github.com/47degrees">47 Degrees</a>)에서 관리하는 라이브러리라는 점에서 높은 신뢰를 가질 수 있었습니다.</li><li><strong>풍부한 레퍼런스</strong>: Kotlin Conf 등 여러 컨퍼런스에서 수많은 적용 사례가 발표되어, 학습 자료나 참고할 코드를 찾기 용이했습니다.</li></ol><p>Arrow는 다양한 기능을 제공하지만, 저희는 먼저 Typed Error 처리, 그중에서도 Either&lt;L, R&gt;를 적극적으로 적용했습니다. 이는 앞서 설명한 Railway Oriented Programming의 &#39;이중 트랙&#39; 개념을 코드로 구현하는 가장 효과적인 방법이었습니다.</p><ul><li><strong>Right (</strong><strong>R)</strong>: 성공 케이스의 값을 표현</li><li><strong>Left (</strong><strong>L)</strong>: 오류, 실패 케이스를 표현</li></ul><p>Either 역시 내부 구현은 sealed class로 되어 있지만, 단순히 타입을 정의하는 것을 넘어 map, flatMap, getOrElse 등 결과값을 안전하고 편리하게 다룰 수 있는 여러 유용한 함수들을 함께 제공합니다.</p><h3>좋아진 점</h3><h3>1. 보일러플레이트 코드 감소</h3><p>가장 먼저 체감된 변화는 <strong>불필요한 보일러플레이트 코드의 감소</strong>입니다.</p><p>이전에는 결제 결과, 사용자 조회 결과 등 주요 비즈니스 로직마다 성공과 실패를 표현하기 위해 각각의 sealed class (예: PaymentResult, FindUserResult)를 만들어야 했습니다.</p><p>Either&lt;FailureType, SuccessType&gt;이라는 표준화된 구조를 재사용하게 되면서, 비즈니스 로직마다 *Result 클래스를 만들던 반복 작업을 크게 줄일 수 있었습니다.</p><h3>2. 성공과 실패의 명확한 분리</h3><p>sealed class로 결과를 다룰 때는 사실 성공 또는 실패(들)의 구조였습니다. 즉, 하나의 sealed class 계층 안에 성공 상태와 여러 실패 상태들이 동일 수준으로 선언되어 있었죠.</p><pre>// 성공과 여러 실패들이 한 계층에 섞여있는 구조<br>sealed class BillingPaymentResult {<br>	data class Billed(val value: BilledPaymentInfo) : BillingPaymentResult() // 성공<br>	<br>	// 여러 실패 타입들<br>	data class PgFailed(...) : BillingPaymentResult()<br>	data class BillingFailed(...) : BillingPaymentResult()<br>	// ...<br>}</pre><p>이렇게 성공과 실패가 한데 묶여 있으면, 오직 ‘실패’ 상황에만 관심 있는 로직을 작성할 때 문제가 발생합니다. 성공 케이스를 ‘무시’하기 위한 불필요한 코드가 추가되기 때문입니다.</p><p>BillingErrorConverter 예시를 살펴보겠습니다. 이 클래스의 역할은 &#39;실패&#39; 결과로부터 표준화된 오류 객체(DomainErrorDetail)를 만드는 것입니다.</p><pre>class BillingErrorConverter {<br>    // 실패 케이스들로부터 DomainErrorDetail을 생성하는 것이 목적인 함수<br>    fun extractErrorDetail(result: BillingPaymentResult): DomainErrorDetail? {<br>        return when (result) {<br>            // &quot;실패&quot;에만 관심 있지만, &quot;성공&quot; 케이스도 반드시 처리해야 함<br>            is BillingPaymentResult.Billed -&gt; {<br>                // 이 분기는 이 함수의 목적과 무관함<br>                // 성공은 오류가 아니므로 null을 반환하도록 명시해야 함<br>                null<br>            }<br>            // 실제 관심사인 실패 타입들에 대한 처리<br>            is BillingPaymentResult.PgFailed -&gt; convertPgFailed(result)<br>            is BillingPaymentResult.BillingFailed -&gt; convertBillingFailed(result)<br>            // ...<br>        }<br>    }<br>}</pre><p>위 코드의 문제점은 오직 ‘실패’에만 관심 있는 함수임에도 ‘성공’ 케이스를 강제로 처리해야 한다는 것입니다. extractErrorDetail 함수는 성공(Billed) 케이스 때문에 불필요하게 DomainErrorDetail?이라는 nullable 타입을 반환해야만 합니다. 이는 함수의 의도를 흐리하고, 반환값을 사용하는 쪽에서도 추가적인 null 체크를 유발합니다.</p><p>Either는 이 문제를 실패와 성공 타입을 명확히 분리함으로써 해결합니다. 만약 executePayment 함수가 Either&lt;PaymentFailure, BilledPaymentInfo&gt;를 반환했다면, 오류 처리 로직은 다음과 같이 바뀔 수 있습니다.</p><pre>// Either를 사용했을 때의 오류 변환 함수<br>fun extractErrorDetail(failure: PaymentFailure): DomainErrorDetail {<br>    // 파라미터로 실패 타입만 받으므로, 성공 케이스를 고려할 필요가 없음<br>    // 반환 타입도 non-nullable이 되어 의도가 명확해짐<br>    return when (failure) {<br>        is PaymentFailure.PgFailed -&gt; ...<br>        is PaymentFailure.BillingFailed -&gt; ...<br>        // ...<br>    }<br>}<br><br>// Either의 결과 사용<br>executePayment().onLeft { failure -&gt;<br>    // 실패한 경우에만 이 블록이 실행됨<br>    val errorDetail = extractErrorDetail(failure) // null 체크가 필요 없음<br>    logError(errorDetail)<br>}</pre><p>이처럼 Either를 사용하면, 성공은 성공대로, 실패는 실패대로 각각의 관심사에만 집중하는 코드를 작성할 수 있어 코드의 안정성과 가독성이 크게 향상됩니다.</p><h3>고려해야할 점</h3><p>Arrow의 Either&lt;L, R&gt;를 통한 오류 처리는 관심사 분리라는 큰 장점을 가져다주었습니다. 하지만 모든 기술이 그렇듯, 장점에만 집중하다 보면 놓치기 쉬운 부분들이 있었습니다. 저희가 Either를 적용하며 발견했던 몇몇 중요한 이슈들을 공유하고자 합니다.</p><h3>1. @Transactional 왜 롤백이 되지 않지?</h3><p>Either를 도입하며 대부분의 오류 처리 로직이 명확해졌지만, 데이터베이스 트랜잭션을 다루는 과정에서 예상치 못한 치명적인 이슈를 발견했습니다. 바로 @Transactional이 적용된 메소드에서 오류가 발생해도 롤백이 되지 않는 현상이었습니다.</p><p>저희는 데이터의 일관성을 보장하기 위해 Spring의 @Transactional을 사용합니다. 외부 결제 시스템 API 호출이 성공한 후, 여러 단계의 DB 저장 작업을 하나의 트랜잭션으로 묶고, 중간에 하나라도 실패하면 전체 작업이 롤백되기를 기대했습니다.</p><p>하지만 실제로는 DB 저장 중 오류가 발생해도, 실패 직전까지의 작업이 그대로 커밋(commit)되는 문제가 있었습니다.</p><p>다음은 문제가 발생했던 DB 저장 코드의 일부입니다.</p><pre>@Transactional<br>fun saveResult(...): Either&lt;SaveException, PayApprovedInfo&gt; {<br>    return either {<br>        catch({<br>            // 1. payEntity 저장<br>            savePayment(payEntity)<br><br>            // 2. payHistoryEntity 저장<br>            savePaymentHistory(payHistoryEntity)<br><br>            // ... 여러 종류의 데이터를 순차적으로 저장 ...<br>            // (만약 여기서 예외가 발생한다면?)<br><br>            // 10. PayExtraEntity 저장<br>            savePayExtra(payExtraEntity)<br><br>            // 결제 승인 저장 정보 반환<br>            PayApprovedInfo(...)<br>        }) {<br>            // 예외를 catch하여 Left 값으로 변환 후 반환<br>            raise(SaveException.FailureToSave(cause = it))<br>        }<br>    }<br>}</pre><p>위 코드에서 무엇이 잘못되었을까요?</p><p>문제는 catch 블록 안에서 발생한 예외를 raise를 통해 Either.Left로 감싸버렸다는 점입니다. 이 방식은 외부에서 볼 때 예외가 발생하지 않은 정상 흐름처럼 보이기 때문에, Spring의 트랜잭션 매니저는 롤백을 수행하지 않습니다.</p><p>특히 raise()는 내부적으로 throw를 호출하지 않고 Either.Left 값을 반환할 뿐입니다.</p><p>이로 인해 AOP 기반의 @Transactional 트랜잭션 매니저는 예외 발생을 감지하지 못하고 커밋을 수행합니다.</p><h3>그렇다면 이 문제는 어떻게 해결해야 할까요?</h3><p>가장 좋은 해결책은 <strong>관심사를 분리</strong>하는 것입니다. 즉, 트랜잭션을 처리하는 계층과 오류를 Either로 변환하는 역할을 나누는 것입니다.</p><ol><li><strong>내부 트랜잭션 메소드</strong>(예외를 그대로 던지는 역할): 이 메소드는 Either를 반환하지 않습니다. 오직 DB 작업에만 집중하고, 실패 시에는 예외를 그대로 호출한 쪽으로 던져(throw) 트랜잭션 롤백을 유발하는 책임을 집니다</li><li><strong>외부 서비스 메소드</strong>(예외를 Either로 변환하는 역할): @Transactional이 없는 이 메소드에서 내부 메소드를 호출합니다. 그리고 try-catch로 예외를 잡아 Either.Left로 변환하여 최종 결과를 반환합니다.</li></ol><pre>// 결제 승인 처리 Service(외부 서비스 계층)<br>class PaymentApproveService(<br>    private val paymentResultSaveService: PaymentResultSaveService<br>) {<br>  // 결제 데이터 저장 결과를 Either&lt;L,R&gt;로 변환하는 메소드<br>    fun savePaymentResult(...): Either&lt;SaveException, PayApprovedInfo&gt; {<br>        return try {<br>            // 트랜잭션 처리된 메소드를 호출하고, 성공 시 Right로 변환한다.<br>            val payApprovedInfo = paymentResultSaveService.saveResultOrThrow(...)<br>            Either.Right(payApprovedInfo)<br>        } catch (e: DataAccessException) {<br>            // DB 예외가 발생하면 Left로 변환한다.<br>            Either.Left(SaveException.FailureToSave(cause = e))<br>        } catch (e: Exception) {<br>            Either.Left(SaveException.UnknownError(cause = e))<br>        }<br>    }<br>}<br><br><br>// 결제 데이터 결과 저장 Service(내부 데이터 저장 서비스 계층)<br>@Service<br>class PaymentResultSaveService(...) {<br>    <br>    @Transactional<br>    fun savePaymentResultOrThrow(...): PayApprovedInfo { // 데이터를 저장하고, 실패 시 예외를 던짐<br>        // 1. payEntity 저장<br>        savePayment(payEntity)<br><br>        // 2. payHistoryEntity 저장<br>        savePaymentHistory(payHistoryEntity)<br><br>        // ... 여러 데이터 저장 로직 ...<br>        <br>        return PayApprovedInfo(...)<br>    }<br>}</pre><p>관심사에 따른 역할을 분리함으로써 @Transactional 는 데이터 일관성을 보장하고, Either는 비즈니스 로직의 결과를 명확하게 표현하는 각자의 책임을 다할 수 있게 됩니다. Either와 같은 함수형 패턴을 다른 lib 또는 framework와 함께 사용할 때는, 각각의 동작 방식을 이해하고 조화롭게 연결하는 고민이 반드시 필요합니다.</p><h3>2. Either의 전염성과 경계 설정</h3><p>하나의 함수가 Either를 반환하면, 그 함수를 호출하는 상위 함수 또한 연쇄적으로 Either를 다뤄야만 합니다. 이 현상은 결국 애플리케이션의 가장 바깥 계층까지 영향을 미치게 됩니다. 모든 곳에서 Either를 사용하는 것이 때로는 과하고 유연성을 해칠 수 있다고 판단했고, 저희는 명확한 사용 경계를 정하기로 했습니다.</p><h3>2–1. 원칙: 도메인 로직의 경계 안에서만 사용</h3><p>저희가 세운 원칙은 간단합니다. 핵심 도메인 로직에서만 Either를 사용하고, 그 외의 계층에서는 전통적인 방식을 고수하는 것입니다.</p><p>이는 곧 I/O 작업(Infrastructure)과 순수 비즈니스 로직(Domain)을 분리하는 것을 의미합니다.</p><ol><li><strong>Infrastructure Layer</strong> (예: DB 접근, 외부 API 클라이언트): 이 계층의 함수는 성공 시 DTO를 반환하거나, 실패 시 예외(Exception)를 그대로 던집니다. Either를 전혀 사용하지 않으며, Arrow 라이브러리 의존성조차 갖지 않도록 설정했습니다.</li><li><strong>Domain &amp; Service Layer</strong>: Infrastructure 계층의 함수를 호출하며, try-catch를 통해 성공 결과와 예외를 Either 타입으로 변환하는 책임을 집니다. 여기서 변환된 Either가 도메인 로직 전반에서 사용됩니다.</li></ol><p>이 경계 설정을 통해, 저희는 Either의 강력한 오류 처리 능력을 필요한 곳에만 집중시키고, 타입의 무분별한 전파를 효과적으로 제어할 수 있었습니다.</p><h3>2–2. 검증: 규칙을 지키기 위한 자동화 테스트</h3><p>규칙은 강제하지 않으면 쉽게 무너집니다. 저희는 이 아키텍처 원칙을 코드 리뷰나 사람의 기억에 의존하는 대신, Konsist를 통해 자동화된 테스트를 진행했습니다. Konsist는 코드 구조를 검증할 수 있는 Kotlin 라이브러리입니다.</p><p>저희는 Konsist 라이브러리를 통해 아키텍처 규칙을 테스트 코드로 작성하여, CI 단계에서 Either가 정해진 계층에서만 사용되는지 자동으로 검증하고 있습니다.</p><pre>@Test<br>fun `Either 는 반드시 Domain, Service module 에서 사용되어야한다.`() {<br>    Konsist.scopeFromProject()<br>        .classes()<br>        .functions()<br>        .withReturnType {<br>            it.name.startsWith(&quot;Either&lt;&quot;) &amp;&amp; it.name.endsWith(&quot;&gt;&quot;)<br>        }<br>        .assertTrue {<br>            it.resideInPackage(&quot;com.naver.pay.domain..&quot;)<br>                || it.resideInPackage(&quot;com.naver.pay.service..&quot;)<br>        }<br>}</pre><p>이처럼 아키텍처 규칙을 코드로 검증함으로써, 저희는 장기적으로 코드의 일관성과 안정성을 유지할 수 있는 튼튼한 토대를 마련했습니다.</p><h3>3. 직렬화 문제와 책임 분리</h3><p>Either를 도입하면서 놓치기 쉬운 부분 중 하나가 바로 직렬화/역직렬화입니다.</p><p>저희 팀은 Either를 오직 내부 로직에서만 사용하기로 했기 때문에, JSON으로 도메인을 다룰 일은 없을 거라 생각했습니다. 그런데 예외가 하나 있었는데, 바로 Spring의 @Cacheable 기능입니다.</p><p>@Cacheable은 메서드의 결과를 JSON으로 만들어 Redis에 저장합니다. 그런데 이 결과가 Either 타입이라면 아래처럼 저장됩니다.</p><pre>// Either 타입으로 반환하는 함수, @Cacheable에 의해 Json으로 직렬화<br>@Cacheable(cacheNames = [CacheNames.MERCHANT_INFO], key = &quot;#merchantNo&quot;)<br>fun findMerchantInfo(merchantNo: Long): Either&lt;IllegalStateException, MerchantInfo&gt; {<br>   ...<br>}</pre><pre>// 1. 성공 케이스 (Right)<br>{<br>   &quot;value&quot;: { &quot;merchantId&quot;: &quot;...&quot;, &quot;merchantName&quot;: &quot;...&quot; },<br>   &quot;isLeft&quot;: false,<br>   &quot;isRight&quot;: true,<br>   &quot;isLeft$arrow_core&quot;: false, // 불필요한 내부 프로퍼티<br>   &quot;isRight$arrow_core&quot;: true, // 불필요한 내부 프로퍼티<br>   ...<br>}<br><br>// 2. 실패 케이스 (Left)<br>// (예외 객체의 클래스 정보까지 직렬화되며 더 복잡해짐)</pre><p>위처럼 Either는 내부 구조까지 모두 직렬화되기 때문에 결과가 복잡해집니다. 특히 Left 값이 sealed class 타입인 경우, 역직렬화를 위해 Jackson의 @JsonTypeInfo, @JsonSubTypes, @JsonTypeName 등을 일일이 명시해야 합니다. 이는 외부 라이브러리의 기능이 도메인 모델 내부로 섞이는 구조가 되어서 도메인 계층의 순수성을 해치는 결과를 낳습니다.</p><p>그렇다면 Either를 캐시해야 할까요? 여러 문제를 종합적으로 고려했을 때, Either 자체를 캐시 대상으로 삼는 것은 바람직하지 않았습니다.</p><p>직렬화 복잡도, 도메인 순수성 침해, 역직렬화 부담 등을 고려했을 때, Either는 서비스 내부에서만 사용하는 것이 더 명확한 경계가 되었습니다.</p><p>트랜잭션 처리와 마찬가지로, 관심사의 분리하는 패턴을 적용했습니다.</p><pre>// 1. 캐시 계층: 순수한 데이터 또는 예외만 반환, 예외 발생하면 Cache 저장하지 않음<br>@Service<br>class MerchantCacheableService(<br>    private val merchantRepository: MerchantRepository<br>) {<br>    @Cacheable(cacheNames = [CacheNames.MERCHANT_INFO], key = &quot;#merchantNo&quot;)<br>    fun findMerchantOrThrow(merchantNo: Long): MerchantInfo {<br>        return merchantRepository.findByNo(merchantNo)<br>            ?: throw NotFoundMerchantException(&quot;존재하지 않는 가맹점입니다. merchantNo=$merchantNo&quot;)<br>    }<br>}<br><br>// 2. 서비스 계층: 캐시 계층을 호출하고 그 결과를 Either로 변환<br>@Service<br>class MerchantService(<br>    private val merchantCacheableService: MerchantCacheableService<br>) {<br>    fun findMerchantInfo(merchantNo: Long): Either&lt;FindMerchantInfoError, MerchantInfo&gt; {<br>        return try {<br>            val merchantInfo = merchantCacheableService.findMerchantOrThrow(merchantNo)<br>            Either.Right(merchantInfo)<br>        } catch (e: NotFoundMerchantException) {<br>            Either.Left(FindMerchantInfoError.NotFound(message = e.message))<br>        } catch (e: Exception) {<br>            Either.Left(FindMerchantInfoError.Unknown(cause = e))<br>        }<br>    }<br>}</pre><p>역할을 분리함으로써 Either를 직렬화하거나 역직렬화할 필요가 없어졌고, 도메인 모델에 외부 라이브러리 어노테이션이 침투하는 문제도 방지할 수 있었습니다. 결과적으로 각 레이어의 책임도 더욱 명확해졌습니다.</p><h3>4. 그렇다면, Exception은 더 이상 쓰지 않나요?</h3><p>“그럼 Either를 쓰면, Exception은 아예 사용하지 않는 건가요?&quot; 결론부터 말하면, &quot;아니요, 각자의 역할에 맞게 둘 다 사용합니다.&quot;</p><p>그 이유는 Spring이 제공하는 강력한 예외 처리 기능, 즉 @ControllerAdvice와 @ExceptionHandler를 활용했기 때문입니다. 이 기능은 API에서 발생하는 모든 예외를 한곳에서 처리하여 일관된 구조의 에러 응답을 생성하는, 효율적이고 유용한 기능입니다. 그리고 이 기능은 Exception이 발생해야만 동작합니다.</p><p>따라서 저희는 도메인 오류는 Either로 처리하고, 마지막에 Exception으로 변환해 프레임워크와 자연스럽게 연동하도록 했습니다.</p><pre>// Presentation Layer: Controller는 결제 실패시, Service는 예외를 던질것으로 예측<br>@RestController<br>class PayApprovalController(...) {<br>    @PostMapping(&quot;/v1/payments/pay-approval&quot;)<br>    fun paymentApproval(@RequestBody request: PayApprovalRequest): PayApprovalResponse {<br>        val successInfo = payApprovalService.approvalPaymentOrThrow(request.toCommand())<br>        return PayApprovalResponse(paymentId = successInfo.paymentId, ...)<br>    }<br>}<br><br>// Domain Layer: Service는 Either.Left를 Exception으로 변환하는 책임<br>@Service<br>class PayApprovalService(...) {<br>    fun approvalPaymentOrThrow(command: PayApprovalCommand): PayApprovedInfo {<br>        // executePayment()은 Either를 반환<br>        return executePayment(command)<br>            .getOrElse { failure -&gt; // Right면 값을, Left면 이 블록을 실행<br>                // 실패의 종류에 따라 적절한 Exception을 생성<br>                // 이를 통해 4xx, 5xx 등의 HTTP 응답을 분기 처리<br>                throw when (failure) {<br>                    is ValidateFailedException -&gt; ExpectedException(...)<br>                    is SaveFailedException -&gt; UnexpectedException(...)<br>                    // ...<br>                }<br>            }<br>    }<br>}</pre><p>위 코드의 approvalPaymentOrThrow 함수가 바로 저희가 설정한 모듈간의 &#39;경계&#39;입니다.</p><p>Service Layer 내에서도, 외부(Controller)에 직접 노출되는 이 끝단의 함수가 도메인 로직을 거치며 축적된 최종 Either 결과를 마지막으로 해석하는 책임을 집니다. 성공(Right)은 그대로 반환하고, 실패(Left)는 프레임워크가 인지할 수 있는 Exception으로 변환하여 던져주는 것이죠.</p><p>이를 통해 Either 기반의 안정적인 도메인 처리와 프레임워크의 유용한 Exception 처리 기능과의 균형을 이룬 실용적 아키텍처를 구성했습니다.</p><p><strong>마치며</strong></p><p>Either를 통해 오류를 처리하는 새로운 방식에 적응하는 과정은 결코 쉽지만은 않았습니다. 기술의 장단점을 이해하고 우리에게 맞는 사용 범위와 규칙을 정하기까지, 수많은 시행착오와 논의가 필요했습니다.</p><p>특히 코드를 공유하게 될 팀원들과의 격렬한 토론은 필수적이었습니다. 이 과정에서 보여준 동료들의 열린 자세와 날카로운 의견들이 지금의 안정적인 시스템을 만든 가장 큰 힘이었습니다.</p><p>새로운 도전을 함께 고민하고, 더 나은 방향을 향해 나아갈 수 있도록 함께 애써주시는 우리 팀원, 모두에게 진심으로 감사합니다.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2a5d425e56f1" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/%EB%8F%84%EB%A9%94%EC%9D%B8-error%EB%A5%BC-%EB%8B%A4%EB%A3%A8%EB%8A%94-%EA%B3%A0%EB%AF%BC%EA%B3%BC-arrow%EC%9D%98-either-2a5d425e56f1">도메인 Error를 다루는 고민과 Arrow의 Either</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Node.js가 싱글스레드 서버라는 미신(feat. Node.js의 대용량 데이터 처리)]]></title>
            <link>https://medium.com/naverfinancial/node-js%EA%B0%80-%EC%8B%B1%EA%B8%80%EC%8A%A4%EB%A0%88%EB%93%9C-%EC%84%9C%EB%B2%84%EB%9D%BC%EB%8A%94-%EB%AF%B8%EC%8B%A0-feat-node-js%EC%9D%98-%EB%8C%80%EC%9A%A9%EB%9F%89-%EB%8D%B0%EC%9D%B4%ED%84%B0-%EC%B2%98%EB%A6%AC-cf1d651290be?source=rss----c7c775a7cf0b---4</link>
            <guid isPermaLink="false">https://medium.com/p/cf1d651290be</guid>
            <category><![CDATA[backend]]></category>
            <category><![CDATA[dev]]></category>
            <dc:creator><![CDATA[twkim913]]></dc:creator>
            <pubDate>Tue, 17 Jun 2025 09:29:30 GMT</pubDate>
            <atom:updated>2025-06-17T09:29:30.397Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong>“Node.js는 싱글스레드인가, 멀티스레드인가?”</strong></blockquote><blockquote><strong>대부분은 너무 쉽게 대답합니다. 하지만 정말 그렇게 단순한 문제일까요?</strong></blockquote><h3>1. Node.js가 싱글스레드 서버라는 미신</h3><p>저는 네이버페이에서 백엔드 서버 개발 업무를 맡고 있는 김태우입니다.</p><p>“Node.js는 싱글스레드인가요, 멀티스레드인가요?”</p><p>제가 이직 전 회사에서 면접관으로 면접에 참여할 때 즐겨 묻는 질문이였습니다.</p><p>기술 면접에서 이런 질문을 던지면, 열이면 아홉은 ‘<strong>Node.js 면접 단골 질문 20선</strong>’ 같은 글로 벼락치기하고 온 티를 내며 이렇게 대답합니다.</p><p>“싱글스레드입니다!”</p><p>틀렸다는 건 아닙니다, 완전히 틀린 건 아니죠. 하지만 완전히 맞다 보기도 어렵습니다.</p><p>HTTP 요청은 응답을 기다리는 동안 응답을 기다리는 Loop에 빠져 스레드를 점유하게 됩니다. 그렇기에, 일반적인 단일 스레드에서는 그 요청이 끝날 때까지 다음 요청을 받을 수 없습니다.</p><p>예를 들어, 어떤 API 요청이 처리되는 과정에서 외부에 요청을 보내고 10초를 기다린다고 가정해 봅시다.<br>순수한 싱글스레드 서버라면 그 10초 동안 서버는 멈춰 버리는게 맞습니다, 그런데 Node.js 서버는 멈추지 않고 그 시간에도 다른 요청을 처리합니다.</p><p>그래서 저는 이런 설명을 마친 다음, 다시 이렇게 물어봅니다.<br>“그래도 Node.js는 싱글스레드인가요?”<br>그러면 보통 면접장에는 아주 묘한 정적이 흐릅니다.<br>“시간이 없어서 그 부분까지는 공부를 못 했습니다…”<br>“그 부분은 더 공부해보겠습니다…”<br>그런 대답도 나오긴 하지만, 그런 대답도 정적만큼 어색하고… 불행합니다.</p><h3>2. 싱글스레드처럼 보이지만, 속은 다르다</h3><p>Node.js의 스레드 구조에 대해 검색해 보면, 늘 모호한 표현들부터 마주치게 됩니다.<br>“Single-threaded event loop”, “Non-blocking I/O” 같은 설명 말입니다.<br>그럴싸해 보이지만, 사실 우리가 정말 알고 싶은 건 이겁니다</p><blockquote><strong>“이거, 그냥 싱글스레드냐 아니냐만 좀 명확히 말해줘!”</strong></blockquote><p>애석하게도, 그 대답은 “<strong>둘 다 맞다”</strong>입니다.<br>아주 개발자 친화적인 답변이죠.<br>똑 부러진 걸 원했는데, 돌아온 건 철학 수업입니다.<br>하지만 어쩔 수 없습니다. 현실이 그렇거든요.</p><p>Node.js는 자바스크립트 코드를 실행할 때, <strong>딱 하나의 메인 스레드</strong>를 사용합니다. 이 안에서 우리가 잘 아는 <strong>이벤트 루프(Event Loop)</strong>가 돌아가고 있죠.</p><p>그런데 이 메인 스레드는, 오래 걸리는 작업은 <strong>직접 처리하지 않습니다</strong>.</p><p>예를 들어:</p><ul><li>파일 시스템 접근</li><li>데이터베이스 쿼리</li><li>HTTP 요청</li></ul><p>이런 작업들은 시간을 꽤 잡아먹을 수 있습니다, Node.js는 이런 I/O 작업을 <strong>libuv</strong>라는 C로 작성된 라이브러리에 넘깁니다.</p><p>물론 Nginx처럼 커널 이벤트를 직접 다루는 서버는 단일 스레드로도 hang 없이 I/O를 처리할 수 있습니다.<br>하지만 Node.js는 애플리케이션 레벨에서 동작하므로, 그런 방식은 현실적이지 않죠.<br>그래서 오래 걸리는 일은 과감히 libuv에게 맡기는 겁니다.</p><p>libuv는 전달받은 작업을 내부의 워커스레드에 던지고, <strong>메인 스레드는 다시 이벤트 루프를 돌며 다른 작업을 처리합니다. </strong>이런 구조로 인해 Node.js는 멈추지 않고 작동할 수 있습니다.</p><p>그렇기에 Node.js는 겉보기엔 싱글스레드지만, 실제로는 뒤에서는 묵묵히 일하는 워커 스레드들이 도와주는 <strong>멀티스레드 아키텍처 기반 서버</strong>입니다.</p><p>게다가, 굳이 libuv 구조까지 고려하지 않더라도, <br> <strong>Node.js v12부터는 </strong><strong>worker_threads 모듈</strong>이 정식 도입 되면서, 개발자 스스로도 명시적인 멀티스레드 처리가 가능해졌습니다.<br>이제는 직접 워커스레드를 만들고, 공유 메모리나 메시지를 통해 데이터도 주고받을 수 있죠.</p><p>즉, Node.js는 <strong>“분명히 멀티스레드 요소를 활용하는”</strong> 서버입니다.<br>그리고 최신 버전에서는 <strong>‘진짜’ </strong>멀티스레드 프로그래밍까지 가능해졌습니다.</p><h3>3. <strong>개발자 입장에선 싱글스레드가 맞다</strong></h3><p>이쯤 되면 이런 생각이 들 수도 있습니다.<br> “아니, 뒤에서 멀티스레드가 그렇게 열심히 돌아가고 있는데, 왜 굳이 Node.js를 싱글스레드라고 하는거야?”</p><p>이 질문에 대한 답은 <strong>개발자의 관점에서</strong> 찾아야 합니다.</p><p>Node.js는 우리가 작성하는 JavaScript 코드와 그 흐름을 제어하는 이벤트 루프까지 <strong>모두 하나의 메인 스레드에서 실행됩니다.</strong><br> JavaScript 코드는 V8이라는 엔진 위에서 실행되고, 비동기 작업은 C 기반 라이브러리인 libuv가 조율하지만, 이 두 구성 요소 모두 <strong>단일 스레드 위에서 움직입니다.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ibokHGsROOIjuc1XD7ivMw.png" /></figure><p>그 결과, 코드를 읽는 입장에서는 모든 작업이 한 줄씩 순서대로 실행되는 것처럼 보이죠.<br>특히 Promise, async/await 같은 비동기 구문을 사용할 때도, 우리가 느끼는 흐름은 여전히 순차적입니다.<br>언뜻 보면 스레드라는 개념조차 존재하지 않는 것처럼 보일 정도입니다.</p><p>물론 위에서 말한 시간이 오래 걸리는 작업들(파일 읽기, HTTP 요청, 데이터베이스 쿼리 등… )은 메인 스레드가 직접 처리하지 않습니다.<br>Node.js는 이런 I/O 중심의 작업을 libuv의 내부 워커 스레드 풀에 위임하고, 메인 스레드는 그 사이에도 다른 이벤트를 계속 처리할 수 있도록 이벤트 루프를 반복 실행합니다.<br>그리고 I/O 작업이 완료되면 작업 결과가 담긴 콜백이 이벤트 큐에 쌓이고, call stack이 비었을 때 V8엔진이 그 콜백을 다시 실행합니다.<br> <strong>즉, 작업은 병렬로 처리되지만, 콜백은 순차적으로 메인 스레드에서 실행되는 구조</strong>입니다.</p><p>이런 구조 덕분에 우리는 Node.js 개발을 할 때 mutex, race condition, deadlock 같은 멀티스레드 개발의 골칫거리들로부터 자유롭습니다.</p><p>왜냐하면 <strong>libuv의 워커 스레드 풀이 병렬로 작업을 수행하긴 하지만, 이 스레드들이 우리가 작성한 JavaScript 코드 내부의 상태나 메모리에 직접 접근하진 않기 때문입니다.</strong></p><p>워커 스레드는 말 그대로 “작업 위임 대상”일 뿐이고, <strong>실제로 실행 흐름을 제어하거나 변수에 접근하는 주체는 오직 메인스레드 하나 </strong>입니다.</p><p>그래서 우리는 병렬 작업의 이점을 누리면서도, 멀티스레드 환경에서 흔히 겪는 데이터 경합이나 동기화 문제로부터는 자연스럽게 보호 받는 셈입니다.</p><p>주니어 시절엔 “<strong>mutex를 극복하는 자만이 진짜 개발자</strong>” 같은 말을 많이 들었지만, 이제는 가능하면 <strong>그런 싸움을 만들지 않는 구조가 더 현명하다고 생각</strong>합니다. ( 인생도 그렇잖아요 )</p><p>다만 한 가지, 이벤트 루프가 바라보는 이벤트 큐는 단순한 FIFO 큐는 아닙니다.<br>macro queue, micro queue, next-tick queue처럼 큐의 종류도 다양하고,이벤트 루프 역시 각 단계(phase)마다 다른 규칙으로 콜백을 처리합니다.</p><p>하지만 이 글에서는 Node.js의 싱글스레드적인 특성에 집중하고 있고, 지금 우리가 집중할 건 ‘<strong>어떻게 동작하느냐</strong>’보다 ‘<strong>어떻게 다루느냐</strong>’ 이니, 이벤트 루프와 이벤트 큐와 관련해서는 더 깊게 들어가진 않겠습니다.</p><p>결국 중요한 건 이겁니다:<br>우리가 작성하는 JavaScript 코드는 온전히 하나의 메인스레드 위에서 실행되고, Node.js는 <strong>싱글스레드처럼 보이지만 꽤 우아하게 멀티스레드를 활용하는 구조</strong>를 가지고 있다는 겁니다.</p><p><strong>그 단순함</strong>, 그리고 복잡함을 숨긴 구조.<br>그게 바로 Node.js의 가장 큰 매력 중 하나입니다.</p><p>저는 특히 Node.js의 이런 <strong>“싱글스레드처럼 동작하도록 설계된 철학”</strong>이 가장 큰 매력이라고 생각하기에, 개인적으로는 worker_threads 같은 멀티스레드 확장 기능을 선호하지 않습니다.</p><p>이런 아름다운 구조 덕분에, 우리는 Node.js를 싱글스레드 서버라고 부를 수 있습니다, <strong>고맙게도 말이죠</strong>.</p><h3>4. 싱글스레드의 그림자는 반드시 온다</h3><p>물론, 싱글스레드처럼 코드를 짤 수 있다는 건 정말 편한 일이긴 합니다.<br>그런데요… 항상 좋은 것만 있을 수는 없잖아요?</p><p>이 구조는 개발자 입장에서 매우 단순하고 직관적이지만, 문제가 생기는 순간이 분명히 존재합니다, 특히 CPU를 많이 쓰는 작업이 들어올 때 그렇습니다.</p><p>예를 들어 이런 작업들이 그렇습니다.</p><ul><li><strong>이미지 / 비디오 인코딩, 디코딩</strong></li><li><strong>수백만 개의 JSON 문자열 파싱</strong></li><li><strong>대용량 리스트 정렬, 필터링</strong></li><li><strong>암호화, 복호화 같은 연산</strong></li></ul><p>이런 작업은 기다리는 I/O가 아니라 <strong>실제로 CPU가 계산해야 하는 일</strong>입니다.<br>그래서 이런 종류의 작업은 I/O 작업에 특화된 libuv 워커스레드에게 슬쩍 넘겨버릴 수도 없습니다.<br>결국 이건 <strong>메인 스레드</strong>, 그러니까 V8이 돌아가고 있는 그 <strong>단 하나의 스레드</strong>가 혼자서 전부 처리해야 합니다.</p><p>그래서 문제가 생깁니다.<br>이런 작업이 하나라도 들어오는 순간, <strong>다른 모든 요청이 줄줄이 대기 상태로 밀려나게 되는</strong> 거죠.</p><p>“싱글스레드”의 단점이 <strong>조용히, 하지만 확실하게 터지는 순간</strong>입니다.</p><p>물론, 대부분의 현실적인 API 요청은 그렇게까지 무겁지 않습니다.<br>JSON 수백 개를 파싱 하거나, 리스트 몇 천 개를 정렬하는 정도는 <strong>보통 10~20ms 안에 처리</strong>됩니다.<br>실제로 Node.js 서버를 직접 운영해보신 분들이라면, “CPU 연산에 약하다고? 잘 모르겠는데?” 싶은 느낌, 한번쯤 받아보셨을 겁니다.<br> I/O 중심의 API가 대부분이고, 비동기로 처리되기 때문에 CPU 병목이 드러날 일이 많지 않습니다.</p><p>하지만 정말 무거운 작업이 들어오면 이야기가 완전히 달라집니다.</p><p>예를 들어, <strong>500만 개의 JSON 문자열을 파싱</strong>해야 하는 요청이 들어온다고 해봅시다.<br>겉보기엔 단순한 반복이지만, 실제로는 2~3분이나 걸리는 작업입니다.<br> 그리고 그 시간 동안, 메인 스레드는 이 작업에 묶이게 되고, 다른 모든 API 요청은 <strong>그저 조용히 줄 서 있는</strong> 신세가 되어버립니다. (그리고 아무도 줄을 서고 있다는 걸 눈치채지 못하죠. 서버는 그저… 조용히 멈춰있을 뿐입니다.)</p><p>반면에 Java Spring 같은 서버는 조금 더 ‘우아하게’ 대응합니다.<br>요청 하나가 무거워도, 스레드풀에서 남는 스레드가 다른 요청을 처리해줍니다.<br>다른 요청이 그 뒤에 줄 서며 서버가 멈춰버리는 일도 없을 거구요.<br>심지어 CPU 작업이라면 여러 개의 스레드로 <strong>병렬 처리</strong>까지 가능하죠.<br>만약 Spring에서 500만 개의 데이터를 파싱해야 한다면?<br>아마도 내부적으로 적절히 나누어 처리해서 <strong>10~20초 안에 응답</strong>을 줄 수도 있습니다.</p><p>Node.js도 worker_threads를 사용하면 병렬 작업이 가능하긴 합니다.<br>하지만 기본 값이 아니고, 설정도 손이 좀 가며, 무엇보다 <strong>하나의 API 요청을 여러 스레드가 동시에 처리하기는 여전히 어렵습니다.</strong></p><p>무엇보다도, worker_threads 를 사용해 Spring 만큼 유연한 병렬 작업을 구현한다고 해도, 근본적으로는 응답을 주기 전 <strong>10~20초 </strong>동안 서버가 멈춰버리는 현상은 막을 수 없을 겁니다.</p><p>즉, Node.js는 가볍고 빠르지만, <strong>진짜 무거운 CPU 작업이 들어오면 조용하게 멈춰버리는 구조</strong>입니다.<br>그리고 그 침묵은… 서버 운영자 입장에서는 꽤나 무섭습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*ohVgWEsgCxTpaC1Z" /></figure><h3>5. <strong>Node.js를 둘러싼 다소 억울한 평가들</strong></h3><p>그래서 그런지 Node.js에 대한 긍정적인 평가를 보면 이런 식입니다</p><blockquote>‘가벼운 웹 서버엔 괜찮다’</blockquote><blockquote>‘스타트업에서 빠르게 개발하고 API 서버 띄울 땐 유용하다’</blockquote><p>들어보면 다 맞는 말이긴 하고, 좋은 말이기도 하지만, 어째 작게 뒷말이 붙은 느낌이죠.</p><blockquote>“물론 <strong>‘진짜’ </strong>트래픽은 Java가 받겠지만 ㅎ”</blockquote><p>제가 좋아하는 맥주로 비유하자면, 대기업 광고에서 흔히 보이는 <strong>“가볍고 부담 없이, 좋은 사람들과 즐기기 딱 좋은 맥주!”</strong> 같은 문구가 떠오릅니다.<br><em>진짜 맛있는 건 따로 있지만</em>, 어쨌든 싸고 목 넘김은 좋다는 그런 느낌.</p><p>하지만 실제로는 그렇지 않습니다.<br> Node.js는 <strong>컨테이너 환경에서의 가벼움</strong>, <strong>스케일아웃에 최적화된 구조</strong>,<br> <strong>I/O 중심 처리에 강한 런타임 특성</strong> 등 꽤 실용적인 장점들을 가지고 있습니다.</p><p>물론 트랜잭션 처리나 ORM 중심의 복잡한 계층 설계에는 Spring보다 아쉬운 부분이 있지만, 반대로 말하면 <strong>필요한 만큼만 만들고, 명확하게 쪼개어 확장하기에는 오히려 더 유리</strong>한 선택지입니다.</p><p>물론 Node.js를 “<strong>맥주 코스프레한 탄산수</strong>”쯤으로 보는 시선도 있지만, 요즘처럼 클라우드 환경이 기본이 된 요즘 상황에선, <strong>Node.js는 발포주 정도가 아니라, 유연하고도 꽤 잘 만든 라거 </strong>일지도 모릅니다.<br>잘 고르고, 제대로 따르면 꽤 맛있게 마실 수 있는 그런 맥주요.</p><h3>6. 실무 사례: 60억 건 마이그레이션</h3><p>네이버페이의 타임라인 서버, 그러니까 사용자가 “내가 뭘 샀더라?” 하고 조회하는 그 화면은 Node.js로 구성되어 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/648/1*4F70jxTw863mH4yMRHRHAQ.jpeg" /><figcaption>어렵게 생각할 것 없이 이거 맞습니다.</figcaption></figure><p>이 서버는 평소에 Kafka에서 결제·구매 데이터를 받아서, 내부 컨버팅 로직을 거친 뒤 MongoDB에 저장하고, 그걸 API로 노출하는 구조로 되어 있죠.</p><p>그런데 2022년 쯤, 이 타임라인 페이지를 전면 리뉴얼하면서 큰 과제가 하나 생겼습니다.<br><strong>기존 데이터 전체를 다시 마이그레이션</strong>해야 했거든요.<br> Kafka에는 최근 2주치 데이터밖에 없으니, 5년 치 데이터를 가져오려면 Hive에서 데이터를 뽑아와야 했습니다.</p><p>이 작업, 말이 쉽지 정말 녹록지 않았습니다.<br>Apache Hive에서 Join + 필터링된 데이터를 HQL로 추출한 뒤, 그걸 Node.js 서버에서 받아 JSON으로 파싱하고, 컨버팅 로직을 적용해 MongoDB에 bulk insert하는 구조로 진행됐습니다. (이 한 줄을 구현한 코드의 커밋 로그들에는 제 고민과 삽질이 고스란히 남아 있지만, 그때 마신 커피와 잃어버린 주말은 이제 어디에도 없습니다…)</p><p>물론 Hive 쿼리 최적화도 고통이었고, MongoDB에 데이터를 넣는 과정도 만만치 않았습니다.</p><p>Hive 쿼리 최적화를 위한 서브쿼리 구성은 어떻게 할지, index는 언제 만들지, writeConcern은 어떻게 가져갈지, bulk insert의 chunk 사이즈는 얼마나 줘야 하는지 같은 고민이 계속 이어졌죠.</p><p>하지만, 진짜 문제는 따로 있었습니다.</p><p>Node.js가 60억 개의 Hive 문자열을 JSON으로 바꾸는 작업이 생각보다 훨씬 느렸던 겁니다.<br>심지어 MongoDB는 멀쩡했습니다, CPU 사용률이 3%를 넘지 않았거든요.</p><p>즉, 병목은 명백히 Node.js 쪽에 있었던 거죠.</p><p>k8s 환경이라 kubectl top pods로 바로 확인할 수 있었는데, <strong>Node.js Pod가 1020~1030m 수준으로 CPU를 풀로 사용 중</strong>이었습니다.<br>싱글스레드가 코어 하나를 풀로 쓰면서 <strong>혼자 죽도록 파싱</strong>을 하고 있었던 거죠.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*W-TAiXlTxoX3U_um.png" /><figcaption>kubectl top pods 예시 (실제 회사 내부 콘솔은 아닙니다)</figcaption></figure><p>그 결과로 정말 말 그대로 “한 대로 돌리면 25일” 걸리는 마이그레이션 스케줄이 나왔습니다.<br>QA 중 이슈라도 터지면, <strong>25일짜리 리셋</strong>을 의미했죠.<br>지금 생각해도 살짝 어질어질 합니다. (그죠?)</p><h3>8. 야근 대신 스케일아웃 — Node.js가 잘 맞는다</h3><p>사실 해결책은 꽤 명확했습니다.<br> <strong>스케일아웃 (Scale-Out)</strong><br> Node.js 하나가 죽도록 일하고 있다면? 그냥 여러 개 띄우면 되는 겁니다.</p><p>물론 스케일아웃이라는 개념 자체는 낯선 것도, 혁신적인 것도 아닙니다.<br>몇십 년 전부터 CS 교과서에 등장하던 아주 기본적인 확장 전략이죠.<br>하지만 Node.js처럼 <strong>가볍고, 구조가 뚜렷하게 쪼개지는 런타임</strong>에선 이 평범한 전략이 생각보다 훨씬 강력하게 작동합니다.</p><p>예전 같았으면 서버 여러 대 띄우고, 로드밸런서 붙이고, 모니터링까지 손이 많이 갔겠지만, 다행히 저희는 이미 k8s 환경에 서버를 올리고 있었습니다.</p><p>Node.js로 마이그레이션 서버 이미지를 만들어서 k8s에 배포하고, 그걸 복제해 서버를 여러 개 띄우고, Deployment 설정과 HPA만 살짝 손 보면 자동 확장까지 됩니다.<br>정말 <strong>변수 하나만 바꾸면 병렬 마이그레이션 서버가 5개든 25개든 바로 준비됩니다.</strong></p><p>그리고 이런 작업 방식에서는, Node.js의 구조가 의외로 강한 장점이 됩니다.<br>가볍고, 단일스레드로 돌아가며, 컨테이너 단위로 쪼개기 좋기 때문이죠.</p><p>Spring 서버는 JVM 구동에만 수백 MB, 운영 중이면 3~4GB도 금방 써버려 스케일 아웃이 약간은 부담스러운데 비해 Node.js는 일반적인 API 서버라면 구동 시 25MB, 운영 중에도 500~ 600MB 정도면 충분합니다.</p><blockquote>다만 대규모 데이터 마이그레이션처럼 <strong>매 요청마다 수백 MB 이상의 JSON 데이터를 쌓고 처리해야 하는 특수 상황</strong>에서는, Node.js도 예외 없이 6~ 8GB까지 메모리를 사용하는 걸 실제로 확인했습니다.</blockquote><blockquote>하지만 이건 어디까지나 특수 케이스였고, 평소 운용하는 서버들과 비교하면 여전히 <strong>가볍고 확장에 유리한 구조</strong>라는 점은 변하지 않습니다.</blockquote><p>CPU도 한 코어만 쓰기 때문에, 대부분 1000m 근처에서 멈춥니다.<br>그래서 저는 k8s Pod마다 CPU를 1200m로 할당했습니다.<br>너무 빡빡하지도, 낭비도 아닌 <strong>딱 적절한 리소스 세팅</strong>이죠.</p><p>결국 서버를 25개 정도까지 띄웠을 때, 병목이 Node.js에서 MongoDB로 넘어갔습니다.<br> MongoDB가 더 이상 write를 감당 못하더라고요.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/1*22VtqPNgPF6ZsVKScm2NcQ.png" /><figcaption>실제 테스트 DB에서 진행했던 테스트 모니터링 데이터</figcaption></figure><p>그래서 그 시점부터는 “더는 Node.js가 느려서 문제다”라고 말할 수 없었습니다.</p><p>60억건의 마이그레이션 역시 잘 처리됬다는 것 역시 말할 필요도 없을 거구요.</p><p>재미있는 건 이 구조가 <strong>API 서버에도 똑같이 적용</strong>된다는 겁니다.<br>Node.js는 싱글스레드 서버이지만, k8s에서 여러 개 띄우면 <strong>멀티스레드 서버처럼 운용</strong>할 수 있습니다.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vSkI6A-YZhvAqBBsJxnoyQ.png" /><figcaption>k8s를 통해 여러 Thread에 트래픽을 나눌 수 있다는 점에서는 mutli-thread처럼 동작</figcaption></figure><p>클러스터 차원에서 보면, 마치 Java의 멀티스레드 서버처럼 트래픽을 여러 스레드로 나눠받고 있죠.</p><p>즉, 약점이던 구조가 오히려 <strong>명확한 단위로 수평 확장 가능하다는 강점</strong>이 되어버리는 겁니다.</p><p>이론으론 괜찮아 보여도 현실은 다르다고들 하죠.</p><p>근데 이건… 생각보다 현실에서도 그냥 잘 작동합니다.<br>지금도 네이버페이 타임라인은 스케일아웃 기반 Node.js 서버로 초당 몇 백번의 요청을 안정적으로 받아내고 있으니까요.</p><h3>9. 마무리: 진실처럼 보이는 거짓을 넘어서</h3><p>튜링상 수상자인 프레드 브룩스는 1986년 유명한 논문(<a href="https://worrydream.com/refs/Brooks_1986_-_No_Silver_Bullet.pdf">No Silver Bullet</a>)에서 이렇게 말했습니다.</p><blockquote>“소프트웨어 개발에는 모든 문제를 단번에 해결해주는 은 탄환은 없다.”</blockquote><p>그리고 지금까지도 (적어도 제가 경험한 바로는) 그런 은 탄환은 없었습니다.</p><p>Node.js도 마찬가지입니다.</p><p>Node.js는 싱글스레드처럼 단순한 구조, 비동기 기반의 빠른 처리, 낮은 리소스 사용량 등 분명한 강점을 지니고 있습니다.<br> 반면, Spring처럼 프레임워크 차원에서 제공되는 트랜잭션 처리, 계층적 설계, 생명주기 제어, 강력한 ORM , 멀티스레드를 통한 강력한 연산능력 같은 기능은 상대적으로 부족한 게 사실입니다.</p><p>물론 Nest.js나 TypeORM 같은 Node.js 생태계는 점점 더 이런 틈을 메워가고 있습니다.</p><p>저 역시 이런 틈을 매워가는 흐름에 보탬이 되고 싶어 실무에서 싱글스레드 구조를 유지하면서도 k8s 기반에서 CPU 자원을 유연하게 활용하는 구조를 직접 구성해보기도 했습니다.</p><p>그리고 그 과정에서 저 나름대로의 작은 결론을 냈습니다:</p><blockquote><strong>Q. Node.js는 싱글스레드 서버라는 ‘미신’, 진실 혹은 거짓?</strong></blockquote><blockquote><strong>A. 완전한 진실은 아니지만, 실무에선 진실만큼이나 쓸모 있는 ‘잘 만든 거짓’.</strong></blockquote><p>물론 그 자체로 완벽한 서버는 아닙니다.<br>하지만 Node.js의 구조를 이해하고 목적에 맞게 설계한다면, 오히려 지나치게 복잡한 시스템보다 더 견고하고 효율적인 선택지가 될 수 있습니다.</p><p>그리고 그게 Node.js가 가진, 가장 Node.js다운 매력 아닐까요?</p><p>긴 글 읽어주셔서 정말 감사합니다.<br>그리고 끝까지 읽으신 걸로 봐선, 이 글은 생각보다 재미있었거나…<br>아니면 여러분이 Node.js에 좀 많이 빠져드신 거겠죠.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NZWu_UcC4DQ2iMvRImtpig.png" /><figcaption>읽어 주셔서 감사합니다!</figcaption></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cf1d651290be" width="1" height="1" alt=""><hr><p><a href="https://medium.com/naverfinancial/node-js%EA%B0%80-%EC%8B%B1%EA%B8%80%EC%8A%A4%EB%A0%88%EB%93%9C-%EC%84%9C%EB%B2%84%EB%9D%BC%EB%8A%94-%EB%AF%B8%EC%8B%A0-feat-node-js%EC%9D%98-%EB%8C%80%EC%9A%A9%EB%9F%89-%EB%8D%B0%EC%9D%B4%ED%84%B0-%EC%B2%98%EB%A6%AC-cf1d651290be">Node.js가 싱글스레드 서버라는 미신(feat. Node.js의 대용량 데이터 처리)</a> was originally published in <a href="https://medium.com/naverfinancial">NAVER Pay Dev Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>