从0到1搭建Python多模块项目结构

先搞懂：为啥单文件脚本撑不起正经项目？

你可能会说：“我就写个小工具，用单文件跑起来不就行了？” 这话没错，但只要项目超过300行代码，或者需要多人合作，单文件的麻烦就来了。我去年帮朋友改他的个人博客后端，他把路由、数据库操作、工具函数全塞在app.py里，结果想加个“文章点赞”功能，改了3行代码，整个登录功能突然崩了——因为函数调用关系乱成一团。后来我跟他说：“模块就像衣柜的抽屉，T恤、裤子、袜子分开装，找的时候才方便；要是堆一起，翻半天还容易弄乱。” 他这才明白，多模块不是“高级操作”，而是帮你“少踩坑”的基础。

其实Python官方早就推荐多模块开发，在Python文档的“项目结构”章节（已添加nofollow）里就提到：“合理的模块划分能显著提升代码复用性和可维护性”。所以别等项目“烂尾”了才想起重构，从一开始就搭好结构，反而更省时间。

3步搭出“抗揍”的目录结构

我 了一套零基础也能上手的“傻瓜式步骤”，你跟着做就行：

第1步：用“功能脑图”拆分模块

先别着急写代码，拿张纸（或用XMind）画一画：你的项目要实现哪些核心功能？比如写个学生管理系统，可能需要“用户登录”“成绩录入”“数据查询”“数据存储”这几个功能。每个功能就是一个潜在的模块，比如负责数据存储的模块，就叫data_storage；负责用户交互的，叫user_interface。我通常会把功能拆到“一个模块只做一件事”为止，比如“数据存储”里再细分“文件存储”和“数据库存储”，这样以后想换存储方式，改一个模块就行，不用动其他地方。

第2步：按“标准模板”建目录

拆分完功能，就可以建目录了。这里给你一个我常用的基础模板，不管是写工具库还是小型Web项目都能用，你直接复制改名字就行：

目录/文件	类型	作用说明
my_project/	项目根目录	存放所有文件，用项目名命名
my_project/main.py	入口文件	程序启动入口，调用其他模块
my_project/utils/	工具包	放通用函数，如日志、加密、格式转换
my_project/models/	模型包	定义数据结构，如用户类、成绩类
my_project/services/	服务包	实现核心业务逻辑，如登录验证、成绩计算
my_project/tests/	测试包	存放单元测试代码，确保模块能用
my_project/__init__.py	包标识文件	空文件即可，告诉Python这是个包

表：Python多模块项目基础目录结构（新手友好版）

你可能注意到每个目录里都有__init__.py，这文件就像“门牌号”，告诉Python“这是个包，可以被导入”。早期Python必须有这个文件，现在3.3+版本可以没有，但我 你加上，一方面兼容旧环境，另一方面可以在里面写点“初始化代码”，比如from . import module1，让导入更方便。

第3步：用“依赖图”检查模块关系

搭好目录后，别急着写代码，画一张“模块依赖图”：A模块用到了B模块的函数，就画个箭头从A指向B。记住一个原则：别让箭头绕圈。比如A依赖B，B又依赖A，这就是“循环依赖”，后面会出大问题。我之前写一个数据分析工具，就犯过这错——data_process.py调用visualize.py的画图函数，visualize.py又调用data_process.py的数据清洗函数，结果一运行就报错“AttributeError: partially initialized module”。后来我加了个common.py放共享函数，才解开这个“死结”。你可以用draw.io（已添加nofollow）画依赖图，免费又好用，亲测能帮你提前发现80%的结构问题。

实战避坑：搞定多模块开发中的常见问题

坑1：“No module named XXX”——导入路径到底怎么写？

你肯定遇到过这种情况：明明文件就在那里，import的时候就是提示“找不到模块”。我刚开始学多模块时，为这个问题卡了整整一下午。后来才发现，Python找模块的“眼光”和我们不一样——它只认“sys.path”里的路径，就像你去图书馆找书，只会看目录索引里有的书架，没在索引里的书架，哪怕书就在旁边也看不到。

比如你的项目结构是my_project/services/user_service.py，想在main.py里导入user_service，直接写import services.user_service可能报错，因为Python可能没把my_project加到“索引”里。解决办法有两个，我通常推荐第二个（更规范）：

临时方案：在main.py开头加两行代码，把项目根目录加到sys.path：

 import sys
 from pathlib import Path
 sys.path.append(str(Path(__file__).parent)) # __file__是当前文件路径，parent是它的父目录（即my_project）
 
规范方案：用-m参数运行。在命令行进入my_project的父目录，执行python -m my_project.main，Python会自动把父目录加到sys.path，这样import services.user_service就能正常工作了。
这里有个小技巧：用VS Code开发时，右键项目根目录，选“将文件夹添加到工作区”，再在.vscode/settings.json里加一句"python.autoComplete.extraPaths": ["./"]，编辑器就会帮你识别模块路径，写代码时还能自动补全，超方便。
坑2：相对导入vs绝对导入——到底用哪个？
写多模块时，你可能见过两种导入方式：from . import module（相对导入）和from my_project.services import user_service（绝对导入）。我之前踩过的坑是：在main.py里用相对导入，结果运行时报“Attempted relative import with no known parent package”。后来查文档才知道，直接运行的文件（如main.py）被视为“顶层模块”，不能用相对导入，相对导入只能在“包内部的模块”里用。
举个例子：在services/user_service.py里导入models/user.py，可以用相对导入from ..models import user（..表示上一级目录）；但在main.py里导入user_service，就必须用绝对导入from services import user_service。记不住的话，可以简单粗暴一点：除了测试文件，其他地方优先用绝对导入，虽然多写几个字，但不容易出错。
坑3：模块里的“全局变量”怎么共享才安全？
新手常犯的错是：在A模块定义个全局变量config = {}，B模块和C模块都去改它，结果运行时数据乱成一锅粥。我之前帮一个团队排查bug，就发现他们的global_config.py被5个模块同时修改，今天加个“debug模式”，明天加个“超时设置”，最后谁也说不清config里到底有啥。后来我 他们用“单例模式”封装配置，就像做一个带锁的抽屉，只能通过固定的“钥匙”（方法）存取，这样谁改了什么一目了然。
简单实现的话，可以在utils/config.py里写：

python

class Config:

_instance = None

def __new__(cls):

if cls._instance is None:

cls._instance = super().__new__(cls)

cls._instance.data = {} # 实际配置存在这里

return cls._instance

其他模块用的时候：

from utils.config import Config

config = Config()

config.data[“debug”] = True # 这样不管多少模块导入，都是同一个Config实例，数据不会乱

亲测这个方法比直接用全局变量安全10倍，尤其适合多人协作的项目。

最后想跟你说，多模块开发就像搭积木，刚开始可能觉得麻烦，但搭顺手了，你会发现自己写的代码不仅别人能看懂，过一个月自己回头看也清清楚楚。如果你按今天说的步骤搭了项目，遇到解决不了的问题，或者有更好的结构技巧，欢迎在评论区告诉我——技术这东西，越交流越明白嘛！

---

你可能会想：“就一百行代码的小工具，费劲拆模块干嘛？写一个文件跑起来多省事啊。”这话我特理解——我刚学Python那会儿，写个批量重命名脚本也就80行，直接堆在main.py里，改起来确实快。但后来我发现个事儿：哪怕是小项目，只要你打算“以后可能还要用”，稍微拆一下反而更省心。

比如你写个简单的股票价格查询工具，核心功能就是“调API拿数据”和“打印结果”。你要是把API请求的代码（比如处理url、加请求头、解析json）单独放一个utils.py，主逻辑（用户输入股票代码、调用工具函数、输出结果）放main.py，也就多建两个文件的事儿。但下次你想加个“保存到Excel”的功能，直接在utils.py里加个save_to_excel函数，main.py里调用一下就行，根本不用翻原来的代码——你想想，要是全堆在一个文件里，加功能时得先找到原来的API请求代码在哪儿，万一不小心删了一行，整个工具都崩了，多不值当。

我带过两个实习生，都是刚毕业的。小王写小工具总说“代码少，不用拆”，一个文件从头写到尾；小李呢，哪怕写个150行的爬虫，也会拆成request_utils.py（处理网络请求）、parse_utils.py（解析网页）、main.py（控制流程）。后来团队做一个中等规模的项目，需要拆成10多个模块，小王光理清楚“哪个模块该放什么”就卡了三天，而小李两天就搭好了基础框架，还没出现循环依赖的问题。你看，多模块思维不是说非得用在大项目上，而是像整理房间——哪怕东西少，衣服归衣服、袜子归袜子，下次找的时候才快，而且习惯了整齐，以后东西多了也乱不了。所以啊，小项目拆分模块，不是给当前添麻烦，是给 的自己省时间。

---

如何判断自己的项目是否需要拆分成多模块？

可以从三个维度判断：代码量超过300行时，单文件查找和修改会变慢；需要多人协作时，多模块能避免代码冲突；功能需要复用时（比如多个地方都要用到数据验证），拆分成模块能减少重复代码。刚开始可以先按“一个功能一个模块”的简单原则拆分，后续再优化，比等到项目混乱后重构更高效。

项目结构搭好后，如果功能增加，该如何调整模块划分？

新增功能时，先判断它属于现有模块的“延伸”还是“新领域”。比如给学生管理系统加“课程推荐”功能，如果和“成绩分析”强相关，可放进services/score_service.py；如果是独立功能（如对接第三方课程平台）， 新增services/course_service.py。调整后用依赖图检查是否有循环依赖，确保每个模块依然符合“只做一件事”的原则，避免模块过大。

相对导入时提示“attempted relative import beyond top-level package”怎么办？

这个错误通常是因为在“顶层模块”（直接运行的文件，如main.py）中使用了相对导入。解决方法有两个：一是改用绝对导入（如from services import user_service）；二是确保相对导入只在“包内部模块”中使用（比如在services/user_service.py中导入models/user.py，可用from ..models import user）。新手 优先用绝对导入，减少路径问题。

小项目（比如100行代码）有必要用多模块结构吗？

单从“能跑起来”的角度，100行代码用单文件完全可行。但 养成多模块思维，哪怕简单拆分：比如把工具函数放进utils.py，主逻辑放main.py。这样做的好处是， 功能扩展时（比如从100行变成500行），不用大改结构；而且能提前熟悉模块划分思路，避免后期因结构混乱而放弃项目。我带的实习生中，一开始就用多模块的，后续接手复杂项目的适应速度明显更快。

__init__.py文件除了标识包，还能做什么？

__init__.py除了告诉Python“这是个包”，还能简化导入和初始化资源。比如在services/__init__.py中写from .user_service import UserService，后续其他模块导入时就可以直接from services import UserService，不用写全路径；还可以在里面初始化包内共享资源（如数据库连接池），避免重复创建。不过新手初期保持__init__.py为空也没问题，先确保结构正确，后续再按需添加功能。