FastAPI를 사용한 파이썬 웹 개발(CHAPTER 4)

FastAPI를 사용한 파이썬 웹 개발(CHAPTER 4)

 

CHAPTER 4 정리 – FastAPI와 Jinja 템플릿팅

CHAPTER 4에서는 템플릿팅(template rendering) 개념을 이해하고, FastAPI에서 Jinja 템플릿 엔진을 사용해 API 응답 데이터를 웹 페이지로 렌더링하는 방법을 학습한다.
템플릿팅이란 API가 전달한 데이터를 HTML과 결합해 사람이 볼 수 있는 화면으로 보여주는 과정이며, 이때 템플릿은 웹 애플리케이션에서 프런트엔드 컴포넌트처럼 동작한다.

 

4.1 Jinja

1. Jinja 템플릿 엔진

Jinja는 파이썬으로 작성된 템플릿 엔진으로, HTML 안에서 변수를 사용하고 조건문이나 반복문 같은 로직을 처리할 수 있도록 도와준다.
템플릿은 일종의 틀이며, 렌더링 시 실제 데이터가 변수 자리에 들어가 최종 HTML이 생성된다.

Jinja의 주요 문법은 다음과 같다.

• {{ }} : 변수 값 출력 (변수 블록)
• {% %} : if문, 반복문 등 흐름 제어
• {# #} : 주석 (화면에 표시되지 않음)

Jinja에서는 리스트, 딕셔너리, 모델 객체 등 문자열로 변환 가능한 모든 파이썬 객체를 템플릿 변수로 전달할 수 있다.

2. 필터(Filter)

필터는 Jinja에서 가장 중요한 기능 중 하나로, 템플릿 내에서 데이터를 가공할 수 있게 해준다.
파이썬의 문자열 처리나 변환 로직을 직접 사용할 수 없기 때문에, 이러한 작업은 필터를 통해 수행한다.

필터는 다음과 같이 파이프 기호(|) 사용해서 변수와 구분하며 괄호( {{}} )를 사용해 선택적 인수를 지정한다.

{{ variable |  filter_name(*args) }} -> 인수O

{[ variable |  filter_name }} -> 인수X

 

자주 사용되는 필터에는 다음과 같은 것들이 있다.

• default : 값이 없을 때 기본값 지정 - 기본 필터
• escape : HTML을 그대로 출력 - 이스케이프 필터
• int, float : 데이터 타입 변환 - 변환 필
• join : 리스트 요소 병합 - 병합 필터
• length : 객체의 길이 반환 - 길이 필터Jinja가 제공하는 전체 필터를 보고 싶다면 아래의 웹 페이지를 참고하세요!

https://jinja.palletsprojects.com/en/3.0.x/templates/#builtin-filters

3. 조건문과 반복문

Jinja에서는 {% if %}, {% else %}, {% endif %} 구문을 사용해 조건에 따라 다른 화면을 렌더링할 수 있다.
또한 {% for %} 문을 사용해 리스트 데이터를 반복 출력할 수 있으며, loop.index 같은 특수 변수를 통해 반복 인덱스도 사용할 수 있다.

 

if문: {% %} 제어 블록 내에서 사용할 수 있다.( ≒ 파이썬의 if문)

{% if todo | length < 5 %}
       할 일 목록에 할 일이 많지 않네요.
{% else %}
        바쁜 날을 보내고 있군요!
{% end if %}

 
반복문: Jinja에서는 변수를 사용해서 반복 처리를 할 수 있다. 다음과 같이 리스트,일반적인 함수를 사용해서 반복 처리를 할 수도 있다.

{% for todo in todos %}
       <b> {{ todo.item }} </b>
{% endfor %}

 

4. 매크로(Macro)

매크로는 HTML 코드를 반환하는 함수 형태의 템플릿 기능이다.
주로 반복해서 사용되는 HTML 코드를 하나의 매크로로 정의해 코드 중복을 줄이는 데 사용된다.
입력 폼 같은 반복 요소를 간단하게 재사용할 수 있다는 장점이 있다.

 

매크로: 하나의 함수로, HTML 문자열을 반환한다.
사용의 주요 목적: 하나의 함수를 사용해 반복적으로 작성하는 코드를 줄이는 것
ex) 입력(input) 매크로를 정의해서 HTML 폼에 반복적으로 정의하는 입력 태그를 줄일 수 있다.

{% macro input(name, value='', type='text', size=20 %}
    <div class="form">
        <input type="{{ type }}" name="{{ name }}"
        value="{{ value|escape }}" size="{{ size }}">
    </div>
{% endmacro %}

 
이 매크로를 호출해서 폼에 사용할 입력 요소를 간단하게 만들 수 있다.

{{ input('item') }}

 

5. 템플릿 상속 (Template Inheritance)

템플릿 상속은 Jinja의 가장 강력한 기능 중 하나로, 중복 코드를 제거(DRY 원칙) 하기 위해 사용된다.
기본이 되는 부모 템플릿을 만들고, 자식 템플릿이 이를 상속받아 필요한 블록만 구현한다.

이 장에서는 home.html을 부모 템플릿으로, todo.html을 자식 템플릿으로 구성해
공통 레이아웃은 유지하면서 내용만 변경하는 구조를 구현했다.

 

템플릿 상속(template inheritance)
: 기본 템플릿을 정의한 다음 이 템플릿을 자식 템플릿이 상속하거나 교체해서 사용할 수 있게 한다.
=Jinja의 가장 강력한 기능이다. 이 기능은 중복 배제(Don't Repeat Yourself(DRY) 원칙에 근거한 것이며 큰 규모의 웹 애플리케이션을 개발할 때 많은 도움이 된다.
 
Jinja의 템플릿 상속을 자세히 알고 싶다면 아래의 웹 페이지를 참고하세요!
https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance

 

4.2 FastAPI에서 Jinja를 사용하는 방법 (정리)

FastAPI에서 Jinja 템플릿을 사용하기 위해 먼저 Jinja2Templates를 설정하고, 프로젝트 루트에 templates 폴더를 생성했다. 이 폴더에는 Jinja 문법이 포함된 HTML 템플릿 파일들이 저장된다.
이번 장에서는 UI 디자인 자체보다는 템플릿 동작 원리 이해에 초점을 맞추기 때문에, CSS는 직접 작성하지 않고 부트스트랩 CDN을 활용했다.

 

템플릿 구조 구성

templates 폴더 안에는 두 개의 템플릿 파일을 생성했다.

• home.html : 애플리케이션의 기본 레이아웃(부모 템플릿) - 애플리케이션 홈 페이지용
• todo.html : 실제 todo 화면을 담당하는 자식 템플릿 - todo 페이지용

home.html은 공통 헤더와 레이아웃을 정의하고, {% block todo_container %}를 사용해 자식 템플릿의 콘텐츠가 삽입될 위치를 지정한다.

FastAPI에서 Jinja 설정

FastAPI 애플리케이션에서는 Jinja2Templates(directory="templates/")를 통해 템플릿 디렉터리를 설정하고,
라우트에서는 TemplateResponse()를 사용해 템플릿과 데이터를 함께 반환하도록 수정했다.

Todo 라우트와 템플릿 연결

todo 애플리케이션 예제에서는 다음과 같은 기능을 구현했다.

• POST /todo
  • 폼 데이터를 받아 새로운 todo를 추가
  • todo 목록을 템플릿으로 전달해 화면 갱신
• GET /todo
  • 전체 todo 목록을 조회
  • todo.html 템플릿에 todos 리스트 전달
• GET /todo/{todo_id}
  • 특정 todo 하나를 조회
  • 단일 todo 객체를 템플릿에 전달

이때 POST 요청에서는 Depends()와 Form()을 사용해 폼 데이터를 처리했다.

템플릿 렌더링 방식

todo.html 템플릿은 home.html을 상속하며, todo_container 블록 안에 실제 화면 내용을 작성한다.
같은 템플릿을 사용하지만, 전달된 데이터에 따라 화면이 달라지도록 조건문을 사용했다.

• {% if todo %}
  → 단일 todo가 전달되면 상세 정보 화면 출력
• {% else %}
  → todo 리스트가 전달되면 전체 목록 화면 출력

또한 {% for %} 반복문과 loop.index를 사용해 todo 목록을 순서대로 출력했다.

🌱 배운 점

• 템플릿팅(template rendering)은 API가 전달한 데이터를 HTML과 결합해 사용자에게 보여주는 과정이며, 웹 애플리케이션에서 화면을 구성하는 핵심 요소임을 이해했다.
• Jinja 템플릿 엔진을 사용하면 HTML 안에서 변수, 조건문, 반복문을 활용해 동적인 화면을 구성할 수 있다.
• Jinja의 필터 기능을 통해 데이터 타입 변환, 문자열 가공, 리스트 병합 등 템플릿 내 데이터 처리가 가능하다는 점을 학습했다.
• 템플릿 상속(template inheritance)을 활용하면 공통 레이아웃을 재사용할 수 있어 코드 중복을 줄이고 유지보수성을 높일 수 있다.
• FastAPI에서 Jinja2Templates와 TemplateResponse()를 사용해 API 로직과 화면 렌더링을 자연스럽게 연결할 수 있다.
• 같은 템플릿이라도 전달되는 데이터에 따라 조건문을 활용해 서로 다른 화면을 렌더링할 수 있음을 todo 예제를 통해 확인했다.

---

✨ 정리

CHAPTER 4를 통해
FastAPI에서 Jinja 템플릿을 활용한 화면 렌더링 흐름을 이해하고 직접 구현해보았다.
API에서 처리한 데이터를 템플릿으로 전달해 화면에 출력하면서,
백엔드 로직과 화면 표현을 분리하는 구조의 중요성을 체감할 수 있었다.

특히 템플릿 상속과 조건부 렌더링을 적용함으로써,
확장성과 재사용성이 높은 웹 애플리케이션 구조를 설계할 수 있다는 점을 배웠다.
이는 이후 CHAPTER 5의 애플리케이션 구조화 학습과
캡스톤 프로젝트 및 실무형 웹 백엔드 개발로 확장 가능한 기반이 될 것이다.