매개변수
| 구분 | 들어오는 위치 | 선언 방법 | 예시 |
|---|---|---|---|
| 경로 매개변수 (Path Parameter) | URL 경로 안 | Path() | /users/{user_id} |
| 쿼리 매개변수 (Query Parameter) | URL ?key=value 뒤에 | Query() | /users?name=kihoon |
| 본문 매개변수 (Body Parameter) | HTTP 요청 본문(body) | Body(), Form(), File() | JSON, Form, 파일 등 |
- 본문 매개변수 : 요청의 body 부분에 포함된 데이터를 받는 걸 의미
기본 용어
- 어트리뷰트: "." 으로 접근할 수 있는 것들을 전부 어트리뷰트라고 함
FastAPI 문서나 코드에서 자주 보이는 “기본 용어”
| 용어 | 뜻 | 예시 코드 | 설명 |
|---|---|---|---|
| 패스(Path) | URL의 경로 | /users/{user_id} | @app.get("/users/{user_id}")처럼 엔드포인트를 구성하는 경로 |
| 쿼리(Query) | URL 뒤에 붙는 ?파라미터 | /users?name=kihoon | Query()로 선언, 선택적 필터링 |
| 본문(Body) | HTTP 요청의 본문 | { "name": "kihoon" } | JSON 데이터 등 요청 내부 내용 |
| 스키마(Schema) | 데이터 구조 정의 | class User(BaseModel) | 입력/출력 데이터의 형태를 정의 (Pydantic) |
| 모델(Model) | DB 테이블 구조 | class UserModel(Model) | ORM에서 데이터베이스 테이블을 표현 |
| 엔드포인트(Endpoint) | 실제 요청이 들어오는 함수 | @app.post("/users") | 클라이언트가 접근하는 API의 “주소 + 동작” |
| 라우터(Router) | 여러 엔드포인트를 묶은 그룹 | APIRouter() | /users, /items 등 모듈별 관리용 |
| 데코레이터(Decorator) | 함수의 기능을 확장하는 문법 | @app.get() | FastAPI 라우팅을 등록할 때 사용 |
| 어노테이션(Annotation) | 타입 힌트에 부가 설명 추가 | Annotated[str, Query()] | 타입에 제약이나 추가 정보 부여 |
| 의존성 주입(Dependency Injection) | 함수 실행 시 필요한 객체 자동 주입 | Depends(get_db) | 공통 리소스를 주입하는 구조 |
| 미들웨어(Middleware) | 요청 전후에 실행되는 중간 처리 | @app.middleware("http") | 로그, 인증, 요청/응답 가공 등 |
| 스코프(Scope) | 객체가 유효한 범위 | request, session, app 등 | FastAPI 내부적으로 요청마다 분리된 영역 |
| 인스턴스(Instance) | 클래스에서 생성된 실제 객체 | user = User("기훈") | 클래스 설계도를 바탕으로 실제 값 생성 |
메타데이터
- API 전체(혹은 각 경로)에 대한 설명 정보를 담는 데이터
- 즉, 서버가 “무엇을 하는 API인지”, “누가 만든 것인지”, “어떤 태그로 묶이는지” 같은 문서화용 정보를 의미
- 메타데이터는 실제 API 동작에는 영향을 주지 않음
- 아래처럼 FastAPI() 생성자에 넣을 수 있음
라우터 단위의 메타데이터 (tags, summary, description)
@app.get("/users/", tags=["users"], summary="모든 사용자 조회", description="DB에 저장된 모든 사용자를 가져옵니다.")
async def read_users():
return [{"username": "Alice"}, {"username": "Bob"}]
- /docs에서 보면
- users 섹션 아래에 "모든 사용자 조회" 라는 항목이 생기고 클릭하면 description이 출력
용어 설명 - 2
- 의존성을 주입하면 주입당한 명령어는 그 의존성을 먼저 거치고 실행한다.
안녕하세요.