在 Django 自定义 User 模型中，若将 username 设为 primary_key，直接修改其值并调用 .save() 会导致数据库误判为插入新记录，从而触发唯一约束冲突（如邮箱重复）。根本解法是分离主键与业务字段，并采用安全更新方式。
在 django 自定义 `user` 模型中，若将 `username` 设为 `primary_key`，直接修改其值并调用 `.save()` 会导致数据库误判为插入新记录，从而触发唯一约束冲突（如邮箱重复）。根本解法是分离主键与业务字段，并采用安全更新方式。
在 Django 中，自定义用户模型时需格外注意主键（primary_key）的设计语义。当 username 被设为 primary_key（如 username = models.CharField(..., primary_key=True)），Django 的 ORM 在检测到主键值变更后，会默认执行 INSERT 而非 UPDATE —— 即使对象已存在于数据库中。这是因为 Django 将主键视为对象身份标识（identity），一旦改变，即等同于“创建一个新实体”。这直接导致后续保存时尝试插入一条具有相同 email（或其他唯一字段）的新记录，从而抛出 IntegrityError: UNIQUE constraint failed。
✅ 正确做法：主键与业务字段解耦
应使用独立、不可变的主键（如自增 id 或 UUID），而将 username 作为普通唯一字段管理：
from django.contrib.auth.models import AbstractBaseUser
from django.core.validators import EmailValidator
from django.db import models
class User(AbstractBaseUser):
# ✅ 推荐：使用自增整数主键（稳定、无业务含义）
id = models.AutoField(primary_key=True)
# ✅ username 是业务字段，保持唯一性但不承担主键职责
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()]
)
# ⚠️ 必须显式定义 USERNAME_FIELD 和 REQUIRED_FIELDS
USERNAME_FIELD = 'username'
REQUIRED_FIELDS = ['email']
# ... 其他必需方法（如 get_full_name, has_perm 等）需按 AbstractBaseUser 规范实现如此设计后，修改用户名可安全使用实例 .save()：
user = User.objects.get(username="username1") user.username = "new_username".lower() user.save() # ✅ 正常执行 UPDATE，不会触发唯一冲突
? 替代方案：批量更新（无需实例化）
若仅需更新 username 字段（且不依赖信号或模型级逻辑），推荐使用 QuerySet.update() —— 它绕过模型实例生命周期，直接生成 SQL UPDATE 语句，性能更高、事务更轻量：
# ✅ 安全、高效、原子性更新
updated_count = User.objects.filter(username="username1").update(username="new_username".lower())
print(f"Updated {updated_count} user(s)") # 输出：Updated 1 user(s)⚠️ 注意：update() 不会触发 save() 相关钩子（如 pre_save/post_save 信号）、不会调用模型 clean() 方法，也不校验字段逻辑（如 max_length）。仅适用于简单字段更新场景。
? 关键注意事项总结
- 永远不要将可变业务字段（如 username、email、phone）设为 primary_key：主键应具备稳定性、不可变性与无业务语义。
- 自定义用户模型必须明确定义 USERNAME_FIELD：否则认证系统无法识别登录凭据字段。
- 迁移已有数据时需谨慎：若原模型已上线，需编写数据库迁移脚本（python manage.py makemigrations --empty your_app）先添加 id 字段并填充唯一值，再移除 username 的 primary_key=True。
- 验证与安全性：username 更新前建议校验格式（如正则）、长度及是否已被占用（可通过 exclude(pk=user.pk) 避免自检冲突）。
遵循以上原则，即可彻底规避因主键设计不当引发的更新异常，构建健壮、可维护的 Django 用户系统。
