一、从一个问题开始：代码为什么要分层组织

写一段几十行的验证脚本时，把代码全堆在一个 .py 文件里不会有任何问题。可当代码规模涨到几千行、涉及多个业务对象、需要多人协作时，“单文件堆砌”就会暴露出三类典型问题：

• 找不到代码：几十个函数、类混在一起，改一处要在文件里反复滚动定位；
• 名字冲突：两个功能各写了一个叫 process() 的函数，后定义的会把先定义的覆盖掉；
• 无法复用：想在另一个项目里用某个类，只能整段复制粘贴。

Python 给出的答案是一套层层递进的组织体系：类（Class）→ 模块（Module）→ 包（Package）→ 库（Library）→ 框架（Framework）。理解这套体系，是从小脚本走向工程化代码的第一步。

二、四个层级：类、模块、包与库/框架

一句话概括包含关系：类写在模块（.py 文件）里，多个模块组成包（文件夹），多个包/模块组成库，多个库加上开发规则就构成框架。

1. 类（Class）：最小封装单元

定义：类是 Python 面向对象编程的基本单元，它把“数据（属性）”和“操作这些数据的行为（方法）”封装在一起，形成一个高内聚的整体。

举例：定义一个 Student 类，把“姓名、年龄”两个属性和“考试、做作业”两个方法绑在一起：

class Student:
    def __init__(self, name, age):
        self.name = name      # 属性：数据
        self.age = age
    def do_homework(self):    # 方法：行为
        print(f"{self.name} 正在做作业")

类的价值在于封装：调用方不需要关心内部实现，只需知道有哪些属性和方法可用。

2. 模块（Module）：最小的代码复用单元

定义：模块就是一个独立的 .py 文件，里面可以包含类、函数、变量等任意代码，是 Python 中最小的代码复用单元。

举例：把上面的 Student 类写进 student.py，那么 student.py 就是一个模块。

作用：把同一主题的代码（比如所有与“学生”相关的逻辑）集中到一个文件，其他文件通过导入即可复用，不必复制粘贴。模块同时也是 Python 管理名字的基本边界——每个模块拥有独立的命名空间，模块内定义的名字不会污染其他模块。

3. 包（Package）：有结构的模块目录

定义：包是包含多个模块（.py 文件）的文件夹。传统上要求目录下必须有 __init__.py 文件（Python 3.3 之后可以省略，此时称为命名空间包，但工程实践中建议保留，以便放置初始化逻辑和导出控制）。

举例：一个叫 school 的包，结构如下：

school/                # 包
├── __init__.py        # 包初始化文件
├── student.py         # 学生模块
└── teacher.py         # 教师模块

作用：把多个相关模块组织成目录层级，一是避免不同团队写的模块重名冲突，二是让大型项目的目录结构一目了然。

4. 库与框架：聚合之上再加“规则”

• 库：多个包和模块的集合，本质是“现成的代码仓库”，开发者按需导入、主动调用；
• 框架：库 + 开发规则。框架不仅提供能力，还规定了代码该怎么组织、在什么时机被调用——控制权从开发者手中交给框架，这也是“控制反转”思想的通俗理解。

层级勾稽关系可以示意如下：

类 Class
  └── 写在 → 模块 Module（.py 文件）
        └── 多个组成 → 包 Package（文件夹）
              └── 多个包/模块组成 → 库 Library
                    └── 库 + 开发规则 → 框架 Framework

三、命名空间：重名模块靠“路径”区分

项目变大后，不同包里出现同名模块几乎是必然的。Python 用“包名.模块名”这种逻辑路径来唯一定位一个模块，这套路径机制就是命名空间。

例如有两个平级包 infra 和 analytics，各自都有一个 utils.py：

project/
├── infra/
│   ├── __init__.py
│   └── utils.py
└── analytics/
    ├── __init__.py
    └── utils.py

引用时加上包名前缀即可区分：

import infra.utils       # 指向基础设施包里的 utils
import analytics.utils   # 指向数据分析包里的 utils

infra 和 analytics 互为平级包，两个 utils.py 谁也不会覆盖谁。补充一点底层逻辑：执行 import 时，解释器会按 sys.path 中记录的目录顺序搜索模块，找到第一个匹配项即停止——这也是工程上要避免自己的模块名与标准库重名的原因，否则搜索顺序可能让你导入到“错误”的那个。

四、引用方式详解：import 与 from…import

1. 同包内引用：import 模块名

先在同包的 module_a.py 里写一个赋值：

# module_a.py
value = 2

在同包的 module_b.py 中引用它：

# module_b.py
import module_a          # import 即“引用”
print(module_a.value)    # 输出：2

2. 跨包引用：加上包名前缀，用法相同

如果目标模块不在当前包，引用时在前面拼上包名即可，访问方式不变：

import school.student
print(school.student.Student)

3. 名字太长？用 as 起别名

路径前缀会让调用代码变长，可以用 as 给模块起一个短别名，效果完全一致：

import school.student as stu
s = stu.Student("张三", 18)

4. from…import：按需导入具体对象

另一种引用方式是 from…import，直接把模块里的某个对象拿进当前命名空间：

from school.student import Student
s = Student("李四", 20)          # 不再需要前缀

两者的区别必须分清：

• import 模块：导入整个模块，使用时要通过「模块名.对象」访问。例如执行 import school.student 后，要调用其中的 Student，得写 school.student.Student；
• from 模块 import 对象：只把指定对象引入当前命名空间，直接写 Student 即可，代码更短，但也更容易与本地名字冲突；
• from 模块 import *：一次性导入模块内所有公开对象，可用模块内的 __all__ 列表控制导出范围，通常不建议滥用，容易造成命名污染。

5. 包内相对导入

包内部模块互相引用时，还可以用相对导入写法，如 from . import teacher（同包）或 from ..tools import log（上级包）。好处是包整体改名或移动时，内部引用无需修改。

五、工程实践建议与常见坑

1. __init__.py 的正确用法：可在其中做包级初始化，或把常用对象提升到包级别。例如在 school/__init__.py 中写 from .student import Student，之后直接 from school import Student 即可，调用方不必关心内部文件结构。
2. 警惕循环导入：A 模块 import B，B 又 import A，程序会在加载中途报错。规避思路：把公共依赖抽取到第三个模块，或把 import 语句下移到函数内部做延迟导入。
3. 入口判断：模块被直接运行时 __name__ 等于 “__main__“，被导入时等于模块名。把演示或测试代码放在 if __name__ == “__main__“: 里，模块既能独立运行，又能被安全导入。
4. 命名规范：模块名、包名用小写加下划线；不要用标准库已有的名字（如 json、os）给自己的文件命名，否则极易触发搜索顺序陷阱。
5. 按职责分层组织包：可维护的项目通常按“领域/功能”拆包，而不是按文件类型堆放，包结构本身就应该能反映业务结构。

六、总结

类、模块、包不是三个孤立的知识点，而是同一套“组织与寻址”思想在不同粒度上的体现：类封装数据与行为，模块按文件聚合代码并隔离命名，包按目录聚合模块并以路径区分重名，库与框架再在聚合之上叠加复用与规则。把 import 与 from…import 的差异、命名空间的路径逻辑、__init__.py 与 __name__ 的机制吃透，无论是阅读大型工程还是搭建自己的项目结构，都能做到心中有图、落笔有序。