이 시리즈에서는 인증, 권한, 에러 처리, 데이터 접근, 인터페이스 설계까지 하나의 Next.js + TypeScript 프로젝트를 운영 관점에서 단계적으로 살펴봤습니다. 각 주제는 개별적으로도 중요하지만, 실무에서는 결국 하나의 아키텍처로 연결됩니다.
문제는 대부분 “중간에 흔들린다”는 데서 시작합니다.
- 처음에는 단순해서 빠르게 만들었는데, 나중에 구조가 버텨주지 않는다
- 그때그때 문제를 고치다 보니 기준이 사라진다
- 새로운 팀원이 들어오면 설명부터 어려워진다
이번 글은 새로운 기술을 소개하지 않습니다. 대신 지금까지 다룬 내용을 한 장의 기준표로 묶어, 프로젝트 초기에 무엇을 결정해야 흔들리지 않는지를 정리합니다.
개념/배경 설명: 아키텍처는 기술 목록이 아니다
아키텍처를 이야기하면 종종 이런 질문이 나옵니다.
- 이 스택이 최신인가요?
- 이 구조가 정답인가요?
하지만 실무에서 아키텍처의 역할은 다릅니다. 아키텍처는 “정답”이 아니라 결정을 반복하지 않게 만드는 기준에 가깝습니다.
그래서 좋은 아키텍처의 조건은 다음과 같습니다.
- 새 기능을 추가할 때 고민이 줄어든다
- 실수를 구조적으로 막아준다
- 운영 이슈가 생겼을 때 원인을 추적할 수 있다
핵심 설계 1: 프로젝트 초기에 반드시 고정해야 할 기준
아래 항목들은 “나중에 바꾸기 가장 비싼 결정”들입니다. 초기에 명확히 정해두는 것이 중요합니다.
- 폴더 구조의 최상위 경계(features / shared / server)
- 서버 코드와 클라이언트 코드의 물리적 분리 기준
- API 응답의 공통 구조(ok/data/error)
- 에러 처리 방식(Result vs throw)
- 권한 판단의 단일 기준(Policy 함수)
이 기준들이 흔들리면, 이후의 모든 선택이 즉흥적으로 변합니다.
실무 포인트 정리
- 초기 결정은 “가볍게”가 아니라 “단순하게” 한다
- 바꾸기 어려운 것부터 먼저 고정한다
핵심 설계 2: 인증·권한·에러·데이터 접근의 연결 관계
이 네 가지는 서로 독립적인 주제가 아닙니다. 실무에서는 항상 함께 움직입니다.
- 인증 결과 → 권한 판단의 입력
- 권한 실패 → 에러 타입과 코드로 표현
- 에러 결과 → 인터페이스 계약을 통해 프론트로 전달
- 모든 흐름 → 공통 데이터 접근 계층을 통해 실행
이 연결이 느슨해지면, 어느 한 곳의 변경이 다른 영역을 예측 없이 깨뜨립니다.
핵심 설계 3: Server Action, API Route, Service 계층의 역할 분리
Next.js에서는 서버 로직을 작성할 수 있는 방법이 여러 가지입니다. 중요한 것은 “어디에 무엇을 두느냐”입니다.
- Server Action: UI 흐름에 밀접한 요청
- API Route: 재사용 가능하고 정책이 중요한 요청
- Service/Policy: 비즈니스 규칙과 권한 판단
이 구분이 명확하면, 기능이 늘어나도 코드의 위치가 자연스럽게 결정됩니다.
핵심 설계 4: 테스트는 “보호해야 할 기준”만 잡는다
모든 코드를 테스트하려고 하면, 테스트는 곧 유지보수 부담이 됩니다.
이 시리즈에서 강조한 테스트 대상은 명확합니다.
- 권한 Policy 함수
- API/Server Action의 권한 연결 여부
- 에러 타입 분기 로직
이 부분만 테스트로 고정해도, 운영에서 발생하는 치명적인 사고의 상당 부분을 막을 수 있습니다.
운영/실무에서 자주 겪는 실패 패턴
- 초기 구조 없이 기능부터 쌓아 올린 경우
- 권한·에러·인터페이스 기준이 사람마다 다른 경우
- 문서만 있고 코드로 강제되지 않는 규칙
- 문제가 생길 때마다 땜질로 고친 아키텍처
이 실패들은 기술 부족보다 “기준 부재”에서 비롯되는 경우가 많습니다.
실무 권장 전체 체크리스트
- 프로젝트 최상위 경계가 명확한가
- 서버/클라이언트 코드가 구조적으로 분리되어 있는가
- 인증과 권한 판단 기준이 단일화되어 있는가
- 에러가 제어 흐름으로 관리되고 있는가
- 백엔드 인터페이스가 타입 계약으로 고정되어 있는가
- 핵심 규칙이 테스트로 보호되고 있는가
좋은 아키텍처는 복잡한 그림이 아닙니다. 팀이 같은 결정을 반복하지 않게 해주는 기준입니다.
Next.js와 TypeScript는 강력한 도구이지만, 기준 없이 사용하면 오히려 혼란을 키웁니다. 초기에 핵심 경계와 규칙을 정리해두면, 프로젝트는 성장해도 구조는 흔들리지 않을것입니다.