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

server/2025/3/16 19:11:24/

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 UserSerializerclass 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 = UserSerializerhttp_method_names = ['get', 'post', 'patch', 'delete']

三、序列化器(Serializers)规范

(一)使用 ModelSerializer

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

python">from rest_framework import serializers
from .models import Userclass UserSerializer(serializers.ModelSerializer):class Meta:model = Userfields = ["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 = Userfields = ["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_userclass 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 BasePermissionclass IsAdminUserOrReadOnly(BasePermission):def has_permission(self, request, view):if request.method in ['GET']:return Truereturn request.user and request.user.is_staff

然后在 views.py 里使用:

python">class UserViewSet(ModelViewSet):permission_classes = [IsAdminUserOrReadOnly]

六、查询优化

(一)使用 select_relatedprefetch_related

避免 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_handlerdef 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": "john@example.com"})assert response.status_code == 201

(二)覆盖率标准

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

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 的可维护性、扩展性和高效性,使代码更加清晰易读。


http://www.ppmy.cn/server/175501.html

相关文章

力扣 11.盛水最多的容器(双指针)

11. 盛最多水的容器 - 力扣&#xff08;LeetCode&#xff09; 代码区&#xff1a; class Solution { public:int maxArea(vector<int>& height) {//双指针int left 0,rightheight.size()-1;int maxarea0;while(left<right){maxareamax(maxarea,(right-left)*min(…

2024年12月CCF-GESP编程能力等级认证C++编程一级真题解析

一级真题的难度: ‌ CCF-GESP编程能力等级认证C++编程一级真题的难度适中‌。这些真题主要考察的是C++编程的基础知识、基本语法以及简单的算法逻辑。从搜索结果中可以看到,真题内容包括了选择题、编程题等题型,涉及的内容如C++表达式的计算、基本输入输出语句的理解…

Java多线程与高并发专题——原子类和 volatile、synchronized 有什么异同?

原子类和 volatile异同 首先&#xff0c;通过我们对原子类和的了解&#xff0c;原子类和volatile 都能保证多线程环境下的数据可见性。在多线程程序中&#xff0c;每个线程都有自己的工作内存&#xff0c;当多个线程访问共享变量时&#xff0c;可能会出现一个线程修改了共享变…

【设计模式】遍历集合的艺术:深入探索迭代器模式的无限可能

概述 定义&#xff1a;提供一个对象来顺序访问聚合对象中的一系列数据&#xff0c;而不暴露聚合对象的内部表示。 结构 迭代器模式主要包含以下角色&#xff1a; 抽象聚合&#xff08;Aggregate&#xff09;角色&#xff1a;定义存储、添加、删除聚合元素以及创建迭代器对象…

Jump Desktop for Mac v9.0.94 优秀的远程桌面连接工具 支持M、Intel芯片

Jump Desktop for Mac 版是macOS平台上的一款远程控制程序&#xff0c;支持Windows和Mac 双平台&#xff0c;通过邮件关联即可帮助设备自动找到桌面并进行操作。 应用介绍 Jump Desktop for Mac 是一款Mac上非常强大和易用的远程桌面控制软件&#xff0c;支持RDP、VNC协议&am…

Windows-PyQt5安装+PyCharm配置QtDesigner + QtUIC

个人环境 Windows 11 pycharm 2024.2 Anaconda2024.6python 3.9 1)先使用pip命令在线安装 1)pip install PyQt5 2)pip install PyQt5-tools2)配置环境变量 1&#xff1a;安装成功后可以在python的安装目录Lib\site-packahes目录下看到安装包。比如我的路径是E:\anaconda3…

[Failed to change to remote directory [D:/web/]]

这里写自定义目录标题 jenkins使用 Publish Over SSH发布到 windows服务器报错&#xff1a; Failed to connect and initialize SSH connection. Message: [Failed to change to remote directory [D:/web/]] 解决办法 将远程目录改为 /D:/web/

export、export default 和 module.exports 深度解析

文章目录 1. 模块系统概述1.1 模块系统对比1.2 模块加载流程 2. ES Modules2.1 export 使用2.2 export default 使用2.3 混合使用 3. CommonJS3.1 module.exports 使用3.2 exports 使用 4. 对比分析4.1 语法对比4.2 使用场景 5. 互操作性5.1 ES Modules 中使用 CommonJS5.2 Com…