김신건의 로그 - 위키 / django

[DRF] Filtering: django-filter, SearchFilter, OrderingFilter

koa (김신건) — Wed, 01 Jul 2026 00:00:00 GMT

정의

Filtering = 쿼리 파라미터로 결과 제한. 3가지 backend + custom.

3가지 내장 Backend

flowchart TD
    Q{Filter Backend}
    Q --> DF["DjangoFilterBackend<br/>(django-filter, 완전 필터)"]
    Q --> SF["SearchFilter<br/>(전문 검색 like)"]
    Q --> OF["OrderingFilter<br/>(정렬)"]

설치 + 설정

pip install django-filter

INSTALLED_APPS = [..., 'django_filters']

REST_FRAMEWORK = {
    'DEFAULT_FILTER_BACKENDS': [
        'django_filters.rest_framework.DjangoFilterBackend',
        'rest_framework.filters.SearchFilter',
        'rest_framework.filters.OrderingFilter',
    ]
}

1. DjangoFilterBackend

간단한 필드 매칭

class ArticleList(generics.ListAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    filterset_fields = ['author', 'category', 'is_published']

GET /articles/?author=1&category=tech&is_published=true

상세 FilterSet

import django_filters

class ArticleFilter(django_filters.FilterSet):
    title = django_filters.CharFilter(lookup_expr='icontains')
    min_views = django_filters.NumberFilter(field_name='views', lookup_expr='gte')
    max_views = django_filters.NumberFilter(field_name='views', lookup_expr='lte')
    published_after = django_filters.DateFilter(field_name='published_at', lookup_expr='gte')
    tag = django_filters.CharFilter(method='filter_tag')
    ordering = django_filters.OrderingFilter(
        fields=(
            ('title', 'title'),
            ('views', 'views'),
            ('published_at', 'published_at'),
        )
    )

    class Meta:
        model = Article
        fields = ['author', 'category']

    def filter_tag(self, queryset, name, value):
        return queryset.filter(tags__name__iexact=value)


class ArticleList(generics.ListAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    filterset_class = ArticleFilter

GET /articles/?title=django&min_views=100&published_after=2026-01-01&tag=python

Lookup expressions

Lookup	의미
`exact` (기본)	`field=x` → WHERE field = x
`iexact`	대소문자 무시
`contains` / `icontains`	LIKE
`startswith` / `endswith`	prefix/suffix
`gt`, `gte`, `lt`, `lte`	크기 비교
`in`	field__in
`range`	범위
`date`, `year`, `month`, `week`	날짜 부분
`isnull`	NULL 여부
`regex` / `iregex`	정규식

class ArticleList(generics.ListAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    filter_backends = [filters.SearchFilter]
    search_fields = ['title', 'body', 'author__username', 'tags__name']

GET /articles/?search=django+rest

Prefix 조정

Prefix	의미
없음	`icontains` (기본)
`^`	`istartswith`
`=`	`iexact`
`@`	`full text search` (Postgres)
`$`	`iregex`

search_fields = ['=username', '^title', '@body']

3. OrderingFilter

class ArticleList(generics.ListAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    filter_backends = [filters.OrderingFilter]
    ordering_fields = ['created_at', 'views', 'title']
    ordering = ['-created_at']       # 기본 정렬

GET /articles/?ordering=-views
GET /articles/?ordering=title,-views    # 다중

다중 Backend 조합

class ArticleList(generics.ListAPIView):
    queryset = Article.objects.all()
    serializer_class = ArticleSerializer
    filter_backends = [
        DjangoFilterBackend,
        filters.SearchFilter,
        filters.OrderingFilter,
    ]
    filterset_class = ArticleFilter
    search_fields = ['title', 'body']
    ordering_fields = ['created_at', 'views']

GET /articles/?category=tech&search=django&ordering=-views

Custom Filter Backend

from rest_framework import filters

class IsOwnerFilterBackend(filters.BaseFilterBackend):
    def filter_queryset(self, request, queryset, view):
        return queryset.filter(owner=request.user)


class ArticleList(generics.ListAPIView):
    filter_backends = [IsOwnerFilterBackend, ...]

PostgreSQL Full-Text Search

from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank

class ArticleList(generics.ListAPIView):
    serializer_class = ArticleSerializer

    def get_queryset(self):
        q = self.request.query_params.get('q', '')
        if q:
            vector = SearchVector('title', weight='A') + SearchVector('body', weight='B')
            query = SearchQuery(q)
            return Article.objects.annotate(
                rank=SearchRank(vector, query),
            ).filter(rank__gte=0.1).order_by('-rank')
        return Article.objects.all()

자세한 건 [[postgresql]] 의 full-text.

OpenAPI 문서화

django-filter 는 OpenAPI schema 자동:

filterset_class = ArticleFilter
# → OpenAPI 에 파라미터 자동 추가

자세한 건 [[drf-schemas-openapi]].

다른 프레임워크

Framework	필터링
DRF	django-filter, SearchFilter
Rails	ransack, filterrific
Spring Data	Specification, Querydsl
FastAPI	수동 Query params
NestJS	nestjs-typeorm-crud

흔한 함정

[!WARNING]

filter_fields (옛 이름) = deprecated. filterset_fields.

큰 filterset_class + 많은 필드 = OpenAPI schema 폭발.

search_fields 에 큰 컬럼 = 매 요청 full-table scan. GIN 인덱스.

ordering 사용자 입력 신뢰 = 임의 필드 정렬 → 성능. ordering_fields 화이트리스트.

[DRF] Schemas + OpenAPI: 자동 문서화

koa (김신건) — Wed, 01 Jul 2026 00:00:00 GMT

정의

OpenAPI (전 Swagger) = REST API를 기계 가독 스펙으로 기술하는 표준. DRF는 이 스펙을 ViewSet / Serializer 로부터 자동 추출할 수 있어, Postman 없이 브라우저에서 API를 탐색 + 실행 가능.

이 페이지는 DRF Documenting your API 를 기반으로, 실무에서 자주 쓰는 drf-spectacular 를 중심으로 정리한다.

왜 API 문서화가 필요한가

flowchart LR
    NoDoc["문서 없음"] --> A1["프론트, Postman 매번 시도"]
    NoDoc --> A2["백엔드, Slack으로 스펙 공유"]
    NoDoc --> A3["변경 시 fault 전파, 늦게 발견"]

    Doc["OpenAPI 문서"] --> B1["프론트, 자동 완성 + type 생성"]
    Doc --> B2["QA, 자동 테스트 케이스 생성"]
    Doc --> B3["변경 즉시 감지 (CI)"]

목적	얻는 것
탐색	브라우저에서 endpoint 목록 + 파라미터 확인
테스트	Try it out 으로 즉시 호출
타입 생성	TypeScript, Kotlin 등 client SDK 자동 생성
계약 (Contract)	프론트/백 합의된 스펙, breaking change 방지
온보딩	신규 개발자 학습 시간 단축

도구 선택

flowchart TD
    Q{DRF 문서화 도구}
    Q --> Spec["drf-spectacular ★ 사실상 표준"]
    Q --> Yasg["drf-yasg (legacy, 유지보수 저조)"]
    Q --> Native["DRF 내장 (제한적)"]

도구	상태	특징
drf-spectacular	활발	OpenAPI 3.1, type hint 인식, Sane defaults
drf-yasg	deprecated 권장	OpenAPI 2.0, 여전히 인기 있지만 3.1 미지원
DRF 내장 SchemaGenerator	기본 포함	OpenAPI 3.0 하지만 커스텀 어려움
coreapi (2020 이전)	사용 금지	DRF 3.10에서 제거됨

[!TIP] 2026년 현재 drf-spectacular 를 기본으로 선택하는 것이 안전. drf-yasg 는 유지보수 프로젝트만.

drf-spectacular 설치 (5분 완성)

pip install drf-spectacular

# settings.py
INSTALLED_APPS = [
    ...,
    'rest_framework',
    'drf_spectacular',
]

REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'My API',
    'DESCRIPTION': '내 서비스 REST API 문서',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,   # /api/schema/ 자체는 문서에서 숨김
    'COMPONENT_SPLIT_REQUEST': True, # request/response schema 분리
}

# urls.py
from drf_spectacular.views import (
    SpectacularAPIView,
    SpectacularSwaggerView,
    SpectacularRedocView,
)

urlpatterns = [
    ...,
    # OpenAPI 3.1 스펙 (JSON/YAML)
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),

    # 두 종류 UI (원하는 것 하나만 쓰거나 둘 다)
    path('api/docs/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
    path('api/redoc/', SpectacularRedocView.as_view(url_name='schema'), name='redoc'),
]

브라우저에서 http://localhost:8000/api/docs/ 접속 → Swagger UI 자동 렌더링.

Swagger UI vs Redoc

flowchart TD
    Q{UI 선택}
    Q --> S["Swagger UI"]
    Q --> R["Redoc"]

    S --> S1["Try it out 지원 (실제 호출)"]
    S --> S2["개발자 도구 스타일"]

    R --> R1["3열 레이아웃, 읽기 편함"]
    R --> R2["문서/스펙 공유용에 적합"]

항목	Swagger UI	Redoc
스타일	아코디언	3열, 문서 스타일
Try it out	예	아니오
검색	예	예
커스텀 CSS	부분적	자유
용도	개발자 테스트	외부 공개 문서

자동 추출 되는 것

DRF ViewSet + Serializer 만 잘 짜면 아래가 자동 문서화:

class UserViewSet(viewsets.ModelViewSet):
    """유저 리소스 관리."""      # ← 이 docstring이 태그 description
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]
    filterset_fields = ['is_staff', 'is_active']
    search_fields = ['username', 'email']

    @action(detail=True, methods=['post'])
    def deactivate(self, request, pk=None):
        """유저 비활성화."""      # ← action의 description
        ...

자동 추출되는 요소:

Endpoint 경로 ← Router URL
HTTP method ← list/create/retrieve/…
Request body schema ← Serializer fields
Response schema ← Serializer fields
Query params ← filterset_fields, search_fields, ordering_fields
Path params ← <int:pk> etc.
Authentication ← authentication_classes
Description ← docstring

`@extend_schema` 로 커스터마이즈

from drf_spectacular.utils import extend_schema, OpenApiParameter, OpenApiExample

class UserViewSet(viewsets.ModelViewSet):

    @extend_schema(
        summary='유저 검색',
        description='이름 또는 이메일로 유저를 검색합니다. 최소 2자 이상 필요.',
        parameters=[
            OpenApiParameter(
                name='q',
                type=str,
                location=OpenApiParameter.QUERY,
                description='검색어',
                required=True,
            ),
        ],
        responses={
            200: UserSerializer(many=True),
            400: OpenApiExample(name='잘못된 요청', value={'detail': '검색어 부족'}),
        },
        tags=['users'],
    )
    @action(detail=False, methods=['get'])
    def search(self, request):
        ...

주요 인자:

summary = endpoint 한 줄 요약
description = 긴 설명 (Markdown 지원)
parameters = query/header/path param 명시
request = request body serializer
responses = status code별 응답 serializer
tags = 그룹핑
deprecated = 곧 제거 예정 표시
exclude = 문서에서 숨김

Enum 필드 문서화

from drf_spectacular.utils import extend_schema_field
from drf_spectacular.types import OpenApiTypes

class UserSerializer(serializers.ModelSerializer):
    role = serializers.ChoiceField(
        choices=['admin', 'user', 'guest'],
        help_text='유저 역할',
    )

DRF ChoiceField → OpenAPI enum 으로 자동 변환.

Nested Serializer 문서화

class ProfileSerializer(serializers.ModelSerializer):
    class Meta:
        model = Profile
        fields = ['bio', 'avatar_url']

class UserSerializer(serializers.ModelSerializer):
    profile = ProfileSerializer(read_only=True)      # ← nested schema 자동 추론

    class Meta:
        model = User
        fields = ['id', 'username', 'profile']

SerializerMethodField 타입 힌트

class UserSerializer(serializers.ModelSerializer):
    is_online = serializers.SerializerMethodField()

    @extend_schema_field(OpenApiTypes.BOOL)     # ← 타입 힌트 없으면 unknown
    def get_is_online(self, obj):
        return obj.last_seen and (now() - obj.last_seen).seconds < 300

[!WARNING] SerializerMethodField 는 반환 타입이 문서에 나오지 않는다. @extend_schema_field 로 명시.

인증 문서화

SPECTACULAR_SETTINGS = {
    ...,
    'SECURITY': [{'jwtAuth': []}],
    'APPEND_COMPONENTS': {
        'securitySchemes': {
            'jwtAuth': {
                'type': 'http',
                'scheme': 'bearer',
                'bearerFormat': 'JWT',
            },
        },
    },
}

Swagger UI 우측 상단 “Authorize” 버튼으로 JWT 토큰 입력 → 이후 요청에 자동 헤더 추가.

자세한 인증 방식은 [[drf-authentication]].

여러 개 응답 (union)

@extend_schema(
    responses={
        200: UserSerializer,
        202: OpenApiExample(name='pending', value={'status': 'pending'}),
        400: OpenApiExample(name='invalid', value={'detail': 'error'}),
        429: OpenApiExample(name='throttled', value={'detail': 'Rate limit'}),
    }
)
def create(self, request):
    ...

요청 예시

from drf_spectacular.utils import OpenApiExample, extend_schema

@extend_schema(
    examples=[
        OpenApiExample(
            'Simple case',
            summary='간단한 유저 생성',
            description='기본 필드만 사용',
            value={'username': 'koa', 'email': 'koa@example.com'},
            request_only=True,
        ),
        OpenApiExample(
            'With profile',
            value={'username': 'koa', 'email': 'koa@example.com', 'profile': {'bio': '개발자'}},
            request_only=True,
        ),
    ]
)
def create(self, request):
    ...

Swagger UI에서 예시 드롭다운으로 선택 가능.

Serializer 재사용 (같은 이름 충돌 방지)

class UserCreateSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['username', 'email', 'password']

class UserReadSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'username', 'email']


class UserViewSet(ModelViewSet):
    queryset = User.objects.all()

    def get_serializer_class(self):
        if self.action == 'create':
            return UserCreateSerializer
        return UserReadSerializer

drf-spectacular 는 자동으로 두 스키마를 UserCreate / UserRead 로 분리 문서화.

Schema 파일 export

# YAML로 저장 (버전 관리)
python manage.py spectacular --file schema.yml

# 검증
python manage.py spectacular --validate --file schema.yml

CI에 넣어두면 스펙 breaking change 를 조기 감지.

Client SDK 자동 생성

OpenAPI 스펙만 있으면 다양한 언어 client 를 코드 생성:

# TypeScript
npx openapi-typescript schema.yml -o api-types.ts

# Kotlin
openapi-generator-cli generate -i schema.yml -g kotlin -o ./kotlin-client

프론트에서:


type UserResponse = paths['/api/users/{id}/']['get']['responses']['200']['content']['application/json'];

백엔드 스펙과 프론트 타입이 자동 동기화. Breaking change → 컴파일 에러.

다른 프레임워크 문서화 대응

도구	자동 문서화
DRF + drf-spectacular	ViewSet + Serializer 자동
FastAPI	내장 (Pydantic type hint 기반)
Django Ninja	내장 (Pydantic type hint 기반)
NestJS	@nestjs/swagger 데코레이터 명시
Spring Boot	springdoc-openapi 자동
Express	swagger-jsdoc 주석 명시
Rails	rswag, apipie-rails

FastAPI/Ninja 는 type hint 만으로 자동. DRF는 Serializer 정의가 문서 기반.

실무 팁

1. 태그로 그룹핑

class UserViewSet(ModelViewSet):
    ...
    @extend_schema(tags=['User Management'])
    def list(self, request):
        ...

Swagger UI에서 카테고리별 아코디언.

2. CORS 문제

Swagger UI 에서 Try it out 시도 → CORS 에러 자주 발생.

INSTALLED_APPS += ['corsheaders']
MIDDLEWARE = [
    'corsheaders.middleware.CorsMiddleware',
    ...,
]
CORS_ALLOWED_ORIGINS = ['http://localhost:8000']

3. 문서 접근 권한 제한

# 프로덕션은 문서 접근 제한
if not DEBUG:
    urlpatterns = [
        path('api/schema/', permission_required('is_staff')(SpectacularAPIView.as_view())),
    ]

4. 버전별 문서 분리

# v1 / v2 각각 별도 스키마
SPECTACULAR_SETTINGS = {
    'SERVERS': [
        {'url': '/api/v1', 'description': 'v1'},
        {'url': '/api/v2', 'description': 'v2 (신규 권장)'},
    ],
}

자세한 API 버전 관리는 [[drf-versioning-content-negotiation]].

흔한 함정

[!WARNING]

Serializer 없는 endpoint = 문서에 body 안 나옴. @extend_schema(request=...) 명시.

SerializerMethodField 타입 안 명시 = OpenAPI type: unknown. @extend_schema_field.

@action 에 methods 만 명시 = summary/description 없어 문서 초라. docstring 사용.

문서 URL 프로덕션 개방 = 내부 endpoint 노출. 접근 제한 필수.

drf-yasg 를 새 프로젝트에 도입 = OpenAPI 2.0 만 지원. drf-spectacular 사용.

[DRF] Testing: APIClient, APITestCase, force_authenticate

koa (김신건) — Wed, 01 Jul 2026 00:00:00 GMT

정의

DRF의 테스트 도구는 Django TestCase 위에 API 특화 helper 를 얹은 것. APIClient 로 real endpoint 를 호출하거나 APIRequestFactory 로 View 단위 테스트가 가능.

테스트 도구 계층

flowchart TD
    Q{테스트 종류}
    Q --> Unit["단위 (Serializer, custom logic)"]
    Q --> Slice["View 단위 (APIRequestFactory)"]
    Q --> Int["통합 (APIClient, DB 포함)"]
    Q --> E2E["End-to-End (playwright, cypress)"]

    Unit --> U1["빠름 (ms)"]
    Slice --> S1["View 로직만"]
    Int --> I1["실제 URL + DB, 권장"]
    E2E --> E1["프론트 포함, 느림"]

도구	층	속도	DB
`TestCase` + Serializer 직접	단위	ms	아니오 (or 필요 시)
`APIRequestFactory`	View	빠름	아니오 (mock)
`APIClient` (DRF)	통합	중간	예
Django `Client`	통합 (form only)	중간	예

[!TIP] DRF 프로젝트는 APIClient 를 기본으로 쓴다. 실제 URL 라우팅 + 인증 + 응답 렌더링 모두 검증.

설치

pip install pytest pytest-django factory-boy freezegun

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings.test
python_files = tests.py test_*.py

1. APIClient (통합 테스트)

from rest_framework.test import APITestCase
from rest_framework import status

class UserAPITest(APITestCase):
    def setUp(self):
        self.user = User.objects.create_user('koa', password='pw')

    def test_list_users(self):
        self.client.force_authenticate(user=self.user)
        response = self.client.get('/api/users/')
        self.assertEqual(response.status_code, status.HTTP_200_OK)
        self.assertEqual(len(response.data['results']), 1)

    def test_create_requires_auth(self):
        response = self.client.post('/api/users/', {'username': 'new'})
        self.assertEqual(response.status_code, status.HTTP_401_UNAUTHORIZED)

self.client = APIClient 인스턴스.

`force_authenticate` (권장)

# ★ 가장 자주 쓰는 인증 helper
self.client.force_authenticate(user=self.user)
# → JWT 발급, 헤더 첨부 등 우회. 유닛 테스트에 이상적.

self.client.force_authenticate(user=None)  # 로그아웃

DRF 인증 클래스 무시 하고 request.user 를 직접 주입. 가장 빠름.

세션 로그인

self.client.login(username='koa', password='pw')
# 또는
self.client.force_login(self.user)   # Django 스타일

SessionAuthentication 검증까지 하고 싶을 때.

토큰 인증

# TokenAuthentication
token = Token.objects.create(user=self.user)
self.client.credentials(HTTP_AUTHORIZATION=f'Token {token.key}')

# JWTAuthentication
from rest_framework_simplejwt.tokens import RefreshToken
refresh = RefreshToken.for_user(self.user)
self.client.credentials(HTTP_AUTHORIZATION=f'Bearer {refresh.access_token}')

실제 인증 파이프라인 을 통과. E2E 시나리오 검증에 적합.

HTTP 메서드

# GET
response = self.client.get('/api/users/', {'q': 'koa'})    # ?q=koa 자동

# POST (JSON 자동)
response = self.client.post('/api/users/', {'username': 'new'}, format='json')

# PATCH
response = self.client.patch('/api/users/1/', {'username': 'updated'}, format='json')

# DELETE
response = self.client.delete('/api/users/1/')

# 헤더
response = self.client.get('/api/users/', HTTP_X_CUSTOM='value')

[!IMPORTANT] format='json' 명시 권장. 안 하면 form-urlencoded 로 보내져 nested 객체 실패.

응답 검증

def test_get_user(self):
    response = self.client.get('/api/users/1/')

    self.assertEqual(response.status_code, 200)
    self.assertEqual(response.data['username'], 'koa')
    self.assertIn('email', response.data)
    self.assertIsInstance(response.data['groups'], list)

    # 헤더
    self.assertEqual(response['Content-Type'], 'application/json')

    # JSON 직렬화된 문자열
    self.assertEqual(response.json(), {'id': 1, 'username': 'koa', ...})

2. APIRequestFactory (View 단위)

from rest_framework.test import APIRequestFactory

class UserViewTest(TestCase):
    def setUp(self):
        self.factory = APIRequestFactory()
        self.user = User.objects.create_user('koa', password='pw')

    def test_view_directly(self):
        view = UserViewSet.as_view({'get': 'list'})
        request = self.factory.get('/api/users/')
        force_authenticate(request, user=self.user)
        response = view(request)

        self.assertEqual(response.status_code, 200)

URL 라우팅 없이 View 직접 호출. 빠르지만 pipeline 일부만 검증.

3. Serializer 단위 테스트

def test_valid_serializer():
    data = {'username': 'koa', 'email': 'koa@example.com'}
    serializer = UserSerializer(data=data)
    assert serializer.is_valid()
    assert serializer.validated_data['username'] == 'koa'


def test_invalid_email():
    data = {'username': 'koa', 'email': 'not-an-email'}
    serializer = UserSerializer(data=data)
    assert not serializer.is_valid()
    assert 'email' in serializer.errors

4. pytest-django 사용

import pytest

@pytest.fixture
def api_client():
    from rest_framework.test import APIClient
    return APIClient()

@pytest.fixture
def user(db):
    return User.objects.create_user('koa', password='pw')

@pytest.fixture
def auth_client(api_client, user):
    api_client.force_authenticate(user=user)
    return api_client

def test_list_users(auth_client):
    response = auth_client.get('/api/users/')
    assert response.status_code == 200

fixture 조합 이 재사용성 극대화. pytest.ini 의 --reuse-db 로 DB 재생성 없이 반복 실행.

5. Factory Boy (테스트 데이터)

# factories.py
import factory
from django.contrib.auth.models import User

class UserFactory(factory.django.DjangoModelFactory):
    class Meta:
        model = User

    username = factory.Sequence(lambda n: f'user{n}')
    email = factory.LazyAttribute(lambda o: f'{o.username}@example.com')
    is_active = True


# 사용
def test_many_users():
    UserFactory.create_batch(50)
    assert User.objects.count() == 50


# 관계
class ArticleFactory(factory.django.DjangoModelFactory):
    class Meta:
        model = Article
    title = factory.Faker('sentence')
    author = factory.SubFactory(UserFactory)

fixtures/*.json 대신 factory 로 동적 생성.

응답 status code 매트릭스

@pytest.mark.parametrize('user_type,expected_status', [
    ('anonymous', 401),
    ('regular', 403),
    ('admin', 200),
])
def test_admin_endpoint(api_client, user_type, expected_status):
    if user_type == 'regular':
        api_client.force_authenticate(user=UserFactory())
    elif user_type == 'admin':
        api_client.force_authenticate(user=UserFactory(is_staff=True))

    response = api_client.get('/api/admin/stats/')
    assert response.status_code == expected_status

parametrize 로 권한 매트릭스 완전 커버.

권한 테스트 패턴

class PostPermissionTest(APITestCase):
    def setUp(self):
        self.author = UserFactory()
        self.other = UserFactory()
        self.post = Post.objects.create(author=self.author, title='...')

    def test_author_can_delete(self):
        self.client.force_authenticate(self.author)
        response = self.client.delete(f'/api/posts/{self.post.pk}/')
        self.assertEqual(response.status_code, 204)

    def test_other_cannot_delete(self):
        self.client.force_authenticate(self.other)
        response = self.client.delete(f'/api/posts/{self.post.pk}/')
        self.assertEqual(response.status_code, 403)

자세한 권한 개념은 [[django-drf-permissions]].

Throttle 테스트

from django.core.cache import cache

class ThrottleTest(APITestCase):
    def setUp(self):
        cache.clear()   # ★ throttle 카운트 초기화

    def test_burst_limit(self):
        with self.settings(REST_FRAMEWORK={
            'DEFAULT_THROTTLE_RATES': {'login': '2/min'},
        }):
            for _ in range(2):
                self.assertEqual(self.client.post('/api/login/', ...).status_code, 200)
            self.assertEqual(self.client.post('/api/login/', ...).status_code, 429)

[!WARNING] setUp 에서 cache.clear() 필수. 안 하면 이전 테스트 카운트 남음.

시간 조작 (freezegun)

from freezegun import freeze_time

@freeze_time('2026-06-25 12:00:00')
def test_expired_token():
    token = RefreshToken.for_user(user)

    with freeze_time('2026-07-25 12:00:00'):    # 30일 후
        response = api_client.get('/api/me/', HTTP_AUTHORIZATION=f'Bearer {token.access_token}')
        assert response.status_code == 401

JWT 만료, 세션 timeout 등 시간 종속 테스트.

Mocking 외부 API

from unittest.mock import patch

@patch('myapp.services.send_email')
def test_signup_sends_email(mock_send):
    response = api_client.post('/api/signup/', {'email': 'a@b.c'})
    assert response.status_code == 201
    mock_send.assert_called_once_with('a@b.c', ...)

DB Snapshot

def test_no_extra_queries():
    # N+1 감시
    with self.assertNumQueries(3):
        response = self.client.get('/api/articles/')

DRF 응답이 예상보다 많은 쿼리를 하면 실패. Performance regression 방어.

자세한 N+1 개념은 [[django-orm-advanced]].

Coverage 측정

pip install coverage
coverage run -m pytest
coverage report
coverage html    # htmlcov/index.html

목표: serializer/view 는 90%+, permission/utility 는 100%.

다른 프레임워크 테스트 도구

Framework	테스트 도구
DRF	`APIClient`, `APIRequestFactory`, pytest-django
FastAPI	`TestClient` (Starlette)
Spring	MockMvc, `@WebMvcTest`
Rails	ActionDispatch, RSpec, request specs
Express	supertest
NestJS	@nestjs/testing + supertest

흔한 함정

[!WARNING]

format='json' 누락 = form-urlencoded 로 전송, nested 데이터 실패.

cache.clear() 안 함 (Throttle 테스트) = flaky test.

self.client.login() 을 JWT 라우트에 = 세션이라 401. force_authenticate 사용.

setUp 에서 heavy DB 초기화 = 매 테스트마다 실행. fixture 로 격리.

assertEqual(response.data, dict) = OrderedDict 차이로 실패 가능. json.loads(response.content) 로 정규화.

[Django] MTV 패턴과 Model 기본

koa (김신건) — Mon, 29 Jun 2026 00:00:00 GMT

정의

Django 는 MTV (Model, Template, View) 패턴 사용. 다른 프레임워크의 MVC 와 이름만 다르고 개념은 유사.

MVC	Django MTV
Model	Model (ORM)
View	Template
Controller	View (function/class)

Model 정의

from django.db import models

class Post(models.Model):
    title = models.CharField(max_length=200)
    body = models.TextField()
    author = models.ForeignKey('User', on_delete=models.CASCADE)
    created = models.DateTimeField(auto_now_add=True)
    published = models.BooleanField(default=False)

    class Meta:
        ordering = ['-created']

    def __str__(self):
        return self.title

마이그레이션

python manage.py makemigrations
python manage.py migrate

CRUD

Post.objects.create(title="Hello", body="...", author=user)
Post.objects.get(pk=1)
Post.objects.filter(published=True).order_by('-created')[:10]
Post.objects.filter(author=user).update(published=True)
post.delete()

View + Form + Template 흐름

# views.py
def post_create(request):
    if request.method == 'POST':
        form = PostForm(request.POST)
        if form.is_valid():
            post = form.save(commit=False)
            post.author = request.user
            post.save()
            return redirect('post_detail', pk=post.pk)
    else:
        form = PostForm()
    return render(request, 'post_form.html', {'form': form})

Form 이 검증 (validation) + 정제 (cleaning) 담당. form.is_valid() 는 Django 의 binding + validation 관용구.

참고

관련 [[rails-activerecord-basics|Rails ActiveRecord 비교]]
관련 [[django-orm|Django ORM]]

[Django 6.0] Content Security Policy: XSS 방어의 최종형

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Content Security Policy (CSP) = 브라우저에게 어떤 스크립트/스타일/이미지 만 허용 할지 선언. XSS 공격의 마지막 방어선.

Django 6.0 부터 CSP 지원이 내장 (옛 django-csp 서드파티 → Django 표준). 자세한 XSS 는 [[django-security]] 참고.

목적 + 대안

접근	의미
입력 필터링	사용자 입력에서 `<script>` 제거 (완벽하지 않음)
출력 escape	`{% autoescape %}` 로 HTML escape (Django 기본)
CSP	브라우저에게 인라인 스크립트 실행 금지 지시

[!IMPORTANT] CSP 는 다중 방어 의 하나. Escape + Sanitize + CSP 3중 방어가 정통.

CSP Header 구조

Content-Security-Policy:
  default-src 'self';
  script-src 'self' https://cdn.example.com;
  style-src 'self' 'unsafe-inline';
  img-src 'self' data: https:;
  connect-src 'self' https://api.example.com;
  frame-ancestors 'none';
  report-uri /csp-report/

Directive	의미
`default-src`	기본값
`script-src`	JavaScript 허용 원본
`style-src`	CSS
`img-src`	이미지
`connect-src`	fetch, XHR, WebSocket
`font-src`	폰트
`frame-src` / `frame-ancestors`	iframe
`form-action`	form action target
`report-uri`	위반 리포트

Django 6.0 CSP 설정

# settings.py
MIDDLEWARE = [
    ...
    'django.middleware.csp.ContentSecurityPolicyMiddleware',
]

SECURE_CSP = {
    'default-src': ["'self'"],
    'script-src': ["'self'", 'https://cdn.example.com'],
    'style-src': ["'self'", "'unsafe-inline'"],
    'img-src': ["'self'", 'data:', 'https:'],
    'connect-src': ["'self'", 'https://api.example.com'],
    'frame-ancestors': ["'none'"],
    'report-uri': ['/csp-report/'],
}

Report-Only 모드 (안전한 배포)

# 처음 도입 시 report-only 로 시작
SECURE_CSP_REPORT_ONLY = {
    'default-src': ["'self'"],
    'script-src': ["'self'"],
    'report-uri': ['/csp-report/'],
}

브라우저가 위반 감지 시 report 만 전송, 실제 차단 안 함. 로그 분석 후 정식 정책으로 전환.

Nonce 로 인라인 스크립트 허용

# views.py
from django.middleware.csp import get_csp_nonce

def home(request):
    return render(request, 'home.html', {
        'csp_nonce': get_csp_nonce(request),
    })

<script nonce="{{ csp_nonce }}">
  console.log('inline script allowed');
</script>

Header:

Content-Security-Policy: script-src 'self' 'nonce-xyz123abc';

[!TIP] 동적 인라인 스크립트 를 안전하게. 'unsafe-inline' 보다 훨씬 안전.

Hash (정적 인라인)

SECURE_CSP = {
    'script-src': [
        "'self'",
        "'sha256-B2yPHKaXnvFWtRChIbabYmUBFZdVfKKXHbWtWidDVF8='",
    ],
}

특정 인라인 스크립트 hash 계산 후 허용. Nonce 와 달리 정적 스크립트만.

위반 리포트 처리

# views.py
import json
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def csp_report(request):
    if request.method == 'POST':
        report = json.loads(request.body)
        logger.warning('CSP violation: %s', report)
        return HttpResponse(status=204)

{
  "csp-report": {
    "document-uri": "https://example.com/page/",
    "referrer": "",
    "violated-directive": "script-src 'self'",
    "blocked-uri": "https://evil.com/xss.js",
    "line-number": 42
  }
}

Strict CSP (현대 권장)

Google 이 권장하는 strict CSP:

SECURE_CSP = {
    'script-src': ["'strict-dynamic'", "'nonce-{{nonce}}'"],
    'object-src': ["'none'"],
    'base-uri': ["'none'"],
}

strict-dynamic: nonce 통과한 스크립트가 로드한 자원은 자동 허용.
object-src 'none': Flash/plugin 완전 차단.

흔한 함정

[!WARNING]

unsafe-inline 남발 = CSP 의 의미 없음. Nonce 또는 hash 사용.

CDN URL 하드코딩 = CDN 변경 시 앱 다운. 설정 관리.

report-uri 없이 시작 = 위반 파악 못함. 반드시 report 먼저.

'unsafe-eval' 필요 = React 개발 mode 등. Production 은 build 후 제거.

다른 프레임워크

Framework	CSP 지원
Django 6.0+	내장
Django 5.x 이하	django-csp 서드파티
Rails	Rails 5.2+ 내장 (`config.content_security_policy`)
Spring	Spring Security header
Express	helmet.js
Next.js	`next.config.js` headers

[Django 6.0] Tasks Framework: 내장 백그라운드 작업

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django Tasks Framework = Django 6.0 (2025) 도입된 내장 백그라운드 작업 실행 표준. Celery 없이 간단한 async task 를 표준 방식으로.

[!IMPORTANT] Django 진영의 가장 큰 최신 변화. Celery 를 대체하려는 것이 아니라 간단한 task 는 내장, 복잡한 것은 여전히 Celery 라는 layer 분리.

목적 + 대안

flowchart TD
    Q{Task 복잡도}
    Q -->|"간단 (email, log)"| DT["Django Tasks (내장)"]
    Q -->|"중간 (스케줄, retry)"| RQ["django-rq / dramatiq"]
    Q -->|"복잡 (workflow, priority)"| Celery["Celery + Redis/RabbitMQ"]

Option	장점	단점
Django Tasks (6.0+)	표준, zero setup, DB backend	기본 기능만
django-rq	간단, Redis 기반	배포 별도
dramatiq	빠름, retry 강력	옛
Celery	최강, 전체 기능	설정 복잡, 무거움

기본 사용

# tasks.py
from django.tasks import task

@task()
def send_welcome_email(user_id: int):
    from django.core.mail import send_mail
    from myapp.models import User

    user = User.objects.get(pk=user_id)
    send_mail(
        subject='환영합니다!',
        message=f'{user.name}님 가입해주셔서 감사합니다.',
        from_email='noreply@example.com',
        recipient_list=[user.email],
    )

# views.py
from django.contrib.auth import login
from .tasks import send_welcome_email

def signup(request):
    user = User.objects.create_user(...)
    send_welcome_email.enqueue(user.pk)   # 백그라운드로!
    login(request, user)
    return redirect('home')

Backend 설정

# settings.py
TASKS = {
    'default': {
        'BACKEND': 'django.tasks.backends.database.DatabaseBackend',
    },
}

Backend 종류:

Backend	의미
`ImmediateBackend`	동기 실행 (개발)
`DummyBackend`	실행 안 함 (테스트)
`DatabaseBackend`	DB 큐 (기본, 프로덕션 OK)
`RedisBackend` (contrib)	Redis 큐

Worker 실행

# 별도 프로세스로 worker 실행
python manage.py db_worker

sequenceDiagram
    autonumber
    Web->>DB: enqueue task (INSERT tasks 테이블)
    Web-->>User: 즉시 응답
    loop worker 프로세스
        Worker->>DB: SELECT ... FOR UPDATE SKIP LOCKED
        DB-->>Worker: 다음 task
        Worker->>Worker: task 실행
        Worker->>DB: UPDATE status = 'succeeded'
    end

옵션

@task(
    queue='email',              # 큐 이름
    priority=5,                 # 우선순위 (높을수록 먼저)
    backend='default',
)
def send_email(user_id): ...

# enqueue 시 우선순위 override
send_email.using(priority=10, queue='urgent').enqueue(user_id)

# 지연 실행
from datetime import timedelta
send_email.enqueue(user_id, run_after=timedelta(hours=1))

Retry + Error

@task()
def flaky_api_call(url: str):
    response = requests.get(url, timeout=5)
    response.raise_for_status()
    return response.json()

# 실패 시 재시도
result = flaky_api_call.using(
    max_retries=3,
    retry_backoff=True,     # 지수 백오프
).enqueue('https://api.example.com')

결과 확인

result = send_email.enqueue(user.pk)

# 상태 조회
result.refresh()
print(result.status)   # 'ready', 'running', 'succeeded', 'failed'
print(result.enqueued_at)
print(result.started_at)
print(result.finished_at)

# 결과값 (return value)
if result.status == 'succeeded':
    print(result.return_value)
elif result.status == 'failed':
    print(result.errors)

Django Tasks vs Celery

flowchart LR
    subgraph Simple["간단한 case"]
        DT["Django Tasks"] --> DB["DB 큐"]
        DB --> W1["단일 worker"]
    end
    subgraph Complex["복잡한 case"]
        Celery --> RB["Redis / RabbitMQ"]
        RB --> W2["다중 worker fleet"]
        W2 --> Beat["Celery Beat (스케줄)"]
        W2 --> Flower["Flower (모니터링)"]
        W2 --> Chord["Chord / Group / Chain"]
    end

Feature	Django Tasks	Celery
설정	3줄	여러 파일
Broker	DB 또는 Redis	Redis/RabbitMQ/SQS
스케줄	지연 실행만	Celery Beat
Workflow (chain, group)	아니오	예
Priority queue	예	예
Rate limiting	아니오	예
Monitoring	기본	Flower + Prometheus
학습 곡선	매우 낮음	가파름

[!TIP] 새 Django 프로젝트 (6.0+) = 간단한 task 는 Django Tasks. 스케줄, workflow, 대량 처리 는 Celery.

다른 프레임워크 비교

Framework	Task 시스템
Django 6.0+	django.tasks (내장)
Rails	Active Job (내장 표준)
Spring	`@Async`, `@Scheduled`
Laravel	Queue (내장)
FastAPI	`BackgroundTasks` (간단) 또는 Celery
Express	별도 (Bull, agenda)

Rails / Laravel / Django 모두 공통 태스크 API + 여러 backend 패턴. Ruby 진영이 먼저 (2015) → Django 는 10년 뒤 (2025).

Test

# settings 에서 DummyBackend 로 전환
TASKS = {'default': {'BACKEND': 'django.tasks.backends.dummy.DummyBackend'}}

from django.test import TestCase
from django.tasks import default_task_backend

class TaskTest(TestCase):
    def test_signup_enqueues_welcome_email(self):
        response = self.client.post('/signup/', {...})

        # 큐에 들어갔는지 확인
        self.assertEqual(default_task_backend.queue.qsize(), 1)
        task = default_task_backend.queue[0]
        self.assertEqual(task.task_func.__name__, 'send_welcome_email')

흔한 함정

[!WARNING]

Worker 안 띄움 = task 가 DB 에 쌓이지만 실행 안 됨. db_worker 확인.

Task 안에서 request/response 참조 = worker 프로세스에는 request 없음. 필요한 값 인자로 전달.

Serialization 어려운 인자 = model instance 통째로 전달 → pickle 실패. .pk 만 전달 하고 worker 에서 조회.

Transaction 안에서 enqueue = commit 전에 worker 가 조회 → race. transaction.on_commit(lambda: task.enqueue(...)).

[Django] File Uploads + Storage: FileField, ImageField, S3

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django 의 파일 업로드 + 저장 시스템. FileField/ImageField + Storage backend 로 로컬 / S3 / GCS 등 자유롭게.

Model 필드

from django.db import models

def user_avatar_path(instance, filename):
    return f'avatars/{instance.user.id}/{filename}'

class Profile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE)
    avatar = models.ImageField(
        upload_to=user_avatar_path,
        blank=True,
        null=True,
        max_length=200,
    )
    resume = models.FileField(
        upload_to='resumes/%Y/%m/',
        blank=True,
    )

upload_to 는 문자열 또는 함수. 함수는 (instance, filename) → path 반환.

Form + View

# forms.py
class ProfileForm(forms.ModelForm):
    class Meta:
        model = Profile
        fields = ['avatar', 'resume']

# views.py
def upload_profile(request):
    if request.method == 'POST':
        form = ProfileForm(request.POST, request.FILES, instance=request.user.profile)
        # request.FILES 필수!
        if form.is_valid():
            form.save()
            return redirect('profile')
    else:
        form = ProfileForm(instance=request.user.profile)
    return render(request, 'upload.html', {'form': form})

Template

<!-- multipart/form-data 필수! -->
<form method="post" enctype="multipart/form-data">
  {% csrf_token %}
  {{ form.as_p }}
  <button>업로드</button>
</form>

[!CAUTION] enctype="multipart/form-data" 없으면 파일 안 올라감. 잊기 쉬움.

Settings

# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'

# 업로드 크기 한도
FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440   # 2.5MB (메모리)
DATA_UPLOAD_MAX_MEMORY_SIZE = 2621440    # form data 전체
FILE_UPLOAD_HANDLERS = [
    'django.core.files.uploadhandler.MemoryFileUploadHandler',
    'django.core.files.uploadhandler.TemporaryFileUploadHandler',
]

개발 시 media 파일 serve:

# urls.py
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    ...
]
if settings.DEBUG:
    urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

[!IMPORTANT] 프로덕션은 nginx/CloudFront 로 media serve. Django 로 serve = 매우 느림.

Storage Backend

flowchart LR
    Model[FileField] --> Storage[Storage backend]
    Storage --> Local["FileSystemStorage (기본)"]
    Storage --> S3[S3Boto3Storage]
    Storage --> GCS[GoogleCloudStorage]
    Storage --> Azure[AzureStorage]
    Storage --> Custom[Custom storage]

Django 6.0 의 STORAGES 설정

# settings.py (Django 6.0+)
STORAGES = {
    'default': {
        'BACKEND': 'storages.backends.s3.S3Storage',
        'OPTIONS': {
            'bucket_name': 'my-media',
            'region_name': 'us-east-1',
            'location': 'media',
            'default_acl': 'private',
            'file_overwrite': False,
        },
    },
    'staticfiles': {
        'BACKEND': 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage',
    },
}

[!TIP] STORAGES 는 Django 4.2+ 부터. DEFAULT_FILE_STORAGE 는 deprecated.

S3 예시 (django-storages)

pip install django-storages[boto3]

STORAGES = {
    'default': {
        'BACKEND': 'storages.backends.s3.S3Storage',
        'OPTIONS': {
            'bucket_name': env('AWS_S3_BUCKET'),
            'region_name': env('AWS_REGION'),
            'location': 'media',
            'file_overwrite': False,
            'querystring_expire': 3600,   # signed URL expiration
        },
    },
}

S3 자세한 건 [[aws-s3]].

Custom Storage

from django.core.files.storage import Storage

class MyStorage(Storage):
    def _save(self, name, content):
        # 저장 로직
        return saved_name

    def _open(self, name, mode='rb'):
        # 열기 로직
        return file

    def exists(self, name): ...
    def url(self, name): ...
    def size(self, name): ...

Direct Upload (프리사인 URL)

브라우저 → S3 직접 업로드 (서버 우회):

import boto3

def get_presigned_url(request):
    filename = request.GET['filename']
    key = f'uploads/{request.user.id}/{filename}'

    s3 = boto3.client('s3')
    url = s3.generate_presigned_post(
        Bucket='my-bucket',
        Key=key,
        Conditions=[
            ['content-length-range', 0, 10 * 1024 * 1024],
        ],
        ExpiresIn=3600,
    )
    return JsonResponse(url)

// 클라이언트
const {url, fields} = await fetch('/presigned-url/?filename=x.jpg').then(r => r.json());
const formData = new FormData();
Object.entries(fields).forEach(([k, v]) => formData.append(k, v));
formData.append('file', file);
await fetch(url, { method: 'POST', body: formData });

이미지 처리

from PIL import Image

def save(self, *args, **kwargs):
    super().save(*args, **kwargs)
    if self.avatar:
        img = Image.open(self.avatar.path)
        img.thumbnail((300, 300))
        img.save(self.avatar.path)

또는 django-imagekit / easy-thumbnails.

Security

# 파일 형식 검증
def validate_image(value):
    valid_extensions = ['.jpg', '.png', '.webp']
    ext = os.path.splitext(value.name)[1].lower()
    if ext not in valid_extensions:
        raise ValidationError('허용 안 된 형식')

    # MIME type 확인
    import magic
    mime = magic.from_buffer(value.read(2048), mime=True)
    value.seek(0)
    if not mime.startswith('image/'):
        raise ValidationError('이미지가 아닙니다')

class Profile(models.Model):
    avatar = models.ImageField(upload_to='avatars/', validators=[validate_image])

[!CAUTION] 확장자만 검증 = 위험. evil.exe.jpg 통과. python-magic 으로 MIME sniff.

흔한 함정

[!WARNING]

enctype 잊음 = 파일 안 올라감 (silent).

로컬 저장 → 프로덕션 배포 후 사라짐 = 컨테이너 재시작. S3 등 외부 저장.

크기 한도 안 정함 = 100MB 업로드 = OOM. FILE_UPLOAD_MAX_MEMORY_SIZE.

경로 traversal = ../../etc/passwd 같은 filename. Django 는 자동 방어하지만 커스텀 upload_to 는 주의.

다른 프레임워크

Framework	파일 업로드
Django	`FileField` + `request.FILES`
Rails	Active Storage (7+)
Spring	`MultipartFile`
FastAPI	`UploadFile`
Express	multer

[Django] Formsets: 여러 폼 동시 처리

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Formset = 여러 폼을 한 페이지에서 동시 처리. “상품 3개 한 번에 등록”, “주문 상세 여러 줄 편집” 같은 시나리오.

3가지 종류

flowchart TD
    Q{Formset 종류}
    Q --> A["FormSet<br/>(일반 Form 반복)"]
    Q --> B["ModelFormSet<br/>(같은 모델 여러 개)"]
    Q --> C["InlineFormSet<br/>(부모 모델의 자식들)"]

1. 기본 FormSet

from django import forms
from django.forms import formset_factory

class ContactForm(forms.Form):
    name = forms.CharField()
    email = forms.EmailField()

ContactFormSet = formset_factory(
    ContactForm,
    extra=2,        # 빈 폼 개수
    max_num=10,     # 최대 개수
    can_delete=True,
)

def contacts_view(request):
    if request.method == 'POST':
        formset = ContactFormSet(request.POST)
        if formset.is_valid():
            for form in formset:
                if form.cleaned_data.get('DELETE'):
                    continue
                name = form.cleaned_data['name']
                email = form.cleaned_data['email']
                # 저장 로직
    else:
        formset = ContactFormSet()
    return render(request, 'contacts.html', {'formset': formset})

Template + Management Form

<form method="post">
  {% csrf_token %}
  {{ formset.management_form }}   <!-- 필수! -->
  {% for form in formset %}
    <div class="form-row">
      {{ form.as_p }}
    </div>
  {% endfor %}
  <button type="submit">저장</button>
</form>

[!CAUTION] {{ formset.management_form }} 필수 - 폼 개수 등 메타데이터. 안 넣으면 ValidationError.

Management form 이 렌더링:

<input type="hidden" name="form-TOTAL_FORMS" value="2">
<input type="hidden" name="form-INITIAL_FORMS" value="0">
<input type="hidden" name="form-MIN_NUM_FORMS" value="0">
<input type="hidden" name="form-MAX_NUM_FORMS" value="10">

2. ModelFormSet

from django.forms import modelformset_factory

ProductFormSet = modelformset_factory(
    Product,
    fields=('name', 'price', 'stock'),
    extra=1,
    can_delete=True,
)

def products_admin(request):
    if request.method == 'POST':
        formset = ProductFormSet(request.POST, queryset=Product.objects.filter(active=True))
        if formset.is_valid():
            formset.save()
    else:
        formset = ProductFormSet(queryset=Product.objects.filter(active=True))
    return render(request, 'products.html', {'formset': formset})

3. InlineFormSet (부모-자식)

from django.forms import inlineformset_factory

# Author 하나에 여러 Book
BookFormSet = inlineformset_factory(
    Author,          # 부모
    Book,            # 자식
    fields=('title', 'published_at'),
    extra=1,
    can_delete=True,
)

def edit_author(request, author_id):
    author = Author.objects.get(pk=author_id)
    if request.method == 'POST':
        formset = BookFormSet(request.POST, instance=author)
        if formset.is_valid():
            formset.save()   # 자동으로 author 지정!
    else:
        formset = BookFormSet(instance=author)
    return render(request, 'author_books.html', {'author': author, 'formset': formset})

동적 formset (JavaScript)

<form method="post">
  {% csrf_token %}
  {{ formset.management_form }}

  <div id="forms-container">
    {% for form in formset %}
      <div class="form-row">
        {{ form.as_p }}
      </div>
    {% endfor %}
  </div>

  <button type="button" onclick="addForm()">폼 추가</button>
  <button type="submit">저장</button>
</form>

<script>
function addForm() {
  const container = document.getElementById('forms-container');
  const totalForms = document.getElementById('id_form-TOTAL_FORMS');
  const idx = parseInt(totalForms.value);

  const template = container.children[0].outerHTML;
  const newForm = template.replaceAll(`form-0-`, `form-${idx}-`);
  container.insertAdjacentHTML('beforeend', newForm);

  totalForms.value = idx + 1;
}
</script>

Validation

class BaseContactFormSet(forms.BaseFormSet):
    def clean(self):
        """폼셋 전체 검증"""
        if any(self.errors):
            return

        emails = []
        for form in self.forms:
            if form.cleaned_data.get('DELETE'):
                continue
            email = form.cleaned_data.get('email')
            if email in emails:
                raise forms.ValidationError('이메일 중복 금지')
            emails.append(email)

ContactFormSet = formset_factory(
    ContactForm,
    formset=BaseContactFormSet,
    extra=2,
)

Ordering (순서 변경)

ContactFormSet = formset_factory(
    ContactForm,
    extra=2,
    can_order=True,   # ← 순서 변경 UI
)

Django 6.0 개선

{{ formset.non_form_errors }} 렌더링 개선
HTMX 통합 예시 문서 추가
Type hints 강화

다른 프레임워크

Framework	여러 폼 처리
Django	`formset_factory`, `inlineformset_factory`
Rails	`accepts_nested_attributes_for` + `fields_for`
Spring	List binding + `@Valid`
HTMX + Alpine	동적 추가

흔한 함정

[!WARNING]

management form 누락 = ValidationError.

DELETE 무시하고 저장 = 삭제 안 됨. if form.cleaned_data.get('DELETE'): continue.

동적 추가 시 form index 잘못 = server side 검증 실패.

max_num 무시 = 무한 폼 추가 → DoS.

[Django] Messages Framework: flash 메시지

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Messages Framework = 1회성 flash 메시지 (성공, 오류 등) 를 사용자에게 표시. Post/Redirect/Get 패턴에서 필수.

목적 + 대안

flowchart LR
    Q{피드백 방법}
    Q -->|"1회성 알림"| Msg["Messages framework"]
    Q -->|"영구 데이터"| Model["Model + View"]
    Q -->|"에러 폼 유지"| Form["Form errors"]
    Q -->|"실시간 push"| WS["WebSocket / SSE"]

기본 설정

# settings.py
INSTALLED_APPS = [
    ...
    'django.contrib.messages',
    ...
]

MIDDLEWARE = [
    'django.contrib.sessions.middleware.SessionMiddleware',
    ...
    'django.contrib.messages.middleware.MessageMiddleware',
]

TEMPLATES = [{
    'OPTIONS': {
        'context_processors': [
            ...
            'django.contrib.messages.context_processors.messages',
        ],
    },
}]

사용

# views.py
from django.contrib import messages

def create_article(request):
    if request.method == 'POST':
        form = ArticleForm(request.POST)
        if form.is_valid():
            form.save()
            messages.success(request, '게시글이 등록되었어요.')
            return redirect('article_list')
        else:
            messages.error(request, '입력을 확인해주세요.')
    else:
        form = ArticleForm()
    return render(request, 'form.html', {'form': form})

5가지 레벨

함수	레벨
`messages.debug(request, ...)`	DEBUG (10)
`messages.info(request, ...)`	INFO (20)
`messages.success(request, ...)`	SUCCESS (25)
`messages.warning(request, ...)`	WARNING (30)
`messages.error(request, ...)`	ERROR (40)
`messages.add_message(request, level, ...)`	커스텀

Template 표시

<!-- base.html -->
{% if messages %}
<div class="messages">
  {% for message in messages %}
    <div class="alert alert-{{ message.tags }}" role="alert">
      {{ message }}
      <button type="button" class="close" data-dismiss="alert">&times;</button>
    </div>
  {% endfor %}
</div>
{% endif %}

message.tags = success, error, warning 등 CSS 클래스 그대로.

옵션 (Extra tags)

messages.success(
    request,
    '완료!',
    extra_tags='animate-bounce',
    fail_silently=False,
)

{{ message.tags }}  <!-- "success animate-bounce" -->

Level 설정

# settings.py
from django.contrib.messages import constants as message_constants

MESSAGE_LEVEL = message_constants.WARNING   # 이 레벨 이상만 저장

# 특정 request 만
messages.set_level(request, messages.DEBUG)

Storage Backend

Backend	의미
`SessionStorage` (기본)	Django session 에 저장
`CookieStorage`	브라우저 cookie 에 (session-less)
`FallbackStorage` (기본)	Cookie 우선, 크면 session

MESSAGE_STORAGE = 'django.contrib.messages.storage.cookie.CookieStorage'

HTMX 통합 예시

from django.http import HttpResponse

def htmx_action(request):
    do_something()
    messages.success(request, '완료됨')

    if request.htmx:
        response = HttpResponse('OK')
        response['HX-Trigger'] = json.dumps({'showMessages': True})
        return response
    return redirect('home')

<div hx-get="{% url 'messages' %}" hx-trigger="showMessages from:body"></div>

Class-Based View 통합

from django.contrib.messages.views import SuccessMessageMixin

class ArticleCreateView(SuccessMessageMixin, CreateView):
    model = Article
    fields = ['title', 'body']
    success_message = '게시글 "%(title)s" 이 등록되었습니다.'
    success_url = '/articles/'

PRG (Post/Redirect/Get) 패턴

sequenceDiagram
    autonumber
    User->>View: POST /create/
    View->>DB: 저장
    View->>Messages: success('완료!')
    View-->>User: 302 → /list/
    User->>View: GET /list/
    View->>Messages: 꺼내기
    View-->>User: HTML with flash
    Note over User: 새로고침 시 message 없음 (1회성)

Rails 의 flash 와 정확히 동일한 패턴.

다른 프레임워크

Framework	Flash message
Django	`messages.success()`
Rails	`flash[:notice]`
Spring	`RedirectAttributes.addFlashAttribute()`
Laravel	`session()->flash()`
Express	`connect-flash` middleware

흔한 함정

[!WARNING]

AJAX 응답에 messages = redirect 없이 API 응답 → 다음 요청까지 남음. 명시적 처리.

messages 후 render = redirect 안 하면 template 에서 소비됨 (다음 request 에 안 보임). PRG.

Cookie storage 크기 초과 = 4KB 넘으면 잘림. 짧게.

XSS = 사용자 입력을 messages 로 그대로 → escape 안 됨. {{ message|safe }} 절대 금지.

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

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

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']   # 블랙리스트 (위험!)

[!WARNING] fields = '__all__' 또는 exclude = 새 필드 추가 시 자동 노출 → mass assignment 취약점. fields 화이트리스트 권장.

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 별도 저장!

[!IMPORTANT] commit=False + save_m2m() 짝. Many-to-Many 필드가 있으면 필수.

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

흔한 함정

[!WARNING]

fields = '__all__' = mass assignment 사고.

save_m2m() 잊음 = ManyToMany 필드 저장 안 됨.

instance=obj 안 넘김 = create 로 오해되어 새 row 생성.

user 필드 폼에 노출 = 사용자가 다른 사람 ID 조작. exclude 또는 view 에서 override.

[Django] Q / F / Case / When / Database Functions

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django ORM 의 고급 표현식. Python 에서 짜지만 SQL 로 컴파일 되어 DB 에서 실행. Raw SQL 없이 복잡한 쿼리.

일반 ORM 은 [[django-queryset]], [[django-orm-advanced]] 참고.

1. Q Object (OR / AND / NOT)

from django.db.models import Q

# OR
Article.objects.filter(Q(status='published') | Q(author=request.user))

# NOT
Article.objects.filter(~Q(status='draft'))

# 조합
Article.objects.filter(
    (Q(status='published') | Q(author=request.user)) &
    ~Q(deleted=True)
)

# XOR (Django 4.1+)
Article.objects.filter(Q(featured=True) ^ Q(premium=True))

2. F Expression (컬럼 참조)

from django.db.models import F

# 컬럼 값 서로 비교
Product.objects.filter(price__lt=F('cost'))   # 원가 이하 판매

# 원자적 update
Article.objects.filter(pk=1).update(views=F('views') + 1)
# SQL: UPDATE ... SET views = views + 1

# ✗ Race condition
article = Article.objects.get(pk=1)
article.views += 1
article.save()   # 다른 요청과 경합

[!IMPORTANT] F() = atomic. 동시 update 시 정확. Race condition 방어.

3. Case / When (SQL CASE)

from django.db.models import Case, When, Value, IntegerField

articles = Article.objects.annotate(
    priority=Case(
        When(status='urgent', then=Value(1)),
        When(status='normal', then=Value(2)),
        When(status='low', then=Value(3)),
        default=Value(99),
        output_field=IntegerField(),
    )
).order_by('priority')

# 조건부 update
User.objects.update(
    tier=Case(
        When(orders_count__gte=100, then=Value('platinum')),
        When(orders_count__gte=10, then=Value('gold')),
        default=Value('silver'),
    )
)

4. Aggregate + Conditional

from django.db.models import Sum, Count

# 매출 통계 with 조건
Order.objects.aggregate(
    total_revenue=Sum('amount'),
    paid_revenue=Sum('amount', filter=Q(status='paid')),   # ← 필터 aggregate
    refunded_count=Count('id', filter=Q(status='refunded')),
)

Django 3.0+ 의 filter= 파라미터. SUM(CASE WHEN status='paid' THEN amount ELSE 0 END) 로 컴파일.

5. Database Functions

from django.db.models.functions import (
    Lower, Upper, Concat, Coalesce, Cast, Trunc, Round,
    Substr, Length, Extract, Now, Least, Greatest,
)
from django.db.models import Value, CharField

# 대소문자 무시 검색
User.objects.annotate(name_lower=Lower('name')).filter(name_lower='koa')

# 이름 합치기
User.objects.annotate(
    full_name=Concat('first_name', Value(' '), 'last_name'),
)

# NULL 처리
Article.objects.annotate(
    display_title=Coalesce('title', 'slug', Value('제목 없음')),
)

# 타입 변환
Product.objects.annotate(
    price_int=Cast('price', IntegerField()),
)

# 시간 자르기
Article.objects.annotate(
    month=Trunc('created_at', 'month'),
).values('month').annotate(count=Count('id'))

# 날짜 부분 추출
Article.objects.annotate(
    year=Extract('created_at', 'year'),
    week_day=Extract('created_at', 'week_day'),
)

문자열 함수

Function	의미
`Lower(x)`	소문자
`Upper(x)`	대문자
`Length(x)`	길이
`Concat(a, b, c)`	이어붙임
`Substr(x, pos, len)`	부분
`Trim(x)`	앞뒤 공백 제거
`Reverse(x)`	뒤집기
`Replace(x, old, new)`	치환
`MD5(x)`, `SHA1(x)`, …	해시

숫자 함수

Function	의미
`Abs(x)`	절대값
`Round(x, precision)`	반올림
`Ceil(x)`, `Floor(x)`	올림/내림
`Power(x, y)`	거듭제곱
`Sqrt(x)`, `Exp(x)`, `Log(x)`	수학
`Sin`, `Cos`, `Tan`, …	삼각
`Random()`	무작위

시간 함수

from django.db.models.functions import Now, TruncDate, ExtractHour

# 지금 시각
Article.objects.filter(published_at__lte=Now())

# 일별 통계
Order.objects.annotate(day=TruncDate('created_at')).values('day').annotate(
    count=Count('id'),
    revenue=Sum('amount'),
)

# 시간대 별
Order.objects.annotate(hour=ExtractHour('created_at')).values('hour').annotate(
    count=Count('id'),
)

Window Functions (Django 2.0+)

from django.db.models import Window, F
from django.db.models.functions import Rank, RowNumber, Lag, Lead

# 랭킹
Employee.objects.annotate(
    rank=Window(
        expression=Rank(),
        partition_by=[F('department')],
        order_by=F('salary').desc(),
    )
).filter(rank__lte=3)   # 부서별 상위 3명

# Row number
Article.objects.annotate(
    row=Window(expression=RowNumber(), order_by=F('created_at').desc()),
)

# 이전/다음 값
Sales.objects.annotate(
    prev_amount=Window(
        expression=Lag('amount'),
        partition_by=[F('product')],
        order_by=F('date'),
    ),
    growth=F('amount') - F('prev_amount'),
)

Custom Function

from django.db.models import Func, FloatField

class Sin(Func):
    function = 'SIN'
    output_field = FloatField()

Employee.objects.annotate(x=Sin('degrees'))

Subquery + OuterRef

from django.db.models import OuterRef, Subquery

# 각 사용자의 최근 게시물 제목
latest_article = Article.objects.filter(
    author=OuterRef('pk')
).order_by('-created_at').values('title')[:1]

User.objects.annotate(latest_article_title=Subquery(latest_article))

Exists

from django.db.models import Exists, OuterRef

has_articles = Article.objects.filter(author=OuterRef('pk'))
User.objects.annotate(has_articles=Exists(has_articles)).filter(has_articles=True)

PostgreSQL 특화

from django.contrib.postgres.aggregates import ArrayAgg, StringAgg, JSONBAgg
from django.contrib.postgres.expressions import ArraySubquery

# 배열로 aggregate
Author.objects.annotate(
    book_titles=ArrayAgg('books__title'),
    tags_str=StringAgg('tags__name', delimiter=', '),
)

Django 6.0 개선

GeneratedField (2024) 안정화
Window function 개선
JSONB 함수 강화

다른 프레임워크

Framework	조건부 표현식
Django	Q, F, Case/When, Window
Rails	`.where("...")` + Arel
SQLAlchemy	`case`, `func`, `select`
JPA	`CriteriaBuilder`, `@Formula`

흔한 함정

[!WARNING]

F() update 후 .refresh_from_db() = update 후 Python 객체는 옛 값. refresh 필요.

Window function + filter = 대부분 지원 안 됨. subquery 로.

.annotate() 후 .aggregate() 순서 = 결과 크게 다름.

DB 별 지원 차이 = SQLite 는 window 제한. PostgreSQL 이 가장 풍부.

[Django] Shortcuts + Decorators: render, redirect, get_object_or_404

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django 의 View 작성을 간결하게 하는 shortcut 함수들 + view 에 공통 기능을 붙이는 decorator 들.

Shortcuts (django.shortcuts)

`render(request, template, context, status=200)`

가장 흔한 view helper.

from django.shortcuts import render

def article_detail(request, pk):
    article = Article.objects.get(pk=pk)
    return render(request, 'articles/detail.html', {
        'article': article,
        'related': article.related.all()[:5],
    })

= HttpResponse(template.render(context, request)) 의 축약.

`redirect(to, *args, **kwargs)`

리다이렉트 응답 생성:

from django.shortcuts import redirect

# URL 이름
return redirect('article_detail', pk=42)

# URL 문자열
return redirect('/articles/42/')

# 외부 URL
return redirect('https://external.com/')

# 모델 인스턴스 (get_absolute_url 사용)
article = Article.objects.get(pk=42)
return redirect(article)   # → article.get_absolute_url()

Permanent redirect (301):

return redirect('new_url', permanent=True)

`get_object_or_404(model, **kwargs)`

없으면 404:

from django.shortcuts import get_object_or_404

def article_detail(request, pk):
    article = get_object_or_404(Article, pk=pk, published=True)
    # 여러 조건 가능
    return render(request, 'detail.html', {'article': article})

= try: Article.objects.get(pk=pk) except Article.DoesNotExist: raise Http404.

`get_list_or_404(model, **kwargs)`

빈 결과 시 404:

def articles_by_tag(request, tag):
    articles = get_list_or_404(Article, tags__name=tag, published=True)
    return render(request, 'list.html', {'articles': articles})

Decorators (django.views.decorators)

`@require_http_methods` / `@require_POST` / `@require_GET`

from django.views.decorators.http import require_http_methods, require_POST

@require_http_methods(['GET', 'POST'])
def article_form(request, pk=None):
    if request.method == 'POST':
        ...
    else:
        ...

@require_POST
def delete_article(request, pk):
    Article.objects.filter(pk=pk).delete()
    return redirect('article_list')

허용 안 된 method = 405 Method Not Allowed 자동 응답.

`@login_required`

from django.contrib.auth.decorators import login_required

@login_required
def profile(request):
    return render(request, 'profile.html', {'user': request.user})

@login_required(login_url='/signin/', redirect_field_name='next')
def dashboard(request): ...

미인증 시 LOGIN_URL (기본 /accounts/login/) 로 리다이렉트 + ?next=/dashboard/ 자동 첨부.

`@permission_required`

from django.contrib.auth.decorators import permission_required

@permission_required('polls.can_vote', raise_exception=True)
def vote(request, question_id): ...

raise_exception=True = 403 Forbidden.

`@user_passes_test`

from django.contrib.auth.decorators import user_passes_test

@user_passes_test(lambda u: u.is_staff)
def staff_only(request): ...

def is_over_18(user):
    return user.is_authenticated and user.profile.age >= 18

@user_passes_test(is_over_18, login_url='/login/')
def adult_content(request): ...

`@cache_page`, `@cache_control`

from django.views.decorators.cache import cache_page, cache_control

@cache_page(60 * 15)   # 15분 캐시
def articles(request): ...

@cache_control(max_age=3600, public=True)
def static_ish(request): ...

자세한 건 [[django-cache]].

`@csrf_exempt`

from django.views.decorators.csrf import csrf_exempt

@csrf_exempt
def webhook(request):
    # 외부 서비스 웹훅 (CSRF token 없음)
    ...

[!WARNING] 남용 금지. 외부 API 는 별도 signature 검증 필수.

`@method_decorator` (Class-Based View)

from django.utils.decorators import method_decorator
from django.views.generic import ListView

@method_decorator(login_required, name='dispatch')
class ArticleListView(ListView):
    model = Article

# 또는 개별 method
class MyView(View):
    @method_decorator(cache_page(60*15))
    def get(self, request): ...

Class-Based View 대안 (Mixin)

from django.contrib.auth.mixins import LoginRequiredMixin, PermissionRequiredMixin

class ProfileView(LoginRequiredMixin, DetailView):
    model = User
    login_url = '/signin/'

class StaffView(LoginRequiredMixin, PermissionRequiredMixin, ListView):
    permission_required = 'polls.can_vote'
    raise_exception = True

자세한 mixin 은 [[django-mixins]].

Custom Decorator

from functools import wraps

def track_time(view_func):
    @wraps(view_func)
    def wrapper(request, *args, **kwargs):
        import time
        start = time.time()
        response = view_func(request, *args, **kwargs)
        elapsed = time.time() - start
        response['X-Response-Time'] = f'{elapsed:.3f}'
        logger.info(f'{request.path} took {elapsed:.3f}s')
        return response
    return wrapper

@track_time
def slow_view(request): ...

다른 프레임워크

Framework	shortcuts / decorators
Django	`render, redirect, get_object_or_404`, `@login_required`
Rails	`render, redirect_to`, `before_action`
Spring	`ResponseEntity`, `@PreAuthorize`
FastAPI	`Depends`, `Response`
Express	middleware chain

흔한 함정

[!WARNING]

get_object_or_404 로 auth 확인 = 로그인 안 한 사용자에게 존재/부재 leak. @login_required 조합.

@csrf_exempt 남발 = CSRF 방어 무력화.

redirect(url) 의 open redirect = ?next= 값 검증 없이 redirect → phishing. is_safe_url 사용.

Decorator 순서 = @login_required @require_POST 순서 중요. @wraps 로 name 보존.

[Django] Transactions: atomic, on_commit, savepoint

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Transaction = 여러 SQL 문을 원자적 (all-or-nothing) 으로 실행. Django 는 자동 커밋 (autocommit) 모드가 기본, transaction.atomic() 으로 명시적 트랜잭션.

일반 트랜잭션 개념은 [[transaction-isolation-levels]] 참고.

3가지 트랜잭션 모드

flowchart TD
    Q{Django 트랜잭션 모드}
    Q --> A["1. Autocommit (기본)"]
    Q --> B["2. atomic() context"]
    Q --> C["3. ATOMIC_REQUESTS (view 단위)"]
    A --> A1["각 쿼리 즉시 commit"]
    B --> B1["명시적 블록 원자성"]
    C --> C1["매 request 자동 wrap"]

1. `transaction.atomic()` (권장)

from django.db import transaction

@transaction.atomic
def transfer_money(from_user_id, to_user_id, amount):
    from_account = Account.objects.select_for_update().get(user_id=from_user_id)
    to_account = Account.objects.select_for_update().get(user_id=to_user_id)

    if from_account.balance < amount:
        raise ValidationError('잔액 부족')

    from_account.balance -= amount
    to_account.balance += amount
    from_account.save()
    to_account.save()

Context manager 형태:

def signup(request):
    with transaction.atomic():
        user = User.objects.create_user(...)
        Profile.objects.create(user=user, ...)
        # 예외 발생 시 둘 다 rollback

2. Nested atomic (savepoint)

with transaction.atomic():
    order = Order.objects.create(...)
    try:
        with transaction.atomic():        # ← savepoint
            payment = charge_card(order)
    except PaymentError:
        # 결제만 rollback, 주문은 유지
        order.status = 'pending_payment'
        order.save()

sequenceDiagram
    T->>DB: BEGIN
    T->>DB: INSERT order
    T->>DB: SAVEPOINT sp1
    T->>DB: charge_card (실패!)
    T->>DB: ROLLBACK TO SAVEPOINT sp1
    T->>DB: UPDATE order SET status='pending_payment'
    T->>DB: COMMIT

3. ATOMIC_REQUESTS

# settings.py
DATABASES = {
    'default': {
        ...
        'ATOMIC_REQUESTS': True,
    },
}

각 view = 자동으로 atomic() 로 감쌈. 예외 시 자동 rollback.

[!CAUTION] 성능 영향: 모든 요청이 트랜잭션 → DB connection 오래 점유. 대량 트래픽 시 명시적 atomic() 권장.

`on_commit` (커밋 후 실행)

from django.db import transaction

def signup(request):
    with transaction.atomic():
        user = User.objects.create_user(...)
        # 즉시 실행 (트랜잭션 안!)
        # send_email(user)   # ← ROLLBACK 시 이미 전송됨!

        # commit 후 실행
        transaction.on_commit(lambda: send_email(user))
        transaction.on_commit(lambda: send_welcome_task.enqueue(user.pk))

sequenceDiagram
    View->>DB: BEGIN
    View->>DB: INSERT user
    View->>Queue[on_commit callbacks]: 등록
    View->>DB: COMMIT
    Queue-->>Service: send_email(user)
    Queue-->>Task: enqueue task

[!IMPORTANT] 외부 시스템 호출은 항상 on_commit - 이메일, 결제, task, webhook 등. rollback 시 부수효과 없어야 함.

`select_for_update` (비관적 락)

@transaction.atomic
def reserve_seat(seat_id):
    seat = Seat.objects.select_for_update().get(pk=seat_id)
    if seat.is_reserved:
        raise AlreadyReservedError()
    seat.is_reserved = True
    seat.save()

SQL: SELECT ... FROM seats WHERE id = ? FOR UPDATE;

다른 트랜잭션이 같은 row 를 lock 잡을 때까지 대기. Race condition 방지.

옵션:

Seat.objects.select_for_update(
    skip_locked=True,       # 잠긴 행 skip (큐 pattern)
    nowait=True,            # 즉시 실패 (대기 X)
    of=('self',),           # 특정 테이블만 lock (JOIN 시)
).filter(...)

Isolation Level

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'OPTIONS': {
            'isolation_level': psycopg.IsolationLevel.SERIALIZABLE,
        },
    }
}

자세한 건 [[transaction-isolation-levels]].

성능 - Bulk operations

# ❌ N번 트랜잭션
for user in users:
    Profile.objects.create(user=user)

# ✓ 1번 트랜잭션 (bulk_create)
profiles = [Profile(user=u) for u in users]
Profile.objects.bulk_create(profiles)

# ✓ 명시적 트랜잭션
with transaction.atomic():
    for user in users:
        Profile.objects.create(user=user)

Test 에서 transaction

from django.test import TestCase, TransactionTestCase

class MyTest(TestCase):
    # 모든 테스트가 트랜잭션 안에서 실행 → rollback 으로 격리
    pass

class TransactionTest(TransactionTestCase):
    # 실제 commit/rollback 테스트 (on_commit 등)
    def test_signup_sends_email(self):
        with self.captureOnCommitCallbacks(execute=True):
            self.client.post('/signup/', {...})

흔한 함정

[!WARNING]

atomic() 안에서 외부 API 호출 = 트랜잭션 오래 점유. on_commit 으로.

select_for_update 를 atomic() 밖에서 = TransactionManagementError.

ATOMIC_REQUESTS=True + long request = connection pool 고갈.

savepoint 남발 = 성능 저하. 필요한 곳만.

다른 프레임워크

Framework	Transaction
Django	`transaction.atomic()`
Rails	`ActiveRecord::Base.transaction`
Spring	`@Transactional`
SQLAlchemy	`session.begin()`

[Django] 첫 프로젝트 튜토리얼: 순차 학습

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django 를 처음 접하는 사람 을 위한 순차 학습 페이지. 투표 앱 (polls) 을 만들며 Django 의 핵심 개념을 익힌다.

먼저 [[django-overview]] 로 MTV 패턴과 프로젝트 구조를 파악한 후 이 페이지로.

학습 순서 (전체 지도)

flowchart TB
    S["1. 설치 + startproject"] --> T["2. runserver 확인"]
    T --> A["3. app 생성 (startapp)"]
    A --> M["4. 모델 (Model)"]
    M --> Adm["5. Admin 사이트"]
    Adm --> V["6. View + URL"]
    V --> Tpl["7. Template"]
    Tpl --> F["8. Form"]
    F --> Test["9. Test"]
    Test --> D["10. Deploy"]

이 순서로 페이지를 따라가면 Django 의 90% 를 이해.

사전 준비

# Python 3.12+ 권장 (Django 6.0 최소 3.12)
python --version

# 가상환경
python -m venv .venv
source .venv/bin/activate       # macOS/Linux
# .venv\Scripts\activate         # Windows

# Django 6.0 설치
pip install django
python -m django --version

Step 1. 프로젝트 시작

django-admin startproject mysite
cd mysite

mysite/
├── manage.py           # CLI 진입점
└── mysite/
    ├── __init__.py
    ├── settings.py     # 설정 파일
    ├── urls.py         # 루트 URL 설정
    ├── asgi.py         # ASGI 서버
    └── wsgi.py         # WSGI 서버

python manage.py runserver
# → http://127.0.0.1:8000/ 접속

[!TIP] manage.py 는 프로젝트 마다 하나. django-admin 은 전역 명령. 실제로 프로젝트 안에서는 manage.py 를 쓴다.

Step 2. App 생성

Django 의 app = 재사용 가능한 모듈. 프로젝트는 여러 app 의 조립.

python manage.py startapp polls

polls/
├── __init__.py
├── admin.py           # Admin 등록
├── apps.py            # App 설정
├── models.py          # 모델
├── views.py           # 뷰
├── tests.py           # 테스트
└── migrations/        # 마이그레이션 파일

mysite/settings.py 에 app 등록:

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'polls.apps.PollsConfig',   # ← 추가
]

Step 3. 모델 정의

polls/models.py:

from django.db import models

class Question(models.Model):
    question_text = models.CharField(max_length=200)
    pub_date = models.DateTimeField('date published')

    def __str__(self):
        return self.question_text

class Choice(models.Model):
    question = models.ForeignKey(Question, on_delete=models.CASCADE, related_name='choices')
    choice_text = models.CharField(max_length=200)
    votes = models.IntegerField(default=0)

    def __str__(self):
        return self.choice_text

Migration 생성 + DB 반영:

python manage.py makemigrations polls
python manage.py migrate

자세한 필드 종류는 [[django-models-fields]], migrations 는 [[django-migrations]].

Step 4. Admin 사이트

python manage.py createsuperuser
# 이름, 이메일, 비밀번호 입력

polls/admin.py:

from django.contrib import admin
from .models import Question, Choice

@admin.register(Question)
class QuestionAdmin(admin.ModelAdmin):
    list_display = ('question_text', 'pub_date')
    list_filter = ('pub_date',)
    search_fields = ('question_text',)

@admin.register(Choice)
class ChoiceAdmin(admin.ModelAdmin):
    list_display = ('choice_text', 'question', 'votes')

python manage.py runserver
# http://127.0.0.1:8000/admin/ 접속 → 위 계정으로 로그인

자세한 건 [[django-admin]].

Step 5. View + URL

polls/views.py:

from django.http import HttpResponse
from django.shortcuts import render, get_object_or_404
from .models import Question

def index(request):
    latest_questions = Question.objects.order_by('-pub_date')[:5]
    return render(request, 'polls/index.html', {
        'latest_questions': latest_questions,
    })

def detail(request, question_id):
    question = get_object_or_404(Question, pk=question_id)
    return render(request, 'polls/detail.html', {'question': question})

polls/urls.py:

from django.urls import path
from . import views

app_name = 'polls'
urlpatterns = [
    path('', views.index, name='index'),
    path('<int:question_id>/', views.detail, name='detail'),
]

mysite/urls.py:

from django.urls import path, include

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

자세한 건 [[django-urls]], [[django-views]], [[django-shortcuts-decorators]].

Step 6. Template

polls/templates/polls/index.html:

{% extends "base.html" %}

{% block content %}
<h1>최근 질문</h1>
{% if latest_questions %}
    <ul>
    {% for q in latest_questions %}
        <li>
            <a href="{% url 'polls:detail' q.id %}">{{ q.question_text }}</a>
        </li>
    {% endfor %}
    </ul>
{% else %}
    <p>질문이 없습니다.</p>
{% endif %}
{% endblock %}

자세한 건 [[django-templates]].

Step 7. Form

polls/forms.py:

from django import forms
from .models import Question

class QuestionForm(forms.ModelForm):
    class Meta:
        model = Question
        fields = ['question_text', 'pub_date']
        widgets = {
            'pub_date': forms.DateTimeInput(attrs={'type': 'datetime-local'}),
        }

자세한 건 [[django-forms]], [[django-modelforms]], [[django-formsets]].

Step 8. Test

# polls/tests.py
from django.test import TestCase
from django.utils import timezone
from .models import Question

class QuestionModelTests(TestCase):
    def test_str(self):
        q = Question.objects.create(question_text='Test?', pub_date=timezone.now())
        self.assertEqual(str(q), 'Test?')

    def test_recent_questions(self):
        Question.objects.create(question_text='Old', pub_date=timezone.now() - timezone.timedelta(days=10))
        Question.objects.create(question_text='New', pub_date=timezone.now())
        recent = Question.objects.order_by('-pub_date').first()
        self.assertEqual(recent.question_text, 'New')

python manage.py test polls

자세한 건 [[django-testing]].

Step 9. Deploy

# 1. 정적 파일 collect
python manage.py collectstatic

# 2. WSGI 서버 (gunicorn)
pip install gunicorn
gunicorn mysite.wsgi:application

# 3. 환경변수
export DJANGO_SETTINGS_MODULE=mysite.settings.production
export DATABASE_URL=postgres://...

# 4. 필수 체크
python manage.py check --deploy

자세한 건 [[django-deployment]], [[django-settings]].

Django vs 다른 프레임워크

Feature	Django	Rails	Spring Boot	FastAPI	Express
언어	Python	Ruby	Java	Python	Node.js
Batteries	포함	포함	starter	최소	최소
ORM	ORM 내장	ActiveRecord	JPA/Hibernate	SQLAlchemy	없음 (선택)
Admin UI	내장	없음 (gem)	없음	없음	없음
Migrations	내장	Active Record	Flyway	Alembic	별도
Template	DTL	ERB	Thymeleaf	Jinja2	EJS/Pug
Forms	내장	Form helpers	Spring MVC	Pydantic	없음
학습 곡선	완만	완만	가파름	매우 완만	매우 완만
규모	대형	대형	대형	소-중	자유

Django 는 “완벽주의자를 위한 프레임워크” - 컨벤션이 많아 처음에는 답답할 수 있지만 대규모 프로젝트에서는 일관성 + 안전 이 큰 장점.

다음 단계

이 튜토리얼 후 학습 순서 권장:

[[django-models-fields]] - 필드 종류
[[django-queryset]] - ORM 쿼리
[[django-urls]] - URL routing
[[django-views]] - View 상세
[[django-templates]] - 템플릿 문법
[[django-forms]] - 폼 처리
[[django-admin]] - 관리자 커스터마이즈
[[django-auth]] - 인증
[[django-cache]] - 캐싱
[[django-testing]] - 테스트

[DRF] Authentication: Session, Token, JWT, OAuth2

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Authentication = 누가 요청했는지 식별. Authorization ([[django-drf-permissions]]) 과 별개.

흐름

flowchart LR
    Req[Request] --> Auth[Authentication class]
    Auth -->|성공| U[request.user = User 인스턴스]
    Auth -->|실패| Anon[request.user = AnonymousUser]
    Auth -->|잘못된 credential| Err[401]
    U --> Perm[Permission class]
    Perm -->|OK| View
    Perm -->|거절| Forbid[403]

자세한 permission 은 [[django-drf-permissions]].

내장 Authentication Classes

Class	방식
`BasicAuthentication`	HTTP Basic Auth
`SessionAuthentication`	Django session (쿠키)
`TokenAuthentication`	Django token (내장)
`RemoteUserAuthentication`	웹 서버 인증

설정

# 전역
REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ]
}

# View 별
class MyView(APIView):
    authentication_classes = [TokenAuthentication]

1. SessionAuthentication (Django 기본)

브라우저 세션 사용. Browsable API 에 필수.

authentication_classes = [SessionAuthentication]

장점: Django 인증 시스템 그대로.
단점: CSRF token 필요. 모바일/외부 앱 부적합.

2. TokenAuthentication (내장 토큰)

INSTALLED_APPS = [
    ...,
    'rest_framework.authtoken',
]

python manage.py migrate

# 토큰 발급 endpoint 등록
from rest_framework.authtoken.views import obtain_auth_token

urlpatterns = [
    path('api-token-auth/', obtain_auth_token),
]

# 사용
curl -X POST http://localhost:8000/api-token-auth/ \
  -d '{"username": "koa", "password": "secret"}' \
  -H 'Content-Type: application/json'
# → {"token": "abc123..."}

# 이후 요청
curl -H 'Authorization: Token abc123...' http://localhost:8000/api/users/

장점: 단순.
단점: 영구 토큰 (rotation 없음), revoke 어려움.

3. JWT (Simple JWT) - 사실상 표준

pip install djangorestframework-simplejwt

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework_simplejwt.authentication.JWTAuthentication',
    ],
}

SIMPLE_JWT = {
    'ACCESS_TOKEN_LIFETIME': timedelta(minutes=15),
    'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
    'ROTATE_REFRESH_TOKENS': True,
    'BLACKLIST_AFTER_ROTATION': True,
    'ALGORITHM': 'HS256',
    'SIGNING_KEY': SECRET_KEY,
    'AUTH_HEADER_TYPES': ('Bearer',),
}

# urls.py
from rest_framework_simplejwt.views import (
    TokenObtainPairView, TokenRefreshView, TokenVerifyView,
)

urlpatterns = [
    path('api/token/', TokenObtainPairView.as_view()),
    path('api/token/refresh/', TokenRefreshView.as_view()),
    path('api/token/verify/', TokenVerifyView.as_view()),
]

# 로그인
POST /api/token/ {"username": "koa", "password": "..."}
→ { "access": "eyJ...", "refresh": "eyJ..." }

# 요청
GET /api/users/ Authorization: Bearer eyJ...

# 갱신
POST /api/token/refresh/ {"refresh": "eyJ..."}
→ { "access": "eyJ...", "refresh": "eyJ..." }  ← rotation

# 검증
POST /api/token/verify/ {"token": "eyJ..."}

자세한 JWT 원리는 [[JWT]].

Custom Claim

from rest_framework_simplejwt.serializers import TokenObtainPairSerializer

class MyTokenObtainPairSerializer(TokenObtainPairSerializer):
    @classmethod
    def get_token(cls, user):
        token = super().get_token(user)
        token['name'] = user.get_full_name()
        token['role'] = 'admin' if user.is_staff else 'user'
        return token

class MyTokenObtainPairView(TokenObtainPairView):
    serializer_class = MyTokenObtainPairSerializer

4. OAuth2 (django-oauth-toolkit)

pip install django-oauth-toolkit

INSTALLED_APPS = [..., 'oauth2_provider']

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'oauth2_provider.contrib.rest_framework.OAuth2Authentication',
    ],
}

자세한 OAuth2 는 [[OAuth2]].

5. Custom Authentication

from rest_framework import authentication, exceptions

class ApiKeyAuthentication(authentication.BaseAuthentication):
    def authenticate(self, request):
        api_key = request.headers.get('X-API-Key')
        if not api_key:
            return None                # authentication 시도 안 함

        try:
            user = User.objects.get(api_key=api_key)
        except User.DoesNotExist:
            raise exceptions.AuthenticationFailed('Invalid API key')

        return (user, None)             # (user, auth) 튜플

    def authenticate_header(self, request):
        return 'X-API-Key'

비교 매트릭스

	Session	Token (built-in)	JWT	OAuth2
설정	최소	간단	중간	복잡
Stateless	❌	❌	✓	하이브리드
Mobile	부적합	적합	최적	적합
Revoke	즉시	DB 삭제	어려움 (blacklist)	refresh revoke
Rotation	-	❌	✓	✓
제3자 통합	❌	❌	표준	표준
사용처	Browsable API	간단 API	현대 API	SSO, 3rd party

다중 Authentication

# 첫 성공한 것 사용
authentication_classes = [
    JWTAuthentication,          # 1순위
    SessionAuthentication,       # fallback
    TokenAuthentication,         # fallback
]

CSRF 처리

flowchart LR
    S["SessionAuthentication"] -->|CSRF 검증| C["CSRF token 필수"]
    T["TokenAuthentication"] -->|CSRF 안 검증| N["Token 만"]
    J["JWTAuthentication"] -->|CSRF 안 검증| N

Session = CSRF token 필요.
Token/JWT = CSRF 없음 (stateless).

HTTPS 필수

[!IMPORTANT] Token / JWT / Session cookie 는 반드시 HTTPS. HTTP 는 탈취.

다른 프레임워크

Framework	인증
DRF	Session, Token, JWT (simple-jwt)
Spring Security	Session, JWT, OAuth2 (내장)
Rails	Devise
Express	passport.js
FastAPI	OAuth2 helpers

흔한 함정

[!WARNING]

SECRET_KEY 노출 = JWT 위조. .env 관리.

Token 무한 저장 = 유출 시 영구 침입. JWT + short expire.

JWT payload 민감 정보 = 누구나 decode 가능. sub (user_id) 만.

CSRF 켜져있는 상태에서 SPA = fetch 실패. csrfmiddlewaretoken 첨부.

[DRF] Pagination + Throttling

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Pagination = 큰 목록을 페이지 단위로 나눔. Throttling = 요청 빈도 제한. 둘 다 API 안정성의 기본.

Pagination 3종

{}

언제 어느 것을 쓸까

flowchart TD
    Q{Pagination 종류}
    Q --> P["PageNumberPagination<br/>?page=1&page_size=20"]
    Q --> L["LimitOffsetPagination<br/>?limit=20&offset=40"]
    Q --> C["CursorPagination<br/>?cursor=abc123"]

종류	목적	장점	단점
PageNumberPagination	특정 페이지 이동 (관리자 UI)	직관적, “5페이지로 가기” 지원	큰 offset 시 느림, 실시간 데이터에 중복/누락
LimitOffsetPagination	임의 offset 필요할 때	유연 (`?limit=10&offset=137`)	PageNumber와 같은 문제, offset 커지면 여전히 느림
CursorPagination	무한 스크롤, 대규모 실시간 피드	일관성, offset 무관 O(log N)	임의 페이지 이동 불가, 정렬 필드 필수

왜 큰 offset은 느린가?

SELECT * FROM users ORDER BY id LIMIT 20 OFFSET 100000;

DB는 OFFSET 100000 을 무시하는 게 아니라 100000개 row 를 실제로 훑고 버린다. 페이지가 뒤로 갈수록 응답 시간 선형 증가.

CursorPagination 은 WHERE id > last_seen_id ORDER BY id LIMIT 20 로 인덱스만 타므로 어느 페이지든 O(log N).

PageNumberPagination

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
}

GET /api/users/?page=2

응답:

{
  "count": 100,
  "next": "http://api/users/?page=3",
  "previous": "http://api/users/?page=1",
  "results": [{...}, ...]
}

Custom:

class MyPagination(PageNumberPagination):
    page_size = 20
    page_size_query_param = 'page_size'   # ?page_size=50
    max_page_size = 100

LimitOffsetPagination

class MyPagination(LimitOffsetPagination):
    default_limit = 20
    max_limit = 100

GET /api/users/?limit=20&offset=40

CursorPagination (대규모 권장)

class MyPagination(CursorPagination):
    page_size = 20
    ordering = '-created_at'   # 정렬 필드 (필수)

GET /api/users/?cursor=cD0yMDI2LTA2LTI1

응답:

{
  "next": "http://api/users/?cursor=cD0yMDI2LTA1LTMx",
  "previous": null,
  "results": [{...}]
}

[!TIP] 대규모 데이터 (수십만 row+) = CursorPagination 필수. LIMIT/OFFSET 은 offset 커질수록 DB 부담.

View 별 override

class MyView(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    pagination_class = CursorPagination
    # pagination_class = None   # 비활성

응답 포맷 커스터마이즈

class CustomPagination(PageNumberPagination):
    page_size = 20

    def get_paginated_response(self, data):
        return Response({
            'meta': {
                'total': self.page.paginator.count,
                'page': self.page.number,
                'per_page': self.page_size,
                'total_pages': self.page.paginator.num_pages,
            },
            'links': {
                'next': self.get_next_link(),
                'previous': self.get_previous_link(),
            },
            'data': data,
        })

언제 무엇을?

flowchart TD
    Q{시나리오}
    Q -->|"UI 페이지네이션 (1, 2, 3)"| P["PageNumberPagination"]
    Q -->|"무한 스크롤"| L["LimitOffsetPagination or Cursor"]
    Q -->|"큰 데이터 + 실시간"| C["CursorPagination"]
    Q -->|"관리자 화면"| P
    Q -->|"모바일 앱"| C

Throttling

flowchart LR
    Req[Request] --> Throttle[Throttle class]
    Throttle -->|"허용"| View
    Throttle -->|"429 Too Many Requests"| Reject

내장 Throttle Classes

Class	Scope
`AnonRateThrottle`	익명 (IP 기반)
`UserRateThrottle`	인증된 user
`ScopedRateThrottle`	View 별 커스텀

설정

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.AnonRateThrottle',
        'rest_framework.throttling.UserRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'anon': '100/hour',
        'user': '1000/hour',
    }
}

Rate 형식: 숫자/기간 (second, minute, hour, day).

ScopedRateThrottle

REST_FRAMEWORK = {
    'DEFAULT_THROTTLE_CLASSES': [
        'rest_framework.throttling.ScopedRateThrottle',
    ],
    'DEFAULT_THROTTLE_RATES': {
        'login': '5/min',
        'signup': '10/hour',
        'ai_generate': '30/day',
    }
}

class LoginView(APIView):
    throttle_scope = 'login'
    def post(self, request): ...

class AIGenerateView(APIView):
    throttle_scope = 'ai_generate'
    def post(self, request): ...

Custom Throttle

from rest_framework.throttling import SimpleRateThrottle

class BurstRateThrottle(SimpleRateThrottle):
    scope = 'burst'
    rate = '10/minute'   # 짧은 시간

    def get_cache_key(self, request, view):
        if request.user.is_authenticated:
            ident = request.user.pk
        else:
            ident = self.get_ident(request)
        return f'throttle_burst_{ident}'


class SustainedRateThrottle(SimpleRateThrottle):
    scope = 'sustained'
    rate = '1000/day'

    def get_cache_key(self, request, view):
        return f'throttle_sustained_{request.user.pk}'

429 응답

HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{ "detail": "Request was throttled. Expected available in 3600 seconds." }

[!TIP] 클라이언트는 Retry-After 확인 후 재시도. 자세한 건 [[retry-with-backoff]].

Cache Backend

Throttle 은 Django cache 사용:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://localhost:6379/1',
    }
}

Production = Redis 권장. LocMemCache 는 프로세스 별 개별 → 여러 worker 에서 부정확.

대안 (외부 도구)

flowchart TD
    Q{Rate limit 위치}
    Q -->|"App 단위"| DRF["DRF Throttle"]
    Q -->|"Nginx / Traefik"| RP["Reverse Proxy"]
    Q -->|"API Gateway"| AG["Kong / AWS API Gateway"]
    Q -->|"CDN"| CDN["Cloudflare Rate Limit"]

여러 계층 조합 권장. DRF = 앱 로직 기반, CDN = 광범위 DDoS 방어.

자세한 rate limit 알고리즘은 [[rate-limiting]].

다른 프레임워크

Framework	Pagination	Throttling
DRF	3종	Class based
FastAPI	없음	slowapi
Spring	Pageable	bucket4j
Express	없음	express-rate-limit
Rails	kaminari, will_paginate	rack-attack

흔한 함정

[!WARNING]

PAGE_SIZE 미설정 + PageNumberPagination = 사용 시 에러.

Cursor pagination 정렬 안 정함 = 에러.

큰 offset (page=1000) = DB 부담. Cursor 로 마이그레이션.

Throttle LocMemCache = worker 마다 별개. Redis.

[DRF] Request + Response 객체

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

DRF 의 Request = Django HttpRequest 의 확장. Response = TemplateResponse 의 확장. 자동 content negotiation + renderer 처리.

요청이 뷰에 도달하기까지

request.data 에 값이 실제로 들어가려면 그 이전에 여러 단계를 거친다.

{}

Request 객체는 위 파이프라인에서 2번 (Router 이후) 에 만들어지고, 파이프라인 내내 확장된다:

단계	Request 에 붙는 것
초기화	`request.data` (파서 지연 로딩), `request.query_params`
Authentication	`request.user`, `request.auth`
Permission	(검사만)
Throttle	(검사만)
View	여기서 처음 읽음
Renderer	`Response` 를 실제 bytes 로

Request 객체

from rest_framework.decorators import api_view

@api_view(['POST'])
def create(request):
    request.data          # 파싱된 body (JSON, form 자동)
    request.query_params  # ?key=value
    request.user          # 인증된 User (or AnonymousUser)
    request.auth          # 토큰 등
    request.method        # 'GET', 'POST', ...
    request.META          # HTTP 헤더 등
    return Response(...)

`request.data` vs `request.POST`

flowchart LR
    Body["Request body"] --> Parser["DRF Parser (JSON, MultiPart, Form)"]
    Parser --> Data["request.data"]

    Django["Django request.POST"] --> Form["form data 만"]

	`request.data` (DRF)	`request.POST` (Django)
JSON body	예	아니오
Form data	예	예
Multipart	예	예
PUT / PATCH body	예	아니오

[!IMPORTANT] DRF 는 request.data 사용. request.POST 는 JSON body 를 못 읽는다.

Content Negotiation

sequenceDiagram
    Client->>DRF: POST /api/users/<br/>Content-Type: application/json
    DRF->>Parser: JSONParser 선택
    Parser-->>DRF: 파싱된 데이터
    DRF->>View: request.data = {...}
    View-->>DRF: Response({...})
    DRF->>Renderer: Accept: application/json<br/>→ JSONRenderer
    Renderer-->>Client: {...}

DRF 가 자동으로 Content-Type 보고 파싱 + Accept 보고 렌더링. 자세한 건 [[drf-versioning-content-negotiation]].

Response 객체

from rest_framework.response import Response
from rest_framework import status

@api_view(['GET'])
def user_detail(request, pk):
    user = get_object_or_404(User, pk=pk)
    return Response(
        UserSerializer(user).data,
        status=status.HTTP_200_OK,
        headers={'X-Custom': 'value'},
    )

파라미터	의미
`data`	응답 데이터 (dict, list, 등)
`status`	HTTP status code
`template_name`	HTML template (Browsable API)
`headers`	추가 헤더
`content_type`	강제 지정 (일반적으로 안 함)

Status Codes

from rest_framework import status

# 자주 쓰는 것
status.HTTP_200_OK
status.HTTP_201_CREATED
status.HTTP_202_ACCEPTED
status.HTTP_204_NO_CONTENT

status.HTTP_400_BAD_REQUEST
status.HTTP_401_UNAUTHORIZED
status.HTTP_403_FORBIDDEN
status.HTTP_404_NOT_FOUND
status.HTTP_409_CONFLICT
status.HTTP_422_UNPROCESSABLE_ENTITY
status.HTTP_429_TOO_MANY_REQUESTS

status.HTTP_500_INTERNAL_SERVER_ERROR
status.HTTP_502_BAD_GATEWAY
status.HTTP_503_SERVICE_UNAVAILABLE

HTTP_200_OK 같은 상수 사용 권장 (magic number 회피).

Parser 종류

REST_FRAMEWORK = {
    'DEFAULT_PARSER_CLASSES': [
        'rest_framework.parsers.JSONParser',      # 기본
        'rest_framework.parsers.FormParser',       # multipart 이전
        'rest_framework.parsers.MultiPartParser',  # 파일
    ]
}

Parser	Content-Type
`JSONParser`	`application/json`
`FormParser`	`application/x-www-form-urlencoded`
`MultiPartParser`	`multipart/form-data`
`FileUploadParser`	binary (파일 stream)

View 단위 override

from rest_framework.parsers import MultiPartParser, JSONParser

class FileUploadView(APIView):
    parser_classes = [MultiPartParser]

    def post(self, request):
        file = request.FILES['file']
        return Response({'uploaded': file.name})

Renderer 종류

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',
        'rest_framework.renderers.BrowsableAPIRenderer',
    ]
}

Renderer	Accept
`JSONRenderer`	`application/json`
`BrowsableAPIRenderer`	`text/html`
`AdminRenderer`	HTML admin
`TemplateHTMLRenderer`	HTML 지정
`HTMLFormRenderer`	HTML form

Format Suffix

# URL: /users.json 또는 /users.api
from rest_framework.urlpatterns import format_suffix_patterns

urlpatterns = format_suffix_patterns([
    path('users/', UserList.as_view()),
    path('users/<int:pk>/', UserDetail.as_view()),
])

URL 확장자로 format 지정. RESTful 이라기보다 옛 패턴, Accept 헤더 권장.

파일 업로드

class FileUploadView(APIView):
    parser_classes = [MultiPartParser, FormParser]

    def post(self, request):
        file = request.data.get('file')
        # 저장
        return Response({'name': file.name, 'size': file.size})

자세한 건 [[django-file-uploads]].

Query Params vs Data

@api_view(['GET'])
def search(request):
    q = request.query_params.get('q', '')       # URL query
    page = int(request.query_params.get('page', 1))
    ...
    return Response(...)


@api_view(['POST'])
def create(request):
    title = request.data.get('title')            # body
    ...

Custom Parser / Renderer

from rest_framework import renderers

class CSVRenderer(renderers.BaseRenderer):
    media_type = 'text/csv'
    format = 'csv'

    def render(self, data, accepted_media_type=None, renderer_context=None):
        import csv, io
        buf = io.StringIO()
        writer = csv.writer(buf)
        for row in data:
            writer.writerow(row.values())
        return buf.getvalue()


class MyView(APIView):
    renderer_classes = [renderers.JSONRenderer, CSVRenderer]

    def get(self, request):
        return Response([{'a': 1, 'b': 2}])
        # GET /myview.csv → CSV 응답

Exception 자동 처리

from rest_framework.exceptions import NotFound, PermissionDenied, ValidationError

@api_view(['GET'])
def item(request, pk):
    try:
        item = Item.objects.get(pk=pk)
    except Item.DoesNotExist:
        raise NotFound('Item not found')

    if not item.can_view(request.user):
        raise PermissionDenied()

    return Response(ItemSerializer(item).data)

DRF 가 자동으로 ProblemDetail 유사 JSON 응답:

{ "detail": "Item not found" }

`HttpResponse` vs `Response`

# ❌ Django HttpResponse
from django.http import JsonResponse
return JsonResponse({'ok': True})

# ✓ DRF Response
return Response({'ok': True})

DRF Response = content negotiation + renderer 자동. HTML/JSON 자유롭게 응답.

다른 프레임워크 비교

Framework	Body 접근
DRF	`request.data`
FastAPI	Pydantic model 자동
Flask	`request.get_json()`
Spring	`@RequestBody DTO`
Express	`req.body` (body-parser)
Rails	`params` (모든 것 통합)

흔한 함정

[!WARNING]

request.POST 사용 = JSON body 못 읽음. request.data.

status_code 매직 넘버 400 = 가독성 낮음. status.HTTP_400_BAD_REQUEST.

JsonResponse 사용 = content negotiation 무시. Response.

request.data 를 dict() 로 변환 = QueryDict/OrderedDict 를 그대로 두는 게 안전.

[DRF] Routers: DefaultRouter, SimpleRouter, custom actions

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Router = ViewSet 에 대한 URL 자동 생성. Rails 의 resources :users 와 유사.

왜 Router?

# ✗ 수동 URL 등록 (ViewSet 마다 6-7 라인)
urlpatterns = [
    path('users/', UserViewSet.as_view({'get': 'list', 'post': 'create'})),
    path('users/<int:pk>/', UserViewSet.as_view({
        'get': 'retrieve',
        'put': 'update',
        'patch': 'partial_update',
        'delete': 'destroy',
    })),
]

# ✓ Router 자동
router = DefaultRouter()
router.register('users', UserViewSet)
urlpatterns = [path('', include(router.urls))]

종류

flowchart TD
    Router --> S["SimpleRouter (URL 만)"]
    Router --> D["DefaultRouter (SimpleRouter + API root + format suffix)"]
    Router --> Custom["Custom Router (상속)"]

DefaultRouter

from rest_framework import routers

router = routers.DefaultRouter()
router.register('users', UserViewSet)
router.register('groups', GroupViewSet, basename='group')

urlpatterns = [
    path('api/', include(router.urls)),
]

생성되는 URL:

URL	Method	대응
`/api/`	GET	API root (endpoint 목록)
`/api/users/`	GET	`list`
`/api/users/`	POST	`create`
`/api/users/{id}/`	GET	`retrieve`
`/api/users/{id}/`	PUT	`update`
`/api/users/{id}/`	PATCH	`partial_update`
`/api/users/{id}/`	DELETE	`destroy`
`/api/users.json` 등	format suffix	옵션

SimpleRouter

DefaultRouter 에서 API root + format suffix 제외. 더 minimal.

router = routers.SimpleRouter()

`basename` (queryset 없을 때 필수)

router.register('users', UserViewSet)
# queryset 있으면 자동 basename='user'

class ArticleViewSet(viewsets.ViewSet):
    def list(self, request):
        return Response(...)

router.register('articles', ArticleViewSet, basename='article')  # ← 필수

Custom Action (`@action`)

Router 는 표준 CRUD 외에 커스텀 endpoint 도 자동 등록:

from rest_framework.decorators import action

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    @action(detail=False, methods=['get'])
    def me(self, request):
        """GET /users/me/"""
        return Response(UserSerializer(request.user).data)

    @action(detail=False, methods=['post'])
    def bulk_delete(self, request):
        """POST /users/bulk_delete/"""
        ids = request.data.get('ids', [])
        User.objects.filter(id__in=ids).delete()
        return Response(status=204)

    @action(detail=True, methods=['post'])
    def deactivate(self, request, pk=None):
        """POST /users/{id}/deactivate/"""
        user = self.get_object()
        user.is_active = False
        user.save()
        return Response(UserSerializer(user).data)

    @action(detail=True, methods=['get'], url_path='articles',
            serializer_class=ArticleSerializer)
    def user_articles(self, request, pk=None):
        """GET /users/{id}/articles/"""
        user = self.get_object()
        articles = Article.objects.filter(author=user)
        page = self.paginate_queryset(articles)
        serializer = ArticleSerializer(page or articles, many=True)
        return self.get_paginated_response(serializer.data) if page else Response(serializer.data)

옵션	의미
`detail=True`	`/users/{id}/action/` (인스턴스별)
`detail=False`	`/users/action/` (컬렉션)
`methods=['post']`	HTTP method
`url_path='...'`	URL 이름 (기본: 메서드명)
`url_name='...'`	reverse URL 이름
`serializer_class=...`	해당 action 전용
`permission_classes=[...]`	해당 action 전용

Nested Router

기본 DRF 는 nested 지원 안 함. drf-nested-routers 사용:

pip install drf-nested-routers

from rest_framework_nested import routers

router = routers.DefaultRouter()
router.register('articles', ArticleViewSet)

# Nested
article_router = routers.NestedDefaultRouter(router, 'articles', lookup='article')
article_router.register('comments', CommentViewSet, basename='article-comments')

urlpatterns = [
    path('', include(router.urls)),
    path('', include(article_router.urls)),
]

→ /articles/{id}/comments/

URL 확인

python manage.py show_urls
# 또는 개발 서버 실행 후 API root 확인

Multiple Routers

# 버전별
router_v1 = DefaultRouter()
router_v1.register('users', UserV1ViewSet)

router_v2 = DefaultRouter()
router_v2.register('users', UserV2ViewSet)

urlpatterns = [
    path('api/v1/', include(router_v1.urls)),
    path('api/v2/', include(router_v2.urls)),
]

자세한 건 [[drf-versioning-content-negotiation]].

Custom Router

from rest_framework.routers import DefaultRouter, Route, DynamicRoute

class ReadOnlyRouter(DefaultRouter):
    """GET 만 지원"""
    routes = [
        Route(
            url=r'^{prefix}/$',
            mapping={'get': 'list'},
            name='{basename}-list',
            detail=False,
            initkwargs={'suffix': 'List'},
        ),
        Route(
            url=r'^{prefix}/{lookup}/$',
            mapping={'get': 'retrieve'},
            name='{basename}-detail',
            detail=True,
            initkwargs={'suffix': 'Detail'},
        ),
    ]

Router vs Manual URLs

flowchart TD
    Q{언제 Router?}
    Q -->|"표준 CRUD ViewSet"| R["Router"]
    Q -->|"복잡한 URL 구조"| M["수동 URLs"]
    Q -->|"1개 endpoint"| M
    Q -->|"버전별 관리"| Both["Router + 별도 include"]

다른 프레임워크

Framework	자동 라우팅
DRF	`router.register`
Rails	`resources :users`
NestJS	`@Controller` decorator
Spring Data REST	`@RepositoryRestResource`
FastAPI	없음 (수동)
Express	없음 (수동)

흔한 함정

[!WARNING]

ViewSet 없이 register = ViewSet 아닌 것 넘기면 에러.

basename 누락 (queryset 없는 ViewSet) = URL 이름 자동 생성 실패.

Nested router 순서 = child router 를 나중에 include.

@action methods 대소문자 = ['GET'] 대신 ['get'] 사용 실패.

[DRF] Tutorial + Quickstart: 첫 API 서버 5분

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Django REST Framework (DRF) 를 처음 사용 하는 사람을 위한 순차 시작 가이드. 5분 안에 동작하는 API 서버 완성.

DRF 개요는 [[django-rest-framework]]. Django 기본은 [[django-tutorial]].

DRF는 무엇인가

한 줄로: Django 위에 REST API 를 짜기 위한 배터리 포함 라이브러리.

Django 자체는 웹앱 (HTML 페이지) 을 잘 만들지만, JSON API 는 손이 많이 간다. DRF 는 그 반복을 자동화한 사실상 표준 도구.

목적

없을 때 (순수 Django)	DRF 사용 시
Model → dict 수동 변환	`Serializer` 자동
Body JSON 파싱 수동	`request.data` 자동
CRUD view 6개 손으로	`ModelViewSet` 한 줄
URL 매핑 손으로	`Router.register()` 한 줄
인증 코드 수동	`authentication_classes` 선언만
API 문서 손으로	drf-spectacular 자동

대안 비교

flowchart TB
    Q{Django에서 REST API}
    Q --> Plain["순수 Django (JsonResponse)"]
    Q --> DRF["Django REST Framework"]
    Q --> Ninja["Django Ninja"]
    Q --> FastAPI["FastAPI (별개 프레임워크)"]
    Plain --> P1["직렬화 수동, 검증 수동, 문서화 없음"]
    DRF --> D1["Serializer, ViewSet, Router 자동, OpenAPI 자동"]
    Ninja --> N1["FastAPI 스타일 (type hint), Django ORM 그대로"]
    FastAPI --> F1["가장 빠름, Django ORM은 별도 통합 필요"]

옵션	장점	단점	언제?
DRF	성숙, 커뮤니티 최대, 문서/책 많음	학습 곡선, 클래스 계층 복잡	Django 프로젝트에 REST API 얹을 때 기본 선택
Django Ninja	빠름, FastAPI 스타일, 코드 간결	상대적으로 신생, 라이브러리 생태계 작음	작은 Django 프로젝트, type hint 선호
FastAPI	가장 빠름, 비동기 우선, 타입 안전	Django ORM 통합 별도, ecosystem 다름	Django 종속성 없을 때
Plain Django	학습 곡선 낮음, 의존성 없음	매번 boilerplate 반복	endpoint 1-2개 짜리 프로토타입

DRF 는 대규모 Django 프로젝트의 REST API 표준. 새 프로젝트에 REST 필요 → DRF 기본 선택.

요청이 어떻게 흐르는가 (한눈에)

DRF는 다음 파이프라인으로 매 요청을 처리한다. 이 순서 를 알면 후속 페이지 이해가 쉽다.

{}

각 스테이지 상세:

단계	하는 일	다음 페이지
1. URL Router	path 매칭 후 View 선택	[[drf-routers]]
2. Authentication	`Authorization` 헤더 읽고 `request.user` 세팅	[[drf-authentication]]
3. Permission	이 user 가 이 view 접근 가능?	[[django-drf-permissions]]
4. Throttle	이 user 너무 자주 요청? (429)	[[drf-pagination-throttling]]
5. View	실제 비즈니스 로직	[[drf-views]], [[django-drf-viewset]]
6. Serializer	Model ↔ dict 변환, 검증	[[django-drf-serializers]]
7. Renderer	`Accept` 헤더 보고 JSON/HTML 등 선택	[[drf-request-response]]

요구사항 (2026)

Django 4.2, 5.x, 6.0
Python 3.10-3.14

설치

pip install djangorestframework
pip install markdown           # Browsable API 마크다운
pip install django-filter      # 필터링

# settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    ...,
    'rest_framework',           # ← 추가
    'rest_framework.authtoken', # Token auth 쓸 때
]

REST_FRAMEWORK = {
    'DEFAULT_AUTHENTICATION_CLASSES': [
        'rest_framework.authentication.SessionAuthentication',
        'rest_framework.authentication.TokenAuthentication',
    ],
    'DEFAULT_PERMISSION_CLASSES': [
        'rest_framework.permissions.IsAuthenticatedOrReadOnly',
    ],
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 20,
}

Quickstart: User API (5분 완성)

1. Serializer (Model → JSON)

# quickstart/serializers.py
from django.contrib.auth.models import User, Group
from rest_framework import serializers

class UserSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = User
        fields = ['url', 'username', 'email', 'groups', 'is_staff']

class GroupSerializer(serializers.HyperlinkedModelSerializer):
    class Meta:
        model = Group
        fields = ['url', 'name']

자세한 건 [[django-drf-serializers]].

2. ViewSet (Endpoint)

# quickstart/views.py
from django.contrib.auth.models import User, Group
from rest_framework import viewsets, permissions
from .serializers import UserSerializer, GroupSerializer

class UserViewSet(viewsets.ModelViewSet):
    """전체 CRUD 자동!"""
    queryset = User.objects.all().order_by('-date_joined')
    serializer_class = UserSerializer
    permission_classes = [permissions.IsAuthenticated]

class GroupViewSet(viewsets.ModelViewSet):
    queryset = Group.objects.all()
    serializer_class = GroupSerializer

자세한 건 [[django-drf-viewset]].

3. Router (URL 자동)

# urls.py
from django.urls import path, include
from rest_framework import routers
from quickstart.views import UserViewSet, GroupViewSet

router = routers.DefaultRouter()
router.register(r'users', UserViewSet)
router.register(r'groups', GroupViewSet)

urlpatterns = [
    path('', include(router.urls)),
    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
]

자세한 건 [[drf-routers]].

4. 실행

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

브라우저에서 http://127.0.0.1:8000/ 접속 → Browsable API 자동 렌더링!

Browsable API

flowchart LR
    Browser -->|Accept: text/html| DRF
    DRF -->|HTML rendering| Browsable[Browsable API<br/>인터랙티브 UI]
    Browser -->|Accept: application/json| DRF
    DRF -->|JSON| JSON[JSON 응답]

[!TIP] Browsable API 는 DRF 만의 큰 장점. 별도 도구 없이 브라우저에서 API 탐색 + 테스트. FastAPI 의 /docs 와 유사하지만 실제 endpoint 이동 가능.

API 호출 예시

# 목록 조회
curl -H 'Accept: application/json' http://127.0.0.1:8000/users/

# 생성 (session auth)
curl -X POST http://127.0.0.1:8000/users/ \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -u admin:admin \
  -d '{"username": "koa", "email": "koa@example.com", "groups": []}'

# 상세
curl http://127.0.0.1:8000/users/1/

# 삭제
curl -X DELETE http://127.0.0.1:8000/users/1/ -u admin:admin

Tutorial 순서 (권장 학습)

flowchart LR
    S["1. Quickstart<br/>(이 페이지)"] --> Ser["2. Serialization<br/>(drf-serializers)"]
    Ser --> RR["3. Requests/Responses<br/>(drf-request-response)"]
    RR --> CBV["4. Class-based views<br/>(drf-views)"]
    CBV --> Auth["5. Auth + Permissions<br/>(drf-authentication, drf-permissions)"]
    Auth --> Rel["6. Relationships<br/>(nested serializers)"]
    Rel --> VS["7. ViewSets + Routers<br/>(drf-viewset, drf-routers)"]

FBV vs APIView vs GenericView vs ViewSet

flowchart TD
    Q{복잡도 vs 자유도}
    Q -->|"최대 자유도"| FBV["@api_view (FBV)"]
    Q -->|"OO + 자유"| APIView["APIView (CBV)"]
    Q -->|"CRUD 반복"| Gen["Generic Views (ListAPIView 등)"]
    Q -->|"완전 자동 CRUD"| VS["ViewSet + Router"]

각 4개 스타일:

# 1. FBV
@api_view(['GET', 'POST'])
def user_list(request):
    if request.method == 'POST':
        serializer = UserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data, status=201)
    users = User.objects.all()
    return Response(UserSerializer(users, many=True).data)

# 2. APIView
class UserList(APIView):
    def get(self, request):
        users = User.objects.all()
        return Response(UserSerializer(users, many=True).data)

# 3. Generic Views
class UserList(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

# 4. ViewSet
class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer

다음 학습 순서

이 튜토리얼 후 순서:

[[django-drf-serializers]] - Serializer 심화
[[drf-request-response]] - Request/Response 객체
[[drf-views]] - Views 종류
[[drf-authentication]] - 인증
[[django-drf-permissions]] - 권한
[[drf-pagination-throttling]] - Pagination + Rate limit
[[drf-filtering]] - 필터링
[[django-drf-viewset]] - ViewSet 심화
[[drf-routers]] - Router 심화
[[drf-schemas-openapi]] - OpenAPI 문서화
[[drf-testing]] - 테스트

다른 프레임워크 비교

Framework	Serializer	Auto CRUD	Browsable API
DRF	Serializer	ViewSet	예
FastAPI	Pydantic	없음	Swagger UI
Django Ninja	Pydantic	없음	Swagger UI
Rails	Active Model Serializers	Scaffold	없음
Spring Boot	Jackson	Spring Data REST	없음
NestJS	class-validator	없음	Swagger 통합

흔한 함정

[!WARNING]

INSTALLED_APPS 에 rest_framework 안 넣음 = 500 error.

HyperlinkedModelSerializer 사용 시 basename 없이 register = URL 생성 실패.

CSRF token session 인증에서 안 넣음 = 401. Browsable API 는 session 이라 필요.

DEFAULT_PERMISSION_CLASSES 미설정 = 기본 모두 접근 가능 (AllowAny).

[DRF] Versioning + Content Negotiation

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

Versioning = API 의 여러 버전 공존. Content Negotiation = 같은 endpoint 가 여러 형식 (JSON, XML, HTML) 응답.

Versioning 종류

flowchart TD
    Q{Versioning}
    Q --> URL["URLPathVersioning<br/>/api/v1/users/"]
    Q --> NS["NamespaceVersioning<br/>URL namespace"]
    Q --> HN["HostNameVersioning<br/>v1.api.example.com"]
    Q --> AH["AcceptHeaderVersioning<br/>Accept: ...;version=1.0"]
    Q --> QP["QueryParameterVersioning<br/>?version=1.0"]

설정

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.URLPathVersioning',
    'DEFAULT_VERSION': 'v1',
    'ALLOWED_VERSIONS': ['v1', 'v2'],
    'VERSION_PARAM': 'version',
}

URLPathVersioning (가장 흔함)

# urls.py
urlpatterns = [
    re_path(r'^api/(?P<version>v1|v2)/', include('myapp.urls')),
]

class UserList(APIView):
    def get(self, request):
        version = request.version    # 'v1' or 'v2'
        if version == 'v2':
            return Response(UserSerializerV2(User.objects.all(), many=True).data)
        return Response(UserSerializerV1(User.objects.all(), many=True).data)

get_serializer_class 로 분기

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()

    def get_serializer_class(self):
        if self.request.version == 'v2':
            return UserSerializerV2
        return UserSerializerV1

완전 분리 (권장)

# urls.py
urlpatterns = [
    path('api/v1/', include('myapp.v1.urls')),
    path('api/v2/', include('myapp.v2.urls')),
]

# myapp/v1/views.py
class UserViewSet(viewsets.ModelViewSet):
    serializer_class = UserSerializerV1

# myapp/v2/views.py
class UserViewSet(viewsets.ModelViewSet):
    serializer_class = UserSerializerV2

[!TIP] 완전 분리 가 옛 버전 유지 + 신규 자유 개발에 유리. Get_serializer_class 분기 는 중복 로직 유지 시.

AcceptHeaderVersioning

REST_FRAMEWORK = {
    'DEFAULT_VERSIONING_CLASS': 'rest_framework.versioning.AcceptHeaderVersioning',
    'DEFAULT_VERSION': '1.0',
    'ALLOWED_VERSIONS': ['1.0', '2.0'],
}

curl -H 'Accept: application/json; version=2.0' http://localhost:8000/api/users/

Stripe 스타일 (날짜 기반)

class DateVersioning(versioning.BaseVersioning):
    default_version = '2026-06-25'
    allowed_versions = ['2024-01-01', '2025-01-01', '2026-06-25']

    def determine_version(self, request, *args, **kwargs):
        version = request.META.get('HTTP_STRIPE_VERSION', self.default_version)
        if version not in self.allowed_versions:
            raise NotAcceptable(...)
        return version

자세한 API versioning 전략은 [[api-versioning]].

Deprecation

class UserListV1(APIView):
    def get(self, request):
        response = Response(...)
        response['Sunset'] = 'Wed, 31 Dec 2026 23:59:59 GMT'
        response['Deprecation'] = 'true'
        response['Link'] = '</api/v2/users/>; rel="successor-version"'
        return response

Content Negotiation

sequenceDiagram
    Client->>DRF: GET /api/users/<br/>Accept: application/json
    DRF->>Negotiator: 선택
    Negotiator-->>DRF: JSONRenderer
    DRF-->>Client: application/json

    Client->>DRF: GET /api/users/<br/>Accept: text/html
    DRF->>Negotiator: 선택
    Negotiator-->>DRF: BrowsableAPIRenderer
    DRF-->>Client: text/html

Renderer 우선순위

REST_FRAMEWORK = {
    'DEFAULT_RENDERER_CLASSES': [
        'rest_framework.renderers.JSONRenderer',        # 1순위
        'rest_framework.renderers.BrowsableAPIRenderer', # 2순위 (HTML 요청 시)
    ]
}

Accept 헤더가 여러 형식 지원 시 → 리스트 순서 대로 선택.

Quality Value (q)

Accept: application/xml;q=0.9, application/json;q=0.8, text/html;q=0.7

XML 우선 → 없으면 JSON → 없으면 HTML.

Custom Content Negotiation

from rest_framework.negotiation import BaseContentNegotiation

class IgnoreClientContentNegotiation(BaseContentNegotiation):
    def select_parser(self, request, parsers):
        return parsers[0]

    def select_renderer(self, request, renderers, format_suffix):
        return (renderers[0], renderers[0].media_type)


class MyView(APIView):
    content_negotiation_class = IgnoreClientContentNegotiation

Format Suffix

from rest_framework.urlpatterns import format_suffix_patterns

urlpatterns = [
    path('users/', UserList.as_view()),
]
urlpatterns = format_suffix_patterns(urlpatterns)

GET /users.json    # → application/json
GET /users.api     # → text/html (Browsable)

[!NOTE] Format suffix 는 옛 패턴. 현재는 Accept 헤더 권장.

versioned URL reverse

from rest_framework.reverse import reverse

def get(self, request):
    url = reverse('user-list', request=request)   # 버전 자동 포함
    return Response({'url': url})

다른 프레임워크

Framework	Versioning	Content Negotiation
DRF	URL/Header/Query	Accept 헤더
Rails	scope로 분기	`respond_to`
Spring	@RequestMapping produces	`MediaType`
FastAPI	prefix 분리	수동
Express	수동	`req.accepts`

흔한 함정

[!WARNING]

버전 없이 시작 = breaking change 강요. v1 부터 시작.

Sunset 정책 없음 = 옛 버전 영원. 6-12개월 예고.

모든 endpoint 에 버전 = 관리 부담. 공통 리소스 는 unversioned.

Accept 헤더 파싱 실수 = q 값 무시. DRF 가 자동이지만 custom 시 주의.

[DRF] Views: APIView, GenericViews, Mixins, FBV

koa (김신건) — Thu, 25 Jun 2026 00:00:00 GMT

정의

DRF View 4가지 스타일. 자유도 vs 자동화 트레이드오프.

4가지 스타일

flowchart TD
    Q{복잡도}
    Q -->|"완전 자유"| FBV["@api_view (FBV)"]
    Q -->|"OO + 자유"| APIView["APIView"]
    Q -->|"CRUD 반복"| Gen["Generic Views"]
    Q -->|"완전 자동"| VS["ViewSet"]

스타일	코드량	자유도
`@api_view`	유사 Django FBV	최고
`APIView`	CBV	높음
`Generic Views`	몇 줄	중간
`ViewSet`	1줄	낮음 (custom action 으로 확장)

ViewSet 은 [[django-drf-viewset]] 참고.

1. FBV (`@api_view`)

from rest_framework.decorators import api_view
from rest_framework.response import Response
from rest_framework import status

@api_view(['GET', 'POST'])
def user_list(request):
    if request.method == 'GET':
        users = User.objects.all()
        serializer = UserSerializer(users, many=True)
        return Response(serializer.data)

    elif request.method == 'POST':
        serializer = UserSerializer(data=request.data)
        if serializer.is_valid():
            serializer.save()
            return Response(serializer.data, status=status.HTTP_201_CREATED)
        return Response(serializer.errors, status=status.HTTP_400_BAD_REQUEST)

Decorator 조합

from rest_framework.decorators import (
    api_view,
    authentication_classes,
    permission_classes,
    throttle_classes,
    renderer_classes,
    parser_classes,
)

@api_view(['GET'])
@authentication_classes([TokenAuthentication])
@permission_classes([IsAuthenticated])
@throttle_classes([UserRateThrottle])
def my_view(request): ...

2. APIView (CBV)

from rest_framework.views import APIView

class UserList(APIView):
    authentication_classes = [SessionAuthentication, TokenAuthentication]
    permission_classes = [IsAuthenticated]
    throttle_classes = [UserRateThrottle]

    def get(self, request):
        users = User.objects.all()
        return Response(UserSerializer(users, many=True).data)

    def post(self, request):
        serializer = UserSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        serializer.save()
        return Response(serializer.data, status=status.HTTP_201_CREATED)

APIView = Django View + DRF 기능 (인증, 권한, throttle, negotiation).

3. Generic Views

Django CBV 의 DRF 버전. CRUD 자동.

from rest_framework import generics

class UserList(generics.ListCreateAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

class UserDetail(generics.RetrieveUpdateDestroyAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

Generic View 종류

Class	메서드	의미
`ListAPIView`	GET	목록
`CreateAPIView`	POST	생성
`RetrieveAPIView`	GET (id)	상세
`UpdateAPIView`	PUT/PATCH	갱신
`DestroyAPIView`	DELETE	삭제
`ListCreateAPIView`	GET + POST	목록 + 생성
`RetrieveUpdateAPIView`	GET + PUT/PATCH	상세 + 갱신
`RetrieveDestroyAPIView`	GET + DELETE	상세 + 삭제
`RetrieveUpdateDestroyAPIView`	GET + PUT + PATCH + DELETE	전체

Mixin 조합

Generic Views 는 Mixin + GenericAPIView 조합:

from rest_framework import mixins, generics

class UserList(
    mixins.ListModelMixin,
    mixins.CreateModelMixin,
    generics.GenericAPIView,
):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    def get(self, request, *args, **kwargs):
        return self.list(request, *args, **kwargs)

    def post(self, request, *args, **kwargs):
        return self.create(request, *args, **kwargs)

Mixin 종류:

Mixin	메서드
`ListModelMixin`	`list(request)`
`CreateModelMixin`	`create(request)`
`RetrieveModelMixin`	`retrieve(request)`
`UpdateModelMixin`	`update(request)`, `partial_update(request)`
`DestroyModelMixin`	`destroy(request)`

Override 지점

class ArticleList(generics.ListCreateAPIView):
    serializer_class = ArticleSerializer

    def get_queryset(self):
        """user 별 필터"""
        return Article.objects.filter(author=self.request.user)

    def perform_create(self, serializer):
        """저장 전 커스터마이즈"""
        serializer.save(author=self.request.user)

    def get_serializer_class(self):
        """action 별 다른 serializer"""
        if self.request.method == 'POST':
            return ArticleCreateSerializer
        return ArticleSerializer

    def get_serializer_context(self):
        """context 추가"""
        ctx = super().get_serializer_context()
        ctx['extra'] = 'value'
        return ctx

URL 등록

# urls.py
from django.urls import path

urlpatterns = [
    path('users/', UserList.as_view()),
    path('users/<int:pk>/', UserDetail.as_view()),
]

Class-based view 는 as_view() 필수.

`get_object` (lookup)

class UserDetail(generics.RetrieveAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer

    lookup_field = 'username'       # 기본 'pk'
    lookup_url_kwarg = 'username'   # URL 의 인자 이름

# urls.py
path('users/<str:username>/', UserDetail.as_view())

Filter + Pagination

Generic Views 는 DEFAULT_PAGINATION_CLASS 와 FILTER_BACKENDS 자동 적용:

class UserList(generics.ListAPIView):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    filter_backends = [DjangoFilterBackend, filters.SearchFilter]
    filterset_fields = ['is_staff', 'is_active']
    search_fields = ['username', 'email']
    pagination_class = LimitOffsetPagination

자세한 건 [[drf-filtering]], [[drf-pagination-throttling]].

언제 무엇을?

flowchart TD
    Q{시나리오}
    Q -->|1개 endpoint 특수 로직| FBV["@api_view"]
    Q -->|공유 로직 있는 여러 endpoint| APIView
    Q -->|표준 CRUD, 소량 override| Gen["Generic Views"]
    Q -->|CRUD 완전 자동| VS["ViewSet"]

사용	권장
Function 하나 (예: webhook)	`@api_view`
상속으로 공통 로직	`APIView`
표준 CRUD	`Generic Views`
리소스 완전 자동화	`ViewSet`

다른 프레임워크 비교

Framework	List/Detail 자동
DRF	`ListAPIView`, `RetrieveUpdateDestroyAPIView`
Spring	`@RestController` + Spring Data REST
Rails	Scaffold
FastAPI	없음 (수동 dependency injection)
NestJS	Custom decorator

흔한 함정

[!WARNING]

APIView + as_view() 잊음 = URL 등록 실패.

get_queryset override 안 함 + 큰 queryset = 매번 전체 fetch.

Mixin 순서 잘못 = Mixin 이 GenericAPIView 앞. 순서 중요.

@api_view 없이 함수 = DRF 기능 (permission, throttle) 안 적용.

[Django] Admin: 자동 생성 관리자 페이지

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Django Admin은 모델 등록만으로 CRUD UI 자동 생성하는 내장 백오피스. 내부 운영 도구, 콘텐츠 관리(CMS) 등에 강력. 권한 시스템 통합. Rails에는 표준에 없는 차별점.

활성화

django.contrib.admin이 기본 INSTALLED_APPS에 있고 URL conf에도 기본 포함.

# settings.py
INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    ...
]

# urls.py
from django.contrib import admin
urlpatterns = [
    path("admin/", admin.site.urls),
]

python manage.py createsuperuser
python manage.py runserver
# /admin/ 접속

모델 등록

# blog/admin.py
from django.contrib import admin
from .models import Post, Tag

admin.site.register(Post)
admin.site.register(Tag)

또는 데코레이터:

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "author", "created_at", "is_published"]

ModelAdmin 핵심 옵션

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    # 목록 페이지
    list_display = ["title", "author", "created_at", "is_published", "view_count"]
    list_display_links = ["title"]
    list_filter = ["is_published", "created_at", "author"]
    search_fields = ["title", "body"]
    list_select_related = ["author"]      # N+1 회피
    list_per_page = 50
    date_hierarchy = "created_at"          # 날짜 드릴다운
    ordering = ["-created_at"]
    list_editable = ["is_published"]       # 인라인 편집

    # 상세 페이지
    fields = ["title", "slug", "body", "author"]      # 또는
    fieldsets = [
        ("기본", {"fields": ["title", "slug", "body"]}),
        ("메타", {"fields": ["author", "is_published"], "classes": ["collapse"]}),
    ]
    readonly_fields = ["created_at", "updated_at"]
    prepopulated_fields = {"slug": ["title"]}    # JS로 자동 채움
    autocomplete_fields = ["author"]              # 검색형 select
    raw_id_fields = ["category"]                  # ID 입력 + popup
    filter_horizontal = ["tags"]                  # M2M 위젯

    # 커스텀 메서드
    def view_count(self, obj):
        return obj.views
    view_count.short_description = "조회수"
    view_count.admin_order_field = "views"

list_display에 함수/메서드도 가능.

커스텀 액션

목록 페이지의 체크박스 + 액션 드롭다운.

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    actions = ["make_published", "make_draft"]

    @admin.action(description="선택 항목 발행")
    def make_published(self, request, queryset):
        updated = queryset.update(is_published=True)
        self.message_user(request, f"{updated}건 발행됨")

    @admin.action(description="선택 항목 임시저장으로")
    def make_draft(self, request, queryset):
        queryset.update(is_published=False)

InlineModelAdmin: 자식 편집

부모-자식 관계를 한 화면에서.

class CommentInline(admin.TabularInline):    # 또는 StackedInline
    model = Comment
    extra = 1
    fields = ["author", "body", "approved"]
    readonly_fields = ["created_at"]

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    inlines = [CommentInline]

TabularInline은 표 형식, StackedInline은 박스 형식.

Form 커스터마이즈

from django import forms

class PostAdminForm(forms.ModelForm):
    class Meta:
        model = Post
        fields = "__all__"
        widgets = {
            "body": forms.Textarea(attrs={"rows": 20, "cols": 80}),
        }

    def clean_title(self):
        title = self.cleaned_data["title"]
        if "스팸" in title:
            raise forms.ValidationError("부적절한 단어 포함")
        return title

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    form = PostAdminForm

save_model: 저장 전후 hook

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    def save_model(self, request, obj, form, change):
        if not change:    # 새로 생성
            obj.author = request.user
        super().save_model(request, obj, form, change)

    def delete_model(self, request, obj):
        log.info(f"Deleting {obj}")
        super().delete_model(request, obj)

get_queryset: 권한별 필터링

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        qs = super().get_queryset(request)
        if request.user.is_superuser:
            return qs
        return qs.filter(author=request.user)

일반 staff는 자기 글만 보이게.

권한

Django 기본 권한: app.add_model, change_model, delete_model, view_model.

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    def has_add_permission(self, request):
        return request.user.is_superuser

    def has_change_permission(self, request, obj=None):
        if obj is None:
            return True
        return obj.author == request.user or request.user.is_superuser

    def has_delete_permission(self, request, obj=None):
        return request.user.is_superuser

검색 with autocomplete

@admin.register(Author)
class AuthorAdmin(admin.ModelAdmin):
    search_fields = ["name", "email"]    # autocomplete의 검색 필드

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    autocomplete_fields = ["author"]      # Author admin이 search_fields 정의해야

대량 데이터에서 모든 옵션 로드(Select)는 느림. autocomplete로 검색형 selection.

list_display 추가 표시

from django.utils.html import format_html

@admin.register(Post)
class PostAdmin(admin.ModelAdmin):
    list_display = ["title", "colored_status", "preview"]

    @admin.display(description="상태", ordering="is_published")
    def colored_status(self, obj):
        color = "green" if obj.is_published else "gray"
        return format_html('<span style="color:{}">{}</span>',
                            color, "발행" if obj.is_published else "임시저장")

    def preview(self, obj):
        return obj.body[:50] + ("..." if len(obj.body) > 50 else "")

커스텀 admin site

여러 사이트, 다른 URL/디자인.

# myadmin.py
from django.contrib import admin

class MyAdminSite(admin.AdminSite):
    site_header = "My Blog 관리"
    site_title = "My Blog Admin"
    index_title = "환영합니다"

    def get_app_list(self, request, app_label=None):
        # 앱 순서 커스텀
        return super().get_app_list(request, app_label)

my_admin = MyAdminSite(name="myadmin")
my_admin.register(Post, PostAdmin)

# urls.py
path("myadmin/", my_admin.urls),

기본 admin.site 외부에서.

함정

1. list_display + 외래키 → N+1

list_display = ["title", "author"]    # author 조회마다 SQL

# 해결
list_select_related = ["author"]

자동 안 됨. 명시 필요.

2. 큰 ForeignKey 드롭다운

author = ForeignKey(User, ...)
# admin에서 select에 모든 사용자 → 10만 명이면 멈춤

# 해결
raw_id_fields = ["author"]            # ID + popup
# 또는
autocomplete_fields = ["author"]      # 검색형 (User admin이 search_fields 필요)

3. list_editable + ordering 충돌

list_editable = ["title"]
list_display = ["title", "author"]    # 첫 항목이 list_display_links와 같으면 안 됨

list_editable 항목은 link 아닌 위치에 둘 것.

4. fieldsets vs fields 동시 사용

둘 중 하나만. fieldsets가 더 유연.

5. 관리자 화면을 일반 사용자에게 노출 X

관리자는 내부 도구. 일반 사용자용 대시보드는 별도 view로 작성.

자주 보는 패턴

다중 DB / Cross-app

@admin.register(Order)
class OrderAdmin(admin.ModelAdmin):
    def get_queryset(self, request):
        return super().get_queryset(request).using("orders_db")

MULTI_DB에서 활용.

다국어 admin

# settings.py
LANGUAGE_CODE = "ko-kr"
USE_I18N = True

# models.py
class Post(models.Model):
    class Meta:
        verbose_name = "포스트"
        verbose_name_plural = "포스트들"

verbose_name이 admin 표시 이름.

대용량 export

기본 admin은 export 안 함. django-import-export 라이브러리:

pip install django-import-export

from import_export.admin import ImportExportModelAdmin

@admin.register(Post)
class PostAdmin(ImportExportModelAdmin):
    ...

CSV/Excel import/export 자동.

Admin 액션으로 비동기 작업

@admin.action(description="발송 큐 등록")
def queue_send(self, request, queryset):
    for obj in queryset:
        send_email.delay(obj.id)    # Celery
    self.message_user(request, f"{queryset.count()}건 큐 등록")

대량 작업은 Celery로 위임. admin은 큐만.

Django Admin vs Custom Dashboard

	Django Admin	커스텀 대시보드
빠른 구축	O	X
UI/UX 자유도	낮음	높음
권한 시스템	내장	직접 구현
외부 사용자 노출	X (내부용)	O

내부 운영 + 빠른 구축 → Admin. 사용자 대상 → 직접 작성.

[Django] Aggregation: annotate, aggregate, F, Q, Window

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Django ORM의 annotate / aggregate / F / Q / Window는 SQL의 GROUP BY, 집계 함수, 동적 조건, 컬럼 참조, Window 함수를 Python으로 표현. N+1 회피 + DB에서 무거운 계산 위임.

aggregate (전체)

from django.db.models import Count, Sum, Avg, Max, Min, F

stats = Post.objects.aggregate(
    total=Count("id"),
    avg_views=Avg("views"),
    max_views=Max("views"),
    total_views=Sum("views"),
)
# {"total": 100, "avg_views": 42.5, "max_views": 1000, "total_views": 4250}

stats["avg_views"]    # dict

annotate (group by)

# 각 작성자별 글 수
from django.db.models import Count

authors = User.objects.annotate(post_count=Count("posts"))
for a in authors:
    print(a.username, a.post_count)

# 정렬 + 필터
top = User.objects.annotate(post_count=Count("posts")).filter(post_count__gt=10).order_by("-post_count")

내부적으로 SQL GROUP BY user.id + COUNT(post.id). ORM이 자동 처리.

여러 annotation 동시 (함정)

# WRONG: 결과가 곱해짐
User.objects.annotate(
    post_count=Count("posts"),
    comment_count=Count("comments"),
)
# JOIN posts × JOIN comments → cartesian product

해결 1: distinct

User.objects.annotate(
    post_count=Count("posts", distinct=True),
    comment_count=Count("comments", distinct=True),
)

해결 2: Subquery (더 정확)

from django.db.models import OuterRef, Subquery, Count

post_count = Post.objects.filter(author=OuterRef("pk")).order_by().values("author").annotate(c=Count("*")).values("c")
comment_count = Comment.objects.filter(author=OuterRef("pk")).order_by().values("author").annotate(c=Count("*")).values("c")

User.objects.annotate(
    post_count=Subquery(post_count),
    comment_count=Subquery(comment_count),
)

F 표현식 (컬럼 참조)

from django.db.models import F

# 조회수 1 증가 (원자적)
Post.objects.filter(id=1).update(views=F("views") + 1)

# 두 컬럼 비교
Post.objects.filter(updated_at__gt=F("created_at"))

# 컬럼 간 연산
Post.objects.annotate(net_score=F("likes") - F("dislikes"))

# 다른 테이블 컬럼
Post.objects.filter(author__points__gt=F("min_points_required"))

Q 객체 (복합 조건)

from django.db.models import Q

# OR
Post.objects.filter(Q(is_published=True) | Q(is_featured=True))

# AND + NOT
Post.objects.filter(Q(views__gt=100) & ~Q(author=current_user))

# 동적
q = Q()
if search:
    q &= Q(title__icontains=search) | Q(body__icontains=search)
if author_id:
    q &= Q(author_id=author_id)
posts = Post.objects.filter(q)

Conditional (Case/When)

from django.db.models import Case, When, Value, IntegerField, CharField

Post.objects.annotate(
    priority=Case(
        When(is_featured=True, then=Value(1)),
        When(views__gt=1000, then=Value(2)),
        When(views__gt=100, then=Value(3)),
        default=Value(4),
        output_field=IntegerField(),
    )
).order_by("priority")

# 라벨링
status_label=Case(
    When(status="draft", then=Value("초안")),
    When(status="published", then=Value("발행")),
    default=Value("기타"),
    output_field=CharField(),
)

Subquery / OuterRef

from django.db.models import Subquery, OuterRef

# 각 작성자의 최신 글 제목
latest_post = Post.objects.filter(
    author=OuterRef("pk")
).order_by("-created_at").values("title")[:1]

User.objects.annotate(latest_title=Subquery(latest_post))

# EXISTS
from django.db.models import Exists

has_comments = Comment.objects.filter(post=OuterRef("pk"))
Post.objects.annotate(has_comments=Exists(has_comments))

Window 함수 (3.2+)

from django.db.models import Window, F
from django.db.models.functions import Rank, DenseRank, RowNumber, Lag, Lead, FirstValue, LastValue

# 각 작성자별로 글 순위
Post.objects.annotate(
    rank=Window(
        expression=Rank(),
        partition_by=[F("author")],
        order_by=F("views").desc(),
    )
).filter(rank__lte=3)    # 작성자별 top 3

# 이전 글
Post.objects.annotate(
    prev_id=Window(
        expression=Lag("id"),
        partition_by=[F("author")],
        order_by=F("created_at"),
    )
)

# 누적 합
Post.objects.annotate(
    running_total=Window(
        expression=Sum("views"),
        order_by=F("created_at"),
    )
)

DB에서 직접 계산. Python 루프보다 매우 빠름.

values + annotate (GROUP BY 명시)

# 작성자별 통계
Post.objects.values("author__username").annotate(
    total=Count("id"),
    avg_views=Avg("views"),
).order_by("-total")
# [{"author__username": "alice", "total": 50, "avg_views": 100.0}, ...]

명시적으로 그룹화할 컬럼 지정.

자주 보는 패턴

Pagination + Count 최적화

posts = Post.objects.all()
total = posts.count()    # SELECT COUNT(*)
page = posts[offset:offset + limit]

큰 테이블에서 COUNT가 느림. estimate 또는 cursor pagination.

통계 dashboard

from django.db.models.functions import TruncMonth, TruncDate

# 월별 가입자 수
User.objects.annotate(
    month=TruncMonth("date_joined")
).values("month").annotate(
    count=Count("id")
).order_by("month")

# 일별
User.objects.annotate(day=TruncDate("date_joined")).values("day").annotate(count=Count("id"))

Conditional aggregation

from django.db.models import Sum, Q

Post.objects.aggregate(
    published_views=Sum("views", filter=Q(is_published=True)),
    draft_views=Sum("views", filter=Q(is_published=False)),
)

3.0+ filter 인자 지원.

Median / Percentile

기본 ORM에 없지만 raw 또는 percentile_cont (PG):

from django.db.models import F
from django.db.models.functions import PercentileCont

# PG 8.4+
posts = Post.objects.aggregate(
    median=PercentileCont(0.5).within_group(F("views"))
)

또는 Subquery + LIMIT/OFFSET.

비싼 annotation 캐싱

@cached_property
def total_views(self):
    return self.posts.aggregate(t=Sum("views"))["t"] or 0

또는 denormalize:

class User(models.Model):
    total_views = models.PositiveIntegerField(default=0)

# signal로 동기화
@receiver(post_save, sender=Post)
def update_total(sender, instance, **kwargs):
    user = instance.author
    user.total_views = user.posts.aggregate(t=Sum("views"))["t"] or 0
    user.save()

함정

1. JOIN 결과 곱

위에서 설명. 여러 reverse FK를 동시 Count 시 cartesian. distinct 또는 Subquery.

2. annotate 순서

Post.objects.annotate(a=Count("comments")).filter(a__gt=5).annotate(b=Count("tags"))
# a는 모든 댓글, b는 a 필터 후 태그

순서에 따라 결과 다름.

3. F 표현식과 Python 연산

post.views += 1
post.save()
# 동시 다수 요청 → race condition

Post.objects.filter(id=post.id).update(views=F("views") + 1)
# DB 레벨 atomic
post.refresh_from_db()

4. Subquery output_field

Subquery(post_count, output_field=IntegerField())

명시 권장. 추론 실패 시 에러.

5. count() vs len(qs)

qs.count()     # SQL COUNT
len(qs)        # 모두 로드 후 len

count로 분기.

[Django] async views와 ASGI

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Django 3.1+ 부터 async view를 지원한다. async def로 view를 정의하면 ASGI 서버(Uvicorn, Daphne, Hypercorn) 아래에서 코루틴으로 실행. I/O 바운드(외부 API, DB - 4.1+, 캐시) 작업에서 동시 처리량 향상. CPU 작업이나 동기 라이브러리엔 효과 X 또는 음수.

ORM은 5.0+에서 본격 비동기 (afilter, aget 등). 그 전엔 sync_to_async로 래핑.

async view 기본

import asyncio
from django.http import JsonResponse

async def async_view(request):
    await asyncio.sleep(1)
    return JsonResponse({"ok": True})

# 외부 HTTP
import httpx

async def fetch_data(request):
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com/data")
    return JsonResponse(r.json())

URL conf에 평소처럼 등록. Django가 async view를 감지하면 적절히 실행.

동기 view와 async view 혼재

같은 프로젝트에 둘 다 가능. Django가 자동으로 양방향 변환:

동기 view + 비동기 미들웨어 → 동기를 thread pool에서 실행
비동기 view + 동기 미들웨어 → 미들웨어를 sync_to_async

자동 변환은 작동하지만 성능 손해. 가능한 한 일관 유지.

ORM의 async (4.1+, 5.0+)

# 5.0+
async def view(request):
    post = await Post.objects.aget(id=1)
    posts = [p async for p in Post.objects.filter(is_published=True)]
    count = await Post.objects.acount()
    return JsonResponse({"count": count})

비동기 메서드는 a 접두 (aget, afilter, acount, acreate, asave, adelete, aupdate, afirst, alast, aexists, aiterator).

5.0 이전에는 sync_to_async로 래핑.

sync_to_async / async_to_sync

from asgiref.sync import sync_to_async, async_to_sync

async def view(request):
    # 동기 함수를 비동기 컨텍스트에서
    posts = await sync_to_async(list)(Post.objects.all())

    # ORM 직접 호출 (5.0 이전)
    user = await sync_to_async(User.objects.get)(id=1)

def sync_view(request):
    # 비동기 함수를 동기에서
    result = async_to_sync(fetch)("url")
    return JsonResponse(result)

thread_sensitive=True(기본)는 같은 스레드 보장 (DB 트랜잭션 안전). False는 더 빠르지만 thread-local에 문제 생길 수 있음.

ASGI 서버

WSGI(Gunicorn 등)는 동기. 비동기 view를 활용하려면 ASGI 서버:

pip install uvicorn
uvicorn myproject.asgi:application --workers 4

또는 Daphne, Hypercorn, Granian.

# myproject/asgi.py
import os
from django.core.asgi import get_asgi_application

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
application = get_asgi_application()

gunicorn + uvicorn worker도 인기:

gunicorn myproject.asgi:application -k uvicorn.workers.UvicornWorker --workers 4

자주 보는 패턴

동시 외부 API 호출

import asyncio
import httpx

async def dashboard(request):
    async with httpx.AsyncClient() as client:
        users_resp, orders_resp, metrics_resp = await asyncio.gather(
            client.get("https://api1.example/users"),
            client.get("https://api2.example/orders"),
            client.get("https://api3.example/metrics"),
        )
    return JsonResponse({
        "users": users_resp.json(),
        "orders": orders_resp.json(),
        "metrics": metrics_resp.json(),
    })

세 외부 호출이 1초씩이면 동기는 3초, 비동기는 ~1초.

Streaming response

from django.http import StreamingHttpResponse
import asyncio

async def stream_view(request):
    async def gen():
        for i in range(10):
            yield f"data: {i}\n\n"
            await asyncio.sleep(1)

    return StreamingHttpResponse(gen(), content_type="text/event-stream")

SSE, 실시간 로그 스트림 등.

LLM/OpenAI 통합

async def chat(request):
    body = json.loads(request.body)
    response = StreamingHttpResponse(content_type="text/event-stream")

    async def stream():
        async with openai_client.responses.stream(...) as s:
            async for event in s:
                yield f"data: {event.text}\n\n"

    return StreamingHttpResponse(stream(), content_type="text/event-stream")

긴 LLM 응답을 토큰 단위로 흘려보냄.

백그라운드 작업 트리거

async def trigger(request):
    asyncio.create_task(background_job())    # fire-and-forget
    return JsonResponse({"started": True})

async def background_job():
    await asyncio.sleep(10)
    ...

단 ASGI 서버 종료 시 task가 잘릴 수 있어 프로덕션엔 Celery 등 권장.

함정

1. 동기 ORM in async view

async def view(request):
    posts = Post.objects.all()           # OK (lazy)
    list(posts)                           # WARN: sync 호출 in async context

    # 5.0+
    posts = [p async for p in Post.objects.all()]    # OK

SynchronousOnlyOperation 예외 발생할 수 있음. 명시적 sync_to_async 또는 a- 메서드.

2. 동기 라이브러리 사용

async def view(request):
    requests.get("...")    # 블로킹! 이벤트 루프 정지

asyncio 친화 라이브러리: httpx, aiohttp, aiomysql, asyncpg, redis.asyncio.

대체 어렵다면 sync_to_async(requests.get)("...") (스레드 풀로 위임).

3. 미들웨어 모두 async?

미들웨어가 동기/비동기 혼재면 변환 비용. 가능한 한 통일.

class AsyncMiddleware:
    sync_capable = True
    async_capable = True

    def __init__(self, get_response):
        self.get_response = get_response

    async def __call__(self, request):
        response = await self.get_response(request)
        return response

4. 트랜잭션과 sync_to_async

thread_sensitive=False로 다른 스레드에서 실행 시 트랜잭션 컨텍스트 누락. 기본 True 유지.

5. 캐시 백엔드

Django cache 백엔드 일부는 sync만. 비동기 코드 안에서 cache.get은 SynchronousOnlyOperation 가능.

acache.get (5.0+) 또는 sync_to_async.

성능 기대치

외부 I/O 동시 호출: 큰 향상 (5-10x)
DB 단순 조회: 거의 동등 (5.0+에서 async ORM도 thread pool 위임)
CPU 작업: 향상 없음 (또는 단점)
단일 동기 라이브러리 잠시 호출: 미미

async가 만능 아님. 측정 후 결정.

Django Channels

표준 async view는 WebSocket 지원 X. Channels로 확장.

pip install channels[daphne]

# settings.py
INSTALLED_APPS = ["daphne", ..., "channels"]
ASGI_APPLICATION = "myproject.asgi.application"

# asgi.py
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
from myapp.routing import websocket_urlpatterns

application = ProtocolTypeRouter({
    "http": get_asgi_application(),
    "websocket": AuthMiddlewareStack(URLRouter(websocket_urlpatterns)),
})

Consumer:

from channels.generic.websocket import AsyncWebsocketConsumer

class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        await self.accept()

    async def receive(self, text_data):
        await self.send(text_data=f"Echo: {text_data}")

자세한 건 django-channels 페이지.

[Django] Caching: per-site, per-view, low-level

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Django 캐싱은 데이터/페이지 재생성 비용 회피의 핵심. 4단계 그래뉴얼리티 제공: site-wide → per-view → template fragment → low-level. Redis, Memcached, DB, 로컬 메모리, 파일 시스템 등 백엔드 선택.

캐시 백엔드 설정

# settings.py
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/1",
    }
}

빌트인 백엔드:

BACKEND	용도
`redis.RedisCache` (4.0+)	프로덕션 표준
`memcached.PyMemcacheCache`	프로덕션 표준
`db.DatabaseCache`	DB 활용 (간단하지만 느림)
`locmem.LocMemCache`	프로세스 로컬 (기본)
`filebased.FileBasedCache`	파일 시스템
`dummy.DummyCache`	캐시 안 함 (개발)

여러 캐시 동시 설정 가능:

CACHES = {
    "default": {"BACKEND": "...Redis...", "LOCATION": "redis://..."},
    "sessions": {"BACKEND": "...Redis...", "LOCATION": "redis://..."},
    "fast": {"BACKEND": "...LocMem..."},
}

cache = caches["sessions"]

low-level cache API

from django.core.cache import cache

cache.set("key", "value", timeout=300)    # 5분 (기본 300)
cache.set("key", "value", timeout=None)    # 영구
cache.get("key")                            # None if 없음
cache.get("key", default="fallback")
cache.add("key", "value")                   # 이미 있으면 무시
cache.get_or_set("key", lambda: expensive())
cache.delete("key")
cache.clear()                                # 전체 (위험)

# 원자적 증감
cache.incr("counter")
cache.decr("counter")

# 다중 키
cache.set_many({"a": 1, "b": 2})
cache.get_many(["a", "b"])
cache.delete_many(["a", "b"])

per-view cache

from django.views.decorators.cache import cache_page

@cache_page(60 * 15)    # 15분
def my_view(request):
    return render(request, "...")

# URL에서
from django.urls import path
urlpatterns = [
    path("posts/", cache_page(60 * 5)(post_list)),
]

요청 URL + 쿼리스트링이 캐시 키. 사용자별로 다른 응답엔 부적합 (모두에게 같은 응답).

vary_on_cookie / vary_on_headers:

from django.views.decorators.vary import vary_on_cookie, vary_on_headers

@cache_page(60 * 15)
@vary_on_cookie    # 쿠키에 따라 다른 캐시 (로그인 등)
def my_view(request):
    ...

@vary_on_headers("Accept-Language")
def view(request):
    ...

per-site cache (모든 페이지)

MIDDLEWARE = [
    "django.middleware.cache.UpdateCacheMiddleware",    # 가장 먼저
    "django.middleware.common.CommonMiddleware",
    "django.middleware.cache.FetchFromCacheMiddleware",  # 가장 나중
    ...
]

CACHE_MIDDLEWARE_SECONDS = 600
CACHE_MIDDLEWARE_KEY_PREFIX = ""
CACHE_MIDDLEWARE_ALIAS = "default"

전체 사이트가 익명 사용자에게 같은 응답이면 OK. 거의 안 씀.

template fragment cache

{% load cache %}

{% cache 600 sidebar request.user.id %}
    ... 비싼 sidebar 렌더링 ...
{% endcache %}

vary 키를 인자로 추가. 600초.

{% cache 600 sidebar request.user.id LANGUAGE_CODE %}

QuerySet cache

def get_top_posts():
    key = "top_posts"
    posts = cache.get(key)
    if posts is None:
        posts = list(Post.objects.order_by("-views")[:10])
        cache.set(key, posts, 300)
    return posts

# 또는 get_or_set
def get_top_posts():
    return cache.get_or_set("top_posts", lambda: list(Post.objects.order_by("-views")[:10]), 300)

ORM 결과를 list로 변환해야 pickle 가능.

캐시 무효화

캐싱의 진짜 어려움은 무효화.

signal 기반

@receiver([post_save, post_delete], sender=Post)
def invalidate(sender, instance, **kwargs):
    cache.delete(f"post:{instance.slug}")
    cache.delete("top_posts")

versioned key

def get_post(slug):
    version = cache.get(f"post:{slug}:version", 0)
    return cache.get_or_set(
        f"post:{slug}:v{version}",
        lambda: Post.objects.get(slug=slug),
    )

@receiver(post_save, sender=Post)
def bump_version(sender, instance, **kwargs):
    cache.incr(f"post:{instance.slug}:version", initial=1)

이전 버전은 TTL로 자연 만료.

django-cachalot 또는 django-cache-utils 같은 라이브러리.

Redis 직접 사용 (고급)

Django cache API는 추상화라 Redis 특화 기능(Sorted Set, Pub/Sub, Stream) 못 씀. 필요 시 redis-py 직접.

import redis

r = redis.from_url(settings.REDIS_URL)
r.zadd("leaderboard", {user_id: score})
r.zrevrange("leaderboard", 0, 10, withscores=True)

Session backend로 cache

SESSION_ENGINE = "django.contrib.sessions.backends.cache"
SESSION_CACHE_ALIAS = "default"

세션을 Redis에 저장. 빠르나 evict 시 로그아웃 위험 → cached_db (DB 백업).

함정

1. cache.set 후 즉시 get → None

cache.set("k", "v", 0)    # timeout 0이면 즉시 만료 (Memcached 일부 버전)
cache.get("k")             # None

timeout=0의 의미가 백엔드마다 다름. 명시적 양수.

2. cache.clear()

모든 키 삭제. 다른 앱과 백엔드 공유 시 위험. 키 prefix 명확히.

CACHES = {"default": {..., "KEY_PREFIX": "myapp:"}}

3. cache thunder herd

캐시 만료 순간 동시 다수 요청이 DB로 → 폭주.

해결:

미리 갱신 (TTL 도달 전)
lock 기반 단일 갱신
Stale-while-revalidate 패턴

4. 큰 객체 캐싱

cache.set("queryset", list(Post.objects.all()), 300)    # 10만 개면 메모리 폭발

크기 제한.

5. pickle 안 됨

cache.set("func", lambda x: x)    # PicklingError

함수, 클래스 인스턴스 일부는 캐시 불가.

6. cache stampede with `get_or_set`

cache.get_or_set("k", expensive)    # 만료 직후 동시 호출 → 모두 expensive 호출

add + lock으로 보호.

자주 보는 패턴

conditional view cache

from django.views.decorators.cache import cache_page
from django.views.decorators.vary import vary_on_cookie

@cache_page(60 * 5)
@vary_on_cookie
def article_detail(request, slug):
    ...

template caching for partials

{% cache 600 post_card post.id post.updated_at %}
    {# post 카드 (updated_at 변경 시 자동 무효화) #}
{% endcache %}

vary 키에 updated_at 포함 → 모델 저장 시 새 키, 옛 키는 자연 만료.

Cache layer 추상

def cached(key_fn, ttl=300):
    def decorator(fn):
        @wraps(fn)
        def wrapper(*args, **kwargs):
            key = key_fn(*args, **kwargs)
            value = cache.get(key)
            if value is None:
                value = fn(*args, **kwargs)
                cache.set(key, value, ttl)
            return value
        return wrapper
    return decorator

@cached(lambda slug: f"post:{slug}")
def get_post(slug):
    return Post.objects.get(slug=slug)

직접 만들기보다 django-cacheops, django-cachalot 등 검토.

모니터링

캐시 히트율 (메트릭)
캐시 키 분포 (redis-cli --bigkeys)
TTL 분포
메모리 사용량

django-cache-memoize, Sentry, Datadog 등.

[Django] Celery: 비동기 태스크와 큐

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Celery는 Python의 분산 태스크 큐. 비동기·예약·재시도 작업을 워커가 처리. Django와 통합되어 이메일 발송, 이미지 처리, ML 추론, 스크래핑 같은 무거운 작업을 HTTP 요청 처리에서 분리.

브로커: Redis 또는 RabbitMQ가 주류. 결과 저장: 같은 브로커 또는 별도 DB.

설치

pip install celery redis

설정

# myproject/celery.py
import os
from celery import Celery

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")

app = Celery("myproject")
app.config_from_object("django.conf:settings", namespace="CELERY")
app.autodiscover_tasks()

# myproject/__init__.py
from .celery import app as celery_app
__all__ = ("celery_app",)

# settings.py
CELERY_BROKER_URL = "redis://localhost:6379/0"
CELERY_RESULT_BACKEND = "redis://localhost:6379/1"
CELERY_TASK_SERIALIZER = "json"
CELERY_ACCEPT_CONTENT = ["json"]
CELERY_TIMEZONE = "Asia/Seoul"
CELERY_TASK_TRACK_STARTED = True
CELERY_TASK_TIME_LIMIT = 30 * 60    # 30분

Task 정의

# blog/tasks.py
from celery import shared_task

@shared_task
def send_welcome_email(user_id):
    user = User.objects.get(id=user_id)
    send_mail("환영합니다", "...", "no-reply@example.com", [user.email])

@shared_task
def process_image(image_path):
    img = Image.open(image_path)
    img.thumbnail((1024, 1024))
    img.save(image_path + ".small.jpg")

@shared_task는 모든 Celery 앱에서 발견. @app.task는 특정 앱.

호출

# 비동기 호출 (워커가 처리)
send_welcome_email.delay(user.id)

# 더 세밀한 옵션
send_welcome_email.apply_async(
    args=[user.id],
    countdown=10,                  # 10초 후
    eta=datetime(...),             # 특정 시각
    expires=60,                    # 60초 후 expire
    retry=True,
    retry_policy={"max_retries": 3, "interval_start": 0, "interval_step": 0.2},
    queue="emails",
    priority=5,
)

delay는 apply_async의 단축형 (인자만).

결과

result = send_welcome_email.delay(user.id)
result.id                          # task UUID
result.status                      # PENDING, STARTED, SUCCESS, FAILURE
result.ready()
result.get(timeout=10)             # 결과 대기 (블록)

대부분 fire-and-forget. result 안 필요하면 ignore_result=True.

재시도

@shared_task(bind=True, max_retries=3, default_retry_delay=60)
def call_api(self, url):
    try:
        return requests.get(url, timeout=10).json()
    except Exception as exc:
        raise self.retry(exc=exc, countdown=2 ** self.request.retries)

bind=True로 self 받음. exponential backoff. autoretry_for=(ExceptionType,) 옵션도.

@shared_task(autoretry_for=(requests.RequestException,), retry_backoff=True, max_retries=5)
def call_api(url):
    return requests.get(url, timeout=10).json()

Worker 실행

celery -A myproject worker -l info
celery -A myproject worker -l info -Q emails,default    # 특정 큐만
celery -A myproject worker -l info --concurrency=8       # 워커 프로세스 수

Celery Beat (스케줄러)

celery -A myproject beat -l info

# settings.py
from celery.schedules import crontab

CELERY_BEAT_SCHEDULE = {
    "send-daily-digest": {
        "task": "blog.tasks.send_daily_digest",
        "schedule": crontab(hour=9, minute=0),
    },
    "cleanup-temp": {
        "task": "blog.tasks.cleanup",
        "schedule": 3600.0,    # 1시간마다
    },
}

DB 기반 동적 스케줄은 django-celery-beat:

INSTALLED_APPS += ["django_celery_beat"]
CELERY_BEAT_SCHEDULER = "django_celery_beat.schedulers:DatabaseScheduler"

admin에서 스케줄 변경 가능.

Task 체이닝

from celery import chain, group, chord

# 순차
chain(fetch.s(url), process.s(), save.s())()

# 병렬
group(process.s(item) for item in items)()

# 병렬 후 합산
chord(group(crunch.s(i) for i in range(100)))(summarize.s())

.s() (signature)로 인자 일부 고정. 함수형 컴포지션.

Worker 종류

celery -A myproject worker --pool=prefork    # 기본 (Unix)
celery -A myproject worker --pool=gevent --concurrency=1000    # I/O 바운드
celery -A myproject worker --pool=threads --concurrency=20
celery -A myproject worker --pool=solo                          # 디버그

prefork: CPU 분리 + 안정성
gevent: greenlet, 수천 동시 I/O
threads: GIL 영향
solo: 단일 스레드 (디버그)

모니터링: Flower

pip install flower
celery -A myproject flower    # http://localhost:5555

활성 워커, 큐 길이, 태스크 통계 시각화.

Sentry, Prometheus 통합

Celery 태스크 안의 예외도 Sentry로:

import sentry_sdk
sentry_sdk.init(dsn=..., integrations=[...])

celery-prometheus-exporter로 메트릭 수집.

자주 보는 패턴

Django Signal에서 Celery

@receiver(post_save, sender=Post)
def reindex(sender, instance, **kwargs):
    reindex_post.delay(instance.id)

Signal handler는 동기 빠른 처리만 → Celery로 위임.

트랜잭션 안에서 호출

from django.db import transaction

def view(request):
    post = Post.objects.create(...)
    transaction.on_commit(lambda: process_image.delay(post.id))

트랜잭션 commit 후에 task 호출. 안 그러면 워커가 아직 commit 안 된 데이터 못 찾음.

큰 작업 청크 분할

@shared_task
def process_chunk(start, end):
    for item in Item.objects.filter(id__range=(start, end)):
        process(item)

def trigger_all():
    total = Item.objects.count()
    chunk_size = 1000
    for start in range(0, total, chunk_size):
        process_chunk.delay(start, start + chunk_size)

100만 행을 1000 → 1000개 워커 또는 직렬 처리.

Task lock (동일 작업 중복 방지)

from django.core.cache import cache

@shared_task(bind=True)
def sync_external_data(self):
    lock_id = "sync-lock"
    if cache.add(lock_id, "1", timeout=600):    # 10분 lock
        try:
            do_sync()
        finally:
            cache.delete(lock_id)
    else:
        self.retry(countdown=30)

또는 celery_once, redbeat 같은 라이브러리.

함정

1. 큰 객체 인자

process.delay(huge_queryset)    # serialize 안 됨, 메모리 폭발

인자는 작은 ID나 primitive. 워커가 다시 DB 조회.

process.delay(post.id)    # 워커: Post.objects.get(id=post_id)

2. self.request 이용해 status update

@shared_task(bind=True)
def long_task(self):
    for i in range(100):
        self.update_state(state="PROGRESS", meta={"progress": i})
        ...

클라이언트에서 polling으로 진행률 확인 가능.

3. Celery 큐 broker로 사용

Celery 자체 큐 외에 일반 Redis/RabbitMQ 큐를 동시 활용 가능. 혼동 주의.

4. 디버깅 어려움

워커가 다른 프로세스라 print/breakpoint 안 보임. --pool=solo로 동기 실행 또는 eager mode:

# 테스트
CELERY_TASK_ALWAYS_EAGER = True    # 즉시 동기 실행
CELERY_TASK_EAGER_PROPAGATES = True

5. 메모리 누수

worker가 장시간 실행 → 메모리 증가. --max-tasks-per-child=1000으로 주기적 재시작.

대안: Django Q, RQ, Huey

도구	특징
Celery	표준, 강력, 복잡
Django-Q2	Django 통합, 간단
RQ	Redis 전용, 가벼움
Huey	SQLite/Redis, 작은 앱
Dramatiq	Celery 대안, 디자인 단순

작은 앱은 RQ/Huey, 복잡한 워크플로는 Celery.

[Django] Channels: WebSocket, Consumer, Group

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

Django Channels는 Django에 WebSocket, 비동기 프로토콜, 백그라운드 작업을 추가하는 공식 확장. 기본 Django는 HTTP만, Channels는 ASGI 위에 채널 레이어를 두어 양방향 통신을 표준화. Redis 등을 채널 레이어로 사용해 다중 워커 간 메시지 라우팅.

3.1+ 의 표준 async view는 단일 요청 처리만. WebSocket 등 양방향은 Channels 필요.

설치

pip install "channels[daphne]" channels-redis

# settings.py
INSTALLED_APPS = [
    "daphne",          # 가장 먼저 (runserver 대체)
    ...
    "channels",
]
ASGI_APPLICATION = "myproject.asgi.application"

CHANNEL_LAYERS = {
    "default": {
        "BACKEND": "channels_redis.core.RedisChannelLayer",
        "CONFIG": {"hosts": [("127.0.0.1", 6379)]},
    },
}

ASGI 설정

# myproject/asgi.py
import os
from django.core.asgi import get_asgi_application
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.auth import AuthMiddlewareStack
import chat.routing

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
django_asgi_app = get_asgi_application()

application = ProtocolTypeRouter({
    "http": django_asgi_app,
    "websocket": AuthMiddlewareStack(
        URLRouter(chat.routing.websocket_urlpatterns)
    ),
})

Consumer

WebSocket 핸들러. View의 WebSocket 버전.

# chat/consumers.py
import json
from channels.generic.websocket import AsyncWebsocketConsumer

class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.room = self.scope["url_route"]["kwargs"]["room_name"]
        self.group_name = f"chat_{self.room}"

        await self.channel_layer.group_add(self.group_name, self.channel_name)
        await self.accept()

    async def disconnect(self, close_code):
        await self.channel_layer.group_discard(self.group_name, self.channel_name)

    async def receive(self, text_data):
        data = json.loads(text_data)
        message = data["message"]

        # 그룹의 모든 소켓에 broadcast
        await self.channel_layer.group_send(
            self.group_name,
            {"type": "chat.message", "message": message},
        )

    async def chat_message(self, event):
        # group_send의 type이 메서드 이름 (점 → 언더스코어)
        await self.send(text_data=json.dumps({"message": event["message"]}))

Routing

# chat/routing.py
from django.urls import re_path
from . import consumers

websocket_urlpatterns = [
    re_path(r"ws/chat/(?P<room_name>\w+)/$", consumers.ChatConsumer.as_asgi()),
]

as_asgi() 호출 (View의 as_view()와 유사).

클라이언트

const socket = new WebSocket(`ws://${window.location.host}/ws/chat/lobby/`);

socket.onmessage = (e) => {
    const data = JSON.parse(e.data);
    console.log(data.message);
};

socket.onopen = () => {
    socket.send(JSON.stringify({message: "Hello!"}));
};

Channel Layer

여러 consumer/워커 사이 메시지 전달. Redis 사용 시 수평 확장 가능.

# 그룹에 메시지 보내기
await channel_layer.group_send("group_name", {
    "type": "method.name",     # consumer의 method_name 호출
    "key": "value",
})

# 특정 채널에만
await channel_layer.send("channel_name", {...})

scope["channel_name"]이 현재 연결의 식별자.

인증

# asgi.py
from channels.auth import AuthMiddlewareStack

application = ProtocolTypeRouter({
    "websocket": AuthMiddlewareStack(URLRouter([...])),
})

AuthMiddlewareStack이 scope["user"]를 세션 기반으로 설정.

class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        if self.scope["user"].is_anonymous:
            await self.close()
            return
        await self.accept()

JWT는 커스텀 미들웨어:

class JWTAuthMiddleware:
    def __init__(self, inner):
        self.inner = inner

    async def __call__(self, scope, receive, send):
        token = parse_token_from_query(scope)
        scope["user"] = await get_user_from_token(token)
        return await self.inner(scope, receive, send)

DB 접근

from channels.db import database_sync_to_async

class ChatConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.user = self.scope["user"]
        self.room = await self.get_room(self.scope["url_route"]["kwargs"]["room_name"])
        ...

    @database_sync_to_async
    def get_room(self, name):
        return Room.objects.get(name=name)

5.0+ async ORM (aget)도 사용 가능.

SyncConsumer (동기 코드)

비동기 라이브러리 없는 경우.

from channels.generic.websocket import WebsocketConsumer

class SyncConsumer(WebsocketConsumer):
    def connect(self):
        self.accept()

    def receive(self, text_data):
        self.send(text_data="echo")

스레드 풀에서 실행. 비동기 consumer가 성능 우위지만 동기 라이브러리(많은 ORM 사용 등) 시엔 단순.

배포

daphne myproject.asgi:application --bind 0.0.0.0 --port 8000

# Uvicorn + gunicorn
gunicorn myproject.asgi:application -k uvicorn.workers.UvicornWorker --workers 4

nginx 프록시 설정:

location /ws/ {
    proxy_pass http://django;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

WebSocket은 long-lived 연결 → 타임아웃 길게.

자주 보는 패턴

알림 (Notification)

# Django view에서 (동기 코드)
from asgiref.sync import async_to_sync
from channels.layers import get_channel_layer

def trigger_notification(user_id, message):
    channel_layer = get_channel_layer()
    async_to_sync(channel_layer.group_send)(
        f"user_{user_id}",
        {"type": "notify", "message": message},
    )

# Consumer
class NotificationConsumer(AsyncWebsocketConsumer):
    async def connect(self):
        self.group = f"user_{self.scope['user'].id}"
        await self.channel_layer.group_add(self.group, self.channel_name)
        await self.accept()

    async def notify(self, event):
        await self.send(text_data=json.dumps({"message": event["message"]}))

실시간 협업 (typing indicator, presence)

class CollabConsumer(AsyncWebsocketConsumer):
    async def receive(self, text_data):
        data = json.loads(text_data)
        if data["type"] == "typing":
            await self.channel_layer.group_send(self.group, {
                "type": "typing.event",
                "user": self.scope["user"].username,
            })

    async def typing_event(self, event):
        await self.send(text_data=json.dumps(event))

Stream 데이터 broadcast

데이터 변경 시 모든 구독자에 push.

# signals.py
from django.db.models.signals import post_save
from asgiref.sync import async_to_sync
from channels.layers import get_channel_layer

@receiver(post_save, sender=Post)
def broadcast_post(sender, instance, **kwargs):
    channel_layer = get_channel_layer()
    async_to_sync(channel_layer.group_send)(
        "post_updates",
        {"type": "post.update", "post_id": instance.id, "title": instance.title},
    )

함정

1. 메서드 이름 컨벤션

{"type": "chat.message"}    # group_send/send에선 점
# → chat_message 메서드 호출 (점 → 언더스코어)

이름 안 맞으면 메시지 조용히 무시.

2. JSON 시리얼라이즈 가능 데이터만

await channel_layer.group_send("g", {"type": "msg", "obj": user})    # User instance
# Pickling 오류 또는 redis 직렬화 실패

dict/list/str/int 등만.

3. WebSocket 종료 처리

async def disconnect(self, close_code):
    await self.channel_layer.group_discard(self.group, self.channel_name)
    # cleanup

disconnect는 close_code 받음. 자원 누수 방지.

4. accept() 빠뜨림

async def connect(self):
    pass    # accept() 안 부르면 클라이언트가 503 받음

거부하려면 await self.close().

5. 인메모리 채널 레이어

CHANNEL_LAYERS = {
    "default": {"BACKEND": "channels.layers.InMemoryChannelLayer"},
}

테스트용. 여러 프로세스 간 메시지 안 됨. 프로덕션엔 Redis.

대안

	Channels	Server-Sent Events	WebSocket libs
양방향	O	X (서버 → 클라이언트)	O
Django 통합	O	StreamingHttpResponse	별도
학습 곡선	중	낮	중

단방향 push (알림, 라이브 업데이트)는 SSE가 단순.

[Django] ContentTypes, Generic Relations

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

django.contrib.contenttypes는 모든 모델을 동적으로 참조하는 시스템. 댓글이 Post, Photo, Video 등 여러 모델을 가리킬 수 있게 함. GenericForeignKey + ContentType을 활용.

활성화

기본 INSTALLED_APPS에 포함됨:

INSTALLED_APPS = [
    "django.contrib.contenttypes",
    ...
]

각 모델마다 ContentType row 자동 생성 (app_label + model).

ContentType 활용

from django.contrib.contenttypes.models import ContentType

ct = ContentType.objects.get_for_model(Post)
ct.app_label    # "blog"
ct.model        # "post"
ct.model_class()    # Post 클래스

GenericForeignKey

from django.contrib.contenttypes.fields import GenericForeignKey
from django.contrib.contenttypes.models import ContentType

class Comment(models.Model):
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
    object_id = models.PositiveIntegerField()
    content_object = GenericForeignKey("content_type", "object_id")

    body = models.TextField()
    author = models.ForeignKey("auth.User", on_delete=models.CASCADE)
    created_at = models.DateTimeField(auto_now_add=True)

post = Post.objects.first()
Comment.objects.create(content_object=post, body="좋아요!", author=user)

photo = Photo.objects.first()
Comment.objects.create(content_object=photo, body="멋져요!", author=user)

# 조회
for comment in Comment.objects.all():
    obj = comment.content_object    # Post 또는 Photo
    print(type(obj), obj)

GenericRelation (역방향)

from django.contrib.contenttypes.fields import GenericRelation

class Post(models.Model):
    title = models.CharField(max_length=200)
    comments = GenericRelation(Comment)

class Photo(models.Model):
    url = models.URLField()
    comments = GenericRelation(Comment)

post.comments.all()    # Post의 모든 댓글
photo.comments.create(body="...", author=user)

GenericRelation은 모델에 정의된 reverse accessor.

N+1 회피

# Bad: N+1
for c in Comment.objects.all():
    print(c.content_object.title)    # 매번 SQL

# prefetch_related로 자동 처리
for c in Comment.objects.prefetch_related("content_object"):
    print(c.content_object)

또는 prefetch_related_objects:

from django.db.models import Prefetch

comments = Comment.objects.all()
prefetch_related_objects(comments, "content_object")

ContentTypes로 권한 확인

# Django auth는 contenttypes 기반
user.has_perm("blog.add_post")

내부적으로 ContentType.objects.get(app_label="blog", model="post") 후 permission row.

자주 보는 패턴

댓글 / 좋아요 / 북마크

class Bookmark(models.Model):
    user = models.ForeignKey("auth.User", on_delete=models.CASCADE)
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
    object_id = models.PositiveIntegerField()
    content_object = GenericForeignKey()

    class Meta:
        unique_together = ("user", "content_type", "object_id")

user.bookmark_set.all()
Bookmark.objects.create(user=user, content_object=post)

여러 모델 (Post, Photo, Video) 모두 북마크 가능.

Activity feed

class Activity(models.Model):
    actor = models.ForeignKey("auth.User", on_delete=models.CASCADE)
    verb = models.CharField(max_length=50)    # "created", "liked", "commented"

    target_ct = models.ForeignKey(ContentType, null=True, on_delete=models.CASCADE, related_name="+")
    target_id = models.PositiveIntegerField(null=True)
    target = GenericForeignKey("target_ct", "target_id")

    action_object_ct = models.ForeignKey(ContentType, null=True, on_delete=models.CASCADE, related_name="+")
    action_object_id = models.PositiveIntegerField(null=True)
    action_object = GenericForeignKey("action_object_ct", "action_object_id")

    timestamp = models.DateTimeField(auto_now_add=True)

# Alice가 Post에 댓글 추가
Activity.objects.create(
    actor=alice,
    verb="commented_on",
    target=post,
    action_object=comment,
)

django-activity-stream 라이브러리가 이 패턴.

Polymorphic 모델 (django-polymorphic 대안)

class Item(models.Model):
    name = models.CharField(max_length=200)
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
    object_id = models.PositiveIntegerField()
    content_object = GenericForeignKey()    # 실제 객체 (Book, Movie, Game 등)

함정

1. cascade 없음

post.delete()
# post를 참조하는 Comment는 orphan으로 남음!

GenericForeignKey는 FK 제약 없음. 부모 삭제 시 자식 안 지워짐.

해결:

부모에 GenericRelation + cascade 안 됨 (Django 제약)
signal로 수동 처리
django-polymorphic 같은 라이브러리

from django.db.models.signals import pre_delete

@receiver(pre_delete, sender=Post)
def delete_comments(sender, instance, **kwargs):
    ct = ContentType.objects.get_for_model(instance)
    Comment.objects.filter(content_type=ct, object_id=instance.id).delete()

2. 검색/필터 어려움

Comment.objects.filter(content_object__title__icontains="django")    # 안 됨

특정 타입만 필터:

post_ct = ContentType.objects.get_for_model(Post)
Comment.objects.filter(content_type=post_ct, object_id__in=...)

복잡한 쿼리는 일반 FK가 더 편함.

3. content_object__title 같은 lookup X

Comment.objects.filter(content_object__author=user)    # 안 됨

처음부터 일반 FK + STI/MTI 검토.

4. 인덱스

class Comment(models.Model):
    content_type = ...
    object_id = ...

    class Meta:
        indexes = [
            models.Index(fields=["content_type", "object_id"]),
        ]

(content_type, object_id) 복합 인덱스로 lookup 빠르게.

5. JSON 직렬화

serializer.data    # GenericForeignKey 자동 직렬화 X

DRF는 수동 처리 필요.

class CommentSerializer(serializers.ModelSerializer):
    content_object = SerializerMethodField()

    def get_content_object(self, obj):
        if isinstance(obj.content_object, Post):
            return PostSerializer(obj.content_object).data
        if isinstance(obj.content_object, Photo):
            return PhotoSerializer(obj.content_object).data
        return None

ContentType vs Polymorphic

패턴	장단점
GenericForeignKey	Django 빌트인, 유연. 쿼리 약함, 무결성 약함
django-polymorphic	풍부한 다형성 (서브클래스 자동 매핑)
Single Table Inheritance	한 테이블 + type 컬럼 (Rails STI 패턴)
Multi-Table Inheritance	Django 기본 (`Book(Item)`)

대부분 일반 FK + 추상 베이스 또는 MTI가 더 명확. ContentTypes는 정말 다형성 필수일 때만.

자주 보는 라이브러리

django-polymorphic: 다형성 모델
django-taggit: 태그 시스템 (내부적으로 GenericFK)
django-activity-stream: 활동 피드
django-comments: 댓글 (deprecated, django-fluent-comments)

[Django] DRF Permission, Throttle, Filter

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

DRF는 view 호출 전 인증(Authentication) → 권한(Permission) → 스로틀(Throttle) 순으로 검사. 각 단계가 통과해야 view 메서드 실행. 모두 클래스 기반이라 조합·재사용 가능.

빌트인 Permission

from rest_framework import permissions

# settings.py
REST_FRAMEWORK = {
    "DEFAULT_PERMISSION_CLASSES": [
        "rest_framework.permissions.IsAuthenticated",
    ],
}

Permission	동작
`AllowAny`	누구나
`IsAuthenticated`	로그인된 사용자
`IsAdminUser`	`is_staff=True`
`IsAuthenticatedOrReadOnly`	인증 또는 SAFE_METHODS (GET/HEAD/OPTIONS)
`DjangoModelPermissions`	Django model permission 활용
`DjangoObjectPermissions`	object-level (django-guardian 등)

class PostViewSet(ModelViewSet):
    permission_classes = [IsAuthenticatedOrReadOnly]

커스텀 Permission

from rest_framework import permissions

class IsAuthorOrReadOnly(permissions.BasePermission):
    """글 작성자만 수정/삭제. 다른 사용자는 읽기만."""

    def has_permission(self, request, view):
        return request.method in permissions.SAFE_METHODS or request.user.is_authenticated

    def has_object_permission(self, request, view, obj):
        if request.method in permissions.SAFE_METHODS:
            return True
        return obj.author == request.user

has_permission: list/create 등 view 레벨
has_object_permission: retrieve/update/destroy 등 객체 레벨 (get_object() 호출 시 자동)

class PostViewSet(ModelViewSet):
    permission_classes = [IsAuthenticated, IsAuthorOrReadOnly]

액션별 permission

class PostViewSet(ModelViewSet):

    def get_permissions(self):
        if self.action == "destroy":
            return [IsAdminUser()]
        elif self.action in ["update", "partial_update"]:
            return [IsAuthorOrReadOnly()]
        elif self.action == "list":
            return [AllowAny()]
        return [IsAuthenticated()]

Object-level (django-guardian)

pip install django-guardian

INSTALLED_APPS += ["guardian"]
AUTHENTICATION_BACKENDS = [
    "django.contrib.auth.backends.ModelBackend",
    "guardian.backends.ObjectPermissionBackend",
]

from guardian.shortcuts import assign_perm

assign_perm("view_post", user, post)
user.has_perm("view_post", post)

from rest_framework.permissions import DjangoObjectPermissions

class PostViewSet(ModelViewSet):
    permission_classes = [DjangoObjectPermissions]

queryset도 자동 필터:

from guardian.shortcuts import get_objects_for_user

def get_queryset(self):
    return get_objects_for_user(self.request.user, "blog.view_post")

Throttling

REST_FRAMEWORK = {
    "DEFAULT_THROTTLE_CLASSES": [
        "rest_framework.throttling.AnonRateThrottle",
        "rest_framework.throttling.UserRateThrottle",
    ],
    "DEFAULT_THROTTLE_RATES": {
        "anon": "100/day",
        "user": "1000/day",
        "burst": "60/min",
        "sustained": "1000/day",
    }
}

단위: /second, /minute, /hour, /day.

커스텀 throttle

from rest_framework.throttling import UserRateThrottle, AnonRateThrottle

class BurstRateThrottle(UserRateThrottle):
    scope = "burst"

class SustainedRateThrottle(UserRateThrottle):
    scope = "sustained"

class PostViewSet(ModelViewSet):
    throttle_classes = [BurstRateThrottle, SustainedRateThrottle]

Scoped throttle

class ContactThrottle(ScopedRateThrottle):
    pass

REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"] = {
    "contact": "5/hour",
}

class ContactViewSet(ViewSet):
    throttle_scope = "contact"
    throttle_classes = [ScopedRateThrottle]

특정 엔드포인트만.

Redis 백엔드

기본은 Django cache. Redis 권장 (분산):

CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": env("REDIS_URL"),
    },
}

throttle도 자동으로 Redis 사용.

Filtering

REST_FRAMEWORK = {
    "DEFAULT_FILTER_BACKENDS": [
        "django_filters.rest_framework.DjangoFilterBackend",
        "rest_framework.filters.SearchFilter",
        "rest_framework.filters.OrderingFilter",
    ]
}

pip install django-filter

FilterSet

import django_filters

class PostFilter(django_filters.FilterSet):
    min_views = django_filters.NumberFilter(field_name="views", lookup_expr="gte")
    max_views = django_filters.NumberFilter(field_name="views", lookup_expr="lte")
    title = django_filters.CharFilter(lookup_expr="icontains")
    created_after = django_filters.DateFilter(field_name="created_at", lookup_expr="gte")
    is_published = django_filters.BooleanFilter()
    tags = django_filters.ModelMultipleChoiceFilter(
        field_name="tags__name",
        to_field_name="name",
        queryset=Tag.objects.all(),
    )

    class Meta:
        model = Post
        fields = ["author", "is_published"]

class PostViewSet(ModelViewSet):
    filterset_class = PostFilter

쿼리:

GET /api/posts/?title=django&min_views=100&tags=python&tags=web

Search / Ordering

class PostViewSet(ModelViewSet):
    search_fields = ["title", "body", "author__username"]
    ordering_fields = ["created_at", "views", "title"]
    ordering = ["-created_at"]    # 기본

GET /api/posts/?search=django
GET /api/posts/?ordering=-views
GET /api/posts/?ordering=-views,title

search_fields 접두:

^: starts with
=: 정확
@: full-text (PG만)
$: regex

커스텀 filter backend

from rest_framework import filters

class IsOwnerFilterBackend(filters.BaseFilterBackend):
    """현재 사용자의 객체만 노출."""

    def filter_queryset(self, request, queryset, view):
        return queryset.filter(owner=request.user)

class PostViewSet(ModelViewSet):
    filter_backends = [IsOwnerFilterBackend]

자주 보는 패턴

Token 만료

from rest_framework.throttling import UserRateThrottle

class TokenRefreshThrottle(UserRateThrottle):
    scope = "token_refresh"
    rate = "5/hour"

REST_FRAMEWORK["DEFAULT_THROTTLE_RATES"]["token_refresh"] = "5/hour"

비밀번호 시도, 토큰 재발급 등 민감 endpoint에 강한 throttle.

Permission + 객체 + 필드

class PostSerializer(ModelSerializer):
    class Meta:
        model = Post
        fields = ["id", "title", "body", "author", "internal_note"]

    def to_representation(self, instance):
        rep = super().to_representation(instance)
        if not self.context["request"].user.is_staff:
            rep.pop("internal_note", None)
        return rep

권한별 다른 필드 노출.

Multi-tenant

class TenantFilterBackend(filters.BaseFilterBackend):
    def filter_queryset(self, request, queryset, view):
        return queryset.filter(tenant=request.tenant)

class PostViewSet(ModelViewSet):
    filter_backends = [TenantFilterBackend]
    permission_classes = [IsAuthenticated, IsTenantMember]

ProblemDetail 응답

class CustomThrottleException(Throttled):
    default_detail = "Rate limit exceeded"
    default_code = "throttled"

# 또는 예외 핸들러
from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    if isinstance(exc, Throttled):
        response.data = {
            "error": "Rate limit exceeded",
            "wait_seconds": exc.wait,
        }
    return response

함정

1. permission_classes vs get_permissions

클래스 변수는 모든 액션 공통. action별 다르면 get_permissions() 메서드.

2. has_object_permission는 list에 호출 X

def has_object_permission(self, request, view, obj):
    return obj.owner == request.user

# list 액션은 호출 안 됨 → 필터링 안 됨

list에서 객체 필터는 get_queryset()에서.

3. throttle rate 변경

settings 변경 후 캐시 비워야 새 rate 적용.

4. SAFE_METHODS

permissions.SAFE_METHODS = ["GET", "HEAD", "OPTIONS"]

이걸 비교. PUT/PATCH/DELETE는 unsafe.

5. JWT 만료 + throttle

JWT_AUTH_RETURN_EXPIRATION = True

만료된 토큰으로 요청 → 401, 그러나 throttle 카운트 증가 가능. 401은 throttle 제외 로직 추가 검토.

[Django] DRF Serializer 심화

koa (김신건) — Sat, 20 Jun 2026 00:00:00 GMT

정의

DRF Serializer는 JSON ↔ Python ↔ Model의 변환과 검증을 담당한다. Django Form과 비슷한 인터페이스이나 API/JSON에 특화. 검증, 직렬화, nested 관계, 동적 필드, custom validation 등 풍부.

두 방향으로 동작한다

Serializer 는 항상 두 방향 중 하나 로 호출된다. 이 구분이 헷갈리면 코드도 헷갈린다.

{}

방향	호출 형태	얻는 것	용도
직렬화 (Serialize)	`Serializer(instance)`	`.data` (dict)	응답: Model → JSON
역직렬화 (Deserialize)	`Serializer(data=request.data)`	`.validated_data` after `.is_valid()`, `.save()`	요청: JSON → Model

# 방향 ①: 직렬화 (응답용)
post = Post.objects.get(pk=1)
serializer = PostSerializer(post)             # instance= 인자
serializer.data                                # {"id": 1, "title": "..."}

# 방향 ②: 역직렬화 (요청용)
serializer = PostSerializer(data=request.data) # data= 인자 (키워드 필수!)
if serializer.is_valid():
    post = serializer.save()                    # validated_data → DB
else:
    print(serializer.errors)

[!IMPORTANT] data= 는 반드시 키워드 인자. PostSerializer(request.data) 는 첫 번째 위치 인자 = instance 로 해석되어 잘못된 결과.

Serializer vs ModelSerializer

# 일반 Serializer
class CommentSerializer(serializers.Serializer):
    id = serializers.IntegerField(read_only=True)
    post_id = serializers.IntegerField()
    body = serializers.CharField(max_length=500)
    created_at = serializers.DateTimeField(read_only=True)

    def create(self, validated_data):
        return Comment.objects.create(**validated_data)

    def update(self, instance, validated_data):
        instance.body = validated_data.get("body", instance.body)
        instance.save()
        return instance

# ModelSerializer (자동)
class CommentSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comment
        fields = ["id", "post_id", "body", "created_at"]
        read_only_fields = ["id", "created_at"]

ModelSerializer는 모델에서 필드 자동 추론 + create/update 자동.

필드

class UserSerializer(serializers.Serializer):
    id = serializers.IntegerField(read_only=True)
    email = serializers.EmailField()
    name = serializers.CharField(max_length=100, allow_blank=True)
    age = serializers.IntegerField(min_value=0, max_value=150, required=False)
    bio = serializers.CharField(required=False, allow_null=True)
    role = serializers.ChoiceField(choices=["admin", "user"])
    avatar = serializers.URLField()
    birthday = serializers.DateField(format="%Y-%m-%d")
    created_at = serializers.DateTimeField(read_only=True)
    tags = serializers.ListField(child=serializers.CharField())
    meta = serializers.JSONField(default=dict)
    secret = serializers.CharField(write_only=True)    # 응답에 노출 X

옵션:

required (기본 True)
default
allow_null
allow_blank (string)
read_only, write_only
source (모델 필드명과 다를 때)
style (HTML 위젯 힌트)
validators

관계 필드

PrimaryKeyRelatedField

class PostSerializer(serializers.ModelSerializer):
    author = serializers.PrimaryKeyRelatedField(queryset=User.objects.all())
    tags = serializers.PrimaryKeyRelatedField(queryset=Tag.objects.all(), many=True)

    class Meta:
        model = Post
        fields = ["id", "title", "author", "tags"]

요청·응답에 ID만:

{"id": 1, "title": "...", "author": 5, "tags": [1, 2]}

StringRelatedField (read_only)

author = serializers.StringRelatedField()
# author의 __str__() 값

Nested serializer

class TagSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tag
        fields = ["id", "name"]

class PostSerializer(serializers.ModelSerializer):
    tags = TagSerializer(many=True, read_only=True)
    author = UserSerializer(read_only=True)
    author_id = serializers.PrimaryKeyRelatedField(
        source="author", queryset=User.objects.all(), write_only=True
    )

    class Meta:
        model = Post
        fields = ["id", "title", "author", "author_id", "tags"]

응답: nested 객체. 요청: author_id로 단순.

HyperlinkedRelatedField

author = serializers.HyperlinkedRelatedField(view_name="user-detail", read_only=True)
# {"author": "/api/users/5/"}

REST의 HATEOAS 추구 시.

SerializerMethodField

동적 계산 필드 (read-only).

class PostSerializer(serializers.ModelSerializer):
    comment_count = serializers.SerializerMethodField()
    is_liked = serializers.SerializerMethodField()

    class Meta:
        model = Post
        fields = ["id", "title", "comment_count", "is_liked"]

    def get_comment_count(self, obj):
        return obj.comments.count()

    def get_is_liked(self, obj):
        request = self.context.get("request")
        if request and request.user.is_authenticated:
            return obj.likes.filter(user=request.user).exists()
        return False

get_<field_name> 메서드. context로 view에서 추가 데이터.

검증

빌트인

각 필드의 type/required/length/regex.

필드 레벨 (validate_<field>)

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["email", "name"]

    def validate_email(self, value):
        if User.objects.filter(email=value).exists():
            raise serializers.ValidationError("이미 가입된 이메일")
        return value.lower()

객체 레벨 (validate)

여러 필드 관계.

def validate(self, data):
    if data.get("password") != data.get("password_confirm"):
        raise serializers.ValidationError({"password_confirm": "일치하지 않음"})
    return data

Validators 인자

from django.core.validators import RegexValidator

phone = serializers.CharField(validators=[
    RegexValidator(r"^\d{3}-\d{4}-\d{4}$"),
    UniqueValidator(queryset=User.objects.all()),    # DRF 내장
])

UniqueTogetherValidator

class Meta:
    validators = [
        UniqueTogetherValidator(queryset=Post.objects.all(), fields=["author", "slug"])
    ]

create / update 오버라이드

nested 관계의 저장은 직접 구현.

class PostSerializer(serializers.ModelSerializer):
    tags = TagSerializer(many=True)

    class Meta:
        model = Post
        fields = ["id", "title", "tags"]

    def create(self, validated_data):
        tags_data = validated_data.pop("tags")
        post = Post.objects.create(**validated_data)
        for tag_data in tags_data:
            tag, _ = Tag.objects.get_or_create(name=tag_data["name"])
            post.tags.add(tag)
        return post

    def update(self, instance, validated_data):
        tags_data = validated_data.pop("tags", None)
        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()

        if tags_data is not None:
            instance.tags.clear()
            for tag_data in tags_data:
                tag, _ = Tag.objects.get_or_create(name=tag_data["name"])
                instance.tags.add(tag)
        return instance

context

view에서 serializer로 전달.

# ViewSet
def get_serializer_context(self):
    context = super().get_serializer_context()
    context["extra"] = "..."
    return context

# 또는 직접
PostSerializer(post, context={"request": request})

# Serializer에서
def get_url(self, obj):
    request = self.context["request"]
    return request.build_absolute_uri(obj.get_absolute_url())

기본 context: request, view, format.

동적 필드

요청에 따라 다른 필드 노출.

class DynamicFieldsModelSerializer(serializers.ModelSerializer):
    def __init__(self, *args, **kwargs):
        fields = kwargs.pop("fields", None)
        super().__init__(*args, **kwargs)
        if fields:
            allowed = set(fields)
            existing = set(self.fields.keys())
            for name in existing - allowed:
                self.fields.pop(name)

# 사용
UserSerializer(user, fields=["id", "email"])

또는 ViewSet에서 query param으로 분기.

ListSerializer

many=True 시 ListSerializer가 사용됨. bulk create/update 오버라이드.

class BookListSerializer(serializers.ListSerializer):
    def create(self, validated_data):
        books = [Book(**item) for item in validated_data]
        return Book.objects.bulk_create(books)

class BookSerializer(serializers.ModelSerializer):
    class Meta:
        model = Book
        fields = "__all__"
        list_serializer_class = BookListSerializer

자주 보는 패턴

Read vs Write 분리

class PostReadSerializer(ModelSerializer):
    author = UserSerializer()
    tags = TagSerializer(many=True)
    class Meta:
        model = Post
        fields = ["id", "title", "body", "author", "tags"]

class PostWriteSerializer(ModelSerializer):
    tag_ids = PrimaryKeyRelatedField(source="tags", many=True, queryset=Tag.objects.all())
    class Meta:
        model = Post
        fields = ["title", "body", "tag_ids"]

class PostViewSet(ModelViewSet):
    def get_serializer_class(self):
        if self.action in ["list", "retrieve"]:
            return PostReadSerializer
        return PostWriteSerializer

Field source 변환

class UserSerializer(serializers.ModelSerializer):
    full_name = serializers.CharField(source="get_full_name", read_only=True)
    avatar_url = serializers.SerializerMethodField()

    def get_avatar_url(self, obj):
        if obj.avatar:
            return self.context["request"].build_absolute_uri(obj.avatar.url)
        return None

Nested write with PK

class CommentSerializer(serializers.ModelSerializer):
    post = serializers.PrimaryKeyRelatedField(queryset=Post.objects.all())
    author_email = serializers.EmailField(source="author.email", read_only=True)
    class Meta:
        model = Comment
        fields = ["id", "post", "body", "author_email"]

함정

1. ModelSerializer + fields=“all”

class UserSerializer(ModelSerializer):
    class Meta:
        model = User
        fields = "__all__"   # password 해시 노출!

명시 권장. password, internal 필드 제외.

2. nested validation

nested 객체 검증 실패 시 에러 메시지가 깊게 nested.

{"tags": [{"name": ["이미 존재"]}]}

UI 처리 주의.

3. partial update (PATCH)

serializer = PostSerializer(post, data=request.data, partial=True)

partial=True로 required 필드 무시.

4. context[“request”] 없으면 None

테스트나 직렬화 단독 호출 시 request 없음. defensive get.

request = self.context.get("request")
if request is None:
    return None

5. N+1 (SerializerMethodField)

def get_comment_count(self, obj):
    return obj.comments.count()    # 매 instance마다 SQL

→ ViewSet에서 annotate(comment_count=Count("comments")) 후 필드:

comment_count = serializers.IntegerField(read_only=True)

김신건의 로그 - 위키 / django

[DRF] Filtering: django-filter, SearchFilter, OrderingFilter

정의

3가지 내장 Backend

설치 + 설정

1. DjangoFilterBackend

간단한 필드 매칭

상세 FilterSet

Lookup expressions

2. SearchFilter

Prefix 조정

3. OrderingFilter

다중 Backend 조합

Custom Filter Backend

PostgreSQL Full-Text Search

OpenAPI 문서화

다른 프레임워크

흔한 함정

관련 위키

[DRF] Schemas + OpenAPI: 자동 문서화

정의

왜 API 문서화가 필요한가

도구 선택

drf-spectacular 설치 (5분 완성)

Swagger UI vs Redoc

자동 추출 되는 것

@extend_schema 로 커스터마이즈

Enum 필드 문서화

Nested Serializer 문서화

SerializerMethodField 타입 힌트

인증 문서화

여러 개 응답 (union)

요청 예시

Serializer 재사용 (같은 이름 충돌 방지)

Schema 파일 export

Client SDK 자동 생성

다른 프레임워크 문서화 대응

실무 팁

1. 태그로 그룹핑

2. CORS 문제

3. 문서 접근 권한 제한

4. 버전별 문서 분리

흔한 함정

관련 위키

[DRF] Testing: APIClient, APITestCase, force_authenticate

정의

테스트 도구 계층

설치

1. APIClient (통합 테스트)

force_authenticate (권장)

세션 로그인

토큰 인증

HTTP 메서드

응답 검증

2. APIRequestFactory (View 단위)

3. Serializer 단위 테스트

4. pytest-django 사용

5. Factory Boy (테스트 데이터)

응답 status code 매트릭스

권한 테스트 패턴

Throttle 테스트

시간 조작 (freezegun)

Mocking 외부 API

DB Snapshot

Coverage 측정

다른 프레임워크 테스트 도구

흔한 함정

관련 위키

[Django] MTV 패턴과 Model 기본

정의

Model 정의

마이그레이션

CRUD

View + Form + Template 흐름

참고

[Django 6.0] Content Security Policy: XSS 방어의 최종형

정의

목적 + 대안

CSP Header 구조

Django 6.0 CSP 설정

`@extend_schema` 로 커스터마이즈

`force_authenticate` (권장)