처음 시작하는 FastAPI

처음 시작하는 FastAPI 책을 읽으면서 책 내용을 정리한 내용입니다.

PART 2

해당 코드는 아래의 모든 테스트 코드입니다.

from fastapi import FastAPI

app = FastAPI()
@app.get("/hi")
def greet():
return"Hello? World"

### Fast API 프레임워크
FastAPI는 Python으로 만든 빠르고 현대적인 웹 프레임워크입니다.
비동기(Async)를 지원하며 Starlette와 Pydantic 위에서 동작합니다.
- **빠른 속도**: Node.js, Go에 가까운 성능
- **자동 문서화**: Swagger UI와 ReDoc을 자동 생성
- **타입힌트(Type Hint) 기반**: 코드만으로 입력값 검증과 문서화 가능
> **"간결하지만 강력한 백엔드 프레임워크"**로 API 개발에 특히 적합합니다.

> 
FastAPI 설치

pip install fastapi #FastAPI 프레임워크 자체를 설치합니다.
pip install fastapi==[version] #FastAPI 프레임워크 특정 버전으로 설치합니다.

Uvicorn 웹 서버

Uvicorn은 FastAPI 앱을 실행하기 위한 ASGI(비동기 서버 게이트웨이 인터페이스[Asynchronous Server Gateway Interface]) 웹 서버입니다.
간다히 말해서 Uvicorn은 FastAPI의 엔진 역할을 하는 서버입니다.

Uvicorn 설치

pip install "uvicorn[standard]"		#ASGI서버인 Uvicorn을 설치합니다.
									#[standard]옵션은 서버 실행에 필요한 추가 의존성까지 한번에 설치합니다.
pip install "uvicorn[standard]==version"	#Uvicorn의 특정 버전으로 설치합니다.

FastAPI와 Uvicorn 한번에 설치

pip install fastapi "uvicorn[standard]"

FastAPI 실행 명령어

uvicorn main:app --reload	#기본 포트 8000으로 개발 모드 실행
uvicorn main:app --port 8080	#특정 포트8080으로 실행

• uvicorn: FastAPI 앱을 구동하는 ASGI 서버 프로그램입니다.

• main: FastAPI 애플리케이션 인스턴스가 정의된 파이썬 모듈(파일 이름)입니다.
  (ex: main.py or user.py)

• ":": 모듈 이름과 애플리케이션 객체 이름을 구분하는 구분자입니다.

• app: 해당 모듈 내에서 정의된 FastAPI 인스턴스의 변수 이름입니다.

• "--reload": 개발 모드를 활성화합니다. 소스코드가 변경될때마다 서버를 자동으로 재시작합니다.
  (즉 코드 수정후 저장하고 서버를 재시작할 필요가 없어집니다.)

• "--port 8080": 포트지정 없이 실행하면 기본 포트인 8000으로 실해 되지만 특정 포트를 지정하여 서버 실행이 가능합니다.

HTTPie 텍스트 웹클라이언트

HTTPie는 터미널에서 API를 테스트 할 때 사용하는 명령줄 기반 HTTP클라이언트이며 curl보다 직관적이고 출력이 보기 좋습니다.
그리고 Postman과 같은 그래픽 사용자 인터페이스(GUI) 기반의 도구를 추가적으로 사용할 필요가 없습니다.

간단하게 HTTPie는 "터미널에서 테스트하는 미니 Postman" 느낌이라고 생각하면 됩니다.

HTTPie (텍스트/CLI 기반) 장단점
HTTPie는 터미널(CLI)에서 작동하는 깔끔한 사용자 친화적인 도구입니다.
- 장점

• 빠른 속도&경량
• 스크립트 친화적
• 가독성 높은 구문
• 터미널 환경 친화적

- 단점

• 복잡한 GUI기능(워크플로우, 스크립팅)이 부족
• 명령줄에 익숙하지 않은 사용자에게 진입 장벽이 있음
• 간단한 구문으로 JSON, 헤더 등을 쉽게 처리
• 서버 환경이나 SSH 접속 환경에서 테스트하기 용이
• 요청/응답을 저장하거나 공유하기 어려움

• FastAPI 개발중 빠르고 간단한 API 테스트가 필요할때
• 터미널에서 작업하는 것을 선호하거나 자동화 스크립트에 테스트를 포함시킬때

Postman (GUI 기반)
Postman은 별도의 데스크톱 앱(GUI)으로 강력한 기능 세트와 편리한 인터페이스를 제공합니다.
- 장점

• 풍부한 기능
• 시각적인 인터페이스
• 컬렉션/워크플로우 관리
• API 요청 설정(헤더, 본문, 인증) 및 응답 확인이 쉬움
• 테스트 케이스 그룹화, 환경변수 관리, 복잡한 테스트 스크립트 작성에 용이
• 팀원간 API 명세 및 테스트 공유에 강력한 기능 제공

- 단점

• 상대적으로 무겁고 설치가 필요하며 실행 시간이 더 걸릴 수 있음
• 단순 요청 테스트에는 오히려 복잡함
• CLI환경과 통합이 어려움

HTTPie 테스트

#출력결과
>>http localhost:8000/hi	#서버 실행 후 터미널에 입력해서 테스트
HTTP/1.1 200 OK
content-legth: 15
content-type: application/json date: Thu, 30 Jun 2025 08:22:27 GMT
sever: uvicorn
"Hello?World"

-b 인자를 사용하면 응답헤더를 제외한 본문만 출력합니다

>> http -b localhost:8000/hi	#서버 실행 후 터미널에 입력해서 테스트
#출력결과
"Hello?World"

-v를 사용하면 요천 전체 허더와 응답을 출력합니다.

>>http -v localhost:8000/hi	#서버 실행 후 터미널에 입력해서 테스트
#출력결과
GET /hi HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Host: localhost:8000
User-Agent: HTTPie/3.2.4
HTTP/1.1 200 OK
content-length: 15
content-type: application/json
date: Fri, 07 Nov 2025 15:28:20 GMT
server: uvicorn
"Hello? World?"

Requests 동기식 웹 클라이언트 패키지

Requests는 Python에서 가장 많이 쓰는 HTTP 요청(GET, POST, PUT, PATCH, DELETE) 패키지입니다.

동기식(Synchronous)의 의미
요청이 끝날때까지 다음 코드가 실행되지 않는것을 의미합니다.

예시 코드
r = requestes.get("http://localhost:8000")		#응답이 올때까지 기다립니다.
print("다음 코드 실행")		#응답 후에 실행

따라서 비동기(Async) FastAPI에서 사용할 땐 requeste 대신 httpx 같은 비동기 라이브러리를 사용하는 경우가 많습니다.
하지만 단순 테스트나 외부 API 호출이 많지 않을땐 requests로도 충분합니다.

Requests와 거의 동일한 HTTPX로 테스트
>>> import httpx
>>> r = httpx.get("http://localhost:8000/hi")
>>> r.json()
"Hello?World"

HTTPX 동기/비동기식 웹 클라이언트 패키지

HTTPX는 Requests를 계승한 차세대 HTTP 클라이언트로 동기와 비동기 둘다 지원합니다.
Requests와 API 스타일이 유사하지만 비동기 AsyncClient를 제공해 asunc/await 환경에서 자연스럽게 사용이 가능합니다.

HTTP 요청의 주요 구성 요소

• Method: GET, POST, PUT, PATCH, DELETE 등 서버에서 어떤 행동을 요청하는지
• URL: "http://localhost:8000/hi"와 같은 브라우저 주소
• Headers: 요청 메타데이터 (ex: Authorization, Content-Type, User-Agent)
• Query parameters: URL뒤의 ?key=value 형태 보통 params로 전달
• Body/Payload: POST/PUT 등에 보내는 데이터(json, data, files, content, stream)
• Status Code: 서버의 응답 코드
• Response headers: 응답의 메타데이터(ex: content-type, set-cookie)
• Response body: 실제 데이터(JSON, 텍스트, 바이너리)
• Cookies: 상태 유지에 사용
• connection & Transport concerns: 타임아웃, 재시도, 프록시, 인증, TLS/SSL등

쿼리 매개변수(Query parameters)

쿼리매개변수는 URL끝에 붙는 추가 데이터로 서버에 요청할 때 필터링, 검색, 페이지네이션등의 목적으로 사용됩니다.

http://localhost:8000/item?page=28&limit=20
#page=28
#limit=20
#page와 limit가 쿼리 매개변수입니다.

"?"는 쿼리 매개변수의 시작을 의미하며 key=value(매개변수의 이름과 값)로 사용합니다. "&"는 여러개의 매개변수 연결을 의미합니다.

쿼리 매개변수 사용한 예시 코드

@app.get("/item")
def read_item(page: int = 1, limit: int = 30, q: str = None);
	return {
    	"page": page,
        "limit": limit,
        "search_query": q
        }
#출력
{
  "page": 2,
  "limit": 5,
  "search_query": "짱짱쎈 무언가"
}