day_2

Python 模块化项目学习笔记:模块、包、导入、入口保护与分层设计

本文通过一个"虚构商品工具"讲解 Python 模块与包、import 搜索路径、函数职责与命名、入口保护,以及业务逻辑和用户交互的分离。

项目拆分为入口、业务和存储三个有实际内容的模块,通过函数参数和返回值传递数据,避免依赖隐式全局变量。

全部代码只使用 Python 标准语法,不需要安装第三方依赖。


目录

  1. 为什么要拆分代码
  2. 模块
  3. 包
  4. import 的基本用法
  5. import 搜索路径
  6. 常见导入错误
  7. 函数职责与命名
  8. 入口保护
  9. 业务逻辑与交互输入的分离
  10. 商品工具项目结构
  11. 存储模块实现
  12. 业务模块实现
  13. 入口模块实现
  14. 项目运行方法
  15. 模块之间的数据流
  16. 为什么不使用隐式全局变量
  17. 代码执行过程
  18. 常见错误与根因
  19. 项目改进练习
  20. 常见面试题
  21. 代码阅读面试题
  22. 核心知识总结

一、为什么要拆分代码

初学 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)

代码较少时,这样写可以运行。

但随着功能增加,一个文件中会同时包含:

  • 商品数据
  • 查询规则
  • 总价计算
  • 用户输入
  • 结果显示
  • 程序启动代码

这会带来几个问题:

  1. 文件越来越长。
  2. 不同职责混在一起。
  3. 修改交互方式时可能影响业务逻辑。
  4. 业务函数难以单独测试。
  5. 其他程序难以复用查询和总价计算功能。
  6. 模块可能偷偷依赖全局变量。
  7. 导入文件时可能意外执行交互代码。

更合理的方式是按照职责拆分:

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 大致会:

  1. 遍历 sys.path。
  2. 在每个路径下查找 shop_app。
  3. 找到包后,查找其中的 business.py。
  4. 执行 business.py 的顶层代码。
  5. 从模块中取得 query_products。
  6. 将其绑定到当前模块的名称中。

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")

这种做法把本机路径写进代码,会导致:

  • 换电脑后失效。
  • 换目录后失效。
  • 导入关系不清晰。
  • 隐藏真正的运行位置或包结构问题。

更好的解决办法是:

  1. 保持正确的项目结构。
  2. 从项目根目录运行。
  3. 使用 python -m 包名.模块名。
  4. 使用清晰的包内导入。

六、绝对导入与相对导入

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)

问题:

  1. 函数必须等待终端输入。
  2. 调用者不能直接传入关键词。
  3. 函数内部直接打印,难以继续处理结果。
  4. 自动化测试需要模拟输入和捕获输出。
  5. 将来改成网页程序时无法直接复用。

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 入口模块的职责

入口模块负责:

  1. 获取商品数据。
  2. 获取用户查询条件。
  3. 调用业务查询函数。
  4. 显示查询结果。
  5. 调用总价函数。
  6. 显示总价。
  7. 决定何时启动程序。

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()
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 中。
  • 包名拼写错误。
  • 目录结构与导入路径不一致。

解决思路:

  1. 确认项目结构。
  2. 进入包含 shop_app 的目录。
  3. 使用:
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()

二十八、必须掌握的结论

  1. 一个 .py 文件通常是一个模块。
  2. 包是组织多个模块的目录。
  3. __init__.py 可以用于明确包结构。
  4. Python 根据模块搜索路径查找导入目标。
  5. 可以通过 sys.path 查看模块搜索路径。
  6. 包内入口通常推荐使用 python -m 包名.模块名 运行。
  7. 绝对导入从顶层包名开始。
  8. 相对导入使用 . 表示当前包。
  9. 不应通过硬编码修改 sys.path 掩盖项目结构问题。
  10. 模块第一次导入时会执行顶层代码。
  11. 可复用模块顶层不应执行 input() 或自动启动流程。
  12. 入口保护用于区分直接运行和被导入。
  13. if __name__ == "__main__": 不是安全机制。
  14. 函数名应该准确描述函数行为。
  15. 一个函数应该有一个主要职责。
  16. 业务函数不应该直接获取终端输入。
  17. 业务函数通常应该返回数据,而不是直接打印数据。
  18. 入口模块负责输入、输出和流程协调。
  19. 业务模块负责业务规则。
  20. 存储模块负责提供或保存数据。
  21. 数据应通过函数参数和返回值在模块之间传递。
  22. 隐式全局变量会隐藏函数依赖。
  23. 可变全局变量会让结果依赖共享状态和调用顺序。
  24. 业务模块不应该反向依赖入口模块。
  25. 清晰、单向的模块依赖可以降低循环导入风险。
  26. from module import * 会降低可读性并增加名称冲突风险。
  27. 本地模块不应与标准库模块重名。
  28. 拆分模块的依据是职责边界,而不是文件数量。
  29. 易测试的函数通常拥有明确输入和明确输出。
  30. 好的模块化设计能够让存储、业务和交互独立变化。
相关推荐
叮当小飞鱼9 分钟前
RAG幻觉
python
赵大仁36 分钟前
Agent 工具调用可靠性:超时、重试、幂等与人工确认怎么设计
python·agent·幂等·工具调用·人工确认
__underline__2 小时前
冷门Python知识点007篇:list[int]不是类,为什么能当基类?
后端·python
Dmz丶2 小时前
前端转 AI 100 天 Day 49:文档切分——RAG 效果的隐形开关
python
青少儿编程课堂3 小时前
第十八届蓝桥杯青少组图形化真题 + 全国青少年信息素养大赛 + 电子学会图形化考级:校园泡泡堂大挑战解析
c++·python·算法·bfs·信息学竞赛
Starry-sky(jing)3 小时前
Hermes Agent 升级 v0.23.2:先辨更新渠道,再看 CLI 退出残留修复
人工智能·python·ai agent
2601_967979123 小时前
“Python,就是新的 BASIC!”
python·编程语言·历史·basic·比较
青少儿编程课堂4 小时前
蓝桥杯·全国青少年信息素养大赛·电子学会Python/C++考级:Dinic最大流解析
c++·python·算法·bfs·信息学竞赛
专注仿真4 小时前
基于 AFSIM 的智能体训练:多智能体强化学习篇 —— QTRAN 算法实战
开发语言·python·算法·php·强化学习·afsim智能体·仿真训练