Path, Query, Response_model

HTTP 통신 오류코드 - 404

• 경로 자체가 없음

HTTP 통신 오류코드 - 422

• 요청 자체에는 오류 없음
• 서버가 요청 내용 처리 불가
• FastAPI에서 주로 경로 변수 타입 불일치 시 발생(Path, Query)

Path

• URL 경로 변수에 제약 조건 부여
• 예: /todos/1 → id는 양수여야 함

Path 매개변수 옵션

• ... : 필수 매개변수 (생략 불가)
• title : Swagger UI 문서에 제목 표시
• ge=1 : 최소값 제한 (1 이상)
• le=100 : 최대값 제한
• gt, lt : 초과/미만 제한

FastAPI 라우팅 순서

• 고정 경로는 먼저 정의
• 경로 매개변수는 나중에 정의
• 예: /users/me → /users/{user_id} 순으로 작성
• 경로 매개변수는 위치 기반, 쿼리 매개변수는 키-값 기반
• 정확한 매칭 우선 적용됨
• 경로 순서 잘못 작성 시 → 422 오류 발생 가능

Query

• URL 쿼리 매개변수에 제약 조건 부여
• 예: /todos/search?item=공부 → item은 필수
• Swagger 문서화 + 유효성 검사 가능

Query 매개변수 옵션

• ... : 필수 매개변수 지정
• 기본값 지정 : 선택 매개변수 (예: Query("기본값"))
• title : Swagger UI 입력창 위 제목
• description : 입력창 아래 설명
• min_length, max_length : 문자열 길이 제한
• regex : 정규표현식 조건
• alias : 변수명과 다른 쿼리 이름 설정
• deprecated=True : Swagger에 "사용 권장 안함" 표시
• example : Swagger UI 예시값

Path vs Query

• Path: URL 경로에서 받음 → 예: /todos/1
• Query: URL ? 뒤에서 받음 → 예: /todos?done=true
• Path: 자원 식별용 (ID 등)
• Query: 검색, 필터링, 옵션 입력용

response_model

• 응답 데이터 구조를 정의
• 출력 데이터 검증 및 자동 문서화 지원
• Pydantic 모델 사용 → JSON 응답 형식 제어
• 보안 및 클라이언트 명세에 유용
• 예: response_model=Item → 응답은 Item 모델 구조 따름

Path, Query VS response_model

Path, Query

• 요청 데이터를 받는 방식 정의
• Path: URL 경로에 포함된 변수 → 경로 변수
• Query: URL 물음표(?) 이후 key=value 형식 → 쿼리 매개변수
• FastAPI 기준: 함수 인자에 따라 자동 분류 (Path 매개변수는 필수)
• 예: /items/{item_id}?q=search → item_id는 Path, q는 Query

response_model

• API 응답 구조 정의
• 클라이언트가 받을 데이터 형식 명확히 지정
• Pydantic 모델 기반 → 필드 타입 및 필수 항목 자동 검증
• 내부 데이터 숨김 가능 → 보안 향상
• 응답 일관성 유지 → 프론트엔드와의 협업 용이
• OpenAPI 문서 자동 생성 → API 문서화 효율적
• 예: response_model=Item → 응답은 Item 모델 형식으로 출력

오류 처리

• 정상 요청 시에는 상황에 맞는 status_code를 명시할 수 있음
• 예: @router.post("", status_code=201) → 새 리소스 생성 시 201 Created를 명확하게 지정
• 비정상 요청 시에는 HTTPException을 사용해 오류 코드와 메시지를 함께 응답
• 예: raise HTTPException(status_code=404, detail="해당 ID의 할 일을 찾을 수 없습니다.")
• status_code는 성공 응답의 상태 코드를 지정하고,
  HTTPException은 실패 상황에 대해 오류 메시지와 상태 코드를 함께 전달함

예시 코드:

@todo_router.put("/{todo_id}")
async def update_todo(todo_id: int, new_todo: TodoItem):
    for todo in todo_list:
        if todo.id == todo_id:
            todo.item = new_todo.item
            return {"message": "할 일이 수정되었습니다."}
    raise HTTPException(
        status_code=404,
        detail="해당 ID의 할 일을 찾을 수 없습니다."
    )

상태 코드 요약:

• 200 OK : 일반적인 성공 응답
• 201 Created : 리소스 생성 성공 (POST)
• 204 No Content : 응답 본문이 없는 성공 (DELETE 등)
• 400 Bad Request : 잘못된 요청 (유효성 검사 실패 등)
• 401 Unauthorized : 인증 실패
• 404 Not Found : 리소스를 찾을 수 없음
• 500 Internal Server Error : 서버 내부 처리 실패