Starlette 1.0.0: 삭제 및 수정 사항

Starlette 1.0.0: 안정 버전 릴리스의 주요 변경 사항

Starlette가 거의 8년의 개발 기간을 거쳐 첫 안정 버전 1.0.0에 도달했습니다. 이번 릴리스는 사용 중단된 API 제거, WebSocket, 폼, 정적 파일 처리의 버그 수정에 중점을 두었습니다. 이 프레임워크는 FastAPI의 기반으로 남아 있으며, AI 애플리케이션을 위한 Python MCP SDK에서 사용되고 있습니다.

새로운 기능

1.0.0 버전에서는 SessionMiddleware에서 세션 접근 및 변경 추적 기능이 추가되었습니다. 이를 통해 미들웨어에서 세션 데이터의 읽기와 수정 사항을 추가적인 해킹 없이 로그로 남길 수 있습니다.

1.0.0rc1 릴리스에서는 WebSocket에 대한 제네릭 상태가 도입되었습니다. 연결 상태가 이제 타입화되어 async 핸들러에서 TypedDict나 Pydantic 모델 작업이 간편해집니다.

버그 수정

이번 릴리스에서 여러 중요한 문제가 수정되었습니다:

• StreamingResponse와 FileResponse의 WebSocket 실패 처리: 응답이 이제 연결을 제대로 종료하여 누수가 발생하지 않습니다.
• FormParser가 필드 누적에 bytearray를 사용해 대형 폼 파싱 시 메모리 사용량을 줄였습니다.
• MultiPartParser.parse()에서 parser.finalize()를 try/except 내부로 이동시켜 불완전한 멀티파트 데이터로 인한 예외를 방지합니다.

rc1에서의 추가 수정 사항:

• 416 응답의 Content-Range 헤더에 bytes 단위를 포함합니다.
• StaticFiles가 경로의 0바이트를 처리할 때 충돌하지 않습니다.
• Range 파싱이 정확성을 위해 정렬된 병합을 사용합니다.
• 응답의 다중 범위에서 Content-Range 대신 Content-Type을 사용합니다.
• 멀티파트 byterange 경계에 CRLF 종료를 적용합니다.
• FileResponse가 range 요청 시 헤더를 수정하지 않습니다.
• CORS 응답이 자격 증명과 함께 명시적 origin을 반환합니다.
• Jinja2Templates가 기본적으로 autoescape를 활성화합니다.

사용 중단된 요소 제거

Starlette 1.0.0은 사용 중단된 함수를 제거하여 API를 정리했습니다. 이전 버전 프로젝트는 마이그레이션이 필요합니다.

제거된 항목 전체 목록:

• Starlette와 Router의 on_startup 및 on_shutdown 매개변수. lifespan으로 대체.
• on_event() 데코레이터. lifespan 사용.
• add_event_handler() 메서드. lifespan 사용.
• Router의 startup() 및 shutdown() 메서드.
• @app.route() 데코레이터. routes에서 Route 사용.
• @app.websocket_route() 데코레이터. routes에서 WebSocketRoute 사용.
• @app.exception_handler() 데코레이터. exception_handlers 사용.
• @app.middleware() 데코레이터. middleware 사용.
• starlette.routing의 iscoroutinefunction_or_partial() 함수.
• Jinja2Templates의 **env_options 매개변수. env를 통해 준비된 jinja2.Environment 전달.
• 사용 중단된 TemplateResponse(name, context) 시그니처. request가 필요: TemplateResponse(request, name, ...).
• FileResponse의 사용 중단된 method 매개변수.

동작 변경

Jinja2Templates는 이제 인스턴스화 시점이 아닌 import 시점에 jinja2가 설치되어 있어야 합니다. 이는 CI/CD에서 종속성 진단을 가속화합니다.

1.0.0으로 마이그레이션

• 모든 on_startup/on_shutdown을 lifespan 컨텍스트로 교체:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: Starlette):
    # startup
    yield
    # shutdown

app = Starlette(lifespan=lifespan, routes=[...])

• routes를 routes 목록으로 이동:

routes = [
    Route("/", endpoint=home),
    WebSocketRoute("/ws", endpoint=ws_endpoint),
]

• exception_handlers와 middleware도 유사하게 업데이트.

• Jinja2Templates의 경우 env를 미리 준비:

import jinja2
env = jinja2.Environment(autoescape=True)
templates = Jinja2Templates(env=env)

업그레이드 후 range 요청과 멀티파트 폼을 테스트하세요.

주요 요점

• API 안정성: 모든 사용 중단 요소 제거로 코드가 더 깔끔하고 예측 가능해짐.
• WebSocket 및 스트리밍: 실패 처리 수정으로 프로덕션 준비 완료.
• 폼 및 파일: 메모리 최적화와 멀티파트/range 파싱 개선.
• Lifespan 대체: ASGI 3.0+와 호환되는 통합 라이프사이클 훅.
• Jinja2: 엄격한 종속성 요구사항과 기본 autoescape.

— Editorial Team