FastAPI应用报错ModuleNotFoundError：如何修复找不到api模块问题

我正在开发一个FastAPI应用，项目结构如下：

/tmp/AbhipQN/url-shortner
    - backend
        - api
            - routes.py
        - app
            - main.py
        - core
        - services
            - url_shortner.py
        - utils
    - frontend
        - node_modules
        - public
        - src 

后端代码如下：

main.py #

from fastapi import FastAPI
from api.routes import shorturl_router

app = FastAPI()
app.include_router(router=shorturl_router, prefix="/api")

routes.py #

from fastapi import APIRouter
from api.schemas import ShortUrlRequest, ShortUrlResponse
from services.url_shortner import url_shortner

shorturl_router = APIRouter()

@shorturl_router.post("/short-url")
async def short_url(req: ShortUrlRequest):
    short_url = await url_shortner(req.url)
    return ShortUrlResponse(short_url=short_url)

执行以下命令启动服务时：

cd /tmp/AbhipQN/url-shortner/backend
fastapi dev app/main.py

出现错误：

ModuleNotFoundError: No module named 'api'

需要修复该模块找不到的问题，让FastAPI能正确定位api等模块。

1. 标记目录为Python包 #

Python要求目录下存在__init__.py文件才会将其识别为可导入的包。给以下目录添加空的__init__.py文件：

• backend/api/
• backend/app/
• backend/services/
• backend/core/
• backend/utils/

示例创建命令：

touch /tmp/AbhipQN/url-shortner/backend/api/__init__.py
touch /tmp/AbhipQN/url-shortner/backend/app/__init__.py
touch /tmp/AbhipQN/url-shortner/backend/services/__init__.py

2. 调整导入路径与启动方式 #

方法A：使用相对导入修改代码 #

由于main.py在backend/app/目录下，api是与app同级的目录，可将main.py的导入改为相对路径：

from fastapi import FastAPI
from ..api.routes import shorturl_router

app = FastAPI()
app.include_router(router=shorturl_router, prefix="/api")

同时修改routes.py中的内部导入为相对路径：

from fastapi import APIRouter
from .schemas import ShortUrlRequest, ShortUrlResponse  # 改为相对导入
from ..services.url_shortner import url_shortner

shorturl_router = APIRouter()

@shorturl_router.post("/short-url")
async def short_url(req: ShortUrlRequest):
    short_url = await url_shortner(req.url)
    return ShortUrlResponse(short_url=short_url)

方法B：设置PYTHONPATH启动服务 #

启动时将backend目录加入Python的模块搜索路径，这样可以保留原有的绝对导入写法：

cd /tmp/AbhipQN/url-shortner
PYTHONPATH=./backend fastapi dev backend/app/main.py

3. 优化项目结构（推荐） #

将main.py移至backend根目录，让backend作为项目的根包，结构调整为：

/tmp/AbhipQN/url-shortner
    - backend
        - __init__.py
        - api
            - __init__.py
            - routes.py
            - schemas.py
        - services
            - __init__.py
            - url_shortner.py
        - main.py  # 移至此处
    - frontend
        ...

启动命令改为：

cd /tmp/AbhipQN/url-shortner
fastapi dev backend/main.py

此时main.py和routes.py的原有绝对导入写法无需修改，Python会自动从backend目录识别模块。

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