在 Django 自定义 User 模型中，若将 username 设为 primary_key，直接赋值修改后调用 save() 会导致数据库误判为插入新记录，引发唯一约束冲突（如 email 重复）；根本解法是分离主键与业务字段，并采用安全更新方式。
在 django 自定义 user 模型中，若将 `username` 设为 `primary_key`，直接赋值修改后调用 `save()` 会导致数据库误判为插入新记录，引发唯一约束冲突（如 email 重复）；根本解法是分离主键与业务字段，并采用安全更新方式。
Django 的 ORM 在保存模型实例时，会根据主键（pk）是否存在来决定执行 INSERT 还是 UPDATE。当 username 同时作为主键和业务标识字段时，修改 userobj.username 实质上等同于修改主键值——Django 无法原地更新主键，因此会尝试插入一条新记录（保留原 email 等字段），从而触发 UNIQUE constraint failed 错误（例如 email 冲突）。
✅ 正确做法一：使用独立主键（推荐）
应始终为自定义 User 模型显式定义一个与业务逻辑解耦的主键（如自增 id），让 username 仅承担业务唯一性约束角色：
from django.contrib.auth.models import AbstractBaseUser, BaseUserManager
from django.core.validators import EmailValidator
from django.db import models
class UserManager(BaseUserManager):
def create_user(self, username, email, password=None, **extra_fields):
if not email:
raise ValueError('Email is required')
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
class User(AbstractBaseUser):
# ✅ 独立主键：由数据库自动生成，不参与业务逻辑
id = models.AutoField(primary_key=True) # 或 models.BigAutoField()
# ✅ username 仅为业务字段，保持 unique 但非主键
username = models.CharField(max_length=30, unique=True)
full_name = models.CharField(max_length=65, null=True, blank=True)
email = models.EmailField(
max_length=255,
unique=True,
validators=[EmailValidator()]
)
# 必需字段（Django auth 要求）
is_active = models.BooleanField(default=True)
is_staff = models.BooleanField(default=False)
objects = UserManager()
USERNAME_FIELD = 'username'
REQUIRED_FIELDS = ['email']
def __str__(self):
return self.username⚠️ 注意：修改主键类型后，需执行 python manage.py makemigrations 并迁移数据库（已有数据需谨慎处理，建议在开发早期完成此设计）。
✅ 正确做法二：安全更新 username（无需 save()）
若需批量或原子化修改 username，应避免实例化对象 + 修改 + save() 的流程，改用 QuerySet.update()——它直接生成 SQL UPDATE 语句，绕过 ORM 实例生命周期，高效且无主键陷阱：
# ✅ 安全、高效：直接 SQL UPDATE，不触发 save() 逻辑
old_username = "username1"
new_username = "newuser123"
updated_count = User.objects.filter(username=old_username).update(username=new_username)
if updated_count == 0:
print(f"Warning: No user found with username '{old_username}'")
else:
print(f"Successfully updated {updated_count} user(s)")该方式还天然支持事务封装：
from django.db import transaction
with transaction.atomic():
User.objects.filter(username="old").update(username="new")
# 其他关联操作...❌ 不推荐的临时方案（仅供理解原理）
虽然可通过重写 save() 强制走 UPDATE，但极易引入竞态条件与逻辑漏洞，且违背 Django 最佳实践：
# ❌ 不推荐：手动干预 save 行为，风险高、可维护性差
def save(self, *args, **kwargs):
if self.pk and 'username' in kwargs.get('update_fields', []):
# ... 复杂主键迁移逻辑（如复制旧记录、删除旧记录）
pass
super().save(*args, **kwargs)总结
- 核心原则：主键（primary_key=True）必须稳定、不可变、与业务无关；username 是典型业务字段，不应兼任主键。
- 首选方案：使用 AutoField/BigAutoField 作为主键，username 仅设 unique=True。
- 更新操作：优先使用 QuerySet.update() 替代实例 save()，尤其涉及唯一字段变更时。
- 验证环节：修改后务必检查 USERNAME_FIELD 和 REQUIRED_FIELDS 配置是否匹配新模型结构。
遵循以上规范，即可彻底规避因主键误用导致的完整性错误，构建健壮、可维护的 Django 用户系统。
