Python模块与包：我从混乱到井井有条，全靠这5个组织原则

2026-02-28

大家好，我是正在实战各种AI项目的程序员晚枫。

今天聊一个让新手困惑、老手也容易忽视的话题——Python的模块与包。

你可能写过很多Python文件，但当项目变大时，代码变得混乱不堪：函数找不到定义、循环导入报错、同名文件冲突…

这篇文章总结了我在项目实战中总结的5个组织原则，帮你写出井井有条的Python代码。

概念1：模块就是.py文件

什么是模块？

任何一个.py文件都是一个模块。

# math_utils.py（这是一个模块）
def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

PI = 3.14159

如何使用模块？

# 方式1：import整个模块
import math_utils
print(math_utils.add(2, 3))  # 5
print(math_utils.PI)         # 3.14159

# 方式2：from import特定内容
from math_utils import add, PI
print(add(2, 3))  # 5
print(PI)         # 3.14159

# 方式3：import as起别名
import math_utils as mu
print(mu.add(2, 3))  # 5

概念2：包是模块的集合

什么是包？

包含__init__.py文件的文件夹就是一个包。

my_project/
├── main.py
└── my_package/          # 这是一个包
    ├── __init__.py      # 包的初始化文件
    ├── module_a.py      # 模块A
    └── module_b.py      # 模块B

如何使用包？

# 导入包中的模块
import my_package.module_a
from my_package import module_b
from my_package.module_a import some_function

原则1：合理划分模块

按功能划分

project/
├── main.py              # 程序入口
├── config.py            # 配置文件
├── utils/               # 工具函数
│   ├── __init__.py
│   ├── file_utils.py    # 文件操作
│   ├── date_utils.py    # 日期处理
│   └── string_utils.py  # 字符串处理
├── models/              # 数据模型
│   ├── __init__.py
│   ├── user.py
│   └── order.py
└── services/            # 业务逻辑
    ├── __init__.py
    ├── user_service.py
    └── order_service.py

每个模块的职责要单一

# good: 只做文件操作
# file_utils.py
def read_file(path):
    pass

def write_file(path, content):
    pass

# bad: 混杂了不相关的功能
# utils.py
def read_file(path):     # 文件操作
    pass

def send_email(to):      # 邮件发送？
    pass

def calculate_tax(money): # 税务计算？
    pass

原则2：避免循环导入

什么是循环导入？

# a.py
from b import func_b

def func_a():
    return func_b()

# b.py
from a import func_a  # 循环导入！

def func_b():
    return "hello"

解决方案

# 方案1：合并模块
# common.py
def func_a():
    pass

def func_b():
    pass

# 方案2：延迟导入
def func_a():
    from b import func_b  # 在函数内部导入
    return func_b()

# 方案3：重构设计（推荐）
# 引入第三个模块
# c.py - 存放共享的内容

原则3：使用相对导入

绝对导入 vs 相对导入

# 绝对导入（从项目根目录开始）
from my_package.utils import file_utils

# 相对导入（相对于当前位置）
from . import sibling_module      # 同级目录
from .. import parent_module       # 上级目录
from .utils import file_utils      # 子目录

什么时候用相对导入？

包内部的模块之间互相引用
移动包的位置时不需要修改导入语句

原则4：善用init.py

init.py的作用

# my_package/__init__.py

# 1. 控制对外暴露的内容
from .module_a import func_a
from .module_b import ClassB

__all__ = ['func_a', 'ClassB']  # from my_package import *

# 2. 执行初始化代码
print("my_package 已加载")

# 3. 简化导入路径
# 用户可以直接：from my_package import func_a
# 而不需要：from my_package.module_a import func_a

原则5：管理第三方依赖

requirements.txt

# requirements.txt
requests==2.31.0
pandas>=1.5.0
numpy

生成和使用

# 生成依赖清单
pip freeze > requirements.txt

# 安装依赖
pip install -r requirements.txt

虚拟环境（必学）

# 创建虚拟环境
python -m venv venv

# 激活（Windows）
venv\Scripts\activate

# 激活（Mac/Linux）
source venv/bin/activate

# 退出
 deactivate

实战：创建一个可发布的包

my_tool/                      # 项目根目录
├── README.md                 # 项目说明
├── LICENSE                   # 许可证
├── setup.py                  # 安装配置
├── requirements.txt          # 依赖
└── my_tool/                  # 包目录
    ├── __init__.py
    ├── core.py               # 核心功能
    └── cli.py                # 命令行接口

# setup.py
from setuptools import setup, find_packages

setup(
    name='my_tool',
    version='0.1.0',
    packages=find_packages(),
    install_requires=[
        'requests>=2.25.0',
    ],
    entry_points={
        'console_scripts': [
            'my_tool=my_tool.cli:main',
        ],
    },
)