Python函数与模块怎么写？自学进阶必须掌握的代码组织技巧

很多初学者在自学 Python 时，往往习惯从头到尾在一个 .py 脚本里写满线性执行的代码，随着业务逻辑增加，变量互相覆盖、调试困难、复制粘贴代码等问题接踵而至。编写清晰的函数与拆分模块，是跨越“单脚本练习”迈向“项目化工程”的核心跳板。本文将直接从函数设计的核心约束切入，逐步演示从单文件逻辑提炼为独立模块并正确导入的具体步骤，梳理工程代码组织的实用技巧。

一、为什么线性脚本需要重构为函数

在开始写函数前，需要建立一种“逻辑封装”的直觉。线性脚本将所有数据和逻辑直接暴露在顶层作用域，不仅每次执行都必须从上跑到底，而且中间变量名极易冲突。将可重复或具有单一目的的计算封装成函数，核心目的是界定职责、控制副作用并实现参数化输入。

图 1：代码架构从扁平脚本向清晰函数与独立模块拆分的演进

二、写好 Python 函数的三个底线要求

编写函数不是简单把几行代码前面加上 def。自学进阶的关键在于理解参数传递、返回值以及作用域的边界控制。以下是编写规范函数的三个核心准则：

1. 单一职责与明确返回值

一个函数只做一件事。例如一个函数负责“解析文本中的数字”，另一个函数负责“统计总和”，切勿在一个函数里既读文件、又计算、还直接用 print() 输出。尽量使用 return 产出计算结果，将输出方式（打印到控制台还是写入日志）交给上层调用者决定。

2. 严禁使用可变对象作为默认参数

初学者容易犯的典型错误是在参数默认值中直接指定列表或字典（例如 def add_item(item, box=[])）。Python 的函数定义在模块加载时只执行一次，默认参数属于函数对象的持久属性。如果使用列表等可变对象，多次调用会共享同一个容器，导致状态污染。推荐做法是使用 None 作为哨兵值：

# 推荐做法：使用 None 作为默认值，在函数体内部新建独立对象
def collect_score(score: float, history: list = None) -> list:
    if history is None:
        history = []
    history.append(score)
    return history

3. 添加类型注解与说明文档（Docstring）

从 Python 3.5 起内置类型提示，配合清晰的文档字符串，能让调用方不需要逐行翻查实现代码即可明白输入期望与产出格式：

def calculate_discount(price: float, rate: float = 0.9) -> float:
    """计算折后价格。

    :param price: 原始价格，必须为非负浮点数
    :param rate: 折扣比例，范围在 0 到 1 之间，默认 0.9
    :return: 折后计算金额，保留两位小数
    """
    if price < 0 or not (0 < rate <= 1):
        raise ValueError("价格或折扣率参数无效")
    return round(price * rate, 2)

三、从单个函数到模块拆分的操作步骤

在 Python 中，每一个以 .py 结尾的文件都是一个独立的模块（Module）。当函数数量增多、职责开始出现分化时，就需要将它们拆分到独立模块中。

图 2：从单脚本重构提炼为独立业务模块的标准化操作步骤

以下通过一个微型项目结构展示实际落地代码。假设目录结构如下：

my_project/
│
├── text_cleaner.py     # 独立功能模块：存放纯函数
└── main.py             # 程序主入口：装配流程并执行

第一步：编写模块 text_cleaner.py

# text_cleaner.py
"""文本清洗与统计专用模块"""

def remove_punctuation(text: str) -> str:
    """去除常见标点符号"""
    symbols = ",.!?，。！？；;\"' "
    for char in symbols:
        text = text.replace(char, "")
    return text

def count_words(text: str) -> int:
    """计算清洗后的字符总数"""
    cleaned = remove_punctuation(text)
    return len(cleaned)

第二步：在 main.py 中引入并使用

# main.py
"""主入口执行脚本"""
import text_cleaner

def main():
    raw_message = "你好，世界！Python 让代码组织更高效。"
    cleaned = text_cleaner.remove_punctuation(raw_message)
    total = text_cleaner.count_words(raw_message)
    
    print(f"清洗后文本: {cleaned}")
    print(f"有效字符总数: {total}")

if __name__ == "__main__":
    main()

四、关键差异对比：两种模块导入方式的区别

在 Python 中，引入模块通常有两种写法：import module_name 与 from module_name import function_name。初学者常以为两者只是字面长短的区别，但在命名空间隔离与代码可读性上存在显著不同。

五、理解 if __name__ == "__main__" 的底层机制

每个自学 Python 的人都会遇到 if __name__ == "__main__"，但往往只把它当成固定的样板代码复制粘贴。要真正掌握模块组织，必须理解其背后的 Python 导入机制。

当 Python 解释器运行一个文件时，会在执行任何代码之前设置一些内置变量，其中 __name__ 就是当前模块的标识符：

• 如果该文件是直接在终端被启动的入口文件（例如执行 python main.py），Python 会将该文件的 __name__ 赋值为字符串 "__main__"。
• 如果该文件是被其他文件通过 import 引入的，Python 会将该文件的 __name__ 赋值为其真实文件名（如 "text_cleaner"）。

图 3：__name__ 变量如何区分“作为主程序启动”与“作为模块导入”

这意味着：当你写完一个功能模块后，完全可以在文件末尾加上 if __name__ == "__main__": 编写自测代码。在直接运行该文件时，可以方便地测试各个函数；而当其他主程序导入该模块时，这些测试语句绝不会被自动触发，既保证了模块独立调试的便利，又避免了产生副作用。

六、自学进阶代码组织总结

从随意写脚本到能够自如地搭建模块化项目，本质是掌握软件工程中“高内聚、低耦合”的思维。在日常写代码时，建议遵循以下组织自检闭环：

图 4：自学 Python 编写规范函数与模块的核心习惯矩阵

掌握了函数封装与模块化拆分，你的 Python 技能就正式脱离了“即写即弃”的初级脚本模式。在接下来的练习中，不妨尝试把过去写过的上百行长脚本，按照功能拆解出 2~3 个模块，用清晰的函数签名和主入口重构一遍，体会代码条理分明、易于维护的愉悦感。