به طور مستقیم: اگر Custom User Model در جنگو را از همان روز اول نسازید، تغییر دادن مدل کاربر در میانه راه تقریبا دردناک و پرریسک است. تمام رابطه‌ها، فرم‌ها، احراز هویت و مهاجرت‌های دیتابیس به User وابسته‌اند؛ عوض کردن آن بعدا یعنی جابجایی داده حساس، اصلاح ForeignKeyها و گاهی بازنویسی بخش‌های کلیدی. در مقابل، شروع پروژه با یک مدل کاربر سفارشی ساده (حداقل مبتنی بر AbstractUser) هزینه ندارد و خیالتان را برای نیازهای آینده مثل ورود با ایمیل/موبایل، فیلدهای پروفایل و سیاست‌های احراز هویت راحت می‌کند.

چرا باید از ابتدای پروژه User سفارشی داشته باشیم؟

  • تغییر سخت و پرهزینه بعدی: جنگو اجازه «تعویض» مدل User پس از ایجاد اولین مهاجرت‌ها را عملا نمی‌دهد. در توسعه اولیه شاید بتوانید دیتابیس را Drop کنید، اما در محیط واقعی این کار پیچیده و پرخطر است.
  • نیازهای متداول: ورود با ایمیل به جای نام کاربری، یکتا بودن ایمیل، شماره موبایل، فیلدهای تکمیلی پروفایل، و یکپارچه‌سازی با سرویس‌های پیامکی/ایمیلی.
  • سازگاری با آینده: سیاست‌های رمزعبور، مسیرهای بازیابی حساب، لاگین اجتماعی یا SSO، همه روی User سوار می‌شوند. با مدل سفارشی دستتان باز است.
  • روابط تمیز: از روز اول ForeignKeyها را به settings.AUTH_USER_MODEL می‌بندید و بعدها نیازی به تغییر مراجع یا مهاجرت داده ندارید.

دو راه رسمی: AbstractUser یا AbstractBaseUser؟

پاسخ کوتاه: اگر فقط می‌خواهید ورود با ایمیل/موبایل یا فیلدهای بیشتر داشته باشید، AbstractUser ساده‌تر و کافی است. اگر سیستم احراز هویت کاملا شخصی (بدون فیلدهای آماده جنگو) می‌سازید، سراغ AbstractBaseUser بروید.

  • AbstractUser: همه امکانات کاربر پیش‌فرض (گروه‌ها، مجوزها، تاریخ‌ها) را دارد؛ شما فقط فیلدها و رفتار را مطابق نیاز تغییر می‌دهید. کم‌ریسک و سریع.
  • AbstractBaseUser: هسته حداقلی احراز هویت را می‌دهد. باید Manager، فیلدها، is_staff/is_active و حتی PermissionsMixin را خودتان مدیریت کنید. انعطاف بالا همراه با پیچیدگی بیشتر.

پیاده‌سازی سریع (توصیه‌شده) با AbstractUser

هدف: حذف نام کاربری، استفاده از ایمیل به عنوان شناسه ورود، و یکتا بودن ایمیل.

۱) ساخت اپ کاربر

python manage.py startapp accounts

۲) مدل User سفارشی

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

class User(AbstractUser):
    username = None  # حذف فیلد username
    email = models.EmailField(unique=True)

    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = []  # هنگام createsuperuser فیلدهای اضافی موردنیاز

    objects = UserManager()  # همچنان از UserManager جنگو استفاده می‌کنیم

    def __str__(self):
        return self.email

۳) تنظیمات پروژه

قبل از اجرای هر migrate، تنظیم زیر را اضافه کنید:

# settings.py
INSTALLED_APPS = [
    # ...
    'accounts',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    # ...
]

AUTH_USER_MODEL = 'accounts.User'

نکته مهم: این تنظیم باید قبل از اولین مهاجرت دیتابیس انجام شود. اگر قبلا migrate کرده‌اید، در محیط توسعه دیتابیس را ریست کنید. در محیط واقعی این کار ساده نیست.

۴) ثبت در پنل ادمین

# accounts/admin.py
from django.contrib import admin
from django.contrib.auth.admin import UserAdmin as BaseUserAdmin
from .models import User

@admin.register(User)
class UserAdmin(BaseUserAdmin):
    ordering = ('email',)
    list_display = ('email', 'first_name', 'last_name', 'is_staff', 'is_active')
    search_fields = ('email', 'first_name', 'last_name')

    # چون username حذف شده است، فرم‌ها را با ایمیل تنظیم می‌کنیم
    fieldsets = (
        (None, {'fields': ('email', 'password')}),
        ('اطلاعات شخصی', {'fields': ('first_name', 'last_name')}),
        ('دسترسی‌ها', {'fields': ('is_active', 'is_staff', 'is_superuser', 'groups', 'user_permissions')}),
        ('تاریخ‌ها', {'fields': ('last_login', 'date_joined')}),
    )
    add_fieldsets = (
        (None, {
            'classes': ('wide',),
            'fields': ('email', 'password1', 'password2', 'is_staff', 'is_active')}
        ),
    )

۵) مهاجرت

python manage.py makemigrations
python manage.py migrate
python manage.py createsuperuser  # حالا ایمیل از شما می‌خواهد

۶) استفاده ایمن در مدل‌های دیگر

# نمونه استفاده در یک اپ دیگر
from django.conf import settings
from django.db import models

class Order(models.Model):
    user = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)
    # ...

و هر وقت به کلاس User در منطق برنامه نیاز داشتید:

from django.contrib.auth import get_user_model

User = get_user_model()
u = User.objects.get(email='example@example.com')

پیاده‌سازی انعطاف‌پذیر با AbstractBaseUser (وقتی نیاز فراتر است)

اگر می‌خواهید مدل‌هایی با شناسه متفاوت (مثلا موبایل) و کنترل کامل روی فرایند ساخت کاربر داشته باشید، از AbstractBaseUser به همراه PermissionsMixin استفاده کنید.

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

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.is_active = extra_fields.get('is_active', True)
        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)
        if extra_fields.get('is_staff') is not True or extra_fields.get('is_superuser') is not True:
            raise ValueError('سوپر یوزر باید is_staff و is_superuser داشته باشد')
        return self.create_user(email, password, **extra_fields)

class User(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    first_name = models.CharField(max_length=150, blank=True)
    last_name = models.CharField(max_length=150, blank=True)
    is_active = models.BooleanField(default=True)
    is_staff = models.BooleanField(default=False)
    date_joined = models.DateTimeField(auto_now_add=True)

    USERNAME_FIELD = 'email'
    REQUIRED_FIELDS = []

    objects = UserManager()

    def __str__(self):
        return self.email

ثبت در ادمین مشابه قبل است، اما چون از AbstractBaseUser استفاده کرده‌اید، باید فرم‌های ایجاد/ویرایش را کامل‌تر سفارشی کنید.

مراحل دقیق اجرا و ترتیب صحیح

  1. قبل از هر migrate، اپ accounts را بسازید و AUTH_USER_MODEL را تنظیم کنید.
  2. مدل User را با AbstractUser یا AbstractBaseUser پیاده‌سازی کنید.
  3. ادمین اختصاصی را ثبت کنید تا ساخت کاربر از پنل ممکن شود.
  4. migrate را اجرا کنید و یک سوپر یوزر بسازید.
  5. در تمام ForeignKey/M2Mها از settings.AUTH_USER_MODEL استفاده کنید.
  6. در کدهای اجرایی از get_user_model() برای دسترسی به کلاس User استفاده کنید.

چگونه مطمئن شویم همه چیز درست کار می‌کند؟

  • ورود به /admin با سوپر یوزر جدید موفق است و فیلد username وجود ندارد.
  • ساخت کاربر تکراری با ایمیل مشابه خطای unique می‌دهد.
  • یک ForeignKey به settings.AUTH_USER_MODEL تعریف و migrate شده است.
  • با get_user_model() می‌توانید کاربر را بر اساس ایمیل پیدا کنید.

خطاهای رایج و رفع آنها

  • اول migrate، بعد AUTH_USER_MODEL: اگر قبلا migrate کرده‌اید، باید در محیط توسعه دیتابیس و مهاجرت‌ها را ریست کنید. در محیط واقعی، جابجایی به مدل سفارشی نیازمند مهاجرت داده و بازنگری وابستگی‌هاست.
  • استفاده از auth.User در رابطه‌ها: همیشه از settings.AUTH_USER_MODEL استفاده کنید.
  • فرم ورود با برچسب Username: اگر USERNAME_FIELD را ایمیل گذاشته‌اید، اعتبارسنجی کار می‌کند اما برچسب فرم پیش‌فرض همچنان «Username» است. برای تجربه بهتر، فرم لاگین را سفارشی کنید.
  • یادتان رفته UserManager را ست کنید: در AbstractBaseUser حتما Manager سفارشی لازم است. در AbstractUser معمولا UserManager کافی است.
  • انکار دسترسی در ادمین: فیلدهای is_staff و is_active برای دسترسی به ادمین الزامی‌اند.

چه زمانی تغییر بعد از شروع ممکن است؟

اگر پروژه‌تان هنوز در مراحل اولیه است، ساده‌ترین راه حذف دیتابیس و مهاجرت‌ها و راه‌اندازی مجدد با مدل سفارشی است. در پروژه‌های زنده، تغییر مدل کاربر نیازمند طراحی مهاجرت داده، بازنویسی روابط، سازگاری با پکیج‌ها و تست فراگیر است. این هزینه دقیقا همان چیزی است که با شروع از روز اول با User سفارشی از آن پیشگیری می‌کنید.

گام بعدی چیست؟

اگر قصد دارید لاگین با ایمیل، تایید ایمیل یا پیامک فعال‌سازی را پیاده‌سازی کنید، یک قدم منطقی یادگیری جریان‌های ثبت نام، احراز هویت و سفارش است. برای تمرین عملی می‌توانید از آموزش جنگو رایگان (فروشگاه اینترنتی) + سورس استفاده کنید و User سفارشی را در یک پروژه واقعی به کار بگیرید.

همچنین اگر می‌خواهید ایمیل تایید یا خوشامدگویی را به شکل غیرهمزمان بفرستید، راه‌اندازی Celery در جنگو انتخاب استانداردی است. راهنمای گام به گام را در آموزش Celery در جنگو: اجرای کارهای پس زمینه و وظایف زمان بندی شده ببینید.