Yeong Rok n roll

Django 운영 코드 정리: 보안, 테스트, i18n, 계정 복구

Sat, 09 May 2026 20:00:00 +0900

들어가며

이전 글에서는 Life Diary의 뷰에 몰린 처리 흐름을 Use Case와 Repository로 옮기고, 통계 쿼리와 캐시, 세션 설정을 정리한 과정을 다뤘다.

그 작업의 중심은 기능 처리 흐름과 비용이었다.

뷰가 너무 많은 일을 알고 있었고, 통계 계산은 점점 무거워졌으며, 반복 쿼리와 세션 write도 줄일 필요가 있었다. 그래서 시간 기록 저장 흐름을 Use Case로 옮기고, ORM 조회는 Repository에 모았고, 통계 캐시와 DB 연결 설정도 함께 정리했다.

하지만 거기서 끝나지는 않았다.

기능 흐름과 비용을 정리하고 나니, 그동안 뒤로 미뤄두었던 운영 코드가 보이기 시작했다.

통계 데이터를 템플릿에 넘기는 방식은 안전한가.
반복적인 로그인 실패를 제한하고 있는가.
테스트 코드는 계속 유지하기 쉬운가.
다국어 메시지는 한국어 하드코딩에서 벗어났는가.
계정 복구 과정에서 사용자 존재 여부를 노출하고 있지는 않은가.
메일 발송 실패가 그대로 500 에러로 이어지지는 않는가.

이번 글은 그 문제들을 정리한 기록이다.

1차 리팩토링이 기능 처리 흐름과 비용을 정리한 작업이었다면, 이번 작업은 보안, 테스트, i18n, 계정 복구처럼 운영 중 문제가 될 수 있는 부분을 정리한 작업이다.

1. 통계 JSON을 `|safe`로 넘기던 문제

Life Diary의 통계 화면은 JavaScript를 사용한다.

서버에서 계산한 통계 데이터를 템플릿에 넘기고, 브라우저에서는 그 데이터를 읽어 차트나 통계 UI를 그린다.

초기 구현에서는 JSON 데이터를 템플릿에 직접 넣기 위해 |safe를 사용했다.

{{ stats_data|safe }}

기능은 동작했다.

서버에서 만든 JSON이 브라우저에 전달되었고, JavaScript에서도 문제없이 읽을 수 있었다. 하지만 이 방식은 운영 관점에서 다시 봐야 했다.

|safe는 Django의 escaping을 우회한다.
데이터가 정말 안전하다고 확신할 수 있을 때만 사용해야 한다.

통계 데이터라고 해서 항상 안전한 것은 아니다.
태그명, 메모, 사용자 입력값이 일부 포함될 수 있다면 HTML 또는 JavaScript 문맥에서 문제가 생길 수 있다.

특히 저장된 사용자 입력이 나중에 통계 JSON에 섞여 화면에 다시 삽입된다면 저장형 XSS 위험으로 이어질 수 있다.

그래서 json_script로 변경했다.

{{ stats_data|json_script:"stats-data" }}

JavaScript에서는 다음처럼 읽는다.

const statsData = JSON.parse(
  document.getElementById("stats-data").textContent
);

이 방식은 JSON 데이터를 HTML 안에 넣되, JavaScript 코드로 직접 실행되지 않도록 다룬다. 화면에서 보이는 기능은 거의 바뀌지 않는다. 하지만 데이터 전달 방식은 더 안전해진다.

이번 수정에서 중요한 점은 기능을 새로 만든 것이 아니라는 점이다.

사용자는 차이를 느끼지 못할 수 있다.
하지만 운영하는 입장에서는 차이가 크다.

기능이 정상 동작한다고 해서 안전한 구현은 아니다.
특히 사용자 입력이 HTML이나 JavaScript 문맥에 들어가는 경우에는 더 조심해야 한다.

2. 로그인 실패를 제한하기

로그인 기능은 이미 있었다.

하지만 로그인 기능이 있다는 것과 로그인 시도를 안전하게 다룬다는 것은 다르다.

아이디와 비밀번호를 입력받는 화면이 있다면 반복적인 로그인 실패도 처리해야 한다.
그렇지 않으면 공격자가 여러 비밀번호를 계속 시도할 수 있다.

Life Diary에는 이를 보완하기 위해 django-axes를 도입했다.

django-axes는 로그인 실패를 추적하고, 설정한 기준을 넘으면 추가 시도를 제한할 수 있게 해준다.

예를 들어 같은 사용자명 또는 같은 IP에서 로그인 실패가 반복되면 일정 시간 동안 로그인을 막을 수 있다.

이 작업은 복잡한 기능은 아니다.
하지만 로그인 기능을 외부에 열어둔 서비스라면 기본적으로 확인해야 할 부분이다.

개인 프로젝트라고 해도 로그인과 사용자 데이터를 다루면 책임이 생긴다.
서비스 규모가 작다고 해서 로그인 공격 가능성이 사라지는 것은 아니다.

이번 작업에서는 로그인 실패 제한을 추가하면서 다음 기준을 확인했다.

- 로그인 실패 횟수를 추적할 수 있는가
- 일정 기준을 넘었을 때 추가 시도를 제한하는가
- 잠금 상태에서 사용자에게 과도한 정보를 주지 않는가
- 운영 로그로 실패 흐름을 확인할 수 있는가

로그인은 단순히 성공과 실패만 처리하면 끝나는 기능이 아니었다.
실패가 반복될 때 어떻게 제한할지도 함께 봐야 했다.

3. CDN 스크립트에 SRI 추가하기

Life Diary는 일부 정적 리소스를 CDN으로 불러온다.

CDN을 사용하면 빠르고 편하다.
하지만 외부에서 가져오는 스크립트라면 무결성도 확인해야 한다.

그래서 CDN 스크립트에 SRI hash를 추가했다.

<script
  src="..."
  integrity="..."
  crossorigin="anonymous">
</script>

SRI는 Subresource Integrity의 약자다.
브라우저가 외부 리소스를 불러올 때, 실제 파일이 예상한 해시와 일치하는지 확인한다.

해시가 맞지 않으면 브라우저는 해당 리소스를 실행하지 않는다.

CDN을 쓴다고 해서 항상 문제가 생기는 것은 아니다.
하지만 외부 스크립트가 변조되었을 때의 영향은 크다.

특히 JavaScript는 브라우저에서 직접 실행된다.
사용자 화면과 입력값에 접근할 수 있기 때문에, 외부 스크립트를 사용할 때는 최소한의 검증 장치를 두는 편이 낫다.

이번 수정도 화면 기능을 바꾸는 작업은 아니었다.
하지만 운영 기준에서는 필요한 작업이었다.

4. pytest를 쓰지만 pytest답지 않았던 테스트

Life Diary에는 테스트가 있었다.

문제는 테스트가 없는 것이 아니었다.
테스트를 계속 유지하기 불편한 상태였다는 점이다.

테스트 러너는 pytest였지만, 테스트 코드 작성 방식은 unittest에 가까웠다.
각 테스트마다 사용자 생성, 로그인 처리, 기본 데이터 생성, 언어 설정, 클라이언트 준비 코드가 반복되었다.

예를 들면 이런 준비 코드가 여러 테스트에 흩어져 있었다.

- 테스트 사용자 생성
- 로그인 처리
- 기본 태그 생성
- 날짜별 기록 생성
- 언어 설정
- 클라이언트 준비

준비 코드가 길어지면 테스트 본문에서 무엇을 검증하는지 잘 보이지 않는다.

주간 통계 화면을 확인하는 테스트라면, 테스트 본문에서는 주간 통계와 관련된 내용이 중심이 되어야 한다. 그런데 사용자 생성과 로그인 코드가 길게 들어가면 테스트의 의도가 흐려진다.

그래서 fixture 중심으로 정리했다.

factory
auth_client
en_client
ko_client

인증된 사용자가 필요한 테스트에서는 auth_client를 사용했다.

def test_user_can_view_weekly_stats(auth_client):
    response = auth_client.get(...)
    assert response.status_code == 200

영어 화면이 필요한 테스트에서는 en_client를 사용했다.

def test_feedback_message_is_rendered_in_english(en_client):
    ...

한국어 화면이 필요한 테스트에서는 ko_client를 사용했다.

def test_feedback_message_is_rendered_in_korean(ko_client):
    ...

이렇게 바꾸면 테스트 본문에서 준비 과정이 줄어든다.
테스트 이름과 fixture만 봐도 어떤 상황에서 무엇을 확인하는지 더 빨리 읽을 수 있다.

이번 정리로 111개의 테스트를 유지하면서 테스트 코드 LOC를 약 14% 줄였다.

LOC 감소 자체가 핵심은 아니다.
중요한 것은 테스트를 읽는 비용이 줄었다는 점이다.

테스트는 기능을 보호하기 위해 존재한다.
그런데 테스트 코드가 너무 장황하면 기능을 고칠 때마다 테스트를 고치는 일도 부담이 된다.

이번 정리의 목적은 테스트를 줄이는 것이 아니었다.
테스트가 계속 유지될 수 있게 만드는 것이었다.

5. 테스트 정리 중 발견한 locale leak

테스트를 fixture 중심으로 정리하면서 locale leak 문제도 확인했다.

다국어 기능이 있는 서비스에서는 언어 설정이 테스트 간에 섞이지 않도록 주의해야 한다.
한 테스트에서 한국어를 활성화했는데, 다음 테스트가 그 영향을 그대로 받으면 테스트 결과가 환경에 따라 달라질 수 있다.

예를 들어 영어 메시지를 기대하는 테스트가 있다고 하자.

이전 테스트에서 한국어가 활성화된 상태로 남아 있으면, 영어 메시지를 기대한 테스트에서 한국어 메시지가 나올 수 있다. 이런 문제는 테스트 순서에 따라 실패하거나 통과할 수 있어 더 위험하다.

테스트가 순서에 의존하면 신뢰하기 어렵다.

그래서 언어별 클라이언트를 분리하고, 테스트가 끝난 뒤 언어 상태가 남지 않도록 정리했다.

def test_feedback_message_is_rendered_in_english(en_client):
    ...

def test_feedback_message_is_rendered_in_korean(ko_client):
    ...

다국어 테스트에서 중요한 것은 번역 결과만 확인하는 것이 아니다.

각 테스트가 독립적으로 실행될 수 있어야 한다.
한국어 테스트가 영어 테스트에 영향을 주면 안 되고, 영어 테스트가 한국어 테스트에 영향을 주면 안 된다.

이번에 테스트 코드를 정리하지 않았다면 이 문제는 더 늦게 발견되었을 가능성이 크다.

테스트 정리는 단순히 코드 줄 수를 줄이는 일이 아니었다.
숨은 의존을 찾는 작업이기도 했다.

6. i18n은 문자열 치환만으로 끝나지 않았다

Life Diary는 한국어를 기본으로 만들었다.

처음에는 대부분의 문구가 한국어로 직접 작성되어 있었다.
템플릿, Python 코드, JavaScript 안에 문자열이 흩어져 있었다.

다국어 지원을 위해 먼저 기본적인 작업을 진행했다.

템플릿에는 {% trans %}를 적용했다.

{% trans "Today" %}

Python 코드에서는 gettext_lazy를 사용했다.

from django.utils.translation import gettext_lazy as _

JavaScript에서 필요한 번역은 JavaScriptCatalog를 사용했다.

여기까지는 일반적인 i18n 작업이었다.

진짜 문제는 동적 피드백 메시지였다.

Life Diary는 사용자의 기록을 분석해서 피드백을 만든다.

예를 들면 이런 메시지다.

운동 시간이 30분 부족합니다.
공부 시간이 어제보다 늘었습니다.
수면 시간이 목표보다 적습니다.

처음에는 Python 코드에서 바로 문장을 만들 수 있다.

message = f"{tag_name} 시간이 {minutes}분 부족합니다."

구현은 쉽다.
하지만 언어가 늘어나면 문제가 생긴다.

첫째, gettext가 문자열을 안정적으로 추출하기 어렵다.
둘째, 언어마다 문장 순서가 다르다.
셋째, 비즈니스 로직과 표시 문구가 결합된다.
넷째, 언어를 추가할 때 Python 코드를 계속 수정하게 된다.

그래서 메시지를 완성된 문장이 아니라 코드와 파라미터로 표현했다.

LocalizableMessage(
    code="feedback.goal.low",
    params={
        "tag_name": tag_name,
        "minutes": minutes,
    },
    severity="warning",
)

Python 코드에서는 어떤 메시지인지와 필요한 값만 만든다.
실제 문장은 번역 파일에서 관리한다.

기존 방식은 이렇다.

Python 코드에서 직접 문장 생성

바꾼 방식은 이렇다.

Python 코드는 메시지 코드와 파라미터만 생성
번역 파일에서 언어별 문장 관리

이렇게 바꾸면 일본어를 추가하더라도 Python 비즈니스 로직을 크게 수정하지 않아도 된다.

i18n 작업에서 중요한 것은 단순히 문구를 번역하는 것이 아니었다.
문장을 만드는 책임이 어디에 있는지 정리하는 일이었다.

7. 계정 복구 기능 추가

운영 중인 서비스라면 계정 복구 흐름도 필요하다.

사용자는 아이디를 잊을 수 있고, 비밀번호를 잊을 수 있다.
로그인에 실패했을 때 다시 서비스로 돌아올 수 있는 경로가 있어야 한다.

Life Diary에는 아이디 찾기와 비밀번호 재설정 기능을 추가했다.

처음에는 단순한 기능처럼 보인다.

이메일을 입력받는다.
계정을 찾는다.
메일을 보낸다.
완료 페이지를 보여준다.

하지만 여기에도 조심해야 할 부분이 있다.

계정 존재 여부를 사용자에게 그대로 알려주면 안 된다.

예를 들어 다음 방식은 좋지 않다.

가입된 이메일:
비밀번호 재설정 메일을 보냈습니다.

가입되지 않은 이메일:
해당 이메일로 가입된 계정이 없습니다.

이렇게 응답하면 공격자는 특정 이메일이 서비스에 가입되어 있는지 확인할 수 있다.

그래서 입력값과 관계없이 동일한 완료 페이지로 이동하도록 했다.

가입된 이메일:
메일 발송 후 완료 페이지 이동

가입되지 않은 이메일:
메일 발송 없이 완료 페이지 이동

사용자에게 보이는 응답은 같다.
내부 처리만 달라진다.

이 방식은 사용자에게 약간 덜 친절해 보일 수 있다.
하지만 계정 존재 여부를 노출하지 않는 쪽이 더 안전하다.

계정 복구는 단순 편의 기능이 아니었다.
인증 흐름의 일부였고, 보안 기준도 함께 봐야 하는 기능이었다.

8. SMTP 실패를 500으로 끝내지 않기

계정 복구 기능을 추가하면서 메일 발송 실패도 다뤄야 했다.

비밀번호 재설정 메일이나 아이디 찾기 메일은 SMTP에 의존한다.
SMTP는 외부 시스템이다. 외부 시스템은 실패할 수 있다.

초기에는 메일 발송 실패가 그대로 500 에러로 이어질 수 있었다.

이 방식은 좋지 않다.

사용자는 계정 복구를 시도했는데 서버 에러 화면을 보게 된다.
운영자는 어떤 입력에서 어떤 메일 발송이 실패했는지 로그로 확인하기 어렵다.

그래서 사용자 응답과 운영 로그를 분리했다.

사용자 응답:
동일한 완료 페이지 제공

운영 로그:
SMTP 실패 원인 기록

사용자에게는 안정적인 흐름을 제공한다.
운영자는 로그를 통해 실패 원인을 확인한다.

여기서 중요한 점은 실패를 숨기는 것이 아니다.

사용자에게 불필요한 내부 오류를 그대로 보여주지 않고, 운영자가 확인할 수 있는 방식으로 남기는 것이다.

외부 시스템에 의존하는 기능은 실패를 예상해야 한다.
메일 발송, 결제, 외부 API, CDN은 모두 실패할 수 있다.

따라서 이런 기능은 성공 흐름만 만들면 부족하다.
실패했을 때 사용자에게 무엇을 보여주고, 운영자는 무엇을 확인할 수 있는지까지 정해야 한다.

9. 이번 작업에서 남긴 기준

이번 작업은 새 기능을 많이 추가하는 작업이 아니었다.

이미 있던 기능을 운영 기준으로 다시 확인하는 작업에 가까웠다.

정리하면서 남긴 기준은 다음과 같다.

- 사용자 입력이 HTML/JS 문맥에 직접 들어가지 않게 한다.
- 로그인 실패는 추적하고 제한한다.
- 외부 스크립트는 무결성을 확인한다.
- 테스트 준비 코드는 fixture로 모은다.
- 언어 설정은 테스트 간에 섞이지 않게 한다.
- Python 코드에서 완성된 번역 문장을 직접 만들지 않는다.
- 계정 존재 여부를 응답으로 노출하지 않는다.
- 외부 시스템 실패는 사용자 응답과 운영 로그를 분리한다.

하지만 실제 서비스를 운영할 때는 이런 부분이 문제를 줄인다.
화면에 보이는 기능보다, 보이지 않는 처리 방식이 더 중요할 때가 있다.

통계 화면이 잘 보이는 것만으로는 충분하지 않다.
그 통계 데이터가 안전하게 전달되어야 한다.

로그인 기능이 되는 것만으로는 충분하지 않다.
실패가 반복될 때 제한할 수 있어야 한다.

테스트가 있는 것만으로는 충분하지 않다.
계속 읽고 수정할 수 있어야 한다.

다국어 문구가 출력되는 것만으로는 충분하지 않다.
언어가 추가되어도 비즈니스 로직을 계속 고치지 않아야 한다.

계정 복구 메일이 발송되는 것만으로는 충분하지 않다.
계정 존재 여부를 노출하지 않고, 메일 실패도 처리해야 한다.

마무리

1차 리팩토링에서는 Life Diary의 기능 처리 흐름과 비용을 정리했다.

이번 작업에서는 그 이후 남은 운영 코드를 정리했다.

보안, 테스트, i18n, 계정 복구는 처음 기능을 만들 때는 뒤로 밀리기 쉽다.
하지만 배포 후에는 계속 따라오는 문제다.

이번 작업을 통해 확인한 내용은 다음과 같다.

- 기능이 동작해도 안전하지 않은 구현이 있을 수 있다.
- 테스트는 작성하는 것보다 유지하기 쉬운 상태로 만드는 것이 중요하다.
- i18n은 문자열 번역보다 문장 생성 책임을 나누는 일이 더 중요했다.
- 계정 복구는 편의 기능이 아니라 인증 흐름의 일부다.
- 외부 시스템 실패는 사용자 응답과 운영 로그를 분리해야 한다.

Django 리팩토링 기록: 뷰, 유스케이스, 그리고 비용 최적화

Sat, 25 Apr 2026 20:00:00 +0900

들어가며

Django로 프로젝트를 시작할 때 처음부터 복잡한 설계를 고민하기는 어렵다.

처음에는 뷰에서 요청을 받고, 모델을 조회하고, 필요한 검증을 거쳐 응답을 반환하는 정도로도 충분하다. 오히려 빠르고 자연스럽다. Django의 장점도 여기에 있다. 적은 코드로 기능을 만들 수 있고, 화면과 데이터의 움직임을 한눈에 확인할 수 있다.

불편함은 프로젝트가 조금씩 커진 뒤에 드러난다.

처음에는 단순한 저장 로직이었던 코드에 권한 검증이 붙고, 중복 처리와 트랜잭션이 붙고, 통계 캐시 무효화가 붙는다. 특정 화면에서만 쓰이던 조회 로직은 다른 화면에서도 필요해지고, 하나의 앱에서 시작한 데이터는 어느새 다른 앱의 계산 결과와 연결된다.

뷰는 요청을 받아 응답하는 입구라기보다, 서비스의 여러 판단을 함께 떠안는 위치가 된다.

Life Diary도 그랬다.

Life Diary는 하루를 10분 단위로 기록하고, 그 기록을 태그와 통계로 다시 읽어보는 생활 로그 서비스다. 사용자는 하루 144개의 시간 슬롯 중 일부를 선택하고, 태그와 메모를 붙여 자신의 시간을 기록한다. 이후 기록 데이터는 목표, 통계, 피드백 화면으로 이어진다.

처음에는 가벼웠다.

하지만 기능이 붙으면서 기록은 더 이상 기록만으로 끝나지 않았다. 기록이 바뀌면 통계도 바뀌어야 했고, 통계는 목표 달성률과 연결되었고, 목표는 다시 마이페이지와 연결되었다. 여기에 캐시, 세션, DB 쿼리 수, 배포 비용 같은 운영상의 부담도 따라왔다.

새로운 아키텍처 이름을 붙이고 싶었던 것은 아니다. 이미 동작하는 기능을 더 잘 설명할 수 있는 형태로 옮기고 싶었다.

뷰에 섞여 있던 처리 순서를 덜어내고, 기능 단위의 로직은 Use Case로 옮기고, ORM 조회는 Repository에 모았다. 동시에 통계 계산과 인프라 사용량처럼 운영에서 드러나는 부담도 함께 줄이고자 했다.

리팩토링을 시작하면서 붙잡은 질문은 하나였다.

Django 프로젝트가 커질 때, 뷰는 어디까지 책임져야 하는가.

뷰가 무거워지기 시작한 순간

Django에서 뷰는 가장 자연스러운 출발점이다.

요청을 받는다.
파라미터를 읽는다.
모델을 조회한다.
검증한다.
저장한다.
응답을 반환한다.

처음에는 충분히 빠르고 직관적이다. 파일을 많이 나누지 않아도 되고, 기능의 흐름도 한눈에 보인다. 다만 기능이 늘어난 뒤에도 같은 형태를 유지하면 불편함이 쌓이기 시작한다.

Life Diary의 핵심 기능은 시간 기록이다. 사용자는 하루 144개의 10분 슬롯 중 일부를 선택하고, 태그와 메모를 저장한다. 겉으로 보면 단순한 저장 API처럼 보인다.

하지만 실제 처리 순서는 단순하지 않았다.

사용자가 보낸 슬롯 인덱스가 0부터 143 사이인지 확인해야 한다.
메모 길이가 너무 길지 않은지 확인해야 한다.
선택한 태그가 기본 태그이거나 본인 소유 태그인지 확인해야 한다.
이미 기록된 슬롯이면 수정해야 하고, 비어 있는 슬롯이면 새로 생성해야 한다.
저장이 끝나면 해당 날짜의 통계 캐시를 무효화해야 한다.

검증, 권한 확인, 저장 분기, 캐시 무효화가 모두 뷰에 있으면 뷰는 더 이상 단순한 HTTP 입구가 아니다. 사실상 하나의 기능 전체를 직접 처리하게 된다.

당장 동작하지 않는 것은 아니다.

오히려 잘 동작한다.
그래서 더 늦게 불편함이 드러난다.

코드가 길어지고, 검증 규칙이 흩어지고, 테스트가 HTTP 요청과 응답에 강하게 묶인다. 핵심 로직만 따로 검증하기 어렵고, 변경이 생겼을 때 어디를 고쳐야 하는지도 점점 흐려진다.

불편했던 것은 뷰의 길이 자체가 아니었다.

진짜 부담은 뷰가 너무 많은 판단 근거를 알고 있다는 데 있었다.

뷰에 남길 것과 옮길 것

“뷰를 얇게 만들자”는 말은 자주 듣는다.

하지만 조금 모호하다. 단순히 뷰의 코드 줄 수를 줄인다고 좋은 구조가 되지는 않는다. 핵심은 뷰가 어떤 일을 맡고, 어떤 일을 넘길지 정하는 데 있다.

이번 리팩토링에서 뷰에 남기고 싶었던 일은 많지 않았다.

요청을 파싱한다.
Command 객체를 만든다.
Use Case를 호출한다.
결과를 응답으로 바꾼다.

반대로 뷰에서 덜어내고 싶었던 일은 다음과 같았다.

태그 접근 권한 확인.
기존 데이터와 신규 데이터의 분기 처리.
트랜잭션 경계 설정.
통계 캐시 무효화.
여러 Repository를 조합하는 처리 순서.

태그 권한 확인, 저장 분기, 캐시 무효화는 HTTP 요청 자체보다 기능의 처리 순서에 더 가깝다. 사용자가 “시간을 기록한다”는 기능은 API 요청으로 들어오든, 나중에 다른 인터페이스를 통해 들어오든 본질적으로 크게 달라지지 않는다.

그래서 시간 기록 저장 과정을 뷰 밖으로 옮기기로 했다.

옮겨간 위치가 Use Case였다.

Use Case로 옮긴 처리 흐름

Use Case라는 이름은 다소 거창하게 들릴 수 있다.

하지만 Life Diary에서 Use Case는 특별한 아키텍처 장치라기보다, 뷰에 섞여 있던 처리 순서를 옮겨 놓는 용도에 가까웠다.

시간 기록 저장을 예로 들면, 기존 뷰에는 입력 검증, 태그 권한 확인, 기존 슬롯 조회, 신규 생성, 기존 수정, 캐시 무효화가 함께 들어 있었다. 입력 검증부터 캐시 무효화까지 이어지는 과정은 HTTP 요청 처리라기보다, “시간 기록 저장” 기능 자체의 처리 순서에 가까웠다.

그래서 입력 검증, 권한 확인, 저장 분기, 캐시 무효화를 Use Case로 옮겼다.

리팩토링 후 처리 경로는 대략 이렇게 바뀌었다.

HTTP Request
  -> views.py
  -> use_cases.py
  -> repositories.py / domain_services.py
  -> models.py
  -> DB

각 파일의 역할도 이전보다 분명해졌다.

views.py는 요청 파싱과 응답 반환을 담당한다. use_cases.py는 기능 하나의 처리 순서를 담당한다. repositories.py는 ORM 쿼리를 담당한다. domain_services.py는 정책 판단과 계산을 담당한다. models.py는 데이터 제약과 저장 규칙을 가진다.

목표는 완전한 클린 아키텍처가 아니었다. 그 정도의 층위를 감당해야 할 규모도 아니었다.

Django 프로젝트 안에서 각 코드가 맡을 일을 조금 더 분명하게 나누고 싶었다. 뷰가 모든 것을 직접 알지 않게 하고, 기능 처리 순서는 Use Case로 옮기고, DB 조회는 Repository에 모았다.

그 결과, 코드를 따라가는 길이 조금 달라졌다.

예전에는 뷰를 읽으면서 “여기서 무엇을 검증하고, 어디서 저장하고, 왜 이런 응답이 나가는가”를 한 번에 따라가야 했다. 이제는 뷰를 보면 어떤 Use Case로 넘어가는지 보이고, Use Case를 보면 기능 하나의 처리 순서가 보인다.

코드를 읽을 때 정말 중요한 것은 파일의 길이만이 아니다.

어디를 읽어야 무엇을 알 수 있는지가 분명해야 한다.

일부만 저장될 수 있는 위험 줄이기

리팩토링 초기에 먼저 본 부분은 트랜잭션이었다.

시간 기록 저장은 새 슬롯을 만들 수도 있고, 기존 슬롯을 수정할 수도 있다. 내부적으로는 bulk_create와 bulk_update가 함께 사용된다. 그런데 두 작업 중 하나만 성공하고 다른 하나가 실패하면 어떻게 될까.

사용자는 하나의 저장 요청을 보냈지만, DB에는 일부만 반영될 수 있다.

겉으로는 구현 방식의 차이처럼 보이지만, 실제로는 데이터가 반쯤 저장될 수 있는 위험이었다.

그래서 쓰기 Use Case에는 transaction.atomic을 적용했다. 사용자의 한 번의 기록 요청은 DB에서도 하나의 단위로 처리되어야 한다. 성공하면 모두 반영되고, 실패하면 모두 되돌아가야 한다.

고민은 트랜잭션을 어디에 둘 것인가였다.

뷰에 둘 수도 있다. Repository에 둘 수도 있다. 하지만 Life Diary에서는 Use Case에 두는 편이 가장 자연스러웠다.

Repository는 저장 방법을 안다. Use Case는 저장 과정 전체를 안다.

따라서 “처리 전체가 하나의 단위로 성공해야 한다”는 판단은 Use Case에 두는 편이 더 적절했다.

구조를 바꾸는 일은 추상적인 설계 문제가 아니었다. 실제로 데이터가 잘못 남을 수 있는 지점을 줄이는 작업이었다.

bulk_create가 놓치는 검증 지점

Django 모델에 clean()을 작성하면 모든 저장 경로에서 검증이 항상 실행될 것처럼 느껴진다.

하지만 실제로는 그렇지 않다.

bulk_create는 개별 모델 인스턴스의 full_clean()을 호출하지 않는다. 따라서 모델에 적어둔 검증 규칙이 있다고 해서 모든 저장 경로에서 자동으로 보장되지는 않는다.

Life Diary에서는 시간 블록이 반드시 0부터 143 사이의 슬롯 인덱스를 가져야 한다. 또한 태그는 기본 태그이거나 본인 소유 태그여야 한다. 모델에도 의미 있는 규칙이지만, 실제 저장 경로가 bulk_create라면 저장 이전 경계에서 명시적으로 검증하는 편이 안전하다.

그래서 Command DTO를 두었다.

UpsertTimeBlocksCommand는 사용자의 입력을 Use Case로 넘기기 전에 검증한다. 슬롯 목록은 비어 있으면 안 되고, 각 슬롯은 0부터 143 사이여야 하며, 메모는 정해진 길이를 넘으면 안 된다.

단순히 Pydantic을 쓰고 싶어서가 아니었다.

입력 검증의 위치를 분명히 하기 위한 선택이었다.

사용자의 요청은 불안정하다. DB에 들어가는 데이터는 안정적이어야 한다. 그 사이에는 검증 경계가 필요하다.

Command DTO는 그 경계를 담당한다.

조회 로직을 한곳에 모은 이유

Repository 패턴을 이야기하면 종종 이런 질문이 따라온다.

Django ORM을 굳이 감싸야 할까?

타당한 질문이다. Django ORM은 이미 충분히 강력하고, 모델 매니저도 잘 되어 있다. 모든 쿼리를 기계적으로 Repository로 감싸면 불필요한 코드만 늘어날 수 있다.

그럼에도 Life Diary에서 Repository를 둔 이유는 ORM을 완전히 숨기기 위해서가 아니었다.

조회 의도를 한곳에 모으기 위해서였다.

예를 들어 시간 기록은 여러 곳에서 조회된다. 대시보드에서는 특정 날짜의 기록이 필요하고, 통계에서는 기간별 기록이 필요하고, 태그 삭제에서는 해당 태그가 사용 중인지 확인해야 한다.

쿼리가 각 뷰와 서비스에 흩어져 있으면 같은 개념을 서로 다른 방식으로 조회하게 된다. 반대로 Repository에 모아두면 조회 방식에 이름이 생긴다.

find_by_date find_by_date_range find_by_slots is_tag_in_use

find_by_date, find_by_date_range 같은 이름은 조회 목적을 드러낸다. 그리고 쿼리 최적화를 적용할 위치도 분명해진다.

이번 리팩토링에서 주간 통계는 기존에 날짜별 조회를 7번 수행하던 구조에서, 기간 조회 한 번으로 가져온 뒤 Python에서 그룹핑하는 방식으로 바뀌었다. Repository에 조회 코드가 모여 있었기 때문에 비교적 안전하게 바꿀 수 있었다.

Repository는 ORM을 감추기 위한 장치라기보다, 여러 곳에서 쓰이는 조회 방식을 한곳에서 관리하기 위한 선택이었다.

통계 화면이 생각보다 복잡했던 이유

처음에는 통계 기능도 단순해 보였다.

하루 기록을 합산한다. 주간 기록을 합산한다. 월간 기록을 합산한다. 태그별 시간을 보여준다.

하지만 실제로는 통계가 가장 무거운 영역 중 하나였다.

통계는 dashboard의 시간 기록을 읽는다. users의 목표를 읽는다. 최근 메모도 읽는다. 목표 달성률을 계산한다. 미분류 시간을 포함한다. 마지막에는 규칙 기반 피드백까지 생성한다.

즉, stats는 단순 조회 화면이 아니라 여러 앱의 데이터를 다시 조립하는 영역에 가까웠다.

문제는 StatsCalculator가 점점 비대해졌다는 점이다. 날짜 범위 계산, 태그 정보 추출, 빈 슬롯 계산, 미분류 데이터 주입, 일간·주간·월간·분석 통계 처리가 한곳에 모이기 시작했다.

처음에는 편하다. 하지만 시간이 지나면 수정하기 어려워진다.

그래서 stats/aggregation 아래로 계산 흐름을 나누었다.

일간 통계는 daily. 주간 통계는 weekly. 월간 통계는 monthly. 태그 분석은 analysis.

daily, weekly, monthly, analysis로 나눈 것은 단순한 파일 분리가 아니었다. 통계라는 큰 기능을 시간 단위와 분석 목적에 따라 다시 나눈 것이다.

좋은 분리는 파일 수를 늘리는 것이 아니다.

나중에 수정할 때 어디를 봐야 할지 예측할 수 있게 만드는 것이다.

순환 참조가 없어도 의존성은 불편해질 수 있다

리팩토링 전 구조에 명확한 순환 참조가 있었던 것은 아니다.

하지만 그렇다고 의존성이 좋은 상태였던 것도 아니다.

대표적인 예가 users와 stats의 관계였다. 마이페이지는 사용자의 목표와 최근 메모를 보여주면서, 목표 달성률도 함께 보여줘야 했다. 그러다 보니 users.views가 stats.logic을 직접 호출하는 구조가 생겼다.

겉으로 보기에는 동작한다.

하지만 의미상으로는 어색했다. 사용자 앱이 통계 앱의 내부 계산 로직을 직접 알고 있었기 때문이다.

users.views가 stats.logic을 직접 호출한다고 해서 당장 오류가 생기지는 않는다. 그러나 시간이 지나면 변경을 어렵게 만든다. stats.logic의 내부 구성을 바꾸려 할 때, 통계 화면뿐 아니라 마이페이지까지 함께 고려해야 한다.

그래서 Use Case를 도입하면서 마이페이지 처리도 함께 정리했다.

마이페이지는 GetMyPageUseCase를 통해 필요한 목표와 메모, 목표 달성률을 조립하도록 바꾸었다. 필요한 통계도 모든 기간을 무조건 계산하지 않고, 사용자의 목표 period에 따라 필요한 것만 계산하도록 했다.

마이페이지에서 필요한 통계만 계산하도록 바꾸자, 앱 간 의존도 줄고 불필요한 계산도 줄었다.

목표가 daily만 있으면 weekly와 monthly까지 계산할 필요가 없다. monthly 목표만 있으면 daily와 weekly 계산은 낭비다.

코드를 나누는 일이 성능 개선과 만나는 지점이었다.

코드뿐 아니라 쿼리와 세션도 정리했다

개인 프로젝트에서는 비용 문제를 뒤로 미루기 쉽다.

사용자가 많지 않으니 괜찮다고 생각한다. 트래픽이 작으니 큰 문제가 아니라고 생각한다. 하지만 무료 또는 저가 인프라 위에서 운영하는 프로젝트일수록 작은 비효율이 더 빨리 눈에 들어온다.

Life Diary는 Render와 Supabase를 사용한다. 이 환경에서는 DB 쿼리 수, 세션 write, 연결 재사용, 캐시 전략이 모두 운영 부담과 연결된다.

특히 통계 페이지는 비용이 큰 기능이었다. 같은 날짜의 같은 사용자가 통계를 다시 조회할 때마다 동일한 계산을 반복할 필요는 없다. 과거 날짜의 기록은 거의 변하지 않는다. 오늘 날짜의 기록은 자주 변할 수 있다.

그래서 캐시 TTL을 다르게 가져갔다.

과거 날짜는 24시간. 오늘 날짜는 5분.

과거 24시간, 오늘 5분이라는 기준은 기술적으로 복잡하지 않다. 하지만 서비스의 성격을 반영한다. 과거의 기록은 안정적이고, 오늘의 기록은 유동적이다.

또한 시간 기록이 저장되거나 삭제되면 해당 날짜의 통계 캐시를 무효화한다. 캐시 무효화는 Use Case 내부에서 처리했다. 시간 기록 변경이라는 처리를 가장 잘 아는 곳이 Use Case이기 때문이다.

세션 설정도 바꾸었다. 요청마다 세션을 저장하면 DB write가 불필요하게 늘어난다. 그래서 SESSION_SAVE_EVERY_REQUEST를 끄고, DB 연결은 CONN_MAX_AGE를 통해 재사용하도록 했다.

세션 write를 줄이고 DB 연결을 재사용하는 일은 화려하지 않다.

하지만 실제 서비스를 운영할 때는 이런 작은 선택들이 비용과 안정성에 영향을 준다.

개선 효과는 측정해야 알 수 있다

다만 조심해야 할 점이 있다.

쿼리 수를 줄이고, 캐시를 넣고, 세션 write를 줄였다고 해서 효과가 자동으로 증명되는 것은 아니다. 구조상 더 나아졌다고 말할 수는 있지만, 실제 운영에서 얼마나 좋아졌는지는 측정해야 한다.

그래서 다음 단계로 MetricsMiddleware를 도입하려고 했다.

요청 경로, HTTP 메서드, 응답 상태, 응답 시간, 사용자 ID 같은 정보를 구조화 로그로 남기면 Render 로그에서 /stats/ 응답 시간을 비교할 수 있다. Supabase 대시보드에서는 세션 write, DB egress, 쿼리 수 추이를 볼 수 있다.

성능과 비용을 이야기할 때 감각만으로는 부족하다.

“좋아졌을 것이다”와 “좋아졌다”는 다르다.

이번 리팩토링에서 비용 최적화는 아직 구조적 가설에 가깝다. 실제 효과는 로그와 대시보드로 확인해야 한다. 그래서 문서에도 측정이 남은 과제로 정리해 두었다.

좋은 리팩토링 기록은 “무엇을 했다”만 적지 않는다.

아직 무엇을 확인하지 못했는지도 함께 남겨야 한다.

일부러 하지 않은 것들

이번 리팩토링에서 중요했던 것은 무엇을 적용했는가만이 아니었다.

무엇을 적용하지 않았는지도 중요했다.

Redis를 도입하지 않았다. Celery를 도입하지 않았다. DRF로 전환하지 않았다. django-ninja를 붙이지 않았다. Domain Events를 만들지 않았다. CQRS나 Read Replica도 도입하지 않았다.

Redis나 Celery를 붙일 만큼의 복잡도는 아직 없었다.

리팩토링을 하다 보면 구성을 더 멋지게 만들고 싶은 욕심이 생긴다. Use Case를 만들었으니 이벤트도 만들고 싶고, Repository를 만들었으니 더 엄격한 포트와 어댑터 구조를 만들고 싶고, 캐시를 넣었으니 Redis도 붙이고 싶어진다.

하지만 좋은 구조는 많은 기술을 붙인 구조가 아니다.

현재 불편한 지점을 해결하는 만큼만 복잡해진 구조가 좋은 구조다.

Life Diary의 현재 문제는 대규모 트래픽이 아니었다. 백그라운드 작업이 많은 것도 아니었다. 여러 클라이언트를 위한 거대한 API 서버도 아니었다.

불편했던 지점은 뷰의 역할이 커지고, 통계 계산이 무거워지고, 앱 간 의존이 흐려지고, 비용 최적화 지점이 흩어지는 것이었다.

그러면 그 부분만 먼저 다루면 된다.

정리 후에 보인 다음 과제

리팩토링을 했다고 해서 코드가 완벽해지는 것은 아니다.

오히려 정리하고 나면 이전에는 보이지 않던 다음 작업이 더 잘 보인다.

운영 설정에서 확인해야 할 부분이 있다. DEBUG 설정은 배포 전 반드시 복구해야 한다. 캐시가 실제로 어느 정도 효과를 내는지도 측정해야 한다. 구조화 로그와 MetricsMiddleware를 통해 응답 시간과 캐시 히트율을 봐야 한다. AJAX 경로와 통계 캐시 TTL, 로그인 잠금 시나리오에 대한 테스트도 더 보강해야 한다. CSP, 세션 쿠키 플래그, 비밀번호 정책 같은 보안 후속 작업도 남아 있다.

남은 과제가 보인다고 해서 리팩토링이 실패했다는 뜻은 아니다.

오히려 좋은 신호에 가깝다. 남은 작업이 더 구체적인 이름을 갖기 시작했기 때문이다.

막연히 “코드가 복잡하다”가 아니라, “MetricsMiddleware로 실측이 필요하다”, “AJAX 목표 저장 경로의 회귀 테스트가 필요하다”, “통계 캐시 TTL 분기를 테스트해야 한다”처럼 말할 수 있게 되었다.

리팩토링의 효과는 단순히 코드가 정리되는 데 있지 않다.

다음에 무엇을 해야 하는지 더 분명해지는 데 있다.

좋은 리팩토링은 이유가 남는다

이번 작업을 하면서 다시 느낀 것은, 리팩토링은 단순히 코드의 모양을 바꾸는 일이 아니라는 점이다.

좋은 개선은 이유를 설명할 수 있어야 한다.

왜 뷰를 얇게 만들었는가. 왜 Use Case를 두었는가. 왜 Repository를 만들었는가. 왜 Command DTO를 사용했는가. 왜 트랜잭션은 Use Case에 두었는가. 왜 통계 캐시는 오늘과 과거의 TTL을 다르게 가져갔는가. 왜 Redis를 도입하지 않았는가. 왜 DRF로 전환하지 않았는가.

위 질문들에 답하기 어렵다면, 구조를 충분히 검토하지 못했을 가능성이 있다.

반대로 답할 수 있다면, 설령 완벽한 구조가 아니더라도 의미가 있다. 지금 프로젝트의 제약 안에서 어떤 선택을 했고, 무엇을 미뤘고, 어떤 위험을 먼저 줄였는지 설명할 수 있기 때문이다.

Life Diary의 리팩토링은 거대한 아키텍처 전환이 아니었다. Django 프로젝트 안에서 역할을 조금 더 나누고, 데이터 정합성과 운영 부담을 함께 다루고, 다음 개선 지점을 드러나게 만드는 과정이었다.

결국 이번 리팩토링을 한 문장으로 정리하면 이렇다.

기능은 이미 동작하고 있었지만, 그 기능이 왜 그렇게 동작해야 하는지 설명하기 어려워지고 있었다. 그래서 코드를 옮겼다.

AI 시대에 개발자는 사라지는가, 아니면 더 높은 레이어로 이동하는가

Mon, 06 Apr 2026 20:00:00 +0900

들어가며

AI 시대에 개발자의 역할을 둘러싼 논의는 대체로 두 극단으로 흐르기 쉽다.

한쪽에서는 이제 코드를 치는 일은 대부분 자동화될 것이므로 개발자라는 직업 자체가 빠르게 축소될 것이라고 말한다. 다른 한쪽에서는 AI는 결국 보조 도구일 뿐이며, 개발자의 역할은 본질적으로 달라지지 않는다고 말한다.

그러나 이 두 주장 모두 절반만 맞다.

지금 실제로 벌어지고 있는 변화는 “개발자가 사라진다”와 “아무것도 변하지 않는다” 사이 어딘가에 있다. AI는 이미 코드를 꽤 잘 생성한다. 더 나아가 저장소를 읽고, 이슈를 이해하고, 수정 패치를 제안하는 단계까지 들어왔다. 즉, 코딩은 이미 가장 먼저 흔들리는 업무 중 하나가 되었다고 보는 편이 정확하다.

하지만 여기서 바로 “그러므로 개발자는 필요 없어질 것이다”라는 결론으로 점프하면 중요한 구분 하나를 놓치게 된다. AI가 잘하는 것은 점점 더 많아지고 있지만, 소프트웨어 엔지니어링 전체가 곧바로 AI에게 넘어간 것은 아니다. 오늘날의 AI는 구현 노동의 상당 부분을 빠르게 잠식하고 있지만, 문제를 정의하고, 제약을 설정하고, 품질을 검증하고, 시스템 전체의 책임을 지는 역할까지 완전히 가져가지는 못하고 있다.

그리고 여기에 하나를 더 추가해야 한다.

AI 시대에는 개발자의 커뮤니케이션 능력이 오히려 더 중요해진다.

많은 사람들은 AI가 코드 생산성을 높이면 개발자는 더 적게 말하고 더 많이 만들 수 있을 것이라고 생각한다. 그러나 실제로는 그 반대다. AI가 구현을 빠르게 해줄수록, 팀은 더 자주 “무엇을 만들어야 하는가”, “이 변경의 의도는 무엇인가”, “어디까지를 이번 범위로 볼 것인가”, “이 설계의 리스크는 무엇인가”를 언어로 명확히 합의해야 한다.

즉, AI는 구현 비용을 낮춘다.
그 대신 정확하게 설명하고, 합의하고, 정렬하는 능력의 가격을 올린다.

결국 핵심 질문은 이것이다.

AI 시대에 개발자는 사라지는가?
내 생각은 그렇지 않다.
다만 개발자의 가치가 생성되는 위치는 분명히 이동한다.

코드를 짜는 능력과 소프트웨어를 만드는 능력은 다르다

많은 논의가 엉키는 이유는 “코드를 짜는 능력”과 “소프트웨어를 만드는 능력”을 같은 것으로 보기 때문이다.

코드는 소프트웨어의 일부다. 그러나 소프트웨어 엔지니어링은 코드보다 훨씬 넓다. 무엇을 만들 것인지, 왜 그렇게 만들어야 하는지, 어떤 제약 아래에서 동작해야 하는지, 실패했을 때 어디가 터질 수 있는지, 운영 비용은 감당 가능한지, 보안과 데이터 정합성은 어떤 식으로 보장할지 같은 질문은 코드 몇 줄만으로 해결되지 않는다. 구현은 이 전체 과정의 마지막에 가까운 층위다.

AI가 강해질수록 이 구분은 더 중요해진다. 왜냐하면 구현이 쉬워질수록, 구현 이전의 사고 과정이 더 본질적인 경쟁력이 되기 때문이다.

그리고 이 사고 과정은 머릿속에만 있어서는 안 된다. 팀 개발에서 사고는 결국 언어가 되어야 한다. 요구사항 정의, 설계 문서, PR 설명, 리뷰 코멘트, 장애 보고, 의사결정 기록은 모두 생각을 언어로 바꾸는 작업이다.

결국 소프트웨어를 잘 만든다는 것은 단지 좋은 코드를 쓰는 것이 아니라, 좋은 판단을 타인과 공유 가능한 형태로 바꾸는 것까지 포함한다.

AI가 가장 먼저 먹어치우는 일은 무엇인가

AI가 잘하는 일에는 공통점이 있다.

명세가 비교적 분명하고, 패턴이 많고, 피드백 루프가 짧고, 로컬에서 바로 확인 가능한 일일수록 강하다.

예를 들어 다음과 같은 일이다.

CRUD API의 반복 구현
UI 컴포넌트 초안 작성
테스트 코드 스캐폴딩
문서화 초안
리팩토링 후보 제안
에러 메시지를 단서로 한 1차 수정 시도

이 영역에서는 이미 “사람이 처음부터 끝까지 손으로 쓰는 방식”이 비효율적일 때가 많다. 이제 단순 반복 구현은 빠르게 외주화될 수 있는 영역이 되었다.

하지만 이 변화는 동시에 다른 병목을 만든다. 예전에는 구현 속도가 느려서 문제 정의의 빈틈이 늦게 드러났다. 지금은 구현이 빨라서 문제 정의의 빈틈이 훨씬 빨리 드러난다.

예를 들어, 팀이 “사용자 경험을 개선하자”라는 모호한 말을 하고 바로 AI를 붙여 기능을 만들기 시작하면 어떤 일이 벌어질까. 아마 초안은 매우 빨리 나올 것이다. 그러나 그 초안은 대개 팀이 각자 다르게 상상한 “개선”을 반영하게 된다. 어떤 사람은 응답 속도를 떠올리고, 어떤 사람은 UI를 떠올리고, 어떤 사람은 알림 정책을 떠올리고, 어떤 사람은 이탈률을 떠올린다.

예전에는 구현 속도가 느려서 중간중간 말을 섞으며 방향을 수정할 시간이 있었다. 지금은 잘못된 이해가 곧바로 코드와 화면과 API로 증식한다.

그래서 AI 시대의 생산성 문제는 단순히 “얼마나 빨리 만들 수 있는가”가 아니다. 오히려 얼마나 빨리 같은 그림을 보게 만들 수 있는가에 가깝다.

그래서 개발자의 핵심 역할은 어디로 이동하는가

내가 보기에는 여섯 가지다.

1. 문제를 정의하는 사람

AI는 답안을 잘 만들 수 있지만, 질문을 잘 세우는 일은 여전히 사람 쪽에 더 가깝다.

무엇이 문제인지, 그 문제가 실제 비즈니스 문제인지, 아니면 단지 국소적인 불편인지, 지금 풀어야 하는지, 나중으로 미뤄도 되는지, 어떤 품질 기준을 만족해야 하는지 정의하는 일은 여전히 상위 레이어의 작업이다.

AI 시대에는 이 문제가 더 커진다. 구현 단가가 낮아지기 때문이다. 전에는 잘못된 아이디어를 구현하는 데 시간이 오래 걸려서 중간에 멈출 기회라도 있었지만, 지금은 잘못된 방향으로도 너무 빨리 갈 수 있다.

따라서 개발자는 단순한 구현자가 아니라, 무엇을 만들지 결정하는 필터가 되어야 한다.

2. 제약을 설계하는 사람

좋은 개발자는 정답을 직접 쓰는 사람이라기보다, 시스템이 엉뚱한 방향으로 가지 않게 제약을 거는 사람이다.

타입, 테스트, 스키마, 권한 모델, 트랜잭션 경계, API 계약, 장애 허용 범위, 로깅 규칙, 배포 절차는 전부 제약이다. AI는 이런 제약이 주어졌을 때 더 잘 동작한다. 반대로 제약이 느슨하면 그럴듯하지만 위험한 코드를 빠르게 양산한다.

이 점에서 테스트와 문서는 더 이상 후행 작업이 아니다. 그것들은 AI 이후 시대의 생산성 장치이자 안전장치다.

3. 문맥을 연결하는 사람

실무의 어려움은 대개 코드 한 파일 안에 있지 않다. 저장소 구조, 기존 관례, 도메인 규칙, 인프라 제약, 데이터 이력, 팀의 배포 리듬 같은 것들이 얽혀 있다.

AI는 이 문맥을 어느 정도 따라오지만, 아직도 문맥의 우선순위를 판단하는 데에는 약하다. 무엇이 핵심 제약이고 무엇이 우연한 구현인지, 어디를 건드리면 사이드 이펙트가 터지는지, 어떤 기술 부채는 지금 갚고 어떤 부채는 의도적으로 미뤄야 하는지를 판단하는 일은 여전히 사람의 몫이다.

그래서 앞으로의 강한 개발자는 “코드를 많이 아는 사람”보다 “문맥의 연결점을 잘 아는 사람”에 가까워질 것이다.

4. 검증하고 책임지는 사람

AI의 확산은 검증 책임을 없애지 않는다. 오히려 더 무겁게 만든다.

왜냐하면 속도가 빨라질수록 잘못된 코드가 들어올 확률도 함께 커지기 때문이다. 사람은 느리지만, 적어도 자기가 무슨 생각을 하면서 짰는지는 어느 정도 추적 가능하다. 반면 AI가 만든 코드는 빠르게 많이 들어오고, 근거가 약한 채로도 그럴듯해 보이기 쉽다.

따라서 앞으로 더 중요한 개발자는 “코드를 작성하는 사람”보다 코드를 믿어도 되는 상태로 만드는 사람이다.

5. 운영과 현실을 이해하는 사람

AI는 로컬 성공을 잘 만든다.
하지만 서비스는 로컬 성공만으로 굴러가지 않는다.

실제 서비스는 장애가 나고, 트래픽이 튀고, 데이터가 꼬이고, 사람이 예상과 다르게 행동하고, 조직은 완벽한 리팩토링보다 오늘의 출시를 더 원할 때가 많다.

구현은 싸졌지만, 실패 비용은 여전히 비싸다. 그래서 운영 감각을 가진 개발자의 가치는 오히려 올라간다.

6. 팀을 정렬시키는 사람

여기서 가장 중요하게 추가해야 할 역할이 있다. 바로 팀을 정렬시키는 사람이다.

커뮤니케이션 능력을 흔히 “말을 잘하는 능력” 정도로 오해한다. 하지만 개발에서 커뮤니케이션은 그런 것이 아니다. 개발자의 커뮤니케이션은 본질적으로 정렬 능력이다.

서로 다른 이해관계자가 같은 문제를 보게 만드는 능력
모호한 요구사항을 충돌 없는 문장으로 바꾸는 능력
설계 선택의 이유를 팀이 납득할 수 있게 설명하는 능력
지금 당장 필요한 합의와 나중에 미뤄도 되는 합의를 구분하는 능력
기술 언어와 비즈니스 언어를 오가며 번역하는 능력

AI 시대에는 이 능력이 훨씬 더 중요해진다. 왜냐하면 구현은 빨라졌지만, 사람들의 머릿속을 맞추는 일은 여전히 느리기 때문이다.

결국 팀의 실제 병목은 종종 코드가 아니라 대화에 있다. 요구사항이 모호하고, 설계 의도가 기록되지 않고, PR에 맥락이 없고, 리뷰가 단순 취향 싸움으로 흐르고, 장애가 났을 때 사실과 해석이 섞여버리면, 아무리 AI가 코드를 빨리 생성해도 팀의 생산성은 오르지 않는다.

반대로 커뮤니케이션이 좋은 팀은 AI의 속도를 제대로 흡수한다. 문제가 잘 정의되고, 결정이 잘 기록되고, 변경의 의도가 공유되고, 리뷰 기준이 명확하므로 AI가 만든 초안도 빠르게 좋은 결과물로 수렴한다.

즉, AI는 커뮤니케이션을 덜 중요하게 만들지 않는다. 오히려 커뮤니케이션이 약한 팀과 강한 팀의 격차를 더 크게 벌린다.

AI 시대의 커뮤니케이션은 무엇이 달라지는가

여기서 말하는 커뮤니케이션은 “분위기 좋게 대화하기”와는 조금 다르다. 물론 그것도 중요하지만, 개발자에게 더 중요한 것은 아래와 같은 능력이다.

1. 모호함을 줄이는 능력

좋은 개발자는 막연한 요구를 구체적인 문장으로 바꾼다.

예를 들어 “성능을 개선해달라”는 말은 너무 모호하다. 응답 시간을 말하는 것인지, 처리량을 말하는 것인지, DB 부하를 말하는 것인지, 사용자 체감 속도를 말하는 것인지 다르다.

AI는 이런 모호함을 알아서 해결해주지 못한다. 대신 그 모호함 위에 매우 그럴듯한 구현을 올려놓는다.

그래서 앞으로 더 강한 개발자는 말을 많이 하는 사람이 아니라, 모호한 말을 정확한 작업 단위로 바꾸는 사람이다.

2. 설계 의도를 설명하는 능력

AI가 코드를 초안으로 잘 만들어줄수록, “왜 이 구조를 택했는가”를 설명하는 능력이 중요해진다.

구현은 눈에 보인다.
하지만 의도는 설명되지 않으면 사라진다.

왜 이 트랜잭션 경계를 선택했는지, 왜 동기 처리가 아니라 비동기로 넘겼는지, 왜 지금은 추상화를 도입하지 않았는지, 왜 테스트를 이 수준까지만 작성했는지 같은 설명은 팀의 유지보수 비용을 좌우한다.

결국 좋은 개발자는 코드를 남기는 사람인 동시에, 타인이 다음 결정을 내릴 수 있을 만큼 충분한 맥락을 남기는 사람이다.

3. 비기술 직군과 번역하는 능력

AI 시대에는 PM, 디자이너, 사업 담당자도 더 빠르게 시제품을 만지고 아이디어를 제안할 수 있게 된다. 이것은 좋은 변화이지만 동시에 충돌 가능성도 키운다.

아이디어는 많아지고, 실행은 빨라지고, 기대치는 높아진다. 이럴수록 개발자는 “그건 안 됩니다”라고 막는 사람이 아니라, 무엇은 가능하고, 무엇은 위험하며, 무엇은 어떤 비용으로 가능한가를 번역하는 사람이 되어야 한다.

기술을 기술 언어로만 말하면 팀은 갈라진다. 비즈니스만 비즈니스 언어로 말해도 시스템은 무너진다. 강한 개발자는 이 둘 사이를 오간다.

4. 비동기 협업을 잘하는 능력

AI 도구의 확산은 오히려 비동기 커뮤니케이션의 중요성을 높인다.

왜냐하면 많은 변경이 더 빨리, 더 자주, 더 작은 단위로 일어나기 때문이다. 그래서 “머릿속에는 있는데 말 안 한 것”, “회의 때만 공유된 것”, “PR에는 없는 설계 의도”가 점점 더 치명적인 비용이 된다.

좋은 비동기 커뮤니케이션은 다음과 같은 형태를 가진다.

이 변경이 왜 필요한지 명확하다
이번 범위와 다음 범위가 구분된다
리뷰어가 어디를 봐야 하는지 드러난다
리스크와 미해결 포인트가 적혀 있다
결정이 나중에도 다시 읽힐 수 있게 남는다

이런 능력은 화려하지 않다.
하지만 팀 생산성을 결정한다.

백엔드 개발자에게 특히 중요한 이유

백엔드 개발자에게 이 변화는 더 직접적이다.

CRUD, 인증, 라우팅, ORM 매핑, 스키마 초안, 테스트 초안 같은 일은 점점 더 AI가 빠르게 처리한다. 이제 “이 정도는 손으로 빨리 칠 수 있다”는 장점은 빠르게 희미해진다. 대신 차별화는 다른 곳에서 생긴다.

예를 들어 이런 역량이다.

도메인 모델링
데이터 정합성 설계
시스템 경계 설정
관측 가능성 확보
검증 가능한 구조 설계
설계 의도를 문서와 대화로 남기는 능력
장애 상황에서 사실을 정리하고 팀을 안정시키는 능력

특히 백엔드에서는 커뮤니케이션이 더 중요하다. 왜냐하면 백엔드의 문제는 종종 눈에 잘 보이지 않기 때문이다.

프론트엔드는 화면으로 드러나는 경우가 많지만, 백엔드는 트랜잭션, 정합성, 동시성, 재시도, 메시지 전달 보장, 캐시 일관성, 배치 타이밍처럼 눈에 보이지 않는 제약을 다룬다. 이런 제약은 설명되지 않으면 팀원에게 잘 전달되지 않는다. 설명되지 않은 제약은 곧 잘못된 기대를 만든다. 잘못된 기대는 결국 장애나 일정 지연으로 돌아온다.

그래서 백엔드 개발자는 단순히 “깊이 있는 기술자”만으로는 부족하다.
보이지 않는 위험을 보이게 말할 수 있는 기술자여야 한다.

예를 들어 이런 식이다.

“이건 기능은 간단해 보여도 멱등성을 보장하지 않으면 중복 처리 위험이 있습니다.”
“여기서는 즉시 일관성보다 최종 일관성을 택하는 편이 운영 비용이 낮습니다.”
“이번 스프린트에서는 구조를 완성하기보다 장애 가능성이 큰 지점부터 관측 가능하게 만들겠습니다.”
“이 변경은 API 스펙보다 데이터 계약 변화가 핵심이므로, 관련 소비자까지 같이 봐야 합니다.”

이런 문장은 단순한 설명이 아니다. 팀의 기대를 조정하고, 잘못된 오해를 줄이고, 실패 비용을 미리 낮추는 행위다.

AI 시대에 약해지는 개발자와 강해지는 개발자

AI 시대에 약해지는 개발자는 대체로 다음과 같은 특징을 가진다.

첫째, 구현량을 자신의 주된 경쟁력으로 삼는다.
둘째, 왜 그렇게 설계했는지 설명하기보다 “일단 되게 만들기”에 머문다.
셋째, 테스트와 문서를 귀찮은 후행 작업으로 본다.
넷째, 운영 문제를 남의 일로 생각한다.
다섯째, AI가 준 결과를 빠르게 수용하지만 느리게 검증한다.
여섯째, 머릿속으로는 많이 알고 있지만 팀이 이해할 수 있는 언어로 정리하지 못한다.

반대로 강해지는 개발자는 정반대다.

첫째, 구현을 목적이 아니라 수단으로 본다.
둘째, 문제 정의와 제약 설정에 시간을 쓴다.
셋째, 테스트·문서·계약을 생산성 저하 요인이 아니라 속도 증폭 장치로 본다.
넷째, 운영과 장애를 설계의 일부로 본다.
다섯째, AI를 “대신 생각해주는 존재”가 아니라 “빠르게 시도하게 해주는 존재”로 쓴다.
여섯째, 설계 의도와 리스크를 타인과 공유 가능한 형태로 남긴다.

이 마지막 차이가 점점 더 커질 것이다.

AI는 혼자 일하는 천재를 더 강하게 만들 수도 있다. 하지만 실무에서 더 큰 차이를 만드는 것은 대개 팀 전체를 더 똑똑하게 만드는 사람이다. 그리고 그런 사람은 대체로 커뮤니케이션이 좋은 사람이다.

결국 개발자는 사라지지 않는다. 다만 더 높은 레이어로 밀려 올라간다

AI는 개발자 일을 덜 중요하게 만드는 것이 아니라, 개발자 일의 분포를 재배치하고 있다.

직접 구현하는 시간은 줄어든다. 대신 문제를 정의하는 시간, 제약을 설계하는 시간, AI가 만든 결과를 검증하는 시간, 운영 리스크를 다루는 시간, 팀의 공통 문맥을 정리하는 시간이 늘어난다.

그리고 나는 여기에 하나를 더 분명히 덧붙이고 싶다.

앞으로 개발자의 경쟁력은 기술력과 커뮤니케이션 능력으로 나뉘지 않는다.
좋은 개발자의 커뮤니케이션은 기술력의 바깥이 아니라 안쪽에 있다.

요구사항을 정확히 묻는 능력,
설계를 납득 가능하게 설명하는 능력,
PR에 충분한 맥락을 남기는 능력,
리뷰를 취향이 아니라 기준으로 이끄는 능력,
장애 상황에서 사실과 해석을 분리해 전달하는 능력,
기술적 리스크를 비기술 직군도 이해할 수 있게 번역하는 능력.

이 모든 것은 “소프트 스킬”이라는 말로 가볍게 묶기에는 너무 핵심적이다. 오히려 이것들은 AI 시대의 하드한 생산성 스킬에 가깝다.

AI가 강해질수록, 코드를 많이 치는 사람보다 문제를 더 정확히 정의하고, 판단 근거를 더 명확히 설명하고, 팀을 더 빠르게 정렬시키는 사람이 강해질 것이다.

그리고 사실 좋은 개발자는 원래부터 그런 사람이었다. 다만 이제는 그 사실이 훨씬 더 노골적으로 드러나고 있을 뿐이다.

마치며

AI는 개발자를 없애기보다, 개발자에게 더 불편한 질문을 던진다.

당신은 정말 문제를 이해하고 있는가.
당신은 왜 그 구조를 선택했는가.
당신은 이 코드를 신뢰할 근거를 가지고 있는가.
당신은 시스템이 실패할 때 무엇이 무너질지 알고 있는가.
그리고 당신은 그 모든 것을 타인이 이해할 수 있는 언어로 설명할 수 있는가.

예전에는 이런 질문을 피해도 어느 정도는 버틸 수 있었다. 구현 자체가 느리고 비쌌기 때문이다. 그러나 지금은 구현이 너무 빨라졌다. 그래서 오히려, 구현 뒤에 숨어 있던 얕은 이해와 불충분한 대화가 더 빨리 드러난다.

나는 그래서 AI 시대의 개발자를 비관적으로 보지 않는다.
다만 낭만적으로도 보지 않는다.

앞으로 살아남는 개발자는 더 많이 치는 사람이 아니라,
더 정확하게 정의하고,
더 엄격하게 검증하고,
더 선명하게 설명하는 사람일 것이다.

그리고 그 변화는 이미 시작되었다.

Cosmic Python 제2부: CQRS, 의존성 주입, 그리고 에필로그

Tue, 24 Mar 2026 10:00:00 +0900

Chapter 12: CQRS (Command-Query Responsibility Segregation)

지금까지 우리는 커맨드와 이벤트를 분리하고, 메시지 버스로 유스케이스를 통합했다. 그런데 한 가지 의문이 남는다.

도메인 모델은 비즈니스 로직을 위해 설계된 건데, 이걸 데이터 조회에도 그대로 쓰는 게 맞을까?

답은 “아니다”이다. 읽기와 쓰기는 근본적으로 다르기 때문이다.

왜 읽기와 쓰기를 분리해야 할까?

구분	쓰기(Command)	읽기(Query)
목적	상태 변경, 비즈니스 규칙 적용	데이터 조회, 화면 표시
복잡도	복잡한 도메인 로직 필요	단순한 데이터 반환
일관성	트랜잭션 일관성 필수	약간의 지연(stale) 허용 가능
캐싱	캐싱 불가	캐싱 가능

도메인 모델은 “비즈니스가 어떻게 동작하는가”를 표현한 것이지, “데이터를 어떻게 보여줄 것인가”를 표현한 게 아니다.

그런데 읽기 요청에 도메인 모델을 쓰면? Aggregate를 통째로 로딩하고, 관계를 탐색하고, 필터링하고… 단순히 “주문 목록 보여줘”에 불필요한 오버헤드가 붙는다.

사실 완벽하게 동기화된 시스템이라도, 페이지가 렌더링되는 순간 이미 데이터는 과거의 것이다. “사용자가 화면을 보는 시점”과 “실제 데이터 상태”는 이미 다르다.

이게 CQRS의 출발점이다. 어차피 읽기 데이터는 약간 stale할 수밖에 없으니, 쓰기 모델과 분리해서 각각 최적화하자.

읽기 모델의 4가지 구현 방법

방법 A: Repository 패턴 그대로 사용

def allocations(orderid: str, uow: AbstractUnitOfWork):
    with uow:
        products = uow.products.for_order(orderid=orderid)
        batches = [b for p in products for b in p.batches]
        return [
            {"sku": b.sku, "batchref": b.reference}
            for b in batches
            if orderid in b.orderids
        ]

기존 추상화를 재사용하니 편하지만, Python 레벨에서 필터링하는 것은 비효율적이다. 새로운 헬퍼 메서드(for_order)도 필요하고, 전체적으로 어색하다.

방법 B: ORM 쿼리

def allocations(orderid: str, uow: AbstractUnitOfWork):
    with uow:
        batches = uow.session.query(model.Batch).join(
            model.OrderLine, model.Batch._allocations
        ).filter(
            model.OrderLine.orderid == orderid
        )
        return [
            {"sku": b.sku, "batchref": b.batchref}
            for b in batches
        ]

ORM 기능을 활용하니 좀 나아졌지만, SELECT N+1 문제가 발생할 수 있고, 복잡한 쿼리는 ORM 문법이 오히려 SQL보다 읽기 어렵다.

방법 C: 순수 SQL

def allocations(orderid: str, uow: SqlAlchemyUnitOfWork):
    with uow:
        results = uow.session.execute(
            """
            SELECT ol.sku, b.reference
            FROM allocations AS a
            JOIN batches AS b ON a.batch_id = b.id
            JOIN order_lines AS ol ON a.orderline_id = ol.id
            WHERE ol.orderid = :orderid
            """,
            dict(orderid=orderid),
        )
    return [{"sku": sku, "batchref": batchref}
            for sku, batchref in results]

SQL을 직접 쓰면 성능을 완전히 제어할 수 있다. 읽기 전용이니까 도메인 모델을 거칠 필요가 없다. SQL이면 충분하다.

방법 D: 비정규화된 읽기 전용 테이블 + 이벤트 핸들러 (CQRS 본격 적용)

이것이 CQRS의 진짜 모습이다. 읽기 전용 테이블을 별도로 만들고, 이벤트 핸들러가 자동으로 업데이트한다.

# 읽기 전용 테이블 정의
allocations_view = Table(
    "allocations_view",
    metadata,
    Column("orderid", String(255)),
    Column("sku", String(255)),
    Column("batchref", String(255)),
)

# 읽기는 이렇게 단순해진다
def allocations(orderid: str, uow: SqlAlchemyUnitOfWork):
    with uow:
        results = uow.session.execute(
            "SELECT sku, batchref FROM allocations_view WHERE orderid = :orderid",
            dict(orderid=orderid),
        )
    return [{"sku": sku, "batchref": batchref} for sku, batchref in results]

조인도 없고, 도메인 모델도 안 거치고, 단순한 SELECT 하나로 끝난다.

이벤트 핸들러로 읽기 모델 갱신

읽기 전용 테이블은 누가 채우는가? 이벤트 핸들러가 한다.

def add_allocation_to_read_model(
    event: events.Allocated,
    uow: unit_of_work.SqlAlchemyUnitOfWork,
):
    with uow:
        uow.session.execute(
            """
            INSERT INTO allocations_view (orderid, sku, batchref)
            VALUES (:orderid, :sku, :batchref)
            """,
            dict(orderid=event.orderid, sku=event.sku,
                 batchref=event.batchref),
        )
        uow.commit()

def remove_allocation_from_read_model(
    event: events.Deallocated,
    uow: unit_of_work.SqlAlchemyUnitOfWork,
):
    with uow:
        uow.session.execute(
            """
            DELETE FROM allocations_view
            WHERE orderid = :orderid AND sku = :sku
            """,
            dict(orderid=event.orderid, sku=event.sku),
        )
        uow.commit()

메시지 버스에 핸들러를 등록한다.

EVENT_HANDLERS = {
    events.Allocated: [
        handlers.publish_allocated_event,
        handlers.add_allocation_to_read_model,     # 읽기 모델 갱신
    ],
    events.Deallocated: [
        handlers.remove_allocation_from_read_model,  # 읽기 모델 삭제
    ],
}

쓰기가 발생하면 → 이벤트가 발행되고 → 읽기 모델이 자동으로 갱신된다.

읽기 모델의 유연성: 저장소 교체

이벤트 기반으로 읽기 모델을 구축하면, 저장소를 자유롭게 바꿀 수 있다. 예를 들어 Redis로 교체하면 이렇다.

# Redis에 읽기 모델 저장
def add_allocation_to_read_model(event: events.Allocated, _):
    redis_client.hset(event.orderid, event.sku, event.batchref)

# Redis에서 읽기
def allocations(orderid: str):
    batches = redis_client.hgetall(orderid)
    return [
        {"batchref": b.decode(), "sku": s.decode()}
        for s, b in batches.items()
    ]

비즈니스 로직은 전혀 건드리지 않고, 읽기 핸들러만 바꾸면 된다.

읽기 모델이 깨지면?

“읽기 전용 테이블이 쓰기 모델과 안 맞으면 어떡하지?” 라는 걱정이 당연히 든다.

하지만 읽기 모델은 재구축이 쉽다. 쓰기 모델의 현재 상태를 기반으로 이벤트를 다시 재생(replay)하면 읽기 모델을 처음부터 다시 만들 수 있다.

이것이 CQRS의 또 다른 장점이다. 읽기 모델은 언제든 버리고 다시 만들 수 있는 파생 데이터다.

Post/Redirect/Get 패턴

CQRS와 함께 자주 사용되는 웹 패턴이 있다.

POST: 커맨드를 보내서 쓰기 작업을 수행 → 202 Accepted 반환
Redirect: 쓰기가 완료되면 읽기 URL로 리다이렉트
GET: 읽기 전용 엔드포인트에서 결과를 조회

@app.route("/allocations/<orderid>", methods=["GET"])
def allocations_view_endpoint(orderid):
    uow = unit_of_work.SqlAlchemyUnitOfWork()
    result = views.allocations(orderid, uow)
    if not result:
        return "not found", 404
    return jsonify(result), 200

쓰기와 읽기가 완전히 다른 경로를 탄다.

Chapter 12 트레이드오프 정리

접근 방식	장점	단점
Repository 그대로 사용	단순, 기존 코드 재사용	복잡한 쿼리에 비효율적
ORM 쿼리	ORM 설정 재활용	SELECT N+1, 복잡한 문법
순수 SQL	성능 완전 제어	스키마 변경 시 수정 필요
비정규화 테이블 (CQRS)	읽기가 극도로 단순하고 빠름	쓰기 시 약간의 추가 비용
별도 저장소 (Redis 등)	수평 확장, 독립 최적화	일관성 지연, 복잡도 증가

Chapter 13: 의존성 주입과 부트스트래핑(Dependency Injection and Bootstrapping)

지금까지 우리 아키텍처에는 한 가지 지저분한 점이 있었다. 의존성이 여기저기 흩어져 있다는 것이다.

Flask 엔드포인트에서 SqlAlchemyUnitOfWork()를 직접 생성하고, Redis 컨슈머에서도 같은 짓을 하고, 테스트에서는 FakeUnitOfWork()를 만들고…

의존성을 한 곳에서 조립하고, 핸들러에는 필요한 것만 주입하자.

이것이 Chapter 13의 핵심이다.

문제: 암묵적 의존성

기존 핸들러를 보자.

from allocation.adapters import email

def send_out_of_stock_notification(event: events.OutOfStock):
    email.send("stock@made.com", f"Out of stock for {event.sku}")

email 모듈을 직접 import하고 있다. 테스트하려면?

with mock.patch("allocation.adapters.email.send") as mock_send:
    ...

mock.patch를 써야 한다. 이건 여러 문제를 만든다.

모든 테스트에서 email.send를 mock해야 한다
import 경로가 바뀌면 모든 mock이 깨진다
mock이 쌓이면 유지보수 비용이 급격히 올라간다

Python의 Zen: “Explicit is better than implicit.”

해결: 명시적 의존성 주입

핸들러가 필요한 의존성을 파라미터로 받게 바꾼다.

# Before: 암묵적 (직접 import)
def send_out_of_stock_notification(event: events.OutOfStock):
    email.send("stock@made.com", f"Out of stock for {event.sku}")

# After: 명시적 (파라미터로 주입)
def send_out_of_stock_notification(event: events.OutOfStock, send_mail):
    send_mail("stock@made.com", f"Out of stock for {event.sku}")

테스트할 때 mock.patch가 필요 없다. 그냥 가짜 함수를 넘기면 된다.

부트스트랩 스크립트: 조합의 뿌리(Composition Root)

의존성을 한 곳에서 조립하는 것이 부트스트랩 스크립트다.

def bootstrap(
    start_orm: bool = True,
    uow: unit_of_work.AbstractUnitOfWork = unit_of_work.SqlAlchemyUnitOfWork(),
    send_mail = email.send,
    publish = redis_eventpublisher.publish,
) -> MessageBus:

    if start_orm:
        orm.start_mappers()

    dependencies = {"uow": uow, "send_mail": send_mail, "publish": publish}

    injected_event_handlers = {
        event_type: [
            inject_dependencies(handler, dependencies)
            for handler in event_handlers
        ]
        for event_type, event_handlers in handlers.EVENT_HANDLERS.items()
    }

    injected_command_handlers = {
        command_type: inject_dependencies(handler, dependencies)
        for command_type, handler in handlers.COMMAND_HANDLERS.items()
    }

    return MessageBus(
        uow=uow,
        event_handlers=injected_event_handlers,
        command_handlers=injected_command_handlers,
    )

핵심 아이디어를 정리하면 이렇다.

기본값은 프로덕션 의존성이다 (SqlAlchemyUnitOfWork, email.send 등)
테스트에서는 가짜를 주입한다 (FakeUnitOfWork, lambda *args: None 등)
핸들러에 의존성을 자동으로 주입한다 (inject_dependencies)
조립된 메시지 버스를 반환한다

의존성 자동 주입: 시그니처 검사

핸들러 함수의 파라미터 이름을 검사해서, 필요한 의존성만 자동으로 주입한다.

import inspect

def inject_dependencies(handler, dependencies):
    params = inspect.signature(handler).parameters
    deps = {
        name: dependency
        for name, dependency in dependencies.items()
        if name in params
    }
    return lambda message: handler(message, **deps)

핸들러가 uow만 필요하면 uow만, send_mail도 필요하면 send_mail도 주입된다. 핸들러마다 수동으로 의존성을 연결할 필요가 없다.

메시지 버스가 클래스로 변환

부트스트랩에서 조립된 핸들러를 들고 있으려면, 메시지 버스도 인스턴스가 되어야 한다.

class MessageBus:
    def __init__(self, uow, event_handlers, command_handlers):
        self.uow = uow
        self.event_handlers = event_handlers
        self.command_handlers = command_handlers

    def handle(self, message):
        self.queue = [message]
        while self.queue:
            message = self.queue.pop(0)
            if isinstance(message, events.Event):
                self.handle_event(message)
            elif isinstance(message, commands.Command):
                self.handle_command(message)

    def handle_event(self, event):
        for handler in self.event_handlers[type(event)]:
            handler(event)  # 의존성은 이미 주입되어 있다
            self.queue.extend(self.uow.collect_new_events())

핸들러 호출 시 인자가 event 하나뿐이다. 나머지 의존성은 부트스트랩에서 이미 바인딩되어 있기 때문이다.

진입점(Entrypoint)이 깔끔해진다

Flask

# Before
from allocation import views
app = Flask(__name__)
orm.start_mappers()

@app.route("/add_batch", methods=["POST"])
def add_batch():
    cmd = commands.CreateBatch(...)
    uow = unit_of_work.SqlAlchemyUnitOfWork()  # 직접 생성
    messagebus.handle(cmd, uow)

# After
from allocation import bootstrap, views
app = Flask(__name__)
bus = bootstrap.bootstrap()  # 한 줄로 모든 의존성 조립

@app.route("/add_batch", methods=["POST"])
def add_batch():
    cmd = commands.CreateBatch(...)
    bus.handle(cmd)  # UoW를 넘길 필요 없다

테스트에서의 활용

통합 테스트: SQLite + 가짜 외부 서비스

@pytest.fixture
def sqlite_bus(sqlite_session_factory):
    bus = bootstrap.bootstrap(
        start_orm=True,
        uow=unit_of_work.SqlAlchemyUnitOfWork(sqlite_session_factory),
        send_mail=lambda *args: None,    # 이메일 안 보냄
        publish=lambda *args: None,       # Redis 발행 안 함
    )
    yield bus

단위 테스트: 전부 가짜

def bootstrap_test_app():
    return bootstrap.bootstrap(
        start_orm=False,                   # ORM 매핑 안 함
        uow=FakeUnitOfWork(),
        send_mail=lambda *args: None,
        publish=lambda *args: None,
    )

mock.patch가 한 줄도 없다. 명시적으로 가짜를 넣어줄 뿐이다.

어댑터 만들기: ABC → 구현 → 가짜 → 테스트

의존성 주입의 실전 워크플로우는 이렇다.

1단계: 추상 클래스(Port) 정의

class AbstractNotifications(abc.ABC):
    @abc.abstractmethod
    def send(self, destination, message):
        raise NotImplementedError

2단계: 프로덕션 구현(Adapter)

class EmailNotifications(AbstractNotifications):
    def __init__(self, smtp_host=DEFAULT_HOST, port=DEFAULT_PORT):
        self.server = smtplib.SMTP(smtp_host, port=port)

    def send(self, destination, message):
        msg = f"Subject: notification\n{message}"
        self.server.sendmail(
            from_addr="allocations@example.com",
            to_addrs=[destination],
            msg=msg,
        )

3단계: 가짜 구현(테스트용)

class FakeNotifications(AbstractNotifications):
    def __init__(self):
        self.sent = defaultdict(list)

    def send(self, destination, message):
        self.sent[destination].append(message)

4단계: 부트스트랩에서 조립

# 프로덕션
bus = bootstrap.bootstrap(notifications=EmailNotifications())

# 테스트
fake_notifications = FakeNotifications()
bus = bootstrap.bootstrap(notifications=fake_notifications)

# 테스트 후 검증
assert "Out of stock" in fake_notifications.sent["stock@made.com"][0]

Chapter 13 트레이드오프 정리

장점	단점
mock.patch 없이 테스트할 수 있다	초기에 코드가 다소 장황해 보인다
의존성이 명시적으로 드러나 가독성이 높다	의존성 체인이 복잡해지면 수동 DI로는 한계가 있다
프로덕션/테스트 환경 전환이 한 줄로 된다	DI 프레임워크(Inject, Punq 등) 도입 검토가 필요할 수 있다
어댑터 교체가 자유롭다 (이메일 → Slack 등)	Flask 글로벌 bus 인스턴스는 스레드 안전성 고려 필요

에필로그: 현실 프로젝트에 어떻게 적용할까?

지금까지 배운 패턴들은 깔끔한 예제 프로젝트에서 진행됐다. 하지만 현실은 다르다. 이미 수년간 쌓인 레거시 코드 위에서 일해야 한다.

“바다를 끓이려 하지 마세요. 실수를 두려워하지도 마세요. 배움의 과정이 될 겁니다.” — David Seddon (기술 리뷰어)

핵심 원칙: 점진적으로 적용하라

전체를 다시 쓰는 건 거의 항상 실패한다. 대신 아키텍처 세금(architecture tax)이라는 개념을 활용하자.

6개월짜리 프로젝트가 있다면, “3주 정도 정리 작업이 필요합니다”라고 말하는 것이 훨씬 설득력 있다.

기능 개발과 함께 아키텍처를 개선하는 것이다.

단계별 적용 전략

Phase 1: 서비스 레이어 추출

가장 먼저 할 일은 유스케이스를 함수로 분리하는 것이다.

각 유스케이스에 명령형 이름을 붙인다: “청구 요금 적용”, “방치 계정 정리”
각 함수가 자체 트랜잭션을 시작하고, 데이터를 가져오고, 도메인을 업데이트하고, 변경을 저장한다
코드가 중복되어도 괜찮다. 완벽한 코드가 아니라, 의미 있는 계층을 분리하는 게 목적이다

Phase 2: 도메인 모델에서 I/O 분리

데이터 접근과 I/O 로직을 도메인 모델에서 위로 끌어올린다 (핸들러/서비스 레이어로).

Phase 3: Aggregate와 일관성 경계 식별

큰 객체 그래프를 탐색하는 코드를 발견하면, Aggregate 경계가 잘못 설정된 것이다.

양방향 링크(bidirectional links)는 Aggregate가 잘못 설계되었다는 신호다.

객체 간 직접 참조 대신 식별자(ID)를 사용하도록 바꾼다.

Phase 4: 이벤트와 메시지 버스 도입

Aggregate 간 통신을 이벤트로 전환한다. 하나의 트랜잭션에서 하나의 Aggregate만 수정하고, 나머지는 이벤트로 처리한다.

Strangler Fig 패턴: 레거시 시스템 교체

기존 시스템을 한 번에 교체하는 대신, 서서히 감싸면서 교체하는 패턴이다.

1. 기존 시스템의 변경을 "이벤트"로 노출한다
    │
    ▼
2. 새로운 시스템이 그 이벤트를 소비하며 자체 도메인 모델을 구축한다
    │
    ▼
3. 새 시스템이 충분히 성숙하면, 기존 시스템을 제거한다

“Walking Skeleton”부터 시작하자. 단 하나의 질문에 답할 수 있는 최소한의 시스템을 먼저 만든다. 이렇게 하면 인프라 문제(배포, 메시지 큐 연동 등)를 초기에 해결할 수 있다.

실제로 MADE.com 사례에서는 수개월이 걸렸다. 하나의 간단한 질문에 답하는 토이 도메인 모델을 만드는 것부터 시작했다.

언제 어떤 패턴을 쓸 것인가?

패턴	적용 시점	비고
서비스 레이어	가장 먼저	레거시에서 유스케이스를 추출하는 출발점
Aggregate	큰 객체 그래프가 있을 때	일관성 경계를 명확히 한다
Repository	데이터 접근을 추상화하고 싶을 때	서비스 레이어와 함께 적용
Unit of Work	트랜잭션 관리가 필요할 때	Repository와 함께
도메인 이벤트	Aggregate 간 변경이 필요할 때	최종 일관성(eventual consistency) 허용
메시지 버스	이벤트를 통합 처리하고 싶을 때	서비스 함수와 이벤트 핸들러 통합
CQRS	읽기 성능이 중요할 때	필수는 아님, Repository로 충분하면 안 써도 된다
이벤트 소싱	감사/이력/리플레이가 필요할 때	기본 이벤트 기반과는 별개

패턴 도입 순서 (권장)

서비스 레이어 (기초)
    ↓
유스케이스 / 핸들러
    ├→ Aggregate 식별
    ├→ Repository 패턴
    └→ Unit of Work 패턴
         ↓
    도메인 이벤트
         ↓
    메시지 버스
         ├→ CQRS (선택)
         └→ 마이크로서비스 (선택)

주의사항

인프라 관련

Redis Pub/Sub는 메시지 유실 가능성이 있다. 프로덕션에서는 RabbitMQ, Kafka, EventBridge 등을 고려하라
Outbox 패턴으로 트랜잭션 안정성을 확보하라
핸들러를 멱등(idempotent)하게 만들어 안전한 재시도를 가능하게 하라

흔한 오해

이 패턴들을 쓰려고 마이크로서비스가 필수는 아니다
CQRS가 항상 필요하지는 않다. Repository로 충분하면 굳이 안 써도 된다
Django에서도 이 패턴들을 적용할 수 있다 (Appendix D 참고)
이건 설계 원칙이지, 복사-붙여넣기할 코드가 아니다

이벤트 스키마 관리

이벤트 스키마를 문서화하고 소비자와 공유하라
시간이 지나면 스키마는 진화한다. 호환성 정책을 미리 정해두자

도메인 모델링이 먼저다

패턴을 적용하기 전에, 도메인을 이해하는 것이 가장 중요하다.

다음과 같은 방법들을 활용하자.

이벤트 스토밍(Event Storming): 도메인 전문가와 함께 이벤트를 도출하는 워크숍
CRC 모델링: 클래스-책임-협력을 카드로 정리
TDD 카타: 도메인 문제를 TDD 연습 문제처럼 풀어보기

엔지니어와 프로덕트 오너가 같은 언어로 대화하게 만드는 것. 이것이 모든 패턴의 출발점이다.

전체 시리즈 핵심 정리

Part 1부터 에필로그까지, 이 책이 말하고 싶은 것을 한 문장으로 압축하면 이렇다.

“도메인 모델을 중심에 두고, 인프라를 바깥으로 밀어내고, 메시지로 소통하라.”

                    ┌─── Flask ───┐
                    │             │
                    ▼             ▼
외부 세계 ──→ 진입점(Adapter) ──→ 메시지 버스 ──→ 핸들러
                                    │              │
                                    │         도메인 모델
                                    │              │
                                    │     Repository / UoW
                                    │              │
                                    └──── DB ◄──────┘

모든 패턴은 결국 하나의 목적을 위해 존재한다. 비즈니스 로직이 인프라에 오염되지 않도록 보호하는 것.

더 읽어볼 것

Clean Architectures in Python — Leonardo Giordani
Enterprise Integration Patterns — Hohpe & Woolf
Monolith to Microservices — Sam Newman
bravenewgeek.com — Tyler Treat의 분산 메시징 에세이

참고 자료

Cosmic Python 제2부: 커맨드와 외부 이벤트 통합(Commands & External Events)

Thu, 19 Feb 2026 10:00:00 +0900

Chapter 10: 커맨드와 커맨드 핸들러(Commands and Command Handlers)

Chapter 8-9에서 우리는 모든 유스케이스를 이벤트 핸들러로 통합했다. 그런데 한 가지 어색한 점이 있다.

BatchCreated, AllocationRequired 같은 이벤트는 이미 일어난 사실을 나타내는 건가, 아니면 “이걸 해줘”라는 요청인가?

이 둘은 본질적으로 다르다. 그래서 구분해야 한다.

커맨드(Command)와 이벤트(Event)의 차이

구분	커맨드(Command)	이벤트(Event)
문법	명령형 (“~해라”)	과거형 (“~되었다”)
의미	의도(intent)를 표현한다	사실(fact)을 기록한다
수신자	딱 하나의 핸들러	여러 핸들러가 받을 수 있다
실패 처리	예외를 즉시 터뜨린다 (fail noisily)	실패해도 계속 진행한다 (fail independently)

한마디로 정리하면 이렇다.

커맨드는 “이걸 해줘”라는 소원이고, 이벤트는 “이런 일이 있었어”라는 알림이다.

커맨드의 발신자는 결과에 관심이 있다. 실패하면 알아야 한다. 이벤트의 발신자는 수신자가 누구인지조차 모른다. 실패해도 자기 일은 이미 끝났다.

코드로 분리하기

커맨드 클래스 정의

기존에 이벤트로 표현했던 것 중, “요청”에 해당하는 것들을 커맨드로 분리한다.

class Command:
    pass

@dataclass
class Allocate(Command):
    orderid: str
    sku: str
    qty: int

@dataclass
class CreateBatch(Command):
    ref: str
    sku: str
    qty: int
    eta: Optional[date] = None

@dataclass
class ChangeBatchQuantity(Command):
    ref: str
    qty: int

이벤트는 도메인에서 발생한 사실만 남긴다.

@dataclass
class OutOfStock(Event):
    sku: str

@dataclass
class Allocated(Event):
    orderid: str
    sku: str
    qty: int
    batchref: str

이벤트 이름이 과거형(OutOfStock, Allocated)이고, 커맨드 이름은 명령형(Allocate, CreateBatch)인 것에 주목하자.

메시지 버스의 변화: 커맨드와 이벤트를 다르게 처리

이제 메시지 버스가 메시지 타입에 따라 다른 전략을 적용한다.

Message = Union[commands.Command, events.Event]

def handle(message: Message, uow: unit_of_work.AbstractUnitOfWork):
    results = []
    queue = [message]
    while queue:
        message = queue.pop(0)
        if isinstance(message, events.Event):
            handle_event(message, queue, uow)
        elif isinstance(message, commands.Command):
            cmd_result = handle_command(message, queue, uow)
            results.append(cmd_result)
    return results

이벤트 핸들러: 실패해도 계속 진행

def handle_event(event: events.Event, queue: List[Message], uow):
    for handler in EVENT_HANDLERS[type(event)]:
        try:
            handler(event, uow=uow)
            queue.extend(uow.collect_new_events())
        except Exception:
            logger.exception("Exception handling event %s", event)
            continue  # 실패해도 다음 핸들러로 넘어간다

이벤트 핸들러는 하나가 실패해도 나머지는 계속 실행된다. 이메일 발송이 실패했다고 해서 주문 처리까지 멈추면 안 되니까.

커맨드 핸들러: 실패하면 즉시 터뜨린다

def handle_command(command: commands.Command, queue: List[Message], uow):
    try:
        handler = COMMAND_HANDLERS[type(command)]
        result = handler(command, uow=uow)
        queue.extend(uow.collect_new_events())
        return result
    except Exception:
        logger.exception("Exception handling command %s", command)
        raise  # 예외를 그대로 다시 던진다

커맨드 핸들러는 실패하면 예외를 즉시 전파한다. “주문을 할당해줘”라는 요청이 실패했다면, 발신자가 그 결과를 알아야 하기 때문이다.

핸들러 등록도 분리

EVENT_HANDLERS = {
    events.OutOfStock: [handlers.send_out_of_stock_notification],
}

COMMAND_HANDLERS = {
    commands.Allocate: handlers.allocate,
    commands.CreateBatch: handlers.add_batch,
    commands.ChangeBatchQuantity: handlers.change_batch_quantity,
}

차이가 보이는가?

이벤트: 핸들러가 리스트다 → 여러 핸들러가 하나의 이벤트에 반응할 수 있다
커맨드: 핸들러가 하나다 → 하나의 커맨드에 정확히 하나의 핸들러만 매핑된다

실패 복구 전략

이벤트 핸들러가 실패할 수 있다면, 재시도 전략도 필요하다.

from tenacity import Retrying, RetryError, stop_after_attempt, wait_exponential

def handle_event(event: events.Event, queue, uow):
    for handler in EVENT_HANDLERS[type(event)]:
        try:
            for attempt in Retrying(
                stop=stop_after_attempt(3),
                wait=wait_exponential()
            ):
                with attempt:
                    handler(event, uow=uow)
                    queue.extend(uow.collect_new_events())
        except RetryError as retry_failure:
            logger.error(
                "Failed after %s attempts handling event %s",
                retry_failure.last_attempt.attempt_number, event
            )
            continue

tenacity 라이브러리를 사용하여 지수 백오프(exponential backoff) 기반의 재시도를 적용한다. 3번까지 시도하고, 그래도 실패하면 로그를 남기고 넘어간다.

또한 이벤트가 dataclass이기 때문에, 로그에 찍힌 데이터를 그대로 복사해서 Python 셸에서 재현할 수 있다. 이것이 디버깅 시 큰 이점이 된다.

왜 이 구분이 중요한가?

비즈니스 관점에서 보면 이렇다.

커맨드 CreateOrder가 성공하면 → 이벤트 OrderCreated가 발생한다. 이벤트 OrderCreated는 → 이력 기록, VIP 전환, 이메일 발송 등의 후속 작업을 트리거한다. 이메일 발송이 실패해도, 주문 생성 자체는 성공이다.

만약 이 구분 없이 전부 동일하게 처리했다면? 이메일 서버가 다운되는 순간 주문 생성까지 실패하게 된다. 커맨드와 이벤트의 분리는 “어디까지가 반드시 성공해야 하고, 어디부터는 실패해도 되는가”를 명확히 한다.

Chapter 10 트레이드오프 정리

장점	단점
반드시 성공해야 하는 작업과 부수 효과를 명확히 구분한다	커맨드와 이벤트의 경계에 대한 의미론적 논쟁이 생길 수 있다
이벤트 핸들러 하나가 실패해도 나머지는 계속 동작한다	이벤트 핸들러의 “실패해도 OK” 전략은 강력한 모니터링을 요구한다
핸들러 이름이 비즈니스 의도를 명시적으로 표현한다	커맨드/이벤트/핸들러 간의 매핑이 많아지면서 시스템 전체 흐름 파악이 어려워진다
실패 도메인을 작고 격리된 단위로 관리할 수 있다	전체 시스템 복잡성이 증가한다

Chapter 11: 외부 이벤트를 활용한 마이크로서비스 통합(Using Events to Integrate Microservices)

지금까지의 이벤트는 하나의 서비스 내부에서 흐르는 것이었다. Chapter 11에서는 드디어 서비스의 경계를 넘어서 이벤트를 주고받는다.

서비스 하나가 아무리 잘 설계되어 있어도, 다른 서비스와 어떻게 통신하느냐에 따라 전체 시스템의 운명이 갈린다.

문제: 명사 기반 서비스 분리의 함정

마이크로서비스를 설계할 때 흔히 하는 실수가 있다. 데이터베이스 테이블 이름으로 서비스를 나누는 것이다.

Orders 서비스 → Batches 서비스 → Warehouse 서비스

이렇게 나누면 어떤 문제가 생길까?

실행 순서 결합(Connascence of Execution): 창고에서 재고 손상이 발생하면, Warehouse가 Batches를 호출하고, Batches가 Orders를 호출해야 한다
시간 결합(Connascence of Timing): 모든 서비스가 동시에 동작해야 한다
장애 전파: 하나가 다운되면 전체 체인이 멈춘다

결국 “분산된 거대한 진흙 덩어리(distributed big ball of mud)”가 된다.

이 문제의 근본 원인은 동기식 RPC(원격 프로시저 호출)로 서비스를 엮었기 때문이다.

해결: 동사 기반, 이벤트 기반 설계

명사(noun) 중심이 아닌 동사(verb) 중심으로 생각을 바꿔야 한다.

“주문 서비스”, “배치 서비스”가 아니라, “주문하기(ordering)”, “할당하기(allocating)” 같은 워크플로우로 서비스를 설계한다.

각 서비스는 일관성 경계(consistency boundary)가 되어, 커맨드를 받아 처리하고 이벤트를 발행한다.

Before (동기식 RPC - 단일 장애 체인):
Orders → Batches → Warehouse → CRM
(하나가 죽으면 전부 멈춘다)

After (이벤트 기반 - 독립적인 서비스):
Orders: "OrderPlaced" 이벤트 발행
    ├─ Batches가 구독 → "Allocated" 이벤트 발행
    ├─ Warehouse가 독립적으로 구독
    └─ CRM이 독립적으로 구독
(각 서비스가 독립적으로 동작한다)

서비스 간의 결합이 “이벤트 이름과 필드에 대한 합의”로만 한정된다. 이를 이름 결합(Connascence of Name)이라 하는데, 이것은 가장 약한(=좋은) 형태의 결합이다.

Redis Pub/Sub로 외부 이벤트 연동하기

이 책에서는 Redis Pub/Sub를 메시지 브로커로 사용한다. (프로덕션에서는 Kafka, RabbitMQ 등을 쓰겠지만, 개념을 이해하기엔 Redis로 충분하다.)

외부 이벤트 수신: Redis → 내부 커맨드

외부에서 오는 메시지를 받아서 내부 커맨드로 변환하는 어댑터를 만든다.

r = redis.Redis(**config.get_redis_host_and_port())

def main():
    orm.start_mappers()
    pubsub = r.pubsub(ignore_subscribe_messages=True)
    pubsub.subscribe("change_batch_quantity")

    for m in pubsub.listen():
        handle_change_batch_quantity(m)

def handle_change_batch_quantity(m):
    data = json.loads(m["data"])
    cmd = commands.ChangeBatchQuantity(ref=data["batchref"], qty=data["qty"])
    messagebus.handle(cmd, uow=unit_of_work.SqlAlchemyUnitOfWork())

구조가 낯이 익지 않은가? Flask 엔드포인트와 같은 패턴이다.

진입점	역할
Flask 엔드포인트	HTTP 요청 → 커맨드 → 메시지 버스
Redis 컨슈머	Redis 메시지 → 커맨드 → 메시지 버스

외부 인프라가 무엇이든 상관없이, 내부적으로는 동일한 메시지 버스를 통해 처리된다. 이것이 바로 포트와 어댑터(Ports and Adapters) 아키텍처의 진가다.

내부 이벤트 발행: 도메인 → Redis

할당이 성공하면, 외부로 알려야 한다. 도메인 모델이 Allocated 이벤트를 발생시키고, 이를 Redis로 발행한다.

# 도메인 모델에서 이벤트 발생
class Product:
    def allocate(self, line: OrderLine) -> str:
        # ... 할당 로직 ...
        batch.allocate(line)
        self.version_number += 1
        self.events.append(
            events.Allocated(
                orderid=line.orderid,
                sku=line.sku,
                qty=line.qty,
                batchref=batch.reference,
            )
        )
        return batch.reference

# Redis로 발행하는 핸들러
def publish_allocated_event(event: events.Allocated, uow):
    redis_eventpublisher.publish("line_allocated", event)

# 실제 발행 로직
def publish(channel, event: events.Event):
    logging.debug("publishing: channel=%s, event=%s", channel, event)
    r.publish(channel, json.dumps(asdict(event)))

# 메시지 버스 핸들러 등록
EVENT_HANDLERS = {
    events.Allocated: [handlers.publish_allocated_event],
    events.OutOfStock: [handlers.send_out_of_stock_notification],
}

전체 흐름: 외부 이벤트 → 내부 처리 → 외부 발행

이벤트의 전체 흐름을 정리하면 이렇다.

1. 외부 시스템이 Redis "change_batch_quantity" 채널에 메시지 발행
    │
    ▼
2. Redis 컨슈머가 메시지를 수신하고 ChangeBatchQuantity 커맨드로 변환
    │
    ▼
3. 메시지 버스가 change_batch_quantity 핸들러를 실행
    │ (수량 초과 시 deallocate → AllocationRequired 이벤트 발행)
    ▼
4. allocate 핸들러가 재할당을 수행
    │ (성공 시 Allocated 이벤트 발행)
    ▼
5. publish_allocated_event 핸들러가 Redis "line_allocated" 채널로 발행
    │
    ▼
6. 다른 외부 서비스가 "line_allocated" 채널을 구독하여 후속 처리

하나의 외부 메시지가 내부 커맨드 → 도메인 처리 → 이벤트 체이닝 → 외부 발행까지 자연스럽게 흘러간다.

외부 이벤트의 E2E 테스트

비동기 시스템의 테스트는 재시도 루프를 사용해야 한다. 메시지 전달이 즉시 이루어지지 않기 때문이다.

def test_change_batch_quantity_leading_to_reallocation():
    orderid, sku = random_orderid(), random_sku()
    earlier_batch, later_batch = random_batchref("old"), random_batchref("newer")

    api_client.post_to_add_batch(earlier_batch, sku, qty=10, eta="2011-01-01")
    api_client.post_to_add_batch(later_batch, sku, qty=10, eta="2011-01-02")
    response = api_client.post_to_allocate(orderid, sku, 10)
    assert response.json()["batchref"] == earlier_batch

    subscription = redis_client.subscribe_to("line_allocated")

    # 외부 이벤트 발행
    redis_client.publish_message(
        "change_batch_quantity",
        {"batchref": earlier_batch, "qty": 5},
    )

    # 재할당 결과가 외부로 발행되었는지 확인 (재시도 루프)
    for attempt in Retrying(stop=stop_after_delay(3), reraise=True):
        with attempt:
            message = subscription.get_message(timeout=1)
            if message:
                data = json.loads(message["data"])
                assert data["orderid"] == orderid
                assert data["batchref"] == later_batch

이 테스트가 검증하는 것은 이렇다.

HTTP API로 배치와 주문을 생성한다
Redis를 통해 배치 수량 변경 외부 이벤트를 발행한다
내부에서 재할당이 이루어지고, 결과가 Redis로 다시 발행되는지 확인한다

HTTP 진입점과 Redis 진입점이 하나의 테스트에서 함께 검증된다.

내부 이벤트 vs 외부 이벤트

한 가지 중요한 설계 원칙이 있다.

내부 이벤트와 외부 이벤트를 구분하라.

모든 내부 이벤트를 외부에 그대로 발행하면 안 된다. 내부 이벤트 중 일부는 구현 세부사항이기 때문이다.

구분	내부 이벤트	외부 이벤트
범위	하나의 서비스 내부	서비스 경계를 넘어 전파
예시	`AllocationRequired`	`Allocated`
목적	내부 이벤트 체이닝	다른 서비스에 사실 전달
변경 영향	내부 코드만 수정	외부 소비자까지 영향
검증	단위 테스트	계약 테스트(contract test) 필요

외부로 나가는 이벤트는 계약(contract)이다. 한번 정의하면 쉽게 바꿀 수 없으므로, 스키마 검증과 버전 관리가 필요하다.

Chapter 11 트레이드오프 정리

장점	단점
서비스 간 결합도가 극적으로 낮아진다	전체 정보 흐름이 암묵적이 되어 파악하기 어렵다
한 서비스가 실패해도 다른 서비스에 영향이 없다	최종 일관성(eventual consistency) 패러다임을 팀 전체가 이해해야 한다
새로운 서비스를 기존 이벤트에 독립적으로 구독시킬 수 있다	메시지 신뢰성, 순서 보장, 멱등성 처리를 설계해야 한다
포트와 어댑터 패턴 덕분에 인프라 교체가 용이하다	인과 관계 추적(tracing)과 디버깅이 어려워진다

Martin Fowler의 말을 빌리면 이렇다.

“이벤트 알림은 낮은 결합도를 의미하지만, 논리적 흐름이 코드에 명시적으로 드러나지 않아 파악하기 어렵다.”

Chapter 10-11 핵심 정리

두 장을 관통하는 핵심 메시지를 정리하면 이렇다.

Chapter 10: 메시지의 성격을 구분하라.

커맨드 = “해줘” → 실패하면 바로 터뜨려라
이벤트 = “일어났어” → 실패해도 계속 진행하라
이 구분이 장애 격리와 복원력의 기반이 된다

Chapter 11: 이벤트로 서비스 경계를 넘어라.

동기식 RPC 대신 비동기 이벤트로 통신하라
내부 이벤트와 외부 이벤트를 명확히 구분하라
Flask든 Redis든, 진입점이 달라도 내부 처리는 동일하다

외부 세계                    내부 세계
──────────────────    ──────────────────────────────
HTTP 요청 ─────┐
               ├──→ 커맨드 → 메시지 버스 → 핸들러
Redis 메시지 ──┘         │
                         ├── 도메인 이벤트 → 내부 핸들러 체이닝
                         └── 외부 이벤트 → Redis 발행 → 다른 서비스

참고 자료

Cosmic Python 제2부: 이벤트 기반 아키텍처(Event-Driven Architecture)

Sat, 07 Feb 2026 10:00:00 +0900

제2부: 이벤트 기반 아키텍처(Event-Driven Architecture)

“오래전에 이 주제에 대해 ‘객체(objects)’라는 용어를 만든 것이 유감입니다. 그 단어 때문에 많은 사람들이 덜 중요한 개념에 집중하게 되었거든요. 진짜 중요한 건 ‘메시징(messaging)’입니다.…위대하고 성장 가능한 시스템을 만드는 핵심은, 모듈의 내부 속성이나 동작이 아니라 모듈 간의 통신을 어떻게 설계하느냐에 달려 있습니다.” — Alan Kay

Part 1에서 Part 2로, 왜 넘어가야 할까?

Part 1에서 우리는 단일 도메인 모델을 중심으로 아키텍처 패턴들을 살펴봤다.

Repository 패턴으로 영속성을 추상화하고
Service Layer로 유스케이스를 관리하고
Unit of Work로 트랜잭션을 제어하고
Aggregate로 일관성 경계를 설정했다.

그런데 현실의 소프트웨어는 단일 도메인 모델 하나로 끝나지 않는다.

회사에서 만드는 시스템은 다른 시스템과 정보를 주고받아야 하고, 조직 내에서 여러 비즈니스 프로세스를 동시에 관리해야 한다. 결국, “하나의 모델을 넘어서 여러 모델이 서로 협력하는 구조”를 고민해야 하는 시점이 온다.

마이크로서비스? 그냥 하면 큰일 난다

많은 팀들이 이 문제를 해결하기 위해 마이크로서비스를 도입하고, HTTP API로 서비스 간 통신을 구현한다.

그런데 이걸 신중하게 설계하지 않으면 어떻게 될까?

“분산된 거대한 진흙 덩어리(distributed big ball of mud)”가 탄생한다.

모노리스에서의 엉킨 코드보다 더 나쁜 상황이 벌어질 수 있다는 뜻이다. 서비스 간의 의존성이 복잡해지고, 장애가 전파되고, 데이터 정합성이 깨지기 시작하면… 그때부터는 정말 손쓰기 어려워진다.

그래서 Part 2에서는 이 문제를 제대로 다루는 방법을 알아본다.

Part 2에서 다루는 핵심 패턴들

Part 1에서 배운 패턴들이 분산 시스템으로 자연스럽게 확장된다. 작은 컴포넌트들이 비동기 메시지 전달(asynchronous message passing)로 소통하는 시스템을 구성하는 방법을 배우게 된다.

1. 도메인 이벤트(Domain Events)

“주문이 생성되었다”, “결제가 완료되었다” 같은 사건을 이벤트로 표현하는 패턴이다.

일관성 경계(consistency boundary)를 넘나드는 워크플로우를 트리거할 때 사용한다. 예를 들어, 주문 서비스에서 “주문 완료” 이벤트가 발생하면 → 배송 서비스가 이를 받아서 배송 준비를 시작하는 식이다.

개념	설명
도메인 이벤트	도메인에서 발생한 중요한 사건을 나타내는 객체
발행(Publish)	이벤트를 시스템에 알리는 행위
구독(Subscribe)	특정 이벤트에 반응하여 처리하는 행위

2. 메시지 버스(Message Bus)

유스케이스를 어떤 진입점에서든 통일된 방식으로 호출할 수 있게 해주는 패턴이다.

웹 API에서 호출하든, 이벤트 핸들러에서 호출하든, CLI에서 호출하든 동일한 방식으로 처리할 수 있다. Service Layer와 Unit of Work 패턴 덕분에 애플리케이션이 비동기 메시지 처리기(asynchronous message processor)로 동작할 수 있게 된다.

3. CQRS (Command Query Responsibility Segregation)

읽기(Query)와 쓰기(Command)를 분리하는 패턴이다.

하나의 모델로 읽기와 쓰기를 모두 처리하면, 어느 쪽도 완벽하게 최적화하기 어렵다. CQRS는 이 둘을 분리해서 각각에 맞는 최적의 구조를 가져갈 수 있게 해준다.

구분	Command (쓰기)	Query (읽기)
목적	상태 변경	데이터 조회
모델	도메인 모델 (복잡한 비즈니스 로직)	읽기 전용 모델 (단순, 빠름)
최적화	정합성, 트랜잭션	성능, 캐싱

4. 의존성 주입(Dependency Injection)

Part 2에서는 의존성 주입 프레임워크도 함께 다룬다. 이벤트 기반 아키텍처와 직접적인 관련은 없지만, 아키텍처가 복잡해질수록 의존성 관리가 중요해지기 때문이다.

부트스트래핑(bootstrapping) 과정에서 의존성을 깔끔하게 주입하면, 테스트도 쉬워지고 컴포넌트 간 결합도도 낮출 수 있다.

Part 2의 큰 그림

정리하면, Part 2는 이런 흐름으로 진행된다.

Part 1의 패턴들 (Repository, Service Layer, UoW, Aggregate)
    │
    ▼
도메인 이벤트로 Aggregate 간 통신
    │
    ▼
메시지 버스로 유스케이스 통합
    │
    ▼
이벤트 기반으로 마이크로서비스 간 통합
    │
    ▼
CQRS로 읽기/쓰기 최적화
    │
    ▼
의존성 주입으로 전체 구조 정리

결국 핵심은 “모듈 간 통신을 어떻게 설계할 것인가”이다. Alan Kay의 말처럼, 객체의 내부 구현보다 메시징이 더 중요하다.

이걸 왜 알아야 할까?

실무에서 서비스가 커지다 보면, 반드시 이런 고민을 하게 된다.

“이 서비스에서 저 서비스로 데이터를 어떻게 전달하지?”
“동기 호출로 하면 장애가 전파되는데, 비동기로 바꿔야 하나?”
“이벤트를 쓰면 순서 보장은 어떻게 하지?”

Part 2는 이런 질문들에 대한 체계적인 답을 제시한다. 단순히 “메시지 큐 쓰면 됩니다”가 아니라, 도메인 모델과 아키텍처 패턴을 기반으로 설계하는 방법을 알려준다.

Part 1에서 단단한 기초를 쌓았다면, Part 2에서는 그 기초 위에 확장 가능한 시스템을 설계하는 방법을 배우는 것이다.

그럼 이제 본격적으로 Chapter 8과 Chapter 9를 살펴보자.

Chapter 8: 이벤트와 메시지 버스(Events and the Message Bus)

문제 상황: “이메일도 보내야 하는데 어디에 넣지?”

지금까지 구축한 아키텍처가 진짜 가치를 발휘하는 순간은, 명확한 기능 구현이 아니라 “기능 주변의 잡다한 것들(the goop around the edge)”을 처리할 때다. 보고서, 권한 체크, 알림 발송 같은 부수적인 요구사항 말이다.

구체적인 예시를 들어보자. 재고 할당(allocation)에 실패하면, 구매팀에게 재고 부족 이메일을 보내야 한다.

그런데 이 이메일 로직을 도대체 어디에 넣어야 할까?

안티패턴 1: 웹 컨트롤러에 넣기

@app.route("/allocate", methods=["POST"])
def allocate_endpoint():
    line = model.OrderLine(
        request.json["orderid"],
        request.json["sku"],
        request.json["qty"],
    )
    try:
        uow = unit_of_work.SqlAlchemyUnitOfWork()
        batchref = services.allocate(line, uow)
    except (model.OutOfStock, services.InvalidSku) as e:
        send_mail(
            "out of stock",
            "stock_admin@made.com",
            f"{line.orderid} - {line.sku}"
        )
        return {"message": str(e)}, 400
    return {"batchref": batchref}, 201

Flask 엔드포인트에 이메일 로직을 넣으면? 관심사 분리가 완전히 깨진다. 웹 계층이 비즈니스 로직과 인프라 로직을 모두 알고 있어야 하고, 단위 테스트도 어려워진다.

안티패턴 2: 도메인 모델에 넣기

def allocate(self, line: OrderLine) -> str:
    try:
        batch = next(b for b in sorted(self.batches) if b.can_allocate(line))
    except StopIteration:
        email.send_mail("stock@made.com", f"Out of stock for {line.sku}")
        raise OutOfStock(f"Out of stock for sku {line.sku}")

도메인 모델에 email.send_mail이 들어가는 순간, 도메인 모델이 인프라에 의존하게 된다. 도메인 모델은 비즈니스 로직만 담고 있어야 한다.

안티패턴 3: 서비스 레이어에 넣기

def allocate(orderid, sku, qty, uow):
    line = OrderLine(orderid, sku, qty)
    with uow:
        product = uow.products.get(sku=line.sku)
        if product is None:
            raise InvalidSku(f"Invalid sku {line.sku}")
        try:
            batchref = product.allocate(line)
            uow.commit()
            return batchref
        except model.OutOfStock:
            email.send_mail("stock@made.com", f"Out of stock for {line.sku}")
            raise

서비스 레이어에 넣으면 좀 낫지 않을까? 여전히 문제다. 할당 로직과 이메일 발송이 하나의 함수에 섞여 있다. 예외를 잡아서 이메일을 보내고 다시 던지는 패턴은 코드 냄새(code smell)다.

핵심 원칙: 단일 책임 원칙(SRP)

여기서 저자들이 강조하는 원칙이 있다.

“함수를 설명할 때 ‘그리고(and)’ 또는 ‘그 다음에(then)’를 사용해야 한다면, SRP를 위반하고 있는 것이다.”

allocate() 함수는 할당만 담당해야 한다. 나중에 이메일 대신 SMS로 바꾼다고 해서 allocate() 함수를 수정해야 한다면? 그건 잘못된 설계다.

해결책: 도메인 이벤트 + 메시지 버스

이벤트를 값 객체로 정의하기

이벤트는 “도메인에서 발생한 사실”을 나타내는 단순한 데이터 구조다.

from dataclasses import dataclass

class Event:
    pass

@dataclass
class OutOfStock(Event):
    sku: str

행동(behavior)은 없고, 데이터만 있다. “무슨 일이 일어났는가”를 기록할 뿐이다.

도메인 모델이 이벤트를 기록하게 하기

예외를 던지는 대신, Aggregate가 이벤트를 내부 리스트에 기록한다.

class Product:
    def __init__(self, sku, batches, version_number=0):
        self.sku = sku
        self.batches = batches
        self.version_number = version_number
        self.events = []  # 이벤트를 쌓아두는 리스트

    def allocate(self, line: OrderLine) -> str:
        try:
            batch = next(b for b in sorted(self.batches) if b.can_allocate(line))
            batch.allocate(line)
            self.version_number += 1
            return batch.reference
        except StopIteration:
            self.events.append(events.OutOfStock(line.sku))
            return None

테스트 코드로 확인해보면 이렇다.

def test_records_out_of_stock_event_if_cannot_allocate():
    batch = Batch("batch1", "SMALL-FORK", 10, eta=today)
    product = Product(sku="SMALL-FORK", batches=[batch])
    product.allocate(OrderLine("order1", "SMALL-FORK", 10))

    allocation = product.allocate(OrderLine("order2", "SMALL-FORK", 1))
    assert product.events[-1] == events.OutOfStock(sku="SMALL-FORK")
    assert allocation is None

예외를 흐름 제어에 사용하던 방식에서, 이벤트 기록 방식으로 바뀐 것이다.

메시지 버스: 이벤트를 핸들러에 라우팅

메시지 버스는 본질적으로 이벤트 타입 → 핸들러 함수 매핑이다. 매우 단순하다.

def handle(event: events.Event):
    for handler in HANDLERS[type(event)]:
        handler(event)

def send_out_of_stock_notification(event: events.OutOfStock):
    email.send_mail(
        "stock@made.com",
        f"Out of stock for {event.sku}",
    )

HANDLERS = {
    events.OutOfStock: [send_out_of_stock_notification],
}

메시지 버스는 멍청한 인프라다. 이벤트의 의미를 모르고, 그저 라우팅만 한다. 그리고 이 구현은 동기적(synchronous)이다. 핸들러가 같은 스레드에서 순차적으로 실행된다.

이벤트를 누가 발행할 것인가? 세 가지 옵션

옵션 1: 서비스 레이어가 명시적으로 발행

def allocate(orderid, sku, qty, uow):
    line = OrderLine(orderid, sku, qty)
    with uow:
        product = uow.products.get(sku=line.sku)
        batchref = product.allocate(line)
        uow.commit()
        return batchref
    # finally 블록에서 messagebus.handle(product.events) 호출

단순하지만, 서비스 레이어가 이벤트를 알아야 한다.

옵션 2: 서비스 레이어가 자체 이벤트를 생성

서비스 레이어가 결과를 보고 직접 이벤트를 만드는 방식이다. 도메인 모델은 단순해지지만, 이벤트 로직이 서비스 레이어로 이동한다.

옵션 3: Unit of Work가 이벤트를 수집하여 발행 (권장)

가장 깔끔한 방식이다. UoW가 commit할 때 자동으로 이벤트를 수집하고 발행한다.

class AbstractUnitOfWork(abc.ABC):
    def commit(self):
        self._commit()
        self.publish_events()

    def publish_events(self):
        for product in self.products.seen:
            while product.events:
                event = product.events.pop(0)
                messagebus.handle(event)

이걸 위해 Repository에 seen 추적 기능을 추가한다.

class AbstractRepository(abc.ABC):
    def __init__(self):
        self.seen = set()

    def add(self, product):
        self._add(product)
        self.seen.add(product)

    def get(self, sku):
        product = self._get(sku)
        if product:
            self.seen.add(product)
        return product

Repository가 add()나 get()으로 접근한 Aggregate를 seen 집합에 기록하고, UoW가 커밋 시점에 seen에 있는 모든 Aggregate의 이벤트를 수집하는 구조다.

이렇게 하면 서비스 레이어는 다시 깔끔해진다.

def allocate(orderid, sku, qty, uow):
    line = OrderLine(orderid, sku, qty)
    with uow:
        product = uow.products.get(sku=line.sku)
        if product is None:
            raise InvalidSku(f"Invalid sku {line.sku}")
        batchref = product.allocate(line)
        uow.commit()
        return batchref

이메일 발송 로직은 어디에도 보이지 않는다. 커밋하면 UoW가 알아서 이벤트를 수집하고, 메시지 버스가 핸들러를 실행한다.

Chapter 8 트레이드오프 정리

장점	단점
할당 로직과 알림 로직이 완전히 분리된다 (SRP)	메시지 버스라는 새로운 개념이 추가되어 복잡도가 올라간다
이벤트와 핸들러를 독립적으로 테스트할 수 있다	`commit()` 호출 시 이메일이 발송되는 건 직관적이지 않다
이메일 → SMS 변경 시 핸들러만 바꾸면 된다	이벤트 기반 워크플로우는 한눈에 흐름을 파악하기 어렵다
이벤트가 도메인 용어로 표현되어 비즈니스와 소통이 쉽다	이벤트 핸들러 간 순환 의존이 생길 수 있다

Chapter 9: 메시지 버스로 전면 전환(Going to Town on the Message Bus)

Chapter 8에서는 메시지 버스를 부수적인 효과(side effect)를 처리하는 용도로 도입했다. Chapter 9에서는 한 발 더 나아간다. 모든 것을 메시지 버스를 통해 처리하는 구조로 전환한다.

“이벤트가 선택적 부수효과”인 아키텍처에서, “모든 것이 메시지 버스를 통해 흐르는” 아키텍처로 바뀌는 것이다.

새로운 요구사항이 아키텍처를 이끈다

현실의 소프트웨어는 상황 기반 소프트웨어(situated software)다. 실제 프로세스를 장기간 관리하다 보면, 예상치 못한 상황이 끊임없이 발생한다. 재고가 손상되거나, 통관이 지연되거나, 공장에서 제조 수량이 줄어들거나…

이번 장의 구체적인 요구사항은 이렇다.

배치(Batch)의 수량이 변경되면, 이미 할당된 주문이 초과된 경우 할당을 해제하고 재할당해야 한다.

예를 들어보자.

Batch에 50개가 있고, 20개씩 2건의 주문이 할당되어 있다 (남은 수량: 10개)
그런데 Batch 수량이 25개로 줄어들었다!
이미 할당된 40개 중 초과분이 생겨서, 한 건을 할당 해제(deallocate)하고 다른 Batch로 재할당(reallocate)해야 한다

이런 연쇄적인 처리를 어떻게 우아하게 구현할 수 있을까?

핵심 아이디어: 모든 것을 이벤트 핸들러로

저자들의 제안은 이렇다.

API가 호출하는 서비스 함수와, 내부 이벤트 핸들러를 구분하지 말자. 모든 것을 이벤트 핸들러로 만들자.

기존의 서비스 함수들이 이벤트 핸들러로 바뀐다.

기존 (서비스 함수)	변경 후 (이벤트 핸들러)
`services.add_batch(ref, sku, qty, eta)`	`handlers.add_batch(BatchCreated 이벤트)`
`services.allocate(orderid, sku, qty)`	`handlers.allocate(AllocationRequired 이벤트)`
(신규)	`handlers.change_batch_quantity(BatchQuantityChanged 이벤트)`

이벤트가 시스템의 입력이 된다

API 입력을 표현하는 이벤트를 새로 정의한다.

@dataclass
class BatchCreated(Event):
    ref: str
    sku: str
    qty: int
    eta: Optional[date] = None

@dataclass
class AllocationRequired(Event):
    orderid: str
    sku: str
    qty: int

@dataclass
class BatchQuantityChanged(Event):
    ref: str
    qty: int

서비스 함수의 시그니처가 개별 인자(primitives)에서 이벤트 객체로 바뀐다.

# Before
def add_batch(ref: str, sku: str, qty: int, eta: Optional[date], uow):
    ...

# After
def add_batch(event: events.BatchCreated, uow: unit_of_work.AbstractUnitOfWork):
    with uow:
        product = uow.products.get(sku=event.sku)
        if product is None:
            product = model.Product(sku=event.sku, batches=[])
            uow.products.add(product)
        product.batches.append(
            model.Batch(event.ref, event.sku, event.qty, event.eta)
        )
        uow.commit()

이벤트 객체를 통해 인터페이스가 통일된다. 모든 핸들러는 (event, uow) 형태의 동일한 시그니처를 갖는다.

메시지 버스의 진화: UoW에서 이벤트를 수집

Chapter 8에서는 UoW가 메시지 버스에 이벤트를 푸시(push)했다. Chapter 9에서는 메시지 버스가 UoW에서 이벤트를 풀(pull)하는 방식으로 바뀐다.

이유는? 순환 의존을 제거하기 위해서다.

def handle(event: events.Event, uow: unit_of_work.AbstractUnitOfWork):
    results = []
    queue = [event]
    while queue:
        event = queue.pop(0)
        for handler in HANDLERS[type(event)]:
            results.append(handler(event, uow=uow))
            queue.extend(uow.collect_new_events())
    return results

핵심 포인트를 정리하면 이렇다.

메시지 버스가 이벤트 큐를 내부적으로 관리한다
핸들러가 실행된 후, UoW에서 새로 발생한 이벤트를 수집한다
수집된 이벤트가 큐에 추가되어 연쇄적으로 처리된다
FIFO 순서로 처리된다

UoW의 publish_events() 메서드는 collect_new_events()로 바뀌어, 능동적으로 발행하는 게 아니라 수동적으로 수집당하는 구조가 된다.

테스트도 이벤트 기반으로

테스트 코드도 서비스 함수를 직접 호출하는 대신, 이벤트를 생성하고 메시지 버스에 전달하는 방식으로 바뀐다.

class TestAddBatch:
    def test_for_new_product(self):
        uow = FakeUnitOfWork()
        messagebus.handle(
            events.BatchCreated("b1", "CRUNCHY-ARMCHAIR", 100, None), uow
        )
        assert uow.products.get("CRUNCHY-ARMCHAIR") is not None
        assert uow.committed

Flask 엔드포인트도 마찬가지다.

# Before
batchref = services.allocate(
    request.json["orderid"], request.json["sku"],
    request.json["qty"], unit_of_work.SqlAlchemyUnitOfWork(),
)

# After
event = events.AllocationRequired(
    request.json["orderid"], request.json["sku"], request.json["qty"]
)
results = messagebus.handle(event, unit_of_work.SqlAlchemyUnitOfWork())
batchref = results.pop(0)

새로운 요구사항 구현: 배치 수량 변경

이제 메시지 버스 중심 아키텍처에서 새 요구사항을 구현해보자. TDD로 진행한다.

테스트 케이스 1: 단순 수량 변경

class TestChangeBatchQuantity:
    def test_changes_available_quantity(self):
        uow = FakeUnitOfWork()
        messagebus.handle(
            events.BatchCreated("batch1", "ADORABLE-SETTEE", 100, None), uow
        )
        [batch] = uow.products.get("ADORABLE-SETTEE").batches
        assert batch.available_quantity == 100

        messagebus.handle(events.BatchQuantityChanged("batch1", 50), uow)
        assert batch.available_quantity == 50

테스트 케이스 2: 수량 감소로 재할당이 필요한 경우

def test_reallocates_if_necessary(self):
    uow = FakeUnitOfWork()
    event_history = [
        events.BatchCreated("batch1", "INDIFFERENT-TABLE", 50, None),
        events.BatchCreated("batch2", "INDIFFERENT-TABLE", 50, date.today()),
        events.AllocationRequired("order1", "INDIFFERENT-TABLE", 20),
        events.AllocationRequired("order2", "INDIFFERENT-TABLE", 20),
    ]
    for e in event_history:
        messagebus.handle(e, uow)

    [batch1, batch2] = uow.products.get("INDIFFERENT-TABLE").batches
    assert batch1.available_quantity == 10
    assert batch2.available_quantity == 50

    messagebus.handle(events.BatchQuantityChanged("batch1", 25), uow)

    # batch1: 25 - 20 = 5 (order1만 남음)
    # batch2: 50 - 20 = 30 (order2가 재할당됨)
    assert batch1.available_quantity == 5
    assert batch2.available_quantity == 30

테스트가 이벤트 히스토리를 먼저 쌓고, 수량 변경 이벤트를 보내는 방식으로 작성된다. 순수하게 이벤트와 상태 변화만으로 테스트할 수 있어서 매우 깔끔하다.

핸들러 구현

def change_batch_quantity(
    event: events.BatchQuantityChanged,
    uow: unit_of_work.AbstractUnitOfWork,
):
    with uow:
        product = uow.products.get_by_batchref(batchref=event.ref)
        product.change_batch_quantity(ref=event.ref, qty=event.qty)
        uow.commit()

도메인 모델의 변화

class Product:
    def change_batch_quantity(self, ref: str, qty: int):
        batch = next(b for b in self.batches if b.reference == ref)
        batch._purchased_quantity = qty
        while batch.available_quantity < 0:
            line = batch.deallocate_one()
            self.events.append(
                events.AllocationRequired(line.orderid, line.sku, line.qty)
            )

여기서 이벤트 체이닝이 일어난다.

BatchQuantityChanged 이벤트 → change_batch_quantity 핸들러 실행
도메인 모델이 초과된 주문을 해제하면서 AllocationRequired 이벤트를 발생
메시지 버스가 새 이벤트를 수집하여 allocate 핸들러 실행
재할당 불가 시 OutOfStock 이벤트 → 알림 핸들러 실행

하나의 이벤트가 연쇄적으로 다른 이벤트를 트리거하는 구조다.

메시지 버스 핸들러 등록

HANDLERS = {
    events.BatchCreated: [handlers.add_batch],
    events.BatchQuantityChanged: [handlers.change_batch_quantity],
    events.AllocationRequired: [handlers.allocate],
    events.OutOfStock: [handlers.send_out_of_stock_notification],
}

새로운 요구사항을 구현하는 데 아키텍처를 변경할 필요가 없었다. 이벤트와 핸들러만 추가하면 됐다.

격리된 핸들러 테스트 (선택)

이벤트 체이닝이 복잡해지면, 개별 핸들러만 격리해서 테스트하고 싶을 수 있다. 이 경우 FakeUnitOfWork를 확장하여 발행된 이벤트를 캡처하는 방식을 사용한다.

class FakeUnitOfWorkWithFakeMessageBus(FakeUnitOfWork):
    def __init__(self):
        super().__init__()
        self.events_published = []

    def publish_events(self):
        for product in self.products.seen:
            while product.events:
                self.events_published.append(product.events.pop(0))

def test_reallocates_if_necessary_isolated():
    uow = FakeUnitOfWorkWithFakeMessageBus()
    # ... 이벤트 히스토리 설정 ...
    messagebus.handle(events.BatchQuantityChanged("batch1", 25), uow)

    # 연쇄 실행 결과가 아닌, 발행된 이벤트만 검증
    [reallocation_event] = uow.events_published
    assert isinstance(reallocation_event, events.AllocationRequired)
    assert reallocation_event.orderid in {"order1", "order2"}

전체 체인을 실행하지 않고, “이 핸들러가 올바른 이벤트를 발행하는가?”만 검증할 수 있다.

Chapter 9 트레이드오프 정리

장점	단점
핸들러와 서비스 함수가 하나의 개념으로 통합된다	메시지 버스는 웹 관점에서 예측하기 어렵다 (언제 끝나는지 모른다)
이벤트가 시스템 입력을 깔끔하게 표현한다	도메인 객체와 이벤트 간 필드 중복이 생긴다
새 요구사항에 아키텍처 변경 없이 이벤트/핸들러만 추가하면 된다	필드 추가 시 여러 관련 구조를 함께 수정해야 한다
이벤트 체이닝으로 복잡한 워크플로우를 자연스럽게 처리한다	서로 다른 트랜잭션에서 일부만 성공하면 정합성 문제가 생길 수 있다

핵심 정리: 복잡성 증가 속도를 늦추는 것

Chapter 8과 9를 관통하는 핵심 메시지는 이것이다.

“애플리케이션 크기에 비해 복잡성이 더 빠르게 증가하지 않도록 하는 것”

배치 수량 변경 → 할당 해제 → 재할당 → 알림 발송이라는 복잡한 요구사항이 들어왔지만, 기존 아키텍처 패턴을 그대로 사용하여 이벤트와 핸들러만 추가하는 것으로 해결했다.

BatchQuantityChanged 이벤트
    │
    ▼
change_batch_quantity 핸들러
    │ (수량 초과 시 deallocate → AllocationRequired 이벤트 발행)
    ▼
allocate 핸들러
    │ (재고 부족 시 OutOfStock 이벤트 발행)
    ▼
send_out_of_stock_notification 핸들러

새로운 아키텍처 카테고리를 도입할 필요 없이, 동일한 패턴의 반복으로 복잡한 비즈니스 요구를 처리할 수 있게 된 것이다.

다음 장에서는 커맨드(Command)와 이벤트(Event)의 구분을 다룬다. “수행해야 할 작업”과 “이미 발생한 사실”을 왜 구분해야 하는지 알아보게 된다.

참고 자료

Cosmic Python 제1부(3): Unit of Work와 Aggregate 패턴

Sat, 24 Jan 2026 10:00:00 +0900

Chapter 6: Unit of Work 패턴

문제: 트랜잭션 관리가 지저분하다

서비스 레이어에서 session을 직접 다루면, 커밋/롤백 로직이 서비스마다 반복된다. 그리고 서비스 레이어가 session이라는 인프라 세부사항을 알고 있어야 한다.

해결: Unit of Work로 원자적 연산 추상화

Unit of Work는 “이 작업들은 전부 성공하거나, 전부 실패해야 한다”를 표현하는 패턴이다. Python의 컨텍스트 매니저(with 문)와 찰떡궁합이다.

class AbstractUnitOfWork(abc.ABC):
    products: AbstractRepository

    def __enter__(self):
        return self

    def __exit__(self, *args):
        self.rollback()

    @abc.abstractmethod
    def commit(self):
        raise NotImplementedError

    @abc.abstractmethod
    def rollback(self):
        raise NotImplementedError

SQLAlchemy 구현

class SqlAlchemyUnitOfWork(AbstractUnitOfWork):
    def __init__(self, session_factory=DEFAULT_SESSION_FACTORY):
        self.session_factory = session_factory

    def __enter__(self):
        self.session = self.session_factory()
        self.products = SqlAlchemyRepository(self.session)
        return self

    def __exit__(self, *args):
        super().__exit__(*args)
        self.session.close()

    def commit(self):
        self.session.commit()

    def rollback(self):
        self.session.rollback()

서비스 레이어가 깔끔해진다

def allocate(orderid: str, sku: str, qty: int,
             uow: AbstractUnitOfWork) -> str:
    line = OrderLine(orderid, sku, qty)
    with uow:
        product = uow.products.get(sku=sku)
        if product is None:
            raise InvalidSku(f"Invalid sku {sku}")
        batchref = product.allocate(line)
        uow.commit()
        return batchref

session이 사라지고, uow 하나로 통합되었다.

with uow: — 트랜잭션 시작
uow.products — Repository 접근
uow.commit() — 명시적 커밋
예외 발생 시 — 자동 롤백 (__exit__에서)

명시적 커밋, 암묵적 롤백. 성공적인 경로에서만 commit()이 호출되고, 그 외에는 모두 롤백된다.

Chapter 7: Aggregate와 일관성 경계

문제: 동시성 환경에서 일관성을 어떻게 보장할까?

두 명의 사용자가 동시에 같은 SKU의 재고를 할당하려고 한다면? 둘 다 “재고 10개 남음”을 읽고, 둘 다 할당에 성공하면 재고가 마이너스가 될 수 있다.

해결: Aggregate로 일관성 경계 설정

Aggregate는 데이터 변경의 단위로 취급하는 관련 객체들의 클러스터다. (Eric Evans)

class Product:
    def __init__(self, sku: str, batches: List[Batch],
                 version_number: int = 0):
        self.sku = sku
        self.batches = batches
        self.version_number = version_number

    def allocate(self, line: OrderLine) -> str:
        try:
            batch = next(
                b for b in sorted(self.batches)
                if b.can_allocate(line)
            )
            batch.allocate(line)
            self.version_number += 1
            return batch.reference
        except StopIteration:
            raise OutOfStock(f"Out of stock for sku {line.sku}")

핵심 원칙들을 정리하면 이렇다.

1. Aggregate가 유일한 진입점

Batch를 직접 수정하지 않는다. 반드시 Product를 통해서만 접근한다. 이렇게 하면 Product가 내부 일관성을 보장할 수 있다.

2. 하나의 Aggregate = 하나의 Repository

BatchRepository (X) → ProductRepository (O)

Repository는 Aggregate 단위로 만든다. Batch를 직접 꺼내오는 Repository는 없다.

3. 낙관적 동시성 제어 (Optimistic Concurrency)

version_number를 사용한다.

할당할 때마다 version_number를 증가시킨다
커밋 시점에 DB의 version_number와 비교한다
다른 트랜잭션이 먼저 수정했으면 충돌 감지 → 재시도

# 비관적 잠금 방식도 가능
def get(self, sku):
    return (
        self.session.query(model.Product)
        .filter_by(sku=sku)
        .with_for_update()  # SELECT FOR UPDATE
        .first()
    )

구분	낙관적 잠금	비관적 잠금
전략	충돌이 드물다고 가정	충돌이 빈번하다고 가정
동작	커밋 시점에 충돌 감지	읽기 시점에 잠금 획득
성능	경합이 적으면 좋다	경합이 많으면 좋다
구현	version_number	SELECT FOR UPDATE

Part 1의 큰 그림

Part 1의 모든 패턴이 어떻게 조합되는지 정리해보자.

Flask / CLI (진입점)
    │
    ▼
Service Layer (유스케이스 오케스트레이션)
    │
    ├─ Unit of Work (트랜잭션 관리)
    │   │
    │   └─ Repository (영속성 추상화)
    │       │
    │       └─ Aggregate (일관성 경계)
    │           │
    │           └─ Domain Model (비즈니스 로직)
    │
    ▼
Database (인프라)

의존성 방향은 항상 안쪽으로 향한다.

Flask는 Service Layer를 안다
Service Layer는 UoW와 도메인 모델을 안다
도메인 모델은 아무것도 모른다 (순수 파이썬)

이것이 양파(Onion) 아키텍처의 핵심이다. 도메인 모델이 중심에 있고, 인프라가 바깥을 감싼다.

Part 1 트레이드오프 총정리

패턴	얻는 것	잃는 것
Domain Model	비즈니스 로직이 명확하게 표현됨	단순 CRUD에는 과하다
Repository	DB 독립적인 테스트, 저장소 교체 가능	ORM 매핑 설정이 추가됨
Service Layer	유스케이스가 명확히 분리됨	추상화 레이어가 하나 더 생긴다
Unit of Work	트랜잭션이 깔끔하게 관리됨	SQLAlchemy가 이미 제공하는 기능이기도 하다
Aggregate	동시성 환경에서 일관성 보장	개발자의 사고방식 전환이 필요하다

이 패턴들은 도메인이 복잡할수록 빛을 발한다. 단순한 CRUD 앱이라면 오히려 과한 투자일 수 있다. 복잡도에 따라 판단하자.

이전 글: 제1부(2): Service Layer와 TDD 전략

다음: 제2부: 이벤트 기반 아키텍처(Event-Driven Architecture)에서 이어진다.

참고 자료

spao proj rebuild

Sun, 18 Jan 2026 10:00:00 +0900

Cosmic Python 제1부(2): Service Layer와 TDD 전략

Tue, 13 Jan 2026 10:00:00 +0900

Chapter 4: Service Layer (서비스 레이어)

문제: Flask 엔드포인트가 너무 뚱뚱하다

웹 컨트롤러에 비즈니스 로직을 넣으면 어떻게 될까?

@app.route("/allocate", methods=["POST"])
def allocate_endpoint():
    session = get_session()
    batches = repository.SqlAlchemyRepository(session).list()
    line = model.OrderLine(
        request.json["orderid"],
        request.json["sku"],
        request.json["qty"],
    )
    # 검증 로직, 에러 처리, 도메인 로직, 커밋... 전부 여기에?

컨트롤러가 검증, 비즈니스 로직, 데이터 접근, 에러 처리를 전부 담당하게 된다. 테스트하려면 HTTP 요청을 보내야 하고, DB가 떠 있어야 한다.

해결: 서비스 레이어로 오케스트레이션 분리

서비스 레이어는 유스케이스의 오케스트레이션(조율)을 담당한다. 직접 비즈니스 로직을 수행하는 게 아니라, 도메인 모델을 호출하는 역할이다.

def allocate(orderid: str, sku: str, qty: int,
             repo: AbstractRepository, session) -> str:
    batches = repo.list()
    if not is_valid_sku(sku, batches):
        raise InvalidSku(f"Invalid sku {sku}")
    line = OrderLine(orderid, sku, qty)
    batchref = model.allocate(line, batches)
    session.commit()
    return batchref

이제 Flask 엔드포인트는 요청 파싱과 응답 반환만 한다.

@app.route("/allocate", methods=["POST"])
def allocate_endpoint():
    try:
        batchref = services.allocate(
            request.json["orderid"],
            request.json["sku"],
            request.json["qty"],
            repo, session,
        )
    except services.InvalidSku as e:
        return {"message": str(e)}, 400
    return {"batchref": batchref}, 201

두 종류의 “서비스”를 구분하자

구분	애플리케이션 서비스 (Service Layer)	도메인 서비스
역할	외부 요청을 받아서 조율	비즈니스 로직 수행
예시	`services.allocate()`	`model.allocate()`
알고 있는 것	Repository, UoW, 도메인 모델	순수 도메인 개념만

서비스 레이어는 “할 일을 조율”하고, 도메인 서비스는 “실제로 일을 수행”한다. 비즈니스 로직이 서비스 레이어로 새어나가지 않도록 주의해야 한다. (빈약한 도메인 모델 안티패턴)

Chapter 5: TDD의 고속 기어와 저속 기어

테스트 피라미드는 건강한가?

서비스 레이어를 도입한 후, 테스트 분포를 살펴보면 이렇다.

단위 테스트 15개 — 빠르고, 도메인 로직 검증
통합 테스트 8개 — DB 연동 확인
E2E 테스트 2개 — 전체 시스템 동작 확인

건강한 테스트 피라미드 모양이다. 단위 테스트가 가장 많고, 느린 테스트는 적다.

하지만 여기서 한 가지 질문이 생긴다. 도메인 레이어 테스트를 서비스 레이어로 옮겨야 할까?

고속 기어 vs 저속 기어

자전거 기어에 비유하면 이해가 쉽다.

저속 기어: 도메인 레이어 TDD

def test_prefers_current_stock_batches_to_shipments():
    in_stock_batch = Batch("in-stock-batch", "RETRO-CLOCK", 100, eta=None)
    shipment_batch = Batch("shipment-batch", "RETRO-CLOCK", 100, eta=tomorrow)
    line = OrderLine("oref", "RETRO-CLOCK", 10)

    allocate(line, [in_stock_batch, shipment_batch])

    assert in_stock_batch.available_quantity == 90
    assert shipment_batch.available_quantity == 100

도메인 객체를 직접 만들고, 직접 호출한다.

장점: 설계 피드백이 풍부하다. 도메인 모델의 API가 어색하면 즉시 느낀다
단점: 도메인 내부 구조에 강하게 결합된다. 리팩터링하면 테스트가 깨진다

고속 기어: 서비스 레이어 TDD

def test_prefers_warehouse_batches_to_shipments():
    repo, session = FakeRepository([]), FakeSession()

    services.add_batch("in-stock-batch", "RETRO-CLOCK", 100, None, repo, session)
    services.add_batch("shipment-batch", "RETRO-CLOCK", 100, tomorrow, repo, session)
    services.allocate("oref", "RETRO-CLOCK", 10, repo, session)

    assert repo.get("in-stock-batch").available_quantity == 90
    assert repo.get("shipment-batch").available_quantity == 100

서비스 함수를 통해서만 상호작용한다.

장점: 도메인 내부를 자유롭게 리팩터링할 수 있다
단점: 설계 피드백이 줄어든다

언제 어떤 기어를 쓸까?

상황	기어	이유
새 프로젝트, 도메인 탐색 중	저속	설계 피드백이 중요하다
도메인 모델이 안정된 후	고속	리팩터링 자유도가 중요하다
복잡한 도메인 규칙 추가	저속	세밀한 검증이 필요하다
일반적인 기능 추가	고속	빠른 개발이 중요하다

핵심은 고정된 하나의 전략이 아니라, 상황에 따라 기어를 바꾸는 것이다.

서비스 레이어 테스트에서 도메인 객체 완전 분리하기

고속 기어로 전환했더라도, 테스트에서 OrderLine이나 Batch를 직접 import하면 여전히 도메인에 결합된다.

1단계: 서비스 함수가 원시 타입을 받도록 변경

# Before: 도메인 객체를 받는다
def allocate(line: OrderLine, repo, session) -> str:

# After: 원시 타입(str, int)을 받는다
def allocate(orderid: str, sku: str, qty: int, repo, session) -> str:
    line = OrderLine(orderid, sku, qty)  # 내부에서 생성
    ...

2단계: 테스트 셋업용 서비스 함수 추가

테스트에서 Batch(...) 를 직접 만들 필요가 없도록, add_batch 서비스 함수를 추가한다.

def add_batch(ref: str, sku: str, qty: int, eta: Optional[date],
              repo: AbstractRepository, session) -> None:
    repo.add(model.Batch(ref, sku, qty, eta))
    session.commit()

결과: 테스트가 완전히 서비스 API로만 표현된다

def test_allocate_returns_allocation():
    repo, session = FakeRepository([]), FakeSession()
    services.add_batch("batch1", "COMPLICATED-LAMP", 100, None, repo, session)

    result = services.allocate("o1", "COMPLICATED-LAMP", 10, repo, session)

    assert result == "batch1"

도메인 객체 import가 사라졌다. 오직 문자열과 숫자만으로 테스트를 작성한다.

“서비스 레이어 테스트에서 도메인 객체를 직접 다뤄야 한다면, 서비스 레이어가 아직 불완전하다는 신호다.”

E2E 테스트도 같은 원칙으로

E2E 테스트에서도 SQL로 직접 데이터를 넣는 대신, HTTP API를 통해 셋업한다.

def test_happy_path_returns_201_and_allocated_batch():
    sku, othersku = random_sku(), random_sku("other")
    earlybatch = random_batchref(1)
    laterbatch = random_batchref(2)
    otherbatch = random_batchref(3)

    post_to_add_batch(laterbatch, sku, 100, "2011-01-02")
    post_to_add_batch(earlybatch, sku, 100, "2011-01-01")
    post_to_add_batch(otherbatch, othersku, 100, None)

    data = {"orderid": random_orderid(), "sku": sku, "qty": 3}
    url = config.get_api_url()
    r = requests.post(f"{url}/allocate", json=data)

    assert r.status_code == 201
    assert r.json()["batchref"] == earlybatch

DB 스키마나 ORM에 결합되지 않는다. HTTP API만으로 셋업과 검증을 한다.

테스트 전략 Rules of Thumb

규칙	설명
기능당 E2E 테스트 1개	전체 연결이 동작하는지만 확인
테스트 대부분은 서비스 레이어에	엣지 케이스까지 포함한 비즈니스 로직 검증
도메인 테스트는 소수만 유지	복잡한 핵심 규칙의 설계 피드백용
서비스 레이어는 원시 타입으로	문자열, 숫자만 받아서 도메인과 분리

“모든 테스트 코드는 접착제다.” 시스템을 특정 모양으로 고정시킨다. 저수준 테스트가 많을수록 내부 변경이 어려워진다. 적절한 추상화 수준에서 테스트하자.

이전 글: 제1부(1): 도메인 모델링, Repository 패턴, 그리고 추상화

다음 글: 제1부(3): Unit of Work와 Aggregate 패턴에서 이어진다.

참고 자료

Cosmic Python 제1부(1): 도메인 모델링, Repository 패턴, 그리고 추상화

Tue, 06 Jan 2026 10:00:00 +0900

제1부: 도메인 모델링을 지원하는 아키텍처 구축

“대부분의 개발자는 도메인 모델을 본 적이 없다. 그들이 본 것은 데이터 모델뿐이다.” — Cyrille Martraire, DDD EU 2017

왜 이 책을 읽어야 할까?

우리가 흔히 하는 개발 방식을 떠올려보자.

데이터베이스 스키마를 먼저 설계하고
ORM 모델을 만들고
그 위에 비즈니스 로직을 얹는다

이 방식이 뭐가 문제일까?

비즈니스 로직이 코드 여기저기에 흩어진다. 컨트롤러에도 있고, 모델에도 있고, 유틸리티 함수에도 있다. 시간이 지나면 “이 로직이 어디에 있더라?” 하면서 코드를 뒤지게 된다.

Cosmic Python의 저자들은 이 접근을 뒤집자고 제안한다.

“저장소가 행동을 결정하는 게 아니라, 행동이 저장소를 결정해야 한다.”

비즈니스 로직을 먼저 설계하고, 데이터베이스는 나중에 생각하자는 것이다.

Part 1에서 다루는 핵심 패턴들

Part 1은 총 7개의 챕터로 구성되어 있다. 각 챕터가 하나의 패턴을 점진적으로 쌓아 올린다.

챕터	패턴	핵심 질문
Ch1	도메인 모델링	“비즈니스 로직을 어떻게 코드로 표현할까?”
Ch2	Repository 패턴	“도메인 모델을 DB에서 어떻게 분리할까?”
Ch3	결합도와 추상화	“좋은 추상화란 무엇일까?”
Ch4	Service Layer	“유스케이스를 어디에 넣을까?”
Ch5	TDD	“테스트 피라미드를 어떻게 최적화할까?”
Ch6	Unit of Work	“트랜잭션을 어떻게 깔끔하게 관리할까?”
Ch7	Aggregate	“일관성 경계를 어떻게 설정할까?”

Chapter 1: 도메인 모델링(Domain Modeling)

도메인 모델이란?

도메인 모델은 “비즈니스 문제를 코드로 표현한 것”이다. 이 책에서는 가구 소매업체의 재고 할당 시스템을 예시로 사용한다.

핵심 비즈니스 규칙은 이렇다.

고객이 주문하면 → 가용 재고에서 할당(allocate)한다
창고 재고를 먼저 할당하고, 입고 예정 배치는 나중에 할당한다
같은 주문 라인을 두 번 할당할 수 없다
재고가 부족하면 할당 실패

값 객체(Value Object)와 엔터티(Entity)

DDD에서 가장 기본적인 두 가지 개념이다.

값 객체: “무엇이냐”가 중요

@dataclass(frozen=True)
class OrderLine:
    orderid: str
    sku: str
    qty: int

frozen=True로 불변(immutable)하게 만든다. 같은 orderid, sku, qty를 가진 두 OrderLine은 동일한 것이다. 정체성(identity)이 없고, 값 자체가 의미다.

엔터티: “누구냐”가 중요

class Batch:
    def __init__(self, ref: str, sku: str, qty: int, eta: Optional[date]):
        self.reference = ref
        self.sku = sku
        self.eta = eta
        self._purchased_quantity = qty
        self._allocations = set()

    def allocate(self, line: OrderLine):
        if self.can_allocate(line):
            self._allocations.add(line)

    def can_allocate(self, line: OrderLine) -> bool:
        return self.sku == line.sku and self.available_quantity >= line.qty

    @property
    def available_quantity(self) -> int:
        return self._purchased_quantity - self.allocated_quantity

    @property
    def allocated_quantity(self) -> int:
        return sum(line.qty for line in self._allocations)

Batch는 reference라는 고유 식별자를 가진다. 수량이 바뀌거나 할당이 추가되어도, 같은 reference면 같은 Batch다.

구분	값 객체(Value Object)	엔터티(Entity)
동일성 기준	값이 같으면 같다	식별자가 같으면 같다
불변성	불변	변경 가능
예시	OrderLine, 주소, 가격	Batch, 주문, 고객

도메인 서비스 함수

모든 로직이 객체에 담기는 건 아니다. “할당한다”라는 행위는 특정 객체에 속하지 않는다. 이런 경우 도메인 서비스 함수로 표현한다.

def allocate(line: OrderLine, batches: List[Batch]) -> str:
    try:
        batch = next(
            b for b in sorted(batches) if b.can_allocate(line)
        )
    except StopIteration:
        raise OutOfStock(f"Out of stock for sku {line.sku}")
    batch.allocate(line)
    return batch.reference

비즈니스 규칙이 그대로 코드에 녹아 있다.

sorted(batches): 창고 재고(ETA 없음)를 먼저, 그 다음은 입고일 빠른 순서로
can_allocate: SKU가 맞고 수량이 충분한지 확인
OutOfStock: 재고 부족이라는 도메인 예외

Chapter 2: Repository 패턴

문제: ORM이 도메인을 오염시킨다

보통 Django나 SQLAlchemy를 쓰면, 도메인 모델이 ORM에 종속된다. models.Model을 상속받거나, ORM 필드를 직접 정의하게 되면 도메인 모델이 인프라를 알게 된다.

그런데 도메인 모델은 비즈니스 로직만 알아야 한다. 데이터베이스가 MySQL인지 PostgreSQL인지, ORM이 뭔지 몰라도 되어야 한다.

해결: 의존성 역전(Dependency Inversion)

“인프라가 도메인에 의존해야지, 도메인이 인프라에 의존하면 안 된다.”

Repository 패턴은 영속성 저장소에 대한 추상화다. 마치 인메모리 컬렉션처럼 add()와 get()만 제공한다.

class AbstractRepository(abc.ABC):
    @abc.abstractmethod
    def add(self, entity):
        raise NotImplementedError

    @abc.abstractmethod
    def get(self, reference) -> model.Batch:
        raise NotImplementedError

실제 구현 (SQLAlchemy)

class SqlAlchemyRepository(AbstractRepository):
    def __init__(self, session):
        self.session = session

    def add(self, batch):
        self.session.add(batch)

    def get(self, reference):
        return self.session.query(model.Batch)\
            .filter_by(reference=reference).one()

테스트용 Fake 구현

class FakeRepository(AbstractRepository):
    def __init__(self, batches):
        self._batches = set(batches)

    def add(self, batch):
        self._batches.add(batch)

    def get(self, reference):
        return next(b for b in self._batches
                    if b.reference == reference)

데이터베이스 없이도 테스트를 돌릴 수 있다. 테스트가 빨라지고 안정적이 된다.

AbstractRepository는 포트(Port), SqlAlchemyRepository와 FakeRepository는 어댑터(Adapter)다. 이것이 바로 포트-어댑터(헥사고날) 아키텍처의 핵심이다.

Chapter 3: 결합도와 추상화

“테스트 가능하게 설계한다는 것은 곧, 확장 가능하게 설계한다는 뜻이다.”

문제: 비즈니스 로직과 I/O가 뒤엉켜 있다

파일 동기화 도구를 예로 들어보자. 소스 디렉토리와 목적지 디렉토리를 비교해서 파일을 복사/이동/삭제하는 프로그램이다.

def sync(source, dest):
    # 1. 소스 파일 해시 수집 (I/O)
    source_hashes = {}
    for folder, _, files in os.walk(source):
        for fn in files:
            source_hashes[hash_file(Path(folder) / fn)] = fn

    seen = set()

    # 2. 목적지 파일과 비교 + 즉시 실행 (로직 + I/O 혼합)
    for folder, _, files in os.walk(dest):
        for fn in files:
            dest_path = Path(folder) / fn
            dest_hash = hash_file(dest_path)
            seen.add(dest_hash)

            if dest_hash not in source_hashes:
                dest_path.remove()
            elif fn != source_hashes[dest_hash]:
                shutil.move(dest_path, Path(folder) / source_hashes[dest_hash])

    for source_hash, fn in source_hashes.items():
        if source_hash not in seen:
            shutil.copy(Path(source) / fn, Path(dest) / fn)

이 코드의 문제점:

비즈니스 로직(어떤 파일을 복사/이동/삭제할지 결정)과 I/O(실제 파일 조작)가 한 함수에 섞여 있다
테스트하려면 실제 파일 시스템이 필요하다 → 느리고 불안정하다
--dry-run 모드나 클라우드 스토리지 지원을 추가하기 어렵다

이것이 바로 결합(coupling)이다. 컴포넌트 A를 변경하면 컴포넌트 B가 깨질까 두려운 상태.

해결: 세 가지 책임을 분리하자

하나의 함수에 묻혀 있던 세 가지 책임을 명확히 분리한다.

1단계: I/O 수집 (Imperative Shell)

def read_paths_and_hashes(root):
    hashes = {}
    for folder, _, files in os.walk(root):
        for fn in files:
            hashes[hash_file(Path(folder) / fn)] = fn
    return hashes

2단계: 순수 비즈니스 로직 (Functional Core)

def determine_actions(source_hashes, dest_hashes, source_folder, dest_folder):
    for sha, filename in source_hashes.items():
        if sha not in dest_hashes:
            sourcepath = Path(source_folder) / filename
            destpath = Path(dest_folder) / filename
            yield "COPY", sourcepath, destpath

        elif dest_hashes[sha] != filename:
            olddestpath = Path(dest_folder) / dest_hashes[sha]
            newdestpath = Path(dest_folder) / filename
            yield "MOVE", olddestpath, newdestpath

    for sha, filename in dest_hashes.items():
        if sha not in source_hashes:
            yield "DELETE", dest_folder / filename

I/O가 전혀 없다. 딕셔너리를 받아서 튜플을 반환할 뿐이다. “무엇을 할지”를 결정하지만, “어떻게 실행할지”는 모른다.

3단계: 오케스트레이션 (Imperative Shell)

def sync(source, dest):
    source_hashes = read_paths_and_hashes(source)
    dest_hashes = read_paths_and_hashes(dest)

    actions = determine_actions(source_hashes, dest_hashes, source, dest)

    for action, *paths in actions:
        if action == "COPY":
            shutil.copyfile(*paths)
        if action == "MOVE":
            shutil.move(*paths)
        if action == "DELETE":
            os.remove(paths[0])

이것이 Gary Bernhardt의 Functional Core, Imperative Shell 패턴이다.

Functional Core: 순수 함수로 비즈니스 로직 수행 (side-effect 없음)
Imperative Shell: 바깥에서 I/O를 처리하고 결과를 전달

테스트가 깔끔해진다

def test_when_a_file_exists_in_the_source_but_not_the_destination():
    source_hashes = {"hash1": "fn1"}
    dest_hashes = {}
    actions = determine_actions(source_hashes, dest_hashes, Path("/src"), Path("/dst"))
    assert list(actions) == [("COPY", Path("/src/fn1"), Path("/dst/fn1"))]


def test_when_a_file_has_been_renamed_in_the_source():
    source_hashes = {"hash1": "fn1"}
    dest_hashes = {"hash1": "fn2"}
    actions = determine_actions(source_hashes, dest_hashes, Path("/src"), Path("/dst"))
    assert list(actions) == [("MOVE", Path("/dst/fn2"), Path("/dst/fn1"))]

파일 시스템이 필요 없다. 딕셔너리 → 리스트 변환을 검증할 뿐이다.

Fake와 의존성 주입으로 Edge-to-Edge 테스트

순수 함수 테스트만으로는 전체 흐름을 검증하기 어렵다. 의존성 주입(DI)을 사용하면 최상위 sync() 함수도 테스트할 수 있다.

class FakeFilesystem:
    def __init__(self, path_hashes):
        self.path_hashes = path_hashes
        self.actions = []

    def read(self, path):
        return self.path_hashes[path]

    def copy(self, source, dest):
        self.actions.append(("COPY", source, dest))

    def move(self, source, dest):
        self.actions.append(("MOVE", source, dest))

    def delete(self, dest):
        self.actions.append(("DELETE", dest))

이 Fake는 실제 파일 시스템을 흉내내면서, 어떤 동작이 수행되었는지 기록한다. sync(source, dest, filesystem=FakeFilesystem(...))처럼 주입하면 된다.

DI의 실질적 이점은 테스트뿐만이 아니다. --dry-run 플래그, FTP/S3 스토리지 전환 등 확장성도 함께 얻는다.

Mock vs Fake: 어떤 걸 써야 할까?

저자들은 unittest.mock.patch를 피하는 이유를 세 가지로 든다.

설계를 개선하지 않는다: shutil.copy를 mock할 수는 있지만, --dry-run이나 FTP 지원은 여전히 불가능하다
구현에 결합된다: assert_called_once_with로 “어떻게 호출되었는지”를 검증하면, 내부 리팩터링 시 테스트가 깨진다
테스트가 복잡해진다: setup 코드가 테스트의 의도를 가린다

구분	Mock	Fake
검증 대상	호출 방식 (behavior)	최종 상태 (state)
스타일	London-school TDD	Classic-style TDD
장점	세밀한 행위 검증	리팩터링에 강하다
단점	구현 변경 시 테스트 깨짐	Fake 구현 비용

이 책은 Classic-style(Fake 기반)을 따른다.

좋은 추상화를 찾는 체크리스트

지저분한 시스템의 상태를 익숙한 파이썬 자료구조로 표현할 수 있는가?
“무엇을 할지”와 “어떻게 실행할지”를 분리할 수 있는가?
어디에 이음새(seam)를 넣어 추상화를 끼워 넣을 수 있는가?
암묵적인 개념을 명시적으로 만들 수 있는가?

“연습하면 덜 불완전해진다!” (Practice makes less imperfect!)

다음 글: 제1부(2): Service Layer와 TDD 전략에서 이어진다.

참고 자료

Yeong Rok n roll

Django 운영 코드 정리: 보안, 테스트, i18n, 계정 복구

들어가며

1. 통계 JSON을 |safe로 넘기던 문제

2. 로그인 실패를 제한하기

3. CDN 스크립트에 SRI 추가하기

4. pytest를 쓰지만 pytest답지 않았던 테스트

5. 테스트 정리 중 발견한 locale leak

6. i18n은 문자열 치환만으로 끝나지 않았다

7. 계정 복구 기능 추가

8. SMTP 실패를 500으로 끝내지 않기

9. 이번 작업에서 남긴 기준

마무리

Django 리팩토링 기록: 뷰, 유스케이스, 그리고 비용 최적화

들어가며

뷰가 무거워지기 시작한 순간

뷰에 남길 것과 옮길 것

Use Case로 옮긴 처리 흐름

일부만 저장될 수 있는 위험 줄이기

bulk_create가 놓치는 검증 지점

조회 로직을 한곳에 모은 이유

통계 화면이 생각보다 복잡했던 이유

순환 참조가 없어도 의존성은 불편해질 수 있다

코드뿐 아니라 쿼리와 세션도 정리했다

개선 효과는 측정해야 알 수 있다

일부러 하지 않은 것들

정리 후에 보인 다음 과제

좋은 리팩토링은 이유가 남는다

AI 시대에 개발자는 사라지는가, 아니면 더 높은 레이어로 이동하는가

들어가며

코드를 짜는 능력과 소프트웨어를 만드는 능력은 다르다

AI가 가장 먼저 먹어치우는 일은 무엇인가

그래서 개발자의 핵심 역할은 어디로 이동하는가

1. 문제를 정의하는 사람

2. 제약을 설계하는 사람

3. 문맥을 연결하는 사람

4. 검증하고 책임지는 사람

5. 운영과 현실을 이해하는 사람

6. 팀을 정렬시키는 사람

AI 시대의 커뮤니케이션은 무엇이 달라지는가

1. 모호함을 줄이는 능력

2. 설계 의도를 설명하는 능력

3. 비기술 직군과 번역하는 능력

4. 비동기 협업을 잘하는 능력

백엔드 개발자에게 특히 중요한 이유

AI 시대에 약해지는 개발자와 강해지는 개발자

결국 개발자는 사라지지 않는다. 다만 더 높은 레이어로 밀려 올라간다

마치며

Cosmic Python 제2부: CQRS, 의존성 주입, 그리고 에필로그

Chapter 12: CQRS (Command-Query Responsibility Segregation)

왜 읽기와 쓰기를 분리해야 할까?

읽기 모델의 4가지 구현 방법

방법 A: Repository 패턴 그대로 사용

방법 B: ORM 쿼리

방법 C: 순수 SQL

방법 D: 비정규화된 읽기 전용 테이블 + 이벤트 핸들러 (CQRS 본격 적용)

이벤트 핸들러로 읽기 모델 갱신

읽기 모델의 유연성: 저장소 교체

읽기 모델이 깨지면?

Post/Redirect/Get 패턴

Chapter 12 트레이드오프 정리

Chapter 13: 의존성 주입과 부트스트래핑(Dependency Injection and Bootstrapping)

문제: 암묵적 의존성

해결: 명시적 의존성 주입

부트스트랩 스크립트: 조합의 뿌리(Composition Root)

의존성 자동 주입: 시그니처 검사

메시지 버스가 클래스로 변환

진입점(Entrypoint)이 깔끔해진다

Flask

테스트에서의 활용

통합 테스트: SQLite + 가짜 외부 서비스

단위 테스트: 전부 가짜

어댑터 만들기: ABC → 구현 → 가짜 → 테스트

1단계: 추상 클래스(Port) 정의

2단계: 프로덕션 구현(Adapter)

3단계: 가짜 구현(테스트용)

4단계: 부트스트랩에서 조립

Chapter 13 트레이드오프 정리

에필로그: 현실 프로젝트에 어떻게 적용할까?

핵심 원칙: 점진적으로 적용하라

1. 통계 JSON을 `|safe`로 넘기던 문제