FastAPI搭配SQLAlchemy 2.0出现ImportError的问题求助

问题核心 #

你遇到的ImportError: cannot import name 'DeclarativeBase' from 'sqlalchemy.orm'本质是运行FastAPI时的Python环境中，SQLAlchemy版本低于2.0.0——DeclarativeBase是SQLAlchemy 2.0才引入的新特性，旧版本没有这个类。

为什么注释FastAPI代码后能正常运行？因为此时脚本直接在你安装了SQLAlchemy 2.0的环境里执行；而启动FastAPI时，可能用了另一个未更新SQLAlchemy的环境（比如全局Python环境、未激活的虚拟环境）。

解决步骤 #

• 确认环境版本一致性
  在脚本开头添加版本打印代码，分别在注释/不注释FastAPI代码的情况下运行，对比输出的版本号：

  import sqlalchemy
  print("当前SQLAlchemy版本:", sqlalchemy.__version__)
  

  如果两个场景版本不同，说明启动FastAPI时用错了环境。

• 确保FastAPI使用正确的虚拟环境
  如果你用了虚拟环境，先激活它，再运行脚本或用uvicorn直接启动：

  # 激活虚拟环境（以venv为例）
  source venv/bin/activate  # macOS/Linux
  venv\Scripts\activate     # Windows
  # 启动FastAPI
  python your_script.py
  # 或者用uvicorn直接启动
  uvicorn your_script:app --host 127.0.0.1 --port 8000
  

• 强制安装指定版本的SQLAlchemy
  在正确的环境下执行命令，确保安装的是2.0及以上版本：

  pip install --upgrade sqlalchemy>=2.0.0
  

  FastAPI与SQLAlchemy 2.0没有已知兼容性问题，两者可以正常配合使用。

• 修复代码中的类型错误
  你的AddUser模型里age定义为str，但User数据库模型里age是Mapped[int]，直接赋值会导致数据库类型错误，需要修改AddUser：

  class AddUser(BaseModel):
      name: str
      age: int  # 改为int类型
  

  另外，FastAPI的接口不需要手动json.dumps，直接返回字典即可，框架会自动处理JSON序列化：

  @app.post("/users/")
  async def post_user(add_user: AddUser):
      with Session(engine) as session:
          user = User(name=add_user.name, age=add_user.age)
          session.add(user)
          session.commit()
          session.refresh(user)  # 刷新获取数据库生成的id等字段
      return {"name": user.name, "age": user.age}
  

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