当前位置：首页 > news >正文

Djoser 详解

news 2025/7/22 12:04:28

1. 什么是 Djoser

Djoser 是一个基于 Django REST framework 的第三方库，它为常见的用户认证功能提供了开箱即用的 RESTful 接口，比如注册、登录、注销、密码重置、账户激活、令牌刷新等。

它主要目的是减少你手写视图和序列化器的工作量，并且与 TokenAuth、JWT（如 simplejwt）集成良好。

适用场景：

基于 DRF 的后端 API 项目
不想自己编写大量注册、登录、找回密码逻辑
需要对用户认证进行自定义扩展

2. 主要特性

特性	Djoser 是否支持
注册与登录、注销	✅ 支持
邮箱激活	✅ 支持
密码重置/修改	✅ 支持
用户信息管理	✅ 支持
支持自定义用户模型	✅ 支持
RESTful API	✅ 支持
Token / JWT 支持	✅ 支持
支持社交媒体登录	✅ 支持
几乎所有方面都可以自定义	✅ 支持

3. 安装与配置

安装

pip install djoser

如果你打算使用 JWT 登录方式，还需要安装：

pip install djangorestframework-simplejwt

基本配置

Djoser 支持两种 Token 认证方式：

传统 Token（不推荐）

REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ['rest_framework.authentication.TokenAuthentication',],
}

JWT（推荐，支持 Token 刷新、验证，安全性更高。）

REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ['rest_framework_simplejwt.authentication.JWTAuthentication',],
}

在 settings.py 中添加：

INSTALLED_APPS = [...'rest_framework','rest_framework.authtoken',  # 如果需要使用token认证'djoser',...
]REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework.authentication.TokenAuthentication',  # token认证# 或者使用JWT# 'rest_framework_simplejwt.authentication.JWTAuthentication',),
}

URL 配置

在 urls.py 中：

from django.urls import path, includeurlpatterns = [...path('auth/', include('djoser.urls')),path('auth/', include('djoser.urls.authtoken')),  # 如果使用token认证# 或者使用JWT# path('auth/', include('djoser.urls.jwt')),...
]

4. 主要端点

Djoser 提供了一系列 RESTful 端点：

用户管理

/users/ - POST: 注册新用户
/users/me/ - GET, PUT, PATCH: 获取/更新当前用户信息
/users/{id}/ - GET: 获取特定用户信息

认证

/token/login/ - POST: 获取认证令牌(登录)
/token/logout/ - POST: 注销(使令牌失效)

密码管理

/users/set_password/ - POST: 更改密码
/users/reset_password/ - POST: 请求密码重置
/users/reset_password_confirm/ - POST: 确认密码重置

激活

/users/activation/ - POST: 激活用户账户
/users/resend_activation/ - POST: 重新发送激活邮件

5. 自定义设置

Djoser 提供了丰富的配置选项，可以在 settings.py 中自定义：

DJOSER = {# -------------------------------------------------------------------# 1. 核心认证配置# -------------------------------------------------------------------'LOGIN_FIELD': 'email',               # 使用email作为登录字段（替代username）'USER_CREATE_PASSWORD_RETYPE': True,  # 注册时需二次确认密码'SET_PASSWORD_RETYPE': True,          # 修改密码时需二次确认'LOGOUT_ON_PASSWORD_CHANGE': True,    # 修改密码后自动登出'PASSWORD_CHANGED_EMAIL_CONFIRMATION': True,  # 密码修改后发送确认邮件# -------------------------------------------------------------------# 2. 用户数据序列化器配置# -------------------------------------------------------------------'SERIALIZERS': {# 用户注册序列化器（需自定义）'user_create': 'accounts.serializers.CustomUserCreateSerializer',# 普通用户数据序列化器'user': 'accounts.serializers.CustomUserSerializer',# 当前用户数据序列化器'current_user': 'accounts.serializers.CustomUserDetailSerializer',# 密码重置序列化器（可选自定义）'password_reset': 'djoser.serializers.PasswordResetSerializer',},# -------------------------------------------------------------------# 3. 权限控制# -------------------------------------------------------------------'PERMISSIONS': {# 用户列表权限（仅管理员）'user_list': ['rest_framework.permissions.IsAdminUser'],# 用户详情权限（用户自己或管理员）'user': ['rest_framework.permissions.IsAuthenticatedOrReadOnly'],# 用户删除权限（仅管理员）'user_delete': ['rest_framework.permissions.IsAdminUser'],# 密码重置权限（允许任何用户）'password_reset': ['rest_framework.permissions.AllowAny'],},# -------------------------------------------------------------------# 4. 邮件相关配置# -------------------------------------------------------------------'SEND_ACTIVATION_EMAIL': True,       # 启用注册激活邮件'SEND_CONFIRMATION_EMAIL': True,     # 注册成功后发送欢迎邮件'ACTIVATION_URL': 'auth/activate/{uid}/{token}',       # 激活链接格式（需与前端路由匹配）'PASSWORD_RESET_CONFIRM_URL': 'auth/password/reset/{uid}/{token}',  # 密码重置链接# 邮件主题和模板配置（可选自定义）'EMAIL': {'activation': 'accounts.email.ActivationEmail','confirmation': 'accounts.email.ConfirmationEmail','password_reset': 'accounts.email.PasswordResetEmail',},# -------------------------------------------------------------------# 5. 安全与令牌配置# -------------------------------------------------------------------'TOKEN_MODEL': None,  # 使用DRF默认Token（推荐使用JWT）# 如果使用JWT，需添加以下配置：# 'JWT_AUTH': {#     'JWT_ALLOW_REFRESH': True,#     'JWT_EXPIRATION_DELTA': timedelta(days=1),# },'HIDE_USERS': True,  # 隐藏用户列表接口中的非管理员用户# -------------------------------------------------------------------# 6. 其他实用配置# -------------------------------------------------------------------'USER_ID_FIELD': 'id',  # 用户主键字段'SOCIAL_AUTH_ALLOWED_REDIRECT_URIS': [  # 社交登录允许的重定向URI'http://localhost:3000/auth/google','https://yourdomain.com/auth/facebook'],# 用户名相关配置（如果使用username）# 'USERNAME_RESET_CONFIRM_URL': 'auth/username/reset/{uid}/{token}',# 'USERNAME_CHANGED_EMAIL_CONFIRMATION': True,
}

6. 与 JWT 集成

如果需要使用 JWT 而不是默认的 Token 认证：

安装所需包：

pip install djangorestframework-simplejwt

修改 settings.py：

REST_FRAMEWORK = {'DEFAULT_AUTHENTICATION_CLASSES': ('rest_framework_simplejwt.authentication.JWTAuthentication',),
}

修改 urls.py：

urlpatterns = [...path('auth/', include('djoser.urls.jwt')),...
]

7. 使用示例

注册用户

POST /auth/users/
Content-Type: application/json{"username": "newuser","password": "strongpassword123","email": "newuser@example.com"
}

登录获取令牌

POST /auth/token/login/
Content-Type: application/json{"username": "newuser","password": "strongpassword123"
}POST /auth/jwt/create/
Content-Type: application/json{"email": "user@example.com",  # 使用 LOGIN_FIELD 指定的字段（默认是 email）"password": "strongpassword123"
}

响应：

{"auth_token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}{"refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

访问受保护资源

GET /api/protected/
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b

8. 高级功能

自定义用户模型（推荐）

建议在项目中使用自定义用户模型：

# accounts/models.py
from django.contrib.auth.models import AbstractUser
from django.db import modelsclass CustomUser(AbstractUser):email = models.EmailField(unique=True)USERNAME_FIELD = 'email'REQUIRED_FIELDS = ['username']

在 settings.py 设置：

AUTH_USER_MODEL = 'accounts.CustomUser'

自定义序列化器

你可以通过修改 DJOSER[‘SERIALIZERS’] 来扩展字段：

# accounts/serializers.py
from djoser.serializers import UserCreateSerializer as BaseUserCreateSerializer
from djoser.serializers import UserSerializer as BaseUserSerializerclass CustomUserCreateSerializer(BaseUserCreateSerializer):class Meta(BaseUserCreateSerializer.Meta):fields = ('id', 'email', 'username', 'password')class CustomUserSerializer(BaseUserSerializer):class Meta(BaseUserSerializer.Meta):fields = ('id', 'email', 'username')

然后在设置中指定：

DJOSER = {'SERIALIZERS': {'user_create': 'myapp.serializers.CustomUserCreateSerializer',}
}

自定义权限

DJOSER = {'PERMISSIONS': {'user_list': ['rest_framework.permissions.IsAdminUser'],'user': ['rest_framework.permissions.IsAuthenticated'],}
}

电子邮件模板

可以自定义各种电子邮件模板：

DJOSER = {'EMAIL': {'activation': 'myapp.email.ActivationEmail','password_reset': 'myapp.email.PasswordResetEmail',}
}

9. 常见问题解决

邮箱激活

# 必须配置
SEND_ACTIVATION_EMAIL = True
ACTIVATION_URL = 'your-frontend-route/{uid}/{token}'  # 前端需要处理该路由，展示对应的激活/重置页面# 推荐配置
EMAIL_TIMEOUT = 10  # 邮件发送超时设置
DEFAULT_FROM_EMAIL = 'noreply@yourdomain.com'  # 发件人地址

测试：

# 测试邮件发送
python manage.py sendtestmail user@example.com# 测试激活链接
curl -X POST http://localhost:8000/auth/users/activation/ -d 'uid=XXX&token=XXX'

密码重置

确保启用：

'SEND_CONFIRMATION_EMAIL': True,
'PASSWORD_RESET_CONFIRM_URL': 'password-reset/{uid}/{token}',

前端需要实现对应路由的页面

用户模型问题

自定义用户模型不工作：

确认 AUTH_USER_MODEL 已正确设置

检查序列化器继承关系：

from djoser.serializers import UserCreateSerializer
class CustomUserCreateSerializer(UserCreateSerializer):class Meta(UserCreateSerializer.Meta):fields = ['id', 'email', 'name', 'password']

10. 实践建议

统一认证方式：优先使用 JWT（SimpleJWT）。
自定义序列化器：始终为自定义用户模型指定序列化器。
测试邮件服务：部署前务必测试邮件发送功能。
安全建议：
- 生产环境务必使用HTTPS
- 合理设置密码强度要求
- 优先使用 JWT，JWT应设置合理的过期时间
- 限制登录尝试次数以防止暴力破解
- 定期轮换敏感密钥（特别是使用 JWT 时）
推荐组合：
功能库
后端框架 Django + DRF
用户认证 Djoser
Token认证方式 simplejwt
邮件发送 SMTP / Mailgun
前端交互 Vue / React