为何React+Flask项目的SQLAlchemy User模型需设置__tablename__？

我正在学习React+Flask应用开发，需要用SQLAlchemy创建数据模型，其中User模型代码如下：

class User(db.Model):
    __tablename__ = "users"
    id = db.Column(db.String, primary_key=True, unique=True, default=get_uuid)
    username = db.Column(db.String(50), nullable=False, unique=True)
    password = db.Column(db.Text, nullable=False)

我尝试移除__tablename__属性后，API就无法正常工作，但我之前创建的SQLAlchemy模型都没设置过这个属性，为什么这个模型必须设置？

其实SQLAlchemy（尤其是Flask-SQLAlchemy）并非强制要求设置__tablename__，它会默认根据模型类名生成表名——规则是将类名转为小写后复数化（比如User类默认生成users表）。你移除该属性后API失效，大概率是以下几种原因：

• API或关联代码硬编码了表名users
  如果你的API里有原生SQL查询（比如db.session.execute("SELECT * FROM users WHERE ...")），或者其他模型关联时指定了users相关的表名（比如多对多关联的中间表），当你移除__tablename__后，若SQLAlchemy自动生成的表名和users不一致（比如项目自定义了表名生成规则），就会导致找不到表，API报错。

• 数据库迁移历史的遗留问题
  如果最初你是带着__tablename__ = "users"创建的数据库迁移文件（比如用Flask-Migrate执行flask db migrate），数据库里已经存在users表。之后移除__tablename__后，新的迁移文件可能会试图创建自动生成的表名（比如意外生成user），但模型会指向这个新表，和数据库中已有的users不匹配，导致查询失败。

• 类名的自动表名生成不符合预期
  虽然默认规则下User会生成users，但如果项目中自定义了表名生成函数（比如修改了SQLALCHEMY_TABLE_NAME_GENERATOR配置），自动生成的表名可能不是users，这时候模型和实际数据库表名不匹配，API就无法正常工作。

你之前的模型没设置__tablename__也能正常工作，是因为那些模型的自动生成表名刚好和数据库表名、代码中的引用完全匹配，没有出现上述冲突情况。

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