Django 프로젝트 구조와 명령어 완벽 가이드

Django 프로젝트 구조와 명령어 완벽 가이드

Django로 웹 개발을 시작할 때 가장 먼저 마주하는 것이 바로 프로젝트 구조와 각종 명령어들이다. Django 프로젝트의 기본 구조와 각 파일의 역할, 그리고 자주 사용하는 명령어들을 상세히 정리해보자.

 

프로젝트 생성: django-admin startproject

Django 프로젝트를 생성하는 첫 번째 단계다.

django-admin startproject config .

명령어 분석

• django-admin: Django가 설치되면 제공되는 커맨드라인 도구. 프로젝트/앱 생성, DB 마이그레이션, 서버 실행 등을 할 수 있음
• startproject: 새로운 Django 프로젝트(settings, wsgi 등 포함된 기본 구조)를 생성하는 서브커맨드
• config: 사용자가 지정하는 프로젝트 이름. Django는 이 이름으로 디렉터리와 설정 모듈들을 만듦
• .: 현재 디렉토리를 프로젝트 루트로 사용하겠다는 뜻

추천 사용법

# 현재 디렉토리를 프로젝트 루트로 사용
django-admin startproject config .

# 결과 구조
myproject/           # 프로젝트 루트
├── config/          # 설정 모듈 폴더
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── asgi.py
│   └── wsgi.py
└── manage.py

 

프로젝트 핵심 파일들

manage.py

Django 프로젝트의 명령어 컨트롤 타워다. 개발자가 Django 명령어를 실행할 수 있게 도와주는 진입점 스크립트.

# 주요 명령어들
python manage.py runserver          # 개발 서버 실행
python manage.py startapp [앱이름]  # 새 앱 생성
python manage.py makemigrations     # 모델 변경 사항을 기록
python manage.py migrate            # DB에 실제 반영
python manage.py createsuperuser    # 관리자 계정 생성
python manage.py shell              # Django 환경에서 Python 셸 열기
python manage.py test               # 테스트 실행
python manage.py collectstatic      # 정적 파일 수집

settings.py

Django 프로젝트 전체의 설정을 담당하는 핵심 파일.

주요 설정 항목:

• INSTALLED_APPS: 사용할 앱들 등록
• DATABASES: DB 연결 정보 설정
• STATIC_URL/MEDIA_URL: 정적 파일(CSS, JS) 위치 지정
• SECRET_KEY: 보안 관련 설정
• DEBUG: 디버그 모드 설정
• ALLOWED_HOSTS: 허용된 호스트 도메인

# config/settings.py 예시
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'collector',  # 우리가 만든 앱 등록
]

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

urls.py

사용자가 웹에서 요청한 주소(URL)가 어떤 기능(뷰)으로 연결되는지 정의하는 URL 라우팅 설정 파일.

# config/urls.py
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('collector.urls')),
]

wsgi.py & asgi.py

• wsgi.py: 동기 방식의 운영 서버가 Django를 실행할 때 진입점
• asgi.py: 비동기 서버가 Django를 실행할 때 진입점

배포 환경에서 Gunicorn, uWSGI(WSGI) 또는 Daphne, Uvicorn(ASGI) 같은 서버가 이 파일을 통해 Django 앱을 실행한다.

 

앱 생성: python manage.py startapp

Django에서 앱(App)은 하나의 기능 단위다. 예를 들어 블로그 기능, 게시판 기능, 사용자 인증 기능 등이 각각의 앱이 될 수 있다.

python manage.py startapp collector

앱 구조

collector/
├── __init__.py      # 파이썬 패키지 표시
├── admin.py         # 관리자 페이지 설정
├── apps.py          # 앱 구성 정보
├── migrations/      # DB 마이그레이션 파일
│   └── __init__.py
├── models.py        # 데이터베이스 모델
├── views.py         # 비즈니스 로직
└── tests.py         # 테스트 코드

중요: 앱 등록

앱을 생성한 후에는 반드시 settings.py의 INSTALLED_APPS에 등록해야 Django가 인식한다.

# config/settings.py
INSTALLED_APPS = [
    # ... 기본 앱들
    'collector',  # 새로 만든 앱 추가
]

 

앱의 주요 파일들

models.py

데이터베이스 테이블 구조를 정의하는 곳. 클래스 형태로 작성하면 Django가 자동으로 SQL로 변환한다.

# collector/models.py
from django.db import models

class Article(models.Model):
    title = models.CharField(max_length=200)
    content = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    def __str__(self):
        return self.title

모듈화 팁: models.py가 커지면 models/ 폴더로 변환 가능

models/
├── __init__.py
├── article.py
├── user.py
└── comment.py

views.py

사용자 요청을 받아서 응답을 생성하는 핵심 로직을 담당한다.

# collector/views.py
from django.shortcuts import render
from .models import Article

def article_list(request):
    articles = Article.objects.all()
    return render(request, 'collector/article_list.html', {
        'articles': articles
    })

모듈화 팁: views.py도 views/ 폴더로 변환 가능

admin.py

Django의 관리자 페이지에 모델을 등록해서 GUI로 데이터를 관리할 수 있게 한다.

# collector/admin.py
from django.contrib import admin
from .models import Article

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ['title', 'created_at']
    search_fields = ['title', 'content']
    list_filter = ['created_at']

apps.py

앱의 메타 정보가 들어있는 설정 클래스. 앱 이름, 경로 등을 Django 내부에서 식별할 수 있게 한다.

# collector/apps.py
from django.apps import AppConfig

class CollectorConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'collector'
    verbose_name = '데이터 수집기'  # 관리자 페이지에서 보이는 이름

migrations/ 폴더

모델이 바뀔 때마다 자동으로 변경 이력을 저장하는 곳. DB와 모델을 동기화할 때 사용된다.

# 마이그레이션 생성 및 적용
python manage.py makemigrations  # 변경사항 감지 및 파일 생성
python manage.py migrate         # 실제 DB에 반영

tests.py

앱의 기능이 잘 동작하는지 자동으로 확인하는 단위 테스트 코드를 작성하는 곳.

# collector/tests.py
from django.test import TestCase
from .models import Article

class ArticleTestCase(TestCase):
    def test_article_creation(self):
        article = Article.objects.create(
            title="테스트 제목",
            content="테스트 내용"
        )
        self.assertEqual(article.title, "테스트 제목")

templates/ 폴더

실제 사용자에게 보여줄 HTML 화면을 담당한다. 별도로 생성해야 한다.

권장 구조

collector/
└── templates/
    └── collector/      # 앱 이름으로 한 번 더 감싸기
        ├── article_list.html
        └── article_detail.html

왜 앱 이름을 두 번 적나?

Django의 템플릿 로딩 방식이 전체 프로젝트의 모든 앱을 한 번에 스캔하기 때문에, 템플릿 이름이 겹칠 수 있다. 이를 방지하기 위해 templates/앱이름/파일.html 구조를 권장한다.

# views.py에서 템플릿 호출 시
return render(request, 'collector/article_list.html', context)

 

추가 폴더들

static/ 폴더

CSS, JavaScript, 이미지 등 정적 파일을 저장하는 곳.

collector/
└── static/
    └── collector/
        ├── css/
        ├── js/
        └── images/

utils/ 폴더

앱에서 공통적으로 쓰이는 헬퍼 함수나 유틸리티를 정리하는 폴더.

# collector/utils/validators.py
def validate_email(email):
    # 이메일 검증 로직
    pass

 

settings.py vs models.py 차이점

• settings.py의 DATABASES: DB 연결 설정 (어떤 DB를 사용하고, 어디에 있는지)
• models.py: DB에 어떤 테이블을 만들지 정의 (테이블 구조)

# settings.py - DB 연결 정보
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mydb',
        'USER': 'myuser',
        'PASSWORD': 'mypassword',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

# models.py - 테이블 구조
class User(models.Model):
    username = models.CharField(max_length=100)
    email = models.EmailField()

 

Django 앱 간의 관계

• Django의 여러 앱들은 하나의 공통 데이터베이스를 공유한다
• 서로 다른 앱에서 동일한 모델(테이블)에 대해 읽기/쓰기 작업이 가능하다
• 앱 간에 모델을 import해서 사용할 수 있다

# blog/models.py
from users.models import User

class Post(models.Model):
    author = models.ForeignKey(User, on_delete=models.CASCADE)
    title = models.CharField(max_length=200)

 

Django의 프로젝트 구조는 처음에는 복잡해 보일 수 있지만, 각 파일과 폴더가 명확한 역할을 가지고 있다. 이러한 구조를 이해하면 Django로 효율적인 웹 개발이 가능하다.

핵심은 프로젝트는 전체 웹사이트를 의미하고, 앱은 그 안의 기능 단위라는 것을 기억하는 것이다. 그리고 각 앱은 독립적으로 개발하되, 필요시 서로 협력할 수 있는 구조로 설계하는 것이 좋다.