Flask应用无法导入领域模块及flask run启动失败求助

问题背景 #

正在学习《Architecture Patterns with Python》一书，参照第四章目录结构重构应用，项目目录结构如下：

src/
  peaked/
     domain/
       __init__.py 
       models.py
     api/
       __init__.py 
       flask_api.py        
     dataaccess/
       __init__.py 
       orm.py
       repository.py
  __init__.py   
  setup.py

repository.py和orm.py可通过from domain import models正常导入领域模块，顶层tests目录的单元测试也能正常导入domain及dataaccess的类和函数，但在flask_api.py中使用相同导入语句时，会出现ModuleNotFoundError，提示“no module named domain”。

当前启动Flask应用的方式及问题：

• 通过python src/peaked/api/flask_api.py启动：无导入时可正常运行，添加导入后报错；
• 尝试flask run启动：设置set FLASK_APP=src/peaked/api/flask_api.py后，提示无法找到Flask应用。

setup.py内容如下：

from setuptools import setup

setup(
    name="peaked",
    version="0.1",
    packages=["peaked"],
)

为什么其他文件可正常导入，Flask应用却不行？ #

核心原因是Python模块导入的路径机制差异：

• repository.py、orm.py以及单元测试的运行上下文是基于peaked包的：要么是从项目根目录启动（此时src目录被加入sys.path，peaked作为可导入包存在），要么是本地包已安装，Python能识别peaked下的子模块（如domain），因此from domain import models这种同包内子模块的导入能生效。
• 直接运行flask_api.py时，Python会把脚本所在的目录（src/peaked/api）加入sys.path的最前端，此时domain模块不在sys.path的可见范围内，自然无法找到；而用文件路径设置FLASK_APP时，Flask的启动逻辑同样会面临相同的路径问题，无法识别peaked包结构下的子模块。

另外，from domain import models属于隐式相对导入，在Python 3中这种写法仅在包内部模块被作为包的一部分导入时才有效，直接运行脚本时会被当作绝对导入处理，导致找不到模块。

子目录下的Flask应用正确设置流程 #

1. 修复导入语句 #

将flask_api.py中的导入语句改为绝对导入，确保适配包上下文：

# 替换 from domain import models
from peaked.domain import models

或使用显式相对导入（仅适用于包内部模块，不推荐直接运行脚本时使用）：

from ..domain import models

2. 以开发模式安装本地包 #

在src目录下（即setup.py所在目录）运行以下命令，将peaked包安装到Python环境的开发模式（包内容修改后无需重新安装）：

pip install -e .

3. 正确配置FLASK_APP并启动 #

FLASK_APP需要使用包路径而非文件路径，具体命令：

• Windows系统：

set FLASK_APP=peaked.api.flask_api
flask run

• Linux/macOS系统：

export FLASK_APP=peaked.api.flask_api
flask run

运行命令时需确保当前目录是src的上级目录（即包含src的目录），或已将src目录加入PYTHONPATH。

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