FastAPI多应用项目导入失败问题排查与结构优化需求

一、FastAPI多应用标准解耦结构 #

参照Django的模块化思路，适配FastAPI的轻量特性，推荐以下目录结构：

project_root/
├── config/
│   ├── __init__.py
│   ├── database.py       # 数据库连接、会话配置、Base模型基类
│   └── settings.py       # 环境变量、全局配置项
├── apps/
│   ├── recruiters/
│   │   ├── __init__.py
│   │   ├── models.py     # 招聘者业务模型
│   │   ├── routers.py    # 招聘者路由定义
│   │   ├── schemas.py    # Pydantic数据校验模型
│   │   └── views.py      # 招聘者业务逻辑处理
│   └── jobs/
│       ├── __init__.py
│       ├── models.py
│       ├── routers.py
│       ├── schemas.py
│       └── views.py
├── migrations/           # Alembic数据库迁移脚本目录
├── main.py               # FastAPI实例入口
└── requirements.txt

各模块职责说明：

• config/：统一管理数据库、全局配置，避免重复定义
• apps/：按业务领域拆分独立应用，每个应用内闭环管理模型、路由、逻辑，和Django的app结构对齐
• migrations/：使用官方推荐的Alembic做数据库迁移，替代自定义migrations.py，稳定性更强
• main.py：作为项目入口，负责挂载各应用路由、初始化全局组件

二、TypeError问题排查与修复 #

你遇到的function() argument 'code' must be code, not str错误，核心原因是路由注册或模块导入时，传入了字符串而非可调用对象/正确模块，以下是针对性修复方案：

1. 修正路由注册方式 #

FastAPI路由需要直接绑定可调用的视图函数，不能用字符串路径引用：

# apps/recruiters/routers.py
from fastapi import APIRouter
from .views import get_recruiters_list

router = APIRouter(prefix="/recruiters", tags=["Recruiters"])

# 正确写法：直接绑定视图函数
router.get("/")(get_recruiters_list)

然后在main.py中统一挂载路由：

# main.py
from fastapi import FastAPI
from apps.recruiters.routers import router as recruiters_router
from apps.jobs.routers import router as jobs_router

app = FastAPI()

app.include_router(recruiters_router)
app.include_router(jobs_router)

2. 替换自定义migrations.py为Alembic #

自定义迁移脚本容易出现代码执行错误，推荐用Alembic标准化处理：

• 安装依赖：pip install alembic
• 初始化迁移目录：alembic init migrations
• 修改alembic.ini中的sqlalchemy.url，和config/database.py的数据库URL保持一致
• 在config/__init__.py中导入所有业务模型，让Alembic能检测到：

  # config/__init__.py
  from apps.recruiters.models import Recruiter
  from apps.jobs.models import Job
  

• 生成迁移脚本：alembic revision --autogenerate -m "init tables"
• 执行迁移：alembic upgrade head

3. 修正模块导入路径 #

确保项目根目录在Python的搜索路径中，可在main.py开头添加：

import sys
from pathlib import Path

sys.path.append(str(Path(__file__).parent))

应用内部优先使用相对导入（如from .views import xxx），避免因绝对路径错误导致模块未正确加载。

三、核心注意事项 #

• FastAPI没有Django的自动app注册机制，必须手动在main.py中include_router挂载各应用路由
• 所有业务模型需继承config/database.py中定义的Base基类，确保数据库表结构能被Alembic识别
• 数据库会话通过依赖注入统一管理，示例：

  # config/database.py
  from sqlalchemy import create_engine
  from sqlalchemy.ext.declarative import declarative_base
  from sqlalchemy.orm import sessionmaker
  
  SQLALCHEMY_DATABASE_URL = "sqlite:///./test.db"
  
  engine = create_engine(SQLALCHEMY_DATABASE_URL, connect_args={"check_same_thread": False})
  SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
  
  Base = declarative_base()
  
  def get_db():
      db = SessionLocal()
      try:
          yield db
      finally:
          db.close()
  

  在视图函数中通过依赖注入获取会话：

  # apps/recruiters/views.py
  from fastapi import Depends
  from sqlalchemy.orm import Session
  from config.database import get_db
  from .models import Recruiter
  
  def get_recruiters_list(db: Session = Depends(get_db)):
      return db.query(Recruiter).all()
  

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