handler / service / adapter boundary

라우트 파일은 얇게, 책임은 세 층으로 나눈다

API Route는 HTTP 경계만 담당하고, 업무 규칙과 외부 입출력은 별도 층으로 넘겨야 테스트와 교체가 쉬워진다.

Handler

app/api/users/route.ts

요청을 해석하고 method, auth, validation 결과를 HTTP 응답으로 묶는다.

methodsessionschema
넘기는 값검증된 DTO와 사용자 id

Service

createUserProfile(input)

비즈니스 규칙, 중복 확인, 상태 전이를 처리한다. HTTP 객체를 직접 알지 않는다.

rulepolicytx
돌려주는 값성공 데이터 또는 도메인 오류

Adapter

db.user / external API

DB, 파일, 외부 API 같은 교체 가능한 입출력을 담당한다.

databasestorageprovider
숨기는 것SQL, API key, provider field
섞이면 생기는 문제 올바른 위치 판정 기준
라우트 파일이 DB와 외부 API 세부사항으로 길어진다. Adapter 입출력 구현을 바꿔도 Handler가 거의 변하지 않는다.
HTTP 응답 코드가 업무 규칙 내부에 섞인다. Handler Service는 도메인 결과만 반환하고 HTTP로 번역하지 않는다.