119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# SQLite + FastAPI + Vue 포트 설정 분리 설계
|
|
|
|
## 목표
|
|
|
|
현재 CRUD 예제의 백엔드와 프론트 실행 포트를 문서와 코드에서 더 분리해, 로컬 포트 충돌이 있어도 최소 수정으로 다시 실행할 수 있게 만든다.
|
|
|
|
## 배경
|
|
|
|
기존 예제는 아래 주소를 기본값으로 사용한다.
|
|
|
|
- 백엔드 API: `http://127.0.0.1:8000`
|
|
- 프론트 정적 서버: `http://127.0.0.1:5173`
|
|
|
|
실행 중 실제로 `8000`, `5173` 포트가 이미 사용 중이어서 새 서버를 같은 포트에 띄우지 못했다. 따라서 포트를 바꾸는 방법이 코드와 문서에 더 명확히 드러나야 한다.
|
|
|
|
## 범위
|
|
|
|
이번 작업은 다음을 포함한다.
|
|
|
|
- 프론트엔드의 API 주소 상수 구조를 분리
|
|
- 백엔드 포트 변경 방법을 README에 명시
|
|
- 프론트 정적 서버 포트 변경 방법을 README에 명시
|
|
- 기본 포트와 대체 포트 예시를 함께 제공
|
|
|
|
이번 작업은 다음을 포함하지 않는다.
|
|
|
|
- 별도 설정 파일 도입
|
|
- `.env` 기반 환경변수 시스템 추가
|
|
- 프론트 번들러 도입
|
|
- 런타임 자동 포트 탐지
|
|
|
|
## 접근 방식
|
|
|
|
### 1. 프론트 상수 분리
|
|
|
|
`frontend/src/main.js`의 API 주소를 하나의 긴 문자열 대신 아래 상수로 분리한다.
|
|
|
|
- `API_HOST`
|
|
- `API_PORT`
|
|
- `API_BASE_URL`
|
|
|
|
예시 구조:
|
|
|
|
```javascript
|
|
const API_HOST = 'http://127.0.0.1'
|
|
const API_PORT = '8000'
|
|
const API_BASE_URL = `${API_HOST}:${API_PORT}/api`
|
|
```
|
|
|
|
이렇게 하면 백엔드 포트를 `8001` 같은 값으로 바꿀 때 한 줄만 수정하면 된다.
|
|
|
|
### 2. 백엔드 실행 포트는 명령에서 제어
|
|
|
|
백엔드는 FastAPI 코드 내부에서 포트를 고정하지 않는다. 실행 포트는 `uvicorn` 명령의 `--port` 옵션으로 제어한다.
|
|
|
|
기본 실행:
|
|
|
|
```bash
|
|
uvicorn backend.main:app --host 127.0.0.1 --port 8000
|
|
```
|
|
|
|
대체 실행:
|
|
|
|
```bash
|
|
uvicorn backend.main:app --host 127.0.0.1 --port 8001
|
|
```
|
|
|
|
### 3. 프론트 정적 서버 포트는 명령에서 제어
|
|
|
|
프론트 정적 서버도 코드가 아니라 실행 명령에서 포트를 선택한다.
|
|
|
|
기본 실행:
|
|
|
|
```bash
|
|
python3 -m http.server 5173 -d frontend
|
|
```
|
|
|
|
대체 실행:
|
|
|
|
```bash
|
|
python3 -m http.server 5174 -d frontend
|
|
```
|
|
|
|
## README 문서화 방식
|
|
|
|
README에는 아래 내용을 포함한다.
|
|
|
|
- 기본 포트 실행 예시
|
|
- 포트 충돌 시 대체 실행 예시
|
|
- 프론트에서 `API_PORT` 값을 어디서 바꾸는지 설명
|
|
- 백엔드와 프론트 포트는 서로 독립적으로 바꿀 수 있다는 점
|
|
|
|
## 데이터 흐름
|
|
|
|
1. 사용자가 백엔드를 원하는 포트로 실행한다.
|
|
2. 프론트는 `API_HOST`와 `API_PORT`를 조합해 API 주소를 만든다.
|
|
3. 프론트 정적 서버는 별도 포트에서 독립적으로 제공된다.
|
|
4. 포트 충돌 시 백엔드와 프론트 포트를 각각 따로 변경할 수 있다.
|
|
|
|
## 오류 처리
|
|
|
|
- 프론트가 잘못된 백엔드 포트를 가리키면 기존처럼 fetch 에러 문구를 보여준다.
|
|
- README에 포트 불일치 점검 순서를 넣어 사용자가 원인을 쉽게 찾을 수 있게 한다.
|
|
|
|
## 검증 기준
|
|
|
|
다음 조건을 만족하면 성공이다.
|
|
|
|
- 프론트 코드에서 백엔드 포트를 한 곳만 바꿔도 API 주소가 함께 변경된다.
|
|
- README만 읽어도 기본 포트와 대체 포트 실행 방법을 이해할 수 있다.
|
|
- 기존 CRUD 기능은 변경 없이 유지된다.
|
|
- 포트 충돌 상황에서 사용자가 다음 행동을 바로 선택할 수 있다.
|
|
|
|
## 구현 원칙
|
|
|
|
- 기존 CRUD 구조를 유지한다.
|
|
- 설정 분리를 위해 새 시스템을 과하게 도입하지 않는다.
|
|
- 실행 문서는 실제 충돌 상황을 해결하는 데 바로 도움이 되도록 쓴다.
|