Notebase

FastAPI에서 .env와 pydantic-settings를 사용해 DB 주소, SECRET_KEY, 디버그 설정을 코드와 분리하는 방법을 예제로 정리합니다. FastAPI 환경변수 설정을 제대로 해두면 DB 주소, JWT 비밀키, 디버그 옵션을 코드에서 분리할 수 있다. 처음에는 main.py에 직접 적는 게 편해 보이지만, GitHub에 올리거나 서버에 배포하는 순간 문제가 될 수 있다.이 글은 2026년 6월 기준 FastAPI 최신 버전과 Pydantic v2 흐름을 기준으로 작성했다. 설정 관리는 pydantic-settings를 사용하고, 로컬 개발 환경에서는 .env 파일을 함께 사용하는 방식으로 설명한다.환경변수 설정은 단순히 .env 파일을 하나 만드는 작업이 아니다.개발 환경과 운영 ..

React, Vue, Next.js 같은 프론트엔드에서 FastAPI API 호출이 CORS 오류로 막히는 이유와 CORSMiddleware 설정 방법을 초보자 기준으로 정리합니다. FastAPI CORS 설정은 프론트엔드에서 백엔드 API를 호출할 때 자주 막히는 지점이다. React, Vue, Next.js 개발 서버와 FastAPI 서버를 따로 실행하면 브라우저 콘솔에 CORS 오류가 뜨는 경우가 많다.처음 보면 FastAPI 코드가 잘못된 것처럼 보인다.하지만 실제로는 API 로직 문제가 아니라 브라우저 보안 정책 때문에 요청이 차단되는 상황인 경우가 많다. CORS가 뭔가요?CORS는 Cross-Origin Resource Sharing의 줄임말이다.한국어로 풀면 “교차 출처 리소스 공유” 정도..

FastAPI에서 JWT 로그인 인증이 어떻게 동작하는지 로그인 요청, 토큰 발급, Bearer 헤더 인증, 보호된 API 접근 흐름을 중심으로 정리합니다. FastAPI JWT 로그인은 사용자가 로그인하면 서버가 토큰을 발급하고, 이후 요청에서 그 토큰을 확인해 사용자를 인증하는 방식이다. 핵심은 “로그인 상태를 서버가 계속 들고 있지 않는다”는 점이다.일반적인 웹 로그인에서는 서버 세션을 떠올리기 쉽다.사용자가 로그인하면 서버가 세션을 만들고, 브라우저는 쿠키를 들고 다닌다. 요청이 올 때마다 서버는 쿠키에 연결된 세션 정보를 확인한다.JWT 방식은 조금 다르다.서버는 로그인 성공 시 서명된 토큰을 만들어 클라이언트에 전달한다. 클라이언트는 이후 API 요청마다 이 토큰을 함께 보낸다. 서버는 토큰의..

FastAPI 프로젝트가 커질 때 main.py 하나로 관리하기 어려워집니다. APIRouter, schemas, models, database 파일을 어떤 기준으로 나누면 좋은지 초보자 눈높이에서 정리합니다. FastAPI 프로젝트 구조는 처음부터 복잡하게 잡을 필요는 없습니다. 다만 API가 늘어나고 데이터베이스, 요청 모델, 응답 모델이 생기면 main.py 하나로 관리하기 어려워집니다.처음에는 한 파일로 시작해도 괜찮습니다.하지만 어느 순간 이런 문제가 생깁니다.main.py 안에- API 코드- Pydantic 모델- DB 연결 코드- 테이블 모델- 예외 처리- 비즈니스 로직이 전부 섞여 있음 이렇게 되면 코드를 고치기 어려워집니다.새로운 API를 추가할 때마다 main.py를 계속 열어야 하고..

FastAPI로 간단한 CRUD API를 만드는 방법을 예제로 정리했습니다. GET, POST, PUT, DELETE 요청이 각각 어떤 역할을 하는지 코드와 함께 확인할 수 있습니다. FastAPI CRUD API를 처음 만들 때는 데이터베이스부터 연결하기보다, 메모리 데이터를 사용해 흐름을 먼저 잡는 게 좋습니다. GET, POST, PUT, DELETE가 각각 어떤 역할을 하는지 코드로 바로 확인할 수 있기 때문입니다.이번 예제에서는 상품 정보를 다루는 간단한 CRUD API를 만들어보겠습니다.데이터베이스는 아직 사용하지 않습니다.파이썬 딕셔너리에 데이터를 저장하는 방식으로 API 구조만 먼저 익힙니다. CRUD API란?CRUD는 데이터를 다룰 때 가장 기본이 되는 4가지 작업입니다.CRUD의미HT..

FastAPI에서 SQLite를 연결하는 방법을 SQLModel 기준으로 정리합니다. 최신 lifespan 방식으로 테이블을 생성하고, 데이터 저장·조회·삭제 API까지 초보자도 따라 할 수 있게 설명합니다. FastAPI SQLite 연결은 API가 받은 데이터를 메모리에만 두지 않고 실제 DB 파일에 저장하는 첫 단계입니다. 입문 단계에서는 별도 DB 서버가 필요 없는 SQLite로 시작하면 구조를 이해하기 쉽습니다.FastAPI에서 데이터베이스를 연결하는 방법은 여러 가지입니다.SQLAlchemy를 직접 써도 되고, 비동기 DB 라이브러리를 써도 됩니다.다만 처음 배우는 단계라면 SQLModel을 사용하는 방식이 편합니다. SQLModel은 Pydantic과 SQLAlchemy를 기반으로 만들어진 ..

FastAPI에서 Swagger UI 문서가 자동으로 생성되는 원리를 초보자도 이해하기 쉽게 정리했습니다. /docs, /redoc, /openapi.json의 역할과 실제 API 테스트 방법까지 함께 설명합니다. FastAPI를 실행한 뒤 /docs에 접속하면 API 문서 화면이 자동으로 열립니다. 따로 문서 파일을 만들지 않았는데도 엔드포인트, 요청값, 응답 구조가 정리되어 나오죠. 이 기능이 FastAPI의 Swagger 문서 자동 생성입니다.처음 보면 꽤 신기합니다.“내가 한 건 함수 하나 만든 것뿐인데, 왜 문서가 생기지?”이 부분을 이해하면 FastAPI가 왜 입문자에게도 편하고, 협업용 API 서버를 만들 때 왜 자주 언급되는지 감이 잡힙니다.2026년 5월 기준 FastAPI 공식 문서에 ..

FastAPI에서 Pydantic 모델을 사용하는 이유와 BaseModel 작성법, POST 요청 데이터 검증, Swagger UI 문서 자동 생성 흐름을 초보자 기준으로 정리합니다. FastAPI Pydantic 모델은 API로 들어오는 JSON 데이터를 정해진 구조로 받고, 타입이 맞는지 자동으로 검증할 때 사용한다. POST 요청을 다루기 시작했다면 거의 반드시 만나게 되는 개념이다.FastAPI를 처음 배울 때는 보통 이런 코드부터 시작한다.@app.get("/items/{item_id}")def read_item(item_id: int): return {"item_id": item_id} 이 단계에서는 URL에 들어온 값을 함수 인자로 받는다.그런데 회원가입, 게시글 작성, 상품 등록처럼 ..

FastAPI에서 Path Parameter와 Query Parameter를 어떻게 구분하고 사용하는지 예제 코드와 함께 정리합니다. 필수값, 선택값, 타입 변환, 검증 방식까지 함께 설명합니다. FastAPI Path Parameter와 Query Parameter는 URL로 값을 받는 방식이다. 둘 다 API에서 자주 쓰이지만, 역할은 다르다.FastAPI를 처음 배우면 이런 URL을 자주 보게 된다./items/1/items?skip=0&limit=10 둘 다 서버에 값을 전달한다는 점은 같다.하지만 /items/1의 1은 Path Parameter이고, ?skip=0&limit=10은 Query Parameter다.이 차이를 정확히 알아야 API 주소를 자연스럽게 설계할 수 있다. Path Par..

FastAPI에서 GET과 POST 요청이 어떻게 다른지, 조회 API와 데이터 생성 API를 직접 만들며 Request Body, Pydantic, HTTPException, 자동 문서 테스트 흐름까지 초보자 기준으로 정리했습니다. FastAPI GET, POST 요청 차이는 API를 만들 때 가장 먼저 헷갈리는 부분입니다. 간단히 보면 GET은 데이터를 조회할 때, POST는 새 데이터를 보내거나 생성할 때 주로 사용합니다.처음에는 @app.get()과 @app.post()가 문법만 다른 것처럼 보일 수 있습니다.하지만 실제로는 API의 목적이 다릅니다.사용자가 상품 목록을 본다 → GET사용자가 새 상품을 등록한다 → POST게시글 상세 내용을 불러온다 → GET회원가입 정보를 서버로 보낸다 → P..