DRF답게 짜려다 Service Layer까지 온 이야기
최민수

l “이 함수에 뭐가 들어오는 거에요?”💡
코드 리뷰 중 팀원에게 이 질문을 받았을 때, 저는 한참을 호출 스택을 거슬러 올라가야 했습니다.
5분쯤 지나서야 ‘아, 여기서 넘기는 거였구나’를 파악했고, 팀원에게 슬랙으로 설명을 보냈습니다. 그 팀원도 같은 코드를 보고 있었는데 말이죠.
사소한 해프닝처럼 보이지만, 이런 일이 하루에 몇 번씩 반복되면 이야기가 달라집니다.
코드를 이해하는 데 쓰는 시간이 코드를 짜는 시간보다 길어지는 순간이 오기 때문입니다.
그게 이 글의 출발점입니다.
빠르게 성장하는 서비스, 느려지는 개발자

스타트업 초기에는 속도가 전부입니다. 기획이 바뀌고, 요구사항이 바뀌고, 심지어 도메인 자체가 바뀌기도 합니다. 그 과정에서 코드는 자연스럽게 ‘일단 동작하게’를 최우선으로 짜게 됩니다. 그리고 그건 틀린 선택이 아닙니다. 존재하지 않는 서비스를 아름답게 설계하는 것보다, 빠르게 검증하고 살아남는 게 더 중요하니까요.
문제는 그 다음입니다.
팀이 커지고, 스쿼드가 나뉘기 시작하면서 각자의 방식으로 짜인 코드들이 서로 얽히기 시작했습니다. 누군가의 Utils가 다른 누군가의 Service를 호출하고, 그 서비스는 또 다른 누군가의
helpers 를 참조합니다. 어디서 무슨 데이터가 어떻게 흘러가는지 파악하려면 파일을 열고, 닫고, 또 열어야 했습니다.
특히 레이어 간 데이터 전달 방식이 제각각이었습니다. 어떤 부분에서는 이런 코드를 사용했습니다.

그리고 어떤 부분에서는 이런 코드로 구현했습니다.

전자는 파라미터가 늘어날수록 함수 시그니처가 끝없이 길어집니다. 후자는 data 안에 뭐가 있는지 코드를 다 뜯어보기 전엔 알 수 없는 블랙박스가 됩니다. 두 방식 모두 팀 규모가 커질수록 협업 비용이 기하급수적으로 올라가는 건 마찬가지였습니다.
그러던 중 저는 새로운 기능을 개발하다가 기존 코드를 수정해야 할 일이 생겼습니다. 함수 하나를 고치려고 열었는데, 그 함수의 data 파라미터가 어디서 채워지는지 파악하기 위해 결국 View → Serializer → 중간 유틸 함수 → 최종 서비스 함수까지 네 개의 파일을 오가며 30분을 쓴 겁니다. 고치는 시간은 5분도 안 걸렸는데 말이죠.
이건 단순한 불편함이 아니라, 팀 전체의 생산성을 갉아먹는 구조적인 문제였습니다.
저는 근본적인 해결책을 찾아야겠다고 생각했고, 자연스럽게 이 질문으로 돌아왔습니다.
“DRF답게 짜자”

문제의 원인을 찾다 보니 결국 이 질문으로 돌아왔습니다.
l “우리가 DRF라는 프레임워크를 제대로 쓰고 있는가?”
DRF의 철학은 명확합니다. Serializer가 단순한 JSON 변환기가 아니라,
데이터의 유효성 검증부터 객체 생성까지 책임지는 레이어가 되어야 한다는 것입니다.
공식 문서 역시 create, update 메서드를 오버라이딩하거나, ViewSet의 get_queryset을 활용해서 비즈니스 로직을 처리하는 방식을 권장합니다.
그래서 우선 이 방향으로 리팩토링을 시도했습니다.
Fat Serializer 방식


데이터의 흐름이 Serializer 안에서 명확하게 보였습니다.
validated_data에 어떤 필드가 있는지, 어떤 검증을 거치는지 한눈에 파악할 수 있었습니다. Swagger 문서도 자동으로 완성됐습니다. 좋았습니다.
그런데 곧 요구사항이 붙기 시작했습니다. 닉네임 중복 검사, 프로필 이미지 변경 시 기존 파일 정리, 특정 조건에서의 알림 발송… 지금도 이미 update 안에 저장 로직과 후처리 로직이 섞여 있는데, 여기에 더 얹어야 한다고 생각하니 머뭇거려졌습니다.
점점 Serializer가 알아야 하는 비즈니스 로직이 복잡해지기 시작했습니다.
Fat Serializer의 한계
결국 요구사항은 전부 update 메서드 안으로 들어왔습니다:
- 닉네임 중복 검사 (DB 조회)
- 프로필 이미지 변경 시 기존 이미지 S3에서 삭제
- 닉네임 변경 이력 기록
- 특정 조건에서 알림 발송
더 늘어난 update 메서드는 이렇게 되었습니다.

Serializer가 S3를 알고 있습니다. 알림 서비스를 알고 있습니다. 히스토리 테이블도 알고 있습니다.
이건 더 이상 데이터 직렬화/역직렬화 레이어가 아닙니다. ViewSet의 get_queryset도 마찬가지입니다.
복잡한 조회 조건이 붙기 시작하면 금세 수십 줄짜리 메서드가 됩니다.
Serializer가 알아야 할 것만 알게 하고, 복잡한 비즈니스 로직은 분리해야 했습니다.
Service Layer 도입
해결책은 비교적 명확했습니다. 복잡한 비즈니스 로직을 담당하는 Service Layer를 별도로 두는 것입니다.

Serializer는 본연의 역할인 입력 검증과 형 변환에 집중하고, 비즈니스 로직은 Service가 담당합니다.


구조는 좋아졌는데, 처음의 문제가 다시 돌아왔습니다.
serializer.validated_data를 dict 그대로 Service로 넘기는 순간, Service 함수의 data 파라미터는 다시 블랙박스가 됩니다. Service 코드만 보는 팀원은 이 함수를 호출하기 위해 Serializer 정의를 다시 찾아봐야 합니다.
TypedDict로 레이어 간 전달을 명확히
이 문제를 해결하기 위해 TypedDict를 활용해 레이어 간 데이터 구조를 명시적으로 선언했습니다.
왜 TypedDict인가?
선택지를 고를 때 먼저 이 질문을 던졌습니다.
l “Service로 데이터가 넘어오는 시점에, 우리에게 무엇이 필요한가?”
답은 단순했습니다. 이미 Serializer가 모든 검증을 끝낸 상태입니다. 필드 존재 여부, 타입, 길이 제약, 커스텀 validate 로직까지 전부 is_valid()를 통과했습니다. Service 레이어에 도달하는 순간 데이터는 이미 신뢰할 수 있는 상태입니다.
그렇다면 이 시점에 필요한 건 재검증이 아니라, 구조를 명시하는 것뿐입니다.
이 관점에서 보면 dataclass나 Pydantic은 오버스펙입니다.
dataclass: 인스턴스 생성, 기본값,__repr__등 부가 기능이 따라오지만, 우리에게 필요한 건 그런 게 아닙니다.validated_data를 dataclass 인스턴스로 변환하는 매핑 코드만 늘어납니다.Pydantic: 강력한 런타임 검증과 파싱을 제공하지만, 이미 Serializer가 다 한 일을 Pydantic이 또 합니다. 검증이 두 레이어에서 이중으로 일어나는 셈이고, 프로젝트에 의존성도 추가됩니다.
우리에게 필요한 건 오직 “이 dict 안에 어떤 키가 있는지 선언하는 것” 입니다. TypedDict는 그 역할에 정확히 맞습니다.
- 런타임 오버헤드 없음: 순수 타입 힌트로, 런타임에 추가 객체를 생성하지 않습니다.
- dict와의 호환성:
serializer.validated_data는dict이므로 캐스팅이 자연스럽습니다. - 외부 의존성 없음: 표준 라이브러리만으로 해결됩니다.
실제 적용


ViewSet의 update를 재정의하지 않아도 됩니다.
DRF의 기본 흐름인 serializer.save() → serializer.update()가 그대로 동작하고, Serializer의 update 안에서 DTO를 만들어 Service로 넘기면 됩니다.
View는 라우팅에만 집중하고, 데이터 검증은 Serializer, 비즈니스 로직은 Service가 담당하는 역할 분리가 자연스럽게 완성됩니다.
물론 여기서 validated_data를 cast하는 과정에 대한 한계점은 있습니다. 레이어의 추가로 인해 두 정의(Serializer와 DTO)를 분리해서 관리하는 구조 자체의 한계 때문입니다. 실제로 validated_data의 키가 TypedDict 정의와 다르더라도 런타임 오류가 나지 않습니다.
하지만 이 ‘관리 포인트의 분리’에서 오는 불안함은 유닛 테스트를 통해 충분히 통제 가능한 영역입니다. 이러한 동기화 문제를 해결하기 위해, 아래와 같은 테스트 코드를 추가한다면 문제를 깔끔하게 해결할 수 있습니다.

이렇게 하면 개발자가 실수로 어느 한쪽의 필드 수정을 누락하더라도 CI 과정에서 즉시 발견할 수 있습니다.
명시적인 구조를 유지하면서도 런타임의 불안함을 테스트 레이어에서 보완하는 셈입니다.
최종 아키텍처
전체 데이터 흐름을 정리하면 다음과 같습니다.

각 레이어의 책임이 명확합니다.

이렇게까지 해서 얻은 것
1. IDE 자동완성과 타입 안전성

TypedDict는 mypy, pyright 등 주요 정적 분석 도구가 모두 지원하는 표준 타입 힌트입니다. VSCode의 Pylance(pyright 기반)를 쓰든, PyCharm의 내장 분석기를 쓰든 동일하게 동작합니다. CI에 정적 분석 단계를 추가해두면 잘못된 필드 이름이나 누락된 필수값을 배포 전에 잡을 수 있습니다.
2. OpenAPI 문서 자동 생성
drf-spectacular를 사용할 때, Serializer가 명확하게 정의되어 있으면 @extend_schema나 OpenApiParameter 를 따로 선언할 필요가 없습니다.
Serializer 없이 dict로 데이터를 받는 View는 drf-spectacular가 스키마를 추론할 수 없어서 이런 코드가 필요해집니다.

그리고 이 선언을 하나라도 빠뜨리면 Swagger UI에서 해당 필드 자체가 사라집니다.
문서는 존재하는데 Swagger에서 직접 요청을 보낼 수 없는 상황이 생깁니다.
결국 프론트엔드 개발자나 QA가 Postman 같은 외부 도구를 별도로 띄워서 테스트해야 했습니다.
‘Swagger 있는데 왜 Postman을 써야 하나?’라는 의문이 생긴 적도 있습니다.
Serializer가 명확히 정의되어 있으면 이 모든 선언이 필요 없습니다.

nickname이 필수인지, bio가 optional인지, 각 필드의 타입은 무엇인지를 drf-spectacular가 Serializer 정의에서 직접 읽어갑니다. Serializer를 제대로 정의하는 것 자체가 곧 API 문서 작업입니다. 프론트엔드 팀과 “이 필드 필수인가요?”를 주고받는 시간이 사라집니다.
3. 테스트 작성이 쉬워짐
Service Layer를 독립적으로 테스트할 때 DTO를 직접 생성하면 됩니다.
Serializer를 거칠 필요가 없습니다.

마치며
돌이켜보면 이 고민은 단순히 ‘코드를 예쁘게 만드는’ 작업이 아니었습니다.
Fat Serializer는 DRF의 철학을 따르는 좋은 출발점이었지만, 복잡한 도메인 앞에서 한계가 있었습니다. Service Layer는 비즈니스 로직을 분리하는 좋은 해결책이었지만, 레이어 간 데이터 전달이라는 새로운 문제를 가져왔습니다. TypedDict DTO는 그 문제를 해결하는 가장 단순한 방법이었습니다.
완벽한 아키텍처는 없습니다.
다만, ‘지금 이 코드에서 우리가 겪는 가장 큰 불편함이 무엇인가’ 에 집중하다 보면 다음 단계가 보인다는 것을 이번 경험을 통해 배웠습니다.
“요즘 AI가 다 짜주는데, 이런 고민이 필요한가요?”
글을 마무리하면서 이 질문을 꺼내지 않을 수 없습니다.
Cursor나 Claude로 코드를 뚝딱 만들어내는 시대에, 레이어 간 데이터 전달 방식 같은 걸 왜 이렇게 깊이 고민해야 하냐고요.
저는 오히려 반대라고 생각합니다. AI가 코드를 잘 짜줄수록, 구조가 더 중요해집니다.
AI는 지금 이 함수에 어떤 데이터가 들어오는지 모릅니다. 컨텍스트를 명시적으로 넘겨주지 않으면 AI도 호출 스택을 추론하다가 엉뚱한 코드를 만들어냅니다. 실제로 data: dict로 선언된 함수를 AI에게 수정해달라고 하면, data 안에 뭐가 있는지 모르니 그럴듯하지만 잘못된 키를 참조하는 코드를 자신 있게 내놓는 경우가 종종 있습니다.
반면 TypedDict로 명시된 구조는 AI에게도 명확한 신호가 됩니다.
UserProfileUpdateDto를 보여주면 AI는 이 함수가 무엇을 기대하는지 즉시 파악하고, 훨씬 정확한 코드를 생성합니다.
명시적인 구조는 사람만을 위한 것이 아닙니다. AI와 함께 일하는 방식이 일상이 된 지금, 코드의 가시성은 AI를 얼마나 잘 활용할 수 있는가, 그리고 얼마나 효율적으로 활용할 수 있는가와도 직결됩니다. 잘 정의된 구조는 사람이 읽기 좋고, AI가 이해하기 좋고, 결과적으로 팀 전체가 더 빠르게, 더 저렴하게 움직일 수 있게 해줍니다.
여러분의 코드에도 ‘이 파라미터에 뭐가 들어있는 거죠?’ 라는 블랙박스가 있지는 않은지, 한 번 찾아보시는 건 어떨까요?
이 글에서 소개한 패턴은 완성형이 아닙니다. 팀의 규모, 도메인의 복잡도, 기술 스택에 따라 적절한 방식은 달라집니다.
여러분의 상황에 맞게 취사선택해 적용해보시길 권합니다.