Kwa nini na vipi unapaswa kutumia custom user model?

Question

Accepted Answer

**Custom user model** hubadilisha `User` ya default ya Django ili kuendana na mahitaji ya application yako — kuongeza fields, kubadilisha login identifier (k.m. email badala ya username), au kubinafsisha tabia. Ushauri muhimu, unaorudiwa mara kwa mara: weka custom user model **mwanzoni kabisa** wa project, hata kama huhitaji mabadiliko bado, kwa sababu kuibadilisha baadaye ni jambo gumu mno.

## Kwa nini: default User ina mipaka na ni ngumu kubadilisha baadaye

```text
The default User has fixed fields (username, email, first/last name) and uses
USERNAME as the login field. Real apps often need:
  ✓ Email-based login (no username)
  ✓ Extra fields (phone, avatar, role, preferences) on the user itself
  ✓ Custom authentication behavior
```

## Sababu muhimu ya kuifanya KWANZA

```text
⚠️ Changing the user model AFTER migrations exist is VERY hard — the User model is
   referenced by auth, admin, sessions, foreign keys throughout the database.
   Swapping it later requires complex, risky data migrations.
→ ALWAYS define a custom user model at project START (before the first migration),
   even an empty one, so you can extend it freely later. Django's docs strongly
   recommend this for EVERY new project.
```

Hili ndilo somo kuu la kivitendo: linagharimu karibu chochote kuweka custom user model siku ya kwanza, lakini kuiweka kwenye project iliyoanzishwa ni kazi kubwa, yenye makosa mengi — hivyo unaifanya mapema kama bima.

## Vipi: kupanua AbstractUser (njia rahisi)

```python
# models.py — add fields, keep Django's auth behavior
from django.contrib.auth.models import AbstractUser

class User(AbstractUser):
    phone = models.CharField(max_length=20, blank=True)
    avatar = models.ImageField(upload_to="avatars/", blank=True)
    is_premium = models.BooleanField(default=False)
```

```python
# settings.py — tell Django to use it
AUTH_USER_MODEL = "myapp.User"
```

`AbstractUser` huhifadhi fields zote za default za Django na auth machinery — unaongeza fields tu. Mtindo rahisi zaidi, wa kawaida zaidi.

## Vipi: AbstractBaseUser (udhibiti kamili, k.m. email login)

```python
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager, PermissionsMixin

class User(AbstractBaseUser, PermissionsMixin):
    email = models.EmailField(unique=True)
    USERNAME_FIELD = "email"          # log in with EMAIL instead of username
    REQUIRED_FIELDS = []
    objects = CustomUserManager()     # a manager defining create_user/create_superuser
```

`AbstractBaseUser` hutoa udhibiti kamili juu ya user model (k.m. kuondoa username kabisa kwa email-only login) — kazi zaidi, lakini ubadilikaji wa juu zaidi.

## Kurejelea user model kwa usahihi

```python
from django.conf import settings
from django.contrib.auth import get_user_model

# in models — reference via settings.AUTH_USER_MODEL
author = models.ForeignKey(settings.AUTH_USER_MODEL, on_delete=models.CASCADE)

# in code — get the active user model dynamically
User = get_user_model()              # NOT a direct import of the default User
```

Kila wakati rejelea user model kupitia `settings.AUTH_USER_MODEL` (katika models) na `get_user_model()` (katika code), kamwe usi-import `User` ya default moja kwa moja — ili code yako ifanye kazi na custom model.

## Kwa nini ni muhimu

Kutumia custom user model ni maarifa muhimu yenye somo muhimu la kivitendo, linalosisitizwa mara kwa mara ambalo kila developer wa Django anapaswa kulielewa kwa kina: **liweke mwanzoni kabisa wa kila project**.

Sababu inayofanya hili kuwa muhimu sana ni tofauti kubwa ya ugumu — kufafanua custom user model siku ya kwanza (hata `AbstractUser` subclass tupu) hugharimu karibu chochote na hutoa ubadilikaji wa thamani kubwa, wakati kubadilisha kuwa custom user model *baada ya* project kuwa na migrations na data ni jambo gumu mno na lenye hatari, kwa sababu User model inarejelewa kwa kina katika Django nzima (authentication, admin, sessions) na na foreign keys katika database yako yote, ikihitaji data migrations tata, zenye makosa kubadilisha.

Hii ndiyo sababu documentation ya Django yenyewe inapendekeza kwa nguvu custom user model kwa kila project mpya, bila kujali hitaji la haraka — ni bima dhidi ya jinamizi la migration la baadaye.

Zaidi ya ushauri huu muhimu wa wakati, kuelewa *jinsi* ya kuunda custom user models — **`AbstractUser`** kwa kuongeza fields tu huku ukibakiza auth behavior ya Django (kisa cha kawaida, rahisi), na **`AbstractBaseUser`** kwa udhibiti kamili kama email-based login (kuondoa username kabisa) — ni jambo lenye thamani kwa kukidhi mahitaji halisi ya application (extra user fields, alternative login identifiers, custom auth).

Muhimu sawa ni kujua **kurejelea user model kwa usahihi** (kupitia `settings.AUTH_USER_MODEL` na `get_user_model()`, kamwe si direct import) ili code ifanye kazi na user model yoyote iliyosanidiwa.

Kwa kuwa karibu kila application halisi ina mahitaji maalum ya user zaidi ya defaults za Django (na hata zile zisizo nazo zinanufaika na ubadilikaji), na kwa kuwa gharama ya kutoiweka mapema ni kubwa sana, kuelewa custom user models — hasa lazima la kuanzisha moja mwanzoni mwa project — ni maarifa muhimu, ya lazima kivitendo yanayozuia kosa la kawaida na kubwa la kiwango cha project, ikifanya kuwa kipande cha hekima ya best-practice ya Django kinachotajwa mara kwa mara.