使用Flask+SQLAlchemy添加新用户时触发IntegrityError问题

错误根源 #

你的User模型中username字段设置了unique=True约束，这要求数据库中不能存在两个用户名相同的用户。报错信息里的Joey.O这个用户名已经存在于数据库中，再次提交时触发了SQLite的唯一约束校验，导致报错。

解决方案 #

方案1：提交前检查用户名是否已存在（推荐） #

在处理表单提交时，先查询数据库确认用户名未被占用，若已存在则返回表单页面并提示错误：

修改create_user视图函数：

@app.route('/create_user', methods=['GET', 'POST'])
def create_user():
    if request.method == 'POST':
        username = request.form['username']
        # 查询是否已有同名用户
        existing_user = db.session.execute(db.select(User).where(User.username == username)).scalar_one_or_none()
        if existing_user:
            return render_template('create_user.html', title='Create User', error="该用户名已存在，请更换")
        
        user = User(
            username=username,
            email=request.form['email'],
        )
        db.session.add(user)
        db.session.commit()
        # 移除多余的id参数，user_list视图不需要接收该参数
        return redirect(url_for('user_list'))
        
    return render_template('create_user.html', title='Create User')

同时在create_user.html中添加错误提示渲染：

{% if error %}
    <p style="color: red;">{{ error }}</p>
{% endif %}

方案2：捕获异常避免程序崩溃 #

即使做了前置检查，仍可能因并发等极端情况触发约束错误，此时可以捕获异常并处理：

from sqlalchemy.exc import IntegrityError

@app.route('/create_user', methods=['GET', 'POST'])
def create_user():
    if request.method == 'POST':
        user = User(
            username=request.form['username'],
            email=request.form['email'],
        )
        db.session.add(user)
        try:
            db.session.commit()
            return redirect(url_for('user_list'))
        except IntegrityError:
            # 回滚事务，避免脏数据
            db.session.rollback()
            return render_template('create_user.html', title='Create User', error="该用户名已存在，请更换")
        
    return render_template('create_user.html', title='Create User')

方案3：取消用户名唯一约束（不推荐） #

如果你的业务逻辑允许重复用户名，可以移除unique=True约束：

class User(db.Model):
    id: Mapped[int] = mapped_column(primary_key=True)
    username: Mapped[str]  # 去掉unique=True约束
    email: Mapped[str]

注意：修改模型后需要更新数据库，可删除旧的project.db文件重启应用重建表，或使用Flask-Migrate工具做数据库迁移。

内容的提问来源于stack exchange，提问作者Iyanu Okunnuga