@humanbased/crosscheck 1.2.0-beta.80 → 1.2.0

package/assets/skills/code-review-skill/reference/django.md

@@ -1,985 +0,0 @@
-# Django / DRF Code Review Guide
-
-> Django / DRF 代码审查指南，覆盖安全审查、N+1 查询优化、Serializer 反模式、ViewSet 最佳实践、异步视图及生产安全配置等核心主题。
-
-## 目录
-
-- [安全审查](#安全审查)
-- [N+1 查询优化](#n1-查询优化)
-- [Serializer 反模式](#serializer-反模式)
-- [ViewSet 最佳实践](#viewset-最佳实践)
-- [异步视图](#异步视图)
-- [中间件与设置](#中间件与设置)
-- [Review Checklist](#review-checklist)
-
----
-
-## 安全审查
-
-### XSS 防护
-
-Django 模板引擎默认自动转义。审查重点：`mark_safe`、`autoescape off`、`format_html` 的使用。
-
-> **跨框架 XSS 防护详见 [XSS Prevention Guide](cross-cutting/xss-prevention.md)**，含 React/Vue/Angular/Svelte 示例及 CSP 配置。
-
-### CSRF 防护
-
-```python
-from django.views.decorators.csrf import csrf_exempt
-
-# ❌ 禁用 CSRF 保护
-@csrf_exempt
-def process_payment(request):
-    # 任何恶意网站都可以提交表单
-    amount = request.POST["amount"]
-    charge(amount)
-
-# ✅ 保留默认 CSRF 保护
-from django.middleware.csrf import CsrfViewMiddleware
-
-# settings.py — 确保 CSRF 中间件已启用
-MIDDLEWARE = [
-    # ...
-    "django.middleware.csrf.CsrfViewMiddleware",
-    # ...
-]
-
-# ✅ API 使用 token 认证代替 CSRF
-# settings.py
-REST_FRAMEWORK = {
-    "DEFAULT_AUTHENTICATION_CLASSES": [
-        "rest_framework.authentication.SessionAuthentication",
-        "rest_framework.authentication.TokenAuthentication",
-    ],
-}
-
-# ✅ 前端 AJAX 请求带上 CSRF token
-# JavaScript: fetch("/api/endpoint/", {
-#   headers: {"X-CSRFToken": document.querySelector("[name=csrfmiddlewaretoken]").value}
-# })
-```
-
-### Cookie 安全设置
-
-```python
-# settings.py
-
-# ❌ 不安全的 cookie 配置
-SESSION_COOKIE_SECURE = False
-CSRF_COOKIE_SECURE = False
-SESSION_COOKIE_HTTPONLY = False
-
-# ✅ 生产环境 cookie 安全配置
-SESSION_COOKIE_SECURE = True    # HTTPS only
-SESSION_COOKIE_HTTPONLY = True   # JavaScript 无法读取
-SESSION_COOKIE_SAMESITE = "Lax"  # 防止 CSRF
-CSRF_COOKIE_SECURE = True
-CSRF_COOKIE_HTTPONLY = True
-CSRF_COOKIE_SAMESITE = "Lax"
-```
-
-### SQL 注入防护
-
-Django ORM 自动参数化查询。审查重点：`raw()`、`extra()`、`RawSQL`、`connection.cursor()` 中的字符串拼接。
-
-> **跨语言 SQL 注入防护详见 [SQL Injection Prevention Guide](cross-cutting/sql-injection-prevention.md)**，含 Python/Java/Go/Node.js/PHP/C# 示例及 ORM 不安全用法。
-
-### 文件上传安全
-
-```python
-# settings.py
-
-# ❌ 默认上传配置不安全
-FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440  # 2.5 MB — 可以接受
-MEDIA_ROOT = "/var/www/uploads"         # web 根目录下
-ALLOWED_UPLOAD_TYPES = None             # 没有类型限制
-
-# ✅ 限制上传大小和位置
-DATA_UPLOAD_MAX_MEMORY_SIZE = 10485760  # 10 MB
-FILE_UPLOAD_MAX_MEMORY_SIZE = 2621440   # 2.5 MB in-memory
-MEDIA_ROOT = "/srv/media/"              # web 根目录之外
-
-# ✅ 验证文件类型
-import mimetypes
-from pathlib import Path
-
-ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".pdf"}
-
-def validate_upload(file):
-    ext = Path(file.name).suffix.lower()
-    if ext not in ALLOWED_EXTENSIONS:
-        raise ValidationError(f"File type {ext} is not allowed.")
-    mime, _ = mimetypes.guess_type(file.name)
-    if mime not in {"image/jpeg", "image/png", "application/pdf"}:
-        raise ValidationError("Invalid MIME type.")
-```
-
----
-
-## N+1 查询优化
-
-> 📖 通用原理和跨语言方案详见 [N+1 查询跨语言指南](cross-cutting/n-plus-one-queries.md)
-
-### select_related（ForeignKey / OneToOne）
-
-```python
-# ❌ N+1: 每本书查一次出版社
-books = Book.objects.all()
-for book in books:
-    print(book.publisher.name)  # 额外 N 条查询
-
-# ✅ select_related 一次 JOIN 查询
-books = Book.objects.select_related("publisher")
-for book in books:
-    print(book.publisher.name)  # 无额外查询
-
-# ✅ 多层关系
-books = Book.objects.select_related("publisher", "publisher__country")
-
-# ✅ 只查需要的字段（延迟加载优化）
-books = Book.objects.select_related("publisher").only(
-    "title", "publisher__name"
-)
-```
-
-### prefetch_related（M2M / 反向 ForeignKey）
-
-```python
-# ❌ N+1: 每个作者查一次书
-authors = Author.objects.all()
-for author in authors:
-    print(author.books.all())  # 额外 N 条查询
-
-# ✅ prefetch_related 两条查询 + Python 合并
-authors = Author.objects.prefetch_related("books")
-for author in authors:
-    print(list(author.books.all()))  # 无额外查询
-
-# ✅ 嵌套 prefetch
-authors = Author.objects.prefetch_related(
-    "books",
-    "books__publisher",
-)
-
-# ✅ Prefetch 对象控制预查行为
-from django.db.models import Prefetch
-
-authors = Author.objects.prefetch_related(
-    Prefetch(
-        "books",
-        queryset=Book.objects.filter(published=True).only("title", "author_id"),
-        to_attr="published_books",
-    )
-)
-for author in authors:
-    print(author.published_books)  # 已过滤，存在 to_attr 中
-```
-
-### QuerySet 缓存误用
-
-```python
-# ❌ count() 后再迭代 —— 两次查询
-qs = Book.objects.all()
-count = qs.count()          # 查询 1: SELECT COUNT(*) — 不填充缓存
-titles = [b.title for b in qs]  # 查询 2: SELECT * — 重新评估
-
-# ✅ 既要对象又要数量时，用 len() 触发一次评估并复用缓存
-qs = Book.objects.all()
-count = len(qs)             # 查询 1: SELECT * — 全部加载并缓存
-titles = [b.title for b in qs]  # 复用缓存，无新查询
-
-# ✅ 如果需要多次迭代，先转 list
-books = list(Book.objects.all())  # 一次查询
-count = len(books)
-titles = [b.title for b in books]
-```
-
-### 切片/索引不填充缓存
-
-```python
-# ❌ 反复索引未评估的 QuerySet —— 每次都查库
-qs = Book.objects.all()
-qs[0]   # 查询 1: SELECT ... LIMIT 1
-qs[0]   # 查询 2 — 切片/索引不会填充缓存
-
-# ✅ 先整体评估，缓存保存所有行，之后索引走缓存
-qs = Book.objects.all()
-list(qs)    # SELECT * — 评估并缓存全部行
-qs[0]       # 走缓存，无查询
-qs[5]       # 走缓存，无查询
-
-# ✅ 只需要前 N 条时，切一次并转 list
-books = list(Book.objects.all()[:10])  # 一次查询：SELECT ... LIMIT 10
-first = books[0]
-rest = books[1:]   # 已是 Python list，无查询
-```
-
-### len() vs count()
-
-```python
-# ❌ len() 加载全部对象到内存
-total = len(Book.objects.all())  # SELECT * FROM book — 全表加载
-
-# ✅ count() 在数据库端计数
-total = Book.objects.count()  # SELECT COUNT(*) — 高效
-
-# ✅ 如果已经需要 QuerySet 结果，再用 len
-books = list(Book.objects.filter(published=True))
-total = len(books)  # 已在内存中，不需要额外查询
-```
-
-### if qs vs qs.exists()
-
-```python
-# ❌ if qs 加载全部记录
-qs = Book.objects.filter(author_id=author_id)
-if qs:  # SELECT * FROM book WHERE ... — 全部加载
-    return qs[0]
-
-# ✅ exists() 只检查是否有记录
-if Book.objects.filter(author_id=author_id).exists():
-    return Book.objects.filter(author_id=author_id).first()
-
-# ✅ 或者直接 get/first 判空
-book = Book.objects.filter(author_id=author_id).first()
-if book is not None:
-    return book
-```
-
----
-
-## Serializer 反模式
-
-### 排除敏感字段
-
-```python
-from rest_framework import serializers
-
-# ❌ __all__ 暴露所有字段，包括敏感数据
-class UserSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = User
-        fields = "__all__"  # 密码 hash、is_superuser 等全部暴露
-
-# ✅ 显式列出允许的字段
-class UserSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = User
-        fields = ["id", "username", "email", "first_name", "last_name"]
-
-# ✅ 使用 exclude 时也要注意
-class UserProfileSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = UserProfile
-        exclude = ["internal_notes", "admin_flags"]
-
-# ✅ 密码字段用 write_only
-class RegistrationSerializer(serializers.ModelSerializer):
-    password = serializers.CharField(write_only=True, min_length=8)
-
-    class Meta:
-        model = User
-        fields = ["id", "username", "email", "password"]
-
-    def create(self, validated_data):
-        user = User(**validated_data)
-        user.set_password(validated_data["password"])
-        user.save()
-        return user
-```
-
-### 缺少验证
-
-```python
-from rest_framework import serializers
-
-# ❌ 没有验证，信任所有输入
-class OrderSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Order
-        fields = ["quantity", "price", "discount"]
-
-# ✅ 字段级验证
-class OrderSerializer(serializers.ModelSerializer):
-    quantity = serializers.IntegerField(min_value=1, max_value=100)
-    price = serializers.DecimalField(max_digits=10, decimal_places=2, min_value=0)
-    discount = serializers.DecimalField(
-        max_digits=5, decimal_places=2, min_value=0, max_value=1, required=False
-    )
-
-    class Meta:
-        model = Order
-        fields = ["quantity", "price", "discount"]
-
-# ✅ 对象级验证
-class OrderSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Order
-        fields = ["quantity", "price", "discount"]
-
-    def validate(self, attrs):
-        if attrs.get("discount", 0) > 0.5 and attrs.get("quantity", 0) < 10:
-            raise serializers.ValidationError(
-                "Bulk discount requires minimum 10 items."
-            )
-        return attrs
-
-# ✅ 自定义字段验证方法
-class BookingSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Booking
-        fields = ["start_date", "end_date", "room"]
-
-    def validate_start_date(self, value):
-        if value < date.today():
-            raise serializers.ValidationError("Start date cannot be in the past.")
-        return value
-
-    def validate(self, attrs):
-        if attrs["end_date"] <= attrs["start_date"]:
-            raise serializers.ValidationError("End date must be after start date.")
-        return attrs
-```
-
-### 嵌套写入
-
-```python
-from rest_framework import serializers
-
-# ❌ 嵌套 Serializer 只读但没有实现 create/update
-class TagSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Tag
-        fields = ["id", "name"]
-
-class ArticleSerializer(serializers.ModelSerializer):
-    tags = TagSerializer(many=True)  # 嵌套写入会失败
-
-    class Meta:
-        model = Article
-        fields = ["id", "title", "tags"]
-
-# ✅ 方案 1: 嵌套只读 + PrimaryKeyRelatedField 写入
-class ArticleSerializer(serializers.ModelSerializer):
-    tags = TagSerializer(many=True, read_only=True)
-    tag_ids = serializers.PrimaryKeyRelatedField(
-        queryset=Tag.objects.all(),
-        many=True,
-        write_only=True,
-        source="tags",
-    )
-
-    class Meta:
-        model = Article
-        fields = ["id", "title", "tags", "tag_ids"]
-
-# ✅ 方案 2: 实现 create() 处理嵌套
-class ArticleSerializer(serializers.ModelSerializer):
-    tags = TagSerializer(many=True)
-
-    class Meta:
-        model = Article
-        fields = ["id", "title", "tags"]
-
-    def create(self, validated_data):
-        tags_data = validated_data.pop("tags")
-        article = Article.objects.create(**validated_data)
-        for tag_data in tags_data:
-            tag, _ = Tag.objects.get_or_create(**tag_data)
-            article.tags.add(tag)
-        return article
-
-    def update(self, instance, validated_data):
-        tags_data = validated_data.pop("tags", None)
-        instance = super().update(instance, validated_data)
-        if tags_data is not None:
-            instance.tags.clear()
-            for tag_data in tags_data:
-                tag, _ = Tag.objects.get_or_create(**tag_data)
-                instance.tags.add(tag)
-        return instance
-```
-
-### read_only_fields 遗漏
-
-```python
-from rest_framework import serializers
-
-# ❌ 计算字段和自动字段可被用户覆盖
-class CommentSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Comment
-        fields = ["id", "body", "author", "created_at", "updated_at"]
-        # created_at, updated_at, author 可被客户端篡改
-
-# ✅ 标记只读字段
-class CommentSerializer(serializers.ModelSerializer):
-    class Meta:
-        model = Comment
-        fields = ["id", "body", "author", "created_at", "updated_at"]
-        read_only_fields = ["author", "created_at", "updated_at"]
-
-# ✅ 在视图中设置只读字段（如当前用户）
-class CommentViewSet(viewsets.ModelViewSet):
-    serializer_class = CommentSerializer
-
-    def get_serializer_context(self):
-        context = super().get_serializer_context()
-        context["request"] = self.request
-        return context
-
-    def perform_create(self, serializer):
-        serializer.save(author=self.request.user)
-```
-
----
-
-## ViewSet 最佳实践
-
-### 选择正确的基类
-
-```python
-from rest_framework import viewsets
-
-# ❌ ModelViewSet 提供完整 CRUD，但只需要读取
-class TagViewSet(viewsets.ModelViewSet):
-    queryset = Tag.objects.all()
-    serializer_class = TagSerializer
-    # 暴露了 destroy, update, create — 标签不应被随意修改
-
-# ✅ 只读场景用 ReadOnlyModelViewSet
-class TagViewSet(viewsets.ReadOnlyModelViewSet):
-    queryset = Tag.objects.all()
-    serializer_class = TagSerializer
-    # 只提供 list 和 retrieve
-
-# ✅ 需要自定义操作时用 Mixin
-from rest_framework import mixins
-
-class TagViewSet(
-    mixins.ListModelMixin,
-    mixins.RetrieveModelMixin,
-    mixins.CreateModelMixin,
-    generics.GenericAPIView,
-):
-    queryset = Tag.objects.all()
-    serializer_class = TagSerializer
-```
-
-### 用户级数据范围限定
-
-```python
-from rest_framework import viewsets
-
-# ❌ 任何用户可以看到所有数据
-class DocumentViewSet(viewsets.ModelViewSet):
-    queryset = Document.objects.all()
-    serializer_class = DocumentSerializer
-
-# ✅ get_queryset 限定当前用户数据
-class DocumentViewSet(viewsets.ModelViewSet):
-    serializer_class = DocumentSerializer
-
-    def get_queryset(self):
-        return Document.objects.filter(
-            owner=self.request.user
-        ).select_related("owner")
-
-# ✅ 管理员看全部，普通用户看自己的
-class DocumentViewSet(viewsets.ModelViewSet):
-    serializer_class = DocumentSerializer
-
-    def get_queryset(self):
-        qs = Document.objects.select_related("owner")
-        if self.request.user.is_staff:
-            return qs
-        return qs.filter(owner=self.request.user)
-
-# ✅ perform_create 自动关联当前用户
-class DocumentViewSet(viewsets.ModelViewSet):
-    serializer_class = DocumentSerializer
-
-    def get_queryset(self):
-        return Document.objects.filter(owner=self.request.user)
-
-    def perform_create(self, serializer):
-        serializer.save(owner=self.request.user)
-```
-
-### 权限控制
-
-```python
-from rest_framework import permissions, viewsets
-
-# ❌ 没有权限控制
-class ArticleViewSet(viewsets.ModelViewSet):
-    queryset = Article.objects.all()
-    serializer_class = ArticleSerializer
-
-# ✅ 类级别权限
-class ArticleViewSet(viewsets.ModelViewSet):
-    queryset = Article.objects.all()
-    serializer_class = ArticleSerializer
-    permission_classes = [permissions.IsAuthenticated]
-
-# ✅ 操作级别权限
-from rest_framework.decorators import action
-
-class ArticleViewSet(viewsets.ModelViewSet):
-    queryset = Article.objects.all()
-    serializer_class = ArticleSerializer
-
-    def get_permissions(self):
-        if self.action in ("list", "retrieve"):
-            return [permissions.AllowAny()]
-        if self.action == "create":
-            return [permissions.IsAuthenticated()]
-        return [permissions.IsAdminUser()]
-
-# ✅ 自定义对象级权限
-class IsOwnerOrReadOnly(permissions.BasePermission):
-    def has_object_permission(self, request, view, obj):
-        if request.method in permissions.SAFE_METHODS:
-            return True
-        return obj.owner == request.user
-```
-
-### 分页和节流
-
-```python
-# settings.py
-
-# ❌ 没有分页和节流配置
-REST_FRAMEWORK = {
-    "DEFAULT_AUTHENTICATION_CLASSES": [
-        "rest_framework.authentication.SessionAuthentication",
-    ],
-}
-
-# ✅ 全局分页和节流
-REST_FRAMEWORK = {
-    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
-    "PAGE_SIZE": 20,
-    "DEFAULT_THROTTLE_CLASSES": [
-        "rest_framework.throttling.AnonRateThrottle",
-        "rest_framework.throttling.UserRateThrottle",
-    ],
-    "DEFAULT_THROTTLE_RATES": {
-        "anon": "100/hour",
-        "user": "1000/hour",
-    },
-}
-
-# ✅ 自定义分页器
-from rest_framework.pagination import PageNumberPagination
-
-class StandardPagination(PageNumberPagination):
-    page_size = 25
-    page_size_query_param = "page_size"
-    max_page_size = 100
-
-class ArticleViewSet(viewsets.ModelViewSet):
-    queryset = Article.objects.all()
-    serializer_class = ArticleSerializer
-    pagination_class = StandardPagination
-```
-
----
-
-## 异步视图
-
-### 同步 ORM 在异步视图中的正确使用
-
-```python
-import asyncio
-from asgiref.sync import sync_to_async
-from django.http import JsonResponse
-
-# ❌ 在 async 视图中直接调用同步 ORM — 阻塞事件循环
-async def user_list(request):
-    users = User.objects.all()  # Synchronous ORM call in async context!
-    data = [{"id": u.id, "name": u.username} for u in users]
-    return JsonResponse(data, safe=False)
-
-# ✅ 使用 async ORM（Django 4.1+）
-async def user_list(request):
-    users = User.objects.all()
-    data = []
-    async for user in users:  # async iteration
-        data.append({"id": user.id, "name": user.username})
-    return JsonResponse(data, safe=False)
-
-# ✅ 使用 aget / afilter / acreate
-async def user_detail(request, pk):
-    user = await User.objects.aget(pk=pk)
-    return JsonResponse({"id": user.id, "name": user.username})
-
-# ✅ 复杂查询用 sync_to_async
-@sync_to_async
-def get_user_with_profile(pk):
-    return User.objects.select_related("profile").get(pk=pk)
-
-async def user_profile(request, pk):
-    user = await get_user_with_profile(pk)
-    return JsonResponse({
-        "id": user.id,
-        "name": user.username,
-        "bio": user.profile.bio,
-    })
-```
-
-### 遗漏 await
-
-```python
-from django.http import JsonResponse
-
-# ❌ 忘记 await — coroutine 不会执行，返回协程对象而非数据
-async def user_detail(request, pk):
-    user = User.objects.aget(pk=pk)  # Missing await!
-    # user 是一个 coroutine 对象，不是 User 实例
-    return JsonResponse({"name": user.username})  # RuntimeError
-
-# ✅ 始终 await 异步 ORM 调用
-async def user_detail(request, pk):
-    user = await User.objects.aget(pk=pk)
-    return JsonResponse({"name": user.username})
-
-# ✅ 使用aget_or_404 的异步版本
-from django.shortcuts import aget_object_or_404
-
-async def user_detail(request, pk):
-    user = await aget_object_or_404(User, pk=pk)
-    return JsonResponse({"name": user.username})
-```
-
-### 异步视图中的事务
-
-```python
-from django.db import transaction
-from asgiref.sync import sync_to_async
-
-# ❌ transaction.atomic() 是同步的，不能直接在 async 中用
-async def create_order(request):
-    async with transaction.atomic():  # Error! Not async-compatible
-        order = await Order.objects.acreate(total=100)
-        await OrderItem.objects.acreate(order=order, product_id=1)
-    return JsonResponse({"order_id": order.id})
-
-# ✅ 用 sync_to_async 包装事务块
-@sync_to_async
-def _create_order_with_items():
-    with transaction.atomic():
-        order = Order.objects.create(total=100)
-        OrderItem.objects.create(order=order, product_id=1)
-        return order.id
-
-async def create_order(request):
-    order_id = await _create_order_with_items()
-    return JsonResponse({"order_id": order_id})
-
-# ✅ 多个操作打包到一个 sync_to_async 中
-@sync_to_async
-def _bulk_create_products(items):
-    with transaction.atomic():
-        products = Product.objects.bulk_create([Product(**i) for i in items])
-        return [p.id for p in products]
-
-async def import_products(request):
-    ids = await _bulk_create_products(request.data)
-    return JsonResponse({"ids": ids})
-```
-
-### 同步中间件拖慢异步性能
-
-```python
-# ❌ 同步中间件会把 async 视图降级为同步执行
-class TimingMiddleware:
-    def __init__(self, get_response):
-        self.get_response = get_response
-
-    def __call__(self, request):  # sync — blocks async views
-        start = time.time()
-        response = self.get_response(request)
-        elapsed = time.time() - start
-        response["X-Elapsed"] = str(elapsed)
-        return response
-
-# ✅ async-capable 中间件：async def __call__，并在 __init__ 里标记实例
-import time
-from asgiref.sync import iscoroutinefunction, markcoroutinefunction
-
-class TimingMiddleware:
-    async_capable = True
-    sync_capable = False
-
-    def __init__(self, get_response):
-        self.get_response = get_response
-        # get_response 是协程函数时标记自己，Django 才会 await 这个实例
-        if iscoroutinefunction(self.get_response):
-            markcoroutinefunction(self)
-
-    async def __call__(self, request):
-        start = time.time()
-        response = await self.get_response(request)
-        elapsed = time.time() - start
-        response["X-Elapsed"] = str(elapsed)
-        return response
-
-# ✅ 要同时兼容同步和异步，用工厂函数 + 内置装饰器
-from django.utils.decorators import sync_and_async_middleware
-```
-
-### async for 迭代模式
-
-```python
-from django.http import JsonResponse
-
-# ❌ 同步迭代大型 QuerySet 在 async 视图中阻塞
-async def export_users(request):
-    users = User.objects.all()
-    data = []  # 同步迭代阻塞事件循环
-    for user in users:
-        data.append({"id": user.id, "name": user.username})
-    return JsonResponse(data, safe=False)
-
-# ✅ 使用 async for 异步迭代
-async def export_users(request):
-    data = []
-    async for user in User.objects.all():
-        data.append({"id": user.id, "name": user.username})
-    return JsonResponse(data, safe=False)
-
-# ✅ 大数据集使用 aiterator() + 分块处理
-async def export_large_dataset(request):
-    data = []
-    async for user in User.objects.all().aiterator(chunk_size=500):
-        data.append({"id": user.id, "name": user.username})
-    return JsonResponse(data, safe=False)
-
-# ✅ 使用 values() 减少内存
-async def lightweight_export(request):
-    data = []
-    async for row in User.objects.values("id", "username"):
-        data.append(row)
-    return JsonResponse(data, safe=False)
-```
-
----
-
-## 中间件与设置
-
-### 生产安全配置清单
-
-```python
-# settings.py — 生产环境必须的安全设置
-
-# ❌ 开发默认值不应出现在生产环境
-DEBUG = True
-SECRET_KEY = "django-insecure-..."
-ALLOWED_HOSTS = ["*"]
-SECURE_SSL_REDIRECT = False
-
-# ✅ 生产环境安全配置
-
-# --- 基础安全 ---
-DEBUG = False
-SECRET_KEY = os.environ["DJANGO_SECRET_KEY"]  # 从环境变量读取
-ALLOWED_HOSTS = ["example.com", "www.example.com"]
-
-# --- HTTPS ---
-SECURE_SSL_REDIRECT = True          # HTTP 重定向到 HTTPS
-SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
-SESSION_COOKIE_SECURE = True
-CSRF_COOKIE_SECURE = True
-
-# --- 安全头 ---
-SECURE_HSTS_SECONDS = 31536000      # 1 year HSTS
-SECURE_HSTS_INCLUDE_SUBDOMAINS = True
-SECURE_HSTS_PRELOAD = True
-SECURE_CONTENT_TYPE_NOSNIFF = True   # X-Content-Type-Options: nosniff
-X_FRAME_OPTIONS = "DENY"             # 防止 clickjacking
-SECURE_REFERRER_POLICY = "strict-origin-when-cross-origin"
-
-# --- 密码验证 ---
-AUTH_PASSWORD_VALIDATORS = [
-    {"NAME": "django.contrib.auth.password_validation.MinimumLengthValidator",
-     "OPTIONS": {"min_length": 12}},
-    {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
-    {"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
-]
-
-# --- Session ---
-SESSION_COOKIE_AGE = 3600 * 8  # 8 hours
-SESSION_SAVE_EVERY_REQUEST = True
-SESSION_EXPIRE_AT_BROWSER_CLOSE = True
-```
-
-### 数据库连接安全
-
-```python
-# settings.py
-
-# ❌ 明文密码在代码中
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.postgresql",
-        "NAME": "mydb",
-        "USER": "admin",
-        "PASSWORD": "hunter2",  # 不要硬编码密码
-        "HOST": "localhost",
-        "PORT": "5432",
-    }
-}
-
-# ✅ 从环境变量读取
-DATABASES = {
-    "default": {
-        "ENGINE": "django.db.backends.postgresql",
-        "NAME": os.environ.get("DB_NAME", "mydb"),
-        "USER": os.environ.get("DB_USER", "mydb_user"),
-        "PASSWORD": os.environ["DB_PASSWORD"],
-        "HOST": os.environ.get("DB_HOST", "localhost"),
-        "PORT": os.environ.get("DB_PORT", "5432"),
-        "OPTIONS": {
-            "sslmode": "require",  # 强制 SSL 连接
-        },
-        "CONN_MAX_AGE": 60,  # 持久连接
-    }
-}
-```
-
-### CORS 配置
-
-```python
-# settings.py (using django-cors-headers)
-
-# ❌ 允许所有来源
-CORS_ALLOW_ALL_ORIGINS = True
-
-# ✅ 限制允许的来源
-CORS_ALLOWED_ORIGINS = [
-    "https://example.com",
-    "https://app.example.com",
-]
-
-# ✅ 生产环境 CORS 设置
-CORS_ALLOW_ALL_ORIGINS = False
-CORS_ALLOWED_ORIGINS = os.environ.get("CORS_ORIGINS", "").split(",")
-CORS_ALLOW_CREDENTIALS = True
-CORS_ALLOW_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
-CORS_ALLOW_HEADERS = [
-    "authorization",
-    "content-type",
-    "x-csrftoken",
-]
-```
-
-### 日志配置
-
-```python
-# settings.py
-
-# ❌ 默认日志配置（或不配置）
-LOGGING = {}
-
-# ✅ 生产环境日志配置
-LOGGING = {
-    "version": 1,
-    "disable_existing_loggers": False,
-    "formatters": {
-        "verbose": {
-            "format": "{levelname} {asctime} {module} {process:d} {thread:d} {message}",
-            "style": "{",
-        },
-    },
-    "handlers": {
-        "file": {
-            "level": "INFO",
-            "class": "logging.handlers.RotatingFileHandler",
-            "filename": "/var/log/django/app.log",
-            "maxBytes": 10 * 1024 * 1024,  # 10 MB
-            "backupCount": 5,
-            "formatter": "verbose",
-        },
-    },
-    "loggers": {
-        "django": {
-            "handlers": ["file"],
-            "level": "INFO",
-            "propagate": False,
-        },
-        "myapp": {
-            "handlers": ["file"],
-            "level": "DEBUG" if DEBUG else "INFO",
-            "propagate": False,
-        },
-    },
-}
-```
-
----
-
-## Review Checklist
-
-### 安全审查
-
-- [ ] 没有使用 `mark_safe` 渲染未转义的用户输入
-- [ ] CSRF 中间件已启用，没有 `@csrf_exempt`
-- [ ] Session 和 CSRF cookie 设置 `Secure`, `HttpOnly`, `SameSite`
-- [ ] SQL 查询使用参数化（ORM 或参数化 `raw()`），无字符串拼接
-- [ ] 文件上传有类型和大小限制
-- [ ] `SECRET_KEY` 从环境变量读取，不在代码仓库中
-- [ ] `DEBUG = False` 在生产环境
-
-### HTTPS 与安全头
-
-- [ ] `SECURE_SSL_REDIRECT = True`
-- [ ] `SECURE_HSTS_SECONDS` 已设置（≥ 31536000）
-- [ ] `SECURE_CONTENT_TYPE_NOSNIFF = True`
-- [ ] `X_FRAME_OPTIONS` 设置为 `DENY` 或 `SAMEORIGIN`
-- [ ] `ALLOWED_HOSTS` 不包含 `"*"`
-- [ ] 数据库连接使用 SSL
-
-### N+1 查询
-
-- [ ] ForeignKey 关系使用 `select_related`
-- [ ] M2M / 反向关系使用 `prefetch_related`
-- [ ] 没有在循环中访问关联对象
-- [ ] 使用 `count()` 代替 `len(queryset)` 做计数
-- [ ] 使用 `exists()` 代替 `if queryset` 做存在性检查
-- [ ] 大数据集使用 `only()` / `defer()` 或 `values()` 减少查询字段
-- [ ] 切片后的 QuerySet 不重复迭代
-
-### Serializer
-
-- [ ] 不使用 `fields = "__all__"` 在敏感模型上
-- [ ] 密码字段标记 `write_only=True`
-- [ ] 有字段级和对象级验证
-- [ ] 嵌套写入实现了 `create()` / `update()` 或使用 `read_only=True`
-- [ ] 计算字段和自动字段在 `read_only_fields` 中
-- [ ] Serializer 不包含不应被修改的字段
-
-### ViewSet
-
-- [ ] 只读场景使用 `ReadOnlyModelViewSet`
-- [ ] `get_queryset()` 限定当前用户数据范围
-- [ ] 设置了 `permission_classes`
-- [ ] 创建时用 `perform_create()` 自动设置 owner/author
-- [ ] 配置了分页（全局或 ViewSet 级别）
-- [ ] 配置了节流（throttling）
-
-### 异步视图
-
-- [ ] async 视图中不直接调用同步 ORM（用 `aget`/`afilter`/`sync_to_async`）
-- [ ] 所有异步调用都有 `await`
-- [ ] `transaction.atomic()` 用 `sync_to_async` 包装
-- [ ] 中间件标记 `async_capable = True` 以避免降级
-- [ ] 大型 QuerySet 使用 `async for` + `aiterator()`
-
-### 生产配置
-
-- [ ] `CORS_ALLOWED_ORIGINS` 不使用 `CORS_ALLOW_ALL_ORIGINS = True`
-- [ ] 密码验证器已配置（最小长度、常见密码检查）
-- [ ] Session 过期时间合理（`SESSION_COOKIE_AGE`）
-- [ ] 日志配置使用 RotatingFileHandler，不在生产环境输出到 stdout
-- [ ] 数据库连接使用 `CONN_MAX_AGE` 持久连接