초짜 파이썬 개발자의 FastAPI 백엔드 개발, 인프라 관점으로 뜯어보니

FastAPI와 파이썬 백엔드 개발은 최근 IT 업계에서 뜨거운 감자입니다. 특히 마이크로서비스 아키텍처와 경량화된 API 서버 구축에 최적화된 선택지로 많은 개발자의 관심을 받고 있죠. 그러나 아무리 좋은 기술 스택이라도 실제 프로젝트에 적용하는 과정은 결코 쉽지 않습니다. PyCon Korea 2025에서 김대현 개발자님의 발표는 이처럼 FastAPI를 처음 다루면서 겪을 수 있는 현실적인 시행착오와 그 속에서 얻은 값진 깨달음을 솔직하게 공유했습니다. 저 역시 지난 10년간 다양한 IT 인프라 프로젝트를 수행하며 수많은 ‘삽질’을 목격하고 경험했습니다. 오늘은 김대현 개발자님의 좌충우돌 경험담을 IT 인프라 전문가의 시각으로 재해석하고, 우리가 놓치기 쉬운 핵심 포인트를 함께 짚어보겠습니다. 단순히 코딩 스킬을 넘어, 안정적이고 확장 가능한 인프라를 구축하기 위한 통찰력을 얻는 시간이 될 것입니다.

FastAPI, 왜 매력적일까? 그리고 그 너머의 인프라적 관점

김대현 개발자님이 공장 자동화 시스템의 백엔드 서비스로 FastAPI를 선택한 이유는 명확했습니다. Django 대비 낮은 학습 곡선과 REST API 제공이라는 프로젝트의 특성이 주효했죠. 특히 NodeJS의 Express와 유사한 코드 구조는 익숙함과 함께 빠른 개발 속도를 가능하게 했을 겁니다. 여기서 중요한 점은 기술 선택의 배경입니다. 최신 기술이라고 무조건 도입하기보다는, 프로젝트의 요구사항과 팀의 숙련도를 고려한 현실적인 판단이 실무에서는 훨씬 중요합니다.

저는 개인적으로 FastAPI가 갖는 경량성과 비동기 처리 능력에 주목하고 싶습니다. 이는 현대 클라우드 인프라 환경에서 매우 큰 이점입니다. 예를 들어, 서버리스(Serverless) 환경이나 컨테이너 기반의 마이크로서비스 아키텍처에 FastAPI는 탁월한 선택이 될 수 있습니다. 적은 리소스로 높은 처리량을 제공하여 인프라 비용을 절감하고, 빠른 응답 속도를 보장하기 때문이죠. 또한, 김대현 개발자님이 API 엔드포인트 패키지에 “router” 대신 “controller”라는 단어를 사용한 것도 흥미로운 부분입니다. 네트워크 용어인 “router” 대신 비즈니스 로직의 제어 흐름을 나타내는 “controller”를 선택한 것은, 결국 개발자가 아키텍처의 목적성과 역할을 명확히 이해하고 설계에 반영하려는 노력이었다고 해석할 수 있습니다. 단순한 명칭 선택을 넘어, 시스템의 확장성과 유지보수성에 영향을 미치는 중요한 고민이었다고 봅니다.

데이터베이스 연결, 놓치기 쉬운 기본기

“This session is provisioning a new connection; concurrent operations are not permitted”라는 SQLAlchemy 예외는 개발자들이 예상치 못한 순간에 마주하는 당혹스러운 상황 중 하나입니다. 김대현 개발자님은 HTTP 요청마다 새로운 데이터베이스 연결을 생성한다고 생각했지만, 실제로는 파이썬의 클래스 변수와 인스턴스 변수에 대한 이해 부족으로 발생한 문제였습니다. 이게 왜 중요할까요? 이 문제는 단순히 코딩 실수의 차원을 넘어, DB Connection Pooling, 세션 관리 등 IT 인프라의 핵심적인 요소와 직결됩니다.

실무에서는 데이터베이스 연결 자원이 부족하거나 비효율적으로 관리될 때, 서비스 전체의 성능 저하나 장애로 이어지는 경우가 허다합니다. 특히 트래픽이 급증하는 상황에서는 이 문제가 더욱 심각해질 수 있습니다. 커넥션 누수로 인해 DB 서버에 부하가 걸리거나, 애플리케이션 서버의 메모리 사용량이 치솟아 서비스가 중단되는 상황도 발생합니다. 따라서 파이썬의 객체 라이프사이클을 정확히 이해하고, SQLAlchemy와 같은 ORM에서 제공하는 세션 관리 기능을 올바르게 활용하는 것이 매우 중요합니다. 이는 개발자가 인프라 자원을 효율적으로 사용하고, 잠재적인 서비스 장애 요인을 사전에 제거하는 데 필수적인 역량입니다.

ORM과 패키지 구조, 최적의 효율을 찾아서

ORM은 분명 개발 생산성을 높이는 강력한 도구입니다. 간단한 CRUD 작업에 용이하고, 테이블 구조를 코드 내에서 파악하기 쉽게 만들어주죠. 그러나 쿼리가 복잡해지면 ORM은 N+1 쿼리 문제, 불필요한 조인 코드, 그리고 김대현 개발자님의 사례처럼 상호 참조 문제와 같은 예상치 못한 난관을 초래합니다. 이러한 문제는 단순히 개발 편의성을 저해하는 것을 넘어, 데이터베이스 서버에 과도한 부하를 주어 인프라 성능에 악영향을 미칠 수 있습니다. N+1 쿼리는 네트워크 I/O를 증가시키고, DB 리소스 소모를 가속화하며, 결국 사용자 응답 속도를 현저히 떨어뜨립니다.

초기에 ORM 클래스 안에 조회 코드를 넣었다가 상호 참조 문제로 인해 모든 쿼리 코드를 분리하는 과정은 많은 개발자가 겪는 공통적인 고민입니다. 코드를 분리했을 때 초기에는 깔끔해 보이지만, 불필요한 데이터 조회, 함수 수정 시 오류 발생, 코드 중복 등의 문제가 발생하며 오히려 설계상의 트레이드오프가 심화될 수 있습니다. 여기서 핵심은 ‘필요를 가지고 있는 Service에 집중시키자’는 결론입니다. 이는 비즈니스 로직과 데이터 접근 로직의 응집도를 높여 전체 시스템의 유지보수성과 가독성을 향상시키는 중요한 원칙입니다. 실제 대규모 시스템에서는 DTO(Data Transfer Object)와 DAO(Data Access Object) 패턴을 통해 각 레이어의 역할과 책임을 명확히 분리하여 이런 문제를 해결하기도 합니다. 김대현 개발자님이 DB 쿼리 코드를 SqlAlchemy 쿼리 빌더 형태로 변환해 주는 라이브러리를 직접 만들었다는 것은, 이런 구조적 한계를 극복하려는 적극적인 노력의 결과물이며, 다른 개발자들에게도 큰 영감을 줄 만한 실질적인 성과라고 생각합니다.

함수 vs 클래스: 파이썬 아키텍처 설계의 딜레마

파이썬에서는 “Everything in python is an object”라는 말이 있을 정도로 객체 지향의 특성이 강하지만, 의외로 많은 예제 코드들이 함수 형태로 되어 있습니다. FastAPI 예제 역시 데이터 객체를 제외하고는 대부분 함수로 구성되는 경향이 있습니다. 이는 파이썬의 유연성과 함수형 프로그래밍 스타일을 반영하는 것이기도 하지만, 대규모 프로젝트에서는 클래스를 활용한 구조화가 더 큰 이점을 제공할 수 있습니다.

김대현 개발자님이 클래스로 코드를 묶은 것은 비즈니스 로직의 성격에 따라 응집도를 높이고, DB 세션이나 사용자 인증 상태와 같은 ‘State’를 효과적으로 관리하기 위함이었습니다. 실무에서는 이러한 클래스 기반의 구조가 의존성 주입(Dependency Injection)과 테스트 용이성을 확보하는 데 매우 유리합니다. Controller는 REST API 처리, Service는 비즈니스 로직에 집중하게 함으로써 각 컴포넌트의 역할이 명확해지고, 이는 향후 시스템의 확장 및 유지보수를 용이하게 만듭니다. 인프라 관점에서 볼 때, 모듈화되고 역할이 명확히 분리된 코드는 트러블슈팅을 단순화하고, 특정 기능의 변경이 전체 시스템에 미치는 영향을 최소화하는 데 기여합니다.

개발 고통의 수레바퀴를 끊는 테스트 자동화

TDD(Test Driven Development)는 모든 개발자가 지향하지만, 현실의 압박 속에서 쉽게 뒷전으로 밀리는 주제입니다. 김대현 개발자님 역시 초기 학습 단계에서 TDD를 제대로 적용하지 못하고 “고통의 수레바퀴”를 겪어야 했습니다. ‘뭔가 만들고 -> 배우고 -> 고치고 -> 디버그하고’의 무한 반복은 개발자라면 누구나 공감할 만한 경험입니다. 특히 새로운 언어와 프레임워크를 동시에 다룰 때는 더욱 그렇죠. 그러나 테스트 코드의 부재는 수동 테스트에 기하급수적인 시간을 소모하게 만들고, 코드 변경에 대한 두려움을 키워 궁극적으로 개발 속도를 저하시킵니다.

늦게라도 Pytest와 Tox를 도입하여 테스트 커버리지를 86%까지 끌어올린 것은 정말 탁월한 선택이었습니다. 테스트 코드는 단순히 버그를 찾는 도구를 넘어, 코드 구조를 개선하고 리팩토링할 수 있는 가장 강력한 안전장치입니다. 저는 인프라를 운영하면서 테스트 코드가 곧 배포의 안정성으로 이어진다는 것을 여러 번 경험했습니다. CI/CD 파이프라인에 자동화된 테스트가 포함되면, 새로운 기능 배포 시 발생할 수 있는 잠재적 위험을 크게 줄여 서비스 다운타임을 최소화할 수 있습니다. 예를 들어, 파이썬 3.9에서 3.11로 버전업하는 과정에서 Tox가 문제를 미리 감지했다는 사례는, 다양한 환경에서의 호환성 테스트가 얼마나 중요한지 여실히 보여줍니다.

REST API와 HTTP 상태 코드: 인프라의 표준을 지키는 힘

PHP와 CodeIgniter로 개발할 때 겪었던 HTTP 상태 코드에 대한 오해는 REST API 설계의 중요성을 다시 한번 상기시킵니다. “서버는 어떤 상황에서도 정상적으로 작동한다고 가정하고, 클라이언트에서 응답의 body를 기준으로 판단하는 게 더 이상적입니다”라는 오해는 실제로는 심각한 문제를 야기할 수 있습니다. REST API의 핵심 원칙 중 하나는 리소스 기반의 통신과 함께 HTTP 상태 코드를 통해 작업의 성공 여부나 오류 유형을 명확하게 전달하는 것입니다.

인프라 관점에서 볼 때, HTTP 상태 코드는 API 게이트웨이, 로드밸런서, 방화벽, 모니터링 시스템 등 다양한 인프라 컴포넌트들이 시스템의 상태를 판단하고 적절한 조치를 취하는 기준이 됩니다. 예를 들어, 5xx 에러는 서버 문제로 인식되어 알림을 발생시키고, 4xx 에러는 클라이언트의 잘못된 요청으로 처리되어 접근을 차단하는 등의 정책을 적용할 수 있습니다. 만약 모든 응답이 200 OK로 돌아온다면, 인프라 팀은 실제 서비스 문제가 발생했을 때도 이를 인지하기 어렵고, 문제 해결에 더 많은 시간과 자원을 소모하게 됩니다. 좋은 동료의 피드백 덕분에 이러한 실수를 피할 수 있었다는 점은, 개발 과정에서 동료 간의 소통과 코드 리뷰가 얼마나 중요한지 보여주는 사례입니다.

숨겨진 보석, Pydantic과 문제 해결의 본질

Controller와 Service에 각각 DTO를 두는 구조는 흔히 볼 수 있는 패턴이지만, 이를 직접 구현하다 보면 데이터 유효성 검사 및 변환 코드가 통제 불능으로 늘어나기 쉽습니다. 여기서 Pydantic의 진가가 발휘됩니다. `model_validator`, `@field_validator`, `@computed_field`와 같은 Pydantic의 강력한 기능을 활용하면, 반복적이고 복잡한 데이터 처리 로직을 깔끔하게 자동화할 수 있습니다. 이는 단순히 코딩을 편리하게 만드는 것을 넘어, 데이터 무결성을 확보하고 시스템의 신뢰도를 높이는 데 결정적인 역할을 합니다.

궁극적으로 김대현 개발자님의 경험담은 “문제 해결의 본질을 잊지 말자”는 메시지로 귀결됩니다. “코딩은 문제 해결 도구”라는 명제를 잊고 코딩 자체에 매몰될 때, 우리는 비효율적인 “코딩 차력쇼”를 반복하게 됩니다. S3 파일명 문제처럼 단순한 아이디어가 해결책이 될 수 있음에도 불구하고, 복잡한 기술적 접근만 고집하는 경우가 많습니다. 저는 여기서 IT 인프라 엔지니어에게도 요구되는 본질적인 자세를 봅니다. 아무리 최첨단 기술을 사용하더라도, 기본적인 시스템 설계 원칙과 문제 해결 능력이 없다면 견고한 인프라를 구축할 수 없습니다.

지금 와서 뒤돌아보니, 성장을 위한 길

김대현 개발자님의 좌충우돌 삽질기는 비단 초짜 개발자뿐만 아니라, 모든 IT 전문가에게 중요한 교훈을 줍니다. 수많은 시행착오와 “고통의 수레바퀴”를 겪으면서 우리는 성장합니다. 여기서 제가 강조하고 싶은 것은 “새로운 것을 배우려면 우리는 과거의 경험과 선입견을 한켠으로 밀어 둘 수 있어야 한다”는 <프로그래머의 길, 멘토에게 묻다>의 구절입니다. 익숙한 PHP와 CodeIgniter의 습관이 FastAPI 프로젝트에 영향을 미쳤듯, 기존의 경험이 새로운 기술을 배우는 데 장애물이 될 수도 있습니다.

우리가 코드를 작성하고 인프라를 설계하는 목적은 결국 “문제 해결”입니다. 이 본질을 잊지 않고 늘 “흰 띠를 매는 자세”로 초심을 유지한다면, 아무리 엉망진창인 코드라도 “유려하고 깔끔함”으로 만들어낼 수 있는 역량이 길러질 것입니다. IT 인프라 환경은 끊임없이 변화하고 복잡해지지만, 본질적인 문제 해결 능력과 끊임없는 학습만이 우리를 진정한 전문가로 만들어 줄 것입니다.

참고: 초짜 파이썬 개발자가 FASTAPI로 서비스 만들면서 겪은 좌충우돌 삽질기 – 요즘IT, 2025