Python 模块化项目学习笔记:模块、包、导入、入口保护与分层设计
本文通过一个"虚构商品工具"讲解 Python 模块与包、
import搜索路径、函数职责与命名、入口保护,以及业务逻辑和用户交互的分离。项目拆分为入口、业务和存储三个有实际内容的模块,通过函数参数和返回值传递数据,避免依赖隐式全局变量。
全部代码只使用 Python 标准语法,不需要安装第三方依赖。
目录
- 为什么要拆分代码
- 模块
- 包
import的基本用法import搜索路径- 常见导入错误
- 函数职责与命名
- 入口保护
- 业务逻辑与交互输入的分离
- 商品工具项目结构
- 存储模块实现
- 业务模块实现
- 入口模块实现
- 项目运行方法
- 模块之间的数据流
- 为什么不使用隐式全局变量
- 代码执行过程
- 常见错误与根因
- 项目改进练习
- 常见面试题
- 代码阅读面试题
- 核心知识总结
一、为什么要拆分代码
初学 Python 时,通常会把所有代码写在一个文件里:
python
products = [
{
"name": "月光笔记本",
"category": "文具",
"price": 15.8,
"quantity": 2
}
]
keyword = input("请输入商品关键词:")
matched_products = []
for product in products:
if keyword in product["name"]:
matched_products.append(product)
total = 0
for product in matched_products:
total += product["price"] * product["quantity"]
for product in matched_products:
print(product)
print("总价:", total)
代码较少时,这样写可以运行。
但随着功能增加,一个文件中会同时包含:
- 商品数据
- 查询规则
- 总价计算
- 用户输入
- 结果显示
- 程序启动代码
这会带来几个问题:
- 文件越来越长。
- 不同职责混在一起。
- 修改交互方式时可能影响业务逻辑。
- 业务函数难以单独测试。
- 其他程序难以复用查询和总价计算功能。
- 模块可能偷偷依赖全局变量。
- 导入文件时可能意外执行交互代码。
更合理的方式是按照职责拆分:
text
入口模块
├── 获取用户输入
├── 调用业务函数
└── 显示结果
业务模块
├── 查询商品
└── 统计总价
存储模块
└── 提供商品数据
核心原则是:
一个模块负责一类事情,一个函数负责一个明确任务。
二、模块
2.1 什么是模块
在 Python 中,一个 .py 文件通常就是一个模块。
例如:
text
business.py
就是一个名为 business 的模块。
文件中定义:
python
def calculate_total(products):
total = 0
for product in products:
total += product["price"] * product["quantity"]
return total
其他模块可以导入并使用:
python
from business import calculate_total
2.2 使用模块的好处
模块可以:
- 按职责组织代码。
- 减少单个文件的长度。
- 复用函数。
- 隔离不同功能。
- 降低模块之间的耦合。
- 方便测试和维护。
- 避免多人协作时都修改同一个文件。
2.3 模块名
文件名通常使用:
- 小写英文字母
- 下划线
推荐:
text
business.py
storage.py
main.py
product_service.py
不推荐:
text
Business.py
商品业务.py
product-service.py
Python 可以处理部分非英文文件名,但在导入、跨平台运行和团队协作中容易产生不必要的问题。
三、包
3.1 什么是包
包是用于组织多个模块的目录。
例如:
text
shop_app
├── __init__.py
├── main.py
├── business.py
└── storage.py
这里:
shop_app是包。main.py是入口模块。business.py是业务模块。storage.py是存储模块。__init__.py用于表明这个目录是一个普通 Python 包。
3.2 __init__.py
__init__.py 可以为空:
python
即使它没有代码,也具有组织意义:
- 明确表示该目录是 Python 包。
- 兼容不同工具和运行环境。
- 可以在包初始化时执行代码。
- 可以控制包对外暴露的内容。
当前学习项目中,建议保留空的 __init__.py,但不要在里面放业务逻辑。
3.3 模块和包的区别
假设目录为:
text
shop_app
├── __init__.py
├── business.py
└── storage.py
那么:
business.py是模块。storage.py是模块。shop_app是包。shop_app.business表示包中的业务模块。shop_app.storage表示包中的存储模块。
四、import 的基本用法
4.1 导入整个模块
python
import shop_app.business
使用函数:
python
result = shop_app.business.calculate_total(products)
优点:
- 来源非常明确。
- 不容易出现同名冲突。
缺点:
- 调用名称较长。
4.2 从模块中导入函数
python
from shop_app.business import calculate_total
使用:
python
result = calculate_total(products)
优点:
- 调用简洁。
- 适合只使用少量明确函数。
4.3 导入多个函数
python
from shop_app.business import calculate_total, query_products
如果一行过长,可以写成:
python
from shop_app.business import (
calculate_total,
query_products,
)
4.4 使用别名
python
import shop_app.business as business
调用:
python
result = business.calculate_total(products)
也可以给函数起别名:
python
from shop_app.business import calculate_total as get_total
不过如果原函数名已经清晰,通常没有必要额外起别名。
4.5 不推荐星号导入
不推荐:
python
from shop_app.business import *
原因:
- 不清楚导入了哪些名称。
- 容易出现同名覆盖。
- 阅读代码时难以判断函数来自哪里。
- 静态检查工具更难分析代码。
推荐明确导入:
python
from shop_app.business import query_products, calculate_total
五、import 搜索路径
5.1 Python 如何找到模块
执行:
python
import shop_app.business
时,Python 会在模块搜索路径中查找 shop_app。
可以通过下面的代码查看搜索路径:
python
import sys
for path in sys.path:
print(path)
sys.path 是一个列表,其中保存 Python 查找模块和包的位置。
通常可能包含:
- 当前启动位置或脚本相关目录
- Python 标准库目录
- Python 环境中的第三方包目录
- 环境变量配置的额外路径
5.2 导入搜索的基本过程
执行:
python
from shop_app.business import query_products
Python 大致会:
- 遍历
sys.path。 - 在每个路径下查找
shop_app。 - 找到包后,查找其中的
business.py。 - 执行
business.py的顶层代码。 - 从模块中取得
query_products。 - 将其绑定到当前模块的名称中。
5.3 工作目录与导入的关系
假设目录为:
text
D:\python-study
└── shop_app
├── __init__.py
├── main.py
├── business.py
└── storage.py
应该先进入项目根目录:
powershell
cd D:\python-study
然后运行:
powershell
python -m shop_app.main
此时 Python 可以从项目根目录找到:
text
shop_app
如果进入包目录:
powershell
cd D:\python-study\shop_app
再运行:
powershell
python main.py
那么下面的绝对导入可能失败:
python
from shop_app.business import query_products
原因是当前搜索起点可能变成了 shop_app 目录本身。Python 会尝试在其中继续寻找另一个 shop_app,但并不存在。
5.4 为什么推荐使用 python -m
推荐:
powershell
python -m shop_app.main
这里:
-m表示按照模块路径运行。shop_app是包名。main是包中的模块名。- 不写
.py。
这种方式能够让 Python 正确理解包结构。
不推荐在包目录中直接运行:
powershell
python main.py
因为直接运行文件时,Python 可能无法正确识别它属于哪个包。
5.5 不要用修改 sys.path 掩盖结构问题
不推荐:
python
import sys
sys.path.append("D:\\python-study")
这种做法把本机路径写进代码,会导致:
- 换电脑后失效。
- 换目录后失效。
- 导入关系不清晰。
- 隐藏真正的运行位置或包结构问题。
更好的解决办法是:
- 保持正确的项目结构。
- 从项目根目录运行。
- 使用
python -m 包名.模块名。 - 使用清晰的包内导入。
六、绝对导入与相对导入
6.1 绝对导入
python
from shop_app.business import query_products
from shop_app.storage import load_products
绝对导入从顶层包名开始。
优点:
- 来源清晰。
- 阅读时容易理解。
- 不容易因文件移动而混淆。
本项目推荐使用绝对导入。
6.2 相对导入
在 shop_app/main.py 中也可以写:
python
from .business import query_products
from .storage import load_products
其中:
.表示当前包。..表示上一级包。
相对导入适合明确的包内部关系,但要求程序以包或模块方式运行。
如果直接执行:
powershell
python .\shop_app\main.py
可能出现:
text
ImportError: attempted relative import with no known parent package
原因是直接运行文件时,Python 不一定知道 main.py 属于 shop_app 包。
正确运行:
powershell
python -m shop_app.main
6.3 当前项目选择
为了让导入来源更明确,本文代码使用绝对导入:
python
from shop_app.business import calculate_total, query_products
from shop_app.storage import load_products
七、导入模块时发生了什么
7.1 模块顶层代码会执行
假设 business.py 中有:
python
print("business 模块正在加载")
def calculate_total(products):
return 0
当其他文件第一次执行:
python
import shop_app.business
终端会打印:
text
business 模块正在加载
说明导入模块不只是"读取函数定义",还会执行模块的顶层代码。
7.2 为什么模块顶层不应执行交互
不推荐:
python
keyword = input("请输入关键词:")
print("你输入了:", keyword)
如果这些代码写在 business.py 顶层,那么任何模块只要导入业务模块,就会立刻要求用户输入。
这会导致:
- 模块难以复用。
- 自动化测试被阻塞。
- 导入产生意外副作用。
- 业务模块依赖终端交互。
因此,交互代码应放入入口模块的函数中,并使用入口保护。
7.3 模块通常只加载一次
同一次 Python 进程中,模块第一次导入后会被缓存。
python
import shop_app.business
import shop_app.business
通常不会完整执行两次模块顶层代码。
Python 会将已导入模块记录在:
python
sys.modules
不过初学阶段最重要的结论是:
不要依赖导入时的副作用完成核心业务。
八、函数职责与命名
8.1 一个函数应有一个主要职责
不推荐:
python
def handle_products():
products = [
{"name": "月光笔记本", "price": 15.8, "quantity": 2}
]
keyword = input("请输入关键词:")
matched_products = []
for product in products:
if keyword in product["name"]:
matched_products.append(product)
total = 0
for product in matched_products:
total += product["price"] * product["quantity"]
for product in matched_products:
print(product)
print(total)
这个函数同时负责:
- 创建商品数据
- 获取用户输入
- 查询商品
- 统计总价
- 输出结果
职责过多,函数难以测试和复用。
推荐拆分:
python
def load_products():
...
def query_products(products, keyword):
...
def calculate_total(products):
...
def read_keyword():
...
def print_products(products):
...
def main():
...
8.2 函数命名应该描述动作
函数通常表示一个动作,因此推荐使用动词或动词短语:
python
load_products()
query_products()
calculate_total()
read_search_conditions()
print_products()
main()
不推荐含义模糊的名称:
python
do_it()
handle()
process()
run_data()
abc()
8.3 名称应该与真实行为一致
如果函数只读取商品,不要命名为:
python
save_products()
如果函数返回多个商品,不要命名为:
python
find_product()
更准确的区别:
python
find_product()
通常表示查找一个商品。
python
query_products()
通常表示查询零个、一个或多个商品。
8.4 避免使用类型名作为变量名
不推荐:
python
list = []
dict = {}
str = "文具"
这些名称会覆盖 Python 内置名称。
推荐:
python
products = []
product = {}
category = "文具"
九、入口保护
9.1 什么是入口保护
Python 中常见的入口保护写法:
python
if __name__ == "__main__":
main()
它用于控制:
- 文件被直接执行时,启动程序。
- 文件被其他模块导入时,不自动启动程序。
9.2 __name__ 是什么
每个 Python 模块都有一个特殊变量:
python
__name__
当文件被直接作为入口运行时:
python
__name__ == "__main__"
当文件被其他模块导入时,__name__ 通常是模块的完整名称。
例如:
python
shop_app.main
9.3 没有入口保护的问题
不推荐:
python
def main():
print("程序启动")
main()
其他模块只要导入这个文件:
python
import shop_app.main
就会自动执行:
text
程序启动
推荐:
python
def main():
print("程序启动")
if __name__ == "__main__":
main()
这样导入模块时只会创建 main 函数,不会自动调用它。
9.4 入口保护不是安全机制
入口保护不会:
- 阻止别人导入函数。
- 保护敏感数据。
- 限制模块访问。
- 提供权限控制。
它只是控制模块作为入口运行时是否调用指定代码。
十、业务逻辑与交互输入的分离
10.1 什么是业务逻辑
业务逻辑表示程序真正要完成的规则,例如:
- 商品名称是否匹配关键词
- 商品分类是否符合条件
- 商品小计如何计算
- 多个商品总价如何累计
业务函数不应该关心:
- 用户是在终端输入还是网页输入
- 结果是打印到终端还是显示在网页上
- 数据来自列表、文件还是数据库
10.2 什么是交互逻辑
交互逻辑负责:
- 使用
input()获取用户输入 - 使用
print()显示结果 - 提示用户如何操作
- 决定调用哪些业务函数
10.3 混合交互和业务逻辑的问题
不推荐:
python
def query_products(products):
keyword = input("请输入关键词:")
matched_products = []
for product in products:
if keyword in product["name"]:
matched_products.append(product)
for product in matched_products:
print(product)
问题:
- 函数必须等待终端输入。
- 调用者不能直接传入关键词。
- 函数内部直接打印,难以继续处理结果。
- 自动化测试需要模拟输入和捕获输出。
- 将来改成网页程序时无法直接复用。
10.4 分离后的写法
业务函数:
python
def query_products(products, keyword):
matched_products = []
for product in products:
if keyword in product["name"]:
matched_products.append(product)
return matched_products
入口模块负责输入:
python
keyword = input("请输入关键词:").strip()
result = query_products(products, keyword)
入口模块负责输出:
python
for product in result:
print(product["name"])
这样,业务函数只负责查询。
十一、商品工具项目结构
创建以下目录和文件:
text
python-study
└── shop_app
├── __init__.py
├── main.py
├── business.py
└── storage.py
三个主要模块的职责:
| 模块 | 职责 |
|---|---|
storage.py |
创建并返回商品数据 |
business.py |
查询商品、计算总价 |
main.py |
获取输入、调用业务函数、显示结果 |
模块依赖方向:
text
main.py
├── 调用 storage.py 获取商品数据
└── 调用 business.py 处理商品数据
business.py
└── 不依赖 main.py,也不依赖 storage.py
storage.py
└── 不依赖 main.py,也不依赖 business.py
这个依赖方向很重要。
业务模块只接收函数参数,不需要知道数据由谁提供。
十二、存储模块:storage.py
文件路径:
text
shop_app/storage.py
代码:
python
def load_products():
"""创建并返回一份新的商品列表。"""
products = [
{
"name": "月光笔记本",
"category": "文具",
"price": 15.8,
"quantity": 2
},
{
"name": "云朵马克杯",
"category": "生活",
"price": 28.5,
"quantity": 1
},
{
"name": "星尘钢笔",
"category": "文具",
"price": 12.0,
"quantity": 3
},
{
"name": "森林便签",
"category": "文具",
"price": 8.5,
"quantity": 4
},
{
"name": "极光小夜灯",
"category": "家居",
"price": 46.0,
"quantity": 1
}
]
return products
12.1 为什么使用函数返回数据
没有直接在模块顶层暴露可变全局列表:
python
PRODUCTS = [...]
而是通过:
python
products = load_products()
取得数据。
好处:
- 每次调用都会得到一份新的列表。
- 调用者通过明确的函数获取数据。
- 减少共享可变全局状态。
- 将来改成读取文件时,调用方式可以保持不变。
- 存储实现细节被集中在存储模块中。
12.2 为什么叫 load_products
名称表示"加载商品"。
目前数据写在函数里,但将来可以改为:
- 从 JSON 文件读取
- 从 CSV 文件读取
- 从数据库读取
- 从接口读取
入口模块仍然可以继续调用:
python
products = load_products()
十三、业务模块:business.py
文件路径:
text
shop_app/business.py
代码:
python
def query_products(products, keyword="", category=""):
"""根据名称关键词和分类查询商品。"""
matched_products = []
normalized_keyword = keyword.strip().lower()
normalized_category = category.strip().lower()
for product in products:
product_name = product["name"].lower()
product_category = product["category"].lower()
name_matches = normalized_keyword in product_name
category_matches = (
normalized_category == ""
or product_category == normalized_category
)
if name_matches and category_matches:
matched_products.append(product)
return matched_products
def calculate_subtotal(product):
"""计算一件商品的价格小计。"""
return product["price"] * product["quantity"]
def calculate_total(products):
"""计算一组商品的总价。"""
total = 0
for product in products:
total += calculate_subtotal(product)
return total
13.1 业务模块没有什么
业务模块没有:
python
input()
也没有:
python
print()
它不负责:
- 询问用户
- 显示菜单
- 输出查询结果
- 决定程序何时启动
它只负责处理传入的数据并返回结果。
13.2 query_products() 的输入和输出
输入:
python
products
keyword
category
输出:
python
matched_products
调用:
python
result = query_products(
products,
keyword="笔",
category="文具"
)
13.3 为什么调用 strip()
python
normalized_keyword = keyword.strip().lower()
strip() 删除字符串首尾空白。
例如:
python
" 笔 ".strip()
得到:
text
笔
这样用户意外输入的前后空格不会影响查询。
13.4 为什么调用 lower()
python
keyword.lower()
用于统一英文大小写。
例如:
python
"NOTE".lower()
得到:
text
note
中文不会受到影响。
13.5 为什么单独创建 calculate_subtotal()
python
def calculate_subtotal(product):
return product["price"] * product["quantity"]
它负责计算一件商品的小计。
python
def calculate_total(products):
负责把多个小计相加。
两个函数职责不同:
calculate_subtotal():一件商品。calculate_total():一组商品。
这也减少了重复计算公式。
十四、入口模块:main.py
文件路径:
text
shop_app/main.py
代码:
python
from shop_app.business import (
calculate_subtotal,
calculate_total,
query_products,
)
from shop_app.storage import load_products
def read_search_conditions():
"""读取用户输入的查询条件。"""
keyword = input("请输入商品名称关键词,直接回车表示不限:").strip()
category = input("请输入商品分类,直接回车表示不限:").strip()
return keyword, category
def print_products(products):
"""显示商品查询结果。"""
if len(products) == 0:
print("没有找到符合条件的商品。")
return
print("\n查询结果:")
for product in products:
subtotal = calculate_subtotal(product)
print(
f"- {product['name']} | "
f"分类:{product['category']} | "
f"单价:{product['price']:.2f} 元 | "
f"数量:{product['quantity']} | "
f"小计:{subtotal:.2f} 元"
)
def main():
"""组织商品工具的完整执行流程。"""
products = load_products()
keyword, category = read_search_conditions()
matched_products = query_products(
products,
keyword=keyword,
category=category,
)
print_products(matched_products)
total = calculate_total(matched_products)
print(f"\n符合条件的商品总价:{total:.2f} 元")
if __name__ == "__main__":
main()
14.1 入口模块的职责
入口模块负责:
- 获取商品数据。
- 获取用户查询条件。
- 调用业务查询函数。
- 显示查询结果。
- 调用总价函数。
- 显示总价。
- 决定何时启动程序。
14.2 read_search_conditions()
python
def read_search_conditions():
keyword = input(...).strip()
category = input(...).strip()
return keyword, category
这个函数只负责读取查询条件。
它没有查询商品,也没有计算总价。
14.3 返回两个值
python
return keyword, category
实际返回一个元组:
python
(keyword, category)
调用时使用解包:
python
keyword, category = read_search_conditions()
14.4 print_products()
python
def print_products(products):
这个函数只负责显示商品。
如果列表为空:
python
if len(products) == 0:
print("没有找到符合条件的商品。")
return
执行 return 后,函数立即结束,不会继续打印商品。
14.5 main() 是流程协调者
python
def main():
main() 不负责实现具体的查询算法,也不负责创建商品明细。
它负责把不同模块的函数串联起来:
text
加载商品
↓
读取条件
↓
查询商品
↓
显示商品
↓
计算总价
↓
显示总价
这种函数也可以称为流程协调函数。
十五、__init__.py
文件路径:
text
shop_app/__init__.py
当前项目中保持为空即可:
python
不要在其中调用:
python
main()
也不要在其中放置:
python
input()
print()
否则只要导入 shop_app,就可能产生意外副作用。
十六、完整项目代码汇总
16.1 shop_app/__init__.py
python
16.2 shop_app/storage.py
python
def load_products():
"""创建并返回一份新的商品列表。"""
products = [
{
"name": "月光笔记本",
"category": "文具",
"price": 15.8,
"quantity": 2
},
{
"name": "云朵马克杯",
"category": "生活",
"price": 28.5,
"quantity": 1
},
{
"name": "星尘钢笔",
"category": "文具",
"price": 12.0,
"quantity": 3
},
{
"name": "森林便签",
"category": "文具",
"price": 8.5,
"quantity": 4
},
{
"name": "极光小夜灯",
"category": "家居",
"price": 46.0,
"quantity": 1
}
]
return products
16.3 shop_app/business.py
python
def query_products(products, keyword="", category=""):
"""根据名称关键词和分类查询商品。"""
matched_products = []
normalized_keyword = keyword.strip().lower()
normalized_category = category.strip().lower()
for product in products:
product_name = product["name"].lower()
product_category = product["category"].lower()
name_matches = normalized_keyword in product_name
category_matches = (
normalized_category == ""
or product_category == normalized_category
)
if name_matches and category_matches:
matched_products.append(product)
return matched_products
def calculate_subtotal(product):
"""计算一件商品的价格小计。"""
return product["price"] * product["quantity"]
def calculate_total(products):
"""计算一组商品的总价。"""
total = 0
for product in products:
total += calculate_subtotal(product)
return total
16.4 shop_app/main.py
python
from shop_app.business import (
calculate_subtotal,
calculate_total,
query_products,
)
from shop_app.storage import load_products
def read_search_conditions():
"""读取用户输入的查询条件。"""
keyword = input("请输入商品名称关键词,直接回车表示不限:").strip()
category = input("请输入商品分类,直接回车表示不限:").strip()
return keyword, category
def print_products(products):
"""显示商品查询结果。"""
if len(products) == 0:
print("没有找到符合条件的商品。")
return
print("\n查询结果:")
for product in products:
subtotal = calculate_subtotal(product)
print(
f"- {product['name']} | "
f"分类:{product['category']} | "
f"单价:{product['price']:.2f} 元 | "
f"数量:{product['quantity']} | "
f"小计:{subtotal:.2f} 元"
)
def main():
"""组织商品工具的完整执行流程。"""
products = load_products()
keyword, category = read_search_conditions()
matched_products = query_products(
products,
keyword=keyword,
category=category,
)
print_products(matched_products)
total = calculate_total(matched_products)
print(f"\n符合条件的商品总价:{total:.2f} 元")
if __name__ == "__main__":
main()
十七、项目运行方法
假设目录为:
text
D:\python-study
└── shop_app
├── __init__.py
├── main.py
├── business.py
└── storage.py
先进入项目根目录:
powershell
cd D:\python-study
确认目录内容:
powershell
dir
应当能够看到:
text
shop_app
然后运行:
powershell
python -m shop_app.main
注意:
text
shop_app.main
是模块路径,不是文件路径,因此:
- 使用点号连接。
- 不写
.py。 - 应从能够看到
shop_app的项目根目录运行。
交互示例:
text
请输入商品名称关键词,直接回车表示不限:笔
请输入商品分类,直接回车表示不限:文具
查询结果:
- 月光笔记本 | 分类:文具 | 单价:15.80 元 | 数量:2 | 小计:31.60 元
- 星尘钢笔 | 分类:文具 | 单价:12.00 元 | 数量:3 | 小计:36.00 元
符合条件的商品总价:67.60 元
十八、模块之间的数据流
完整数据流:
text
storage.load_products()
│
│ 返回商品列表
▼
main.main()
│
│ 将商品列表和查询条件作为参数传入
▼
business.query_products(products, keyword, category)
│
│ 返回匹配商品列表
▼
main.print_products(matched_products)
│
│ 传入匹配商品列表
▼
business.calculate_total(matched_products)
│
│ 返回总价
▼
main.main() 显示总价
每一步都通过以下方式传递数据:
- 函数参数
- 函数返回值
没有模块需要偷偷读取另一个模块中的可变全局变量。
十九、为什么要避免隐式全局变量
19.1 什么是隐式全局依赖
下面的函数没有参数,却直接读取模块外部的 products:
python
products = [
{
"name": "月光笔记本",
"price": 15.8,
"quantity": 2
}
]
def calculate_total():
total = 0
for product in products:
total += product["price"] * product["quantity"]
return total
calculate_total() 看起来不需要输入,实际上偷偷依赖全局变量 products。
这就是隐式全局依赖。
19.2 隐式全局依赖的问题
调用者看到:
python
calculate_total()
无法直接知道函数依赖什么数据。
问题包括:
- 函数不能方便地统计其他列表。
- 测试前必须修改全局变量。
- 其他函数可能意外修改全局列表。
- 代码执行结果依赖隐藏状态。
- 模块之间产生紧密耦合。
19.3 通过参数明确传递
推荐:
python
def calculate_total(products):
total = 0
for product in products:
total += product["price"] * product["quantity"]
return total
调用:
python
all_total = calculate_total(all_products)
query_total = calculate_total(matched_products)
函数的依赖非常明确:
text
输入:products
输出:total
19.4 全局常量和可变全局变量不同
下面的常量通常问题较小:
python
CURRENCY_NAME = "元"
它:
- 含义明确。
- 不应在运行中被修改。
- 使用全大写命名表示常量。
但下面的可变全局列表风险更大:
python
PRODUCTS = []
它可能被多个函数共同修改,导致结果依赖调用顺序。
当前项目通过 load_products() 返回数据,并把数据显式传入业务函数。
二十、函数职责分析
项目中的函数职责如下:
| 函数 | 所属模块 | 输入 | 输出 | 职责 |
|---|---|---|---|---|
load_products() |
storage.py |
无 | 商品列表 | 提供商品数据 |
query_products() |
business.py |
商品、关键词、分类 | 匹配列表 | 查询商品 |
calculate_subtotal() |
business.py |
单个商品 | 小计 | 计算单项金额 |
calculate_total() |
business.py |
商品列表 | 总价 | 累计总金额 |
read_search_conditions() |
main.py |
用户键盘输入 | 关键词、分类 | 获取查询条件 |
print_products() |
main.py |
商品列表 | None |
显示商品 |
main() |
main.py |
无 | None |
协调整体流程 |
一个判断函数职责是否清晰的方法是:
能否用一句简短的话准确描述该函数,并且这句话中不需要出现多个"并且"。
例如:
text
读取查询条件,并查询商品,并计算总价,并打印结果
这样的函数通常职责过多。
二十一、业务函数为什么更容易测试
因为 query_products() 不调用 input() 和 print(),所以可以直接测试:
python
from shop_app.business import calculate_total, query_products
test_products = [
{
"name": "测试笔记本",
"category": "文具",
"price": 10.0,
"quantity": 2
},
{
"name": "测试水杯",
"category": "生活",
"price": 20.0,
"quantity": 1
}
]
result = query_products(
test_products,
keyword="笔",
category="文具",
)
assert len(result) == 1
assert result[0]["name"] == "测试笔记本"
assert calculate_total(result) == 20.0
print("测试通过")
测试代码可以直接提供输入数据并检查返回值。
如果业务函数内部包含:
python
input()
print()
测试就需要额外模拟终端输入、捕获输出,复杂度明显增加。
二十二、常见错误与根因
22.1 ModuleNotFoundError
错误:
text
ModuleNotFoundError: No module named 'shop_app'
常见根因:
- 没有从项目根目录运行。
- 项目根目录不在
sys.path中。 - 包名拼写错误。
- 目录结构与导入路径不一致。
解决思路:
- 确认项目结构。
- 进入包含
shop_app的目录。 - 使用:
powershell
python -m shop_app.main
不要优先通过修改 sys.path 打补丁。
22.2 相对导入失败
错误:
text
ImportError: attempted relative import with no known parent package
常见原因:
python
from .business import query_products
配合直接运行:
powershell
python .\shop_app\main.py
Python 不知道当前文件属于哪个包。
正确运行:
powershell
python -m shop_app.main
22.3 模块名与标准库重名
不要把文件命名为:
text
json.py
random.py
sys.py
typing.py
例如存在本地文件:
text
json.py
执行:
python
import json
可能导入本地文件,而不是标准库中的 json 模块。
这叫模块遮蔽。
22.4 循环导入
假设:
text
main.py 导入 business.py
business.py 又导入 main.py
可能造成循环导入。
不推荐:
python
# main.py
from shop_app.business import query_products
python
# business.py
from shop_app.main import print_products
更好的设计是:
- 业务模块不依赖入口模块。
- 入口模块负责调用业务模块。
- 公共逻辑放到合适的独立模块。
22.5 导入时自动要求输入
错误:
python
# business.py
keyword = input("请输入关键词:")
只要导入业务模块就会阻塞等待输入。
根因:把交互代码写在模块顶层。
解决方法:
- 将输入放入入口函数。
- 使用入口保护。
22.6 业务函数直接打印结果
不推荐:
python
def calculate_total(products):
total = 0
for product in products:
total += product["price"] * product["quantity"]
print(total)
调用者不能继续使用总价。
推荐:
python
def calculate_total(products):
total = 0
for product in products:
total += product["price"] * product["quantity"]
return total
22.7 使用隐式全局变量
不推荐:
python
products = []
def query_products(keyword):
for product in products:
...
推荐:
python
def query_products(products, keyword):
...
22.8 为了拆分而过度拆分
不必给每一行代码创建一个模块。
当前项目只有三个主要职责:
- 入口交互
- 业务规则
- 数据存储
所以拆成三个模块已经足够。
模块拆分应该服务于职责边界,而不是追求文件数量。
二十三、常见面试题
面试题 1:Python 中什么是模块?
参考答案:
一个 .py 文件通常就是一个 Python 模块。模块可以包含函数、类、变量和顶层代码,其他模块可以通过 import 使用其中的内容。
面试题 2:Python 中什么是包?
参考答案:
包是组织多个模块的目录。普通包通常包含 __init__.py,模块可以通过 包名.模块名 的方式导入。
面试题 3:模块和包有什么区别?
参考答案:
模块通常是一个 .py 文件;包通常是包含多个模块的目录。模块用于组织代码,包用于进一步组织多个模块。
面试题 4:Python 如何查找被导入的模块?
参考答案:
Python 会根据模块搜索路径查找模块,搜索路径可以通过 sys.path 查看。它通常包含启动位置、标准库目录以及当前环境中的包目录等。
面试题 5:为什么推荐从项目根目录运行?
参考答案:
从项目根目录运行可以让顶层包位于合理的模块搜索路径中,使绝对导入能够按照项目结构解析,减少 ModuleNotFoundError。
面试题 6:python file.py 和 python -m package.module 有什么区别?
参考答案:
python file.py 把指定文件作为独立脚本运行;python -m package.module 按模块路径运行,使 Python 正确理解模块所属的包。对于包内入口,通常推荐使用 python -m。
面试题 7:绝对导入与相对导入有什么区别?
参考答案:
绝对导入从顶层包名开始,例如:
python
from shop_app.business import query_products
相对导入以当前包为参照,例如:
python
from .business import query_products
绝对导入来源更清晰;相对导入适合明确的包内部关系,但需要以包方式运行。
面试题 8:为什么不推荐修改 sys.path 解决导入问题?
参考答案:
直接修改 sys.path 容易把本机绝对路径写入代码,降低可移植性,还可能掩盖项目结构和运行方式的问题。应优先修正目录结构、导入方式和启动位置。
面试题 9:导入模块时会执行模块代码吗?
参考答案:
会。模块第一次导入时,Python 会执行模块的顶层代码。因此不应在可复用模块顶层放置 input()、自动启动程序或其他有明显副作用的操作。
面试题 10:if __name__ == "__main__": 有什么作用?
参考答案:
它用于判断当前模块是否作为程序入口运行。如果是,就调用入口函数;如果模块只是被导入,则不会自动执行入口代码。
面试题 11:入口保护是安全机制吗?
参考答案:
不是。它只是控制模块直接运行和被导入时的不同行为,不提供权限控制或数据保护。
面试题 12:为什么业务逻辑不应直接调用 input()?
参考答案:
直接调用 input() 会让业务逻辑依赖终端交互,降低复用性和可测试性。更好的方式是入口层获取输入,再把值作为参数传给业务函数。
面试题 13:为什么业务函数通常应该返回数据,而不是直接打印?
参考答案:
返回的数据可以继续计算、保存、测试或由不同界面显示。直接打印只能产生终端输出,调用者难以继续使用结果。
面试题 14:什么是函数的单一职责?
参考答案:
一个函数应有一个明确的主要任务。例如,查询函数负责查询,总价函数负责计算,显示函数负责输出。职责越清晰,函数越容易理解、复用和测试。
面试题 15:为什么函数名通常使用动词?
参考答案:
函数通常表示一个动作,例如 load_products、query_products、calculate_total。动词名称能够直接表达函数行为。
面试题 16:什么是隐式全局依赖?
参考答案:
函数没有通过参数接收数据,却直接读取或修改模块外部的全局变量。调用者仅看函数调用无法知道它依赖哪些状态。
面试题 17:隐式全局变量有什么问题?
参考答案:
它会隐藏函数依赖,使结果受到外部状态和调用顺序影响,增加测试、复用、调试和维护难度。可变全局对象尤其容易被多个函数意外修改。
面试题 18:如何减少模块耦合?
参考答案:
可以通过以下方式减少耦合:
- 通过函数参数传入数据。
- 通过返回值交回结果。
- 让业务模块不依赖交互模块。
- 避免共享可变全局变量。
- 保持清晰、单向的模块依赖。
- 将公共规则放在合适的独立模块中。
面试题 19:什么是循环导入?
参考答案:
模块 A 导入模块 B,而模块 B 又在加载过程中导入模块 A,就可能形成循环导入。此时某个模块可能尚未初始化完成,导致名称不存在或导入失败。
面试题 20:如何避免循环导入?
参考答案:
应重新检查模块职责和依赖方向,例如让入口层依赖业务层,而业务层不反向依赖入口层。真正共享的逻辑可以提取到第三个独立模块。
面试题 21:为什么不推荐 from module import *?
参考答案:
它会把多个未知名称引入当前作用域,容易产生名称冲突,也不利于阅读、维护和静态分析。推荐明确导入需要的名称。
面试题 22:为什么文件不应命名为 json.py 或 random.py?
参考答案:
本地文件可能遮蔽同名标准库模块。执行 import json 时,Python 可能导入本地 json.py,导致标准库功能不可用或出现循环导入。
面试题 23:__init__.py 有什么作用?
参考答案:
它用于明确包结构,可以为空,也可以用于包初始化或控制对外接口。但不建议在其中执行输入、输出或自动启动业务流程。
面试题 24:为什么 main() 应该保持简洁?
参考答案:
main() 的主要职责是协调流程,而不是实现所有细节。简洁的 main() 能让读者快速看懂程序从输入到输出的整体过程。
面试题 25:存储模块是否一定要连接数据库?
参考答案:
不一定。存储模块表示数据来源的职责边界。它可以暂时返回内存数据,也可以读取 JSON、CSV、数据库或网络接口。关键是调用者不需要知道具体实现。
二十四、代码阅读面试题
题目 1:下面代码导入时会发生什么?
python
# report.py
print("报告模块已加载")
def create_report():
return "报告完成"
python
import report
答案:
第一次导入时会执行模块顶层的 print(),输出:
text
报告模块已加载
然后创建 create_report 函数。
题目 2:下面代码有什么问题?
python
# business.py
keyword = input("请输入关键词:")
def query_products(products):
...
答案:
交互代码位于模块顶层。任何模块导入 business.py 时都会立即等待用户输入。业务模块不应依赖终端交互。
题目 3:下面函数依赖了什么隐藏状态?
python
products = []
def calculate_total():
total = 0
for product in products:
total += product["price"] * product["quantity"]
return total
答案:
函数隐式依赖全局变量 products。应改为:
python
def calculate_total(products):
...
题目 4:下面代码为什么不会在导入时调用 main()?
python
def main():
print("程序启动")
if __name__ == "__main__":
main()
答案:
被导入时,__name__ 是模块名,而不是 "__main__",所以条件不成立。
题目 5:下面运行方式可能为什么失败?
目录:
text
project
└── shop_app
├── __init__.py
├── main.py
└── business.py
main.py:
python
from shop_app.business import query_products
在 shop_app 目录中运行:
powershell
python main.py
答案:
当前搜索起点是包目录本身,Python 可能无法在其中找到顶层包 shop_app。应回到 project 目录运行:
powershell
python -m shop_app.main
题目 6:下面两个函数哪个更容易测试?
版本一:
python
def query_products(products):
keyword = input("请输入关键词:")
for product in products:
if keyword in product["name"]:
print(product)
版本二:
python
def query_products(products, keyword):
matched_products = []
for product in products:
if keyword in product["name"]:
matched_products.append(product)
return matched_products
答案:
版本二更容易测试。它的输入通过参数提供,输出通过返回值取得,不依赖终端输入和打印。
题目 7:下面导入方式有什么风险?
python
from shop_app.business import *
答案:
无法直观看出导入了哪些名称,可能覆盖当前作用域中的同名变量或函数,也会降低代码可读性。
题目 8:下面模块依赖是否合理?
text
main.py → business.py
business.py → main.py
答案:
不合理,存在循环导入风险。业务模块不应依赖入口模块。入口模块可以调用业务模块,但依赖方向不应反转。
题目 9:为什么下面的函数名不够准确?
python
def process(data):
...
答案:
process 没有说明处理什么、如何处理、返回什么。如果函数负责查询商品,应命名为 query_products;如果负责总价计算,应命名为 calculate_total。
题目 10:下面代码是否完全复制了商品数据?
python
def query_products(products):
return products.copy()
答案:
没有。它只复制了外层列表,内部商品字典仍然与原列表共享,属于浅复制。
二十五、编程练习
练习 1:新增库存查询
在 business.py 中新增:
python
def query_in_stock_products(products):
matched_products = []
for product in products:
if product["quantity"] > 0:
matched_products.append(product)
return matched_products
要求:
- 不调用
input()。 - 不调用
print()。 - 不读取全局商品列表。
- 通过参数接收数据。
- 通过返回值返回结果。
练习 2:新增分类统计
python
def count_by_category(products):
category_counts = {}
for product in products:
category = product["category"]
category_counts[category] = category_counts.get(category, 0) + 1
return category_counts
示例结果:
python
{
"文具": 3,
"生活": 1,
"家居": 1
}
显示结果的代码仍然应该放在入口模块中。
练习 3:新增最高价商品查询
python
def find_most_expensive_product(products):
if len(products) == 0:
return None
most_expensive = products[0]
for product in products:
if product["price"] > most_expensive["price"]:
most_expensive = product
return most_expensive
练习 4:扩展入口菜单
在入口模块中新增:
python
def read_action():
print("1. 查询商品")
print("2. 查看全部商品")
print("3. 退出")
return input("请选择操作:").strip()
注意:
- 菜单输入属于交互逻辑。
- 商品查询属于业务逻辑。
- 菜单函数不应该实现查询算法。
练习 5:将存储改为不同数据
修改 storage.py 中的数据,但不修改:
python
query_products()
calculate_total()
如果业务模块无需修改,说明模块之间的职责边界是有效的。
练习 6:为业务函数编写断言测试
python
from shop_app.business import calculate_total, query_products
products = [
{
"name": "测试钢笔",
"category": "文具",
"price": 10.0,
"quantity": 2
},
{
"name": "测试水杯",
"category": "生活",
"price": 25.0,
"quantity": 1
}
]
result = query_products(
products,
keyword="笔",
category="文具",
)
assert len(result) == 1
assert result[0]["name"] == "测试钢笔"
assert calculate_total(result) == 20.0
print("全部测试通过")
二十六、判断模块职责是否合理的检查清单
存储模块
- 是否只负责提供或保存数据?
- 是否避免处理终端输入?
- 是否避免显示业务结果?
- 是否通过函数返回数据?
- 更换数据来源后,业务函数是否无需修改?
业务模块
- 是否通过参数接收需要的数据?
- 是否通过返回值交回结果?
- 是否避免调用
input()? - 是否避免直接打印结果?
- 是否避免读取可变全局数据?
- 是否可以直接编写断言测试?
入口模块
- 是否负责读取用户输入?
- 是否负责显示结果?
- 是否负责协调模块调用?
- 是否使用入口保护?
main()是否能够清晰展示完整流程?- 是否避免在入口模块重复实现业务规则?
二十七、核心知识地图
text
Python 项目
└── 包 shop_app
├── __init__.py
├── main.py
│ ├── 获取用户输入
│ ├── 调用存储函数
│ ├── 调用业务函数
│ ├── 显示结果
│ └── 入口保护
│
├── business.py
│ ├── 查询商品
│ ├── 计算小计
│ └── 计算总价
│
└── storage.py
└── 提供商品数据
模块之间的数据传递
├── 函数参数
└── 函数返回值
导入过程
├── 根据 sys.path 查找包
├── 查找包中的模块
├── 执行模块顶层代码
└── 绑定导入名称
运行方式
└── python -m shop_app.main
入口保护
└── if __name__ == "__main__":
main()
二十八、必须掌握的结论
- 一个
.py文件通常是一个模块。 - 包是组织多个模块的目录。
__init__.py可以用于明确包结构。- Python 根据模块搜索路径查找导入目标。
- 可以通过
sys.path查看模块搜索路径。 - 包内入口通常推荐使用
python -m 包名.模块名运行。 - 绝对导入从顶层包名开始。
- 相对导入使用
.表示当前包。 - 不应通过硬编码修改
sys.path掩盖项目结构问题。 - 模块第一次导入时会执行顶层代码。
- 可复用模块顶层不应执行
input()或自动启动流程。 - 入口保护用于区分直接运行和被导入。
if __name__ == "__main__":不是安全机制。- 函数名应该准确描述函数行为。
- 一个函数应该有一个主要职责。
- 业务函数不应该直接获取终端输入。
- 业务函数通常应该返回数据,而不是直接打印数据。
- 入口模块负责输入、输出和流程协调。
- 业务模块负责业务规则。
- 存储模块负责提供或保存数据。
- 数据应通过函数参数和返回值在模块之间传递。
- 隐式全局变量会隐藏函数依赖。
- 可变全局变量会让结果依赖共享状态和调用顺序。
- 业务模块不应该反向依赖入口模块。
- 清晰、单向的模块依赖可以降低循环导入风险。
from module import *会降低可读性并增加名称冲突风险。- 本地模块不应与标准库模块重名。
- 拆分模块的依据是职责边界,而不是文件数量。
- 易测试的函数通常拥有明确输入和明确输出。
- 好的模块化设计能够让存储、业务和交互独立变化。