[Django] ModelForm: 모델 기반 폼 자동 생성

Django ModelForm, model form, Meta.fields, Meta.exclude, ModelForm save, clean_field

정의

ModelForm = Model 로부터 Form 자동 생성. 필드 반복 정의 없이 CRUD 폼 완성.

일반 Form 은 django-forms 참고.

왜 ModelForm?

# ❌ 일반 Form: 필드 중복 정의
class UserForm(forms.Form):
    name = forms.CharField(max_length=100)
    email = forms.EmailField()
    age = forms.IntegerField(min_value=0)

    def save(self):
        # 직접 model 저장 코드...

# ✓ ModelForm: 자동
class UserForm(forms.ModelForm):
    class Meta:
        model = User
        fields = ['name', 'email', 'age']

# form.save() 자동 지원!

기본 사용

from django import forms
from .models import Article

class ArticleForm(forms.ModelForm):
    class Meta:
        model = Article
        fields = ['title', 'body', 'category', 'tags']
        widgets = {
            'body': forms.Textarea(attrs={'rows': 20}),
        }
        labels = {
            'title': '제목',
            'body': '본문',
        }
        help_texts = {
            'title': '100자 이내',
        }
        error_messages = {
            'title': {
                'required': '제목은 필수입니다',
                'max_length': '제목이 너무 길어요',
            },
        }

fields vs exclude

class Meta:
    model = User
    fields = ['name', 'email']          # 명시적 화이트리스트 (권장)
    # 또는
    fields = '__all__'                   # 모든 필드 (위험!)
    # 또는
    exclude = ['password', 'is_staff']   # 블랙리스트 (위험!)

View 에서 사용

def create_article(request):
    if request.method == 'POST':
        form = ArticleForm(request.POST)
        if form.is_valid():
            article = form.save()   # DB 저장 후 instance 반환
            return redirect('article_detail', pk=article.pk)
    else:
        form = ArticleForm()
    return render(request, 'article_form.html', {'form': form})


def edit_article(request, pk):
    article = get_object_or_404(Article, pk=pk)
    if request.method == 'POST':
        form = ArticleForm(request.POST, instance=article)   # ← 편집!
        if form.is_valid():
            form.save()
            return redirect('article_detail', pk=article.pk)
    else:
        form = ArticleForm(instance=article)
    return render(request, 'article_form.html', {'form': form})

save(commit=False)

저장 전 수정:

if form.is_valid():
    article = form.save(commit=False)
    article.author = request.user          # 현재 사용자 자동 지정
    article.status = 'draft'
    article.save()                          # 이제 DB에
    form.save_m2m()                         # ManyToMany 별도 저장!

Custom Validation

class ArticleForm(forms.ModelForm):
    class Meta:
        model = Article
        fields = ['title', 'body', 'publish_date']

    def clean_title(self):
        title = self.cleaned_data['title']
        if Article.objects.filter(title=title).exclude(pk=self.instance.pk).exists():
            raise forms.ValidationError('이미 존재하는 제목입니다')
        return title

    def clean(self):
        cleaned_data = super().clean()
        publish_date = cleaned_data.get('publish_date')
        if publish_date and publish_date < timezone.now():
            self.add_error('publish_date', '과거로 예약할 수 없습니다')
        return cleaned_data

자세한 form 검증은 django-forms.

Class-Based View 와 함께

from django.views.generic.edit import CreateView, UpdateView

class ArticleCreateView(CreateView):
    model = Article
    form_class = ArticleForm
    template_name = 'article_form.html'
    success_url = '/articles/'

    def form_valid(self, form):
        form.instance.author = self.request.user
        return super().form_valid(form)

class ArticleUpdateView(UpdateView):
    model = Article
    form_class = ArticleForm
    template_name = 'article_form.html'

자세한 CBV 는 django-views, django-mixins.

Template 렌더링

<form method="post">
  {% csrf_token %}
  {{ form.as_p }}                    <!-- 각 필드 <p> 로 -->
  <button type="submit">저장</button>
</form>

<!-- 또는 필드 단위 -->
<form method="post">
  {% csrf_token %}
  <div>
    <label for="{{ form.title.id_for_label }}">제목</label>
    {{ form.title }}
    {{ form.title.errors }}
  </div>
  <button>저장</button>
</form>

Django 6.0 의 새 template 문법:

{{ form.as_field_group }}    <!-- 필드 그룹으로 (6.0+) -->

필드 override

class ArticleForm(forms.ModelForm):
    # 모델 필드보다 우선
    title = forms.CharField(
        max_length=200,
        widget=forms.TextInput(attrs={'class': 'form-control'}),
    )

    class Meta:
        model = Article
        fields = ['title', 'body']

Formset (여러 개 동시)

자세한 건 django-formsets.

다른 프레임워크

Framework	모델 기반 폼
Django	ModelForm
Rails	form_with model: (helper)
Spring	@ModelAttribute + Jakarta Validation
FastAPI	Pydantic + response_model

흔한 함정

관련 위키

• django-forms
• django-formsets
• django-models-fields
• django-views (CBV)