그래서 이번에는 반대로 해 봤다. 이미 돌아가고 있는 서비스를 보면서, 기획자였다면 썼을 문서를 하나씩 채웠다. 사후에 쓴 문서라는 건 문서 첫 줄에 적어 두었다. 쓰는 데 하루가 걸렸고, 그 하루 동안 서비스에 빠져 있던 것 아홉 가지가 나왔다.

결과: 기획 문서 여덟 편(시장조사, 서비스 기획서, 요구사항 정의서, 정책서, 정보구조와 흐름, 화면설계서, 지표와 이벤트 설계, 출시·운영 계획)을 썼다. 쓰면서 빠진 것 아홉 가지를 찾았고 그중 다섯 가지는 그날 고쳐서 배포했다. 서비스를 실제로 바꾼 문서는 정책서와 지표 설계 두 편이었다.

문서는 저장소의 docs/planning에 올려 두었다.

1. 무엇을 썼나

시장조사의 숫자는 출처 페이지를 직접 열어 확인한 것만 적었다. 오프라인 진단이 4만 원대에서 시작해 평균 6만 원대라는 것, 한 예약 플랫폼에서는 외국인 손님의 뷰티숍 결제 가운데 80%가 퍼스널 컬러 진단이었다는 것, 올리브영이 올해 안에 피부 진단 앱에 퍼스널 컬러를 넣는다는 것. 이 셋을 놓고 보면 업계가 진단에서 구매로 이어지는 쪽으로 가고 있고, 집에서 무료로 그 흐름을 끝까지 해 주는 서비스는 아직 없다. 톤빛은 그 자리를 보고 만든 셈이라, 시장조사는 쓰면서 방향을 다시 확인하는 정도였다.

나머지 일곱 편은 이미 있는 서비스를 문서로 옮겨 적는 일에 가까웠다. 그런데 옮겨 적다 보니 문서에는 써 놓고 서비스에는 없는 것이 자꾸 나왔다.

2. 쓰면서 걸린 것

앞의 다섯 가지는 하나씩 한두 시간이면 되는 일인데 3주 동안 한 번도 안 했다. 기능을 만들 때는 그 기능만 보게 되고, 고지가 빠졌는지나 순위가 언제 것인지 같은 건 누가 물어보기 전에는 생각이 나지 않았기 때문이다. 문서를 쓰는 일이 그 질문을 대신 해 준 셈이다.

3. 그날 고친 것

화면이 바뀔 때마다 이벤트를 보낸다

측정이 끝난 뒤 화면이 바뀔 때마다 어느 화면인지 보내는 이벤트를 넣었다. 내 톤, 느낌, 질감, 둘 중 고르기, 순위, 발라 보기, 정확도 높이기, AI 상담까지 전부 남는다. 측정 완료 이벤트에는 사진 몇 장을 합쳤는지도 같이 보내게 했다. 사진 장수와 확신도가 어떤 관계인지는 4주쯤 쌓이면 볼 수 있을 것 같다.

발라 보기 화면에도 파트너스 고지

정책서에 고지 규칙을 쓰고 나서 화면을 하나씩 열어 보니 순위 화면에는 있고 발라 보기 화면에는 없었다. 고지 문단을 컴포넌트 하나로 빼서 두 화면이 같은 걸 쓰게 했다. 앞으로 구매 링크가 있는 화면이 늘어도 이 컴포넌트만 넣으면 된다.

순위에 기준 시점을 적는다

순위 데이터는 분기마다 손으로 갱신하는데 화면에는 그게 언제 것인지 적혀 있지 않았다. 적지 않으면 보는 사람은 지금 순위로 읽는다. 순위 화면 아래에 “인기 순위는 2026년 9월 기준이에요” 한 줄을 넣고, 날짜는 상수로 두어 데이터를 갱신할 때 같이 바꾸도록 했다.

반응 카드를 내 톤 화면으로 옮겼다

“이 결과, 내 생각과 비슷해요?”라고 묻는 카드가 정확도 높이기 화면에만 있었다. 거기까지 들어오는 사람은 결과가 미심쩍어서 온 경우가 많을 테니, 그 답만 모으면 정확도가 실제보다 낮게 잡힌다. 측정을 끝낸 사람이 모두 보는 내 톤 화면으로 옮겼다. 지난 글에서 화면마다 글을 줄였던 걸 생각하면 주 화면에 질문을 하나 더하는 게 마음에 걸렸지만, 쓸 수 있는 숫자를 얻는 쪽이 낫다고 봤다. 전문가 진단 입력은 그대로 정확도 높이기에 두고, 달라요를 누르면 그리로 이어지게 했다.

눕혀 저장된 사진을 테스트에 넣었다

폰으로 찍은 사진은 픽셀은 눕혀 저장하고 EXIF에 회전 정보만 적는 경우가 많다. 지금까지는 아이폰 실기기로 한 번 확인하고 넘어갔는데, 그런 사진을 픽스처로 만들어 올리면 세로로 세워서 측정하는지 E2E 테스트에 넣었다. 브라우저의 기본 회전 처리에 맡기는 설계라 코드는 바뀐 게 없고 테스트만 늘었다.

4. 미룬 것

5. 어떤 문서가 쓸모 있었나

빠진 걸 찾아낸 건 거의 정책서와 지표 설계였다. 기획서와 화면설계서는 있는 화면을 보고 옮겨 적으면 끝났다. 정책서는 “이 경우에는 이렇게 한다”를 한 줄씩 써야 해서 정해 두지 않은 게 바로 드러났고, 지표 설계는 “이 숫자는 어떤 이벤트로 재나”를 쓰다 보면 이벤트가 없는 게 보였다.

판단 기준: 쓰고 나서 서비스가 바뀐 게 없는 문서는 다음 프로젝트에서는 건너뛴다.

다음에 사이드 프로젝트를 또 한다면 여덟 편을 다 쓰지는 않을 것 같다. 정책서와 지표 설계 두 편은 만들기 전에 쓰고, 나머지는 만든 뒤에 필요하면 채우는 정도가 혼자 하는 프로젝트에는 맞는 것 같다. 처음부터 여덟 편을 썼다면 첫 버전이 하루 만에 나오지는 않았을 것이다.

마치며

문서 없이 3주를 고쳤는데, 문서 쓰는 데 하루를 쓰고 나니 다섯 가지가 더 고쳐졌다. 개인적으로는 반응 카드를 내 톤 화면으로 옮긴 게 가장 잘한 결정이라고 생각한다. 이게 있어야 정확도 이야기를 숫자로 할 수 있기 때문이다.

다음은 4주 뒤에 퍼널 숫자를 보는 일이다. 가설로 적어 둔 측정 완료율 60%, 구매 클릭 5%가 실제로 얼마였는지, 그래서 무엇을 바꿨는지를 다음 글에 적으려고 한다.

MyBatis는 문법이 많아서, 꼭 기억할 세 가지를 먼저 정리해 두고 시작한다.

1. MyBatis는 SQL을 사람이 직접 쓰고, 결과만 객체에 담아 준다.
2. 값은 반드시 #{} 로 넣는다. ${}는 SQL 인젝션이 된다.
3. 쿼리 두 개가 같은 DB 연결을 써야 할 때가 있고, 그걸 보장하는 게 트랜잭션이다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

① JPA와 무엇이 다른가

어느 쪽이 더 나은 건 아니다. 테이블 7개를 조인하는 복잡한 조회 화면은 SQL을 직접 쓰는 게 훨씬 편하다. 대신 규칙이 SQL 곳곳에 흩어지기 쉽다는 단점이 있다. 이 이야기는 ⑤에서 다시 한다.

② 구조: 인터페이스 하나, XML 하나

카트 목록 조회를 예로 따라가 봤다. Java 쪽에는 인터페이스만 있고 구현이 없다.

@Mapper
public interface CartMapper {
    List<CartSearchOutDTO> selectCartList(CartSearchReqDTO reqDTO);
}

SQL은 XML에 있다.

<mapper namespace="com.example.wms.cart.mapper.CartMapper">        <!-- 어느 인터페이스? -->

    <select id="selectCartList" resultType="CartSearchOutDTO">     <!-- 어느 메서드? 결과는 어디에 담나? -->
        SELECT cm.cart_id
              ,cm.cart_type_cd
              ,cm.cart_barcode_no
          FROM cart_mst cm
         WHERE cm.delete_yn = 'N'
           AND cm.sub_account_id = #{subAccountId}
          <if test="cartTypeCd != null">
           AND cm.cart_type_cd = #{cartTypeCd}
          </if>
          <if test="searchData != null and searchData != ''">
           AND cm.cart_barcode_no LIKE CONCAT('%', #{searchData}, '%')
          </if>
         ORDER BY cm.cart_id DESC
         LIMIT #{start}, #{size}
    </select>
</mapper>

둘은 이름으로 연결된다. namespace는 인터페이스 이름, id는 메서드 이름이다. cartMapper.selectCartList(reqDTO)를 부르면 MyBatis가 같은 이름의 SQL을 찾아 실행하고, 결과 한 줄 한 줄을 CartSearchOutDTO에 담아 준다.

SQL 컬럼은 cart_barcode_no인데 DTO 필드는 cartBarcodeNo다. map-underscore-to-camel-case: true 설정이 자동으로 바꿔 준다. 프론트에서 API 응답에 camelcaseKeys()를 쓰는 것과 같다.

③ 조건이 있을 때만 붙이기: 동적 SQL

검색 조건은 있을 수도 있고 없을 수도 있다. 프론트에서는 이렇게 처리한다.

const params = { subAccountId };
if (cartTypeCd) params.cartTypeCd = cartTypeCd;
if (searchData) params.searchData = searchData;

XML에서는 <if test="...">가 같은 일을 한다. 조건이 참일 때만 그 줄이 SQL에 들어간다.

IN (1, 2, 3)처럼 목록을 넣을 때는 <foreach>를 쓴다.

AND cm.cart_id IN
<foreach collection="cartIds" item="cartId" separator="," open="(" close=")">
    #{cartId}
</foreach>

`IN (${cartIds.map(() => '?').join(',')})`   // 하는 일은 같다

④ #{}와 ${}: 이것만은 꼭 기억

#{searchData}는 값을 SQL에 문자열로 이어 붙이지 않는다. SQL 모양을 먼저 확정해 두고, 값은 ? 자리에 데이터로만 따로 넘긴다.

WHERE cm.cart_barcode_no LIKE CONCAT('%', ?, '%')     -- 값은 따로 전달

그래서 사용자가 무엇을 입력해도 SQL 문법으로 해석되지 않는다.

${}는 반대로 입력을 그대로 이어 붙인다. 프론트로 치면 이런 차이다.

el.textContent = userInput;   // #{} : 글자로만 들어간다
el.innerHTML  = userInput;    // ${} : 입력이 코드로 실행될 수 있다 (XSS)

이 레포의 매퍼 XML 65개를 전부 검색해 봤더니 ${}는 0개였다. 일부러 쓰지 않는다는 뜻이다.

⑤ 페이징의 함정: 같은 연결이어야 한다

목록 화면에는 “전체 N건”도 필요하다. 레거시는 MySQL 기능으로 이걸 구한다.

SELECT SQL_CALC_FOUND_ROWS ... LIMIT 0, 20    -- 20건만 가져오되, LIMIT이 없었다면 몇 건인지 기억해 둬
SELECT FOUND_ROWS()                            -- 방금 기억한 숫자를 줘

@Service
@Transactional(readOnly = true)
public class CartService {

    public PageDTO<List<CartSearchOutDTO>> searchCartList(CartSearchReqDTO reqDTO) {
        List<CartSearchOutDTO> dataList = cartMapper.selectCartList(reqDTO);   // 쿼리 1
        pageDTO.setTotCnt(commMapper.getTotCnt());                              // 쿼리 2: FOUND_ROWS()

FOUND_ROWS()는 같은 DB 연결에서 바로 전에 실행한 쿼리의 결과를 기억한다. 그래서 쿼리 1과 쿼리 2가 같은 연결을 써야 맞는 숫자가 나온다.

그걸 보장하는 게 5편에서 배운 @Transactional이다. 트랜잭션 안에서는 메서드가 끝날 때까지 연결 하나를 붙잡고 쓴다. 트랜잭션이 롤백 말고도 하는 일이 하나 더 있었다.

⑥ 레거시에서 보이는 것

6편에서 본 “빈약한 모델”이 여기 그대로 있다.

• DTO에는 필드와 getter, setter만 있다.
• delete_yn = 'N'(삭제 안 된 것만 보기) 같은 규칙을 쿼리마다 직접 적어야 한다. 하나만 빠뜨려도 삭제된 카트가 화면에 나온다.
• 상태를 바꾸려면 UPDATE문을 직접 써서 호출해야 한다.

<update id="updateDeleteYnCartContainerDtl">
    UPDATE cart_container_dtl
       SET delete_yn = 'Y', upd_dt = now(), upd_id = #{userId}
     WHERE cart_id = #{cartId}
</update>

신규 기능을 JPA와 도메인 모델로 만드는 이유가 여기서 이해됐다. MyBatis가 나빠서가 아니라 규칙이 SQL에 흩어지면 테스트하기 어렵기 때문이다. 8편에서 본 것처럼 Entity 안의 규칙은 순수 Java로 바로 테스트할 수 있다. 반면 XML 속 WHERE 조건은 DB를 띄워야만 확인할 수 있다.

퀴즈 풀어 보기

문제 1: ${}로 바꾸고 이상한 값을 넣으면?

AND cm.cart_barcode_no LIKE CONCAT('%', '${searchData}', '%')

검증되지 않은 값이 들어가서 오류가 날 거라고 답했다. 위험하다는 건 맞혔지만 결과는 틀렸다. 오류가 나지 않는다. 그래서 더 위험하다.

검색창에 ') OR 1=1 -- 를 넣으면 SQL이 이렇게 바뀐다.

WHERE cm.delete_yn = 'N'
  AND cm.sub_account_id = 5
  AND cm.cart_barcode_no LIKE CONCAT('%', '') OR 1=1 -- ', '%')
                                                     ↑ 이 뒤는 전부 주석 처리

AND가 OR보다 먼저 계산되니까 결국 (앞의 조건들) OR 1=1이 된다. 1=1은 항상 참이라서 다른 창고의 카트까지 전부 조회된다. 화면에는 에러 없이 데이터가 잘 나오니 아무도 눈치채지 못한다. 이게 SQL 인젝션이다. 차라리 오류가 났으면 다행이었을 것이다.

문제 2: @Transactional을 지우면 전체 건수는?

“조회만 하는데 트랜잭션이 왜 필요해?” 하고 지웠을 때를 묻는 문제였다. 트랜잭션이 없으면 같은 트랜잭션이라는 걸 몰라서 안 된다고 답했다. 방향은 맞았지만, 정확한 원인은 트랜잭션이 아니라 같은 연결이다.

트랜잭션이 없으면 쿼리마다 커넥션 풀에서 연결을 빌렸다가 돌려준다. 쿼리 1과 쿼리 2가 서로 다른 연결을 쓰게 될 수 있고, 그러면 FOUND_ROWS()가 엉뚱한 숫자를 준다.

더 무서운 건 항상 틀리지는 않는다는 점이다. 풀이 우연히 같은 연결을 다시 주면 숫자가 맞는다. 로컬에서 혼자 테스트하면 멀쩡하고, 사용자가 몰리는 운영 환경에서만 가끔 전체 건수가 이상하게 나온다. 이렇게 가끔만 틀리는 버그가 가장 찾기 어렵다.

문제 3: 검색 조건이 비어 있으면 어떤 SQL이 나갈까?

cartTypeCd는 null이고 searchData는 ""인 요청이다. 처음엔 질문을 잘못 읽어서 SELECT *를 떠올렸는데, 물은 건 WHERE 절에 무엇이 남느냐였다.

두 <if>가 모두 거짓이라서 두 줄 다 빠진다.

WHERE cm.delete_yn = 'N'
  AND cm.sub_account_id = #{subAccountId}

“이 창고의 삭제 안 된 카트 전부”다. 프론트에서 필터를 하나도 고르지 않고 조회 버튼을 누른 상황과 같다.

searchData != ''까지 확인하는 이유도 알게 됐다. 프론트에서 검색창을 비워 두고 보내면 null이 아니라 빈 문자열이 오는 경우가 많다. 프론트에서 if (searchData)로 빈 문자열까지 거르는 것과 같은 습관이다.

정리

정리하고 나니 남는 건 결국 세 가지였다. SQL을 직접 쓴다, 값은 #{}로 넣는다, 쿼리 두 개가 이어지면 같은 연결이 필요하다. 나머지 문법은 필요할 때 다시 찾아보면 된다.

다음 글은 이 시리즈의 마지막이다. 지금까지 배운 Controller, UseCase, Port, Entity, 예외, 테스트를 모아서 작은 API를 직접 만들어 볼 예정이다.

결과: 셀카를 올리면 내 톤이 확률과 함께 나온다. 내 얼굴에 바른 두 립 중 나은 쪽을 일곱 번 고르면, 196색 중 내 피부와 내 눈에 맞춘 순위가 나오고 바로 살 수 있다.

3주 동안 이런 순서로 바뀌었다. 아래 글도 같은 순서로 간다.

1. 왜 만들었나

뷰티와 유통에 관심이 있어서, 평소 궁금했던 퍼스널 컬러를 아이템으로 잡았다. 전문가 진단은 몇만 원에서 십만 원이 넘는다. 온라인 자가 진단은 설문이라 얼굴을 보지 않는다. 사진으로 봐 주는 앱은 사진을 서버로 올려야 한다. 그리고 어느 쪽이든 “당신은 여름 쿨입니다”에서 끝난다.

내가 만들고 싶었던 건 그 다음이었다. 진단이 “그래서 이 립을 사면 된다”까지 이어지는 서비스. 조건은 세 가지였다.

• 돈을 들이지 않는다. 서버 비용을 내지 않고, 광고 심사도 받지 않는다. 수익은 쿠팡 파트너스 링크로만 낸다.
• 할 수 있는 만큼 정확하게 진단한다.
• 진단에서 구매까지 한 흐름으로 이어지게 한다.

얼굴 인식 모델(MediaPipe)이 브라우저에서 돌아가니, 사진을 서버로 보내지 않는 구조로 갈 수 있었다.

2. 하루 만에 만든 첫 버전

아이디어를 내고 하루 만에 바이브 코딩으로 결과물을 만들어냈다. MVP를 따로 두지 않고 처음부터 서비스 모양을 갖췄다. 공유 카드, 쿠팡 링크, 보안 설정, 자동 테스트는 나중에 붙이면 구조를 다시 짜야 해서 첫날에 넣었다.

제품 색은 브랜드 설명을 보고 눈대중으로 적은 값이었고, 어울림 점수는 없었다. 시즌이 나오면 그 시즌 팔레트를 발라 보는 게 전부였다.

배포하고 폰으로 열어 보니 바로 문제가 보였다. 아이폰에서 모델이 안 뜨고, 아이패드가 데스크톱으로 잡히고, 색을 고르는 동안 사진이 화면 밖으로 밀려났다. 그날 저녁에만 일곱 개를 고쳤다. 데스크톱 브라우저에서만 확인하고 배포한 대가였다.

3. 진단이 사진마다 달랐다

며칠 써 보니 같은 사람인데 사진마다 다른 시즌이 나왔다. 전문가 진단을 받아 본 지인에게 돌려 보니 절반쯤 맞았다. 정확도를 올려야 했는데, 막상 손을 대려니 “무엇과 비교해서 정확한가”부터 정해야 했다.

잴 수 있는 두 가지를 쟀더니 둘 다 안 좋았다. 네 시즌 중 겨울이 38%로 쏠려 있었고, 조명을 바꾸면 답이 자주 바뀌었다. 쏠림은 기준값을 다시 잡아서 네 시즌이 22~28%로 고르게 나오게 했다. 조명은 보정 방법 자체를 바꿨다. 전에는 사진 전체의 평균색으로 조명을 추정했는데, 그러면 벽이나 옷 색까지 조명으로 착각한다. 지금은 얼굴 안에 있는 흰 것, 즉 치아와 눈 흰자를 기준으로 조명을 되돌린다.

그러고 나서 논문을 찾아봤다. 셀카 한 장으로 네 시즌을 맞히는 연구는 방법이 달라도 전부 55% 근처에서 멈춘다. 모델을 더 잘 만든다고 넘을 수 있는 벽이 아니었다. 그래서 한 시즌을 단정하지 않고 확률과 다음 후보를 같이 보여 주기로 했다. 마지막 판정은 사용자 눈에 맡긴다. 두 색을 번갈아 발라 보고 고르는 “셀프 비교”가 여기서 나왔다.

판단 기준: 측정은 후보를 줄이는 역할이고, 고르는 건 사람이다.
이 뒤의 결정은 전부 이 기준에서 나왔다.

4. 어울린다는 립이 하나도 안 어울렸다

서비스 중심을 “내 립 찾기”로 옮기고, 올리브영 베스트셀러 립 90색에 어울림 점수를 매겼다. 그런데 내 얼굴로 돌려 보니 1등이라는 립이 하나도 안 어울렸다. 점수를 세 번 다시 만들었다.

두 번째까지 안 어울렸던 이유는 “가장 알맞은 지점”이 모든 사람에게 같았기 때문이다. 세 번째 점수는 그 지점을 사람마다 다르게 잡는다. 쿨톤이면 핑크 쪽 색이, 웜톤이면 코랄 쪽 색이 기준점이 된다. 피부가 밝은 라이트 타입이면 연한 립이, 어두운 딥 타입이면 진한 립이 기준점이 된다. 비교할 때는 제품 색 그대로가 아니라 “이 사람 입술에 발랐을 때 보일 색”을 쓴다.

점수를 매기는 기준은 아홉 가지다.

바꾼 뒤 피부색이 다른 얼굴 넷으로 전체 제품의 점수를 뽑아 봤다. 1등이 체리 레드, 뮤트 로즈, 브릭 레드, 다크 피그로 전부 달랐고, 1등은 80점대, 중간은 60~70점대다. 100점은 없다. 이 결과는 자동 테스트로 적어 두어서, 나중에 점수를 고쳤다가 웜과 쿨의 1등이 다시 같아지면 테스트가 실패한다.

제품 색은 직접 뽑았다

한국 브랜드 립 색을 무료로 주는 데이터는 없었다. 쇼핑몰을 크롤링하면 약관 문제도 있고 색의 출처를 설명할 수 없다. 대신 브랜드 공식 사이트의 색상 칩과 발색 사진에서 색을 직접 뽑았다. 196색 중 173색이 이렇게 잰 값이고, 색마다 출처를 적어 뒀다.

발색이 스티커 같았다

립을 얹는 렌더링도 두 번 갈아엎었다. 처음에는 제품 색을 반투명하게 덮었는데 밝은 제품이 형광처럼 떴다. 색을 덜 올리니 이번엔 묽어지고, 입술의 반짝이는 부분까지 색이 덮여서 스티커 같았다. 지금은 밝기, 반짝임, 명암을 따로 다룬다. 밝기는 일부만 옮기고, 원래 반짝이던 자리에는 색을 덜 묻히고, 밝게 띄울수록 명암 폭을 같이 키운다.

5. 측정 뒤 화면을 다섯 단계로

기능이 늘어나는 동안 측정 뒤 화면은 쌓이기만 했다. 만든 나도 다음에 뭘 눌러야 하는지 몰랐다. 한 화면에 한 가지 일만 두기로 하고 다섯 단계로 나눴다. 모두가 쓰지 않는 기능은 곁가지로 뺐다.

폰에서 쓰는 걸 기본으로 놓았다. 뒤로 가기는 브라우저 뒤로 가기와 같아서, 뒤로 스와이프하면 이전 단계로 돌아간다. 사진은 질문 화면에서 숨기고, 내 톤 화면에서는 작게, 발라 보기에서만 위에 고정했다. 진행 막대와 다음 버튼은 화면 아래에 붙여 엄지로 바로 닿는다.

둘 중 고르기: 내 눈으로 고른 결과가 순위에 들어간다

“측정은 후보를 줄이고 고르는 건 사람”이라는 기준을 제품에도 적용한 게 둘 중 고르기다. 점수 상위에서 서로 다른 8색을 뽑아 내 얼굴에 바른 사진을 두 장씩 보여 주고, 더 나은 쪽을 고른다. 일곱 번 고르면 끝까지 이긴 립에 “내 1등”이 붙는다. 고른 결과는 점수에도 들어간다. 내가 고른 쪽이 더 높은 점수를 받도록 아홉 기준의 비중을 조금씩 옮기는 식이다.

처음엔 기준을 전부 움직이게 했더니 일곱 번 고른 걸로 작은 항목 하나가 −70%까지 튀었다. 일곱 번은 아홉 개를 정하기엔 너무 적어서 우연에 맞춰진 것이었다. 지금은 진하기, 웜·쿨 방향, 혈색, 선명함, 시즌 팔레트 다섯 가지만 움직인다.

직접 써 보고 고친 것

여기까지 만들고 처음부터 끝까지 직접 써 봤다. 기능은 다 있는데 “이게 뭐지?” 싶은 데가 세 군데 나왔다.

6. 결과

마치며

처음 목표는 진단에서 구매까지 한 줄로 이어지는 서비스였지, 진단을 잘하는 것 자체는 아니었다. 정확도 55%라는 벽은 넘지 못했지만, 그 벽 덕분에 “측정은 후보를 줄이고 고르는 건 사람”이라는 흐름이 생겼다. 돌아보면 그게 처음 의도에 더 가까웠다. 진단 결과를 통보받는 것보다, 내 얼굴에 발라 본 두 립 중 하나를 고르는 쪽이 구매까지 훨씬 자연스럽게 이어진다.

개인적으로 가장 잘한 결정은 점수를 두 번째로 고쳤을 때 분포가 예뻐졌는데도 “그래도 안 어울린다”를 그냥 넘기지 않은 것이다. 숫자가 괜찮아 보여도 내 얼굴로 써 보면 바로 티가 났다. 그 느낌을 “피부색이 다른 얼굴 셋에서 1등이 같으면 안 된다”는 기준으로 바꾸고 나서야 고칠 수 있었다.

다음은 이 흐름이 정말 구매로 이어지는지 숫자로 보는 일이다. 측정을 마쳤는지, 둘 중 고르기를 끝냈는지, 어느 화면에서 몇 위 제품의 구매 링크를 눌렀는지를 남기고 있으니, 쌓이면 어디서 끊기는지부터 볼 생각이다.

참고

• Kärkkäinen, K., & Joo, J. (2021). FairFace. WACV.
• Choi, K., Choi, J., & Suk, H.-J. (2017). The human sclera and pupil as the calibration targets. IS&T Electronic Imaging.
• Hirayama, H. 외 (1998). 립 컬러와 피부색의 조화에 관한 연구. 粧技誌 32(2).
• Ou, L.-C., & Luo, M. R. (2006). A colour harmony model for two-colour combinations. Color Research & Application 31(3).
• 코드와 수치 전체: github.com/OHaEuN/tonebit의 docs/color-analysis.md, docs/lip.md.

describe('formatPrice', () => {
  it('천 단위에 콤마를 붙인다', () => {
    expect(formatPrice(12000)).toBe('12,000');
  });
});

백엔드 테스트도 생각은 같다. 다만 백엔드에서는 테스트가 훨씬 더 중요하다는 걸 이번에 알았다.

• 눌러 볼 화면이 없다. 프론트는 브라우저에서 버튼을 눌러 보면 된다. 하지만 “취소된 출고는 출하 불가” 같은 규칙을 직접 확인하려면 DB에 데이터를 넣고, 서버를 띄우고, API를 호출해야 한다.
• 서버 재시작이 느리다. 서버를 한 번 띄우는 데 수십 초가 걸린다. 테스트는 0.1초면 끝난다.
• 틀리면 창고에서 물건이 잘못 움직인다. 지난 글들에서 본 중복 재고 차감 같은 사고가 난다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

① 테스트는 세 층으로 나뉜다

          ▲  느림, 적게
         ╱ ╲
        ╱통합╲      FeatureFlagIntegrationTest  ← 진짜 Spring + DB + HTTP
       ╱─────╲
      ╱UseCase╲     DeleteFeatureFlagTest       ← Port를 가짜(Mock)로
     ╱─────────╲
    ╱  도메인   ╲    FeatureFlagTest, OutboundTest ← 순수 Java, 아무것도 없이
   ╱─────────────╲
          ▼  빠름, 많이

1편에서 배운 Port가 여기서 쓸모를 보여 준다. UseCase는 DB를 직접 모르고 인터페이스만 안다. 그래서 테스트에서는 그 자리에 가짜를 끼우면 되고, DB 없이도 UseCase를 테스트할 수 있다.

② 도메인 테스트: 가장 쉽고 가장 많다

@DisplayName("FeatureFlag 도메인")                // describe
class FeatureFlagTest {

    @Nested
    @DisplayName("delete")                        // 중첩 describe
    class Delete {

        @Test
        @DisplayName("삭제하면 deletedAt과 updatedBy가 설정된다")   // it
        void deletesFeatureFlag() {
            // given
            FeatureFlag featureFlag = offFeatureFlag();

            // when
            featureFlag.delete(DELETED_BY);

            // then
            assertThat(featureFlag.getDeletedAt()).isNotNull();
            assertThat(featureFlag.getUpdatedBy()).isEqualTo(DELETED_BY);
        }
    }
}

생김새만 다르고 Jest와 거의 일대일로 대응된다.

// given / when / then 주석은 준비, 실행, 확인 단계를 나눠 보여 준다. 팀 컨벤션으로 아예 필수로 정해 둔 곳도 있다. 테스트가 길어져도 어디까지가 준비 단계인지 바로 보인다.

예외가 나는지는 이렇게 확인한다.

@Test
@DisplayName("ON 상태면 ActiveFeatureFlagException을 던진다")
void throwsWhenOn() {
    FeatureFlag featureFlag = onFeatureFlag();

    assertThatThrownBy(() -> featureFlag.validateModifiable(flag -> List.of()))
        .isInstanceOf(ActiveFeatureFlagException.class);
}

expect(() => flag.validateModifiable()).toThrow(ActiveFeatureFlagError);

지난 글에서 예외를 클래스별로 나눠 만든 이유가 여기서 하나 더 보였다. 어떤 예외가 나야 하는지를 클래스로 정확히 검증할 수 있다.

도메인 테스트에는 Spring도, DB도, Mock도 없다. 객체를 만들고 메서드를 부르고 결과를 본다. 이렇게 단순할 수 있는 건 규칙을 Entity 안에 뒀기 때문이다. 규칙이 Service와 SQL에 흩어져 있었다면 하나를 확인하는 데도 DB가 필요했을 것이다.

③ 여러 경우를 한 번에: @ParameterizedTest

출고의 endPicking은 PICK과 EXCP일 때만 PACK으로 바뀌고, 나머지 6개 상태에서는 아무 일도 하지 않는다. 6개를 테스트로 하나씩 쓰면 지루하다.

@ParameterizedTest
@EnumSource(value = OutboundStepType.class, names = {"PICK", "EXCP"}, mode = EnumSource.Mode.EXCLUDE)
@DisplayName("PICK과 EXCP가 아니면 상태가 변경되지 않는다")
void endPickingFromOtherSteps(OutboundStepType step) {
    Outbound outbound = createOutboundWithStep(step);

    outbound.endPicking(2L);

    assertEquals(step, outbound.getOutboundStepType());
}

“OutboundStepType 중에서 PICK과 EXCP를 뺀 나머지 전부로 이 테스트를 돌려라”라는 뜻이다. WAIT, PACK, SHIP, DONE, CNCL, EXPA로 6번 실행된다.

test.each(['WAIT', 'PACK', 'SHIP', 'DONE', 'CNCL', 'EXPA'])('%s면 상태가 안 바뀐다', (step) => { ... });

test.each와 다른 점은 목록을 직접 쓰지 않는다는 것이다. 나중에 enum에 상태가 추가되면 자동으로 테스트 대상에 들어간다.

테스트 이름도 다시 보게 됐다. “상태가 변경되지 않는다.” 6편에서 고민했던 “조용히 무시하는 동작”을 이 테스트가 명세로 못 박아 두고 있다. 테스트는 확인 도구이면서 “이 코드는 이렇게 동작해야 한다”고 적어 둔 문서이기도 하다.

④ UseCase 테스트: Mockito로 가짜 끼우기

DeleteFeatureFlag는 생성자로 Port 4개를 주입받는다(3편 DI). 테스트에서는 이 4개를 모두 가짜로 바꾼다.

@ExtendWith(MockitoExtension.class)
class DeleteFeatureFlagTest {

    @InjectMocks                                    // 테스트 대상. 아래 가짜들을 생성자에 넣어서 만들어 준다
    private DeleteFeatureFlag deleteFeatureFlag;

    @Mock private UserApplicationService userService;
    @Mock private FindFeatureFlag findFeatureFlag;
    @Mock private FindUserFeatureFlagRelation findUserFeatureFlagRelation;
    @Mock private LoadFeatureFlagHistory loadFeatureFlagHistory;

3편에서 배운 DI와 같은 원리다. 서버에서는 Spring이 진짜 Repository를 넣어 주고, 테스트에서는 Mockito가 가짜를 넣어 준다. DeleteFeatureFlag는 생성자로 받기만 하니까 받은 게 진짜인지 가짜인지 모른다.

가짜에게는 대답을 미리 정해 준다.

@Test
@DisplayName("OFF 상태이고 연결된 사용자가 없으면 삭제되고 이력이 저장된다")
void deletesFeatureFlagAndSavesHistory() {
    // given
    FeatureFlag featureFlag = offFeatureFlag();
    given(findFeatureFlag.findFeatureFlag(10L)).willReturn(Optional.of(featureFlag));        // "10번 찾으면 이걸 줘"
    given(findUserFeatureFlagRelation.findByFeatureFlag(featureFlag)).willReturn(List.of()); // "연결된 사용자는 없어"

    // when
    deleteFeatureFlag.execute(new DeleteFeatureFlagCommand(1L, 10L));

    // then
    assertThat(featureFlag.getDeletedAt()).isNotNull();
    verify(loadFeatureFlagHistory).loadFeatureFlagHistory(any(FeatureFlagHistory.class));   // "이력 저장이 불렸나?"
}

“안 불렸다”를 확인하는 게 더 중요할 때

@Test
@DisplayName("ON 상태면 사용자 조회 없이 예외를 던지고 삭제되지 않는다")
void throwsWhenActiveWithoutCheckingUsers() {
    // given
    FeatureFlag featureFlag = onFeatureFlag();
    given(findFeatureFlag.findFeatureFlag(10L)).willReturn(Optional.of(featureFlag));

    // when & then
    assertThatThrownBy(() -> deleteFeatureFlag.execute(new DeleteFeatureFlagCommand(1L, 10L)))
        .isInstanceOf(ActiveFeatureFlagException.class);

    assertThat(featureFlag.getDeletedAt()).isNull();
    verifyNoInteractions(findUserFeatureFlagRelation, loadFeatureFlagHistory);
}

처음엔 예외만 확인하면 충분하지 않나 싶었다. 그런데 누군가 순서를 바꿔서 이력을 먼저 저장하고 그다음에 검증하도록 고쳤다고 해 보자. 예외는 똑같이 나니까 예외만 보는 테스트는 통과한다. 하지만 실패한 삭제의 이력이 DB에 남는다. verifyNoInteractions가 이런 경우를 잡는다.

UseCase 테스트로는 확인할 수 없는 것

여기엔 진짜 DB도 @Transactional도 없다. 그래서 객체의 deletedAt이 채워졌는지는 확인할 수 있지만, 그 값이 DB에 UPDATE로 실제로 반영되는지는 알 수 없다(5편 변경 감지). 그건 다음 층에서 확인한다.

⑤ 통합 테스트: 진짜로 끝까지

@Test
@DisplayName("피처플래그 전체 조회 시 저장된 목록을 반환한다")
void returnsAllSavedFeatureFlags() throws Exception {
    // given: 진짜 DB에 저장
    featureFlagJpaRepository.save(featureFlag("FF-TEST-001", "테스트 플래그 A"));
    featureFlagJpaRepository.save(featureFlag("FF-TEST-002", "테스트 플래그 B"));

    // when & then: HTTP 요청처럼 호출하고 응답 JSON 확인
    mockMvc.perform(get("/api/v2/feature-flag"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.data.details.length()").value(2));
}

Spring을 실제로 띄우고 DB에 데이터를 넣은 다음, Controller부터 Repository까지 전부 실제로 거쳐 간다. jsonPath("$.data.details")는 응답 JSON에서 값을 꺼내는 문법이다. 프론트에서 response.data.data.details를 읽는 것과 같다.

가장 확실하지만 가장 느리다. Spring을 띄우는 데만 몇 초가 걸린다. 그래서 핵심 흐름만 통합 테스트로 쓰고, 규칙 하나하나는 도메인 테스트로 확인한다. 테스트 구조가 피라미드 모양이 되는 이유다.

퀴즈 풀어 보기

이번 퀴즈는 직접 풀지 않고 바로 답을 봤다. 대신 답을 보면서 왜 그런지 하나씩 따라가 봤다.

문제 1: 규칙을 바꾸면 테스트는 어떻게 될까?

6편에서 endPicking을 “이미 PACK 이후면 무시하고, 그 밖의 잘못된 상태면 예외를 던진다”로 바꾸자는 이야기가 있었다. 그렇게 바꾸면 ③의 테스트는 어떻게 될까?

6개 상태가 둘로 갈린다.

• PACK, SHIP, DONE: 계속 무시된다. 테스트를 통과한다.
• WAIT, CNCL, EXPA: 이제 예외가 난다. 테스트가 실패한다.

처음엔 테스트가 깨지면 나쁜 일이라고 생각했다. 하지만 이 테스트에는 “이 상태들에서는 조용히 무시한다”는 기존 명세가 담겨 있다. 동작을 일부러 바꿨다면 명세도 함께 바꾸는 게 맞고, 테스트가 그걸 알려 준 것이다. 실수로 바꾼 거라면 배포 전에 버그를 잡아 준 것이다. 어느 쪽이든 아무 일 없이 통과하는 것보다 낫다.

규칙을 바꾼 뒤에는 테스트도 두 개로 나눈다.

@EnumSource(names = {"PACK", "SHIP", "DONE"})   // 무시되는지
@EnumSource(names = {"WAIT", "CNCL", "EXPA"})   // 예외가 나는지

문제 2: 택배 출하 검증 테스트 빈칸 채우기

@Test
@DisplayName("택배 출고가 PACK 상태여도 송장이 없으면 NotIssuedTrackingNumberException을 던진다")
void throwsWhenNoTrackingNumber() {
    // given
    OutboundStatusChangeTarget outbound = new OutboundStatusChangeTarget(
        1L, OutboundStepType.PACK, TransportType.CARRIER, List.of()
    );
    CarrierChangeOutboundStatusValidator validator = new CarrierChangeOutboundStatusValidator();

    // when & then
    assertThatThrownBy(() -> validator.validate(outbound))
        .isInstanceOf(NotIssuedTrackingNumberException.class);
}

빈칸에 들어갈 답은 PACK, List.of(), NotIssuedTrackingNumberException이다. 포장까지 끝난 택배 출고인데 송장 목록이 비어 있으니 “송장 미발번” 예외가 나야 한다. 테스트 이름이 곧 시나리오가 되고, given에는 그 시나리오를 그대로 옮겨 적으면 된다는 게 보였다.

문제 3: @Transactional을 실수로 지우면?

UseCase 위의 @Transactional을 누가 실수로 지웠다면, UseCase 테스트는 통과할까?

통과한다. @Transactional은 Spring이 붙여 주는 기능인데, Mockito 테스트에는 Spring이 없다. 그러니 어노테이션이 있든 없든 테스트 결과는 같다. 이 테스트는 “메서드가 불렸나”, “필드가 바뀌었나”만 확인한다.

실제 서버에서는 트랜잭션이 없으니 변경 감지가 동작하지 않는다. deletedAt을 바꿔도 UPDATE가 나가지 않아서 삭제가 저장되지 않는다.

이 실수는 Spring과 DB를 실제로 띄우는 통합 테스트만 잡을 수 있다. 삭제 API를 호출한 다음 DB에서 다시 조회해서 deletedAt을 확인하는 식이다. 아래층 테스트가 아무리 많아도 위층 테스트를 남겨 둬야 하는 이유를 이 문제로 납득했다.

정리

테스트 문법 자체는 Jest와 거의 같아서 금방 읽혔다. 오히려 새로 알게 된 건 지금까지 배운 설계가 테스트를 쉽게 만들어 준다는 점이었다. 규칙을 Entity에 둬서 도메인 테스트가 순수 Java로 끝나고, Port로 DB를 감춰 둬서 UseCase 테스트에 가짜를 끼울 수 있다. 반대로 말하면 테스트 쓰기가 어려운 코드는 설계부터 의심해 볼 만하다.

다음 글에서는 신규 코드와 다르게 SQL을 직접 쓰는 레거시 MyBatis를 공부할 예정이다.

try {
  await api.post('/outbound/ship', { ids });
} catch (e) {
  toast.error(e.response.data.message);   // "송장 번호가 발번되어 있지 않습니다."
}

이 message가 서버 어디에서 만들어지는지는 생각해 본 적이 없었다. 지난 글에서 출고 도메인 모델을 보면서 throw new ...Exception을 잔뜩 봤는데, 이번에는 그 예외가 어떻게 이 JSON이 되는지 따라가 봤다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

① 예외는 위로 올라간다

택배 출고를 송장 없이 출하하려고 하면 이런 순서로 흘러간다.

Controller.ship()
  └─ UseCase.execute()                    @Transactional
       └─ CarrierValidator.validate()
            └─ throw new NotIssuedTrackingNumberException(id)   💥

throw가 일어나면 그 아래 코드는 실행되지 않고, 예외가 자기를 부른 쪽으로 계속 올라간다. 누군가 catch할 때까지.

1. Validator에서 터진다.
2. UseCase를 지나면서 @Transactional이 예외를 보고 롤백한다. (5편에서 본 내용)
3. Controller에도 try/catch가 없으니 그냥 통과한다.
4. 결국 Spring까지 올라온다.

그런데 Controller를 아무리 찾아봐도 try/catch가 없었다. 그럼 누가 잡는 걸까?

② 전역 예외 처리기: @RestControllerAdvice

@RestControllerAdvice                       // 모든 Controller에서 올라온 예외를 여기서 잡는다
public class GlobalControllerException {

    @ExceptionHandler(AppException.class)  // AppException과 그 자식들이 올라오면 실행
    public ResponseEntity<AppResponse<Void>> handleAppException(AppException e) {
        if (e.isClientError()) {
            log.warn(e.getLogMessage());
        } else {
            log.error(e.getLogMessage(), e);
        }
        return ResponseEntity
            .status(e.getStatusCode())                                   // HTTP 상태 코드
            .body(AppResponse.fail(e.getMessage(), e.getErrorCode()));  // JSON body
    }
}

Controller 수백 개가 각자 try/catch를 쓰는 대신, 이 한 곳에서 모든 예외를 응답으로 바꾼다.

프론트에도 같은 생각으로 만든 게 있다.

• axios interceptor: 모든 응답 에러를 한 곳에서 처리한다.
• React ErrorBoundary: 하위 컴포넌트 어디서 터지든 위에서 잡아 에러 화면을 보여 준다.

그래서 프론트는 이런 응답을 받는다.

HTTP/1.1 422 Unprocessable Entity

{
  "data": null,
  "message": "송장 번호가 발번되어 있지 않습니다.",
  "errorCode": "outbound/not-issued-tracking-number",
  "validations": null
}

1편부터 계속 본 AppResponse가 성공일 때는 success(data), 실패일 때는 fail(message, errorCode)로 같은 모양을 유지한다. 프론트는 항상 같은 구조로 파싱하면 된다.

③ 예외 하나에 메시지가 세 개인 이유

public class NotIssuedTrackingNumberException extends AppRuleException {

    private static final String MESSAGE     = "송장 번호가 발번되어 있지 않습니다.";
    private static final String ERROR_CODE  = "outbound/not-issued-tracking-number";
    private static final String LOG_MESSAGE = "[송장 미발번] %d 주문 상태 변경 실패";

    public NotIssuedTrackingNumberException(Long id) {
        super(MESSAGE, ERROR_CODE, LOG_MESSAGE.formatted(id));
    }
}

로그에는 “출고 12345번에서 실패”처럼 id가 있어야 추적할 수 있다. 하지만 그걸 사용자 화면에 보여 줄 필요는 없다. 내부 정보는 로그에만 남기고 화면에는 안내 문구만 보낸다.

errorCode가 따로 있는 이유는 퀴즈에서 제대로 알게 됐다. 아래에서 다시 정리한다.

④ 예외 종류가 곧 HTTP 상태 코드

이 프로젝트의 예외는 상속 구조로 상태 코드가 정해져 있었다.

RuntimeException
└─ AppException (기본 500)
   ├─ AppValidationV2Exception    400  요청 형식이 틀림 (필수값 누락 등)
   ├─ AppUnAuthorizationException 401  로그인 안 함
   ├─ AppForbiddenException       403  로그인은 했는데 권한 없음
   ├─ AppNotFoundException        404  찾는 게 없음
   ├─ AppConflictException        409  다른 데이터와 충돌 (중복 등)
   ├─ AppRuleException            422  요청은 멀쩡한데 비즈니스 규칙 위반
   └─ AppServerException          500  서버 잘못

예외 클래스를 만들 때 어떤 부모를 extends 할지 고르는 게 곧 상태 코드를 고르는 것이다. NotIssuedTrackingNumberException은 AppRuleException을 상속했으니 422가 된다. 요청 형식은 맞는데 “송장 없이 출하 불가”라는 규칙에 걸렸기 때문이다.

처음에 헷갈렸던 건 400과 422의 차이였다.

• 400: { "ids": "abc" }처럼 숫자 자리에 문자를 보냄 → 요청 자체가 틀림
• 422: 요청은 완벽한데, 이 출고는 지금 출하할 수 없는 상태 → 규칙 위반

⑤ warn과 error를 나누는 이유

if (e.isClientError()) {          // 4xx
    log.warn(e.getLogMessage());
} else {                          // 5xx
    log.error(e.getLogMessage(), e);
}

• 4xx: 작업자가 송장 없이 출하를 눌렀다. 시스템은 정상이고, 막아야 할 걸 잘 막았다. 하루에 수백 번 일어나도 괜찮다. → warn
• 5xx: 서버 코드가 터졌다. 개발자가 고쳐야 한다. → error. 보통 Sentry나 Datadog 알림이 이걸 보고 울린다.

4xx까지 전부 error로 찍으면 새벽에 “작업자가 송장 없이 출하 누름” 알림이 수백 개 온다. 그러다 진짜 장애 알림이 그 사이에 묻힌다.

⑥ 실제 코드에서 보인 것들

404여야 할 것 같은데 422인 예외

public class NotFoundFeatureFlagException extends AppRuleException { ... }   // 422

이름은 NotFound인데 AppRuleException을 상속해서 404가 아니라 422가 나간다. 상태 코드별 예외가 나중에 생겨서 일관되지 않은 부분이 남아 있었다. 프론트에서 status === 404로 분기했다면 이 API에서는 걸리지 않는다.

에러인데 200 OK로 오는 응답

같은 처리기 아래쪽에 레거시용 코드가 있었다.

return ResponseEntity.ok(new LegacyValidationResponse(response));   // 에러인데 200

레거시 API는 에러도 HTTP 200으로 보내고, body 안에 에러 코드를 넣었다. 프론트에서 “응답은 200인데 왜 실패지?”를 겪었던 이유가 이거였다. 기존 프론트 코드가 이 형식에 맞춰져 있어서 하위 호환을 위해 남겨 둔 것이다.

아무도 예상하지 못한 예외

NullPointerException처럼 AppException이 아닌 예외는 위 처리기에 걸리지 않는다. Spring 기본 처리로 넘어가서 500과 Spring 기본 에러 JSON이 나간다. AppResponse 모양이 아니라서 프론트에서 e.response.data.message가 undefined가 될 수 있다.

퀴즈 풀어 보기

문제 1: 없는 출고를 조회하면?

출고 조회 API에 없는 id(999999)로 요청이 왔다. 새 예외 NotFoundOutboundException은 어떤 클래스를 상속해야 하고, 프론트는 어떤 상태 코드와 JSON을 받으며, 로그는 어느 레벨로 찍힐까?

AppNotFoundException을 상속한다고만 답하고 나머지는 빠뜨렸다. 부모를 정하면 나머지는 저절로 따라온다는 걸 연결하지 못한 것이다.

public class NotFoundOutboundException extends AppNotFoundException { ... }

HTTP/1.1 404 Not Found

{
  "data": null,
  "message": "출고 정보를 찾을 수 없습니다.",
  "errorCode": "outbound/not-found",
  "validations": null
}

404는 4xx라서 isClientError()가 true이고, 로그는 warn으로 찍힌다. 없는 id로 조회한 건 서버 버그가 아니니 알림을 울릴 일도 아니다. 부모 클래스 하나를 고르면 상태 코드, 응답, 로그 레벨이 한꺼번에 정해진다.

문제 2: DB 에러를 그대로 던지면?

catch (DataIntegrityViolationException e) {
    throw new AppRuleException(
        e.getMessage(),   // "Duplicate entry 'NEW_PICKING' for key 'uk_feature_flag_code'"
        "feature-flag/duplicate",
        e.getMessage()
    );
}

errorCode가 항상 똑같은 게 문제라고 답했는데, 짚은 곳이 틀렸다. “중복”이라는 한 가지 상황이니 errorCode가 하나인 건 오히려 맞다. 프론트는 이 값으로 분기하면 된다.

진짜 문제는 message 자리에 e.getMessage()를 넣은 것이었다. message는 토스트로 뜨는 문구라서, 작업자 화면에 이게 그대로 뜬다.

Duplicate entry 'NEW_PICKING' for key 'uk_feature_flag_code'

• 작업자가 읽을 수 없다. 영어로 된 DB 에러라 무엇을 하라는 건지 알 수 없다.
• 내부 정보가 새어 나간다. 제약 조건 이름, DB 종류 같은 서버 내부 구조가 브라우저까지 간다. 공격하는 쪽에는 좋은 힌트가 된다.

catch (DataIntegrityViolationException e) {
    throw new AppConflictException(                       // 중복은 409가 더 맞다
        "이미 등록된 기능 플래그 코드입니다.",                  // 사용자용 문구
        "feature-flag/duplicate",                          // 그대로
        "기능 플래그 코드 중복: " + e.getMessage()             // 원문은 로그에만
    );
}

DB나 라이브러리의 원문 에러는 로그에만 남기고, 화면에는 사람이 쓴 문구만 보낸다.

문제 3: 송장 발행 모달을 자동으로 띄우려면?

“송장이 없다는 에러가 나면 송장 발행 모달을 자동으로 띄워 주세요”라는 요구가 왔다. message와 errorCode 중 무엇으로 분기해야 할까?

처음엔 질문 자체가 무슨 뜻인지 몰랐다. 프론트에서 “이게 송장 없음 에러인지”를 판단해야 하는데, 그 판단 기준을 무엇으로 하느냐는 질문이었다.

// A: 문구로 판단
if (e.response.data.message === '송장 번호가 발번되어 있지 않습니다.') openModal();

// B: 코드로 판단
if (e.response.data.errorCode === 'outbound/not-issued-tracking-number') openModal();

답은 B다. 기획자가 문구를 “송장이 아직 없어요. 먼저 발행해 주세요”로 바꾸면 백엔드는 MESSAGE 상수만 고친다. 그러면 A는 문자열이 안 맞아서 모달이 조용히 안 뜬다. 에러도 나지 않아서 한참 뒤에야 알게 된다.

errorCode는 문구가 바뀌어도 그대로인 프론트와 백엔드 사이의 약속이다. 프론트에서 번역된 한국어 문장이 아니라 i18n 키(t('outbound.notIssued'))로 분기하는 것과 같은 이유다.

정리

프론트에서 늘 e.response.data.message를 꺼내 쓰기만 했는데, 그 한 줄 뒤에 “누가 읽을 문구인가”, “바뀌어도 되는 값인가”를 나눠 둔 설계가 있었다. 앞으로 에러 분기 코드를 짤 때는 문구가 아니라 errorCode를 먼저 찾게 될 것 같다.

다음 글에서는 이런 규칙들이 정말 지켜지는지 확인하는 테스트(JUnit, Mockito)를 공부할 예정이다.

“이거 그냥 우리 회사 구현 내용 아닌가? 백엔드 공부랑 무슨 상관이지?”

다시 보니 출고는 예시일 뿐이었다. 진짜 주제는 백엔드에서 매일 하는 고민 하나였다. “이 상태에서는 이걸 하면 안 된다” 같은 규칙을 코드 어디에 둘까? 쇼핑몰이면 “배송 시작된 주문은 취소 불가”, 은행이면 “잔액보다 많이 출금 불가” 같은 규칙이다. 이번 글은 WMS 출고를 따라가면서 이 질문을 정리한다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

① 출고 하나가 창고를 지나가는 길

쇼핑몰에서 주문이 들어오면 WMS에 출고 한 건이 생기고, 이렇게 흘러간다.

WAIT ──→ PICK ──→ PACK ──→ SHIP ──→ DONE
대기      피킹      패킹      출하      완료
          (선반에서  (박스에   (트럭/택배
           꺼내기)   담기)     에 실음)

중간에 빠지는 길도 있다. 고객이 주문을 취소하면 CNCL(취소), 재고가 없거나 문제가 생기면 EXCP(예외) 로 간다.

@Enumerated(EnumType.STRING)
@Column(name = "outbound_step_cd")
private OutboundStepType outboundStepType;   // WAIT, PICK, PACK, SHIP, DONE, CNCL, EXPA, EXCP

이 흐름에는 지켜야 할 규칙이 있다.

• 피킹을 안 했는데 패킹으로 넘어가면 안 된다. 빈 박스를 싸게 된다.
• 이미 트럭에 실린(SHIP) 출고는 취소할 수 없다. 물건이 이미 창고를 떠났다.
• 취소된 출고를 피킹하면 안 된다. 작업자가 헛걸음한다.

프론트에서 상태가 꼬이면 화면이 잠깐 이상해지는 정도다. 그런데 여기서 규칙이 깨지면 실제 창고에서 물건이 잘못 움직인다. 그래서 규칙을 어디에 두느냐가 중요하다.

② 방식 A: Service가 규칙을 들고 있기

레거시 코드에서 쇼핑몰 주문이 취소됐을 때 출고를 취소하는 부분이다.

if (ShopOrderStatsCd.CNL.name().equals(dto.getShopOrderStatsCd())) {
    outboundVO.setCancelStepCd(dto.getOutboundStepCd());   // 어느 단계에서 취소됐는지
    outboundVO.setOutboundStepCd(STEP_CD_CNCL);            // 단계 = 취소
    outboundVO.setStatsCd(OutboundStats.CNCL);             // 상황 = 취소
    outboundVO.setCancelDt(param.getBaseDt());             // 취소 시각
}

OutboundVO는 setter만 있는 데이터 상자다. “출고 취소란 필드 4개를 이렇게 바꾸는 것”이라는 규칙은 이 Service만 알고 있다.

그런데 출고를 취소하는 길은 하나가 아니다.

• 쇼핑몰 주문 동기화로 들어온 취소
• 관리자가 화면에서 직접 하는 취소
• 판매자가 API로 요청한 취소
• 재고 부족으로 처리할 수 없어서 하는 취소

길이 4개면 이 4줄도 4번 복사된다. 누군가 새 취소 기능을 만들면서 setCancelDt를 빠뜨리면? 에러는 안 난다. DB에 취소됐는데 취소 시각이 없는 출고가 조용히 쌓이고, 몇 달 뒤 “취소 통계가 안 맞아요”라는 문의가 와서야 알게 된다.

4곳 중 한 곳에서 “이미 SHIP이면 취소 불가” 검사를 빠뜨리면 더 심각하다. 트럭에 실려 나간 물건이 시스템에서는 취소로 바뀌고, 재고와 정산이 다 틀어진다.

프론트로 치면 컴포넌트마다 setOrder({ ...order, status: 'CANCEL' })를 직접 쓰고 있는 상황이다.

③ 방식 B: 출고가 자기 규칙을 지키기

새 코드의 Outbound 엔티티에는 단계를 바꾸는 setter가 없다. 대신 무엇을 하는지를 이름으로 가진 메서드가 있다.

public void startPickingForRobot(Long userId) {
    if (this.outboundStepType.equals(OutboundStepType.WAIT)) {   // 대기 중일 때만
        this.outboundStepType = OutboundStepType.PICK;
        this.pickingDt = LocalDateTime.now();                    // 피킹 시작 시각도 같이
        this.updatedId = userId;
    }
}

public void endPicking(Long userId) {
    if (this.outboundStepType.equals(OutboundStepType.PICK)
        || this.outboundStepType.equals(OutboundStepType.EXCP)) { // 피킹 중일 때만
        this.outboundStepType = OutboundStepType.PACK;
        this.updatedId = userId;
    }
}

로봇이 피킹을 시작하든 작업자가 PDA로 스캔하든, 부르는 쪽은 메서드 한 줄만 쓴다.

• “WAIT일 때만 PICK으로 간다”는 규칙을 건너뛸 수 없다.
• “PICK으로 갈 때 시각도 기록한다”는 걸 빠뜨릴 수 없다.
• 규칙이 바뀌면 이 메서드 하나만 고치면 된다.

②의 취소도 이 방식으로 쓰면 이렇게 된다.

public void cancel(Long userId) {
    if (this.outboundStepType == SHIP || this.outboundStepType == DONE) {
        throw new AlreadyShippedOutboundException(this.id);   // 이미 나간 건 취소 불가
    }
    this.cancelStepType = this.outboundStepType;
    this.outboundStepType = CNCL;
    this.statsCd = OutboundStatsType.CANCEL;
    this.cancelDt = LocalDateTime.now();
    this.updatedId = userId;
}

취소 길이 4개여도 모두 outbound.cancel(userId)를 부른다. 규칙은 한 곳에만 있다.

프론트로 치면 리듀서다. 컴포넌트는 dispatch({ type: 'CANCEL' })만 하고, 무엇을 어떻게 바꿀지는 리듀서가 정한다.

우리 프로젝트가 레거시(MyBatis)에서 새 구조(JPA)로 옮기면서 바꾸려는 게 바로 이거였다. 팀 문서에 있던 “도메인 로직은 반드시 도메인 모델 안에” 라는 한 줄이 이제야 이해됐다.

setter를 막아서 규칙이 있는 메서드로만 상태를 바꾸게 하는 것을 캡슐화라고 한다. 다만 실제 코드에는 @Builder가 열려 있어서, 이걸로 객체를 만들면 메서드를 거치지 않고 아무 단계나 넣을 수 있었다. 레거시를 옮겨 오는 과도기라 교과서와 다른 부분도 있다.

④ 상태를 묻는 것도 출고에게

규칙은 상태를 바꿀 때만 있는 게 아니다. 물어볼 때도 있다.

public boolean isPackingInProgress() {
    return OutboundStepType.PACK.equals(outboundStepType)
        && !OutboundStatsType.CANCEL.equals(statsCd)
        && !OutboundStatsType.CANCEL_WAIT.equals(statsCd);
}

statsCd는 단계와 별개인 상황이다. 고객이 주문을 취소했는데 창고에서는 이미 박스를 싸고 있으면, 단계는 PACK인데 상황은 CANCEL_WAIT(취소 대기)가 된다.

그래서 “패킹 진행 중”이란 PACK이면서 취소(대기)가 아닌 것이다. 이 조건을 Service마다 직접 쓰면 누군가는 CANCEL_WAIT를 빠뜨린다. 그러면 취소될 박스에 택배 라벨이 붙는다.

// 이렇게 쓰면 CANCEL_WAIT를 빠뜨린다
if (outbound.getOutboundStepType() == PACK && outbound.getStatsCd() != CANCEL) { ... }

// 이렇게 쓴다
if (outbound.isPackingInProgress()) { ... }

프론트의 selector(selectIsPackingInProgress(state))와 같은 역할이다.

⑤ 같은 스캔이 두 번 오면: 멱등성

③의 endPicking을 다시 보면 이상한 점이 있다. 조건이 안 맞으면 예외 없이 그냥 아무것도 안 한다. 피처 플래그는 규칙에 어긋나면 예외를 던졌는데, 이건 왜 무시할까?

창고 현장을 떠올리면 이유가 보인다.

작업자가 PDA로 피킹 완료 바코드를 찍었다. 서버는 PICK → PACK으로 바꾸고 응답을 보냈는데, 창고 구석이라 와이파이가 끊겨서 응답이 PDA에 도착하지 못했다. 작업자는 반응이 없으니 한 번 더 찍는다.

1번째 스캔: PICK → PACK ✅  (응답 유실)
2번째 스캔: 이미 PACK인데 또 endPicking

• 예외를 던지면: PDA에 빨간 에러가 뜬다. 실제로는 성공했는데. 작업자는 관리자를 부르고 작업이 멈춘다.
• 무시하면: 두 번째 스캔도 성공으로 끝난다. 결과는 똑같이 PACK이다.

같은 요청을 여러 번 보내도 한 번 보낸 것과 결과가 같은 성질을 멱등성(idempotency) 이라고 한다. 네트워크는 언제든 끊길 수 있으니 백엔드에서 정말 중요한 개념이다.

프론트에서도 이미 겪어 본 문제였다.

• 버튼 연타를 막으려고 disabled 처리를 한다. 그건 프론트 쪽 방어다. 서버는 그런 방어 없이 요청이 두 번 와도 버텨야 한다.
• React Query는 실패하면 자동으로 재시도한다. 서버가 멱등하지 않으면 재시도가 오히려 사고를 낸다.

그렇다고 무조건 무시하면

WAIT 상태(피킹을 시작도 안 함)에서 endPicking이 왔다면 그건 중복 스캔이 아니라 잘못된 요청이다. 다른 출고의 바코드를 찍었거나 버그일 수 있다. 무조건 무시하면 이런 문제도 같이 묻힌다.

그래서 이렇게 나누는 게 더 안전하다.

public void endPicking(Long userId) {
    if (this.outboundStepType == PACK) return;          // 이미 끝남 → 중복 스캔이니 무시
    if (this.outboundStepType != PICK && this.outboundStepType != EXCP) {
        throw new InvalidOutboundStepException(this.id, this.outboundStepType);  // 잘못된 요청
    }
    this.outboundStepType = PACK;
    this.updatedId = userId;
}

“이미 처리됨”과 “처리할 수 없음”을 구분하는 것이 핵심이다.

⑥ 출하 규칙은 배송 방법마다 다르다

PACK → SHIP으로 넘어갈 때의 규칙은 배송 방법마다 다르다.

• 차량(TRUCK): 패킹만 끝났으면 출하할 수 있다.
• 택배(CARRIER): 패킹이 끝났고 송장 번호도 있어야 한다.

이걸 if (CARRIER) {...} else if (TRUCK) {...}로 쓰지 않고, 배송 방법마다 검증 클래스를 따로 만들어 Map에 넣어 두었다.

// 택배용
if (!outbound.outboundStepType().equals(PACK)) throw new NotCompletePickingOutboundException(...);
if (outbound.trackingNumbers().isEmpty())       throw new NotIssuedTrackingNumberException(...);

// 차량용
if (!outbound.outboundStepType().equals(PACK)) throw new NotCompletePickingOutboundException(...);

// 프론트로 치면
const validators = { TRUCK: validateTruck, CARRIER: validateCarrier };
validators[transportType](outbound);

나중에 퀵 배송이 생기면 클래스 하나를 만들고 Map에 한 줄만 추가하면 된다. 이런 방식을 전략 패턴이라고 한다.

퀴즈 풀어 보기

문제 1: 취소 사유를 추가해 달라는 요청이 오면?

출고 취소 코드(setter 4줄)가 Service 4곳에 복사돼 있다. 기획에서 “취소할 때 취소 사유도 꼭 저장해 주세요”라는 요청이 왔다.

A는 복사된 곳을 전부 찾아 고쳐야 해서 한 곳이라도 빠뜨릴 위험이 있고, B는 cancel() 안에 한 줄만 추가하면 된다고 답했다. 여기까지는 맞았는데, B에는 장점이 하나 더 있었다. 사유를 받으려면 메서드 모양이 바뀐다.

public void cancel(Long userId, String reason) { ... this.cancelReason = reason; }

그러면 cancel(userId)를 부르던 4곳이 전부 컴파일 에러가 난다. 컴파일러가 고칠 곳을 빠짐없이 찾아 주는 셈이다. A는 setter 한 줄을 추가할 뿐이라 컴파일러가 아무것도 알려 주지 않는다. TS에서 함수에 필수 파라미터를 추가하면 호출하는 곳이 전부 빨간 줄이 되는 것과 같다.

문제 2: 출하 스캔이 두 번 오면?

작업자가 PDA로 출하(SHIP) 처리를 찍었는데, 와이파이가 끊겨서 한 번 더 찍었다. 출하할 때는 재고 차감도 같이 일어난다.

재고가 두 번 차감될 거라고 답했고, 맞았다. 출고 1건에 재고가 2번 빠진다. 선반에는 물건이 있는데 시스템에서는 없다고 나오고, 다음 주문이 “재고 부족”으로 막힌다. 막는 방법은 ⑤와 같다.

public void ship(Long userId) {
    if (this.outboundStepType == SHIP) return;   // 이미 출하됨 → 재고 차감까지 가지 않음
    ...
}

다만 이게 통하려면 지난 글의 트랜잭션처럼 재고 차감과 단계 변경이 같은 트랜잭션 안에 있어야 한다. 그래야 두 번째 요청이 SHIP을 보고 멈춘다.

그리고 두 요청이 정확히 동시에 오면 둘 다 아직 PACK인 상태를 읽고 둘 다 통과할 수 있다. 3편에서 본 race condition과 같은 문제다. 이건 DB 락(lock)으로 막는다고 하는데, 나중에 따로 공부해 보려고 한다.

문제 3: 이미 완료된 출고에 피킹 완료가 오면?

개선한 endPicking에서, 이미 DONE(완료)인 출고에 endPicking이 불리면?

코드대로라면 InvalidOutboundStepException을 던진다고 답했다. 코드만 보면 맞는 답인데, 창고 상황을 떠올려 보니 이 동작이 꼭 옳은 건 아니었다.

작업자 A가 피킹 완료를 찍었는데 응답이 늦어졌고, 그 사이에 작업자 B가 패킹하고 출하까지 끝냈다. 그 뒤에 A의 PDA가 재시도를 보내면 출고는 이미 DONE이다. 이 요청은 잘못된 요청이 아니라 늦게 도착한 중복 요청이다. 그런데 에러가 뜬다.

그래서 “이미 PACK이면 무시”보다 “이미 PACK 이후 단계면 무시” 가 더 정확하다.

if (this.outboundStepType.isAfterOrEqual(PACK)) return;   // PACK, SHIP, DONE → 이미 지나감

반대로 CNCL(취소)인 출고에 endPicking이 오면 진짜 문제다. 취소된 물건을 들고 다니고 있다는 뜻이니 예외로 알려야 한다.

기준은 “이 요청이 원하는 상태가 이미 이뤄졌는가” 다. 이뤄졌으면 무시하고, 이뤄질 수 없는 상태면 예외를 던진다.

정리

처음엔 “이건 그냥 회사 구현 내용 아닌가” 싶었는데, 출고라는 예시를 걷어 내고 보니 남는 질문은 어느 서비스에나 있는 것이었다. 규칙은 한 곳에 두고, 같은 요청이 두 번 와도 버티게 만든다. 프론트에서는 사용자 한 명의 화면만 지키면 됐지만, 서버는 네트워크가 끊기고 요청이 겹쳐 와도 데이터를 지켜야 한다는 걸 다시 느꼈다.

다음 글에서는 이번에 잔뜩 나온 throw new ...Exception이 어떻게 프론트에서 보던 에러 응답과 토스트 메시지로 바뀌는지 따라가 볼 예정이다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

왜 필요할까?

피처 플래그를 켜고 끄는 코드다.

@Transactional
public void execute(ChangeStatusFeatureFlagCommand command) {
    FeatureFlag featureFlag = findFeatureFlag.findFeatureFlag(id)
        .orElseThrow(() -> new NotFoundFeatureFlagException(id));
    featureFlag.changeStatus(status, userId);                        // ① 상태 변경

    FeatureFlagHistory history = new FeatureFlagHistory(featureFlag);
    loadFeatureFlagHistory.loadFeatureFlagHistory(history);          // ② 이력 저장
}

DB 작업이 두 개다. ①은 성공하고 ②에서 에러가 나면? 트랜잭션이 없으면 플래그는 켜졌는데 누가 켰는지 기록은 없는 상태가 된다.

WMS(창고관리시스템)에서는 더 심각하다. 출고를 처리할 때 “재고 차감”과 “출고 상태를 SHIP으로 변경”이 같이 일어나야 하는데, 재고만 빠지고 출고 상태가 그대로면 물건은 사라졌는데 아직 안 보낸 주문이 생긴다.

트랜잭션은 여러 DB 작업을 하나로 묶어서 전부 성공하거나 전부 취소되게 한다.

프론트로 비유하면: React Query의 낙관적 업데이트

useMutation({
  onMutate: () => { /* 화면 먼저 바꿈 */ return snapshot; },
  onError: (err, vars, snapshot) => { /* 실패하면 snapshot으로 되돌림 */ },
});

“일단 바꾸고, 실패하면 되돌린다”는 생각은 같다. 차이는 트랜잭션이 커밋되기 전까지 다른 사용자에게 바뀐 내용이 보이지 않는다는 점이다. 낙관적 업데이트는 실패하기 전에도 화면에 이미 반영돼 있다.

① @Transactional이 실제로 하는 일

어노테이션 한 줄이 메서드를 이렇게 감싼다.

// Spring이 만들어 주는 코드 (개념)
트랜잭션 시작;
try {
    execute(command);      // 원래 메서드
    커밋;                   // 끝까지 오면 확정
} catch (RuntimeException e) {
    롤백;                   // 예외가 나면 전부 취소
    throw e;               // 예외는 그대로 위로 던짐
}

3편의 DI와 연결된다. Controller가 주입받는 UseCase는 사실 원본이 아니라, Spring이 이 try/catch로 감싼 대리 객체(프록시) 다. 프론트의 고차 함수와 같은 원리다.

const withTransaction = (fn) => async (...args) => {
  begin();
  try { const r = await fn(...args); commit(); return r; }
  catch (e) { rollback(); throw e; }
};

② “save를 안 불러도 저장된다”는 정확히 언제일까?

1편에서 미뤄 뒀던 질문의 답은 커밋 직전이다.

트랜잭션 시작
  │
  ├─ findFeatureFlag(id)        → SELECT, JPA가 원본 스냅샷 보관 {status: OFF}
  ├─ changeStatus("ON")         → Java 객체만 바뀜. DB는 아직 그대로
  ├─ loadFeatureFlagHistory()   → 이력 INSERT
  │
  ├─ (커밋 직전) JPA가 스냅샷과 비교: status OFF → ON 바뀜!
  │              → UPDATE feature_flag SET feature_flag_status = 'ON' ...
  │
커밋 ✅

changeStatus()를 부른 순간에는 DB가 바뀌지 않는다. 메서드가 끝날 때 한꺼번에 반영된다.

③ 롤백되는 예외, 안 되는 예외

checked 예외는 메서드 선언에 throws를 반드시 적어야 하는 예외다. 이건 롤백되지 않는다는 게 유명한 함정이라고 한다.

우리 프로젝트는 그 걱정을 덜 수 있게 만들어져 있었다.

public class ActiveFeatureFlagException extends AppRuleException { ... }
public class AppRuleException extends AppException { ... }
public class AppException extends RuntimeException { ... }   // ← 결국 RuntimeException

도메인 규칙 예외가 전부 RuntimeException을 상속하니까, 규칙을 어겨서 던진 예외는 항상 롤백된다.

④ 조회에는 readOnly = true

@Transactional(readOnly = true)
public GetAllFeatureFlagResult execute() { ... }

“이 메서드는 읽기만 한다”는 표시다. JPA는 ②의 스냅샷 보관과 비교를 생략해서 조금 더 가벼워지고, 실수로 객체를 바꿔도 DB에 반영되지 않는다. 코드를 보면 조회(Get...)는 전부 readOnly = true, 변경(Change..., Delete..., Register...)은 그냥 @Transactional이었다.

⑤ 주의: 트랜잭션은 DB만 되돌린다

롤백은 우리 DB에 보낸 SQL만 취소한다. 그 밖에서 일어난 일은 되돌리지 못한다.

• 택배사 API를 호출해서 송장 번호를 발급받음
• 슬랙이나 알림톡 전송
• 다른 서버에 요청

보낸 이메일을 취소할 수 없는 것처럼, 이런 건 롤백돼도 이미 일어난 일이다.

퀴즈 풀어 보기

문제 1: 이력 저장에서 예외가 나면 플래그 상태는?

맨 위의 ChangeStatusFeatureFlag에서 OFF → ON으로 바꾸다가 ② 이력 저장에서 예외가 났다. DB의 플래그 상태는?

@Transactional 때문에 다 롤백돼서 OFF로 남는다고 답했고, 맞았다.

다만 더 정확히 말하면, 이 경우에는 되돌릴 UPDATE가 애초에 실행되지 않았다.

① changeStatus("ON")       → Java 객체만 바뀜. DB는 아직 OFF
② 이력 저장 중 예외 💥
   → 커밋 직전 변경 감지 단계까지 가지 못함 → UPDATE 자체가 실행 안 됨
   → 이미 실행된 SQL이 있었다면 그것도 롤백

결과는 같지만, 이 원리를 알면 changeStatus() 바로 다음 줄에서 DB를 조회해 봤을 때 아직 OFF로 나오는 이유도 이해된다.

문제 2: 택배사 API가 끼어 있으면?

@Transactional
public void ship(...) {
    stock.decrease(qty);                  // ① 재고 차감 (DB)
    courierApi.issueInvoice(outbound);    // ② 택배사 API로 송장 발급 (외부)
    outbound.changeStatus(SHIP);          // ③ 출고 상태 변경 (DB) → 여기서 예외!
}

이번에도 다 롤백된다고 답했는데, 절반만 맞았다. ②가 함정이었다.

택배사 API 호출은 이미 HTTP 요청을 보내고 응답까지 받은 상태다. 택배사 시스템에는 송장이 만들어져 있고, 우리 서버가 롤백해도 택배사는 그 사실을 모른다.

우리 DB:   재고 그대로, 출고 상태 그대로  → "아직 출고 안 함"
택배사:    송장 번호 발급 완료          → "곧 택배 보낼 예정"

택배 기사가 물건을 가지러 왔는데 창고에서는 보낼 게 없다고 하거나, 다시 출고 처리를 하면 송장이 두 번 발급될 수 있다. 프론트로 비유하면 결제 API는 성공했는데 그 뒤 우리 서버 저장이 실패해서 돈은 나갔는데 주문은 없는 상황이다.

그래서 실무에서는

① 외부 호출을 DB 작업 뒤로 미룬다

@Transactional
public void ship(...) {
    stock.decrease(qty);
    outbound.changeStatus(SHIP);
}   // 커밋 성공

// 커밋이 확실히 끝난 뒤에 송장 발급
courierApi.issueInvoice(outbound);

DB가 실패하면 송장 발급까지 가지 않는다. 반대로 송장 발급이 실패하면 DB는 이미 SHIP이니까 “송장 재발급” 처리를 따로 해야 한다. 어느 쪽이 실패해도 복구할 수 있는 쪽으로 순서를 정하는 게 핵심이다.

② 실패하면 취소 요청을 보낸다 (보상 처리)

try {
    ...
} catch (Exception e) {
    courierApi.cancelInvoice(invoiceNo);   // 발급했던 송장을 직접 취소
    throw e;
}

DB 롤백처럼 자동으로 되지 않으니, 되돌리는 코드를 직접 짠다.

정리

이번 회차에서 가장 크게 남은 건 “롤백은 우리 DB 안에서만 통한다” 는 것이다. 앞으로 외부 연동 코드를 읽을 때 “이 호출이 트랜잭션 안에 있나? 실패하면 어떻게 되지?”를 먼저 보게 될 것 같다.

다음 글에서는 WMS의 핵심인 출고(Outbound) 도메인 모델을 열어서, WAIT → PICK → PACK → SHIP → DONE 상태 흐름이 코드로 어떻게 지켜지는지 볼 예정이다.

글에 나오는 코드는 이해를 돕기 위해 일부 단순화했다.

JPA가 하는 일

DB는 표(테이블)로 데이터를 저장하고, Java는 객체로 다룬다. 둘을 잇는 방법은 두 가지다.

// JPA 없이: SQL을 직접 쓰고, 결과를 손으로 객체에 옮김
ResultSet rs = db.query("SELECT * FROM feature_flag WHERE feature_flag_id = ?", 12);
FeatureFlag flag = new FeatureFlag();
flag.setCode(rs.getString("feature_flag_identifier_code"));
...

// JPA 사용: 객체 단위로 요청하면 SQL 생성과 변환을 대신 해 줌
FeatureFlag flag = featureFlagJpaRepository.findById(12L);

fetch 응답을 손으로 파싱하는 대신 Prisma 같은 ORM을 쓰는 것과 같다. JPA도 ORM(Object-Relational Mapping)이다.

① 테이블과 Entity를 나란히 놓고 보기

실제 테이블 정의:

CREATE TABLE `feature_flag` (
  `feature_flag_id` bigint NOT NULL AUTO_INCREMENT,
  `feature_flag_identifier_code` varchar(300) NOT NULL,
  `feature_flag_status` varchar(50) NOT NULL,
  `feature_flag_name` varchar(50) NOT NULL,
  `feature_flag_description` varchar(500) DEFAULT NULL,
  `registered_at` datetime NOT NULL,
  `created_by` bigint NOT NULL,
  `updated_by` bigint NOT NULL,
  PRIMARY KEY (`feature_flag_id`)
);

이 테이블과 연결된 Entity:

@Entity                              // "이 클래스는 테이블과 연결된다"
@Table(name = "feature_flag")        // 어떤 테이블과?
public class FeatureFlag {

    @Id                                                  // PRIMARY KEY
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // AUTO_INCREMENT
    @Column(name = "feature_flag_id")
    private Long id;

    @Column(name = "created_by", nullable = false)       // created_by ↔ createdBy
    private Long createdBy;

    @Column(name = "registered_at", nullable = false)
    private LocalDateTime registeredAt;                  // datetime ↔ LocalDateTime
}

@Column(name = "...")은 컬럼 이름과 필드 이름을 짝지어 준다. DB는 snake_case, Java는 camelCase를 쓰니까 연결이 필요하다. API 응답의 created_by를 프론트에서 createdBy로 바꾸는 것과 같은 일이다.

id가 long이 아니라 Long(대문자)인 이유도 여기서 이해됐다. new FeatureFlag(...)로 만든 직후에는 아직 DB에 저장되지 않아서 번호가 없다(null). 저장하는 순간 DB가 AUTO_INCREMENT로 번호를 매기고, JPA가 그 값을 id에 채운다.

② @Embedded: 테이블은 하나, 객체는 여러 개

Entity를 보면 code, status, name 컬럼이 바로 보이지 않는다. 묶여 있다.

public class FeatureFlag {
    @Embedded private FeatureFlagBasicInformation basicInformation;    // name, description
    @Embedded private FeatureFlagDetailInformation detailInformation;  // code, status
}

@Embeddable   // "나는 독립된 테이블이 아니라, 다른 Entity에 끼워 들어간다"
public class FeatureFlagDetailInformation {

    @Column(name = "feature_flag_identifier_code", length = 300, nullable = false)
    private String code;

    @Enumerated(value = EnumType.STRING)       // enum을 "ON"/"OFF" 문자열로 저장
    @Column(name = "feature_flag_status", length = 50, nullable = false)
    private FeatureFlagStatus status;

    public FeatureFlagDetailInformation(String code) {
        validateCode(code);                    // 2~100자 검증
        this.code = code;
        this.status = FeatureFlagStatus.OFF;   // 처음엔 항상 OFF
    }
}

DB에서는 컬럼이 한 줄에 평평하게 나열돼 있지만, Java에서는 관련 있는 것끼리 묶었다.

DB (평평함)                          Java (묶음)
feature_flag_identifier_code  ──┐
feature_flag_status           ──┴→  detailInformation { code, status }
feature_flag_name             ──┐
feature_flag_description      ──┴→  basicInformation { name, description }

평평한 API 응답을 { detail: {...}, basic: {...} }로 재구성하는 것과 비슷하다. 이렇게 묶으면 “code는 2~100자” 같은 규칙을 code를 가진 객체 안에 둘 수 있다. 생성자에서 검증하니까 잘못된 code를 가진 객체는 만들어질 수조차 없다.

③ @Enumerated(STRING)을 빼먹으면?

@Enumerated를 생략하면 JPA는 기본값인 EnumType.ORDINAL을 쓴다. enum을 이름이 아니라 순서 번호로 저장하는 방식이다.

public enum FeatureFlagStatus {
    ON,    // 0번
    OFF;   // 1번
}

이미 "ON"으로 저장된 데이터가 있는 상태에서 이 줄을 지우면:

1. 조회할 때 에러가 난다. JPA가 "ON"을 숫자로 바꾸려다 실패한다.
2. 더 무서운 건 저장이다. 새 플래그를 저장하면 에러 없이 "1"이 들어간다. 테이블에 "ON", "OFF", "0", "1"이 섞인다.

나중에 누군가 알아채고 @Enumerated(STRING)을 다시 붙여도, 이번에는 "1"이라는 이름의 enum이 없어서 또 에러가 난다. 그때는 코드만 고쳐서는 안 되고 DB 데이터까지 고쳐야 한다.

에러가 나는 버그보다 에러 없이 데이터가 이상해지는 버그가 더 위험하다.

프론트는 새로고침하면 상태가 초기화되지만, DB에 잘못 저장된 데이터는 누군가 직접 고치기 전까지 계속 남는다. 백엔드에서 가장 크게 다르게 느낀 감각이다. 그래서 실무에서는 enum에 거의 항상 STRING을 쓴다고 한다. ORDINAL을 쓰면 누가 enum 순서만 바꿔도 DB 데이터의 의미가 통째로 뒤바뀐다.

④ JpaRepository: 인터페이스만 쓰면 구현이 생긴다

public interface FeatureFlagJpaRepository extends JpaRepository<FeatureFlag, Long> {
    //                                                    ↑ Entity    ↑ id 타입
    List<FeatureFlag> findAllByOrderByIdDesc();
    boolean existsByDetailInformationCode(String code);
    Optional<FeatureFlag> findByDetailInformationCode(String code);
}

interface라서 구현이 없다. 그런데도 동작한다. 서버가 켜질 때 Spring Data JPA가 구현체를 자동으로 만들어서 Bean으로 등록하기 때문이다(지난 글의 DI 덕분에 다른 곳에서 주입받아 쓸 수 있다).

JpaRepository를 상속하는 것만으로 기본 메서드가 생긴다.

메서드 이름이 곧 쿼리

직접 선언한 메서드는 이름을 문법대로 해석해서 SQL을 만든다.

existsByDetailInformationCode(String code)
└─┬──┘└┬┘└───────┬───────┘└┬─┘
 exists By  detailInformation .code
 존재여부 조건   필드 경로 (Embedded 안으로 들어감)

SELECT COUNT(*) > 0 FROM feature_flag
WHERE feature_flag_identifier_code = ?

주의할 점은 이름이 DB 컬럼명이 아니라 Java 필드 경로를 따른다는 것이다. findByFeatureFlagIdentifierCode라고 쓰면 그런 필드가 없어서 서버 시작 시 에러가 난다.

직접 만들어 보기

문제 1: ON인 플래그를 전부 조회하기

처음에는 어떻게 써야 할지 감이 오지 않았다. 이미 있는 메서드를 조금씩 고쳐 가는 방식으로 접근하니 풀렸다.

출발점:

Optional<FeatureFlag> findByDetailInformationCode(String code);

1단계: 조건 필드를 code → status로 바꾼다. status도 detailInformation 안에 있으니 이름 끝만 바꾸고, 파라미터 타입도 status 필드 타입에 맞춘다.

Optional<FeatureFlag> findByDetailInformationStatus(FeatureFlagStatus status);

2단계: 여러 개를 받는다. ON인 플래그는 여러 개일 수 있다. Optional은 “0개 또는 1개”라서 결과가 2개 이상이면 에러가 난다.

List<FeatureFlag> findAllByDetailInformationStatus(FeatureFlagStatus status);

All은 읽기 쉽게 붙인 것이고, JPA는 이름보다 반환 타입을 보고 하나를 줄지 여러 개를 줄지 정한다.

SELECT * FROM feature_flag WHERE feature_flag_status = 'ON'

문제 2: OFF인 플래그를 최신순으로 조회하기

기존 메서드 두 개를 합치면 된다.

List<FeatureFlag> findAllByOrderByIdDesc();
List<FeatureFlag> findAllByDetailInformationStatus(FeatureFlagStatus status);

내가 처음 쓴 답:

findAllByOrderByDetailInformationStatusIdDesc(FeatureFlagStatus status);

재료는 맞았는데 순서가 틀렸다.

내 답:  findAll By  OrderBy DetailInformationStatus IdDesc
정답:   findAll By  DetailInformationStatus  OrderBy IdDesc
                 └ 조건(WHERE) ┘        └ 정렬(ORDER BY) ┘

List<FeatureFlag> findAllByDetailInformationStatusOrderByIdDesc(FeatureFlagStatus status);

규칙은 SQL 순서와 같다. 조건(WHERE)이 먼저, 정렬(ORDER BY)이 나중.

SELECT * FROM feature_flag
WHERE feature_flag_status = 'OFF'    -- By DetailInformationStatus
ORDER BY feature_flag_id DESC        -- OrderBy IdDesc

내 답을 JPA는 “조건 없이, detailInformation.status.id로 정렬”로 읽는다. status에는 id가 없으니 서버 시작 시 에러가 난다. 반환 타입(List<FeatureFlag>)도 빠뜨렸다. Java 메서드 선언은 항상 반환타입 이름(파라미터) 형태다.

이름 짓는 공식

반환타입  find(All)  By  [조건 필드들]  OrderBy  [정렬 필드]  Asc|Desc  (파라미터)

조건이 여러 개면 And로 잇는다. 다만 이름이 너무 길어지면 읽기 어려워서, 조건이 복잡하면 @Query나 QueryDSL로 쿼리를 직접 쓴다고 한다. 메서드 이름 방식은 조건 1~2개짜리 간단한 조회용이다.

⑤ 테이블은 누가 만들까? Flyway 마이그레이션

JPA가 테이블을 자동으로 만들 수도 있지만, 실무 프로젝트에서는 SQL 파일로 직접 관리하고 있었다.

src/main/resources/db/migration/
  V202605200001__initial_schema.sql              ← 초기 테이블
  V202607020001__add_featureflag_deleted_at.sql  ← 나중에 컬럼 추가

파일 이름 앞의 V날짜번호가 버전이고, Flyway라는 도구가 아직 실행 안 된 파일을 순서대로 DB에 적용한다. DB용 git 커밋 기록이라고 생각하면 된다.

재미있던 점: 초기 스키마의 feature_flag 테이블에는 deleted_at 컬럼이 없었다. soft delete는 나중에 추가됐고, 그때 이 파일이 생겼다.

ADD COLUMN deleted_at datetime DEFAULT NULL COMMENT '삭제일시';
...
ADD UNIQUE KEY uk_feature_flag_01 (feature_flag_identifier_code, (if(deleted_at is null, true, null)));

마지막 줄은 “code는 중복되면 안 되는데, 삭제된 것끼리는 중복돼도 된다“는 제약이다. soft delete는 지운 행이 남아 있어서, 같은 code로 새 플래그를 만들면 DB가 중복이라고 막는다. 그 문제를 해결한 것이다. 1편에서 본 soft delete가 DB 설계에도 영향을 준 사례다.

그리고 Entity에 필드를 추가하는 것만으로는 DB가 바뀌지 않는다. 컬럼을 추가하려면 마이그레이션 SQL과 Entity 필드를 둘 다 바꿔야 한다. 프론트에서 API 응답 타입만 바꿔도 서버 응답은 안 바뀌는 것과 같다.

정리

다음 글에서는 트랜잭션(@Transactional)을 정리한다. save를 안 불러도 저장되는 변경 감지가 정확히 언제 일어나는지, 중간에 에러가 나면 왜 앞에서 저장한 것까지 취소되는지 알아볼 예정이다.

업무에서 사용자가 여러 창을 띄워 같은 작업을 동시에 진행하다가 브라우저 스토리지의 데이터가 꼬이는 문제를 다룬 적이 있다. 해결책으로 Web Locks API(navigator.locks)를 검토하면서 “이 락은 정확히 어디까지 공유되지?”를 따라가 봤다. 처음에는 origin만 같으면 되는 줄 알았는데, 파고들수록 프로필, 시크릿 창, 컨테이너 탭 같은 경계가 여러 겹으로 나왔다.

이번 글에서는 브라우저가 저장소를 어떤 단위로 나누는지, 그중 프로필이 정확히 무엇이고 브라우저마다 어떻게 다른지, 그리고 웹 개발자 입장에서 무엇을 신경 써야 하는지 정리했다.

① 저장소 경계는 네 겹이다

브라우저가 탭에 저장소를 나눠 주는 경계는 바깥부터 브라우저 설치 → 프로필 → 브라우징 컨텍스트 → 스토리지 키 순서다. 두 탭은 이 네 가지가 모두 같아야 같은 저장소를 쓴다.

하나라도 다르면 localStorage도, Web Locks도 공유되지 않는다. 바깥 층부터 하나씩 살펴보자.

② 프로필의 정체: 디스크 위의 폴더 하나

결론부터 말하면 프로필은 디스크에 있는 폴더 하나다. 그 폴더가 쿠키, localStorage, IndexedDB 같은 사이트 데이터를 통째로 들고 있다.

Chromium 문서를 보면 user data 디렉터리에는 방문 기록, 북마크, 쿠키 같은 프로필 데이터와 설치 단위의 로컬 상태가 들어 있고, 각 프로필은 그 아래의 하위 폴더(보통 Default)다. 프로필을 추가하면 Profile 1, Profile 2 같은 폴더가 생긴다.

지금 쓰는 탭이 어느 프로필인지는 주소창에 chrome://version을 입력해 “프로필 경로” 항목을 보면 바로 알 수 있다.

구글 계정 로그인과는 별개다

나도 처음엔 “프로필 = 구글 계정”이라고 생각했는데, 그렇지 않았다. 계정에 로그인하지 않아도 Chrome은 처음부터 Default 프로필로 동작한다. Google 도움말도 프로필을 북마크, 방문 기록, 비밀번호, 설정을 분리하는 수단으로 설명하고, 계정 로그인은 그 데이터를 다른 기기와 동기화하는 선택 사항으로 다룬다.

즉 로그인은 프로필 위에 동기화를 얹는 기능일 뿐이고, 저장소가 나뉘는 단위에는 영향을 주지 않는다. 프로필을 삭제하면 그 프로필의 데이터가 컴퓨터에서 지워진다는 점도 “프로필 = 로컬 폴더”라는 걸 보여준다.

브라우저 내부에서는

Chromium 코드에서 프로필 하나는 BrowserContext에 대응한다. 그 안에서 실제 저장소를 관리하는 게 StoragePartition인데, 소스 주석은 이를 “각 자식(렌더러) 프로세스가 BrowserContext 안의 영속 상태를 바라보는 뷰”라고 정의한다.

StoragePartitionImpl은 DOM Storage(localStorage), IndexedDB, Cache Storage, Service Worker, BroadcastChannel 같은 컨텍스트를 함께 들고 있다. 탭은 생성될 때 어느 BrowserContext 소속인지 정해지고, 같은 객체를 바라보는 탭끼리만 이 저장소들을 공유한다.

BrowserContext (프로필)
└── StoragePartition
    ├── DOM Storage (localStorage)
    ├── IndexedDB
    ├── Cache Storage
    ├── Service Worker
    └── BroadcastChannel

같은 user data 디렉터리로 Chrome을 한 번 더 실행하면 새 프로세스가 아니라 이미 떠 있는 브라우저로 요청이 넘겨진다. 반대로 --user-data-dir 플래그로 다른 폴더를 지정하면 완전히 별개의 브라우저 인스턴스가 된다.

③ 시크릿 창과 게스트 모드: 잠깐 쓰고 버리는 컨텍스트

시크릿 창과 게스트 모드는 각각 일반 프로필과 분리된 별도의 저장소를 쓰고, 세션이 끝나면 그 저장소를 통째로 버린다.

시크릿 창

시크릿 창을 열면 Chrome은 별도의 브라우징 세션을 시작하고, 이 세션은 시크릿 창을 전부 닫아야 끝난다. 세션 동안에는 사이트가 동작하도록 쿠키와 사이트 데이터를 임시로 보관하고, 세션이 끝나면 지운다. 시크릿 창을 하나 더 열면 새 세션이 아니라 기존 시크릿 세션이 그대로 이어진다.

웹 개발자 관점에서 정리하면 이렇다.

• 같은 프로필에서 연 시크릿 창끼리는 localStorage, IndexedDB, Web Locks를 공유한다.
• 시크릿 창과 일반 창은 서로 공유하지 않는다.
• 마지막 시크릿 창을 닫는 순간 전부 사라지고, 다음에 여는 시크릿 창은 빈 상태에서 시작한다.

Chromium 내부에서 시크릿 세션은 각 일반 프로필에 딸린 off-the-record 프로필로 구현된다. 그래서 프로필이 두 개면 시크릿 세션도 프로필마다 따로 생긴다.

게스트 모드

게스트 모드는 어느 프로필에도 속하지 않는 독립된 임시 컨텍스트다. 게스트 모드에서는 다른 프로필의 정보를 보거나 바꿀 수 없고, 게스트 창을 닫으면 방문 기록, 쿠키, 사이트 데이터가 삭제된다.

게스트 창 안에서 연 탭끼리는 저장소와 락을 정상적으로 공유한다.

“게스트라서 Web Locks가 안 된다”가 아니라, “게스트 창끼리만 공유된다”가 정확한 표현이다.

④ 브라우저별 차이

“프로필로 저장소를 나눈다”는 큰 틀은 같지만, 그 안에서 추가로 나누는 장치와 프라이빗 모드의 동작은 브라우저마다 다르다. 특히 Safari 개인정보 보호 브라우징은 탭끼리도 저장소를 공유하지 않는다.

Edge

Edge는 Chromium 기반이라 프로필, InPrivate, 게스트의 구조가 Chrome과 같다. 디스크 위치만 %LOCALAPPDATA%\Microsoft\Edge\User Data로 다르다. 그래서 같은 PC에서 Chrome과 Edge로 같은 사이트를 열어도 두 탭은 서로를 전혀 모른다.

Edge에서 특히 눈여겨볼 기능은 자동 프로필 전환(Automatic Profile Switching)이다. 개인 프로필에서 회사·학교 계정으로 인증하는 사이트에 들어가면, Edge가 이를 감지해 회사 프로필로 전환하라고 안내하고 선택한 프로필에서 사이트를 연다. 외부 앱에서 여는 링크를 어느 프로필로 열지 기본값도 정할 수 있다.

사용자 입장에서는 “같은 Edge”지만 실제로는 다른 프로필이라 저장소가 공유되지 않는 상황이 생길 수 있다. 사내 업무용 서비스라면 충분히 만날 수 있는 경우라서 기억해 둘 만하다.

그 밖에도 알아둘 것이 두 가지 있다.

• IE 모드 탭은 Chromium이 아니라 예전 IE 엔진으로 렌더링되고 저장소도 별개라서, navigator.locks 같은 최신 API 자체가 없다.
• Edge 엔진을 앱에 임베드하는 WebView2는 user data 폴더(UDF)에 쿠키, 권한, 캐시 같은 데이터를 저장한다. 하나의 UDF 아래 여러 프로필을 둘 수 있고, 프로필마다 전용 폴더가 생겨 데이터가 분리된다. 결국 Edge 브라우저와 WebView2 앱, 그리고 WebView2 앱끼리도 기본적으로 저장소를 공유하지 않는다.

Firefox

Firefox도 가장 바깥 단위는 프로필 폴더다. 흥미로운 건 그 안에서 저장소를 나누는 방식이다.

Firefox는 origin에 OriginAttributes라는 꼬리표를 붙여, origin이 같아도 다른 보안 컨텍스트로 구분한다. 여기에는 이런 값들이 들어간다.

• userContextId: 컨테이너 탭
• privateBrowsingId: 사생활 보호 모드 여부
• partitionKey: 스토리지 파티셔닝

컨테이너 탭은 이 구조를 사용자에게 드러낸 기능이다. 각 컨테이너 탭은 쿠키와 localStorage 같은 저장소를 다른 컨테이너와 따로 쓴다. 즉 Firefox에서는 같은 프로필, 같은 창 안에서도 컨테이너가 다르면 저장소가 분리된다.

Safari

Safari는 17부터 프로필을 지원한다. 프로필마다 방문 기록, 쿠키, 웹사이트 데이터, 확장 프로그램, 탭 그룹, 즐겨찾기가 따로 있고, 처음 프로필을 만들면 기존 데이터는 “개인”이라는 기본 프로필로 들어간다.

정리하면서 가장 놀랐던 부분은 개인정보 보호 브라우징이었다. Apple 도움말은 개인정보 보호 브라우징 창의 각 탭이 서로 격리되어 있다고 설명한다. Chrome 시크릿 창에서는 탭끼리 저장소를 공유하지만, Safari 개인정보 보호 브라우징에서는 같은 사이트를 탭 두 개로 열어도 서로 다른 저장소를 쓴다. 이 경우 Web Locks로 탭끼리 조율하려는 시도는 애초에 성립하지 않는다.

⑤ 프로필 안에서 한 번 더: 스토리지 파티셔닝

같은 프로필 안에서도 저장소는 origin 하나가 아니라 (최상위 사이트, 프레임 origin) 조합으로 다시 나뉜다. 이걸 스토리지 파티셔닝이라고 부른다.

파티셔닝 이전에는 서드파티 iframe이 어느 사이트에 임베드되든 같은 저장소를 써서, 여러 사이트를 넘나드는 추적에 악용될 수 있었다. 지금 Chrome에서는 데이터가 origin도 같고 최상위 사이트도 같은 컨텍스트에서만 보인다.

https://app.example.com 을 탭에서 직접 열면
  → 키: (example.com, app.example.com)

같은 페이지가 https://partner.com 안의 iframe으로 열리면
  → 키: (partner.com, app.example.com)   ← 위의 탭과 저장소·락 공유 안 함

A 사이트 안에 B iframe이 있고, 그 안에 다시 A iframe이 있는 경우도 있다. 최상위와 현재 프레임만 보면 안쪽 A가 1st-party처럼 보이기 때문에, Chrome은 중간에 cross-site 문서가 끼어 있으면 켜지는 “ancestor bit”를 키에 추가로 넣는다.

파티셔닝 대상에는 Web Storage, IndexedDB, Cache Storage, BroadcastChannel, SharedWorker, Web Locks 등이 포함된다. 다만 대부분의 서비스처럼 내 사이트를 최상위 탭으로 여는 경우에는 키가 언제나 같으니, 실무에서 이 층이 문제가 되는 건 다른 사이트에 iframe으로 임베드될 때뿐이다.

⑥ 웹 개발자에게 의미하는 것

탭끼리 무언가를 공유하는 브라우저 API는 전부 저장소 경계를 그대로 따른다. 그래서 “이 API는 어디까지 닿는가”는 “이 탭들이 같은 저장소를 쓰는가”와 같은 질문이다.

Web Locks는 저장소 버킷 단위다

Web Locks 명세는 락 조율이 같은 저장소 버킷을 공유하는 에이전트(탭, iframe, 워커) 사이에서 이루어진다고 정의한다. 각 저장소 버킷은 락 매니저를 하나씩 가지고, 같은 버킷을 쓰는 페이지와 워커는 서로 무관한 창이어도 락 매니저를 공유한다.

이 정의 덕분에 앞에서 본 모든 경계가 락에도 그대로 적용된다. 아래 경우는 모두 락을 공유하지 않는다.

• 다른 프로필
• 시크릿·InPrivate 창, 게스트 창
• Firefox의 다른 컨테이너
• Safari 개인정보 보호 브라우징의 다른 탭
• cross-site iframe

localStorage, IndexedDB, BroadcastChannel도 마찬가지다.

경계가 같아서 오히려 안전한 경우

락이 닿지 않는 곳에는 보통 보호할 공유 자원도 없다. 예를 들어 여러 탭에서 토큰 갱신이 동시에 일어나는 걸 Web Locks로 막는다고 해보자.

게스트 창의 탭들은 게스트 창의 토큰을 같이 쓰고 락도 그 탭들끼리 공유하니, 딱 보호해야 할 범위를 보호한다. 일반 창의 탭은 애초에 토큰이 따로라서 게스트 탭과 경쟁할 일이 없다. 저장소 경계와 락의 경계가 같기 때문에 오히려 자연스럽게 맞아떨어지는 셈이다.

경계 밖의 동시성은 서버 몫이다

문제는 보호하려는 자원이 브라우저 밖에 있을 때다. “같은 작업 건은 한 화면에서만 편집해야 한다” 같은 요구사항이라면, 같은 계정으로 다른 프로필이나 다른 브라우저, 다른 PC에서 들어오는 경우를 프론트에서는 막을 수 없다.

이런 경우는 서버에서 버전 체크(낙관적 락)나 상태 체크로 막아야 한다. 이번에 가장 크게 느낀 부분도 이거였다. 프론트에서 할 수 있는 조율에는 분명한 경계가 있다.

JS로 “같은 저장소인가” 확인하기

웹 페이지가 “지금 몇 번 프로필이다”를 알아낼 방법은 없다. 프라이버시 때문에 의도적으로 노출하지 않는다. 대신 실제로 공유되는지는 직접 확인할 수 있다.

// 창 A: 락을 잡고 놓지 않는다
navigator.locks.request('probe', () => new Promise(() => {}));

// 창 B: 같은 저장소라면 held 목록에 'probe'가 보인다
const { held } = await navigator.locks.query();
console.log(held.some((l) => l.name === 'probe'));

BroadcastChannel로 메시지를 보내서 다른 창이 받는지 보는 것도 같은 원리다. 디버깅할 때 “왜 이 두 창은 락을 공유하지 않지?” 싶으면 이 방법으로 먼저 같은 저장소인지부터 확인하면 된다.

정리

“같은 브라우저에서 열었으니 저장소도 같겠지”라는 가정은 생각보다 자주 틀린다.

브라우저 API로 조율할 수 있는 건 같은 저장소를 쓰는 탭까지이고, 그 밖의 동시성은 서버가 책임져야 한다. 그리고 디버깅할 때는 “두 창이 정말 같은 저장소를 쓰고 있는가”부터 확인하는 게 빠르다.

참고 자료

• User Data Directory — Chromium docs
• storage_partition.h — Chromium source
• Manage Chrome with multiple profiles — Google Chrome Help
• Browse in Incognito mode — Google Chrome Help
• Browse Chrome as a guest — Google Chrome Help
• Automatic profile switching — Microsoft Edge Blog
• Support multiple profiles under a single user data folder — WebView2 docs
• Web Security Checks in Gecko — Firefox source docs
• Multi-Account Containers — Mozilla Support
• Use profiles in Safari on Mac — Apple Support
• Safari Help: Private Browsing
• Storage Partitioning — Chrome for Developers
• privacycg/storage-partitioning — GitHub
• Web Locks API — W3C

@UseCase
@RequiredArgsConstructor
public class DeleteFeatureFlag {
    private final FindFeatureFlag findFeatureFlag;   // 선언만 함

    public void execute(DeleteFeatureFlagCommand command) {
        findFeatureFlag.findFeatureFlag(...);         // 바로 사용함
    }
}

final 필드는 생성자에서 반드시 값을 넣어야 한다. 그런데 생성자도 없고, new DeleteFeatureFlag(...)를 부르는 곳도 없다. 그런데도 null이 아니다. 이 두 가지를 각각 다른 도구가 대신해 준다.

① 생성자는 Lombok이 만든다

@RequiredArgsConstructor는 “final 필드를 모두 받는 생성자를 만들어줘”라는 뜻이다. 컴파일하면 실제로 아래 코드가 생긴다.

public DeleteFeatureFlag(UserApplicationService userService,
                         FindFeatureFlag findFeatureFlag,
                         FindUserFeatureFlagRelation findUserFeatureFlagRelation,
                         LoadFeatureFlagHistory loadFeatureFlagHistory) {
    this.userService = userService;
    this.findFeatureFlag = findFeatureFlag;
    ...
}

② 생성자 호출은 Spring이 한다

서버가 시작될 때 Spring이 하는 일은 이렇다.

1. 찾기: @Component가 붙은 클래스를 전부 찾는다.
2. 분석: 각 생성자를 보고 무엇이 필요한지 파악한다.
3. 조립: 필요한 것부터 new 해서 생성자에 넣어준다.

이렇게 Spring이 만들어 관리하는 객체를 Bean이라고 부른다.

그런데 DeleteFeatureFlag에는 @Component가 아니라 @UseCase가 붙어 있었다. 정의를 열어 보면:

@Component
public @interface UseCase {}

@UseCase는 @Component인데 이름만 바꿔 붙인 것이었다. @RestController, @Repository도 안쪽에 @Component를 갖고 있다. 이름을 다르게 붙여서 코드를 읽을 때 역할이 바로 보이게 한 것이다.

③ 인터페이스 자리에는 구현체를 찾아서 넣는다

FindFeatureFlag는 인터페이스라 new 할 수 없다. Spring은 “FindFeatureFlag를 implements 한 Bean이 있나?” 하고 찾는다.

@Repository
public class FeatureFlagRepository implements LoadFeatureFlag, FindFeatureFlag, ExistFeatureFlag

하나 찾았으니 이걸 넣는다. 서버가 켜질 때의 조립 순서를 그려 보면 이렇다.

FeatureFlagJpaRepository     (JPA가 자동 생성)
        ↓ 주입
FeatureFlagRepository        (@Repository) ── FindFeatureFlag 자리에 들어감
        ↓ 주입
DeleteFeatureFlag            (@UseCase)
        ↓ 주입
FeatureFlagController        (@RestController)

DeleteFeatureFlag 코드에는 FeatureFlagRepository라는 이름이 한 번도 나오지 않는다. 그런데도 동작한다. 이게 “UseCase는 DB를 모른다”가 실제로 구현되는 방식이다. 그리고 Java는 implements를 명시해야 그 타입으로 인정하기 때문에(명목적 타이핑), Spring이 구현체를 정확히 찾을 수 있다.

프론트로 비유하면

// Spring이 서버 시작 시 해주는 일을 직접 쓴다면
const repo = new FeatureFlagRepository(jpa);
const deleteUseCase = new DeleteFeatureFlag(userService, repo, ...);
const controller = new FeatureFlagController(..., deleteUseCase);

이 조립 코드를 사람이 쓰지 않고 Spring이 자동으로 해준다. React의 Context Provider로 의존성을 내려주는 것과 비슷한데, 클래스가 수천 개라서 손으로 조립하는 건 사실상 불가능하다.

만약 @Repository를 지우면?

FeatureFlagRepository에서 @Repository를 지우면, Spring은 이 클래스를 관리해야 하는지 자체를 모르게 된다. 그러면:

FeatureFlagRepository     ❌ Bean 아님 (아무도 안 만듦)
        ↓
DeleteFeatureFlag         "FindFeatureFlag 넣어줘" → 구현한 Bean이 없음 → 💥

***************************
APPLICATION FAILED TO START
***************************
Parameter 1 of constructor in ...DeleteFeatureFlag required a bean of type
'...FindFeatureFlag' that could not be found.

API 하나만 안 되는 게 아니라 서버 전체가 켜지지 않는다. 런타임에 null로 터지는 대신 시작 시점에 바로 실패하는 게 DI의 장점이다. 프론트로 치면 런타임 undefined is not a function 대신 빌드 에러로 잡히는 셈이다.

이 에러를 보면 어노테이션이 빠졌거나, 구현체가 없구나를 먼저 의심하면 된다.

④ Bean은 서버 전체에서 하나 (싱글톤)

이번 공부에서 가장 중요하다고 느낀 부분이다.

Spring은 각 Bean을 딱 한 번만 만든다. 사용자 100명이 동시에 삭제 요청을 보내도 DeleteFeatureFlag 객체는 하나고, 100개의 요청이 동시에 그 객체의 execute()를 호출한다.

이렇게 쓰면 안 된다

private Long currentUserId;   // ❌ Bean의 필드에 요청 데이터 저장

public void execute(DeleteFeatureFlagCommand command) {
    this.currentUserId = command.getUserId();
    ...
    featureFlag.delete(this.currentUserId);
}

처음 이 퀴즈를 받았을 때는 “delete에 userId를 넘기는 게 맞나?”를 묻는 줄 알았다. delete(userId)가 userId를 받는 건 맞다. 누가 삭제했는지 기록(updatedBy)하기 위해서다. 문제는 그게 아니라 userId를 필드에 저장했다는 것이었다.

사용자 A와 B가 거의 동시에 삭제를 누르면:

시간 →     DeleteFeatureFlag 객체 (서버에 1개뿐, 둘이 공유)
           currentUserId 필드

A 요청:    currentUserId = A
B 요청:                    currentUserId = B   ← A의 값을 덮어씀
A 요청:                                        delete(currentUserId) → B로 기록됨 ❌
B 요청:                                        delete(currentUserId) → B

A가 지웠는데 DB에는 B가 지운 것으로 남는다. 에러도 나지 않고, 동시에 요청이 와야만 생겨서 테스트에서도 거의 재현되지 않는다. 이런 문제를 동시성 문제(race condition) 라고 한다.

프론트 코드로 바꾸면 이런 상황이다.

let currentUserId: number;   // 모듈 최상단 변수 = 모두가 공유

export async function deleteFlag(userId: number) {
  currentUserId = userId;
  await something();          // 이 사이에 다른 호출이 currentUserId를 바꿈
  save(currentUserId);
}

브라우저는 사용자 한 명이 쓰니까 이런 문제가 거의 없다. 하지만 서버는 한 프로세스가 수많은 사용자의 요청을 동시에 처리한다. 프론트에서 백엔드로 넘어오면서 가장 크게 바꿔야 하는 감각이 이거라고 느꼈다.

올바른 방식

public void execute(DeleteFeatureFlagCommand command) {
    Long userId = command.getUserId();   // 지역 변수 = 이 요청에서만 존재
    ...
    featureFlag.delete(userId);
}

메서드 안의 지역 변수는 호출할 때마다 새로 생기기 때문에 다른 요청과 섞이지 않는다.

규칙: Bean(@UseCase, @Repository, @RestController)의 필드에는 다른 Bean만 넣고, 요청 데이터는 항상 파라미터나 지역 변수로 다룬다.

정리

다음 글에서는 메서드 이름만 써도 SQL이 만들어지는 JPA를 정리한다.