์ฌ์ฃผ ๊ธฐ๋ฐ ์ด์ธ ๋ฐ ๋ก๋ ์ถ์ฒ ์๋น์ค ๋ฐฑ์๋
์ด ํ๋ก์ ํธ๋ Clean Architecture ํจํด์ ๋ฐ๋ฆ ๋๋ค.
๊ฐ ๋ชจ๋(users, lotto, fortune ๋ฑ)์ ๋ค์๊ณผ ๊ฐ์ ๋ ์ด์ด ๊ตฌ์กฐ๋ฅผ ๊ฐ์ง๋๋ค:
{module}/
โโโ api/ # API ๋ ์ด์ด (ํ๋ ์ ํ
์ด์
)
โ โโโ router.py # FastAPI ๋ผ์ฐํฐ (์๋ํฌ์ธํธ ์ ์)
โ โโโ schemas.py # ์์ฒญ/์๋ต ์คํค๋ง (Pydantic ๋ชจ๋ธ)
โ
โโโ application/ # ์ ํ๋ฆฌ์ผ์ด์
๋ ์ด์ด (Use Case)
โ โโโ service.py # ๋น์ฆ๋์ค ๋ก์ง ๊ตฌํ, ๋๋ฉ์ธ ์กฐํฉ
โ
โโโ domain/ # ๋๋ฉ์ธ ๋ ์ด์ด (๋น์ฆ๋์ค ๊ท์น)
โ โโโ entities/ # ๋๋ฉ์ธ ์ํฐํฐ
โ โ โโโ models.py # SQLAlchemy ๋ชจ๋ธ
โ โ โโโ enums.py # ๋๋ฉ์ธ Enum
โ โโโ interfaces.py # ๋ฆฌํฌ์งํ ๋ฆฌ ์ธํฐํ์ด์ค (Protocol)
โ
โโโ infrastructure/ # ์ธํ๋ผ ๋ ์ด์ด (๊ตฌํ)
โโโ repository.py # ๋ฆฌํฌ์งํ ๋ฆฌ ๊ตฌํ (๋ฐ์ดํฐ๋ฒ ์ด์ค ์ ๊ทผ)
API Layer (
api/)
- HTTP ์์ฒญ/์๋ต ์ฒ๋ฆฌ
- FastAPI ๋ผ์ฐํฐ๋ฅผ ํตํ ์๋ํฌ์ธํธ ์ ์
- ์์ฒญ ๊ฒ์ฆ ๋ฐ ์๋ต ์ง๋ ฌํ
- ์:
@router.get("/users/{user_id}")์๋ํฌ์ธํธ ์ ์
Application Layer (
application/)
- Use Case ๊ตฌํ
- ๋๋ฉ์ธ ๋ก์ง ์กฐํฉ ๋ฐ ์ค์ผ์คํธ๋ ์ด์
- ํธ๋์ญ์ ๊ด๋ฆฌ
- ์:
UserService.create_user()- ์ฌ์ฉ์ ์์ฑ Use Case
Domain Layer (
domain/)
- ๋น์ฆ๋์ค ๊ท์น ๋ฐ ๋๋ฉ์ธ ๋ชจ๋ธ
- ์ธ๋ถ ์์กด์ฑ ์์ (์์ ๋น์ฆ๋์ค ๋ก์ง)
- ์ธํฐํ์ด์ค ์ ์ (์์กด์ฑ ์ญ์ ์์น)
- ์:
IUserRepository์ธํฐํ์ด์ค,User์ํฐํฐ
Infrastructure Layer (
infrastructure/)
- ์ธ๋ถ ์์คํ ๊ณผ์ ํต์ ๊ตฌํ
- ๋ฐ์ดํฐ๋ฒ ์ด์ค ์ ๊ทผ ๊ตฌํ
- ์ธ๋ถ API ํด๋ผ์ด์ธํธ
- ์:
UserRepository- MySQL ์ ๊ทผ ๊ตฌํ
API โ Application โ Domain โ Infrastructure
- Domain: ๊ฐ์ฅ ์์ชฝ ๋ ์ด์ด, ์ธ๋ถ ์์กด์ฑ ์์
- Application: Domain์ ์ฌ์ฉํ์ฌ ๋น์ฆ๋์ค ๋ก์ง ๊ตฌํ
- Infrastructure: Domain ์ธํฐํ์ด์ค๋ฅผ ๊ตฌํ
- API: Application์ ํธ์ถํ์ฌ HTTP ์์ฒญ ์ฒ๋ฆฌ
- ์ฌ์ฉ์ ์์ฑ/์กฐํ/์์
- ์ฌ์ฃผ ์ ๏ฟฝ๏ฟฝ๏ฟฝ ์ ์ฅ ๋ฐ ์กฐํ
- ์๋ ์์ผ ๊ธฐ๋ฐ ์ฌ์ฃผ ๊ณ์ฐ
- ์คํ, ์ญ์ ๋ถ์
- HCX API๋ฅผ ํตํ ์ฌ์ฃผ ์ค๋ช ์์ฑ
- ์ผ์ผ ์ด์ธ ์ ๊ณต
- ์ฌ์ฃผ ๊ธฐ๋ฐ ์ด์ธ ๋ถ์
- ์ฌ์ฃผ ๊ธฐ๋ฐ ๋ก๋ ๋ฒํธ ์ถ์ฒ
- ๋ก๋ ํต๊ณ ๋ฐ ๋น์ฒจ ํ์ธ
- Python 3.13+
- MySQL
- uv (ํจํค์ง ๊ด๋ฆฌ์)
# ์์กด์ฑ ์ค์น
uv sync
# ํ๊ฒฝ ๋ณ์ ์ค์
cp .env.example .envdocker-compose -f docker-compose.local.yml up --buildSatto-Server/
โโโ src/
โ โโโ users/ # ์ฌ์ฉ์ ๋ชจ๋
โ โโโ four_pillars/ # ์ฌ์ฃผ ๊ณ์ฐ ๋ชจ๋
โ โโโ fortune/ # ์ด์ธ ๋ชจ๋
โ โโโ lotto/ # ๋ก๋ ์ถ์ฒ ๋ชจ๋
โ โโโ hcx_client/ # HCX API ํด๋ผ์ด์ธํธ
โ โโโ config/ # ์ค์
โ โโโ common/ # ๊ณตํต ์ ํธ๋ฆฌํฐ
โโโ migrations/ # ๋ฐ์ดํฐ๋ฒ ์ด์ค ๋ง์ด๊ทธ๋ ์ด์
โโโ nginx/ # Nginx ์ค์
โโโ pyproject.toml # ํ๋ก์ ํธ ์ค์
- Framework: FastAPI
- Database: MySQL (SQLAlchemy)
- Migration: Alembic
- Package Manager: uv
- Code Quality: ruff, mypy
ruff format .
ruff check .mypy src/# ๋ง์ด๊ทธ๋ ์ด์
์์ฑ
alembic revision --autogenerate -m "description"
# ๋ง์ด๊ทธ๋ ์ด์
์ ์ฉ
alembic upgrade head