Django用户模型扩展与重写完全指南：从基础到高级实践

高压锅_1220

于 2025-07-07 09:48:19 发布

阅读量29

点赞数

CC 4.0 BY-SA版权

文章标签： django 数据库 sqlite

原文链接：https://blog.csdn.net/qq_74847271/article/details/143610008

引言

Django的认证系统提供了一个功能完善的User模型，但在实际项目开发中，内置User模型往往无法满足特定业务需求。例如，需要添加手机号、头像、部门等自定义字段，或实现基于邮箱的登录认证。本文将详细介绍Django用户模型的三种扩展方式（一对一关联、继承AbstractUser、继承AbstractBaseUser），分析各自的适用场景，并通过实战案例演示如何实现自定义用户模型，帮助开发者根据项目需求选择最合适的方案。

一、为什么需要扩展或重写User模型

1.1 内置User模型的局限性

Django内置的User模型位于django.contrib.auth.models.User，包含以下字段：

用户名(username)
密码(password)
邮箱(email)
姓(first_name)
名(last_name)
活跃状态(is_active)
管理员权限(is_staff)
超级用户权限(is_superuser)
最后登录时间(last_login)
注册时间(date_joined)

这些字段对于简单应用足够，但在实际项目中常遇到以下局限：

无法添加自定义字段（如手机号、头像、性别等）
认证方式固定为用户名认证，不支持邮箱/手机号登录
用户资料与认证信息耦合，不符合关注点分离原则
权限系统简单，难以满足复杂的角色管理需求

1.2 常见扩展需求

需求类型	具体场景	推荐方案
简单扩展	添加少量额外字段（如手机号、头像）	一对一关联或AbstractUser
认证方式修改	使用邮箱/手机号登录	AbstractUser
完全自定义	复杂的用户属性和认证逻辑	AbstractBaseUser
多用户类型	普通用户、管理员、VIP用户等不同角色	代理模型或权限组+AbstractUser

二、用户模型扩展的三种方式

2.1 方式一：一对一关联（Profile模型）

原理：创建一个与User模型一对一关联的Profile模型，存储额外字段。

优点：

实现简单，不影响原有User模型结构
可以随时添加，无需修改已有数据库结构
保留Django认证系统的全部功能

缺点：

查询用户信息时需要额外关联查询
管理用户数据需要操作两个模型

实现步骤：

创建Profile模型：

# accounts/models.py
from django.db import models
from django.contrib.auth.models import User

class UserProfile(models.Model):
    """用户资料扩展模型"""
    user = models.OneToOneField(User, on_delete=models.CASCADE, related_name='profile')
    phone = models.CharField(max_length=11, blank=True, null=True, verbose_name='手机号')
    avatar = models.ImageField(upload_to='avatars/', blank=True, null=True, verbose_name='头像')
    gender = models.CharField(max_length=10, choices=[('male', '男'), ('female', '女'), ('other', '其他')], blank=True, null=True, verbose_name='性别')
    department = models.CharField(max_length=100, blank=True, null=True, verbose_name='部门')
    created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')
    updated_at = models.DateTimeField(auto_now=True, verbose_name='更新时间')

    class Meta:
        verbose_name = '用户资料'
        verbose_name_plural = '用户资料'

    def __str__(self):
        return f"{self.user.username}的资料"

创建信号自动生成Profile：

# accounts/signals.py
from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User
from .models import UserProfile

@receiver(post_save, sender=User)
def create_user_profile(sender, instance, created, **kwargs):
    """用户创建时自动创建对应的Profile"""
    if created:
        UserProfile.objects.create(user=instance)

@receiver(post_save, sender=User)
def save_user_profile(sender, instance,** kwargs):
    """用户保存时自动保存对应的Profile"""
    instance.profile.save()

在settings.py中注册信号：

# myproject/settings.py
INSTALLED_APPS = [
    # ...其他应用
    'accounts',
]

# 信号配置
SIGNAL_HANDLERS = [
    'accounts.signals',
]

使用示例：

# 创建用户
user = User.objects.create_user(username='testuser', email='test@example.com', password='password123')

# 访问用户资料
print(user.profile.phone)  # None

# 更新用户资料
user.profile.phone = '13800138000'
user.profile.gender = 'male'
user.profile.save()

# 查询用户资料
from django.db.models import F
users_with_profile = User.objects.select_related('profile').annotate(
    phone=F('profile__phone'),
    department=F('profile__department')
)

2.2 方式二：继承AbstractUser（推荐）

原理：继承Django提供的AbstractUser类，在其基础上添加自定义字段。

优点：

保留Django认证系统的全部功能
直接扩展User模型，使用简单
管理界面友好，无需额外配置

缺点：

必须在项目初始阶段使用，否则需要复杂的数据迁移
无法完全控制认证逻辑

实现步骤：

创建自定义User模型：

# accounts/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    """扩展Django内置User模型"""
    phone = models.CharField(max_length=11, blank=True, null=True, verbose_name='手机号')
    avatar = models.ImageField(upload_to='avatars/', blank=True, null=True, verbose_name='头像')
    gender = models.CharField(max_length=10, choices=[('male', '男'), ('female', '女'), ('other', '其他')], blank=True, null=True, verbose_name='性别')
    department = models.CharField(max_length=100, blank=True, null=True, verbose_name='部门')
    # 可以添加更多自定义字段

    class Meta:
        verbose_name = '用户'
        verbose_name_plural = '用户'

    def __str__(self):
        return self.username

在settings.py中指定自定义User模型：

# myproject/settings.py
# 必须在第一次迁移前设置，否则需要手动修改数据库
AUTH_USER_MODEL = 'accounts.User'

创建迁移并应用：

python manage.py makemigrations accounts
python manage.py migrate

自定义用户管理器（可选）：

# accounts/models.py
from django.contrib.auth.models import BaseUserManager

class UserManager(BaseUserManager):
    """自定义用户管理器"""
    def create_user(self, username, email, password=None, **extra_fields):
        """创建普通用户"""
        if not email:
            raise ValueError('必须提供邮箱地址')
        email = self.normalize_email(email)
        user = self.model(username=username, email=email,** extra_fields)
        user.set_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, username, email, password=None, **extra_fields):
        """创建超级用户"""
        extra_fields.setdefault('is_staff', True)
        extra_fields.setdefault('is_superuser', True)
        extra_fields.setdefault('is_active', True)
        
        if extra_fields.get('is_staff') is not True:
            raise ValueError('超级用户必须设置is_staff=True')
        if extra_fields.get('is_superuser') is not True:
            raise ValueError('超级用户必须设置is_superuser=True')
            
        return self.create_user(username, email, password,** extra_fields)

# 在User模型中使用自定义管理器
class User(AbstractUser):
    # ...字段定义...
    
    objects = UserManager()

使用示例：

# 创建用户
user = User.objects.create_user(
    username='testuser',
    email='test@example.com',
    password='password123',
    phone='13800138000',
    department='技术部'
)

# 查询用户
users = User.objects.filter(department='技术部')

2.3 方式三：继承AbstractBaseUser（完全自定义）

原理：继承最基础的AbstractBaseUser，完全自定义用户模型和认证逻辑。

优点：

完全控制用户模型结构和认证逻辑
适合特殊业务需求（如无用户名，使用手机号/邮箱作为唯一标识）

缺点：

实现复杂，需要自定义用户管理器和权限系统
与Django内置应用兼容性可能存在问题

实现步骤：

创建自定义User模型：

# accounts/models.py
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin
from django.db import models

class UserManager(BaseUserManager):
    def create_user(self, email, password=None, **extra_fields):
        """使用邮箱作为唯一标识创建用户"""
        if not email:
            raise ValueError('必须提供邮箱地址')
        email = self.normalize_email(email)
        user = self.model(email=email,** extra_fields)
        user.set_password(password)
        user.save(using=self._db)
        return user

    def create_superuser(self, email, password=None, **extra_fields):
        """创建超级用户"""
        extra_fields.setdefault('is_staff', True)
        extra_fields.setdefault('is_superuser', True)
        extra_fields.setdefault('is_active', True)
        
        return self.create_user(email, password,** extra_fields)

class User(AbstractBaseUser, PermissionsMixin):
    """完全自定义的用户模型，使用邮箱作为唯一标识"""
    email = models.EmailField(unique=True, verbose_name='邮箱')
    name = models.CharField(max_length=100, verbose_name='姓名')
    phone = models.CharField(max_length=11, blank=True, null=True, verbose_name='手机号')
    is_active = models.BooleanField(default=True, verbose_name='是否活跃')
    is_staff = models.BooleanField(default=False, verbose_name='是否为员工')
    created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')
    updated_at = models.DateTimeField(auto_now=True, verbose_name='更新时间')

    objects = UserManager()

    USERNAME_FIELD = 'email'  # 设置邮箱为登录标识
    REQUIRED_FIELDS = ['name']  # 创建超级用户时必填字段

    class Meta:
        verbose_name = '用户'
        verbose_name_plural = '用户'

    def __str__(self):
        return self.email

在settings.py中指定自定义User模型：

# myproject/settings.py
AUTH_USER_MODEL = 'accounts.User'

创建迁移并应用：

python manage.py makemigrations accounts
python manage.py migrate

自定义认证后端（可选）：

# accounts/backends.py
from django.contrib.auth.backends import ModelBackend
from django.db.models import Q
from .models import User

class EmailOrPhoneBackend(ModelBackend):
    """支持邮箱或手机号登录"""
    def authenticate(self, request, username=None, password=None, **kwargs):
        try:
            # 尝试通过邮箱或手机号查找用户
            user = User.objects.get(
                Q(email=username) | Q(phone=username)
            )
            if user.check_password(password):
                return user
        except User.DoesNotExist:
            return None

# 在settings.py中配置认证后端
AUTHENTICATION_BACKENDS = [
    'accounts.backends.EmailOrPhoneBackend',
    'django.contrib.auth.backends.ModelBackend',
]

三、三种方式对比与选择建议

3.1 功能对比

特性	一对一关联	继承AbstractUser	继承AbstractBaseUser
实现复杂度	简单	中等	复杂
保留内置功能	全部	全部	部分（需自定义）
添加自定义字段	是	是	是
修改认证方式	需额外实现	较容易	完全控制
数据迁移难度	低	中（初始阶段使用）	高
管理界面支持	需额外配置	原生支持	需大量自定义
第三方应用兼容性	高	中	低

3.2 选择建议

小型项目，简单扩展需求：
- 选择"一对一关联"方式，实现简单，风险低
中型项目，需要添加字段或修改认证方式：
- 选择"继承AbstractUser"方式，平衡灵活性和复杂度
大型项目，特殊业务需求：
- 选择"继承AbstractBaseUser"方式，完全定制用户模型
项目初始阶段：
- 推荐直接使用"继承AbstractUser"，为未来扩展预留空间
已有项目扩展：
- 只能选择"一对一关联"方式，避免数据迁移风险

四、实战案例：基于AbstractUser的用户系统

4.1 模型定义

# accounts/models.py
from django.contrib.auth.models import AbstractUser
from django.db import models

class User(AbstractUser):
    """扩展用户模型"""
    phone = models.CharField(max_length=11, unique=True, blank=True, null=True, verbose_name='手机号')
    avatar = models.ImageField(upload_to='avatars/', blank=True, null=True, verbose_name='头像')
    gender = models.CharField(max_length=10, choices=[('male', '男'), ('female', '女'), ('other', '其他')], blank=True, null=True, verbose_name='性别')
    department = models.ForeignKey('Department', on_delete=models.SET_NULL, null=True, blank=True, related_name='users', verbose_name='部门')
    position = models.CharField(max_length=100, blank=True, null=True, verbose_name='职位')
    date_joined = models.DateTimeField(auto_now_add=True, verbose_name='加入时间')

    class Meta:
        verbose_name = '用户'
        verbose_name_plural = '用户'
        ordering = ['-date_joined']

    def __str__(self):
        return f"{self.username} ({self.get_full_name() or '未设置姓名'})"

class Department(models.Model):
    """部门模型"""
    name = models.CharField(max_length=100, unique=True, verbose_name='部门名称')
    description = models.TextField(blank=True, null=True, verbose_name='部门描述')
    created_at = models.DateTimeField(auto_now_add=True, verbose_name='创建时间')

    class Meta:
        verbose_name = '部门'
        verbose_name_plural = '部门'
        ordering = ['name']

    def __str__(self):
        return self.name

4.2 表单实现

# accounts/forms.py
from django import forms
from django.contrib.auth.forms import UserCreationForm, UserChangeForm
from .models import User

class CustomUserCreationForm(UserCreationForm):
    """自定义用户创建表单"""
    email = forms.EmailField(required=True, widget=forms.EmailInput(attrs={'class': 'form-control'}))
    phone = forms.CharField(required=False, max_length=11, widget=forms.TextInput(attrs={'class': 'form-control', 'placeholder': '11位手机号'}))
    first_name = forms.CharField(required=True, widget=forms.TextInput(attrs={'class': 'form-control', 'placeholder': '请输入姓名'}))

    class Meta(UserCreationForm.Meta):
        model = User
        fields = ('username', 'email', 'first_name', 'phone', 'password1', 'password2')

    def save(self, commit=True):
        user = super().save(commit=False)
        user.email = self.cleaned_data['email']
        user.first_name = self.cleaned_data['first_name']
        user.phone = self.cleaned_data['phone']
        if commit:
            user.save()
        return user

class CustomUserChangeForm(UserChangeForm):
    """自定义用户修改表单"""
    password = None  # 不显示密码字段
    phone = forms.CharField(required=False, max_length=11, widget=forms.TextInput(attrs={'class': 'form-control'}))
    avatar = forms.ImageField(required=False, widget=forms.FileInput(attrs={'class': 'form-control-file'}))
    gender = forms.ChoiceField(required=False, choices=User.gender.field.choices, widget=forms.Select(attrs={'class': 'form-control'}))
    department = forms.ModelChoiceField(required=False, queryset=Department.objects.all(), widget=forms.Select(attrs={'class': 'form-control'}))
    position = forms.CharField(required=False, widget=forms.TextInput(attrs={'class': 'form-control'}))

    class Meta:
        model = User
        fields = ('username', 'email', 'first_name', 'last_name', 'phone', 'avatar', 'gender', 'department', 'position', 'is_active', 'is_staff')

4.3 视图实现

# accounts/views.py
from django.contrib.auth.views import LoginView, PasswordChangeView
from django.urls import reverse_lazy
from django.views.generic import CreateView, UpdateView
from django.contrib.auth.mixins import LoginRequiredMixin
from .forms import CustomUserCreationForm, CustomUserChangeForm
from .models import User

class CustomLoginView(LoginView):
    """自定义登录视图，支持邮箱登录"""
    template_name = 'accounts/login.html'
    redirect_authenticated_user = True
    
    def get_success_url(self):
        return reverse_lazy('dashboard')

class RegisterView(CreateView):
    """用户注册视图"""
    model = User
    form_class = CustomUserCreationForm
    template_name = 'accounts/register.html'
    success_url = reverse_lazy('login')

class ProfileUpdateView(LoginRequiredMixin, UpdateView):
    """用户资料更新视图"""
    model = User
    form_class = CustomUserChangeForm
    template_name = 'accounts/profile.html'
    
    def get_object(self):
        return self.request.user
    
    def get_success_url(self):
        return reverse_lazy('profile')

4.4 URL配置

# accounts/urls.py
from django.urls import path
from django.contrib.auth.views import LogoutView, PasswordResetView, PasswordResetDoneView, PasswordResetConfirmView, PasswordResetCompleteView
from . import views

urlpatterns = [
    path('login/', views.CustomLoginView.as_view(), name='login'),
    path('logout/', LogoutView.as_view(next_page='login'), name='logout'),
    path('register/', views.RegisterView.as_view(), name='register'),
    path('profile/', views.ProfileUpdateView.as_view(), name='profile'),
    
    # 密码重置
    path('password-reset/', PasswordResetView.as_view(template_name='accounts/password_reset.html'), name='password_reset'),
    path('password-reset/done/', PasswordResetDoneView.as_view(template_name='accounts/password_reset_done.html'), name='password_reset_done'),
    path('password-reset-confirm/<uidb64>/<token>/', PasswordResetConfirmView.as_view(template_name='accounts/password_reset_confirm.html'), name='password_reset_confirm'),
    path('password-reset-complete/', PasswordResetCompleteView.as_view(template_name='accounts/password_reset_complete.html'), name='password_reset_complete'),
]

4.5 管理界面配置

# accounts/admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin
from .models import User, Department
from .forms import CustomUserCreationForm, CustomUserChangeForm

class CustomUserAdmin(UserAdmin):
    """自定义用户管理界面"""
    add_form = CustomUserCreationForm
    form = CustomUserChangeForm
    model = User
    list_display = ('username', 'email', 'first_name', 'last_name', 'phone', 'department', 'is_active', 'is_staff')
    list_filter = ('is_active', 'is_staff', 'is_superuser', 'department')
    fieldsets = (
        (None, {'fields': ('username', 'password')}),
        ('个人信息', {'fields': ('email', 'first_name', 'last_name', 'phone', 'avatar', 'gender', 'department', 'position')}),
        ('权限', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
        ('日期信息', {'fields': ('last_login', 'date_joined')}),
    )
    add_fieldsets = (
        (None, {
            'classes': ('wide',),
            'fields': ('username', 'email', 'first_name', 'phone', 'password1', 'password2'),
        }),
    )
    search_fields = ('username', 'email', 'first_name', 'last_name', 'phone')
    ordering = ('username',)

admin.site.register(User, CustomUserAdmin)
admin.site.register(Department)

五、常见问题与解决方案

5.1 数据迁移问题

问题：项目中途想要从内置User模型切换到自定义User模型。

解决方案：

创建新的自定义User模型
使用Django的数据迁移工具导出用户数据
修改AUTH_USER_MODEL指向新模型
创建初始迁移并应用
编写自定义脚本导入用户数据

示例迁移脚本：

# 导出数据
python manage.py dumpdata auth.User > users.json

# 导入数据到新模型（自定义脚本）
import json
from django.core.management.base import BaseCommand
from accounts.models import User

class Command(BaseCommand):
    help = 'Import users from auth.User to custom User model'

    def handle(self, *args, **options):
        with open('users.json', 'r') as f:
            users = json.load(f)
            
        for user_data in users:
            User.objects.create(
                id=user_data['pk'],
                username=user_data['fields']['username'],
                password=user_data['fields']['password'],
                email=user_data['fields']['email'],
                first_name=user_data['fields']['first_name'],
                last_name=user_data['fields']['last_name'],
                is_active=user_data['fields']['is_active'],
                is_staff=user_data['fields']['is_staff'],
                is_superuser=user_data['fields']['is_superuser'],
                date_joined=user_data['fields']['date_joined'],
                last_login=user_data['fields']['last_login']
            )
        self.stdout.write(self.style.SUCCESS('Successfully imported users'))

5.2 第三方应用兼容性

问题：某些第三方应用依赖Django内置User模型。

解决方案：

检查第三方应用文档，确认是否支持自定义User模型
使用代理模型包装自定义User模型
必要时修改第三方应用代码

代理模型示例：

# compatibility/models.py
from django.db import models
from accounts.models import User

class AuthUserProxy(User):
    """代理模型，兼容依赖auth.User的第三方应用"""
    class Meta:
        proxy = True
        verbose_name = '兼容用户'
        verbose_name_plural = '兼容用户'

5.3 认证方式修改

问题：想要使用手机号或邮箱登录。

解决方案：

使用AbstractUser创建自定义User模型
实现自定义认证后端
在settings.py中配置认证后端

示例认证后端：

# accounts/backends.py
from django.contrib.auth.backends import ModelBackend
from django.db.models import Q

class EmailPhoneUsernameBackend(ModelBackend):
    """支持邮箱、手机号或用户名登录"""
    def authenticate(self, request, username=None, password=None, **kwargs):
        try:
            # 尝试通过用户名、邮箱或手机号查找用户
            user = User.objects.get(
                Q(username=username) | 
                Q(email=username) | 
                Q(phone=username)
            )
            if user.check_password(password):
                return user
        except User.DoesNotExist:
            # 为了安全，不区分"用户不存在"和"密码错误"
            return None