FastAPI에서 다형성 요청 처리하기

0. 개요

FastAPI로 서버를 개발하다 보면 다양한 형태의 요청 데이터를 받게 된다.

특히 하나의 엔드포인트에서 여러 타입의 요청을 처리하는 상황에서는 어떻게 구조를 잡을지 고민이 많아진다.

 

이번 포스팅에서는 Pydantic을 활용하여 하나의 엔드포인트에서 다형성 요청을 처리하는 방법을 설명한다.

---

1. 시나리오

서비스에 사용자가 결제 수단을 등록할 수 있는 API가 있다고 가정해 보자.

사용자는 원하는 결제 수단을 선택하여 등록하게 된다.

다양한 형태의 결제 수단

결제 수단은 신용카드, 계좌이체, 간편 결제 총 3가지이고, 각 결제 수단이 필요로 하는 정보는 모두 다르다.

 

결제 수단 별 요청 형태는 다음처럼 작성할 수 있다.

결제 수단 별 요청 형태 예시

이처럼 하나의 API에서 다형적인 요청을 처리하려면 FastAPI에서는 어떻게 구현해야 할까?

---

2. Pydantic 스키마 정의

FastAPI에서 요청을 받기 위해서는 Pydantic 객체를 정의해야 한다.

하나의 API에서 세 가지 형태의 요청을 받기 위해서는 아래 형태의 스키마가 나오게 된다.

세 요청의 공통된 부분인 method 필드를 제외하곤 어떤 필드가 들어올지 알 수 없으므로 나머지 필드의 타입을 Optional로 설정한다.

이 구현 방식은 어떤 단점이 있을까?

 

FastAPI에서 Pydantic을 사용하는 이유가 데이터 타입 검증을 위함인데, 이러한 형태의 스키마는 그 의미를 잃어버린다.

이런 잘못된 형태의 요청도 검증에서 통과된다.

 

FastAPI에서 해주는 API 자동 문서화에서도 모든 필드가 보이게 되어 의사소통에 혼란을 가져온다.

의미를 알기 어려운 API 문서

---

3. Discriminated Union으로 타입 구분하기

명시적으로 각 결제 수단의 요청 형태를 정하기 위해, 먼저 각 결제 수단의 스키마를 Pydantic 객체로 정의한다.

Pydantic 객체로 정의한 결제 수단 스키마

요청이 들어왔을 때 3개의 스키마 중 자동으로 타입이 결정되어야 한다.

모든 요청에는 공통적으로 method 필드가 포함되어 있으므로 이 필드를 기준으로 타입을 판별할 수 있다.

 

Pydantic에서는 Discriminated Unions라는 기능으로 다형성 타입 판별을 지원한다.

Discriminated Unions 타입 선언

PaymentMethod 타입에 요청이 들어오면 discriminator로 설정한 method 필드를 기준으로 최종 스키마를 결정하게 된다.

 

Discriminated Unions를 사용하면 요청의 타입 유효성 검사를 제대로 할 수 있고, API 문서에 각 요청의 타입이 명시적으로 표시된다.

자동 생성된 API 문서에 타입이 명시된 모습

4. 정리

하나의 엔드포인트가 여러 타입의 요청을 받아야 하는 경우 Pydantic의 Discriminated Union을 활용하면 좋다.

타입 유효성 검사와 자동 API 문서화라는 FastAPI의 장점을 살릴 수 있게 된다.