基于 Django 构建 RESTful WebAPI 项目实战
Django 作为 Python 生态中最成熟的全栈框架，其内置的 ORM、认证系统以及强大的第三方库支持，使其成为快速搭建后端 API 的首选。本文将带你从零开始，完成一个包含数据库连接、缓存、JWT 认证及接口文档生成的完整 API 项目。
环境准备与项目初始化
首先确保 Python 环境已就绪，建议创建虚拟环境以避免依赖冲突。安装 Django 基础包：
pip install django
使用 django-admin 创建项目目录，并进入其中初始化应用：
django-admin startproject myproject
cd myproject
python manage.py startapp api
此时项目结构已初步形成，接下来需要引入核心依赖来扩展功能。
安装关键依赖
为了构建标准的 RESTful 服务，我们需要安装 DRF（Django REST Framework）及相关插件。推荐使用以下命令：
pip install djangorestframework djangorestframework-simplejwt django-cors-headers drf-spectacular redis
这些库分别负责序列化数据、处理 JWT 令牌、跨域请求支持以及自动生成 Swagger 文档。安装完成后，记得在 settings.py 中注册到 INSTALLED_APPS。
配置 MySQL 数据库
默认 SQLite 仅适合开发测试，生产环境建议使用 MySQL。修改 settings.py 中的 DATABASES 配置：
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'your_db_name',
'USER': 'your_username',
'PASSWORD': 'your_password',
'HOST': 'localhost',
'PORT': '3306',
}
}
注意需安装 mysqlclient 或 pymysql 驱动，并确保数据库用户权限正确。配置完成后执行迁移命令即可生成表结构。
集成 Redis 缓存
Redis 能显著提升接口响应速度。在 CACHES 配置中添加 Redis 后端：
CACHES = {
"default": {
"BACKEND": "django_redis.cache.RedisCache",
"LOCATION": "redis://127.0.0.1:6379/1",
"OPTIONS": {
"CLIENT_CLASS": "django_redis.client.DefaultClient",
}
}
}
同时记得在 MIDDLEWARE 中加入 django.middleware.cache.UpdateCacheMiddleware 和 FirstPageCacheMiddleware 以启用缓存中间件。
配置 JWT 认证
相比 Session 模式，JWT 更适合前后端分离架构。安装 djangorestframework-simplejwt 后，在 settings.py 中配置认证类：
REST_FRAMEWORK = {
'DEFAULT_AUTHENTICATION_CLASSES': (
'rest_framework_simplejwt.authentication.JWTAuthentication',
),
'DEFAULT_PERMISSION_CLASSES': (
'rest_framework.permissions.IsAuthenticated',
)
}
并在 urls.py 中引入 Token 视图，用于获取访问令牌。这样用户登录后可通过 Header 携带 Token 进行受保护资源的访问。
接入 Swagger 接口文档
为了让前端同事更方便地对接，我们使用 drf-spectacular 自动生成 OpenAPI 文档。添加应用配置：
INSTALLED_APPS += ['drf_spectacular']
SPECTACULAR_SETTINGS = {
'TITLE': 'My Project API',
'DESCRIPTION': 'API Documentation',
'VERSION': '1.0.0',
}
最后在 urls.py 中映射 /schema/ 路径，配合 UI 工具即可查看在线文档。
编写示例 API
现在可以创建一个简单的模型视图集。在 api/views.py 中：
from rest_framework import viewsets
from .models import Item
from .serializers import ItemSerializer
class ItemViewSet(viewsets.ModelViewSet):
queryset = Item.objects.all()
serializer_class = ItemSerializer
注册路由后即可通过 GET/POST/PUT/DELETE 操作数据。记得检查 serializers.py 中的字段定义是否符合预期。
总结
至此，一个具备基础认证、缓存及文档能力的 Django API 项目骨架已完成。后续可根据业务需求扩展权限控制、异步任务等功能。保持代码规范，善用中间件和装饰器，能让项目更易维护。
