콘텐츠로 이동

Infrastructure – 기술적 외부 세계

Infrastructure는 평판이 좋지 않습니다.

이 단어를 듣자마자 포트, 어댑터, 리포지토리 인터페이스, 팩터리, 여러 계층을 거치는 통합 아키텍처를 떠올리는 사람이 많습니다. 화살표는 많고 사각형은 더 많은 다이어그램도 빠지지 않습니다.

이 시리즈의 도입 글에서는 기술적 외부 세계에서 사용자에게 이르는 경로의 첫 단계로 Infrastructure를 소개합니다. 이 단계에서 실제로 하는 일은 이름에서 짐작하는 것보다 훨씬 소박합니다.

이 글에서는 우선 이렇게 보면 충분합니다.

Infrastructure는 우리 애플리케이션이 완전히 통제할 수 없는 대상을 만나는 지점입니다.

백엔드, REST 또는 GraphQL API, WebSocket이나 SSE, Local Storage, IndexedDB, 브라우저 API, 인증 제공자, 외부 SDK, 다른 바운디드 컨텍스트가 그 예입니다.

같은 회사 안에도 완전히 통제할 수 없는 대상은 있습니다. 사내 백엔드 팀도 프론트엔드가 막을 수 없는 계약(Contract) 변경을 할 수 있습니다. 조직의 경계보다 중요한 것은 그 구조를 누가 소유하고 앞으로 어떻게 바꿀지 누가 결정하느냐입니다.

어떤 기술을 쓰는지는 부차적인 문제입니다. Angular의 HttpClient, fetch, Axios, 그 밖의 어떤 클라이언트를 써도 아키텍처상의 책임은 같습니다.

외부 세계
↓
Infrastructure
↓
애플리케이션의 도메인

Infrastructure는 외부의 기술적 구조를 받아 정해진 방식으로 우리 애플리케이션에 맞게 변환합니다.

우선은 이 정도면 충분합니다.

인프라 계층이 백엔드 API, 브라우저 API, 저장소, 외부 SDK에서 들어오는 데이터를 검증하고 정규화한 뒤 애플리케이션의 도메인에 맞게 변환하는 구조

인프라 경계 그림 원본 크기로 열기

바로 그게 핵심입니다. Infrastructure는 지루해도 됩니다.

외부 세계는 우리 소유가 아닙니다

섹션 제목: “외부 세계는 우리 소유가 아닙니다”

백엔드의 계약은 기본적으로 백엔드 소유입니다. 외부 SDK는 그 SDK를 만든 업체의 것이고, 브라우저 API 계약은 브라우저의 것입니다.

그 모델이 우리 쪽에 먼저 도착했다는 이유만으로 애플리케이션의 도메인 모델로 삼을 필요는 없습니다.

간단한 예를 들어 보겠습니다. 백엔드는 고객 데이터를 이렇게 보냅니다.

type CustomerDto = {
id: string;
first_name: string;
last_name: string;
};

애플리케이션 내부에서는 이렇게 다룹니다.

type Customer = {
id: string;
firstName: string;
lastName: string;
};

까다로운 변환은 아닙니다. 예가 단순하다는 점이 중요합니다. 실무에서 마주치는 경계도 이처럼 소박한 경우가 많기 때문입니다.

CustomerDto는 백엔드가 고객 데이터를 어떤 형태로 보내는지 나타냅니다. Customer는 우리 애플리케이션이 고객을 어떻게 표현하는지 나타냅니다. 둘 사이의 변환이 명시되어 있으면 두 모델은 서로 독립적으로 발전할 수 있습니다.

이쯤에서 이런 반론이 나올 수 있습니다.

function toCustomer(dto: CustomerDto): Customer {
return {
id: dto.id,
firstName: dto.first_name,
lastName: dto.last_name,
};
}

두 구조가 거의 같은데 굳이 코드를 더 작성해야 할까요?

오늘만 보면 Mapper가 거의 필요 없어 보입니다. 내일은 백엔드가 필드 이름을 바꿀 수도 있습니다.

first_name → givenName
last_name → familyName

그때 바뀌는 것은 바로 이 변환입니다. 이상적으로는 Store, 비즈니스 규칙, Facade, 컴포넌트에까지 그 변경이 전해지지 않습니다.

백엔드 계약이 바뀌면 Mapper에서 변경을 흡수하며 내부 Customer 모델은 그대로 유지되는 구조

Mapper가 변경을 흡수하는 그림 원본 크기로 열기

외부 계약이 파일 50곳에서 알게 모르게 도메인 모델로 쓰이는 일을 막을 수 있다면, 다섯 줄짜리 Mapper는 과잉 설계가 아닙니다.

DTO가 이 경계를 그대로 넘어 State, Application, 컴포넌트, 템플릿까지 퍼지면 어떤 일이 생기는지는 DTO 누출을 다룬 글(독일어)에서 더 자세히 살펴봅니다.

여기서는 작은 변환 경계 하나로 외부 시스템의 구조가 서서히 우리 애플리케이션의 구조로 굳어지는 일을 막을 수 있다는 점만 기억하면 됩니다.

TypeScript만으로는 경계를 지킬 수 없습니다

섹션 제목: “TypeScript만으로는 경계를 지킬 수 없습니다”

프론트엔드에서 놓치기 쉬운 점이 하나 더 있습니다.

HTTP 응답은 외부에서 옵니다. JSON을 파싱하고 나면 문자열, 숫자, 객체, 배열, null 같은 JavaScript 값이 남습니다.

다음과 같은 타입 단언이나

const customer = response as CustomerDto;

타입을 지정한 HTTP 호출은

http.get<CustomerDto>('/api/customers/42');

프론트엔드가 어떤 구조를 기대하는지 표현합니다. 백엔드가 실제로 그 구조를 보냈는지는 이 코드만으로 알 수 없습니다.

TypeScript의 타입은 외부 데이터를 검증하지 않습니다. 타입은 어떤 구조로 작업할지를 컴파일 시점에 표현합니다. 실제 데이터가 그 구조를 따르는지는 필요에 따라 시스템 경계에서 런타임에 별도로 확인해야 합니다.

이 검증은 Infrastructure의 책임입니다.

이 경계에서 하는 일은 몇 가지로 정리할 수 있습니다.

unknown / 외부 데이터
↓
Infrastructure
│
├── 검증
├── 정규화
└── 변환
↓
애플리케이션의 모델

대표적인 작업은 다음과 같습니다.

  • 런타임에 데이터를 검증합니다.
  • 필수 필드가 있는지 확인합니다.
  • 외부 형식을 정규화합니다.
  • 날짜 값을 변환합니다.
  • null과 undefined를 정해진 방식으로 처리합니다.
  • 기술적 상태 코드를 변환합니다.
  • DTO를 애플리케이션의 모델로 변환합니다.
  • 외부 시스템의 오류를 애플리케이션이 정의한 기술적 오류로 변환합니다.

런타임 검증에는 Zod 같은 라이브러리를 사용할 수 있습니다. 어느 라이브러리가 그 일을 맡을지는 아키텍처를 결정할 때 부차적인 문제입니다. 중요한 것은 어디에서 검증하느냐입니다.

정규화도 단순하고 명확해야 합니다.

알려진 날짜 형식은 Date로 변환할 수 있습니다. 선택 필드는 미리 정한 기술적 규칙에 따라 정규화할 수 있습니다. 외부 상태 코드는 애플리케이션이 정의한 기술적 표현이나 도메인 표현에 대응시킬 수 있습니다.

예상과 다른 값이 들어왔을 때 기술적으로 명확히 해석할 수 없다면, Infrastructure가 임의로 도메인 의미를 부여해서는 안 됩니다.

해석할 수 없는 데이터는 우선 기술적 오류로 다룹니다.

그 오류를 사용자에게 어떻게 보여 줄지는 별도의 책임입니다.

DTO에만 해당하는 이야기는 아닙니다

섹션 제목: “DTO에만 해당하는 이야기는 아닙니다”

Customer 예에서 HTTP를 사용한 것은 이 원리를 보여 주기 쉽기 때문입니다. 데이터가 외부에서 들어오는 곳이라면 어디에나 같은 경계가 있습니다.

localStorage에서 읽은 값은 우선 문자열이나 null입니다. 어제 저장한 객체가 자동으로 복원되지는 않습니다.

결제 서비스 제공자의 SDK는 고유한 오류 클래스와 오류 코드를 사용합니다.

WebSocket으로 받는 메시지의 구조는 서버 버전이 바뀌면서 달라질 수 있습니다.

어느 경우든 질문은 같습니다. 원래 값을 애플리케이션으로 그대로 들여올까요? 아니면 먼저 해당 기능이 이해할 수 있는 형태로 변환할까요?

오류도 이 경계에서 변환할 수 있습니다.

try {
await paymentSdk.charge(order);
} catch (error) {
throw toPaymentInfrastructureError(error);
}

toPaymentInfrastructureError는 SDK의 오류 코드와 기술적 특성을 알아도 됩니다. 애플리케이션의 다른 부분은 내부에서 정의하고 관리하는 기술적 오류 유형만 다룹니다.

결제 서비스 제공자가 바뀌어도 외부 시스템 고유의 용어와 표현은 인프라 경계 안에 머뭅니다.

기술적 불확실성을 처리하는 일과 도메인 판단의 경계

섹션 제목: “기술적 불확실성을 처리하는 일과 도메인 판단의 경계”

이 글에서 가장 중요한 경계입니다.

Infrastructure는 외부에서 들어오는 불확실성을 걷어낼 수 있습니다. 그 과정에서 비즈니스 규칙까지 도출해서는 안 됩니다.

예를 들어 외부 계약의 값을 다음과 같이 변환할 수 있습니다.

"ACTIVE"
↓
CustomerStatus.Active

이 변환은 Infrastructure가 맡을 수 있습니다.

이 상태에 있는 고객이 주문해도 되는지는 별개의 질문입니다.

CustomerStatus.Active
↓
이 고객은 주문할 수 있나요?

여기서부터 도메인 로직이 시작됩니다.

코드만 보면 두 연산의 모습은 매우 비슷할 수 있습니다. 둘 다 switch나 if, 또는 대입문 한 줄로 표현할 수 있습니다. 그래도 각각 맡은 책임은 전혀 다릅니다.

예를 들어 Infrastructure는 다음과 같이 변환할 수 있습니다.

"2026-08-10T10:15:00Z" → Date
null → undefined
"C" → CreditHold
first_name → firstName

+State가 답하는 질문은 다음과 같습니다.

이 주문을 취소해도 되나요?
이 고객은 주문할 수 있나요?
이 상태 전이는 허용되나요?
도메인 규칙상 어떤 동작을 할 수 있나요?

Infrastructure는 기술적·구조적 불확실성을 없앱니다. 도메인 판단은 그다음에 시작됩니다.

Infrastructure가 맡을 일과 맡지 않을 일

섹션 제목: “Infrastructure가 맡을 일과 맡지 않을 일”

Infrastructure가 맡아야 할 일은 다음과 같습니다.

  • 외부 계약을 캡슐화합니다.
  • DTO를 애플리케이션의 모델로 변환합니다.
  • 기술적 형식을 정규화합니다.
  • 외부 입력을 검증합니다.
  • 기술적 API를 캡슐화합니다.
  • 외부 오류를 애플리케이션이 정의한 기술적 오류로 변환합니다.
  • 외부 모델이 통제 없이 애플리케이션 내부로 스며드는 일을 막습니다.

다음과 같은 일은 Infrastructure의 책임에서 벗어납니다.

  • 비즈니스 규칙 구현
  • 도메인 판단
  • 도메인 값의 파생
  • 특정 뷰에 맞춘 ViewModel 구성
  • UI 상태 관리
  • 내비게이션 제어
  • 대화상자 열기
  • Presentation의 책임 떠맡기
  • 마침 기술 서비스 코드를 수정 중이라는 이유만으로 그곳에 로직 추가하기

인프라 계층의 비즈니스 로직이 복잡해질수록 그 로직이 정말 그 자리에 있어야 하는지 더 자세히 살펴볼 필요가 있습니다.

더 본격적인 변환이 필요한 경우

섹션 제목: “더 본격적인 변환이 필요한 경우”

Customer 예제의 단순한 Mapper는 Eric Evans가 Domain-Driven Design에서 설명하는 엄밀한 의미의 Anti-Corruption Layer에는 아직 이르지 않습니다.

두 방식에는 외부 모델이 별다른 통제 없이 우리 모델이 되는 일을 막는다는 공통점이 있습니다.

first_name을 firstName으로 바꾸는 정도라면 경계에서 하는 일은 여전히 단순합니다.

서로 다른 용어, 상태 모델, 도메인 의미가 만날 때 이 경계가 더 흥미로워집니다. 외부 시스템의 "ACTIVE"가 우리 기능의 Active와 다른 뜻일 수도 있습니다. 레거시 시스템이 그 안에서만 통하는 의미를 오류 코드에 담아 보낼 수도 있습니다. 두 시스템이 같은 고객을 모델링하면서도 각 도메인에서 고객을 다르게 정의할 수도 있습니다.

이런 경우에는 어느 순간 필드를 기계적으로 대응시키는 것만으로는 부족해집니다.

외부 모델과 내부 모델 사이에서 이처럼 더 깊이 있는 변환이 필요한 경우는 Anti-Corruption Layer 글(독일어)에서 다룹니다.

인프라 계층에서 우선 기억할 점은 더 간단합니다. 작더라도 경계를 명시해 두면 외부 모델이 눈에 띄지 않게 애플리케이션 전체로 퍼지는 일을 막을 수 있습니다.

경계는 필요한 만큼, Infrastructure는 가능한 한 작게

섹션 제목: “경계는 필요한 만큼, Infrastructure는 가능한 한 작게”

원시 타입 필드마다 별도의 Value Object를 만들 필요는 없습니다. API 객체마다 인터페이스, 리포지토리, 포트, 어댑터, 팩터리, 여러 단계의 추상화를 모두 도입할 이유도 없습니다.

계층화는 파일 수를 늘리는 경쟁이 아닙니다.

단순한 계약을 반드시 여러 모델로 나눠 표현할 필요는 없습니다. 판단 기준은 그 계약을 그대로 쓸 때 생기는 위험입니다.

다음 질문이 판단에 도움이 됩니다.

  • 계약의 소유자는 누구인가요?
  • 우리와 별개로 계약이 바뀔 수 있나요?
  • 그 계약은 애플리케이션 내부 어디까지 퍼질 수 있나요?
  • 경계 바깥과 안에서 같은 값이 서로 다른 의미를 갖나요?
  • 데이터를 정규화하거나 검증해야 하나요?
  • 나중에 결합을 끊으려면 비용이 얼마나 들까요?

한곳에서만 쓰는 작은 기술적 조회 구조라면 추가 추상화가 필요 없을 수 있습니다.

이후의 도메인 판단에 영향을 주는 결제 상태라면 처음에는 변환 코드가 몇 줄뿐이어도 경계를 의식적으로 두는 편이 좋습니다.

판단 기준은 코드 줄 수가 아닙니다.

경계를 두지 않았을 때 결합도가 얼마나 높아지는지가 중요합니다.

경계는 필요한 만큼, Infrastructure는 가능한 한 작게 유지합니다.

Infrastructure는 계속 지루해도 됩니다.

인프라 계층의 끝에 이르면, 외부에서 받은 데이터는 검증과 정규화를 거쳐 우리 기능이 신뢰할 수 있는 형태로 바뀌어 있습니다.

이 과정에서 도메인 판단은 아직 이뤄지지 않았습니다.

"ACTIVE"는 CustomerStatus.Active로 바뀌었습니다. 이 고객이 주문해도 되는지, 주문을 취소할 수 있는지, 지금 어떤 상태 전이가 허용되는지는 아직 정해지지 않았습니다.

데이터가 기술적 경계를 넘은 뒤 어떤 일이 일어나는지는 +State 글에서 살펴봅니다.

거기서부터 도메인 로직이 시작됩니다.