프로젝트 구조

Django 프로젝트는 정해진 폴더 구조와 이름 규칙을 따릅니다. 규칙을 알면 처음 보는 Django 코드도 어디에 무엇이 있는지 금방 찾을 수 있습니다. 이 장에서는 프로젝트와 앱의 파일, 설정 파일, 그리고 자주 쓰는 관례를 살펴봅니다.

프로젝트와 앱의 파일

django-admin startproject mysite .와 python manage.py startapp polls를 실행하면 다음과 같은 구조가 생깁니다.

mysite-project/
    manage.py
    mysite/
        __init__.py
        settings.py
        urls.py
        asgi.py
        wsgi.py
    polls/
        __init__.py
        admin.py
        apps.py
        models.py
        tests.py
        views.py
        migrations/
            __init__.py

urls.py, forms.py, templates/, static/은 startapp이 만들지 않으므로 필요할 때 직접 추가합니다.

템플릿과 정적 파일의 위치

Django는 기본적으로 각 앱의 templates/와 static/ 폴더에서 파일을 찾습니다. 이름이 겹치지 않도록 앱 이름으로 한 단계 더 감싸는 것이 관례입니다.

polls/
    templates/
        polls/
            index.html
            detail.html
    static/
        polls/
            style.css

이렇게 두면 뷰에서는 "polls/index.html", 템플릿에서는 {% static 'polls/style.css' %}처럼 앱 이름이 들어간 경로로 가리킵니다. 여러 앱이 함께 쓰는 공용 템플릿(예: base.html)은 프로젝트 루트의 templates/ 폴더에 두고 설정의 DIRS에 추가합니다.

settings.py 살펴보기

settings.py는 평범한 파이썬 모듈입니다. 자주 손대는 항목은 다음과 같습니다.

# mysite/settings.py (일부)
from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

SECRET_KEY = "개발용-임시-키"
DEBUG = True
ALLOWED_HOSTS = []

DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.sqlite3",
        "NAME": BASE_DIR / "db.sqlite3",
    }
}

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

LANGUAGE_CODE = "ko-kr"
TIME_ZONE = "Asia/Seoul"
USE_TZ = True

STATIC_URL = "static/"
DEFAULT_AUTO_FIELD = "django.db.models.BigAutoField"

BASE_DIR는 manage.py가 있는 폴더입니다. USE_TZ = True이면 데이터베이스에는 UTC로 저장하고 화면에 보여 줄 때 TIME_ZONE으로 바꿉니다. DEFAULT_AUTO_FIELD는 모델에 기본 키를 따로 적지 않았을 때 쓰는 자동 증가 필드의 종류입니다.

환경마다 다른 설정 나누기

SECRET_KEY나 데이터베이스 비밀번호를 코드에 그대로 두면 안 됩니다. 가장 간단한 방법은 환경 변수에서 읽는 것입니다.

# mysite/settings.py
import os

SECRET_KEY = os.environ.get("DJANGO_SECRET_KEY", "개발용-임시-키")
DEBUG = os.environ.get("DJANGO_DEBUG", "") == "1"
ALLOWED_HOSTS = os.environ.get("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1").split(",")

설정이 많아지면 settings/ 패키지로 나눠 base.py, dev.py, prod.py를 두고, 실행할 때 DJANGO_SETTINGS_MODULE 환경 변수로 고르는 방식도 많이 씁니다. django-environ 같은 패키지를 쓰면 .env 파일에서 값을 읽을 수 있습니다.

# 운영 설정으로 관리 명령 실행
DJANGO_SETTINGS_MODULE=mysite.settings.prod python manage.py check --deploy

manage.py로 쓰는 명령

앱에 management/commands/ 폴더를 만들고 BaseCommand를 상속한 클래스를 두면 직접 만든 명령도 같은 방식으로 실행할 수 있습니다.

정리

• 프로젝트 폴더에는 manage.py와 설정 패키지가, 앱 폴더에는 모델·뷰·관리자·마이그레이션이 들어갑니다.
• 템플릿과 정적 파일은 앱 이름 폴더로 한 번 더 감싸 이름 충돌을 피합니다.
• 비밀 값은 환경 변수로 넘기고, 필요하면 설정을 개발·운영용으로 나눕니다.
• 반복 작업은 manage.py 명령과 직접 만든 관리 명령으로 처리합니다.