开发规范
接口与路由
- API 前缀：
/api/v1 - Swagger：
/api/docs/swagger/
路由定义：config/urls.py
项目结构
youlai-django/
├── config/ # 项目配置
│ ├── settings/ # 环境配置
│ │ ├── base.py # 通用配置
│ │ ├── dev.py # 开发配置
│ │ └── prod.py # 生产配置
│ ├── urls.py # 全局路由
│ ├── wsgi.py # WSGI 入口
│ └── asgi.py # ASGI 入口
├── core/ # 公共基础能力
│ ├── viewsets/ # 基础视图集
│ ├── serializers/ # 基础序列化器
│ ├── permissions/ # 权限控制
│ └── ... # 其他（分页/过滤器/异常等）
├── system/ # 系统核心模块
│ ├── users/ # 用户管理
│ ├── roles/ # 角色管理
│ ├── menus/ # 菜单管理
│ └── ... # 其他（部门/字典/日志等）
├── platform/ # 平台能力模块
│ ├── auth/ # 认证模块
│ ├── codegen/ # 代码生成
│ └── files/ # 文件上传
├── scripts/ # 数据库脚本
├── manage.py # Django 管理入口
└── .env # 环境变量目录约定
| 目录 | 说明 |
|---|---|
config/ | 项目配置（settings/urls） |
core/ | 公共基础能力（异常/响应/工具） |
system/ | 系统管理模块（用户/角色/菜单） |
platform/ | 平台能力（认证/代码生成/文件） |
infra/ | 基础设施（日志/中间件） |
代码风格
遵循 PEP 8：
| 类型 | 命名风格 | 示例 |
|---|---|---|
| 类名 | UpperCamelCase | UserProfile |
| 函数/方法 | snake_case | get_user_by_id |
| 变量 | snake_case | user_name |
| 常量 | UPPER_SNAKE_CASE | MAX_PAGE_SIZE |
| 包/模块 | snake_case | user_views |
DRF 开发规约
架构分层
- ViewSet：处理 HTTP 请求，调用 Service/Serializer
- Serializer：数据序列化与校验
- Service：复杂业务逻辑抽取（可选）
- Model：数据模型定义，禁止写复杂业务逻辑
ViewSet 示例
python
from rest_framework import viewsets
from rest_framework.decorators import action
from django_filters.rest_framework import DjangoFilterBackend
class UserViewSet(viewsets.ModelViewSet):
queryset = User.objects.all()
serializer_class = UserSerializer
filter_backends = [DjangoFilterBackend]
filterset_class = UserFilter
@action(detail=False, methods=['get'])
def profile(self, request):
"""获取当前用户信息"""
user = request.user
serializer = self.get_serializer(user)
return Response(serializer.data)Serializer 示例
python
from rest_framework import serializers
from django.core.validators import MinLengthValidator
class UserSerializer(serializers.ModelSerializer):
class Meta:
model = User
fields = ['id', 'username', 'email', 'phone', 'status']
read_only_fields = ['id']
def validate_phone(self, value):
"""验证手机号"""
if not value.isdigit() or len(value) != 11:
raise serializers.ValidationError('手机号格式不正确')
return value统一响应
所有接口返回统一格式：
python
from core.response import success, error
# 成功响应
return success(data=result)
# 错误响应
return error('认证失败', code='A0001')响应格式：
json
{
"code": "00000",
"msg": "操作成功",
"data": { ... }
}参数校验
使用 Serializer 校验
python
class CreateUserSerializer(serializers.Serializer):
username = serializers.CharField(max_length=50)
password = serializers.CharField(min_length=6, max_length=20)
email = serializers.EmailField(required=False)
# 视图中使用
serializer = CreateUserSerializer(data=request.data)
if not serializer.is_valid():
return error(serializer.errors, code='A0400')异常处理
自定义异常
python
from core.exception import BusinessException
class BusinessException(Exception):
def __init__(self, code: str, message: str):
self.code = code
self.message = message
# 使用
raise BusinessException('A0001', '认证失败')全局异常处理
python
# core/exception.py
def exception_handler(exc, context):
if isinstance(exc, BusinessException):
return Response({
'code': exc.code,
'msg': exc.message,
'data': None
}, status=400)
return None接口幂等
- 优先使用数据库唯一约束
- 对高风险操作使用 Redis 分布式锁
python
from django.core.cache import cache
def create_order(request):
lock_key = f"lock:order:{request.user.id}"
lock = cache.add(lock_key, 1, 30)
if not lock:
return error('操作进行中，请勿重复提交', code='A0004')
try:
# 业务处理
pass
finally:
cache.delete(lock_key)数据库迁移
bash
# 生成迁移文件
python manage.py makemigrations
# 执行迁移
python manage.py migrate
# 初始导入 SQL 后
python manage.py migrate --fake-initial相关文件
| 文件 | 说明 |
|---|---|
core/response.py | 统一响应 |
core/exception.py | 异常处理 |
core/permissions/ | 权限控制 |
core/viewsets/ | 基础视图集 |