Django 全栈框架与企业级项目实战

Django 的核心哲学"batteries-included"不是营销口号——它是 Python 生态中唯一一个在 startproject 之后就自带 ORM、模板引擎、表单处理、认证系统、管理后台、国际化、缓存框架、信号系统和测试框架的 Web 框架。如果你要做的是一个需要后台管理、用户系统、权限控制、内容管理的传统 Web 项目，Django 是让你省掉 80% 重复造轮子时间的终极武器。本文从 MTV 架构的物理实现拆解到 K8s 集群部署，覆盖 Django 全栈开发中 90% 以上的生产级知识点。

MTV 架构：从请求到响应的完整链路

Django 的请求处理全流程

# 模拟 Django 的请求处理流程（简化版）
class MockHttpRequest:
    """模拟 Django HttpRequest 对象"""
    def __init__(self, method, path, headers=None, body=None):
        self.method = method
        self.path = path
        self.META = headers or {}
        self.GET = {}
        self.POST = {}
        self.body = body or b""

        # 解析查询字符串
        if "?" in path:
            path, query_string = path.split("?", 1)
            self.path = path
            for pair in query_string.split("&"):
                if "=" in pair:
                    key, value = pair.split("=", 1)
                    self.GET[key] = value

class MockHttpResponse:
    """模拟 Django HttpResponse 对象"""
    def __init__(self, content="", status=200, content_type="text/html"):
        self.content = content.encode() if isinstance(content, str) else content
        self.status_code = status
        self["Content-Type"] = content_type
        self._headers = {"Content-Type": content_type}

    def __setitem__(self, key, value):
        self._headers[key] = value

    def __getitem__(self, key):
        return self._headers[key]

# Django 中间件洋葱模型
MIDDLEWARE_STACK = []

def register_middleware(middleware_class):
    """注册中间件到栈中"""
    MIDDLEWARE_STACK.append(middleware_class)

class MiddlewareManager:
    """Django 的中间件管理器（简化版）"""

    def __init__(self, get_response):
        self._get_response = get_response
        self._middleware_chain = self._build_chain()

    def _build_chain(self):
        """构建中间件调用链"""
        handler = self._get_response

        # 从后往前包裹（洋葱模型的外层先执行 process_request）
        for middleware_class in reversed(MIDDLEWARE_STACK):
            mw_instance = middleware_class(handler)
            handler = mw_instance

        return handler

    def __call__(self, request):
        return self._middleware_chain(request)

# 示例中间件
class RequestLoggingMiddleware:
    """记录请求日志"""
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # process_request 阶段
        start_time = time.time()
        print(f"\n→ [中间件-日志] 请求进入: {request.method} {request.path}")

        # 调用下一个中间件或视图
        response = self.get_response(request)

        # process_response 阶段
        duration = time.time() - start_time
        print(f"← [中间件-日志] 响应离开: {response.status_code} ({duration:.3f}s)")

        return response

class AuthMiddleware:
    """认证中间件"""
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        # process_request 阶段
        token = request.META.get("HTTP_AUTHORIZATION", "")
        request.user = None

        if token.startswith("Bearer "):
            user_id = token[7:]
            request.user = {"id": user_id, "name": f"User-{user_id}"}
            print(f"  [中间件-认证] 用户已认证: {request.user['name']}")
        else:
            print(f"  [中间件-认证] 未认证请求")

        response = self.get_response(request)
        return response

class CORSMiddleware:
    """CORS 中间件"""
    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        response = self.get_response(request)

        # process_response 阶段：添加 CORS 头
        response["Access-Control-Allow-Origin"] = "*"
        response["Access-Control-Allow-Methods"] = "GET, POST, PUT, DELETE, OPTIONS"
        response["Access-Control-Allow-Headers"] = "Content-Type, Authorization"

        return response

# 注册中间件
register_middleware(RequestLoggingMiddleware)
register_middleware(AuthMiddleware)
register_middleware(CORSMiddleware)

# 视图函数
def article_list_view(request):
    """模拟 Django 视图函数"""
    print(f"    [视图] 处理 {request.method} {request.path}")

    if request.user:
        return MockHttpResponse(
            f"Welcome {request.user['name']}! Articles list...",
            status=200
        )
    return MockHttpResponse("Articles list...", status=200)

# 运行模拟请求
def simulate_django_request():
    """模拟完整的 Django 请求处理流程"""
    manager = MiddlewareManager(article_list_view)

    # 模拟请求 1：已认证
    print("=" * 60)
    print("模拟请求 1：已认证用户")
    request1 = MockHttpRequest(
        "GET",
        "/articles/?page=1&tag=python",
        headers={"HTTP_AUTHORIZATION": "Bearer 42"}
    )
    response1 = manager(request1)
    print(f"\n最终响应: {response1.status_code} - {response1.content.decode()}")

    # 模拟请求 2：未认证
    print("\n" + "=" * 60)
    print("模拟请求 2：未认证用户")
    request2 = MockHttpRequest("GET", "/articles/")
    response2 = manager(request2)
    print(f"\n最终响应: {response2.status_code} - {response2.content.decode()}")

simulate_django_request()

URL 分发器的路径树编译

Django 的 URL 分发器在启动时将 urlpatterns 编译为解析树：

# urls.py - 项目级 URL 配置
from django.urls import path, include, re_path
from django.contrib import admin

urlpatterns = [
    path("admin/", admin.site.urls),
    path("api/v1/", include("api.v1.urls")),
    path("api/v2/", include("api.v2.urls")),
    re_path(r"^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/$", view_func),
]

# api/v1/urls.py - 应用级 URL 配置
from django.urls import path
from . import views

app_name = "api_v1"

urlpatterns = [
    path("articles/", views.ArticleListCreateView.as_view(), name="article-list"),
    path("articles/<slug:slug>/", views.ArticleDetailView.as_view(), name="article-detail"),
    path("users/", views.UserListView.as_view(), name="user-list"),
    path("users/<int:pk>/", views.UserDetailView.as_view(), name="user-detail"),
]

# 打印所有路由
def show_all_urls():
    """展示 Django 项目所有注册的 URL 路由"""
    from django.urls import get_resolver

    resolver = get_resolver()

    def print_url_patterns(patterns, prefix=""):
        for pattern in patterns:
            if hasattr(pattern, "url_patterns"):
                # 这是一个 include()，递归处理
                new_prefix = prefix + str(pattern.pattern)
                print_url_patterns(pattern.url_patterns, new_prefix)
            else:
                # 这是一个具体的 URL 模式
                full_pattern = prefix + str(pattern.pattern)
                view_name = pattern.callback.__name__ if hasattr(pattern.callback, "__name__") else str(pattern.callback)
                print(f"  {full_pattern:40s} -> {view_name}")

    print("Django URL 路由列表：")
    print_url_patterns(resolver.url_patterns)

Django ORM：深度剖析与查询优化

QuerySet 的惰性求值机制与源码级解析

Django ORM 是 Python 生态中最成熟的 ORM 之一。它的核心设计思想是惰性求值——直到数据被真正需要时才执行 SQL：

from django.db import models
from django.db.models import (
    Q, F, Count, Sum, Avg, Max, Min, 
    OuterRef, Subquery, Exists,
    Prefetch, Value, CharField,
    Case, When, Window
)
from django.db.models.functions import (
    ExtractYear, ExtractMonth, Coalesce,
    RowNumber, Rank, Lag, Lead
)
from django.contrib.postgres.aggregates import ArrayAgg, StringAgg
from django.contrib.postgres.search import SearchVector, SearchQuery, SearchRank
import time

class Publisher(models.Model):
    name = models.CharField(max_length=100)
    address = models.CharField(max_length=200)
    website = models.URLField(blank=True)
    established_date = models.DateField(null=True, blank=True)

    class Meta:
        db_table = "publishers"
        indexes = [
            models.Index(fields=["name"]),
        ]

    def __str__(self):
        return self.name

class Author(models.Model):
    first_name = models.CharField(max_length=50)
    last_name = models.CharField(max_length=50)
    email = models.EmailField(unique=True)
    birth_date = models.DateField(null=True, blank=True)
    bio = models.TextField(blank=True)

    class Meta:
        db_table = "authors"
        indexes = [
            models.Index(fields=["last_name", "first_name"]),
        ]
        constraints = [
            models.UniqueConstraint(
                fields=["first_name", "last_name"],
                name="unique_author_name"
            )
        ]

    @property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    def __str__(self):
        return self.full_name

class Category(models.Model):
    name = models.CharField(max_length=100, unique=True)
    slug = models.SlugField(max_length=100, unique=True)
    parent = models.ForeignKey(
        "self", on_delete=models.CASCADE, 
        null=True, blank=True, 
        related_name="children"
    )
    description = models.TextField(blank=True)

    class Meta:
        db_table = "categories"
        verbose_name_plural = "categories"

    def __str__(self):
        return self.name

class Book(models.Model):
    STATUS_CHOICES = [
        ("draft", "Draft"),
        ("published", "Published"),
        ("out_of_print", "Out of Print"),
    ]

    title = models.CharField(max_length=200)
    slug = models.SlugField(max_length=200, unique=True)
    isbn = models.CharField(max_length=13, unique=True, db_index=True)

    # 外键关系
    publisher = models.ForeignKey(
        Publisher, on_delete=models.PROTECT,
        related_name="books"
    )
    authors = models.ManyToManyField(Author, related_name="books")
    category = models.ForeignKey(
        Category, on_delete=models.SET_NULL,
        null=True, related_name="books"
    )

    # 内容字段
    summary = models.TextField(blank=True)
    page_count = models.PositiveIntegerField(default=0)

    # 价格与库存
    price = models.DecimalField(max_digits=10, decimal_places=2)
    discount_price = models.DecimalField(max_digits=10, decimal_places=2, null=True, blank=True)
    stock = models.PositiveIntegerField(default=0)

    # 统计字段
    view_count = models.PositiveIntegerField(default=0)
    sales_count = models.PositiveIntegerField(default=0)
    rating = models.DecimalField(max_digits=3, decimal_places=2, default=0)

    # 时间与状态
    status = models.CharField(max_length=20, choices=STATUS_CHOICES, default="draft")
    publication_date = models.DateField(null=True, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = "books"
        ordering = ["-created_at"]
        indexes = [
            models.Index(fields=["status", "-publication_date"]),
            models.Index(fields=["price"]),
            models.Index(fields=["publisher", "status"]),
        ]
        constraints = [
            models.CheckConstraint(
                check=models.Q(price__gt=0),
                name="price_positive"
            ),
            models.CheckConstraint(
                check=models.Q(stock__gte=0),
                name="stock_non_negative"
            ),
        ]

    def __str__(self):
        return self.title

    @property
    def current_price(self):
        return self.discount_price or self.price

class Review(models.Model):
    book = models.ForeignKey(Book, on_delete=models.CASCADE, related_name="reviews")
    reviewer = models.ForeignKey(Author, on_delete=models.CASCADE, related_name="reviews")
    rating = models.PositiveSmallIntegerField()  # 1-5
    title = models.CharField(max_length=200)
    body = models.TextField()
    helpful_count = models.PositiveIntegerField(default=0)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        db_table = "reviews"
        ordering = ["-created_at"]
        constraints = [
            models.CheckConstraint(
                check=models.Q(rating__gte=1) & models.Q(rating__lte=5),
                name="rating_range"
            ),
            models.UniqueConstraint(
                fields=["book", "reviewer"],
                name="one_review_per_user_per_book"
            ),
        ]

select_related 与 prefetch_related 的物理差异（带 SQL 验证）

from django.db import connection, reset_queries
from django.test.utils import override_settings
import json

def analyze_query(queryset, description=""):
    """分析 QuerySet 的 SQL 查询"""
    print(f"\n{'='*60}")
    print(f"分析: {description}")
    print(f"{'='*60}")

    # 清空查询日志
    reset_queries()

    # 强制执行查询
    results = list(queryset)

    # 分析查询
    queries = connection.queries
    print(f"总查询次数: {len(queries)}")

    for i, query in enumerate(queries):
        sql = query["sql"]
        time_taken = query["time"]

        # 截断过长的 SQL
        if len(sql) > 200:
            display_sql = sql[:200] + "..."
        else:
            display_sql = sql

        print(f"\n  查询 {i+1} ({time_taken}s):")
        print(f"  {display_sql}")

    return results

# 1. N+1 问题演示
print("\n\n>>> N+1 问题演示 <<<")

books_no_optimize = Book.objects.filter(status="published")[:5]
analyze_query(books_no_optimize, "无优化的查询")
# 此时还没有访问 author，所以只有 1 次查询

# 访问 author 触发 N+1
reset_queries()
for book in books_no_optimize:
    _ = book.publisher.name  # 每次访问触发一次查询
    for author in book.authors.all():  # 每次触发 N 次查询
        _ = author.email

print(f"\n访问关联字段后总查询次数: {len(connection.queries)}")

# 2. select_related 优化（JOIN）
books_select_related = Book.objects.filter(
    status="published"
).select_related("publisher", "category")[:5]

results = analyze_query(books_select_related, "select_related 优化")
print(f"\n生成的 JOIN 查询，一次获取书籍+出版社+分类")

# 验证：访问 publisher 不会触发额外查询
reset_queries()
for book in results:
    _ = book.publisher.name
    _ = book.category.name

print(f"访问 publisher 和 category 后的查询次数: {len(connection.queries)}（0 表示无额外查询）")

# 3. prefetch_related 优化（多对多）
books_prefetch = Book.objects.filter(
    status="published"
).select_related("publisher").prefetch_related(
    "authors",
    Prefetch("reviews", queryset=Review.objects.order_by("-helpful_count")[:3])
)[:5]

results = analyze_query(books_prefetch, "prefetch_related 优化")
print(f"\n先查书籍(publisher JOIN), 再批量查 authors(WHERE id IN (...)), 再查 reviews")

F 表达式与乐观锁

from django.db.models import F
from django.db import transaction

def demonstrate_f_expression():
    """演示 F 表达式的原子更新能力"""

    print("\n>>> F 表达式原子更新 <<<\n")

    # 获取当前库存
    book = Book.objects.get(slug="django-for-professionals")
    print(f"更新前库存: {book.stock}")

    # 1. 错误的做法：read-modify-write（存在竞态条件）
    # book.stock -= 1
    # book.save()
    # 如果两个线程同时执行，可能只减一次！

    # 2. F 表达式：数据库层原子操作
    Book.objects.filter(slug="django-for-professionals").update(
        stock=F("stock") - 1,
        sales_count=F("sales_count") + 1
    )
    # 生成 SQL: UPDATE books SET stock = stock - 1, sales_count = sales_count + 1 WHERE slug = '...'

    book.refresh_from_db()
    print(f"F 表达式更新后库存: {book.stock}")

    # 3. 带乐观锁的更新
    from django.db.models import Value
    from django.db.models.functions import Greatest

    # 确保库存不会变为负数
    Book.objects.filter(
        slug="django-for-professionals",
        stock__gt=0  # 乐观锁条件
    ).update(
        stock=Greatest(F("stock") - 1, Value(0)),
        sales_count=F("sales_count") + 1
    )

    book.refresh_from_db()
    print(f"带乐观锁更新后库存: {book.stock}")

    # 4. select_for_update（悲观锁）
    with transaction.atomic():
        # 锁定行，事务期间其他事务无法修改
        book = Book.objects.select_for_update().get(slug="django-for-professionals")

        # 安全的业务逻辑
        if book.stock > 0:
            book.stock -= 1
            book.sales_count += 1
            book.save()

        # 事务提交时释放锁

    print(f"悲观锁更新后库存: {book.stock}")

def demonstrate_subquery():
    """演示子查询和复杂查询"""

    print("\n>>> 子查询与复杂查询 <<<\n")

    # 1. 子查询：每本书的评论数
    from django.db.models import OuterRef, Subquery, Count

    review_count_subquery = Review.objects.filter(
        book=OuterRef("pk")
    ).values("book").annotate(
        count=Count("id")
    ).values("count")

    books_with_review_count = Book.objects.annotate(
        review_count=Subquery(review_count_subquery)
    )

    for book in books_with_review_count[:3]:
        print(f"{book.title}: {book.review_count or 0} 条评论")

    # 2. Exists 子查询：找到有评论的书
    has_reviews = Review.objects.filter(book=OuterRef("pk"))
    books_with_reviews = Book.objects.filter(Exists(has_reviews))
    print(f"\n有评论的书: {books_with_reviews.count()} 本")

    # 3. 窗口函数（需要 PostgreSQL）
    from django.db.models.functions import RowNumber, Rank

    books_ranked = Book.objects.annotate(
        rank=Window(
            expression=Rank(),
            partition_by=[F("category")],
            order_by=[F("sales_count").desc()]
        )
    )

    print("\n按分类排名（销售数）：")
    for book in books_ranked.order_by("category", "rank")[:5]:
        print(f"  [{book.category}] {book.title}: 排名 {book.rank}, 销量 {book.sales_count}")

    # 4. Case/When 条件表达式
    books_with_price_level = Book.objects.annotate(
        price_level=Case(
            When(price__lt=50, then=Value("便宜")),
            When(price__lt=100, then=Value("适中")),
            When(price__lt=200, then=Value("较贵")),
            default=Value("昂贵"),
            output_field=CharField()
        )
    )

    print("\n按价格分档：")
    for book in books_with_price_level[:5]:
        print(f"  {book.title}: ¥{book.price} - {book.price_level}")

批量操作性能优化

import random
from django.utils import timezone
from django.db import transaction

def benchmark_bulk_operations():
    """性能基准测试：批量操作"""

    print("\n>>> 批量操作性能基准测试 <<<\n")

    # 准备测试数据
    test_data = []
    for i in range(1000):
        test_data.append(Book(
            title=f"Test Book {i}",
            slug=f"test-book-{i}",
            isbn=f"978-test-{i:04d}",
            publisher_id=1,
            category_id=1,
            price=random.uniform(10, 200),
            stock=random.randint(0, 100),
            page_count=random.randint(100, 500),
            status="draft"
        ))

    # 方法 1: 逐个 save()
    start = time.time()
    with transaction.atomic():
        for book in test_data[:100]:
            book.save()
    print(f"逐个 save() (100 条): {time.time() - start:.4f}s")

    # 方法 2: bulk_create
    start = time.time()
    Book.objects.bulk_create(test_data[:100])
    print(f"bulk_create (100 条): {time.time() - start:.4f}s")

    # 方法 3: bulk_create + batch_size
    start = time.time()
    Book.objects.bulk_create(test_data[:500], batch_size=100)
    print(f"bulk_create batch=100 (500 条): {time.time() - start:.4f}s")

    # 方法 4: bulk_update
    books = list(Book.objects.filter(title__startswith="Test Book")[:50])
    for book in books:
        book.price = random.uniform(10, 200)
        book.stock = random.randint(0, 100)

    start = time.time()
    Book.objects.bulk_update(books, ["price", "stock"])
    print(f"bulk_update (50 条): {time.time() - start:.4f}s")

Django Admin 的深度定制

Django Admin 的真正价值不在于"省掉写后台的时间"，而在于它是一套基于模型元数据反射动态生成 CRUD 界面的引擎。

from django.contrib import admin
from django.utils.html import format_html
from django.urls import reverse
from django.db.models import Count, Avg

class ReviewInline(admin.TabularInline):
    """内联评论管理"""
    model = Review
    extra = 0  # 不显示空白行
    readonly_fields = ("created_at",)
    fields = ("reviewer", "rating", "title", "body", "helpful_count")
    show_change_link = True

class BookAdmin(admin.ModelAdmin):
    """完整的书籍管理配置"""

    # 列表显示
    list_display = (
        "title", "publisher_link", "category", "status_badge",
        "price_display", "stock_status", "rating_stars",
        "view_count", "publication_date"
    )
    list_display_links = ("title",)

    # 过滤器
    list_filter = (
        "status",
        ("category", admin.RelatedOnlyFieldListFilter),
        ("publication_date", admin.DateFieldListFilter),
        "publisher",
    )

    # 搜索
    search_fields = ("title", "isbn", "summary", "authors__first_name", "authors__last_name")

    # 排序
    ordering = ("-created_at",)

    # 分页
    list_per_page = 25

    # 批量操作
    actions = (
        "make_published",
        "make_draft",
        "bulk_update_price",
        "export_as_csv",
    )

    # 只读字段
    readonly_fields = ("created_at", "updated_at", "view_count", "sales_count")

    # 内联
    inlines = (ReviewInline,)

    # 字段分组
    fieldsets = (
        ("基本信息", {
            "fields": ("title", "slug", "isbn", "summary")
        }),
        ("出版信息", {
            "fields": ("publisher", "authors", "category", "status", "publication_date")
        }),
        ("定价与库存", {
            "fields": ("price", "discount_price", "stock")
        }),
        ("统计数据", {
            "fields": ("view_count", "sales_count", "rating"),
            "classes": ("collapse",)  # 默认折叠
        }),
        ("元数据", {
            "fields": ("created_at", "updated_at"),
            "classes": ("collapse",)
        }),
    )

    # 自动完成
    autocomplete_fields = ("publisher", "authors")

    # 预填充
    prepopulated_fields = {"slug": ("title",)}

    # 过滤器横向排列
    filter_horizontal = ("authors",)

    # 日期层次导航
    date_hierarchy = "publication_date"

    # 保存时行为
    save_on_top = True

    # --- 自定义列表显示方法 ---

    def publisher_link(self, obj):
        """可点击的出版社链接"""
        url = reverse("admin:app_publisher_change", args=[obj.publisher_id])
        return format_html('<a href="{}">{}</a>', url, obj.publisher.name)
    publisher_link.short_description = "出版社"
    publisher_link.admin_order_field = "publisher__name"

    def status_badge(self, obj):
        """状态徽章"""
        colors = {
            "published": "#28a745",    # 绿色
            "draft": "#ffc107",        # 黄色
            "out_of_print": "#dc3545", # 红色
        }
        color = colors.get(obj.status, "#6c757d")
        return format_html(
            '<span style="background:{};color:white;padding:2px 8px;'
            'border-radius:4px;font-size:0.85em">{}</span>',
            color, obj.get_status_display()
        )
    status_badge.short_description = "状态"

    def price_display(self, obj):
        """价格显示（含折扣）"""
        if obj.discount_price:
            return format_html(
                '<span style="text-decoration:line-through;color:#999">¥{}</span> '
                '<span style="color:#dc3545;font-weight:bold">¥{}</span>',
                obj.price, obj.discount_price
            )
        return f"¥{obj.price}"
    price_display.short_description = "价格"
    price_display.admin_order_field = "price"

    def stock_status(self, obj):
        """库存状态"""
        if obj.stock == 0:
            return format_html('<span style="color:#dc3545">缺货</span>')
        elif obj.stock < 10:
            return format_html('<span style="color:#ffc107">{} 本（低库存）</span>', obj.stock)
        return f"{obj.stock} 本"
    stock_status.short_description = "库存"
    stock_status.admin_order_field = "stock"

    def rating_stars(self, obj):
        """星级评分"""
        full_stars = int(obj.rating)
        half_star = obj.rating - full_stars >= 0.5
        empty_stars = 5 - full_stars - (1 if half_star else 0)

        stars = "★" * full_stars
        if half_star:
            stars += "½"
        stars += "☆" * empty_stars

        return format_html(
            '<span style="color:#f0ad4e">{}</span> {:.1f}',
            stars, obj.rating
        )
    rating_stars.short_description = "评分"
    rating_stars.admin_order_field = "rating"

    # --- 自定义批量操作 ---

    @admin.action(description="批量发布选中书籍")
    def make_published(self, request, queryset):
        """批量发布"""
        updated = queryset.filter(status="draft").update(
            status="published",
            publication_date=timezone.now().date()
        )
        self.message_user(request, f"成功发布 {updated} 本书籍")

    @admin.action(description="批量设为草稿")
    def make_draft(self, request, queryset):
        updated = queryset.exclude(status="draft").update(status="draft")
        self.message_user(request, f"成功将 {updated} 本书籍设为草稿")

    @admin.action(description="批量调整价格（上涨 10%）")
    def bulk_update_price(self, request, queryset):
        """批量调整价格"""
        from django.db.models import F
        queryset.update(price=F("price") * 1.1)
        self.message_user(request, f"成功更新 {queryset.count()} 本书籍的价格")

    @admin.action(description="导出为 CSV")
    def export_as_csv(self, request, queryset):
        """导出数据为 CSV"""
        import csv
        from django.http import HttpResponse

        response = HttpResponse(content_type="text/csv; charset=utf-8-sig")
        response["Content-Disposition"] = 'attachment; filename="books_export.csv"'

        writer = csv.writer(response)
        writer.writerow(["标题", "ISBN", "出版社", "价格", "库存", "状态"])

        for book in queryset.select_related("publisher"):
            writer.writerow([
                book.title, book.isbn, book.publisher.name,
                book.price, book.stock, book.get_status_display()
            ])

        return response

# 注册模型
admin.site.register(Book, BookAdmin)
admin.site.register(Author)
admin.site.register(Publisher)
admin.site.register(Category)

# 自定义 Admin 站点
class BookstoreAdminSite(admin.AdminSite):
    """自定义管理站点"""
    site_header = "Bookstore 管理系统"
    site_title = "Bookstore Admin"
    index_title = "管理面板"

    def get_app_list(self, request):
        """自定义应用列表顺序"""
        app_list = super().get_app_list(request)
        # 自定义排序逻辑
        return app_list

Django REST Framework 深度集成

Serializer 的高级用法

from rest_framework import serializers
from rest_framework.validators import UniqueValidator, UniqueTogetherValidator
from django.core.validators import MinValueValidator, MaxValueValidator
import re

class PublisherSerializer(serializers.ModelSerializer):
    """出版社序列化器"""
    book_count = serializers.IntegerField(read_only=True)

    class Meta:
        model = Publisher
        fields = ["id", "name", "address", "website", "established_date", "book_count"]
        read_only_fields = ["id"]

class AuthorSerializer(serializers.ModelSerializer):
    """作者序列化器"""
    full_name = serializers.CharField(read_only=True)

    class Meta:
        model = Author
        fields = ["id", "first_name", "last_name", "email", "birth_date", "bio", "full_name"]
        read_only_fields = ["id"]
        extra_kwargs = {
            "email": {
                "validators": [UniqueValidator(queryset=Author.objects.all())]
            }
        }

class ReviewSerializer(serializers.ModelSerializer):
    """评论序列化器"""
    reviewer_name = serializers.CharField(source="reviewer.full_name", read_only=True)

    class Meta:
        model = Review
        fields = ["id", "rating", "title", "body", "helpful_count", "reviewer_name", "created_at"]
        read_only_fields = ["id", "helpful_count", "created_at"]
        validators = [
            UniqueTogetherValidator(
                queryset=Review.objects.all(),
                fields=["book", "reviewer"],
                message="您已经评论过这本书了"
            )
        ]

    def validate_rating(self, value):
        if not 1 <= value <= 5:
            raise serializers.ValidationError("评分必须在 1-5 之间")
        return value

    def validate_body(self, value):
        if len(value.strip()) < 10:
            raise serializers.ValidationError("评论内容至少 10 个字符")
        return value

class BookListSerializer(serializers.ModelSerializer):
    """书籍列表序列化器（轻量版）"""
    publisher_name = serializers.CharField(source="publisher.name", read_only=True)
    category_name = serializers.CharField(source="category.name", read_only=True)
    author_count = serializers.IntegerField(read_only=True)

    class Meta:
        model = Book
        fields = [
            "id", "title", "slug", "isbn",
            "publisher_name", "category_name",
            "price", "discount_price", "stock",
            "status", "rating", "author_count",
            "publication_date"
        ]
        read_only_fields = ["id", "rating"]

class BookDetailSerializer(serializers.ModelSerializer):
    """书籍详情序列化器（完整版）"""
    publisher = PublisherSerializer(read_only=True)
    authors = AuthorSerializer(many=True, read_only=True)
    category_name = serializers.CharField(source="category.name", read_only=True)
    reviews = ReviewSerializer(many=True, read_only=True)
    current_price = serializers.DecimalField(max_digits=10, decimal_places=2, read_only=True)
    days_since_publication = serializers.SerializerMethodField()

    class Meta:
        model = Book
        fields = [
            "id", "title", "slug", "isbn",
            "publisher", "authors", "category_name",
            "summary", "page_count",
            "price", "discount_price", "current_price", "stock",
            "view_count", "sales_count", "rating",
            "status", "publication_date", "days_since_publication",
            "created_at", "updated_at",
            "reviews"
        ]
        read_only_fields = ["id", "view_count", "sales_count", "rating", "created_at", "updated_at"]

    def get_days_since_publication(self, obj):
        """计算出版天数"""
        if obj.publication_date:
            delta = timezone.now().date() - obj.publication_date
            return delta.days
        return None

    def to_representation(self, instance):
        """自定义序列化输出"""
        data = super().to_representation(instance)
        # 如果用户未登录，隐藏成本价相关字段
        request = self.context.get("request")
        if request and not request.user.is_staff:
            data.pop("price", None)
            data.pop("discount_price", None)
        return data

class BookCreateUpdateSerializer(serializers.ModelSerializer):
    """书籍创建/更新序列化器"""
    author_ids = serializers.ListField(
        child=serializers.IntegerField(),
        write_only=True
    )

    class Meta:
        model = Book
        fields = [
            "title", "slug", "isbn",
            "publisher", "author_ids", "category",
            "summary", "page_count",
            "price", "discount_price", "stock",
            "status", "publication_date"
        ]
        extra_kwargs = {
            "slug": {
                "validators": [UniqueValidator(queryset=Book.objects.all())]
            },
            "isbn": {
                "validators": [
                    UniqueValidator(queryset=Book.objects.all()),
                    serializers.RegexValidator(
                        r"^\d{13}$", "ISBN 必须是 13 位数字"
                    )
                ]
            }
        }

    def validate_isbn(self, value):
        """验证 ISBN-13 校验位"""
        if not value.isdigit() or len(value) != 13:
            raise serializers.ValidationError("ISBN 必须是 13 位数字")

        # ISBN-13 校验位算法
        total = sum(int(d) * (1 if i % 2 == 0 else 3) for i, d in enumerate(value[:12]))
        check_digit = (10 - (total % 10)) % 10

        if int(value[12]) != check_digit:
            raise serializers.ValidationError(f"ISBN 校验位错误，应为 {check_digit}")

        return value

    def create(self, validated_data):
        author_ids = validated_data.pop("author_ids")
        book = Book.objects.create(**validated_data)
        book.authors.set(author_ids)
        return book

    def update(self, instance, validated_data):
        author_ids = validated_data.pop("author_ids", None)

        for attr, value in validated_data.items():
            setattr(instance, attr, value)
        instance.save()

        if author_ids is not None:
            instance.authors.set(author_ids)

        return instance

ViewSet 与 Router

from rest_framework import viewsets, status, filters, permissions
from rest_framework.decorators import action
from rest_framework.response import Response
from rest_framework.pagination import PageNumberPagination
from django_filters.rest_framework import DjangoFilterBackend
from django.db.models import Count, Q

class BookPagination(PageNumberPagination):
    """自定义分页"""
    page_size = 20
    page_size_query_param = "page_size"
    max_page_size = 100

class BookFilter(filters.FilterSet):
    """自定义过滤器"""
    min_price = filters.NumberFilter(field_name="price", lookup_expr="gte")
    max_price = filters.NumberFilter(field_name="price", lookup_expr="lte")
    min_rating = filters.NumberFilter(field_name="rating", lookup_expr="gte")
    author_name = filters.CharFilter(
        field_name="authors__last_name", lookup_expr="icontains"
    )
    published_after = filters.DateFilter(
        field_name="publication_date", lookup_expr="gte"
    )
    published_before = filters.DateFilter(
        field_name="publication_date", lookup_expr="lte"
    )
    search_all = filters.CharFilter(method="filter_search_all")

    class Meta:
        model = Book
        fields = {
            "status": ["exact"],
            "category": ["exact"],
            "publisher": ["exact"],
            "stock": ["gt", "lt"],
        }

    def filter_search_all(self, queryset, name, value):
        """全文搜索"""
        return queryset.filter(
            Q(title__icontains=value) |
            Q(isbn__icontains=value) |
            Q(summary__icontains=value) |
            Q(authors__first_name__icontains=value) |
            Q(authors__last_name__icontains=value)
        ).distinct()

class BookViewSet(viewsets.ModelViewSet):
    """完整的书籍 API ViewSet"""
    queryset = Book.objects.select_related(
        "publisher", "category"
    ).prefetch_related("authors").all()

    filter_backends = [
        DjangoFilterBackend,
        filters.SearchFilter,
        filters.OrderingFilter
    ]
    filterset_class = BookFilter
    search_fields = ["title", "isbn", "summary"]
    ordering_fields = [
        "title", "price", "-price",
        "rating", "-rating",
        "publication_date", "-publication_date",
        "created_at", "-created_at",
        "sales_count", "-sales_count"
    ]
    ordering = ["-created_at"]

    pagination_class = BookPagination

    def get_serializer_class(self):
        """根据操作选择序列化器"""
        if self.action == "list":
            return BookListSerializer
        elif self.action in ("create", "update", "partial_update"):
            return BookCreateUpdateSerializer
        return BookDetailSerializer

    def get_permissions(self):
        """根据操作选择权限"""
        if self.action in ("create", "update", "partial_update", "destroy"):
            return [permissions.IsAuthenticated()]
        return [permissions.AllowAny()]

    @action(detail=True, methods=["post"])
    def like(self, request, pk=None):
        """点赞操作"""
        book = self.get_object()
        book.view_count += 1
        book.save(update_fields=["view_count"])
        return Response({"message": "Liked", "view_count": book.view_count})

    @action(detail=False, methods=["get"])
    def top_rated(self, request):
        """获取评分最高的书籍"""
        top_books = self.get_queryset().filter(
            rating__gte=4.0, status="published"
        ).order_by("-rating")[:10]

        serializer = BookListSerializer(top_books, many=True)
        return Response(serializer.data)

    @action(detail=False, methods=["get"])
    def statistics(self, request):
        """获取统计数据"""
        from django.db.models import Avg, Count, Sum

        stats = Book.objects.aggregate(
            total_books=Count("id"),
            avg_price=Avg("price"),
            total_stock=Sum("stock"),
            avg_rating=Avg("rating"),
            published_count=Count("id", filter=Q(status="published"))
        )

        by_category = Book.objects.values(
            "category__name"
        ).annotate(count=Count("id")).order_by("-count")

        return Response({
            "statistics": stats,
            "by_category": list(by_category)
        })

    def perform_create(self, serializer):
        """创建时附加逻辑"""
        serializer.save()

    def perform_update(self, serializer):
        """更新时附加逻辑"""
        serializer.save()

# 注册路由
from rest_framework.routers import DefaultRouter

router = DefaultRouter()
router.register("books", BookViewSet, basename="book")
router.register("authors", AuthorViewSet)
router.register("publishers", PublisherViewSet)

# 自动生成的路由：
# GET    /api/books/              → list（分页列表）
# POST   /api/books/              → create（创建）
# GET    /api/books/{id}/         → retrieve（详情）
# PUT    /api/books/{id}/         → update（完整更新）
# PATCH  /api/books/{id}/         → partial_update（部分更新）
# DELETE /api/books/{id}/         → destroy（删除）
# POST   /api/books/{id}/like/    → like（自定义操作）
# GET    /api/books/top_rated/    → top_rated（自定义操作）
# GET    /api/books/statistics/   → statistics（自定义操作）

urlpatterns = router.urls

生产环境部署：从 Docker 到 Kubernetes

Docker 多阶段构建

# Dockerfile
# 第一阶段：构建依赖
FROM python:3.12-slim AS builder

WORKDIR /app

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    build-essential \
    libpq-dev \
    python3-dev \
    libjpeg-dev \
    zlib1g-dev \
    && rm -rf /var/lib/apt/lists/*

# 创建虚拟环境
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && \
    pip install --no-cache-dir -r requirements.txt

# 第二阶段：运行时
FROM python:3.12-slim

WORKDIR /app

# 安装运行时依赖
RUN apt-get update && apt-get install -y \
    libpq-dev \
    libjpeg-dev \
    curl \
    netcat-openbsd \
    && rm -rf /var/lib/apt/lists/*

# 复制虚拟环境
COPY --from=builder /opt/venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 创建用户
RUN useradd -m -u 1000 djangouser \
    && mkdir -p /app/staticfiles /app/media /var/log/django \
    && chown -R djangouser:djangouser /app /var/log/django

# 复制源码
COPY --chown=djangouser:djangouser . .

USER djangouser

# 启动脚本
COPY docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8000/health/ || exit 1

EXPOSE 8000

ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["gunicorn", "config.wsgi:application", \
     "--bind", "0.0.0.0:8000", \
     "--workers", "4", \
     "--worker-class", "gthread", \
     "--threads", "2", \
     "--max-requests", "1000", \
     "--max-requests-jitter", "100", \
     "--timeout", "120", \
     "--graceful-timeout", "30", \
     "--access-logfile", "/var/log/django/access.log", \
     "--error-logfile", "/var/log/django/error.log"]

docker-entrypoint.sh

#!/bin/bash
set -e

echo "=========================================="
echo "Django Docker Entrypoint"
echo "=========================================="

# 等待数据库就绪
echo "Waiting for database..."
while ! nc -z $DB_HOST $DB_PORT; do
    sleep 1
done
echo "Database is ready!"

# 运行迁移
echo "Running database migrations..."
python manage.py migrate --noinput

# 收集静态文件
echo "Collecting static files..."
python manage.py collectstatic --noinput

# 创建超级用户（如果不存在）
echo "Creating superuser if not exists..."
python manage.py shell -c "
from django.contrib.auth import get_user_model;
User = get_user_model();
if not User.objects.filter(username='admin').exists():
    User.objects.create_superuser('admin', 'admin@example.com', '${DJANGO_SUPERUSER_PASSWORD:-admin123}')
    print('Superuser created.')
else:
    print('Superuser already exists.')
"

echo "Starting application..."
exec "$@"

docker-compose 完整编排

version: '3.8'

x-django-env: &django-env
  DJANGO_SETTINGS_MODULE: config.settings.production
  DJANGO_SECRET_KEY: ${DJANGO_SECRET_KEY}
  DB_ENGINE: django.db.backends.postgresql
  DB_HOST: postgres
  DB_PORT: 5432
  DB_NAME: ${DB_NAME:-djangodb}
  DB_USER: ${DB_USER:-djangouser}
  DB_PASSWORD: ${DB_PASSWORD}
  REDIS_URL: redis://redis:6379/0
  EMAIL_HOST: ${EMAIL_HOST:-smtp.sendgrid.net}
  EMAIL_PORT: ${EMAIL_PORT:-587}
  EMAIL_HOST_USER: ${EMAIL_HOST_USER}
  EMAIL_HOST_PASSWORD: ${EMAIL_HOST_PASSWORD}

services:
  postgres:
    image: postgres:16-alpine
    container_name: django-postgres
    environment:
      POSTGRES_DB: ${DB_NAME:-djangodb}
      POSTGRES_USER: ${DB_USER:-djangouser}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./scripts/init-db.sql:/docker-entrypoint-initdb.d/init.sql
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-djangouser} -d ${DB_NAME:-djangodb}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - django-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: django-redis
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - django-network
    restart: unless-stopped

  django-app:
    build:
      context: .
      dockerfile: Dockerfile
    image: django-app:latest
    container_name: django-app
    environment:
      <<: *django-env
    volumes:
      - static_volume:/app/staticfiles
      - media_volume:/app/media
      - django_logs:/var/log/django
    ports:
      - "8000:8000"
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    networks:
      - django-network
    restart: unless-stopped

  celery-worker:
    build:
      context: .
      dockerfile: Dockerfile
    image: django-app:latest
    container_name: django-celery-worker
    command: celery -A config.celery_app worker --loglevel=info --concurrency=4
    environment:
      <<: *django-env
      CELERY_BROKER_URL: redis://redis:6379/1
      CELERY_RESULT_BACKEND: redis://redis:6379/2
    volumes:
      - media_volume:/app/media
    depends_on:
      - redis
      - postgres
    networks:
      - django-network
    restart: unless-stopped

  celery-beat:
    build:
      context: .
      dockerfile: Dockerfile
    image: django-app:latest
    container_name: django-celery-beat
    command: celery -A config.celery_app beat --loglevel=info --scheduler django_celery_beat.schedulers:DatabaseScheduler
    environment:
      <<: *django-env
      CELERY_BROKER_URL: redis://redis:6379/1
      CELERY_RESULT_BACKEND: redis://redis:6379/2
    depends_on:
      - redis
      - postgres
    networks:
      - django-network
    restart: unless-stopped

  nginx:
    image: nginx:1.25-alpine
    container_name: django-nginx
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/sites-enabled:/etc/nginx/sites-enabled:ro
      - static_volume:/var/www/static:ro
      - media_volume:/var/www/media:ro
      - nginx_logs:/var/log/nginx
    ports:
      - "80:80"
      - "443:443"
    depends_on:
      - django-app
    networks:
      - django-network
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  static_volume:
  media_volume:
  django_logs:
  nginx_logs:

networks:
  django-network:
    driver: bridge

Kubernetes 部署清单

# k8s/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: django-app

---
# k8s/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: django-config
  namespace: django-app
data:
  DJANGO_SETTINGS_MODULE: "config.settings.production"
  DB_ENGINE: "django.db.backends.postgresql"
  DB_HOST: "postgres-service"
  DB_PORT: "5432"
  DB_NAME: "djangodb"
  REDIS_URL: "redis://redis-service:6379/0"

---
# k8s/secrets.yaml
apiVersion: v1
kind: Secret
metadata:
  name: django-secrets
  namespace: django-app
type: Opaque
stringData:
  DJANGO_SECRET_KEY: "your-super-secret-key-here"
  DB_USER: "djangouser"
  DB_PASSWORD: "your-db-password"
  EMAIL_HOST_USER: "apikey"
  EMAIL_HOST_PASSWORD: "your-sendgrid-key"

---
# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: django-app
  namespace: django-app
  labels:
    app: django-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: django-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: django-app
    spec:
      containers:
      - name: django-app
        image: django-app:latest
        imagePullPolicy: Always
        ports:
        - containerPort: 8000
          name: http
        envFrom:
        - configMapRef:
            name: django-config
        - secretRef:
            name: django-secrets
        resources:
          requests:
            cpu: 250m
            memory: 512Mi
          limits:
            cpu: 1000m
            memory: 1Gi
        livenessProbe:
          httpGet:
            path: /health/
            port: 8000
          initialDelaySeconds: 30
          periodSeconds: 30
          timeoutSeconds: 5
          failureThreshold: 3
        readinessProbe:
          httpGet:
            path: /health/
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 10
          timeoutSeconds: 3
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: app
                  operator: In
                  values:
                  - django-app
              topologyKey: kubernetes.io/hostname

---
# k8s/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: django-service
  namespace: django-app
spec:
  selector:
    app: django-app
  ports:
  - port: 80
    targetPort: 8000
    protocol: TCP
    name: http
  type: ClusterIP

---
# k8s/ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: django-ingress
  namespace: django-app
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
spec:
  tls:
  - hosts:
    - api.bookstore.example.com
    - admin.bookstore.example.com
    secretName: bookstore-tls
  rules:
  - host: api.bookstore.example.com
    http:
      paths:
      - pathType: Prefix
        path: /api/
        backend:
          service:
            name: django-service
            port:
              number: 80
  - host: admin.bookstore.example.com
    http:
      paths:
      - pathType: Prefix
        path: /
        backend:
          service:
            name: django-service
            port:
              number: 80

企业级避坑指南

1. settings 模块拆分与环境隔离

触发条件：所有环境用同一个 settings.py，DEBUG=True 硬编码，SECRET_KEY 明文。

后果：生产环境暴露 DEBUG 页面（含完整 traceback 和局部变量），攻击者可获取数据库结构、源代码路径和敏感变量值。

修复方案：

# config/settings/base.py
import os
from pathlib import Path

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

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    # 第三方
    "rest_framework",
    "corsheaders",
    "django_filters",
    # 本地
    "apps.books",
    "apps.users",
]

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "corsheaders.middleware.CorsMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

# config/settings/development.py
from .base import *

DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1"]

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

# config/settings/production.py
from .base import *

DEBUG = False
ALLOWED_HOSTS = os.environ.get("ALLOWED_HOSTS", "").split(",")

SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]

DATABASES = {
    "default": {
        "ENGINE": os.environ.get("DB_ENGINE"),
        "HOST": os.environ["DB_HOST"],
        "PORT": os.environ["DB_PORT"],
        "NAME": os.environ["DB_NAME"],
        "USER": os.environ["DB_USER"],
        "PASSWORD": os.environ["DB_PASSWORD"],
        "CONN_MAX_AGE": 600,
        "OPTIONS": {
            "connect_timeout": 10,
        }
    }
}

# 安全配置
SECURE_SSL_REDIRECT = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SECURE_BROWSER_XSS_FILTER = True
SECURE_HSTS_SECONDS = 31536000
SECURE_HSTS_INCLUDE_SUBDOMAINS = True

# 缓存
CACHES = {
    "default": {
        "BACKEND": "django.core.cache.backends.redis.RedisCache",
        "LOCATION": os.environ["REDIS_URL"],
    }
}

2. 数据库迁移冲突与合并

触发条件：多人同时开发，各自生成 migration 文件，依赖链冲突。

后果：迁移无法执行，数据库升级受阻，甚至需要重建数据库。

修复方案：

# 1. 开发时拉取最新代码后先合并迁移
python manage.py makemigrations --merge

# 2. 检查迁移是否冲突（推荐 django-migration-linter）
pip install django-migration-linter
python manage.py lintmigrations

# 3. 生产环境迁移前备份
python manage.py dumpdata --natural-foreign --natural-primary \
    -e contenttypes -e auth.Permission -o backup.json

# 4. 执行迁移（dry-run 先验证）
python manage.py migrate --plan
python manage.py migrate

# 5. CI/CD 中禁止自动生成迁移（只允许手动创建）
# .github/workflows/test.yml
- name: Check missing migrations
  run: python manage.py makemigrations --check --dry-run

3. bulk_create 不触发信号

触发条件：依赖 post_save 信号做审计日志或后续处理，但使用了 bulk_create。

后果：数据已入库，但信号中的业务逻辑未执行（如索引更新、通知发送）。

修复方案：

from django.db.models.signals import post_save
from django.dispatch import receiver

# 1. 为 bulk_create 手动触发信号
def bulk_create_with_signals(model, objects, batch_size=None):
    """带信号的批量创建"""
    created = model.objects.bulk_create(objects, batch_size=batch_size)

    # 手动发送信号
    for obj in created:
        post_save.send(
            sender=model,
            instance=obj,
            created=True,
            raw=False,
            using="default"
        )

    return created

# 2. 或避免 bulk_create，用事务包裹
from django.db import transaction

with transaction.atomic():
    for obj in objects:
        obj.save()  # 会触发信号，但慢得多

# 3. 最佳实践：信号只做轻量逻辑，重量级用 Celery
@receiver(post_save, sender=Book)
def on_book_saved(sender, instance, created, **kwargs):
    """信号中只发消息，不做重操作"""
    from .tasks import index_book, invalidate_cache

    # 异步处理
    transaction.on_commit(lambda: index_book.delay(instance.id))
    transaction.on_commit(lambda: invalidate_cache.delay(instance.id))

4. 文件上传的安全边界

触发条件：ImageField/FileField 未做文件类型/content-type 校验，未限制大小。

后果：上传恶意文件（含脚本的 SVG、伪装后缀的可执行文件），或大文件耗尽磁盘。

修复方案：

from django.core.exceptions import ValidationError
from django.core.validators import FileExtensionValidator
import magic  # python-magic

def validate_file_type(value):
    """基于文件内容的类型验证"""
    # 读取文件头部进行 MIME 类型检测
    file_content = value.read(2048)
    value.seek(0)  # 重置文件指针

    mime = magic.from_buffer(file_content, mime=True)
    allowed_mimes = {
        "image/jpeg", "image/png", "image/gif", "image/webp",
        "application/pdf"
    }

    if mime not in allowed_mimes:
        raise ValidationError(f"不支持的文件类型: {mime}")

def validate_file_size(value):
    """文件大小验证"""
    max_size = 10 * 1024 * 1024  # 10MB
    if value.size > max_size:
        raise ValidationError(f"文件大小不能超过 {max_size // (1024*1024)}MB")

class DocumentUpload(models.Model):
    """安全的文件上传模型"""
    title = models.CharField(max_length=200)
    file = models.FileField(
        upload_to="documents/%Y/%m/%d/",
        validators=[
            FileExtensionValidator(["pdf", "jpg", "png"]),
            validate_file_type,
            validate_file_size
        ]
    )
    uploaded_at = models.DateTimeField(auto_now_add=True)

# 生产环境额外安全措施
# Nginx 配置限制上传大小
# client_max_body_size 10M;

# 定期清理未使用的文件
# python manage.py cleanup_unused_media

5. 缓存策略不当

触发条件：直接使用 @cache_page 不做版本控制，或缓存 key 冲突。

后果：发布新内容后用户看到旧缓存，或不同用户看到相同缓存内容。

修复方案：

from django.core.cache import cache
from django.views.decorators.cache import cache_page
from django.utils.decorators import method_decorator
import hashlib
import json

# 1. 版本化缓存 key
def cache_key_versioned(prefix, obj_id, version):
    """带版本的缓存 key"""
    return f"{prefix}:{obj_id}:v{version}"

# 2. 用户相关缓存
def cache_key_user_specific(prefix, user_id):
    """用户特定的缓存 key"""
    return f"{prefix}:user:{user_id}"

# 3. 带 etag 的视图缓存
from django.views.decorators.http import condition

def book_etag(request, slug):
    """基于最后修改时间的 ETag"""
    try:
        book = Book.objects.only("updated_at").get(slug=slug)
        return str(book.updated_at.timestamp())
    except Book.DoesNotExist:
        return None

@condition(etag_func=book_etag)
def book_detail(request, slug):
    book = Book.objects.get(slug=slug)
    return render(request, "book_detail.html", {"book": book})

# 4. 缓存失效策略
def invalidate_book_cache(book_id):
    """失效所有相关缓存"""
    patterns = [
        f"book:{book_id}:*",
        "book_list:*",
        "top_rated",
        "statistics"
    ]

    for pattern in patterns:
        if "*" in pattern:
            # 使用 Redis 的 SCAN 命令（需 django-redis）
            cache.delete_pattern(pattern)
        else:
            cache.delete(pattern)

# 5. 缓存预热
def warm_cache():
    """启动时预热热门数据"""
    books = Book.objects.filter(status="published").order_by("-rating")[:100]
    for book in books:
        key = f"book:{book.id}:detail"
        if not cache.get(key):
            cache.set(key, BookDetailSerializer(book).data, timeout=3600)

6. 日志未串联

触发条件：无统一请求 ID，日志分散在各服务中。

后果：生产问题定位如大海捞针，无法追踪完整链路。

修复方案：

# middleware.py
import uuid
import logging
from django.utils.deprecation import MiddlewareMixin

logger = logging.getLogger(__name__)

class RequestIDMiddleware(MiddlewareMixin):
    """为每个请求添加唯一 ID"""

    def process_request(self, request):
        request.request_id = request.META.get("HTTP_X_REQUEST_ID", str(uuid.uuid4()))

    def process_response(self, request, response):
        response["X-Request-ID"] = request.request_id
        return response

# 日志配置
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "filters": {
        "request_id": {
            "()": "apps.core.logging.RequestIDFilter"
        }
    },
    "formatters": {
        "verbose": {
            "format": "{levelname} {asctime} {module} [request_id={request_id}] {message}",
            "style": "{",
        }
    },
    "handlers": {
        "console": {
            "class": "logging.StreamHandler",
            "formatter": "verbose",
            "filters": ["request_id"],
        },
        "file": {
            "class": "logging.handlers.RotatingFileHandler",
            "filename": "/var/log/django/app.log",
            "maxBytes": 50 * 1024 * 1024,  # 50MB
            "backupCount": 10,
            "formatter": "verbose",
            "filters": ["request_id"],
        }
    },
    "loggers": {
        "django": {
            "handlers": ["console", "file"],
            "level": "WARNING" if not DEBUG else "INFO",
            "propagate": False,
        },
        "apps": {
            "handlers": ["console", "file"],
            "level": "INFO",
            "propagate": False,
        }
    }
}

# Django 查询日志（仅开发环境）
if DEBUG:
    LOGGING["loggers"]["django.db.backends"] = {
        "handlers": ["console"],
        "level": "DEBUG",
        "propagate": False,
    }

7. Admin 安全加固

# admin.py
from django.contrib import admin
from django.contrib.admin import AdminSite

class SecureAdminSite(AdminSite):
    """加固后的管理站点"""

    # 自定义登录模板
    login_template = "admin/login.html"

    # 限制登录尝试
    def has_permission(self, request):
        return request.user.is_active and request.user.is_staff

    def each_context(self, request):
        context = super().each_context(request)
        context["ip_address"] = request.META.get("REMOTE_ADDR")
        return context

# 使用加固站点
admin_site = SecureAdminSite(name="secure_admin")

# 额外安全措施
# 1. 限制 Admin URL（只允许内网访问）
# Nginx: allow 10.0.0.0/8; deny all;

# 2. 二次认证
# 使用 django-otp
from django_otp.admin import OTPAdminSite
admin.site.__class__ = OTPAdminSite

# 3. 审计日志
# 使用 django-auditlog 记录所有 Admin 操作

Django、Flask、FastAPI 终极选型决策框架

决策维度	Django	Flask	FastAPI
定位	全栈框架（一切内置）	微框架（自由组合）	异步 API 框架
学习成本	高（概念多，隐式行为多）	低（核心就 4 个概念）	中（需 async/await）
ORM 质量	内置，最成熟	SQLAlchemy（需集成）	SQLAlchemy（需集成）
Admin 后台	内置，零开发成本	无，需 flask-admin	无，需 SQLAdmin
认证系统	内置（User、Permission、Group）	Flask-Login	fastapi-users
API 文档	DRF（需安装）	flasgger	OpenAPI 自动生成
模板引擎	Django Templates	Jinja2	无（可集成 Jinja2）
WebSocket	Channels（额外配置）	Flask-SocketIO	原生支持
测试工具	内置 TestCase	pytest-flask	TestClient
部署复杂度	中等	简单	简单
社区规模	最大（20年历史）	次大（13年）	快速增长（5年）
生产案例	Instagram、Disqus、Mozilla	Netflix、Airbnb、Lyft	Netflix、Uber、Microsoft
适合项目	CMS、电商、后台密集型	轻量API、微服务、原型	高并发API、ML serving、实时通信