FastAPI项目：UUID自动赋值应在模型还是Alembic迁移中处理？

问题描述 #

我有一个FastAPI应用，在Item表中id字段为UUID。想知道应在models.py中还是Alembic迁移文件中处理id的自动赋值？

目前我的模型代码如下：

class ItemDb(SQLMODEL, table=True):
    __tablename__ = "items"
    id: str = Field(
        default_factory=uuid.uuid4, primary_key=True, index=True, nullable=False
    )

迁移文件代码为：

sa.Column("id", sa.String(), nullable=False),

这种处理id的方式是否合理？有没有更优方案，比如让PostgreSQL在插入新行时自动生成UUID？

补充：我曾尝试修改如下：
模型：

class ItemDb(SQLMODEL, table=True):
        __tablename__ = "items"
        id: str = Field(
            primary_key=True, index=True, nullable=False
        )

迁移：

sa.Column("id", UUID(as_uuid=True), primary_key=True, default=uuid.uuid4),

但出现报错，提示id为None。

现有方案的合理性 #

• 当前在模型层使用default_factory=uuid.uuid4的方式完全合理：
  • 逻辑集中在模型层，代码易维护，无需同时改动模型和迁移文件
  • UUID生成逻辑由Python控制，跨数据库兼容，切换数据库时无需调整主键生成规则
  • 小优化点：迁移文件中可将sa.String()改为UUID(as_uuid=True)，让字段类型更贴合UUID，避免字符串与UUID类型的隐式转换

更优方案：PostgreSQL自动生成UUID #

如果想让数据库层面自动生成UUID，需同时调整模型和迁移文件，解决之前的报错问题：

1. 修改模型定义 #

将id类型改为UUID，设置default=None（让数据库处理默认值），并通过server_default指定PostgreSQL原生的UUID生成函数：

from sqlalchemy.dialects.postgresql import UUID
from sqlalchemy.sql import text
from uuid import UUID as PythonUUID  # 避免命名冲突

class ItemDb(SQLMODEL, table=True):
    __tablename__ = "items"
    id: PythonUUID = Field(
        primary_key=True, 
        index=True, 
        nullable=False,
        default=None,  # 告知SQLModel不在Python端生成值
        server_default=text("gen_random_uuid()")  # PostgreSQL内置UUID生成函数
    )

2. 生成并确认迁移文件 #

运行alembic revision --autogenerate生成迁移文件，此时id字段的定义应类似：

sa.Column("id", UUID(as_uuid=True), server_default=sa.text("gen_random_uuid()"), nullable=False, primary_key=True),

这样设置后，插入数据时若不指定id，PostgreSQL会自动调用gen_random_uuid()生成UUID，不会出现id为None的报错。

之前修改报错的原因 #

你之前仅在迁移文件中添加了default=uuid.uuid4，但模型层未声明该字段的默认值由数据库提供。SQLModel会认为id是必填字段，不会主动从数据库获取默认值，因此抛出id为None的错误。必须通过server_default让模型层感知数据库端的默认值逻辑。

两种方案对比 #

• 模型层生成（当前方案）：优势是跨数据库兼容，逻辑统一在代码层，适合多数据库场景；缺点是UUID生成在应用端，数据库无法感知生成逻辑。
• 数据库层生成：优势是数据库原生支持，性能更优，适合固定使用PostgreSQL的场景；缺点是与数据库绑定，切换数据库需调整规则。

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