1
RESTful 设计原则：
2
1. 资源用名词，不用动词：/users ✅  /getUser ❌
3
2. 用 HTTP 方法表达操作：GET 查、POST 增、PUT/PATCH 改、DELETE 删
4
3. URL 表示资源层级：/users/1/posts（用户1的文章）
5
4. 无状态：每个请求自带全部信息（认证），服务器不存会话状态
6
5. 用 JSON 作为数据交换格式

1
# 序列化（对象 → JSON）：many=True 处理多条
2
posts = Post.objects.all()
3
serializer = PostSerializer(posts, many=True)
4
print(serializer.data)        # [{'id':1,'title':'...',...}, ...]
5

6
# 反序列化（JSON → 对象）：需校验
7
serializer = PostSerializer(data={"title": "新文章", "content": "..."})
8
if serializer.is_valid():                 # 校验数据
9
    serializer.save()                     # 创建对象
10
else:
11
    print(serializer.errors)              # 校验失败的错误信息
12

13
# 更新（传入 instance）
14
post = Post.objects.get(id=1)
15
serializer = PostSerializer(post, data={"title": "改标题"}, partial=True)  # partial 局部更新
16
if serializer.is_valid():
17
    serializer.save()

1
class PostSerializer(serializers.ModelSerializer):
2
    # 自定义校验：校验单个字段 validate_<字段名>
3
    def validate_title(self, value):
4
        if "敏感词" in value:
5
            raise serializers.ValidationError("标题含敏感词")
6
        return value
7

8
    # 全局校验：跨字段验证
9
    def validate(self, attrs):
10
        if attrs.get("start") and attrs.get("end"):
11
            if attrs["start"] > attrs["end"]:
12
                raise serializers.ValidationError("开始时间不能晚于结束时间")
13
        return attrs
14

15
    class Meta:
16
        model = Post
17
        fields = "__all__"

1
APIView（最基础，手写 get/post）
2
   └── GenericAPIView（增加 queryset/serializer_class）
3
          └── Mixin + GenericAPIView（组合出增删改查）
4
                 └── ViewSet（按 action 组织，配合 Router 自动生成路由）
5
                        └── ModelViewSet（一站式 CRUD）

1
from rest_framework import generics, mixins
2

3
# 列表 + 创建
4
class PostList(mixins.ListModelMixin, mixins.CreateModelMixin,
5
               generics.GenericAPIView):
6
    queryset = Post.objects.all()
7
    serializer_class = PostSerializer
8

9
    def get(self, request, *args, **kwargs):
10
        return self.list(request, *args, **kwargs)
11
    def post(self, request, *args, **kwargs):
12
        return self.create(request, *args, **kwargs)
13

14
# 更简洁：直接用封装好的通用视图
15
from rest_framework.generics import ListCreateAPIView, RetrieveUpdateDestroyAPIView
16

17
class PostListCreate(ListCreateAPIView):        # 列表 + 创建
18
    queryset = Post.objects.all()
19
    serializer_class = PostSerializer
20

21
class PostDetail(RetrieveUpdateDestroyAPIView): # 详情 + 改 + 删
22
    queryset = Post.objects.all()
23
    serializer_class = PostSerializer

1
from rest_framework import viewsets
2
from .models import Post
3
from .serializers import PostSerializer
4

5
# ModelViewSet 一站式提供 list/create/retrieve/update/partial_update/destroy
6
class PostViewSet(viewsets.ModelViewSet):
7
    queryset = Post.objects.all()
8
    serializer_class = PostSerializer
9

10
    # 自定义 action（额外接口）
11
    from rest_framework.decorators import action
12
    @action(detail=True, methods=["post"])     # detail=True 针对单个对象
13
    def publish(self, request, pk=None):
14
        post = self.get_object()
15
        post.is_published = True
16
        post.save()
17
        return Response({"status": "已发布"})
18
    # 访问 /api/posts/1/publish/

1
JWT 流程：
2
1. 用户 POST /api/token/ 提交账号密码 → 服务器返回 access + refresh token
3
2. 后续请求在头部带上：Authorization: Bearer <access_token>
4
3. access 过期后用 refresh token 换新的 access
5
4. JWT 无状态，服务器不存 session，适合分布式

1
from rest_framework.permissions import IsAuthenticated, IsAdminUser, BasePermission
2

3
# 内置权限类
4
# AllowAny         任何人可访问
5
# IsAuthenticated  仅登录用户
6
# IsAdminUser      仅管理员
7
# IsAuthenticatedOrReadOnly  登录可写，未登录只读
8

9
class PostViewSet(viewsets.ModelViewSet):
10
    queryset = Post.objects.all()
11
    serializer_class = PostSerializer
12
    permission_classes = [IsAuthenticatedOrReadOnly]   # 应用权限
13

14
# 自定义权限：只有作者能改自己的文章
15
class IsAuthorOrReadOnly(BasePermission):
16
    def has_object_permission(self, request, view, obj):
17
        if request.method in ("GET", "HEAD", "OPTIONS"):
18
            return True                       # 读操作放行
19
        return obj.author == request.user     # 写操作需是作者

1
# settings.py 全局配置
2
REST_FRAMEWORK = {
3
    "DEFAULT_PAGINATION_CLASS": "rest_framework.pagination.PageNumberPagination",
4
    "PAGE_SIZE": 10,
5
}
6

7
# 响应格式：
8
# { "count": 100, "next": "...", "previous": null, "results": [...] }
9

10
# 自定义分页类
11
from rest_framework.pagination import PageNumberPagination, LimitOffsetPagination
12

13
class MyPagination(PageNumberPagination):
14
    page_size = 10
15
    page_size_query_param = "size"      # 允许客户端指定每页数量 ?size=20
16
    max_page_size = 100

1
import django_filters
2
from .models import Post
3

4
class PostFilter(django_filters.FilterSet):
5
    title = django_filters.CharFilter(lookup_expr="icontains")   # 模糊
6
    min_views = django_filters.NumberFilter(field_name="views", lookup_expr="gte")
7

8
    class Meta:
9
        model = Post
10
        fields = ["category", "is_published"]
11

12
class PostViewSet(viewsets.ModelViewSet):
13
    queryset = Post.objects.all()
14
    serializer_class = PostSerializer
15
    filter_backends = [DjangoFilterBackend, SearchFilter, OrderingFilter]
16
    filterset_class = PostFilter                 # 精确/自定义过滤
17
    search_fields = ["title", "content"]         # ?search=关键词
18
    ordering_fields = ["views", "created_at"]    # ?ordering=-views

1
# settings.py：防止接口被刷
2
REST_FRAMEWORK = {
3
    "DEFAULT_THROTTLE_CLASSES": [
4
        "rest_framework.throttling.AnonRateThrottle",   # 匿名用户
5
        "rest_framework.throttling.UserRateThrottle",   # 登录用户
6
    ],
7
    "DEFAULT_THROTTLE_RATES": {
8
        "anon": "100/hour",        # 匿名每小时 100 次
9
        "user": "1000/day",        # 用户每天 1000 次
10
    },
11
}
12
# 超限返回 429 Too Many Requests

1
用户 → Nginx（反向代理/静态文件/负载均衡）
2
         ├── 静态文件（css/js/img）直接返回
3
         └── 动态请求 → Gunicorn/uWSGI（WSGI 服务器）→ Django 应用 → 数据库

1
server {
2
    listen 80;
3
    server_name example.com;
4

5
    # 静态文件由 Nginx 直接处理（高性能）
6
    location /static/ {
7
        alias /path/to/mysite/static/;
8
    }
9

10
    # 动态请求转发给 Gunicorn
11
    location / {
12
        proxy_pass http://127.0.0.1:8000;
13
        proxy_set_header Host $host;
14
        proxy_set_header X-Real-IP $remote_addr;
15
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
16
    }
17
}

1
□ settings.py 中 DEBUG = False（生产必关！否则泄露敏感信息）
2
□ 配置 ALLOWED_HOSTS = ['example.com', 'www.example.com']
3
□ 用环境变量管理 SECRET_KEY、数据库密码（不硬编码）
4
□ python manage.py collectstatic 收集静态文件
5
□ 生产数据库用 PostgreSQL/MySQL，不用 SQLite
6
□ 配置 HTTPS（Let's Encrypt 免费证书）
7
□ 用 systemd / supervisor 守护 Gunicorn 进程
8
□ 配置数据库定时备份
9
□ 开启日志监控（错误告警）