트리어스

JAVA의 자료구조를 톺아보자

leestana01 — Thu, 18 Jun 2026 16:53:55 +0900

Java Collection 톺아보기

List

ArrayList를 톺아보자

ArrayList는 이름에 List가 들어가지만, 본질적으로는 배열 기반 자료구조이다.

그래서 인덱스를 통한 조회가 빠르다.

배열 공간이 꽉 찬다면?
더 큰 배열을 새로 만들고, 기존 데이터를 새 배열로 복사한다.

LinkedList를 톺아보자

LinkedList는 prev, next 형태의 참조로 노드 객체를 연결하는 자료구조이다.

배열처럼 인덱스로 바로 접근할 수 없기 때문에 조회가 느리다.

중간 삽입/삭제가 빠르니 무조건 좋을까?
해당 노드를 이미 알고 있다면 빠르다.
하지만 index 기준으로 삽입/삭제를 한다면, 결국 해당 위치까지 찾아가야 하므로 느리다.

Map

HashMap을 톺아보자

HashMap의 기본적인 본질은 배열 + 해시 + 충돌 처리이다.

내부에는 다음과 같은 배열이 존재한다.

Node<K, V>[] table;

이 배열의 각 칸을 bucket이라고 부른다.

값이 저장되는 흐름은 대략 다음과 같다.

key → hash → index → bucket

즉, 주어진 key에 대해 해시를 만들고, 그 해시를 배열 인덱스로 변환한 뒤, 해당 bucket에 데이터를 저장한다.

그러나 서로 다른 key가 같은 bucket에 들어가는 해시 충돌이 발생할 수 있다.

Java의 HashMap은 기본적으로 충돌을 LinkedList로 처리한다.
다만, 한 bucket에 노드가 너무 많아지면 Red-Black Tree 구조로 바뀐다.

충돌 적음 → LinkedList
충돌 많음 → Red-Black Tree

또한 HashMap의 배열 크기는 고정되어 있지 않다.
일정 비율 이상 데이터가 차면 배열 크기를 늘리는 resize가 발생한다.

기본 load factor는 0.75이다.

resize가 발생하면 배열 크기가 달라지므로, 기존 key들의 index 계산 결과도 바뀔 수 있다.
따라서 기존 노드들을 새 배열에 다시 배치하는 rehash 과정이 필요하다.

HashMap의 성능을 좌우하는 것은?
hashCode()가 핵심이다.
hashCode()가 엉망이면 모든 key가 같은 bucket에 몰릴 수 있고, 이 경우 사실상 LinkedList처럼 동작하게 되어 성능이 떨어진다.

HashSet을 톺아보자

HashSet은 내부적으로 HashMap을 사용해 구현된다.

다만, 저장하려는 값을 HashMap의 key로 넣고, value에는 의미 없는 더미 값을 넣는다.

HashSet의 값 → HashMap의 key
더미 객체 → HashMap의 value

TreeMap을 톺아보자

HashMap은 정렬을 보장하지 않는다.

반면 TreeMap은 key를 기준으로 항상 정렬된 상태를 유지한다.

정렬을 보장하지 않는다는 뜻은?
예를 들어 c, a, b를 HashMap에 넣었다고 해서 순회 결과가 a, b, c라는 보장은 없다.
하지만 TreeMap은 key 기준 정렬을 유지하므로 a, b, c 순서를 보장한다.

TreeMap은 내부적으로 Red-Black Tree를 사용해 구현된다.

왜 Red-Black Tree일까?
일반적인 이진 탐색 트리, 즉 BST는 데이터가 1 → 2 → 3 → 4 → 5처럼 들어오면 한쪽으로 편향될 수 있다.
이 경우 트리라기보다 사실상 연결 리스트처럼 동작하게 되고, 탐색 성능이 O(n)까지 떨어질 수 있다.
그래서 TreeMap은 자가 균형 이진 탐색 트리인 Red-Black Tree를 사용한다.

TreeMap은 평균적인 조회 성능만 보면 HashMap보다 느리다.
하지만 key의 정렬이 필요하다면 TreeMap을 사용한다.

언제 사용하면 좋을까?
가장 작은 key가 필요할 때
가장 큰 key가 필요할 때
특정 범위의 key가 필요할 때
현재 key보다 큰 key가 필요할 때
현재 key보다 작은 key가 필요할 때

TreeSet을 톺아보자

TreeSet도 HashSet처럼 내부적으로 Map을 사용한다.

다만 TreeSet은 HashMap이 아니라 TreeMap을 사용한다.

저장하려는 값을 TreeMap의 key로 넣고, value에는 의미 없는 더미 값을 넣는다.

TreeSet의 값 → TreeMap의 key
더미 객체 → TreeMap의 value

Queue / Stack / Deque

PriorityQueue를 톺아보자

PriorityQueue는 이름에 Queue가 들어가지만, 일반적인 선입선출 큐라기보다는 Binary Heap 기반 자료구조이다.

내부적으로는 배열을 사용한다.

Object[] queue;

기본적으로 루트에 가장 작은 값이 위치한다.

따라서 최소값을 빠르게 꺼내야 할 때 유용하다.

ArrayDeque를 톺아보자

ArrayDeque는 head와 tail을 이용한 원형 배열 기반 Deque이다.

앞쪽과 뒤쪽 양방향에서 삽입과 삭제가 가능하다.

Java에서는 오래된 Stack 클래스 대신 ArrayDeque를 스택처럼 사용하는 경우가 많다.

Stack을 톺아보자

Stack은 내부적으로 Vector를 상속한다.

Vector는 동기화된 동적 배열이다.

하지만 요즘 Java에서는 Stack과 Vector를 잘 사용하지 않는 편이다.

왜 Vector를 잘 사용하지 않을까?
단일 스레드 환경에서는 동기화가 불필요한 비용이 된다.
멀티 스레드 환경에서는 Vector보다 더 세분화되고 목적에 맞는 동시성 컬렉션들이 존재한다.
따라서 요즘은 Stack 대신 ArrayDeque를 사용하는 것이 더 일반적으로 권장된다.

커스텀 파라미터, 그 원리와 사용방법은?

leestana01 — Thu, 18 Jun 2026 16:48:48 +0900

커스텀 파라미터 구현

설명에 앞서, 먼저 간단한 예시 코드를 작성해본다.

다음과 같은 커스텀 파라미터를 가정한다.

@Target(ElementType.PARAMETER)  
@Retention(RetentionPolicy.RUNTIME)  
@Documented  
public @interface CurrentUserId {  
}  
@CurrentUserId 자체는 파라미터 전용 런타임 Annotation입니다.

이는 다음 커스텀 Resolver가 처리한다.

Resolver에 필요한 supportsParameter와 resolveArgument를 Override해주었다.

public class CurrentUserIdArgumentResolver implements HandlerMethodArgumentResolver {  

@Override  
public boolean supportsParameter(MethodParameter parameter) {  
  return parameter.hasParameterAnnotation(CurrentUserId.class)   
    && Long.class.equals(parameter.getParameterType());  
}  

@Override  
public Long resolveArgument(...머시깽이...) {  
  ...저시깽이...  
}

마지막으로 설정을 위해 WebConfig에 다음을 추가했다고 가정한다.

Resolver 목록에 방금 제작한 커스텀 Resolver를 추가한 것이다.

이로써 방금 생성한 어노테이션을 활용할 수 있다.

@Override public void addArgumentResolvers(List<HandlerMethodArgumentResolver> resolvers) {   
  resolvers.add(new CurrentUserIdArgumentResolver());   
}

커스텀 파라미터는 어떻게 인식되는가?

이제 컨트롤러에서 다음으로 호출하는 경우를 보자.

Controller의 파라미터부터

@PostMapping("/api/participate")  
ApiResponse<?> participate(@CurrentUserId Long userId)

Spring MVC는 컨트롤러 호출 직전에 각 파라미터를 하나씩 해석한다.

@CurrentUserId Long userId를 만나면
resolver 목록을 돌면서 supportsParameter()를 호출하고,
현재 resolver가 true를 반환한다.
그 다음 resolveArgument()가 실행된다.

resolver 흐름

상기 예시의 HandlerMethodArgumentResolver를 다시 보자.

public class CurrentUserIdArgumentResolver implements HandlerMethodArgumentResolver {

@Override  
public boolean supportsParameter(MethodParameter parameter) {  
  return parameter.hasParameterAnnotation(CurrentUserId.class)   
    && Long.class.equals(parameter.getParameterType());  
}  

@Override  
public Long resolveArgument(...머시깽이...) {  
  ...저시깽이...  
}

이 Resolver는 @CurrentUserId에 대하여,
supportsParameter에 의해 true를 반환한다.

이후, resolveArgument()는 "저시깽이"의 코드에 따라 Long 값을 반환한다.

그리고 이 Long 값이 아까 봤던 Controller의 다음 코드에서
@CurrentUserId Long userId 내부에 들어갈 값이다.

@PostMapping("/api/participate")  
ApiResponse<?> participate(@CurrentUserId Long userId)

프론트의 CSR과 SSR에 따른 백엔드의 대응 방식 연구

leestana01 — Tue, 31 Mar 2026 05:47:03 +0900

배경

본인 허락 받고 인용함

최근 프론트 팀원들의 컴포넌트 CSR과 SSR에 대한 열띤 논의가 있었다.

그런데, CSR과 SSR은 프론트 측의 단순 UI 렌더링만 관련있을까?

백엔드 api 설계는 이와 완전 무관할까?

이 게시글을 통해 프론트와 백엔드 모두 컴포넌트 및 api 설계에 도움이 되길 바란다.

목표

백엔드 api에 따른 프론트 컴포넌트의 csr과 ssr의 영향을 분석하고자 한다.

가설

이를 원활히 테스트 할 수 있도록 다음과 같이 범용적인 상품 판매 시나리오를 가정했다.

결과

우선 가장 직관적으로 크롬 디버깅 툴로 직접 조사해보았다.

- Full SSR과 Full CSR로 SSR과 CSR을 분석하고

- 백엔드 V1과 V2를 통해 백엔드 api의 영향을 분석한다.

Full SSR + 백엔드 V1(단일응답)	Full CSR + 백엔드 V1(단일응답)	Hybrid + 백엔드 V1(단일응답)	Hybrid + 백엔드 V2(분할응답)

			가장 오래걸린 api

이를 상세하게 표로 정리하면 다음과 같다.

갱신 기준은 Price&Stock 정보를 매번 새롭게 갱신하는 것을 가정한다.

	Full SSR +백엔드v1	Full CSR +백엔드v1	Hybrid +백엔드v1	Hybrid +백엔드v2
TTFB	SSR 744.84ms	Html 로드 110ms API 갱신 711.91ms (+ 갱신시마다 711.91ms)	SSR 734.18ms API 갱신 716.21ms (+ 갱신시마다 716.21ms)	SSR 73.54ms API 갱신 305.44ms (+ 갱신시마다 203.83ms)
설명	전체 SSR 로딩 백엔드 API 통합	전체 CSR 로딩 백엔드 API 통합	SSR + CSR 분리 백엔드 API 통합	SSR + CSR 분리 백엔드 API 분리
API 호출 수	1회 (서버)	1회 (클라이언트)	2회+ (중복!)	4회 (분리)
초기 HTML	완전한 콘텐츠	빈 껍데기	완전한 콘텐츠	기본정보만 포함
실시간 갱신	불가	가능	가능	가능
데이터 낭비	없음	없음	중복 전송	없음
캐시 효율	불가 (통합)	불가 (통합)	불가 (통합)	static 캐시

웹 자체에 메트릭 분석을 포함해본 결과는 다음과 같다.

단순하게 useEffect/useCallback를 통해 로드되는 시점과 이후의 시간을 비교했다.

분석

프론트가 CSR + SSR 구조를 가져가고, 이에 맞춰 백엔드가 api를 설계하면 베스트이다.
그러나 하나라도 어긋나면 성능이 극도로 저하된다.
- 즉, 프론트/백엔드 소통이 이루어지지 않으면 무용지물이다.
- 프론트가 SSR ALL 또는 CSR ALL을 쓰면, 백엔드가 api 설계를 잘해도 의미가 없다.
- 프론트가 CSR + SSR을 써도,
  백엔드가 어느 포인트에서 api 분리가 필요한지 알지 못한다면 api 응답은 중복되어 성능이 극감할수있다.
SSR이 근소하게 빠르다.
로컬호스트에서 진행된 만큼, 프로덕션에서는 서버 환경이 가장 큰 예외 변수일 것 같다.
API 호출 수가 많으면 TCP Connection이 많아져 더 느려질 거라고 생각했는데,
어차피 동시에 비동기 요청하므로 의미 없다는걸 깨달았다. 그냥 서버만 죽어나갈 뿐..

마치며

이 게시글은 성능만 언급했다. 그러나 SSR 이 도입될수록 서버 관리는 극악이다.

조사 중, 토스도 유사한 고민을 했다는 것을 알 수 있었다.

다음 토스 서버비를 보면 알 수 있다.

출처 : https://toss.tech/article/ssr-server

놀라웠던 사실은 토스는 코드 상의 최적화를 넘어, 인프라 팀과 협업하며 지표를 분석했다.

이를 확인하는 과정이 매우 놀라운데, 꽤나 재밌다.

특히 재밌던건 OpenTelemetry 지원안한다고 최신버전에서 hook 빼내서 삽입하고,
Next.js 커스텀서버에서 Express를 제거해 Node 내장 http 서버로 돌리는 등 프레임워크를 가지고 놀더라는 점이다.

토스에서 직접 제시한 교훈을 마지막으로 이 글을 마친다. 꽤나 토스의 철학과 일치하는 질문인 것 같다.

Node.js SSR 서버의 성능을 개선하고 싶다면, 다음의 과정을 한 번 고민해보시면 좋겠습니다.
1. 현재의 런타임은 어떻게 구성되어 있는가? 네트워크 토폴로지는 어떻게 구성되어 있으며, 어떤 요청이 오가는가?
2. 측정이 필요한 성능은 무엇이 있는가? 측정할 수 있는가?
3. 개선 전후를 확인할 수 있는, 변인이 통제된 재현 환경이 존재하는가?

FastAPI 기본부터 극한까지 날먹하기 (Pydantic, Depends 심화)

leestana01 — Mon, 30 Mar 2026 20:41:18 +0900

Discriminated Union

만약 결제 수단(카드, 계좌이체, 간편결제)에 따라 요청 구조가 다르다면?

Spring에서는 @JsonTypeInfo + @JsonSubTypes를 사용해야 하고, 커스텀 디시리얼라이저를 작성해야 하는 경우도 많다.

Pydantic에서는 매우 간단하게 처리 가능하다. 다음 코드를 살펴보자.

from pydantic import BaseModel, Field
from typing import Literal, Annotated, Union
from enum import Enum

# 각 결제 수단별 요청 스키마
class CardPaymentRequest(BaseModel):
    method: Literal["CARD"] = "CARD"
    card_number: str = Field(..., pattern=r"^\d{16}$")
    expiry_month: int = Field(..., ge=1, le=12)
    expiry_year: int = Field(..., ge=2024, le=2035)
    cvv: str = Field(..., pattern=r"^\d{3,4}$")
    installment_months: int = Field(default=0, ge=0, le=12)

class BankTransferRequest(BaseModel):
    method: Literal["BANK_TRANSFER"] = "BANK_TRANSFER"
    bank_code: str = Field(..., pattern=r"^\d{3}$")
    account_number: str = Field(..., pattern=r"^\d{10,14}$")
    account_holder: str = Field(..., min_length=2, max_length=20)

class EasyPayRequest(BaseModel):
    method: Literal["EASY_PAY"] = "EASY_PAY"
    provider: str = Field(..., pattern="^(TOSS|KAKAO|NAVER)$")
    token: str

# Discriminated Union — method 필드를 기준으로 자동 판별
PaymentMethodRequest = Annotated[
    Union[CardPaymentRequest, BankTransferRequest, EasyPayRequest],
    Field(discriminator="method"),
]

class CreatePaymentRequest(BaseModel):
    amount: int = Field(..., gt=0, le=100_000_000)
    currency: str = Field(default="KRW", pattern="^(KRW|USD|JPY)$")
    order_id: str = Field(..., min_length=1, max_length=64)
    payment_method: PaymentMethodRequest  # 결제 수단에 따라 다른 스키마 적용
    description: str | None = Field(None, max_length=200)

# 요청 예시:
# {"amount": 50000, "order_id": "ORD-001",
#  "payment_method": {"method": "CARD", "card_number": "1234567890123456", ...}}
# → CardPaymentRequest로 자동 파싱

# {"amount": 50000, "order_id": "ORD-002",
#  "payment_method": {"method": "BANK_TRANSFER", "bank_code": "004", ...}}
# → BankTransferRequest로 자동 파싱

응답 모델

response에서 데이터를 가공해서 필요한 응답을 제공해보자.

간편하게 즉시 연산하여 반환할 수 있다.

from pydantic import BaseModel, ConfigDict, computed_field
from datetime import datetime

class PaymentResponse(BaseModel):
    """결제 응답 — 민감 정보 마스킹 포함"""
    model_config = ConfigDict(
        from_attributes=True,     # ORM 객체에서 자동 변환 (= ModelMapper)
        populate_by_name=True,    # 별칭과 원래 이름 모두 허용
    )

    payment_id: UUID
    status: PaymentStatus
    amount: int
    currency: str
    fee: int
    description: str | None
    created_at: datetime
    completed_at: datetime | None

    # Computed Field — 파생 값 자동 계산
    @computed_field
    @property
    def total_amount(self) -> int:
        """수수료 포함 총액"""
        return self.amount + self.fee

    @computed_field
    @property
    def masked_card_number(self) -> str | None:
        """카드번호 마스킹 (핀테크 필수)"""
        if hasattr(self, "_card_number") and self._card_number:
            return f"{'*' * 12}{self._card_number[-4:]}"
        return None

# 목록 조회용 간소화 응답
class PaymentSummary(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    payment_id: UUID
    status: PaymentStatus
    amount: int
    created_at: datetime

# 페이지네이션 래퍼 (제네릭)
T = TypeVar("T", bound=BaseModel)

class PaginatedResponse(BaseModel, Generic[T]):
    items: list[T]
    total_count: int
    page: int
    size: int

    @computed_field
    @property
    def total_pages(self) -> int:
        return (self.total_count + self.size - 1) // self.size

    @computed_field
    @property
    def has_next(self) -> bool:
        return self.page < self.total_pages

Custom Serializer

api 응답할 때 dto 수준에서 금액을 바로 포맷팅 해보자.

from pydantic import field_serializer, field_validator

class MoneyResponse(BaseModel):
    amount: int           # 내부: 정수 (원 단위)
    currency: str

    @field_serializer("amount")
    def serialize_amount(self, value: int, _info) -> str:
        """API 응답에서 금액을 포맷팅"""
        if self.currency == "KRW":
            return f"{value:,}원"
        return f"{value / 100:.2f}"  # USD 등은 센트 단위

    # 역직렬화 시 (요청 받을 때) 타입 변환
    @field_validator("amount", mode="before")
    @classmethod
    def parse_amount(cls, v: int | str) -> int:
        if isinstance(v, str):
            return int(v.replace(",", "").replace("원", ""))
        return v

의존성 주입(DI) 심화

Depends()는 "함수를 호출하고, 그 반환값을 파라미터로 주입"하는 것이 전부다.
즉, Spring의 IoC Container와는 근본적으로 다르다.

Spring: 컨테이너가 빈의 생명주기를 관리 (생성, 주입, 소멸)
FastAPI: Depends()가 호출된 시점에 팩토리 함수를 실행하여 값을 주입

Depends()의 동작 원리

실행 흐름은 다음과 같다.

요청 도착
FastAPI가 엔드포인트 함수의 파라미터를 분석
Depends()를 발견하면 해당 함수를 호출
Depends() 체이닝이 있으면 재귀적으로 해결
모든 의존성이 해결되면 엔드포인트 함수 호출
요청 종료 시 generator 기반 의존성의 cleanup 실행

yield를 사용하면 cleanup 로직을 정의할 수 있다.

async def get_db() -> AsyncGenerator[AsyncSession, None]:
    session = async_session_factory()
    try:
        yield session        # ← 여기서 값이 주입됨
        await session.commit()
    except Exception:
        await session.rollback()
        raise
    finally:
        await session.close()  # ← 요청 종료 시 실행됨 (= @PreDestroy)

Depends() 보일러플레이트 해결

문제는 Depends() 팩토리 함수가 끝없이 늘어나는 경우이다.
10개 서비스에서 동일하게 아래 코드가 반복 된다고 가정해보자.

def get_payment_repo(db: AsyncSession = Depends(get_db)) -> PaymentRepository:
    return PaymentRepository(db)

def get_payment_service(
    repo: PaymentRepository = Depends(get_payment_repo),
) -> PaymentService:
    return PaymentService(repo)

이는 크게 두 가지 방식으로 해결한다.

Annotated 타입으로 재사용하거나 (Spring의 @Autowired처럼)
Class 기반 의존성을 활용하거나 (Spring의 @Component처럼)

Annotated 타입으로 재사용 하는 방법

from typing import Annotated

DBSession = Annotated[AsyncSession, Depends(get_db)]
AuthUser = Annotated[CurrentUser, Depends(get_current_user)]
PaymentSvc = Annotated[PaymentService, Depends(get_payment_service)]

@router.post("/payments")
async def create_payment(
    request: CreatePaymentRequest,
    db: DBSession,              # 깔끔
    user: AuthUser,             # 깔끔
    service: PaymentSvc,        # 깔끔
) -> PaymentResponse:
    ...

Class 기반 의존성으로 처리하는 방법 (Spring @Component 처럼)

class PaymentService:
    """
    __init__에 Depends()를 사용하면 클래스 자체를 Depends()에 넣을 수 있다.
    Spring의 생성자 주입과 거의 동일한 형태이다.
    """
    def __init__(
        self,
        repo: PaymentRepository = Depends(get_payment_repo),
        fee_calc: FeeCalculator = Depends(get_fee_calculator),
        event_bus: EventBus = Depends(get_event_bus),
    ):
        self.repo = repo
        self.fee_calc = fee_calc
        self.event_bus = event_bus

    async def create_payment(self, request: CreatePaymentRequest) -> Payment:
        ...

# 라우터에서 바로 클래스를 Depends에 전달
@router.post("/payments")
async def create_payment(
    request: CreatePaymentRequest,
    service: PaymentService = Depends(),  # ← Depends(PaymentService)와 동일
) -> PaymentResponse:
    return await service.create_payment(request)

싱글톤 의존성 (app.state와 lifespan)

FastAPI에서 싱글톤이 필요한 경우들이 있다. 가령, 다음과 같다.

(사실 이렇게 나열할 필요도 없이, 당연히 싱글톤으로 작성되어야 하는 설정 정보들이다.)

DB 엔진 (커넥션 풀)
Redis 클라이언트
HTTP 클라이언트 풀
설정 객체

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 싱글톤 초기화
    app.state.db_engine = create_async_engine(settings.DATABASE_URL)
    app.state.redis = redis.from_url(settings.REDIS_URL)
    app.state.http_client = httpx.AsyncClient(timeout=30.0)

    yield

    # 싱글톤 정리
    await app.state.db_engine.dispose()
    await app.state.redis.close()
    await app.state.http_client.aclose()

app = FastAPI(lifespan=lifespan)

# 싱글톤 접근 패턴
from fastapi import Request

async def get_redis(request: Request) -> redis.Redis:
    return request.app.state.redis

RedisClient = Annotated[redis.Redis, Depends(get_redis)]

async/await

동시성 모델의 근본적 차이

Spring을 경험해보지 못한 사람들에게는 미안하지만, 원활한 이해를 위해 Spring과 비교해보자.

Spring MVC

FastAPI

Thread Pool (200 스레드)
- Thread-1: 요청 A 처리 중 (DB 대기... 3초 동안 스레드 점유)
- Thread-2: 요청 B 처리 중 (API 호출 대기... 5초 동안 스레드 점유)
- Thread-3: 요청 C 처리 중
- ... 197개 남은 스레드

→ 동시 처리 한계 = 스레드 수 (200)
→ I/O 대기 중에도 스레드를 점유하므로 비효율적

Event Loop (1개) + 코루틴 (무제한)
- 코루틴 A: DB 쿼리 await → 이벤트 루프에 제어권 반환 → 다른 코루틴 실행
- 코루틴 B: API 호출 await → 이벤트 루프에 제어권 반환 → 다른 코루틴 실행
- 코루틴 C: 처리 중
- ... 수천 개의 코루틴이 하나의 스레드에서 교대 실행

→ 동시 처리 한계 = 메모리 (사실상 무제한)
→ I/O 대기 중 스레드를 해제하므로 매우 효율적

Event Loop 방식 덕분에 소규모 프로젝트에서는 얻는 장점이 매우 크다.

그러나 다음의 문제가 동반된다.

Event Loop가 막히면 전체 서비스가 막힌다는 점
하나만 async를 써도 전체가 async를 강제로 써야한다는 점 (일부만 비동기 불가능)

비동기 동시 실행 패턴

import asyncio
import httpx

# === 순차 실행 (나쁜 예) ===
async def enrich_payment_sequential(payment_id: UUID) -> dict:
    """3개 API를 순서대로 호출 → 총 3초"""
    fraud = await fraud_client.check(payment_id)        # 1초
    balance = await account_client.get_balance(payment_id)  # 1초
    fee = await fee_client.calculate(payment_id)         # 1초
    return {"fraud": fraud, "balance": balance, "fee": fee}

# === 동시 실행 (좋은 예) ===
async def enrich_payment_concurrent(payment_id: UUID) -> dict:
    """3개 API를 동시에 호출 → 총 1초 (가장 느린 것 기준)"""
    fraud, balance, fee = await asyncio.gather(
        fraud_client.check(payment_id),
        account_client.get_balance(payment_id),
        fee_client.calculate(payment_id),
    )
    return {"fraud": fraud, "balance": balance, "fee": fee}

# === 동시 실행 + 개별 에러 처리 ===
async def enrich_payment_safe(payment_id: UUID) -> dict:
    """일부 실패해도 나머지는 사용"""
    results = await asyncio.gather(
        fraud_client.check(payment_id),
        account_client.get_balance(payment_id),
        fee_client.calculate(payment_id),
        return_exceptions=True,  # 예외를 반환값으로 전환
    )

    return {
        "fraud": results[0] if not isinstance(results[0], Exception) else None,
        "balance": results[1] if not isinstance(results[1], Exception) else None,
        "fee": results[2] if not isinstance(results[2], Exception) else None,
        "errors": [
            str(r) for r in results if isinstance(r, Exception)
        ],
    }

# === TaskGroup ===
async def enrich_payment_taskgroup(payment_id: UUID) -> dict:
    """하나라도 실패하면 나머지도 취소"""
    async with asyncio.TaskGroup() as tg:
        fraud_task = tg.create_task(fraud_client.check(payment_id))
        balance_task = tg.create_task(account_client.get_balance(payment_id))
        fee_task = tg.create_task(fee_client.calculate(payment_id))

    # TaskGroup 블록을 벗어나면 모든 Task 완료 보장
    return {
        "fraud": fraud_task.result(),
        "balance": balance_task.result(),
        "fee": fee_task.result(),
    }

사용자가 많아지면 Rate Limit를 강제해야하는 경우가 무조건 생긴다.

이는 다음과 같이 처리 가능하다. (Semaphore를 통한 동시성 제한)

semaphore = asyncio.Semaphore(10)  # 동시 10개까지

async def call_with_limit(url: str) -> dict:
    async with semaphore:
        async with httpx.AsyncClient() as client:
            response = await client.get(url)
            return response.json()

# 100개 요청을 동시에 10개씩 처리
results = await asyncio.gather(
    *[call_with_limit(f"/api/item/{i}") for i in range(100)]
)

async def vs def

언제 async를 사용해야할까? 어떤 점에 유의해야할까?

async를 사용하면 async로 선언하면 된다. 너무 당연하다.

그럼 async 내에서는 딱히 유의할게 없을까?

다음을 살펴보자.

@router.get("/report")
async def generate_report():
    # time.sleep은 블로킹! 이벤트 루프 전체를 3초간 멈춤
    time.sleep(3)  # 절대 금지

    # requests.get은 블로킹! httpx.AsyncClient를 써야 함
    result = requests.get("https://api.example.com")  # 절대 금지

앞서 말한것처럼 FastAPI는 하나의 Event Loop를 공유한다.

위처럼 블로킹 함수를 async 안에서 선언하면 매우 위험하다.

그렇다면 어떻게 처리할 수 있을까? 방법은 다양할 것이다.

블로킹 함수를 async로 처리한다.
함수를 애당초 동기 함수로 만들어버린다.
블로킹 함수를 별도 쓰레드로 넘긴다.

# async 함수 + async 라이브러리
@router.get("/report")
async def generate_report():
    await asyncio.sleep(3)  # 비동기 sleep
    async with httpx.AsyncClient() as client:
        result = await client.get("https://api.example.com")  # 비동기 HTTP

# 동기 함수 (블로킹 코드를 써야 할 때)
@router.get("/report")
def generate_report():  # async 아님!
    # FastAPI가 자동으로 스레드풀에서 실행
    time.sleep(3)  # 이건 괜찮음 (별도 스레드)
    result = requests.get("https://api.example.com")  # 이것도 괜찮음

# async 함수 안에서 동기 코드를 실행해야 할 때
@router.get("/report")
async def generate_report():
    # 동기 함수를 스레드풀에 위임
    result = await asyncio.to_thread(
        generate_heavy_pdf,  # CPU 바운드 동기 함수
        data=report_data,
    )
    return FileResponse(result)

조금 헷갈릴 수 있어서,

자주 마주할 수 있는 상황을 기준으로 다음과 같이 정리해본다.

async 라이브러리 사용 (asyncpg, httpx, aioredis)	async def	논블로킹 I/O 활용
동기 라이브러리 사용 (psycopg2, requests)	def	FastAPI가 스레드풀 처리
CPU 연산 (PDF 생성, 암호화, 데이터 변환)	def	CPU 바운드는 async 의미 없음
여러 외부 서비스 동시 호출	async def + gather	병렬 I/O
파일 읽기/쓰기	def 또는 aiofiles	디스크 I/O
WebSocket 처리	async def	필수
의심스러울 때	def	안전한 기본값

FastAPI 기본부터 극한까지 날먹하기 (SpringBoot에서 넘어가기)

leestana01 — Mon, 30 Mar 2026 20:14:30 +0900

용어부터 알아보자

SpringBoot와 FastAPI는 어떻게 다를까? 기본적인 구조부터 잡고 가면 편할 것 같다.

JDK (Java 17/21)	Python (3.11/3.12/3.13)
Maven / Gradle	Poetry / uv / pip
application.yml	.env + pydantic-settings
Tomcat (내장 서블릿 컨테이너)	Uvicorn (ASGI 서버)
Spring Initializr	수동 구성 (or cookiecutter)
./gradlew bootRun	uvicorn app.main:app --reload
JAR 패키징	Docker 이미지 (사실상 표준)
JUnit + Mockito	pytest + pytest-asyncio + httpx
Checkstyle + SpotBugs	Ruff + mypy
Lombok	dataclass / Pydantic (언어 자체에 내장)

보기만 해도 바이트코드로 컴파일해서 동작하는 Java의 위대함이 다시 돋보인다.

그럼에도 이 열악한 환경에서 간편하고 개발친화적인 환경을 구축한 FastAPI에 경이로움을 표한다.

근데 요즘은 이렇게 다 서드파티 엮고 내장시키는게 유행인가.. 나도 프레임워크 하나 개발해볼까 싶다.

바꿔야 할 사고방식

SpringBoot에 익숙하다면 FastAPI로 넘어가는 것은 어렵지 않다.

그러나 그 속도를 빠르게 하려면, 우선 Python으로 사고하는 법을 익힐 필요가 있다.

모든 것이 클래스가 아니다

Java: 모든 것이 클래스 안에 존재

Java는 유틸리티 함수 하나를 위해서도 클래스가 필요하다.

public class FeeCalculator {
    public static int calculate(int amount) {
        return Math.max(amount * 1 / 1000, 500);
    }
}

// 호출: FeeCalculator.calculate(100000)

Python: 함수가 독립적으로 존재

파이썬은 파일 자체가 모듈이다. 즉, 클래스가 불필요하다.

def calculate_fee(amount: int) -> int:
    return max(amount // 1000, 500)

# 호출: from app.domain.payment.fee_utils import calculate_fee

그럼, Class는 언제 만들어야할까? 쉽게 정리해봤다.

Class가 필요한 겨우	함수로 충분한 경우
상태(state)를 가질 때 초기화 시 설정을 받고, 메서드마다 그 설정을 사용 여러 메서드가 공유하는 컨텍스트가 있을 때 DB 세션, HTTP 클라이언트 등... 다형성이 필요할 때 Protocol/ABC로 인터페이스 정의, 여러 구현체	입력 → 출력이 명확한 변환/계산 로직 유틸리티 함수 간단한 팩토리

Interface가 없다 → Protocol을 쓴다

Java: Interface + 구현체

public interface PaymentGateway {
    PaymentResult charge(ChargeRequest request);
    PaymentResult refund(RefundRequest request);
}

@Service
public class TossPaymentGateway implements PaymentGateway {
    @Override
    public PaymentResult charge(ChargeRequest request) { ... }
    @Override
    public PaymentResult refund(RefundRequest request) { ... }
}

Python: Protocol (구조적 서브타이핑)

Protocol은 Java의 Interface에 해당한다. 그러나 근본적인 차이가 존재한다.

Interface : 명시적으로 implements를 선언해야 함
Protocol : 메서드 시그니처만 맞으면 자동 호환 (덕 타이핑)

덕 타이핑이란? Gemini의 예시를 살펴보자.

class Duck:
    def quack(self):
        print("꽥꽥!")

class Person:
    def quack(self):
        print("사람이 오리 소리를 냅니다.")

def make_it_quack(animal):
    # animal이 무엇이든 상관없이 quack() 메서드만 있으면 작동
    animal.quack()

duck = Duck()
person = Person()

make_it_quack(duck)   # 꽥꽥!
make_it_quack(person) # 사람이 오리 소리를 냅니다.

즉, 객체의 실제 타입보다 객체가 가진 속성과 메서드가 무엇인지(행동)를 기반으로 타입을 판단하는 방식이다.

from typing import Protocol, runtime_checkable

@runtime_checkable
class PaymentGateway(Protocol):
    async def charge(self, request: ChargeRequest) -> PaymentResult: ...
    async def refund(self, request: RefundRequest) -> PaymentResult: ...

# implements 키워드가 없다!
class TossPaymentGateway:
    """Protocol에 정의된 메서드를 구현하면 자동으로 PaymentGateway 호환"""

    def __init__(self, api_key: str, base_url: str):
        self.client = httpx.AsyncClient(
            base_url=base_url,
            headers={"Authorization": f"Basic {api_key}"},
        )

    async def charge(self, request: ChargeRequest) -> PaymentResult:
        response = await self.client.post("/v1/payments", json=request.model_dump())
        return PaymentResult(**response.json())

    async def refund(self, request: RefundRequest) -> PaymentResult:
        response = await self.client.post(
            f"/v1/payments/{request.payment_key}/cancel",
            json={"cancelReason": request.reason},
        )
        return PaymentResult(**response.json())

# 다른 PG사 구현체
class KakaoPayGateway:
    async def charge(self, request: ChargeRequest) -> PaymentResult: ...
    async def refund(self, request: RefundRequest) -> PaymentResult: ...

# 타입 체커가 PaymentGateway 호환 여부를 검증
def get_gateway(gateway_type: str) -> PaymentGateway:
    if gateway_type == "toss":
        return TossPaymentGateway(api_key="...", base_url="...")
    elif gateway_type == "kakao":
        return KakaoPayGateway(...)
    raise ValueError(f"Unknown gateway: {gateway_type}")

ABC(Abstract Base Class) - 명시적 상속이 필요할 때

Protocol과 달리 명시적 상속을 강제한다. Java의 abstract class에 가장 가깝다.
언제 ABC를 쓰고 언제 Protocol을 써야할 까?

ABC: 공통 구현 로직이 있을 때 (Template Method 패턴)
Protocol: 인터페이스 계약만 정의할 때 (Strategy 패턴)

from abc import ABC, abstractmethod

class PaymentGateway(ABC):
    def __init__(self, api_key: str, base_url: str):
        # 공통 초기화 (= Java abstract class의 constructor)
        self.client = httpx.AsyncClient(
            base_url=base_url,
            headers=self._build_headers(api_key),
            timeout=30.0,
        )

    @abstractmethod
    def _build_headers(self, api_key: str) -> dict[str, str]:
        """각 PG사별 인증 헤더 포맷이 다름"""
        ...

    @abstractmethod
    async def charge(self, request: ChargeRequest) -> PaymentResult: ...

    @abstractmethod
    async def refund(self, request: RefundRequest) -> PaymentResult: ...

    # 공통 메서드 (= Java abstract class의 concrete method)
    async def health_check(self) -> bool:
        try:
            response = await self.client.get("/health")
            return response.status_code == 200
        except httpx.HTTPError:
            return False

class TossPaymentGateway(PaymentGateway):  # 명시적 상속
    def _build_headers(self, api_key: str) -> dict[str, str]:
        return {"Authorization": f"Basic {api_key}"}

    async def charge(self, request: ChargeRequest) -> PaymentResult: ...
    async def refund(self, request: RefundRequest) -> PaymentResult: ...

타입 시스템

Java는 컴파일 타임에 타입이 강제된다. (즉, 타입 오류 = 컴파일 실패)
Python은 런타임 언어이다. 타입 힌트는 "선택적 문서"이며, 런타임에 무시된다.

그런데 FastAPI/Pydantic이 타입 힌트를 런타임에 활용하면서 상황이 바뀐다

from typing import Annotated, TypeVar, Generic
from pydantic import BaseModel, Field

# === 기본 타입 힌트 ===
def add(a: int, b: int) -> int:      # Java의 int add(int a, int b)
    return a + b

# === Optional 처리 ===
# Java: Optional<String>
# Python:
name: str | None = None               # Python 3.10+ 문법
name: Optional[str] = None            # 구버전 문법 (동일 의미)

# === 제네릭 ===
# Java: public class ApiResponse<T> { T data; String message; }
T = TypeVar("T")

class ApiResponse(BaseModel, Generic[T]):
    data: T
    message: str
    success: bool = True

# 사용:
class PaymentListResponse(BaseModel):
    payments: list[PaymentResponse]
    total_count: int

response: ApiResponse[PaymentListResponse]  # 구체 타입 지정

Java에는 없는 것도 있다. FastAPI의 꽤나 강력한 무기라고 생각한다.

# === Annotated ===
# Java에는 없는 개념. 타입에 메타데이터를 부착한다.
from fastapi import Depends, Query

# Before (보일러플레이트)
@router.get("/payments")
async def list_payments(
    page: int = Query(1, ge=1),
    size: int = Query(20, ge=1, le=100),
    db: AsyncSession = Depends(get_db),
    user: CurrentUser = Depends(get_current_user),
): ...

# After (Annotated로 재사용 가능한 타입 정의)
Page = Annotated[int, Query(ge=1, description="페이지 번호")]
PageSize = Annotated[int, Query(ge=1, le=100, description="페이지 크기")]
DBSession = Annotated[AsyncSession, Depends(get_db)]
AuthUser = Annotated[CurrentUser, Depends(get_current_user)]

@router.get("/payments")
async def list_payments(
    page: Page = 1,
    size: PageSize = 20,
    db: DBSession,
    user: AuthUser,
): ...
# → 타입 + DI + 검증이 하나의 타입 별칭으로 통합

mypy

Java 컴파일러의 타입 검사에 해당한다. 필히 다음에 꼭 유의하자.

mypy strict 모드를 처음부터 적용할 것. 나중에 켜면 수천 개의 에러가 쏟아진다.
Pydantic, SQLAlchemy 용 mypy 플러그인을 반드시 설정할 것.
CI/CD에 mypy 검사를 포함할 것.

# 타입 체크 실행 (= javac의 타입 검사 부분만 수행)
mypy app/

# 에러 예시:
# app/service.py:42: error: Argument 1 to "withdraw" has incompatible type "str"; expected "int"

데코레이터

Spring AOP(@Transactional, @Cacheable, @Async, @PreAuthorize)의 역할(이걸 횡단 관심사 라고 하더라..)에 대해

Python에서는 데코레이터가 그 역할을 한다.

import functools
import time
import structlog
from typing import Callable, ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")
logger = structlog.get_logger()

# === 성능 측정 데코레이터 (= Spring AOP의 @Around 어드바이스) ===
def measure_time(func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        try:
            result = await func(*args, **kwargs)
            return result
        finally:
            duration = (time.perf_counter() - start) * 1000
            logger.info(
                "function_executed",
                function=func.__name__,
                duration_ms=round(duration, 2),
            )
    return wrapper

# === 재시도 데코레이터 (= Spring Retry의 @Retryable) ===
def retry(
    max_attempts: int = 3,
    delay: float = 1.0,
    backoff_factor: float = 2.0,
    exceptions: tuple[type[Exception], ...] = (Exception,),
):
    def decorator(func: Callable[P, R]) -> Callable[P, R]:
        @functools.wraps(func)
        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            last_exception: Exception | None = None
            current_delay = delay

            for attempt in range(1, max_attempts + 1):
                try:
                    return await func(*args, **kwargs)
                except exceptions as e:
                    last_exception = e
                    if attempt < max_attempts:
                        logger.warn(
                            "retry_attempt",
                            function=func.__name__,
                            attempt=attempt,
                            max_attempts=max_attempts,
                            delay=current_delay,
                            error=str(e),
                        )
                        await asyncio.sleep(current_delay)
                        current_delay *= backoff_factor

            raise last_exception  # type: ignore
        return wrapper
    return decorator

# === 사용 ===
class PGGatewayClient:

    @measure_time
    @retry(max_attempts=3, delay=0.5, exceptions=(httpx.HTTPError, TimeoutError))
    async def charge(self, request: ChargeRequest) -> PaymentResult:
        response = await self.client.post("/v1/payments", json=request.model_dump())
        response.raise_for_status()
        return PaymentResult(**response.json())

알면 좋은 Spring AOP와의 차이
- Spring AOP는 프록시 기반이므로, 같은 클래스 내에서 this.method()를 호출하면 AOP가 동작하지 않는 유명한 함정이 있다. Python 데코레이터는 함수 자체를 래핑하므로 이 문제가 없다.
- Spring AOP는 런타임에 프록시 객체를 생성하므로 디버깅이 어렵다. Python 데코레이터는 스택 트레이스가 명확하다.

컨텍스트 매니저

솔직히 SpringBoot에서 넘어가면 좀 번거롭게 느껴지는 부분이다.

다음 코드로 설명을 대체한다.

# Java의 try-with-resources:
# try (Connection conn = dataSource.getConnection()) { ... }

# Python의 context manager:
async with async_session_factory() as session:
    # session 사용
    ...
# 자동으로 close/rollback

# 직접 만들기 (= AutoCloseable 구현)
from contextlib import asynccontextmanager

@asynccontextmanager
async def transaction(db: AsyncSession):
    """
    명시적 트랜잭션 관리.
    Spring의 @Transactional(propagation = REQUIRES_NEW)와 유사한 역할.
    """
    try:
        yield db
        await db.commit()
    except Exception:
        await db.rollback()
        raise
    finally:
        await db.close()

# 사용
async def transfer_money(sender_id: UUID, receiver_id: UUID, amount: int):
    async with transaction(db) as session:
        await debit(session, sender_id, amount)
        await credit(session, receiver_id, amount)
        # 블록을 벗어나면 자동 commit, 예외 시 자동 rollback

FastAPI 기본부터 극한까지 날먹하기

leestana01 — Mon, 30 Mar 2026 17:58:00 +0900

서론

일반적인 FastAPI 강의는 지양한다. 그럴거면 ChatGPT에게 물어보는게 낫다.

아키텍처 구조부터 모든 한 줄마다 연구하고 최적의 방향을 서술할 것이다.

환경 구축

Python 버전 관리

파이썬 설치 방법까지는 언급하지 않겠다. 그러나 경우에 따라 Python의 버전 관리가 필요할 수 있다.

Java에서 sdkman으로 JDK 17, 21을 전환하듯, Python에서는 pyenv를 사용한다.

# 설치
curl https://pyenv.run | bash

# ~/.bashrc 또는 ~/.zshrc에 추가
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# Python 버전 설치 및 전환
pyenv install 3.12.4
pyenv install 3.11.9
pyenv global 3.12.4          # 시스템 전체 기본
pyenv local 3.11.9           # 현재 디렉토리에서만 (.python-version 파일 생성)

# 설치된 버전 확인
pyenv versions

프로젝트 초기화

라이브러리 천국 Python 답게 패키지매니저도 다양하다.

venv + pip (비추)

문제는 requirements.txt에 의존한다는 것.

lock 파일이 아니므로 재현성 보장 안 된다는 의견도 있으나, 보통 pip freeze 쓰니깐 상관 없을 듯

개발/프로덕션 의존성 분리 불가
의존성 해결이 단순해 충돌 가능

# 디렉토리 생성
mkdir practice-api && cd practice-api

# 가상환경 생성 (= 이 프로젝트 전용 Python 사본 생성)
python3 -m venv .venv

# 활성화
source .venv/bin/activate          # Linux/Mac
# .venv\Scripts\activate           # Windows

# 프롬프트가 바뀜:
# (.venv) user@host:~/practice-api$

# pip 업그레이드 후 패키지 설치
pip install --upgrade pip
pip install fastapi "uvicorn[standard]" sqlalchemy alembic pydantic-settings

# 설치 기록 (= 의존성 스냅샷)
pip freeze > requirements.txt

# 다른 환경에서 복원
pip install -r requirements.txt

poetry

gradle과 유사한 느낌이 든다.

UV와 성능차이가 궁금해서 조사하다가 아래 블로그를 발견했다. 궁금하면 들어가보시길

https://devocean.sk.com/blog/techBoardDetail.do?ID=167425&boardType=techBlog

Python Poetry 대신 UV를 써보면서 느낀 점들

devocean.sk.com

# Poetry 설치 (공식 방법)
curl -sSL https://install.python-poetry.org | python3 -

# 프로젝트 초기화
mkdir practice-api && cd practice-api
poetry init --no-interaction

# 핵심 의존성 추가 (= implementation 'group:artifact:version')
poetry add fastapi
poetry add "uvicorn[standard]"
poetry add sqlalchemy[asyncio]
poetry add asyncpg                # PostgreSQL async 드라이버
poetry add alembic
poetry add pydantic-settings
poetry add structlog              # 구조화 로깅
poetry add httpx                  # async HTTP 클라이언트
poetry add "redis[hiredis]"       # Redis 클라이언트 (성능 최적화)
poetry add "python-jose[cryptography]"  # JWT

# 개발 의존성 (= testImplementation, developmentOnly)
poetry add --group dev pytest
poetry add --group dev pytest-asyncio
poetry add --group dev pytest-cov
poetry add --group dev httpx         # 테스트용 async HTTP 클라이언트
poetry add --group dev ruff          # 린터 + 포매터 (통합)
poetry add --group dev mypy          # 타입 체커
poetry add --group dev factory-boy   # 테스트 픽스처 팩토리
poetry add --group dev faker         # 테스트 데이터 생성

# 의존성 설치 (= gradle build)
poetry install

# 실행
poetry run uvicorn app.main:app --reload

pyproject.toml

build.gradle 과 유사하다. Node 사용자라면 package-lock 생각해도 될 듯.

[tool.poetry]
name = "practice-api"
version = "0.1.0"
description = "API 연습용 서버"
authors = ["Team Lead <lead@practice.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.115.0"
uvicorn = {extras = ["standard"], version = "^0.30.0"}
sqlalchemy = {extras = ["asyncio"], version = "^2.0"}
asyncpg = "^0.30.0"
alembic = "^1.14"
pydantic-settings = "^2.5"
structlog = "^24.4"
httpx = "^0.27"
redis = {extras = ["hiredis"], version = "^5.0"}
python-jose = {extras = ["cryptography"], version = "^3.3"}

[tool.poetry.group.dev.dependencies]
pytest = "^8.3"
pytest-asyncio = "^0.24"
pytest-cov = "^5.0"
ruff = "^0.6"
mypy = "^1.11"
factory-boy = "^3.3"
faker = "^30.0"

# === 린터/포매터 설정 (= Checkstyle 설정) ===
[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = [
    "E",    # pycodestyle errors
    "W",    # pycodestyle warnings
    "F",    # pyflakes
    "I",    # isort (import 정렬)
    "N",    # pep8-naming
    "UP",   # pyupgrade
    "B",    # flake8-bugbear
    "SIM",  # flake8-simplify
    "ASYNC",# flake8-async
]

# === 타입 체커 설정 (= Java 컴파일러의 타입 검사에 해당) ===
[tool.mypy]
python_version = "3.12"
strict = true                    # 가장 엄격한 모드
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true     # 타입 힌트 없는 함수 금지

# === 테스트 설정 ===
[tool.pytest.ini_options]
asyncio_mode = "auto"            # async 테스트 자동 감지
testpaths = ["tests"]
addopts = "-v --tb=short"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

uv (매우 추천 & 최신 표준)

uv (차세대 표준)

uv는 Rust로 작성된 초고속 패키지 매니저이다.

pip 대비 10~100배 빠르다고 알려져있어서 Poetry 대안으로 요즘 뜨고있다.

세상 깔끔하다.

주의!
현재 app 폴더를 만들지 않았으므로, 실행 시 발생하는 에러는 정상입니다.
uv run uvicorn app.main:app --reload → 에러

# 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 초기화
uv init practice-api
cd practice-api

# 의존성 추가 (lock 파일 자동 생성)
uv add fastapi "uvicorn[standard]" sqlalchemy asyncpg
uv add --dev pytest ruff mypy

# 실행 (가상환경 자동 생성/관리)
uv run uvicorn app.main:app --reload

# 동기화 (= poetry install)
uv sync

개발 환경 표준화 (생략해도 좋음)

그냥 통상적인 컨벤션이다. 필요 시 더보기를 통해 확인하면 된다.

.editorconfig (= 팀 코딩 스타일 통일)

root = true

[*]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{yml,yaml,json}]
indent_size = 2

pre-commit (= Git 컨벤션)

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.0
    hooks:
      - id: ruff          # 린트
        args: [--fix]
      - id: ruff-format   # 포맷

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.0
    hooks:
      - id: mypy
        additional_dependencies: [pydantic, sqlalchemy[mypy]]

pip install pre-commit
pre-commit install
# 이후 모든 git commit 시 자동으로 린트/포맷/타입체크 실행

VS Code 설정

// .vscode/settings.json
{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.analysis.typeCheckingMode": "strict",
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    }
}

Hello World

이제 진짜 시작해보자. 먼저 다음 두 파일을 생성하자.

app/__init__.py : 빈 파일로 생성한다. (없으면 에러. Python 패키지 선언)
app/main.py

# app/main.py
from fastapi import FastAPI

app = FastAPI(
    title="FastAPI 연습 API",
    version="0.1.0",
    description="FastAPI 연습용 API 스펙",
)

@app.get("/")
async def root():
    return {"message": "Hello, World"}

@app.get("/health")
async def health_check():
    return {"status": "healthy", "service": "practive-api"}

# 실행
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

app.main → app/ 내의 main.py 파일
:app → 그 안의 app 변수 (FastAPI 인스턴스)
--reload → 파일 변경 감지 자동 재시작

브라우저에서 확인해보자. FastAPI는 Swagger가 내장이다.

API: http://localhost:8000/
Swagger UI: http://localhost:8000/docs ← 킬러 기능. 별도 라이브러리 불필요
ReDoc: http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

FastAPI 핵심 개념

깔끔하게 다음에 대해 설명한다. 이 정도만 알아도 FastAPI의 코드를 이해하는데 문제가 없다.

이 글로 3분만에 개념을 날먹해보자.

API(라우팅) 작성 방법
Pydantic
Depends
Annotated

라우팅

기본 CRUD 매핑

전혀 어려울게 없다. 기본적인 구조는 다음과 같다.

@router.{post/get/put/patch/delete}(
	스웨거 명세
)
async def 함수명 (인자) -> 결과타입:
	함수 코드

초보자용 상세설명은 더보기 클릭.

가령 다음을 보자.

# GET — 단건 조회 (Path 파라미터)
@router.get(
    "/{payment_id}", 
    response_model=PaymentResponse,
    status_code=status.HTTP_200_OK,
    responses={
        404: {"description": "없는 결제 내역"},
        422: {"description": "요청 데이터 검증 실패"},
    },
)
async def get_payment(
    payment_id: UUID = Path(..., description="결제 고유 ID"),
    db: DBSession,
    user: AuthUser,
) -> PaymentResponse:
    ...(구현할 코드)...

@router.get() 분석

첫 번째 인자는 api경로이다. /{payment_id}
→ 즉, https://서버주소/{payment_id}로 GET 요청하면 접근 가능하다는 것이다.
→ 결제 ID가 1234-5678-9012-3456이라면? https://서버주소/1234-5678-9012-3456 로 접근하면 된다.
두 번째 인자부터는 의미 없다. 그냥 Swagger 전용 Spec 문서이다.
→ 기본 응답값 200, 그 외에는 상황에 따른 응답값

async def get_payment() -> PaymentResponse 분석

인자는 payment_id, db, user를 받는다.
→ payment_id 는 사용자로부터 받는다.
→ DBSession과 AuthUser는 사용자에게 받지 않고, FastAPI가 자동으로 주입(DI)한다.

DBSession과 AuthUser가 자동 주입되는 것은 현재 이해되지 않는 것이 당연하다.
Depends와 Annotated의 조합형태이다. 본문 하단에 자세히 후술하겠다.
결과 형태는 PaymentResponse이다.
async def get_payment(인자) -> PaymentResponse 형태로 결과 형태를 정의했다.

실전 코드를 보면 이해가 쉬울 것이다.

더보기 없이 아래 코드만 읽어봐도 사용법이 바로 감 잡힐 것이다.

from fastapi import APIRouter, Path, Query, Body, Header, status
from uuid import UUID

router = APIRouter(
    prefix="/api/v1/payments",
    tags=["Payments"],          # Swagger UI에서 그룹핑
    responses={
        401: {"description": "인증 실패"},
        403: {"description": "권한 없음"},
    },
)

# GET — 단건 조회 (Path 파라미터)
@router.get("/{payment_id}", response_model=PaymentResponse)
async def get_payment(
    payment_id: UUID = Path(..., description="결제 고유 ID"),
    db: DBSession,
    user: AuthUser,
) -> PaymentResponse:
    ...

# POST — 생성
@router.post(
    "/",
    status_code=status.HTTP_201_CREATED,
    response_model=PaymentResponse,
    responses={
        409: {"description": "중복 결제 요청"},
        422: {"description": "요청 데이터 검증 실패"},
    },
)
async def create_payment(
    request: CreatePaymentRequest = Body(...),
    idempotency_key: str = Header(..., alias="Idempotency-Key"),
    db: DBSession,
    user: AuthUser,
) -> PaymentResponse:
    ...

와! 당신은 벌써 api를 찍어낼 수 있다!

DB에 데이터 저장하는 방법만 안다면 당신도 지금 해커톤 가능!

(심화 내용 → 지금 이해 안가면 무시하고 넘어가시면 됩니다.)
잠깐! DB 연결을 router(api)에서 인자로 받는다고요?
이러면 api 구현할 때마다 인자에 번거롭게 DBSession을 써야하는데,
실제 로직을 구현할 파일(Service)에서 주입하면 인자도 줄고 좋지 않나요?

충분히 의문이 들 수 있다. 그러나 이는 FastAPI에서 명시성을 위해 의도한 것이다.

여러 관점에서 볼 수 있는데, 필자가 느낀 대표적인 이유는 다음과 같다.

하위 레이어 독립성
생명주기 관점

무슨 뜻인지 상세히 설명하면,

하위 레이어 독립성

(필자가 만든 말이니 검색해도 안나올 수 있다.)

Service에서 아예 FastAPI 의존성을 없앤다는 의미이다. 즉, fastapi를 일체 import하지 않는다.

서비스가 FastAPI를 모르므로 다른 곳(배치, 스크립트)에서 재사용 가능하다.

가령, 스케줄러와 api, 워커 등 다양한 환경을 한 프로젝트에서 구성할 수 있다.

api가 아닌 다른 컨테이너는 fastapi가 필요없다.

개인적으로 이렇게 코드베이스 공유하면서 간단하게 쓸 수 있는게 Python의 치트키같다.

같은 이미지(또는 같은 코드베이스)
- api 컨테이너        → uvicorn main:app
- worker 컨테이너     → celery -A tasks worker
- scheduler 컨테이너  → python jobs/daily_cleanup.py
- migration 컨테이너  → alembic upgrade

생명주기 관점

Depends를 router에서 받으면 요청마다 세션을 만들고, 응답 후 자동으로 닫아줄 수 있다.

즉, 트랜잭션과 요청의 경계가 동일하다.

잠깐, 그럼 응답 전까지 Connection Pool을 그대로 점유한다고요?

필자가 가장 우려한 의문이다.

영속성 컨텍스트가 너무 오래 살아있는거 아닌가? 세션의 수명을 그대로 끌고가면 트래픽이 몰리는 경우 어떻게 대응하는가?

실제로 그렇다. 다만, 커넥션을 View 영역까지 끌고가는 문제부터 말해보면,

Fastapi는 Eventloop 환경 때문에 비동기로 db 세션을 연결한다.

이 때, SQLAlchemy는 기본이 lazy load이므로 비동기에서 문제가 자주 발생한다.

따라서 명시적으로 eager load를 강제하는 경우가 많으므로 뷰에서 N+1 문제가 발생하는 경우는 줄어들긴 한다.

더불어 DTO로 즉시 반환하도록 하면 lazy load가 불가해지므로 대응 가능하다.

문제는 앞서 말한 Connection Pool 문제이다.

여러 방법이 있는데 SessionFactory을 주입해서 아예 세션을 Service에서 열고 닫는 방법도 있다.

이러면 응답 직렬화 시점엔 커넥션이 풀로 돌아간다.

# 세션 팩토리만 주입
@router.get("/users/{id}")
async def get_user(id: int, session_factory = Depends(get_session_factory)):
    return await user_service.get(session_factory, id)

# service
async def get(session_factory, id):
    async with session_factory() as session:
        async with session.begin():
            user = await repo.find(session, id)
    # 여기서 이미 세션/커넥션 반납됨
    return UserDTO.from_orm(user)  # DTO 변환은 세션 밖

근데 그 정도로 코어 시스템이면 그냥 SpringBoot 쓰는 것도 답인 것 같다.

그럼 이렇게 불편하게 살아요?

필자는 아예 다음과 같이 서비스도 Depends로 묶는다. 꽤 흔한 방식이다.

router의 인자에 DBSession 대신 UserServiceDep이 들어가긴 하나,

Service의 각 메서드에서 불필요한 db session을 입력할 필요가 없다.

def get_user_service(session: AsyncSessionDep) -> UserService:
    """Get UserService instance."""
    return UserService(session)

UserServiceDep = Annotated[UserService, Depends(get_user_service)]

@router.post(
    "/",
    response_model=UserResponse,
    status_code=status.HTTP_201_CREATED,
    summary="사용자 생성",
)
async def create_user(
    data: UserCreate,
    service: UserServiceDep,
) -> UserResponse:
    """새로운 사용자 생성"""
    user = await service.create_user(data)
    return UserResponse.model_validate(user)

UserService의 __init__에서 session만 입력받아주면 된다.

class UserService:
    def __init__(self, session: AsyncSession):
        self.repository = UserRepository(session)

    async def create_user(self, data: UserCreate) -> User:
        ...생략...
        return await self.repository.create(user)

라우터 등록 패턴

# app/main.py
from app.domain.payment.router import router as payment_router
from app.domain.account.router import router as account_router
from app.domain.transfer.router import router as transfer_router
from app.domain.auth.router import router as auth_router
from app.domain.admin.router import router as admin_router

# 버전별 그룹핑
app.include_router(payment_router, prefix="/api/v1")
app.include_router(account_router, prefix="/api/v1")
app.include_router(transfer_router, prefix="/api/v1")
app.include_router(auth_router, prefix="/api/v1")

# 관리자 API는 별도 prefix
app.include_router(admin_router, prefix="/api/admin")

Pydantic

더 들어가기 전에 기초 정도는 짚고 넘어가자.

Fastapi를 사용하면 Pydantic 라이브러리가 자주 언급된다.

Pydantic은 Python에서 데이터 검증 + 타입 기반 모델링을 자동으로 처리해주는 라이브러리다.

Python은 기본적으로 타입이 느슨하다.

def func(age):
    return age + 1

func("10")  # 에러 발생

이를 자동으로 처리해주는 라이브러리라고 보면 된다. 기본적으로 BaseModel을 활용한다.

아래 예시를 보면 age를 string 형태로 넣었으나, 자동으로 정수형으로 인식한 것을 알 수 있다.

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    
user = User(name="kim", age="20")
print(user.age)  # 20 (자동 변환됨)

검증도 매우 간편한데 다음과 같은 검증도 지원한다.

gt(Greater Than, 초과), ge(Greater Than or Equal, 이상), lt(Less Than, 미만), le(Less Than or Eqaul, 이하)

from pydantic import BaseModel, Field

class User(BaseModel):
    age: int = Field(gt=0)
    
User(age=-1) # 에러

객체 변환도 간편하다. 딕셔너리 형태를 Unpacking해서 인자로 전달할 수 있다.

JS로 치면 destructing, SpringBoot로 치면 Jackson의 Mapping 느낌?

data = {"name": "kim", "age": 20}

user = User(**data)
print(user.model_dump())  # dict 변환

눈치 챘겠지만 Fastapi의 api 호출에 활용된다.

from fastapi import FastAPI

app = FastAPI()

@app.post("/user")
def create_user(user: User):
    return user

Depends

Depends또한 중요한 핵심 개념으로, 모르면 이해하기 힘들 것이다.

Depends는 DI(의존성 주입)을 진행한다.

다음의 경우, get_user에 대한 반환값을 user에 대입해준다.

def get_user():
    return {"name": "Lee"}

@app.get("/")
def read_root(user = Depends(get_user)):
    return user

결과를 넣어준다면 그냥 함수를 호출하면 될텐데? 왜 쓰는걸까?

가장 큰 이유는 생명주기 관리이다. Depends 없이 직접 DB세션을 호출하는 경우를 보자.

참고: Fastapi에서 DB 연결은 비동기로 처리된다.

@router.get("/users/{id}")
async def get_user(id: int):
    session = await get_session()  # 근데 이거 언제 닫지?
    ...
    await session.close()  # 매번 try/finally로 감싸야 함

Depends는 단순히 함수 결과를 주입하는 게 아니라, 컨텍스트 매니저를 관리한다.

async def get_session():
    async with SessionLocal() as session:
        yield session
    # yield 이후: 요청 끝나면 FastAPI가 자동으로 여기로 돌아와 정리

@router.get("/users/{id}")
async def get_user(id: int, session = Depends(get_session)):
    ...  # 예외 터져도 세션 정리됨

또한 의존성을 자동으로 처리하는데,

아래의 경와 같이 요청 내에서 get_session이 여러 번 필요해도 한 번만 호출하고 캐시한다.

async def get_session():
    async with SessionLocal() as session:
        yield session

async def get_user_repo(session = Depends(get_session)):
    return UserRepo(session)

async def get_post_repo(session = Depends(get_session)):
    return PostRepo(session)

async def get_current_user(
    token: str = Header(...),
    session = Depends(get_session),
) -> User:
    return await session.get(User, decode(token))

@router.post("/posts")
async def create_post(
    body: PostCreate,
    user: User = Depends(get_current_user),
    user_repo: UserRepo = Depends(get_user_repo),
    post_repo: PostRepo = Depends(get_post_repo),
):
    ...

더불어 get_current_user가 없다면 매 첫 줄마다 다음을 입력했어야 한다. 심지어 OpenAPI 스펙에도 반영되지 않는다.

user = await current_user(request.headers["authorization"])

Annotated

그래서 맨날 귀찮게 이렇게 써야할까?

session: AsyncSession = Depends(get_session)

다음과 같이 사전에 정의해두고 재활용할 수 있다.

SessionDep = Annotated[AsyncSession, Depends(get_session)]

세상 깔끔하다. 이제 이렇게 표현할 수 있다.

SessionDep = Annotated[AsyncSession, Depends(get_session)]
CurrentUser = Annotated[User, Depends(get_current_user)]

# routers/users.py
@router.get("/users/{id}")
async def get_user(id: int, session: SessionDep, user: CurrentUser):
    ...

@router.delete("/users/{id}")
async def delete_user(id: int, session: SessionDep, user: CurrentUser):
    ...

다음을 진행하기 전에

Pydantic, Depends 심화

아래 게시글을 읽지 않아도 된다.

그러나, 실전에서 필히 마주칠 문제이므로 익히고 가면 이후 개발이 훨씬 용이할 것이다.

https://leestana01.tistory.com/25

FastAPI 기본부터 극한까지 날먹하기 (Pydantic, Depends 심화)

Discriminated Union만약 결제 수단(카드, 계좌이체, 간편결제)에 따라 요청 구조가 다르다면?Spring에서는 @JsonTypeInfo + @JsonSubTypes를 사용해야 하고, 커스텀 디시리얼라이저를 작성해야 하는 경우도 많

leestana01.tistory.com

SpringBoot 개발자용

SpringBoot 에서 넘어왔다면 다음을 먼저 읽어보자.

Java와 Python 그리고 SpringBoot와 Fastapi를 비교하여 개념을 정리했다.

이것만 읽어도 FastAPI가 훨씬 쉬워질 것이다.

https://leestana01.tistory.com/24

FastAPI 기본부터 극한까지 파보자 (SpringBoot에서 넘어가기)

용어부터 알아보자SpringBoot와 FastAPI는 어떻게 다를까? 기본적인 구조부터 잡고 가면 편할 것 같다.JDK (Java 17/21)Python (3.11/3.12/3.13)Maven / GradlePoetry / uv / pipapplication.yml.env + pydantic-settingsTomcat (내장 서

leestana01.tistory.com

아키텍처 구조

Spring에서는 프로젝트가 무거워질수록, Facade 패턴이 유용하다.

FastAPI에서는 어떤 아키텍처 구조가 좋을까?

Spring에서 Facade가 자연스러운 이유

Spring Boot에서 Facade 패턴이 자연스럽게 작동하는 데에는 프레임워크의 근본적인 구조가 뒷받침된다.

우선, Spring IoC Container가 싱글톤 빈을 관리한다. 무거운 Service 객체들이 애플리케이션 생명주기 동안 한 번만 생성되므로, 여러 Service를 주입받아 조합하는 Facade 클래스가 비용 없이 동작한다.

또한 @Transactional도 AOP 프록시로 동작한다. Facade 메서드에 @Transactional을 선언하면 내부에서 호출하는 모든 Repository 작업이 하나의 트랜잭션으로 묶인다. 이 선언적 트랜잭션 관리가 Facade의 오케스트레이션과 궁합이 맞는다.

FastAPI에서 Facade가 어색한 이유

Python은 근본적으로 다른 언어이다. 우선, 함수가 일급 객체이다.

비즈니스 로직 오케스트레이션을 위해 클래스를 만들 필요가 없다.

async def execute_transfer(...)라는 함수 하나가 오케스트레이터 역할을 완벽히 수행한다.

또한 Spring의 싱글톤 빈과 달리, FastAPI의 Depends()는 매 요청마다 새 인스턴스를 생성한다.

더 중요한건, AOP가 없다. Python에는 @Transactional 같은 것이 없다.

데코레이터로 유사하게 구현할 수 있지만, Spring AOP처럼 프록시 기반이 아니라 함수 래핑이다.

모듈 관점에서 바라봐도 Python에서는 파일 하나에 관련 함수를 모아두는 것이 자연스럽다.

Java: 패키지 → 클래스 → 메서드

Python: 패키지 → 모듈(파일) → 함수/클래스

Facade가 복잡한 비즈니스 로직을 해결하는 본질적 문제는 FastAPI에서도 당연히 존재한다.

다만 해결 형태가 다르다.

Use Case패턴

Use Case의 원칙

하나의 비즈니스 시나리오만 담당
도메인 로직은 Domain Service에 위임
인프라 호출(DB, 외부 API)은 Repository/Client에 위임
Use Case 자체는 "흐름 조율"만 담당

취소나 정산은 별도 Use Case.

도메인 별 디렉토리 구조

app/domain/transfer/
├── __init__.py
├── router.py                    # 라우터 (= Controller)
├── models.py                    # ORM 엔티티 (= JPA Entity)
├── schemas.py                   # 요청/응답 DTO (= Request/Response DTO)
├── enums.py                     # 상태 enum
├── repository.py                # 데이터 접근 (= Repository)
├── exceptions.py                # 도메인 예외
├── use_cases/                   # ← Facade 대신 이것
│   ├── __init__.py
│   ├── execute_transfer.py      # 이체 실행
│   ├── cancel_transfer.py       # 이체 취소
│   └── get_transfer_status.py   # 이체 상태 조회 (단순 조회는 함수로도 충분)
└── services/                    # 도메인 서비스 (순수 비즈니스 로직)
    ├── __init__.py
    ├── fee_calculator.py
    └── limit_checker.py

UseCase 예시

다음 예제를 통해 execute_transfer.py에 대한 Use Case 를 살펴보자.

통상 Use Case는 Class로 선언한 뒤, Annotated 타입으로 깔끔하게 호출한다.

# app/domain/transfer/use_cases/execute_transfer.py

from dataclasses import dataclass
from sqlalchemy.ext.asyncio import AsyncSession

from app.domain.transfer.schemas import TransferCommand, TransferResult
from app.domain.transfer.services.fee_calculator import FeeCalculator
from app.domain.account.repository import AccountRepository
from app.infrastructure.notification.service import NotificationService

@dataclass(frozen=True)
class ExecuteTransferUseCase:
    """
    이체 실행 UseCase.
    """
    db: AsyncSession
    transfer_repo: TransferRepository
    account_repo: AccountRepository
    fee_calculator: FeeCalculator
    notification: NotificationService

    async def execute(self, command: TransferCommand) -> TransferResult:
        ...이체 시도 로직...
        return TransferResult.from_entity(transfer)


# DI 팩토리
from fastapi import Depends
from app.config.database import get_db

def get_execute_transfer_use_case(
    db: AsyncSession = Depends(get_db),
    ...레포 및 서비스 선언...
) -> ExecuteTransferUseCase:
    return ExecuteTransferUseCase(
        db=db,
        ...레포 및 서비스 초기화...
    )

# Annotated 타입으로 깔끔하게
ExecuteTransfer = Annotated[ExecuteTransferUseCase, Depends(get_execute_transfer_use_case)]

Router에서 사용

# app/domain/transfer/router.py
from fastapi import APIRouter, Depends, Header, status
from app.domain.transfer.schemas import TransferCommand, TransferResult
from app.domain.transfer.use_cases.execute_transfer import ExecuteTransfer
from app.domain.transfer.use_cases.cancel_transfer import CancelTransfer
from app.core.security import AuthUser

router = APIRouter(prefix="/transfers", tags=["Transfers"])

@router.post("/", status_code=status.HTTP_201_CREATED)
async def execute_transfer(
    command: TransferCommand,
    use_case: ExecuteTransfer,
    user: AuthUser,
) -> TransferResult:
    """이체 실행"""
    command.idempotency_key = idempotency_key
    command.sender_user_id = user.user_id
    return await use_case.execute(command)

@router.post("/{transfer_id}/cancel")
async def cancel_transfer(
    transfer_id: UUID,
    use_case: CancelTransfer,
    user: AuthUser,
) -> TransferResult:
    """이체 취소"""
    return await use_case.execute(transfer_id, reason, user.user_id)

단순 CRUD는 함수형으로

모든 것을 Use Case 클래스로 만들 필요는 없다. 단순 조회는 함수로 충분하다.

오히려 모든 것을 Use Case로 만드는건 오버엔지니어링일 수 있다.

# app/domain/transfer/use_cases/get_transfer_status.py

from uuid import UUID
from fastapi import Depends
from app.domain.transfer.repository import TransferRepository
from app.domain.transfer.schemas import TransferResponse
from app.domain.transfer.exceptions import TransferNotFoundError

async def get_transfer_status(
    transfer_id: UUID,
    repo: TransferRepository = Depends(get_transfer_repo),
) -> TransferResponse:
    transfer = await repo.find_by_id(transfer_id)
    if not transfer:
        raise TransferNotFoundError(transfer_id)
    return TransferResponse.model_validate(transfer)

# 라우터에서 함수를 직접 호출하거나, 더 간단하게:
@router.get("/{transfer_id}")
async def get_transfer(
    transfer_id: UUID,
    repo: TransferRepository = Depends(get_transfer_repo),
    user: AuthUser,
) -> TransferResponse:
    transfer = await repo.find_by_id(transfer_id)
    if not transfer:
        raise TransferNotFoundError(transfer_id)
    return TransferResponse.model_validate(transfer)

전체 프로젝트 구조

필자는 다음과 같이 프로젝트 구조를 잡아 확장 가능하도록 설계를 마련했다.

프로젝트/
├── pyproject.toml                 # = build.gradle
├── alembic/                       # = DB 마이그레이션
│   ├── alembic.ini
│   └── versions/
├── app/
│   ├── __init__.py
│   ├── main.py                    # = 진입점
│   ├── config/                    # = 설정 폴더
│   │   ├── __init__.py
│   │   ├── settings.py            # = 기본 세팅
│   │   ├── database.py            # = DataSource 설정
│   │   ├── redis.py               # = RedisConfig
│   │   └── logging.py             # = 로깅 설정
│   │
│   ├── core/                      # = 공통 인프라
│   │   ├── __init__.py
│   │   ├── exceptions.py          # = @ControllerAdvice + 커스텀 예외
│   │   ├── security.py            # = SecurityConfig
│   │   ├── middleware.py          # = Filter/Interceptor
│   │   └── dependencies.py        # = 공통 DI 팩토리
│   │
│   ├── domain/                    # = 도메인 레이어
│   │   ├── 특정도메인/               # = 특정 도메인 패키지
│   │   │   ├── __init__.py
│   │   │   ├── router.py          # = API 스펙
│   │   │   ├── service.py         # = 기본적인 스펙
│   │   │   ├── repository.py      # = DB 연동 스펙
│   │   │   ├── models.py          # = DB 모델(Entity) 구현
│   │   │   ├── schemas.py         # = DTO 구현
│   │   │   ├── enums.py           # = 상태 ENUM
│   │   │   └── exceptions.py      # = DomainNotFoundException 등
│   │   │
│   │   └── user/
│   │       └── ...
│   │
│   └── infrastructure/            # = 외부 시스템 연동
│       ├── __init__.py
│       ├── notification/          # = 알림 서비스
│       │   ├── sms.py
│       │   ├── push.py
│       │   └── email.py
│       ├── pg_gateway/            # = PG사 연동
│       │   └── ...
│       └── cache/
│           └── redis_client.py
│
├── tests/
│   ├── conftest.py                # = 공통 테스트
│   ├── unit/
│   │   ├── ...
│   ├── integration/
│   │   ├── ...
│   └── e2e/
│       └── ...
│
├── docker/                        # 귀찮으면 루트에 둠
│   ├── Dockerfile
│   └── docker-compose.yml
│
├── scripts/
│   └── ...
│
└── docs/
    └── api-spec.md

아키텍처 구조

한 페이지에 다 담으려고 했는데, 게시글이 너무 길다..

아키텍처 각각에 대한 구현 방식은 차후 게시글을 따로 작성하여 여기에 링크하겠다.

KVM Netfilter 설정

leestana01 — Sat, 28 Mar 2026 22:34:59 +0900

KVM Machine Netfilter 추가 설정

KVM 머신이 외부와 통신을 하는 상황에서, Bridge 설정 및 포트포워딩을 완료해도 불안정한 상황이 발생하였다.

이미 Host 측에서 Netfilter를 비활성화하였으나, 간헐적으로 통신이 안되는 상황이 발생하였기에 VM 측의 Netfilter를 점검했다.

VM의 Bridge Netfilter 비활성화

점검 결과는 다음과 같았다.

$ cat /proc/sys/net/bridge/bridge-nf-call-arptables
1
$ cat /proc/sys/net/bridge/bridge-nf-call-iptables
1
$ cat /proc/sys/net/bridge/bridge-nf-call-ip6tables
1

값이 1이면 netfilter가 활성화 상태이다.

KVM Bridge에서 netfilter를 비활성화하고 런타임을 변경한다.

echo 0 | sudo tee /proc/sys/net/bridge/bridge-nf-call-arptables
echo 0 | sudo tee /proc/sys/net/bridge/bridge-nf-call-iptables
echo 0 | sudo tee /proc/sys/net/bridge/bridge-nf-call-ip6tables

머신이 재부팅되면 /proc/sys/ 내의 설정이 초기화되므로, /etc/sysctl.conf에 영구 설정을 추가한다.

sudo tee -a /etc/sysctl.conf <<EOF
net.bridge.bridge-nf-call-ip6tables = 0
net.bridge.bridge-nf-call-iptables = 0
net.bridge.bridge-nf-call-arptables = 0
EOF

설정을 다시 로드한다.

sudo sysctl -p /etc/sysctl.conf

설정 적용 원리

시스템을 부팅한다.

init 프로그램이 /etc/sysctl.conf를 불러온다.

/etc/rc.d/rc.sysinit 스크립트가 sysctl을 실행하여 설정을 적용한다.

결과

그래도 SpringBoot의 간헐적 통신 불가능 문제는 바뀌지 않았다.

참고 문헌

Linux Console - Netfilter 설정

KVM Machine Netfilter 추가 설정 2

Host의 브릿지 넷필터를 비활성화 한다.

브릿지 넷필터 비활성화

/etc/sysctl.d/bridge-filter.conf로 저장한다.

net.bridge.bridge-nf-call-ip6tables=0
net.bridge.bridge-nf-call-iptables=0
net.bridge.bridge-nf-call-arptables=0

/etc/udev/rules.d/99-bridge-filter.rules로 저장한다.

ACTION=="add", SUBSYSTEM=="module", KERNEL=="br_netfilter", RUN+="/sbin/sysctl -p /etc/sysctl.d/bridge-filter.conf"

netfilter 모듈이 적재될 때 자동으로 위의 sysctl 설정을 적용하는 udev 규칙이다.

참고 문헌

OSG - 브릿지 넷필터 비활성화

KVM Hypervisor Type 1.5에서 VM 관리

leestana01 — Sat, 28 Mar 2026 21:32:50 +0900

KVM[HyperVisor Type1] 설치

Ubuntu Server 22.04 CLI 환경

KVM 지원 여부 확인

grep -Eoc '(vmx|svm)' /proc/cpuinfo

출력 결과가 0이 아니면 KVM을 지원한다.

KVM을 지원하지 않는 경우, BIOS 설정 문제일 가능성도 높다.

HP 기준 해결 방법

Security > System Security > Virtualization Technology (VTx) 를 Enabled로 설정

패키지 설치

sudo apt install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils virtinst

패키지명	설명
`qemu-kvm`	KVM 하이퍼바이저용 하드웨어 에뮬레이션
`libvirt-daemon-system`	libvirt 데몬 시스템 서비스 구성
`libvirt-clients`	가상화 플랫폼 관리 소프트웨어
`bridge-utils`	이더넷 브리지 구성 명령 줄 도구
`virtinst`	가상 머신 생성 명령 줄 도구

virt-manager를 제외한 이유
CLI 환경에서만 작업하므로, virt-manager는 사용이 제한됨. 따라서 설치 대상에서 제외

설치 완료 확인

kvm 설치 확인

$ kvm --version
QEMU emulator version 6.2.0 (Debian 1:6.2+dfsg-2ubuntu6.15)
Copyright (c) 2003-2021 Fabrice Bellard and the QEMU Project developers

설치 후 추가 작업

그룹에 사용자 추가

sudo usermod -aG libvirt $USER
sudo usermod -aG kvm $USER

서비스 시작 및 활성화

sudo systemctl enable --now libvirtd

게스트 OS 생성

virt-install \
  --name [가상머신 이름] \
  --ram [메모리 크기] \
  --disk path=[디스크 경로],size=[디스크 크기] \
  --vcpus [CPU 수] \
  --os-type [OS 타입] \
  --os-variant [OS 버전] \
  --network bridge=virbr0 \
  --graphics none \
  --console pty,target_type=serial \
  --location '[OS 설치 이미지 경로]' \
  --extra-args 'console=ttyS0,115200n8 serial'

--network bridge=virbr0 : 가상 머신이 호스트 시스템의 virbr0 브리지로 연결되도록 함
--graphics none : CLI 환경이므로 그래픽 출력 비활성화
--extra-args 'console=ttyS0,115200n8 serial' : 해당 머신의 화면 정보를 시리얼 콘솔로 전달

예시

sudo virt-install \
  --name myvm \
  --vcpus 2 \
  --ram 2048 \
  --os-variant ubuntu20.04 \
  --location 'http://archive.ubuntu.com/ubuntu/dists/focal/main/installer-amd64/' \
  --network bridge=virbr0,model=virtio \
  --graphics none \
  --extra-args='console=ttyS0,115200n8 serial'

기타 게스트 OS 관리

virsh start [가상머신 이름]      # 시작
virsh shutdown [가상머신 이름]   # 정지
virsh reboot [가상머신 이름]     # 재시작
virsh list --all                 # 게스트 상태 확인

KVM에서 VM 생성 (접속 불가 오류 해결 포함)

KVM으로 VM을 생성하면 Escape character is ^] (Ctrl + ]) 이후에 진행이 안되는 문제가 발생한다.
해외 사이트에도 방안이 나와있지 않아 직접 연구하여 서술한다.

VM 생성

예시를 참고하여 VM을 생성한다. 현재 생성한 방법은 다음과 같다.

name : DNSserv
disk : 논리 디스크 경로 (LVM 파티션을 따로 생성하였음)

virt-install \
  --name DNSserv \
  --ram 2048 \
  --vcpus 2 \
  --os-variant ubuntu20.04 \
  --disk path=/dev/ubuntu-vg/kvmvol1,bus=virtio,size=10 \
  --network bridge=virbr0,model=virtio \
  --graphics none \
  --location 'http://archive.ubuntu.com/ubuntu/dists/focal/main/installer-amd64/' \
  --extra-args 'console=ttyS0,115200n8 serial'

참고 — Logical Volume 생성

sudo vgscan                                          # Volume Group 확인
sudo vgdisplay 해당그룹                               # 여유 공간 확인
sudo lvcreate -n 새볼륨명 -L 10G 해당그룹              # 새 논리 볼륨 생성
sudo mkfs.ext4 /dev/해당그룹/새볼륨명                   # 파일 시스템 생성

설치 진행

Go Back 선택

Download installer components 선택

기본 설정

기본적인 설정을 진행한다. 설치를 위한 기본 필드이므로, 안내에 따라 진행한다.

Hostname
Ubuntu Archive 미러 도메인 설정
소유주명
계정명 / 계정 비밀번호 설정

설정을 마치면 다시 처음 본 창이 뜬다. Go back 선택

SSH 설정을 위한 세팅

CLI 환경에서 접속 불가한 VM 머신에 연결하도록 미리 OpenSSH Server를 구동시킨다.

Select and install software 선택

이후 파티션 설정 및 PAM 설정을 진행한다.

참고 — 파티션 설정 선택지

선택지 설명

Guided - resize Virtual disk 1 (vda) and use freed space 기존 OS/데이터가 있는 디스크에서 추가 공간을 만들 때 유용. KVM 인스턴스에는 비적합

Guided - use entire disk 디스크 전체 사용

Guided - use entire disk and set up LVM 전체 디스크 사용 + LVM 설정. 추후 파티션 크기 조정·스냅샷 등 필요 시

Guided - use entire disk and set up encrypted LVM LVM + 디스크 전체 암호화

Manual 수동 파티셔닝. 파티션 크기·파일 시스템 유형·마운트 포인트 등 직접 설정

선택지	설명
Guided - resize Virtual disk 1 (vda) and use freed space	기존 OS/데이터가 있는 디스크에서 추가 공간을 만들 때 유용. KVM 인스턴스에는 비적합
Guided - use entire disk	디스크 전체 사용
Guided - use entire disk and set up LVM	전체 디스크 사용 + LVM 설정. 추후 파티션 크기 조정·스냅샷 등 필요 시
Guided - use entire disk and set up encrypted LVM	LVM + 디스크 전체 암호화
Manual	수동 파티셔닝. 파티션 크기·파일 시스템 유형·마운트 포인트 등 직접 설정

참고 — PAM(자동 업데이트) 설정 선택지

선택지 설명

No automatic updates 모든 업데이트를 수동으로 관리

Install security updates automatically 보안 업데이트만 자동 설치. 취약점에 신속 대응

Manage system with Landscape Canonical의 Landscape를 통해 웹에서 중앙 관리. 대규모 배포에 유용

선택지	설명
No automatic updates	모든 업데이트를 수동으로 관리
Install security updates automatically	보안 업데이트만 자동 설치. 취약점에 신속 대응
Manage system with Landscape	Canonical의 Landscape를 통해 웹에서 중앙 관리. 대규모 배포에 유용

위의 창이 뜨면 다음을 선택하여 설치한다.

OpenSSH server
Basic Ubuntu server

이후 GRUB 부트 로더를 설치한다.

설치 완료

에러 발생

막상 설치가 완료되어도 Escape character is ^] (Ctrl + ]) 에서 아무 반응이 없을 것이다.

에러 해결

VM의 IP 확인

연결된 VM의 IP를 확인한다. 여기서는 192.168.122.115이다.

SSH 접속

접속이 된다. 그러나 이는 임시방편이므로, virsh console이 작동되게 해야 한다.

grub 설정 편집

nano /etc/default/grub

변경 전

변경 후

다음과 같이 변경한다.

GRUB_CMDLINE_LINUX_DEFAULT="console=tty0 console=ttyS0"

마무리

다음의 명령어를 순차적으로 입력한다.

update-grub
systemctl enable serial-getty@ttyS0.service
systemctl start serial-getty@ttyS0.service

이후 쉘에서 탈출한다.

접속 시도

virsh console 머신이름

이로서 VM 생성이 완료된다.

KVM Network Bridge 설정 (VM당 개별 IP 할당)

KVM의 VM을 위해서 Bridge를 설정할 때, VM에서 Bridge 설정이 제대로 되지 않는다.
이 역시도 해외 사이트를 검색해도 정보가 나오지 않는다.

현재 네트워크 인터페이스 확인

ip a

본문에서는 eno1 인터페이스를 가정하여 서술한다.

Bridge 설정

sudo vi /etc/netplan/파일명.yaml

사용 환경

라우터 : 192.168.1.1

IP 대역 : 192.168.1.X

DHCP : 192.168.1.11 ~ 199

VM 머신 : 192.168.1.2 ~ 192.168.1.10 범위 내에서 설정

eno1 인터페이스에 대해 bridge를 설정한다. bridge의 이름은 br0으로 설정하였다.

다만, 호스트의 고정 IP 설정을 원한다면 다음과 같이 설정한다.

sudo netplan apply

이로서 호스트의 bridge 설정이 완료된다.

VM의 bridge 연결

virsh edit VM이름

<devices> 태그 내에서 <interface> 영역을 수정한다.

기본 설정은 nat 방식으로 되어있는데, <interface>와 <source>를 bridge로 변경해준다.

virsh reboot VM이름

이로서 VM의 bridge 설정이 완료된다.

VM 내에서 IP 설정

VM 내부에서도 netplan 설정을 해준다.

virsh console VM이름                      # VM 진입
sudo vi /etc/netplan/파일명.yaml           # netplan 설정

만약 DHCP로 할당받기 원한다면 dhcp4: yes로 설정한다.

sudo netplan apply

이로서 VM 내부의 bridge IP 설정이 완료된다.

버그 발생

이 상태에서 통신을 시도하면, VM이 Host와는 ping으로 통신이 원활하나 Router 및 외부와는 통신이 불가하다. 이 문제는 여러 곳에서도 보고되나 해결 방안이 제시된 곳이 없다.

leesh@lshserv:~$ arp -a
? (192.168.1.3) at 52:54:00:ee:5d:6e [ether] on virbr0
_gateway (192.168.1.1) at bc:62:ce:2a:91:8c [ether] on virbr0

Host의 bridge 할당을 확인해보았으나 문제가 없었고, 공유기 설정에서도 VM에 IP를 제대로 할당하였다.

dnsserv@dnsserv:/etc/netplan$ sudo tcpdump -i enp1s0
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on enp1s0, link-type EN10MB (Ethernet), capture size 262144 bytes
11:09:54.530661 STP 802.1d, Config, Flags [none], bridge-id 8000.4e:8d:53:35:f2:bf.8002, length 35
11:09:55.249151 IP 192.168.1.3.45126 > 8.8.8.8.domain: Flags [S], seq 2656147049, win 64240, ...
11:09:56.546801 STP 802.1d, Config, Flags [none], bridge-id 8000.4e:8d:53:35:f2:bf.8002, length 35
11:09:58.193223 IP 192.168.1.3.53194 > 8.8.8.8.domain: Flags [S], seq 1669409495, win 64240, ...
11:09:58.530844 STP 802.1d, Config, Flags [none], bridge-id 8000.4e:8d:53:35:f2:bf.8002, length 35

tcpdump 확인 결과, VM이 공유기에 IP 요청을 원활히 하였으나 응답이 없다. 패킷이 Host를 통해 지나가는 과정에서 Router로부터의 응답이 차단된 것으로 판단하여, Host단의 문제로 가정하고 원인을 파악했다.

버그 해결

넷필터 모듈 확인 :

lsmod | grep br_netfilter

브릿지 네트워크 트래픽 처리 모듈(br_netfilter)이 적재되어있는지 확인한다.

해당 모듈을 비활성화하고, 재부팅 시 자동 적재를 방지한다.

sudo rmmod br_netfilter
echo "blacklist br_netfilter" | sudo tee -a /etc/modprobe.d/blacklist.conf

참고 문헌

DNS 네임서버 구축 및 API를 통한 자동화 관리 올인원

leestana01 — Wed, 25 Mar 2026 18:35:09 +0900

설계목표

- 네임서버를 구축한다.
- 네임서버를 API를 통해 편하게 관리한다.
- API를 통해 DNS 레코드 및 Redirection을 관리한다.

참고사항

- 네임서버는 API를 제공하지 않는다.
- 네임서버는 Redirection을 지원하지 않는다.

- AI도 할 줄 모른다... 이 글 학습하면 앞으로 가능할듯

DNS 조회 원리

다음 이미지로 대체한다.

중요한 것은 우리 네임서버(klr.kr)를 TLD에 등록하여, 쿼리 가능하도록 해야한다는 점이다.

DNS 서버 설정(Bind9)

목표 : DNS 서버를 구축한다.

bind9 설치

sudo apt install bind9

/etc/bind/named.conf.local 수정

내 네임서버를 정의하고, 레코드 설정을 기록할 경로를 입력한다.

Zone 파일은 밑에서 설명하겠다.

zone "klr.kr" {
    type master;
    file "/etc/bind/zones/db.klr.kr"; # Zone 파일 경로
};

Zone 설정

1. /etc/bind/zones 폴더 생성

2. /etc/bind/zones/db.klr.kr 생성

이후 편리한 설정을 위해 db.local 을 복사한다.

sudo cp db.local ./zones/db.klr.kr

해당 파일을 열어 아래와 같이 도메인(klr.kr) 및 네임서버 ip를 일치시킨다.

;
; BIND data file for local loopback interface
;
$TTL    604800
@       IN      SOA     ns1.klr.kr. admin.klr.kr. (
                              2         ; Serial
                         604800         ; Refresh
                          86400         ; Retry
                        2419200         ; Expire
                         604800 )       ; Negative Cache TTL
; Name Server Info
@       3600    IN      NS      ns1.klr.kr.
; Name Server A record
ns1     IN      A       203.253.76.163

@       IN      A       203.253.76.163
a       IN      CNAME   google.com.
b       IN      A       158.180.67.189

문법을 상세히 알고싶다면? 아래 더보기

설정 내용 설명

위 문법이 뭔지도 모르고 그냥 따라하면 찝찝하다. 각각을 명확히 알아보자.

$TTL 604800 : DNS 레코드가 캐시될 시간을 초단위로 지정 (1주일로 지정됨)

상기된 레코드는 다음과 같이 분류된다.

A, CNAME은 다들 알텐데, SOA와 NS는 생소할 수 있다.

SOA	NS	A	CNAME
도메인 기본 설정	네임서버 정보	IP 주소 안내	도메인 주소 별칭

차례로 분석해보면 다음과 같다

@	IN	SOA	ns1.klr.kr.	admin.klr.kr.
현재 영역 이름 (klr.kr	인터넷 클래스	Start of Authority 시작 권한 레코드	주 네임서버	도메인 관리자 메일 주소 (실제로 @는 .으로 대체됨)

Serial	영역 파일 버전 일련번호 DNS 설정 변경시마다 증가해야 함
Refresh	보조 네임서버가 주 네임서버에 변경사항 확인하는 주기
Retry	주 네임서버 연결 실패시 재시도할 시간 간격
Expire	보조 네임저버가 주 네임서버와 연결하지 못할 때 정보유지 기간
Negative Cache TTL	존재하지 않는 레코드에 대한 응답을 캐시하는 시간

(선택) 정의되지 않은 DNS 매핑

특정 PC/서버에서 DNS를 이 네임서버로만 가리키고 싶은 경우,

현재 서버에는 다른 DNS 정보가 없기 때문에 구글,네이버 등의 외부 사이트 쿼리에 실패한다.

일반적으로 네임서버 여기 하나만 쓸 일은 없을테니 안해도 된다.

/etc/bind/named.conf.options 파일에서 다음을 추가한다.

forwarders {
    8.8.8.8;
    8.8.4.4;
};
allow-query { any; };

수정사항 반영

# 방법 1(추천) - 변경사항만 반영
rndc reload 

# 방법 2 - bind9 재시작
sudo systemctl restart bind9

DNS 테스트

dig a.klr.kr @localhost
dig b.klr.kr @localhost
#또는 nslookup b.klr.kr

오류가 발생한 경우? 아래 더보기

오류 발생 시

다음을 입력해 오류 발생 지점 확인 가능

named-checkzone [영역 이름] [영역 파일 경로]

예)

sudo named-checkzone klr.kr /etc/bind/zones/db.klr.kr

당장 내 컴퓨터에서 네임서버에 접근 가능한지 보고 싶다면?

(개별 클라이언트) DNS 연동

별거 없다. 그냥 클라이언트 네임서버 주소 변경이다.

아직 TLD에 네임서버를 등록하지 않아서 외부에서는 네임서버를 알아볼 수 없다.

이 방식은 임의로 클라이언트에서 네임서버를 현재 서버로 지정하여 접속 가능하게 한다.

이 설정은 개별 클라이언트에 적용되므로, 범용적이지 않다.

방법 1

neplan에서 nameserver를 공인 ip로 설정한다.

그냥 보면 알 수 있다. 별도 설명은 하지 않겠다.

방법 2

일시 변경 : sudo vi /etc/resolv.conf 에 다음을 추가한다.

nameserver [ip주소]

영구 변경 : sudo vi /etc/resolvconf/resolv.conf.d/head 에 다음을 추가하고 재부팅한다.

nameserver [ip주소]

이로써 매우 간단하게 네임서버 구축을 완료하였다.

DNS TLD에 공개

목표 : DNS 서버를 외부에 공개하여, 모든 클라이언트에서 DNS 쿼리를 가능하게 한다.

사설 보안망 구축이 아닌 이상, 외부에서 쿼리도 못하는 네임서버는 반쪽짜리 네임서버다.

호스트 등록

네임서버를 TLD 수준에 등록한다.

네임서버 변경

등록한 네임서버로 도메인을 연동한다.

.com과 .net : 3~4 시간 (실시간 루트 네임서버 변경)
.kr (한국인터넷진흥원) : 약 1일 소요
- 전일 18:00 ~ 금일 08:00 변경 건 : 금일 08:20 업데이트
- 금일 08:00 ~ 금일 12:00 변경 건 : 금일 12:20 업데이트
- 금일 12:00 ~ 금일 18:00 변경 건 : 금일 18:20 업데이트
.us .cn .jp .in : 약 1일 소요
.biz .info .org : 3~4시간 (실시간 루트 네임서버 변경)

변경된 네임서버 확인

https://www.whatsmydns.net/

DNS Propagation Checker - Global DNS Checker Tool

Instant DNS Propagation Check. Global DNS Propagation Checker - Check DNS records around the world.

www.whatsmydns.net

Nginx 기반 리다이렉트 진행

목표 : 내 DNS 서버가 Redirection까지 지원하도록 설계한다.

내가 만든 사이트를 내 도메인을 활용해 단축 URL을 만들고 싶지 않은가?

안타깝게도 이 방법을 서술한 블로그는 전혀 보이지 않는다.

Nginx 를 활용해 응용해보자. 필자는 다음과 같은 리디렉션 방식을 설계했다.

1. 사용자가 특정 서브도메인(a.klr.kr)에 대한 리디렉션(naver.com) 추가를 요청한다.

2. 서브도메인(a.klr.kr)은 네임서버(1.2.3.4)를 가리킨다.

3. 네임서버의 80 포트는 Nginx이므로, Nginx에서 해당 리디렉션을 안내한다.

원하는 서비도메인은 Bing9에서 직접 네임서버를 가리키도록 추가하고,

이후 Nginx가 신경써야할 부분은 위 3번이다.

NginX 설치

sudo apt update
sudo apt install nginx

conf 파일 수정

DNS 서버가 단독으로 공인 ip를 지닌 경우

map $host $redirect_destination {
        hostnames;
        입력주소 http://연결대상주소;
        입력주소2 http://연결대상주소2;
                ...
}

server {
        listen 80;
        server_name _;

        location / {
                if ($redirect_destination) {
                        return 301 $redirect_destination$request_uri;
                }
        }
}

내 네임서버가 다른 VM(인스턴스)와 공인 ip를 공유하나요?

= HyperVisor 환경에서 "네임서버"와 "웹 서버"를 격리된 인스턴스로 운용중이라면?

아래 더보기

DNS 서버가 다른 VM(인스턴스)와 공인 ip를 공유하는 경우

필자와 같이 KVM 등으로 DNS VM을 별도로 구축한 경우, Redirect 대상이 아닌 모든 요청은 웹서버 VM으로 다시 빠져야한다.

안그러면 웹 서버에 접근이 안된다.

map $host $redirect_destination {
        hostnames;
        입력주소 http://연결대상주소;
        입력주소2 http://연결대상주소2;
                ...
}

server {
        listen 80;
        server_name _;

        location / {
                if ($redirect_destination) {
                        return 301 $redirect_destination$request_uri;
                }

                proxy_pass http://웹서버VM주소;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }
}

이상으로 설정을 마치면 된다.

DNS 세팅 API 자동화 - Bind9 자동화

목표 : DNS 및 리디렉션을 자동화 하는 API 서버를 구축한다.

클라우드 서비스 (AWS EC2)	OnPremise
우측 이미지에서 녹색 영역만 보면 된다.

위와 같은 형태로 제작하는 것을 목표로 한다.

개인적으로 창의적인 방법을 고안하여 생각한 방법이므로,

더 좋은 방법이 있는지 알아볼 필요가 있음

Bind9 설정

bind의 zone 영역은 include가 불가능하다. 따라서 이를 스크립트화 시킬 것이다.

change_record.sh

ZONES_DIR="/etc/bind/zones/list_dns"
ZONE_FILE="/etc/bind/zones/zone파일명"

cat > $ZONE_FILE <<EOF
;
; BIND data file for local loopback interface
;
\$TTL    300
@       IN      SOA     네임서버. 메일주소. (
                              2         ; Serial
                          86400         ; Refresh
                           7200         ; Retry
                        2419200         ; Expire
                          86400 )       ; Negative Cache TTL
; Name Server Info
@       3600    IN      NS      네임서버.
; Name Server A record
ns1     IN      A       네임서버ip
@       IN      A       네임서버ip

EOF

for file in $ZONES_DIR/*; do
        cat $file >> $ZONE_FILE
        #echo "" >> $ZONE_FILE
done

add_record.sh

FILE_PATH="/etc/bind/zones/list_dns/$1"

if [ -f "$FILE_PATH" ]; then
            rm "$FILE_PATH"
fi

echo "$1        IN      $2      $3" > "$FILE_PATH"

sudo /etc/bind/zones/change_record.sh

sudo rndc reload

del_record.sh

FILE_PATH="/etc/bind/zones/list_dns/$1"

if [ -f "$FILE_PATH" ]; then
            rm "$FILE_PATH"
fi

sudo /etc/bind/zones/change_record.sh

sudo rndc reload

DNS 레코드 한번에 관리

이후 /etc/bind/zones/에 list_dns 폴더를 제작한다.

sudo mkdir list_reidrects

예)

/etc/bind/zones/list_dns/example1 의 내부 내용

example1        IN      A      1.2.3.4

/etc/bind/zones/list_dns/example2 의 내부 내용

example2        IN      A      5.6.7.8

위와 같이 모든 서브도메인을 파일로 관리한 뒤, 앞으로 api를 요청 받으면 해당 폴더에
[서브도메인] [레코드명] [대상주소]를 담은

[서브도메인] 파일을 제작하기 위함이다.

이제 api를 요청 받으면 서버는 다음과 같이 파일을 실행하면 된다.

/etc/bind/zones/add_record.sh [서브도메인] [레코드명] [대상주소]

DNS 세팅 API 자동화 - Nginx 자동화

자동화를 위해 Nginx의 리디렉션 경로들도 위와 같이 파일로 관리한다.

파일로 관리하기 위해 Nginx의 conf 파일에서

"입력주소 http://연결대상주소" 형태의 목록을 include로 대체한다.

/etc/nginx/conf.d/redirect.conf

map $host $redirect_destination {
        hostnames;
        include /etc/nginx/conf.d/list_redirects/*; # 이 부분을 수정한다
}

server {
        listen 80;
        server_name _;

        location / {
                if ($redirect_destination) {
                        return 301 $redirect_destination$request_uri;
                }

                proxy_pass http://웹서버VM주소;
                proxy_set_header Host $host;
                proxy_set_header X-Real-IP $remote_addr;
                proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                proxy_set_header X-Forwarded-Proto $scheme;
        }
}

이후 /etc/nginx/conf.d/에 list_redirects 폴더를 제작한다.

sudo mkdir list_reidrects

예) /etc/nginx/conf.d/list_redirects/example1 의 내부 내용

example1.test.com https://naver.com

이는 앞으로 api를 요청 받으면 해당 폴더에

[요청 서브도메인 주소] [리다이렉트 주소] 를 담은

[서브도메인] 파일을 제작하기 위함이다.

add_redirects.sh

DOMAIN_NAME=".도메인주소"
FILE_PATH="/etc/nginx/conf.d/list_redirects/$1"

if [ -f "$FILE_PATH" ]; then
            rm "$FILE_PATH"
fi

echo "$1$DOMAIN_NAME $2" > "$FILE_PATH"

sudo /etc/bind/zones/add_record.sh $1 A 네임서버ip

sudo nginx -s reload

del_redirects.sh

FILE_PATH="/etc/nginx/conf.d/list_redirects/$1"

if [ -f "$FILE_PATH" ]; then
            rm "$FILE_PATH"
fi

sudo /etc/bind/zones/del_record.sh $1

sudo nginx -s reload

이제 api를 요청 받으면 다음과 같이 실행한다.

/etc/nginx/conf.d/add_redirects.sh [서브도메인] [대상주소]

DNS 세팅 API 자동화 - API를 통해 DNS, Nginx 관리 자동화

목표 : API를 통해 "서브도메인과 레코드" 또는 "리디렉션 주소"를 정하면, 해당 세팅을 자동화하는 서버 제작

이 페이지에서는 DNS 서버의 SpringBoot영역을 구성하고 마무리한다.

DTO

요청 받을 정보들을 담을 DTO를 먼저 처리한다.

이 Application을 DB 저장을 하지 않고 process만 처리하므로, Entity는 생성하지 않는다.

DNSRecordDTO

@Data
public class DNSRecordDTO {
    // 양식
    // subdomain    A   1.2.3.4
    // subdomain    CNAME   example.com. (뒤에 온점)
    private String subdomain;
    private String record;
    private String targetAddress;
}

RedirectDTO

@Data
public class RedirectDTO {
    private String subdomain;
    private String targetAddress;
}

DeleteDomainDTO

@Data
public class DeleteDomainDTO {
    private String subdomain;
}

Service

DTO를 기반으로 ‘Record, Redirection 생성 및 삭제’을 위해 생성해두었던 ~.sh를 실행시킨다.

@Service
public class DnsService {

    private void executeScript(String scriptPath, String... args){
        try {
            List<String> command = new ArrayList<>();
            command.add("sudo");
            command.add(scriptPath);
            Collections.addAll(command, args);

            ProcessBuilder processBuilder = new ProcessBuilder(command);
            Process process = processBuilder.start();
            process.waitFor();
        } catch (Exception e) {
            throw new NotRunnableException(scriptPath);
        }
    }
    public void addDNSRecord(DNSRecordDTO dnsRecordDTO){
        String targetAddress = dnsRecordDTO.getTargetAddress();
        if(dnsRecordDTO.getRecord().equals("CNAME")){
            targetAddress = targetAddress+ ".";
        }
        executeScript("/etc/bind/zones/add_record.sh", dnsRecordDTO.getSubdomain(), dnsRecordDTO.getRecord(), targetAddress);
    }

    public void addRedirect(RedirectDTO redirectDTO){
        executeScript("/etc/nginx/conf.d/add_redirects.sh", redirectDTO.getSubdomain(), redirectDTO.getTargetAddress());
    }

    public void delDomain(String subDomain){
        executeScript("/etc/nginx/conf.d/del_redirects.sh", subDomain);
    }
}

Exception

Service에서 생성한 Exception을 정의한다

public class NotRunnableException extends RuntimeException{
    public NotRunnableException(String filepath){
        super("파일 실행에 실패함: "+filepath);
    }
}

Controller

일반 Controller

Service를 바탕으로, 이를 호출한다.

@RestController
@RequiredArgsConstructor
@RequestMapping("/v1")
public class DnsController {

    private final DnsService dnsService;

    @PostMapping("/records")
    public ResponseEntity<?> addDNSRecord(@RequestBody DNSRecordDTO dnsRecordDTO){
        dnsService.addDNSRecord(dnsRecordDTO);
        return ResponseEntity.status(HttpStatus.OK).build();
    }

    @PostMapping("/redirects")
    public ResponseEntity<?> addRedirects(@RequestBody RedirectDTO redirectDTO){
        dnsService.addRedirect(redirectDTO);
        return ResponseEntity.status(HttpStatus.OK).build();
    }

    @DeleteMapping("/subdomain/{subdomain}")
    public ResponseEntity<?> delDomain(@PathVariable String subdomain){
        dnsService.delDomain(subdomain);
        return ResponseEntity.status(HttpStatus.OK).build();
    }
}

예외 처리 Controller

발생시킨 Exception에 대한 Response를 정의한다.

@ControllerAdvice
public class ExceptionHandlerControllerAdvice {

    @ExceptionHandler({NotRunnableException.class})
    public ResponseEntity<?> handleNotRunnableException(NotRunnableException e){
        System.out.println(e.getMessage());
        return new ResponseEntity<>(e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

마치며

주변에서도 유사한 서비스를 구현하고 싶은데, 방법을 몰라 구축을 못한 사례들이 종종 있었다.

게시글도 없고, AI도 해결을 못해서 어려운게 아닐까 싶다.

이러한 서비스 구축을 희망하는 이들에게 도움이 되길 바란다.

참고 문헌

https://m.blog.naver.com/love_tolty/222690840923

https://dev.dwer.kr/2020/04/bind-9.html

아래는 DNS 갱신시간 관련 Webtizen 설명

https://www.webtizen.co.kr/support/faq/cs_faq_view?uid=2&vid=27&rm=50&this_page=6

내부망 구성하기 (개정판)

leestana01 — Mon, 23 Mar 2026 18:14:48 +0900

개발서버 분리를 위해 VPN 환경에서만 접근 가능한 내부 망을 구성한다.

서론

과거에는 너무 엄격하게 한 나머지, DNS 쿼리를 해도 내부망에 접근 못하게 구성했다.

VPN으로 접근된 트래픽을 Squid 를 통해 Proxy를 구성하고, HTTPS를 MITM시켜 구성했다.
그런데 네이버, 구름 등 대기업들도 이렇게까진 하지 않더라...

이전에 정리한 게시글(https://leestana01.tistory.com/6)이 있는데, 너무 과거 회고에 가깝다.

그래서 내부망 구성 방식을 보기좋게 다시 고안하고 정리한다.

설계 목표

- 인가되지 않은 외부인의 개발 리소스 접근을 일체 금지한다.
- 내부 리소스의 모든 접근은 VPN을 이용해 접근해야한다.

하단에 기술할 구성 방법은 본인이 직접 구상하여 설계한 것으로,
더 좋은 실무적 방법이 있는 경우 공유해주시면 감사할 듯 하다.

방법 1 - Ingress에서 차단하기

결론적으로 이 방식을 사용중이다. 매우 간단한데, 매우 확실하다.

개인적인 우려가 있다면 굳이 ingress까지 트래픽이 한 번 타고 가야한다는 점이다.

externalTrafficPolicy 변경

우선, 사용자가 VPN 환경에서 접속했는지 Client-IP를 확인해야한다.

그러나 기존 `externalTrafficPolicy: Cluster`에서는 ingress-nginx가 실제 클라이언트 IP를 볼 수 없다.

→ 모든 트래픽이 kube-proxy를 거쳐 노드 IP로 변환되기 때문

조금 더 상세히 설명하면 다음과 같이 SNAT이 발생하여, Client-IP가 유실된다.
Client → Node A → (kube-proxy) → Node B의 Pod

다음과 같이 Local로 변경 가능하다.

(주의 : kubectl 직접 패치이므로 ingress-nginx Helm 재설치 시 재적용 필요!)

kubectl patch svc ingress-nginx-controller -n ingress-nginx \
-p '{"spec":{"externalTrafficPolicy":"Local"}}'

환경 분석

VPN 환경이 다음과 같다고 가정하자.

- VPN: WireGuard (wg-easy)
- 클라이언트 서브넷: `10.8.0.0/24`
- VPN pod IP: `10.0.10.51` (node 10.0.10.220)

트래픽 경로는 다음과 같을 것이다.

externalTrafficPolicy: Cluster 라면 어떻게 되나요?

VPN 클라이언트 (10.8.0.x)
→ WireGuard 터널
→ VPN pod (MASQUERADE → 10.0.*.*)
→ NAT Gateway (SNAT → 152.69.*.*)
→ OCI LB (168.107.*.*)
→ kube-proxy (SNAT → 노드 IP)
→ ingress-nginx (sees: 노드 IP)

VPN 클라이언트 (10.8.0.x)
→ WireGuard 터널
→ VPN pod (MASQUERADE → 10.0.*.*)
→ 목적지: dev.notinoty.kr = 168.107.*.* (OCI LB)
→ OCI 내부 라우팅 (같은 VCN이므로 NAT Gateway 미경유, SNAT 없음)
→ OCI LB (168.107.*.*)
→ ingress-nginx (sees: 10.0.*.*) ← VPN Pod IP 그대로 보존

즉, VPN 트래픽의 source IP = VPN pod (10.0.*.*) 이다.

Ingress 수정

이후 각 프로젝트의 gitops(kustomization.yaml)의 기존 patches에 overlay로 다음을 추가한다.

(혹시 몰라 SNAT을 고려하여 NAT 주소까지 추가했다.)

patches:
# 기존 patches에 추가
- patch: |-
- op: add
path: /metadata/annotations/nginx.ingress.kubernetes.io~1whitelist-source-range
value: "10.0.*.*/32,152.69.*.*/32"

target:
kind: Ingress

gitops가 아닌 자체 배포를 사용중이라면, ingress에 annotaion을 직접 추가하면 된다.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress이름
annotations:
nginx.ingress.kubernetes.io/whitelist-source-range: "10.0.*.*/32,152.69.*.*/32"
spec:
...(생략)...

방법 2 - DNS에서 차단하기

역시나 매우 간단하다. k8s의 해당 Service주소를 DNS로 가리키면 된다.

다만, DNS-01 방식을 통해 인증해야한다는 점이 치명적인 단점이다.

DNS-01은 txt 기반으로 인증된다.

DNS Provider API가 없다면 인증서를 매번 수동 갱신해야한다. (네임서버에서 txt 직접 수정해야함)

DNS Provider API는 보통 다음을 지원한다.

Cloudflare
Route53
Google DNS

필자는 호스팅케이알을 이용중이므로, 적합하지 않다고 판단했다.

지원되는 환경이라면 와일드카드 지원을 포함하여 꽤 유용하다고 생각한다.

심지어 트래픽을 DNS 수준에서 걸러버릴 수 있다.

간단해서 여기에 방법은 기재하지 않는다.

방법 3 - 외부에서 존재조차 모르게 차단하기

방법이 너무 복잡하므로, 아래 이미지로 갈음한다.

과거에 직접 구성했던 VPN 환경을 이미지로 표현한 것이다.

사실상 필요한 내용이 모두 담겨있다.

다만, Squid 설정이 인터넷에도 없고 AI도 제대로 구성 못한다. 부딪히면서 공부하는게 답이다.