fastapi

이는 FastAPI 0.142.0의 버그입니다: OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수가 설정되어 있지만(호스팅 플랫폼에서 흔한 경우) OpenTelemetry extra가 설치되어 있지 않으면, 앱이 시작 시 'Automatic OpenTelemetry export requires fastapi[opentelemetry]' 오류와 함께 비정상 종료됩니다. 해결 방법: FastAPI 0.142.2 이상으로 업그레이드하면 이 문제가 해결됩니다(PR #16418). 0.142.0을 계속 사용해야 하는 경우 대체 해결 방법은 다음과 같습니다: (1) pip install fastapi[opentelemetry] 또는 fastapi[standard]로 extra를 설치하거나, (2) FastAPI()에 telemetry={'auto_configure': False}를 전달하여 자동 구성을 비활성화하거나, (3) FastAPI 0.141.0으로 다운그레이드하는 것입니다.

이것은 FastAPI 0.137.0에서 발생한 타입 어노테이션 회귀(regression)로(PR #15745에서 도입됨), APIRoute가 클래스 수준의 tags 어노테이션을 잃어버려, 커스텀 generate_unique_id_function 내부에서 타입 체커(ty, Pyright strict)가 route.tags에 대해 unresolved-attribute 오류를 보고합니다 — 코드가 런타임에는 정상적으로 동작함에도 불구하고 말입니다. 해결 방법: 해당 어노테이션을 복원한 FastAPI 0.137.1 이상으로 업그레이드하세요(PR #15765):

pip install -U "fastapi>=0.137.1"

그러면 문서에 나온 패턴이 올바르게 타입 검사를 통과합니다:

from fastapi import FastAPI
from fastapi.routing import APIRoute

def custom_generate_unique_id(route: APIRoute) -> str:
    return f"{route.tags[0]}-{route.name}"

app = FastAPI(generate_unique_id_function=custom_generate_unique_id)

임시로 0.137.0 버전을 유지해야 한다면, route.tags 라인에 # type: ignore[attr-defined] 주석을 달아 오류를 무시하거나, getattr(route, "tags", [])를 통해 접근하세요.

FastAPI는 (lazy router-inclusion 재작성 이후, #15745) 포함된 각 라우터의 해석된 라우트를 내부 버전 카운터(APIRouter._routes_version)를 키로 하여 캐시합니다. append(), remove(), clear(), 슬라이스 할당 또는 재할당으로 router.routes를 직접 변경하면 이 카운터가 절대 증가하지 않으므로, 부모 라우터는 오래된 캐시 목록을 계속 제공하게 됩니다: 새 라우트는 404를 반환하고, 삭제된 라우트는 '유령(ghost)' 라우트로서 계속 응답합니다.

우회 방법:
1. 캐시를 올바르게 무효화하는, 추적되는 공식 메서드를 통해서만 라우트를 변경하세요:

# child.routes.append(APIRoute("/child2", handler, methods=["GET"])) 대신
   child.add_api_route("/child2", handler, methods=["GET"])
   # 또는: child.add_route(...), child.include_router(...)

child.routes.append(new_route)
   child._mark_routes_changed()  # 비공개(private) API이며 향후 릴리스에서 변경될 수 있음

.routes가 변경을 인식하도록 만드는 근본적인 수정은 fastapi issue #16301에서 논의되고 있습니다.

이것은 FastAPI 0.137.2+에서 확인된 버그입니다(0.141.1에서도 여전히 존재합니다). iter_route_contexts()는 HTTP 라우트에는 include_router() prefix를 적용하지만, APIWebSocketRoute에 대해서는 ctx.path == ""를 yield하며, ctx.route.path에는 prefix가 붙지 않은 경로만 들어 있습니다. 아직 수정이 포함된 릴리스는 없습니다. 우회 방법: websocket 라우트를 별도로 특별 처리하고, include_router()에 전달한 prefix를 앞에 붙여 전체 경로를 직접 재구성하세요.

from fastapi.routing import APIWebSocketRoute, iter_route_contexts

PREFIX = "/api/v1"  # app.include_router(router, prefix=PREFIX)에서 사용한 prefix

for ctx in iter_route_contexts(app.routes):
    if isinstance(ctx.route, APIWebSocketRoute) and not ctx.path:
        full_path = PREFIX + ctx.route.path  # 예: /api/v1/stream/{job_id}
    else:
        full_path = ctx.path

prefix를 정적으로 알 수 없는 경우에는 private _IncludedRouter.include_context.prefix에 저장되어 있지만, 이 API는 내부용이므로 변경될 수 있습니다. 따라서 수정이 반영되기 전까지는 include_router() prefix를 직접 추적하는 것이 더 안전한 방법입니다.