FastAPI第三方库：如何实现模型迁移及告知配置需求？

在FastAPI生态里，没有Django那种内置的模型迁移和统一配置系统，但可以通过Pydantic和主流ORM工具（SQLAlchemy/SQLModel）实现类似的第三方库能力，下面分两部分说明：

一、告知用户所需配置 #

FastAPI原生依赖Pydantic，第三方库可以基于pydantic-settings定义配置模型，既支持环境变量加载，也能无缝集成到用户的FastAPI依赖注入体系中。

实现步骤： #

1. 定义配置模型：用带前缀的Pydantic Settings类明确必填/可选配置项，避免和用户项目配置冲突：

# my_library/config.py
from pydantic_settings import BaseSettings, SettingsConfigDict

class MyLibSettings(BaseSettings):
    model_config = SettingsConfigDict(env_prefix="MY_LIB_")
    
    # 必填配置项
    database_url: str
    # 可选配置项（带默认值）
    api_timeout: int = 30
    debug_mode: bool = False

2. 提供配置获取方式：可以提供全局实例，或者让用户通过依赖注入获取：

# my_library/__init__.py
from .config import MyLibSettings

# 全局配置实例（用户可通过环境变量覆盖）
lib_settings = MyLibSettings()

# 或者提供依赖注入用的函数
def get_lib_settings() -> MyLibSettings:
    return MyLibSettings()

3. 文档说明：在库的README里清晰列出所有配置项、环境变量前缀、默认值，比如：

配置项说明：

• MY_LIB_DATABASE_URL：必填，数据库连接字符串
• MY_LIB_API_TIMEOUT：可选，API请求超时时间，默认30秒
• MY_LIB_DEBUG_MODE：可选，调试模式开关，默认False

用户在项目中可以直接导入配置类，或通过依赖注入使用：

# 用户项目代码
from fastapi import Depends, FastAPI
from my_library import get_lib_settings

app = FastAPI()

@app.get("/lib-status")
async def get_lib_status(settings=Depends(get_lib_settings)):
    return {"debug_mode": settings.debug_mode, "timeout": settings.api_timeout}

二、提供依赖数据库表的功能 #

FastAPI没有内置ORM，但社区主流用SQLAlchemy或SQLModel，第三方库可以提供预定义的ORM模型，让用户集成到自己的数据库体系中，并指导生成迁移文件。

基于SQLAlchemy的实现： #

1. 定义库的模型：

# my_library/models.py
from sqlalchemy import Column, Integer, String, DateTime
from sqlalchemy.ext.declarative import declarative_base
from datetime import datetime

LibBase = declarative_base()

class ScheduledTask(LibBase):
    __tablename__ = "my_lib_scheduled_tasks"
    
    id = Column(Integer, primary_key=True, index=True)
    task_name = Column(String(255), index=True, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

2. 指导用户集成：告诉用户将库的模型元数据合并到自己的项目中：

# 用户项目的database.py
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from my_library.models import LibBase

UserBase = declarative_base()
UserBase.metadata = LibBase.metadata

engine = create_engine("postgresql://user:pass@db:5432/mydb")
UserBase.metadata.create_all(bind=engine)

3. 迁移指导：如果用户用Alembic做迁移，指导他们在alembic/env.py中导入库的模型：

# alembic/env.py
from my_library.models import ScheduledTask
from my_project.database import UserBase

target_metadata = UserBase.metadata

基于SQLModel的实现（更简洁）： #

SQLModel同时支持Pydantic和SQLAlchemy，第三方库可以直接定义带table=True的模型：

# my_library/models.py
from sqlmodel import SQLModel, Field
from datetime import datetime

class ScheduledTask(SQLModel, table=True):
    __tablename__ = "my_lib_scheduled_tasks"
    
    id: int | None = Field(default=None, primary_key=True)
    task_name: str = Field(index=True, max_length=255)
    created_at: datetime = Field(default_factory=datetime.utcnow)

用户只需导入该模型，在自己的SQLModel初始化中包含即可，迁移同样用Alembic，在env.py中导入模型就能生成对应的迁移脚本。

内容的提问来源于stack exchange，提问作者Альберт Александров