1. 为什么需要Django REST Framework项目模板
第一次用DRF（Django REST Framework）开发API接口时，我踩了无数坑：跨域问题没处理、权限配置混乱、Swagger文档缺失、分页参数不统一...每个新项目都要重新折腾一遍。直到后来整理出这套项目模板，开发效率直接翻倍。
这个模板不是简单的脚手架，而是集成了DRF最佳实践的完整解决方案。它默认包含：
- 开箱即用的JWT认证
- 自动化API文档生成
- 标准化的响应格式
- 预配置的CORS跨域支持
- 常用工具类封装
提示：模板基于Python 3.8+和Django 3.2+验证，完全遵循DRF官方推荐写法，避免了自己造轮子可能带来的兼容性问题。
2. 核心架构设计
2.1 项目目录结构
模板采用模块化设计，关键目录作用如下：
code复制project_template/
├── apps/ # 业务应用目录
│ ├── account/ # 用户认证模块
│ └── demo/ # 示例模块
├── config/ # 项目配置
│ ├── settings/ # 多环境配置
│ │ ├── base.py # 基础配置
│ │ ├── dev.py # 开发环境
│ │ └── prod.py # 生产环境
│ └── urls.py # 主路由
├── utils/ # 工具包
│ ├── exceptions.py # 自定义异常
│ ├── pagination.py # 分页器
│ └── response.py # 响应封装
└── manage.py
这种结构优势在于：
- 配置按环境分离，避免敏感信息泄露
- 业务代码隔离，方便功能扩展
- 公共组件集中管理，维护更高效
2.2 认证系统实现
模板默认采用JWT认证方案，关键配置在config/settings/base.py：
python复制REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework_simplejwt.authentication.JWTTokenUserAuthentication',
),
}
SIMPLE_JWT = {
'ACCESS_TOKEN_LIFETIME': timedelta(minutes=30),
'REFRESH_TOKEN_LIFETIME': timedelta(days=7),
'ROTATE_REFRESH_TOKENS': True # 刷新token时返回新refresh_token
}
注意：生产环境务必修改
SECRET_KEY，且不要将refresh_token有效期设置过长
3. 关键功能实现细节
3.1 统一响应格式
在utils/response.py中封装了标准响应：
python复制from rest_framework.response import Response
def APIResponse(code=200, message='success', data=None, **kwargs):
return Response({
'code': code,
'message': message,
'data': data,
**kwargs
}, status=code//100)
使用示例：
python复制class UserViewSet(viewsets.ModelViewSet):
def list(self, request):
queryset = self.get_queryset()
serializer = self.get_serializer(queryset, many=True)
return APIResponse(data=serializer.data)
这种封装使得前端处理响应时：
- 始终有明确的code/message字段
- 实际数据永远在data字段中
- 支持扩展额外字段
3.2 自动化API文档
通过drf-yasg实现Swagger文档自动生成：
- 安装依赖：
bash复制pip install drf-yasg
- 配置
config/urls.py：
python复制from drf_yasg import openapi
from drf_yasg.views import get_schema_view
schema_view = get_schema_view(
openapi.Info(title="API文档", default_version='v1'),
public=True,
)
urlpatterns = [
path('swagger/', schema_view.with_ui('swagger')),
]
访问/swagger/即可看到自动生成的交互式文档，支持：
- 接口在线测试
- 模型定义查看
- 认证token传递
4. 开发环境最佳实践
4.1 本地调试配置
推荐使用config/settings/dev.py配置：
python复制from .base import *
DEBUG = True
CORS_ALLOW_ALL_ORIGINS = True # 允许所有跨域请求
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': BASE_DIR / 'db.sqlite3',
}
}
启动命令建议：
bash复制python manage.py runserver --settings=config.settings.dev
4.2 常用开发工具
模板已预配置：
django-debug-toolbar- SQL查询分析django-extensions- 增强shell等工具black- 代码自动格式化
启用方式：
python复制# dev.py
INSTALLED_APPS += [
'debug_toolbar',
'django_extensions',
]
MIDDLEWARE.insert(0, 'debug_toolbar.middleware.DebugToolbarMiddleware')
5. 生产环境部署要点
5.1 安全配置
config/settings/prod.py必须包含：
python复制from .base import *
DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com']
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SECURE_HSTS_SECONDS = 31536000 # 强制HTTPS
5.2 性能优化建议
- 数据库连接池：
python复制DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql',
'CONN_MAX_AGE': 60, # 连接复用
}
}
- 静态文件处理：
bash复制python manage.py collectstatic
- 使用Gunicorn+Gevent：
bash复制gunicorn config.wsgi:application -w 4 -k gevent
6. 常见问题解决方案
6.1 跨域问题
尽管模板已配置django-cors-headers，但特殊场景可能需要：
python复制CORS_ALLOWED_ORIGINS = [
"https://example.com",
"http://localhost:8080",
]
CORS_ALLOW_METHODS = [
'GET',
'OPTIONS',
'PATCH',
'POST',
'DELETE',
]
6.2 分页器定制
默认分页器在utils/pagination.py：
python复制from rest_framework.pagination import PageNumberPagination
class StandardPagination(PageNumberPagination):
page_size = 20
page_size_query_param = 'page_size'
max_page_size = 100
视图中使用：
python复制class BookViewSet(viewsets.ModelViewSet):
pagination_class = StandardPagination
6.3 数据库迁移冲突
当多人开发出现迁移冲突时：
bash复制# 查看冲突
python manage.py showmigrations
# 重置迁移（开发环境）
find . -path "*/migrations/*.py" -not -name "__init__.py" -delete
python manage.py makemigrations
这套模板经过5个以上生产项目验证，平均节省40%的初期开发时间。最新版本特别优化了：
- 异步任务支持（Celery+Django）
- 更完善的单元测试框架
- 自动化部署脚本（Docker+K8S）
实际使用中建议根据团队规范调整代码风格，但核心架构已经覆盖了DRF项目的大多数痛点需求。