【后端】【django drf】Django DRF API 编写规范(程序设计规则)

Django DRF API 编写规范(程序设计规则)

为了确保 Django DRF 代码的可维护性、可扩展性和高质量,API 设计不仅要符合 RESTful 规范,还需要遵循一定的程序设计规则。以下是一些关键的编写规范,以保证代码的清晰性、可读性和稳定性。


一、代码组织与结构

(一)项目目录结构

建议遵循 Django 的最佳实践,将 API 代码模块化,保持清晰的层次结构:

复制代码
my_project/
│── my_app/
│   │── models.py          # 数据模型
│   │── serializers.py     # 序列化器
│   │── views.py          # 视图
│   │── urls.py           # 路由
│   │── permissions.py    # 权限
│   │── paginations.py    # 分页
│   │── filters.py        # 过滤器
│   │── services.py       # 业务逻辑
│   └── tests/            # 单元测试
│── config/
│   │── settings.py       # 项目配置
│   │── urls.py           # 主路由
│── manage.py
  • models.py:定义数据库模型
  • serializers.py:定义数据序列化逻辑
  • views.py:编写 API 逻辑
  • permissions.py:自定义权限
  • paginations.py:自定义分页逻辑
  • filters.py:定义过滤器
  • services.py:封装业务逻辑,避免视图代码膨胀
  • tests/:单元测试,提高代码质量

二、视图层规范

(一)优先使用 ViewSet

避免 APIView,尽可能使用 ModelViewSet 来减少代码重复:

python 复制代码
from rest_framework.viewsets import ModelViewSet
from .models import User
from .serializers import UserSerializer

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

如果 ViewSet 过重,可以拆分逻辑到 services.py,避免过多业务逻辑混杂在视图层。

(二)限制 ViewSet 的 HTTP 方法

如果某个 ViewSet 只需要支持部分 HTTP 方法,应在 viewset 里限制:

python 复制代码
class UserViewSet(ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    http_method_names = ['get', 'post', 'patch', 'delete']

三、序列化器(Serializers)规范

(一)使用 ModelSerializer

尽可能使用 ModelSerializer,减少重复代码:

python 复制代码
from rest_framework import serializers
from .models import User

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "email", "created_at"]

(二)避免 serializers.Serializer 直接定义字段

除非是特殊业务数据结构,否则不推荐手写字段:

python 复制代码
# ❌ 不推荐
class CustomSerializer(serializers.Serializer):
    username = serializers.CharField()
    email = serializers.EmailField()

尽量使用 ModelSerializer 直接绑定模型,减少维护成本。

(三)字段验证逻辑放在 validate_xxx

python 复制代码
class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ["id", "username", "email"]

    def validate_email(self, value):
        if "spam" in value:
            raise serializers.ValidationError("Email contains spam content")
        return value

四、业务逻辑拆分(Services 层)

为了避免 views.py 代码过于庞大,建议将业务逻辑封装到 services.py

python 复制代码
# services.py
def create_user(username, email):
    if User.objects.filter(email=email).exists():
        raise ValueError("Email already exists")
    return User.objects.create(username=username, email=email)

然后在 views.py 里调用:

python 复制代码
from .services import create_user

class UserViewSet(ModelViewSet):
    ...
    def perform_create(self, serializer):
        create_user(serializer.validated_data["username"], serializer.validated_data["email"])

五、权限控制(Permissions)

(一)尽可能使用 permissions.py 单独管理权限

避免直接在 views.py 里写权限判断,而是使用 Django DRF 的 permissions 机制:

python 复制代码
from rest_framework.permissions import BasePermission

class IsAdminUserOrReadOnly(BasePermission):
    def has_permission(self, request, view):
        if request.method in ['GET']:
            return True
        return request.user and request.user.is_staff

然后在 views.py 里使用:

python 复制代码
class UserViewSet(ModelViewSet):
    permission_classes = [IsAdminUserOrReadOnly]

六、查询优化

避免 N+1 查询:

python 复制代码
class UserViewSet(ModelViewSet):
    queryset = User.objects.select_related("profile").all()

(二)使用分页减少数据库压力

配置全局分页:

python 复制代码
REST_FRAMEWORK = {
    'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
    'PAGE_SIZE': 10
}

七、异常处理

(一)全局异常处理

exception_handler.py 里统一管理异常:

python 复制代码
from rest_framework.views import exception_handler

def custom_exception_handler(exc, context):
    response = exception_handler(exc, context)
    if response is not None:
        response.data = {
            "code": response.status_code,
            "message": response.data.get("detail", "An error occurred")
        }
    return response

settings.py 里配置:

python 复制代码
REST_FRAMEWORK = {
    'EXCEPTION_HANDLER': 'my_app.exception_handler.custom_exception_handler'
}

八、单元测试(Tests)

(一)测试 API 逻辑

编写 pytest 测试,确保 API 可用:

python 复制代码
import pytest
from rest_framework.test import APIClient

@pytest.mark.django_db
def test_create_user():
    client = APIClient()
    response = client.post("/api/users/", {"username": "john", "email": "[email protected]"})
    assert response.status_code == 201

(二)覆盖率标准

使用 pytest 运行测试,并确保代码覆盖率:

bash 复制代码
pytest --cov=my_app

总结

  1. 遵循 Django 项目目录结构,保持模块化设计
  2. 使用 ViewSet 处理 API 逻辑,并限制 HTTP 方法
  3. 优先使用 ModelSerializer,避免重复字段定义
  4. 业务逻辑拆分到 services.py,避免 views.py 代码过重
  5. 权限控制统一放在 permissions.py,避免手写权限逻辑
  6. 使用 select_relatedprefetch_related 进行查询优化
  7. 使用 custom_exception_handler 统一异常处理
  8. 编写 pytest 单元测试,确保代码稳定

通过这些规则,可以提升 Django DRF API 的可维护性、扩展性和高效性,使代码更加清晰易读。

相关推荐
前端开发张小七1 分钟前
Python 学习总结-2
python
蜡笔小新..7 分钟前
开发、科研、日常办公工具汇总(自用,持续更新)
论文阅读·人工智能·python·插件·zotero
发财哥fdy14 分钟前
3.12-3 html
人工智能·python·tensorflow
斯密码赛我是美女23 分钟前
日志Python安全之SSTI——Flask/Jinja2
后端·python·flask
YuiGod33 分钟前
《从零开始DeepSeek R1搭建本地知识库问答系统》六:关于聊天模型 API Key 的使用与调用 Embedding 模型
python·langchain·deepseek
柳如烟@42 分钟前
docker python:latest镜像 允许ssh远程
python·docker·ssh
bryant_meng1 小时前
【python】OpenCV—Hough Circle Transform
开发语言·python·opencv·hough·圆形检测
chen丶21 小时前
搭建基于flask的web应用框架
python·flask
梦想画家2 小时前
使用Python Seaborn创建热力图:从核心概念到实战案例
python·信息可视化
Nice2cu_Code2 小时前
Python教程(三):类&对象、闭包、装饰器、类型注解、MRO
开发语言·python