在 Cursor 中开发 Python 项目时，通常需要将单个 .py 文件拆分为 src/core、src/utils、src/models 等模块目录，并通过创建 __init__.py、迁移业务逻辑、配置 pyproject.toml 以及验证模块导入，确保项目具备更好的可维护性、复用性和团队协作效率。

在 Cursor 中开发 Python 项目时，如果想让代码结构更清晰、后期维护更轻松、多人协作更顺畅，同时提升代码复用能力，就必须把单个 .py 文件拆分成多个模块。这并不是为了追求形式，而是当业务逻辑超过 200 行、团队新增第二位开发者，或项目需要接入测试与部署流水线时，若仍然保持单文件结构，往往会在调试效率、代码管理和合并冲突上遇到明显瓶颈。

确认项目根目录并创建标准包结构

打开 Cursor 左侧文件树，右键点击项目根目录 → 选择“New Folder”，命名为 src。这一步非常关键，不能省略，否则后续 Python 模块导入路径很容易出现混乱。

在 src 目录下继续新建子目录 core、utils、models，然后在每个子目录中右键 → “New File”，命名为 __init__.py。这个空文件是 Python 识别包结构的重要标志，缺少它时，import 通常会报出 ModuleNotFoundError。

把已有逻辑按职责迁移到对应模块

方法一：从 main.py 或 app.py 中提取核心业务逻辑

将 main.py 中所有与用户认证相关的函数统一选中，例如 login、logout、validate_token，剪切后粘贴到 src/core/auth.py 中。迁移过程中要特别注意，原文件中的 docstring 和类型注解必须完整保留，同时不要删除 if __name__ == "__main__" 块——这部分现在可以作为 auth.py 自身的测试入口使用。

方法二：把重复出现的工具函数集中管理

先在整个项目里进行搜索，可以发现一共会找到 3 处 使用了 datetime.now().strftime("%Y-%m-%d") 的位置。接下来新建 src/utils/time.py，并统一封装为一个函数：def today_str() -> str: return datetime.now().strftime("%Y-%m-%d")。完成后，再把这 3 处原有调用逐一替换为通过 from src.utils.time import today_str 进行导入和使用，这样更方便后续统一维护与修改。

【迁移完成后一定要删除原位置的重复代码，否则很容易埋下逻辑不一致和后续维护困难的隐患】

配置Cursor智能导入补全

第一步：打开 Cursor 设置 → 搜索“Python Path” → 在“Python › Default Interpreter Path”中确认已经指向项目虚拟环境的 Python 解释器（如 venv/bin/python）。

第二步：在项目根目录下创建 pyproject.toml 文件，写入：

[tool.black]
line-length = 88
skip-string-normalization = true

[tool.mypy]
python_version = "3.11"
disallow_untyped_defs = true

第三步：重启 Cursor 窗口。此时在任意 .py 文件中输入“from src.”，Cursor 通常会自动弹出 core、utils、models 三个包名提示；继续输入“from src.core.auth import ”，则会更精准地列出 login、logout 等函数名称。

验证模块拆分是否生效

步骤一：在项目根目录新建 test_split.py

步骤二：写入以下代码并运行：

from src.core.auth import login
from src.utils.time import today_str
print(login("admin", "123"))
print(today_str())

步骤三：观察终端输出。如果打印出预期结果（例如 True 和当天日期字符串），就说明 Python 项目的模块拆分已经生效，模块路径解析正常，跨目录导入也已成功。