Django REST Framework 后端开发规范
触发条件
- Develop Django projects
- Implement REST APIs
- Use DRF ViewSets and Serializers
- Implement JWT authentication
- Implement permission control
Part 1: 技术栈
| 层 | 选型 | 说明 |
|---|
| 运行环境 | Python 3.11+ | 类型注解增强 |
| Web 框架 | Django 4.2+ | 全栈框架、ORM 内置 |
| REST API | Django REST Framework (DRF) | ViewSet、Serializer、认证 |
| 数据库 | MySQL 8.x (mysqlclient) | InnoDB 引擎 |
| 缓存 | Redis 7.x (django-redis) | 分布式缓存 |
| 认证 | PyJWT + DRF Authentication | Token 签发/验签 |
| API 文档 | drf-spectacular | OpenAPI 3.0 自动生成 |
Part 2: 目录结构
project/
├── apps/ # 应用模块
│ ├── system/ # 系统管理（Django App）
│ │ ├── users/ # 用户管理（models, serializers, views, urls, filters）
│ │ ├── roles/ # 角色管理
│ │ ├── menus/ # 菜单管理
│ │ ├── dept/ # 部门管理
│ │ ├── dicts/ # 字典管理
│ │ ├── configs/ # 系统配置
│ │ ├── notices/ # 通知公告
│ │ ├── logs/ # 日志管理
│ │ └── utils/ # decorators, exception_handler, rate_limit
│ ├── auth/ # 认证模块
│ │ ├── views.py, serializers.py, urls.py
│ │ ├── utils/ # jwt_authentication, redis_token_authentication
│ │ └── models/ # user_session, user_social
│ ├── codegen/ # 代码生成器（models, views, urls, templates/）
│ ├── file/ # 文件管理
│ └── message/ # 消息模块（SSE）
├── core/ # 公共模块
│ ├── response.py # 统一响应 + 分页
│ ├── viewsets.py # ViewSet 基类
│ ├── serializers.py # Serializer 基类
│ ├── exceptions/ # BusinessException + 全局处理器
│ ├── permissions/ # 接口权限 + 数据权限
│ └── middleware/ # rate_limit, request_context
├── config/ # 项目配置
│ ├── settings/{base,dev,prod}.py
│ ├── urls.py # 根路由
│ └── env.py
├── sql/mysql/youlai_admin_django.sql
├── manage.py
└── requirements.txt
设计原则：
core/ 是公共基础设施，被所有 App 共享，不依赖业务 Appapps/ 中每 App 按实体分子模块（user/role/menu），每子模块含 models/serializers/views/urls/filters- ViewSet + Serializer 是标准模式，复杂业务逻辑抽到
services.py
Part 3: 命名规范
3.1 文件命名
| 类型 | 规范 | 示例 |
|---|
| 模块目录 | 小写复数 | users/, roles/, menus/ |
| 模型 | models.py | apps/system/users/models.py |
| Serializer | serializers.py | 同上 |
| 视图 | views.py | 同上 |
| 路由 | urls.py | 同上 |
| 过滤器 | filters.py | 同上 |
3.2 类命名
| 类型 | 规范 | 示例 |
|---|
| 模型 | PascalCase，Sys 前缀 | SysUser, SysRole, SysMenu |
| Serializer | 功能 + Serializer | UserSerializer, UserFormSerializer |
| ViewSet | 功能 + ViewSet | UserViewSet |
| Filter | 功能 + Filter | UserFilter |
3.3 方法命名
| 动作 | DRF 内置方法 | 自定义 action |
|---|
| 查询列表 | list() | page() |
| 查询详情 | retrieve() | — |
| 新增 | create() | — |
| 更新 | update() | — |
| 删除 | destroy() | — |
| 批量删除 | — | batch() |
| 下拉选项 | — | options() |
3.4 变量命名
| 类型 | 规范 | 示例 |
|---|
| 变量 | snake_case | user_list |
| 常量 | UPPER_SNAKE_CASE | MAX_PAGE_SIZE |
| 私有方法 | _ 前缀 | _parse_date() |
| 布尔值 | is_/has_ 前缀 | is_deleted, has_permission |
Part 4: RESTful API 规范
4.1 标准 CRUD 路径
| 操作 | 方法 | 路径 |
|---|
| 分页列表 | GET | /api/v1/users/page/ |
| 详情 | GET | /api/v1/users/{id}/ |
| 新增 | POST | /api/v1/users/ |
| 更新 | PUT | /api/v1/users/{id}/ |
| 删除 | DELETE | /api/v1/users/{id}/ |
| 批量删除 | DELETE | /api/v1/users/batch/ |
| 下拉选项 | GET | /api/v1/users/options/ |
4.2 ViewSet 模板
@extend_schema(tags=["用户管理"])
class UserViewSet(ModelViewSet):
queryset = SysUser.objects.all()
serializer_class = UserSerializer
filterset_class = UserFilter
permission_classes = [HasPermission]
@extend_schema(summary="用户分页列表")
@action(detail=False, methods=["get"])
def page(self, request):
queryset = self.filter_queryset(self.get_queryset())
page = self.paginate_queryset(queryset)
return page_result(self.get_serializer(page, many=True).data, self.paginator.count)
@extend_schema(summary="新增用户")
def create(self, request, *args, **kwargs):
serializer = UserFormSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
user = serializer.save()
return success_result({"id": user.id})
@extend_schema(summary="更新用户")
def update(self, request, *args, **kwargs):
instance = self.get_object()
serializer = UserFormSerializer(instance, data=request.data)
serializer.is_valid(raise_exception=True)
serializer.save()
return success_result()
@extend_schema(summary="删除用户")
def destroy(self, request, *args, **kwargs):
self.get_object().delete()
return success_result()
Part 5: 响应格式与异常处理
5.1 统一响应
def success_result(data=None, msg="操作成功"):
return Response({"code": 200, "msg": msg, "data": data})
def page_result(list_data, total, msg="操作成功"):
return Response({"code": 200, "msg": msg, "data": {"list": list_data, "total": total}})
def error_result(code=400, msg="操作失败", data=None):
return Response({"code": code, "msg": msg, "data": data})
5.2 业务异常
from rest_framework.exceptions import APIException
class BusinessException(APIException):
status_code = 200 # 统一 200，业务码在 body 中
default_detail = "业务异常"
default_code = 400
def __init__(self, detail=None, code=400):
self.detail = detail or self.default_detail
self.code = code
5.3 全局异常处理
class GlobalExceptionHandler:
def __call__(self, exc, context):
if isinstance(exc, BusinessException):
return error_result(code=exc.code, msg=str(exc.detail))
if isinstance(exc, APIException):
return error_result(code=exc.status_code, msg=str(exc.detail))
return error_result(code=500, msg="系统异常")
Part 6: 模型规范
class BaseModel(models.Model):
id = models.BigAutoField(primary_key=True)
create_time = models.DateTimeField(auto_now_add=True, verbose_name="创建时间")
update_time = models.DateTimeField(auto_now=True, verbose_name="更新时间")
is_deleted = models.BooleanField(default=False, verbose_name="是否删除")
class Meta:
abstract = True
def delete(self, *args, **kwargs):
"""逻辑删除。"""
self.is_deleted = True
self.save()
class SysUser(BaseModel):
username = models.CharField(max_length=50, unique=True, verbose_name="用户名")
password = models.CharField(max_length=100, verbose_name="密码")
nickname = models.CharField(max_length=50, verbose_name="昵称")
mobile = models.CharField(max_length=20, blank=True, verbose_name="手机号")
status = models.SmallIntegerField(default=1, verbose_name="状态")
dept = models.ForeignKey("SysDept", on_delete=models.SET_NULL, null=True, verbose_name="部门")
class Meta:
db_table = "sys_user"
Part 7: Serializer 规范
class UserSerializer(serializers.ModelSerializer):
"""用户 VO 序列化器。"""
class Meta:
model = SysUser
fields = ["id", "username", "nickname", "mobile", "email", "status", "create_time"]
class UserFormSerializer(serializers.ModelSerializer):
"""用户表单序列化器。"""
class Meta:
model = SysUser
fields = ["id", "username", "password", "nickname", "mobile", "email", "status", "dept"]
def validate_username(self, value):
if SysUser.objects.filter(username=value, is_deleted=False).exclude(
id=self.instance.id if self.instance else None).exists():
raise serializers.ValidationError("用户名已存在")
return value
def create(self, validated_data):
validated_data["password"] = bcrypt.hashpw(validated_data["password"])
return super().create(validated_data)
Part 8: 认证规范
8.1 JWT 认证
class JWTAuthentication(BaseAuthentication):
def authenticate(self, request):
token = request.META.get("HTTP_AUTHORIZATION", "").replace("Bearer ", "")
if not token:
return None
try:
payload = jwt.decode(token, settings.JWT_SECRET, algorithms=["HS256"])
except jwt.ExpiredSignatureError:
raise AuthenticationFailed("Token 已过期")
except jwt.InvalidTokenError:
raise AuthenticationFailed("无效 Token")
user = SysUser.objects.get(id=payload["sub"], is_deleted=False)
return (user, token)
8.2 权限类
class HasPermission(BasePermission):
def has_permission(self, request, view):
required = getattr(view, "required_permissions", [])
if not required:
return True
return any(p in request.user.permissions for p in required)
Part 9: 注释规范
- docstring 优先：所有公共类、方法必须有 docstring
- 中文优先：专有名词保留英文，解释用中文
class UserViewSet(ModelViewSet):
"""用户管理 ViewSet。
提供用户分页查询、增删改查、下拉选项等接口。
所有接口（除 options 外）需认证。
"""
@action(detail=False, methods=["get"])
def page(self, request):
"""用户分页列表。
Args:
request: DRF Request 对象，Query 参数含 pageNum/pageSize/keywords/status。
Returns:
Response: {"code": 200, "data": {"list": [...], "total": int}}
"""
...
Part 10: 代码质量检查清单
常见反模式
| 反模式 | 正确做法 |
|---|
return Response(data) 直接返回 | 用 success_result(data) 统一封装 |
try/except Exception: pass | 抛出 BusinessException 或记录日志 |
User.objects.get(id=id) 无异常处理 | 捕获 DoesNotExist → 抛出 BusinessException |
| 在 View 中写复杂业务逻辑 | 抽到 Model Manager 或 services.py |
request.data["key"] 无校验 | 走 Serializer is_valid(raise_exception=True) |
