경로 동작 데코레이터의 의존성

경로 동작 데코레이터의 의존성 (Dependencies in path operation decorators)

어떤 경우에는 의존성의 반환값을 경로 동작 함수 안에서 전혀 쓸 필요가 없어요. 또는 의존성이 아예 값을 반환하지 않을 수도 있어요. 그런데도 그 의존성이 실행은 되어야 하는 상황이 있어요. 예를 들어 인증이나 권한 확인처럼 "이 요청이 통과하려면 이 검사는 반드시 거쳐야 한다" 같은 경우죠.

그럴 때는 함수 파라미터에 Depends를 쓰는 대신, _경로 동작 데코레이터_에 dependencies 목록을 추가할 수 있어요.

출처: 공식문서

_경로 동작 데코레이터_에 dependencies 추가하기

_경로 동작 데코레이터_는 선택 인자 dependencies를 받아요. 이 값은 Depends()들의 list예요.

from typing import Annotated

from fastapi import Depends, FastAPI, Header, HTTPException

app = FastAPI()

async def verify_token(x_token: Annotated[str, Header()]):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")

async def verify_key(x_key: Annotated[str, Header()]):
    if x_key != "fake-super-secret-key":
        raise HTTPException(status_code=400, detail="X-Key header invalid")
    return x_key

@app.get("/items/", dependencies=[Depends(verify_token), Depends(verify_key)])
async def read_items():
    return [{"item": "Foo"}, {"item": "Bar"}]

이렇게 선언한 의존성들은 일반 의존성과 똑같이 실행/해결돼요. 다만 이들이 반환하는 값(있다면)은 _경로 동작 함수_로 전달되지 않아요. read_items의 시그니처를 보면 파라미터가 아예 없잖아요. 의존성들은 그저 "실행"만 되는 거예요.

팁

어떤 에디터는 사용하지 않는 함수 파라미터를 오류로 표시하기도 해요. 데코레이터의 dependencies를 쓰면 그런 에디터/도구 오류를 피하면서 의존성을 확실히 실행시킬 수 있어요. 또 코드를 처음 보는 개발자가 "이 파라미터는 왜 있는 거지?" 하고 헷갈리는 것도 막아 주죠.

참고

이 예제에서는 가상의 커스텀 헤더 X-Key, X-Token을 사용했어요. 실제 보안을 구현할 땐 다음 장에서 배울 통합 보안 유틸리티를 쓰는 게 훨씬 유리해요.

의존성의 오류와 반환값

이 데코레이터 dependencies에는 평소에 쓰던 것과 똑같은 의존성 _함수_를 사용할 수 있어요.

의존성의 요구 사항

의존성들은 헤더 같은 요청 요구 사항이나 다른 하위 의존성을 선언할 수 있어요. 위 코드의 verify_token이 X-Token 헤더를 요구하는 게 그 예시예요.

async def verify_token(x_token: Annotated[str, Header()]):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")

예외 던지기

이 의존성들도 일반 의견성처럼 raise로 예외를 던질 수 있어요. verify_token에서 헤더 값이 다르면 HTTPException을 던지는 것처럼요. 그러면 요청이 _경로 동작 함수_까지 도달하기 전에 실패 처리돼요.

async def verify_token(x_token: Annotated[str, Header()]):
    if x_token != "fake-super-secret-token":
        raise HTTPException(status_code=400, detail="X-Token header invalid")

반환값

그리고 이 의존성들은 값을 반환할 수도, 안 할 수도 있어요. 반환하더라도 그 값은 사용되지 않아요. 그래서 다른 곳에서 이미 쓰는 일반 의존성(값을 반환하는)을 그대로 재사용해도 돼요. 값은 버려지겠지만, 의존성 자체는 실행되니까요. verify_key처럼 값을 반환하는 의존성이 있어도, 데코레이터 dependencies에 넣으면 그 값은 무시되는 거예요.

경로 동작 묶음에 대한 의존성

여러 파일로 나누는 더 큰 애플리케이션 구조(Bigger Applications - Multiple Files)를 다룰 때, 한 경로 동작 묶음에 대해 dependencies 파라미터 하나를 선언하는 방법도 배우게 돼요. 지금은 "개별 동작에 dependencies를 거는 법"으로 충분해요.

전역 의존성

다음으로는 FastAPI 애플리케이션 전체에 의존성을 추가해서, 모든 _경로 동작_에 적용되도록 하는 방법을 볼 거예요. 이번 장에서 배운 개념이 그대로 확장되는 거라, 흐름은 이미 잡혀 있을 거예요.

더 알아보기 (Learn more)