在 Learn Python Programming Masterclass 系列里,第 5 部分会把学习重心从“写好一段能运行的代码”转移到“把代码组织成可复用的函数”。前面几部分通常已经覆盖了变量、数据类型、条件判断和循环,这些内容能让你写出执行固定流程的脚本;但脚本一旦超过几十行,重复逻辑变多,或者需要在多个文件之间共享同一段处理过程,直接复制粘贴就会让代码迅速失控。本部分要解决的就是这个问题:理解 Python 函数的工作原理,掌握 def、参数、return、作用域、lambda 和类型标注,学会从 traceback 和日志里定位函数调用链上的错误,最后形成一套能直接用于练习和小项目开发的函数设计习惯。
适合阅读本部分的读者有两类:一类是从零开始学 Python、已经会写循环和条件判断但还没有系统学过函数的初学者;另一类是写过一些脚本、经常遇到函数返回 None、参数顺序传错、在函数内修改全局变量报错等问题的开发者。学完后,你应该能完成这些事:把重复逻辑抽成独立函数;用位置参数、默认参数、*args、**kwargs 设计灵活的函数接口;用元组、字典或数据类把多个计算结果组织成结构化返回;看懂函数相关的常见报错并从 traceback 反推调用链;用日志和断言验证函数是否真的符合预期。
1. 为什么程序需要函数:从“顺序代码”到“按职责拆分”
1.1 函数解决的实际问题:复用、隔离、可维护
先看一个没有函数时的常见场景。假设要计算一个长方形的面积,还要计算一个圆的面积,最简单的写法是:
python复制rectangle_area = 10 * 5
circle_area = 3.14159 * 4 * 4
这段代码能跑,但有几个隐患:如果面积公式要调整,比如改用更精确的圆周率,你得找到每一处计算公式并逐个修改;如果同一个计算逻辑出现在十个地方,其中一处漏改,程序就会悄悄出错。函数的意义就是把“计算长方形面积”这件事封装成一份实现,让所有调用方都指向这份实现。
python复制def rectangle_area(width, height):
return width * height
def circle_area(radius):
return 3.14159 * radius * radius
从这个例子能看到函数带来的三个变化。第一是复用:公式只写一次,调用方不需要关心内部细节。第二是隔离:计算逻辑被隔离在一个独立单元里,修改实现时只要保证参数和返回值不变,调用方基本不用跟着改。第三是可维护:函数名本身就表达了意图,别人读代码时看到 circle_area(4),不需要再脑补 3.14159 * 4 * 4 在算什么。
这里要理解一个关键点:函数是一种“接口约定”。调用方关心的是三个信息——函数名、需要传入什么参数、会返回什么结果。至于函数内部是用 while 还是 for,是先排序再取最大值还是直接用 max(),都是实现细节。把接口和实现分开,是函数化改造里最重要的一步。
1.2 函数调用背后的机制:定义、调用与调用栈
Python 里 def 语句本身不会执行函数体。它做的事情是创建一个函数对象,并把函数体绑定到这个对象上。真正执行函数体的时机是调用时。这意味着函数体里出现的变量查找、参数绑定、return 跳转,全部发生在调用那一刻。
python复制def outer():
print("outer called")
inner()
def inner():
print("inner called")
deeper()
def deeper():
raise ValueError("最深处的错误")
outer()
运行后,deeper() 抛出异常,Python 会打印类似这样的 traceback:
text复制Traceback (most recent call last):
File "demo.py", line 10, in <module>
outer()
File "demo.py", line 2, in outer
inner()
File "demo.py", line 5, in inner
deeper()
File "demo.py", line 8, in deeper
raise ValueError("最深处的错误")
ValueError: 最深处的错误
这段信息值得仔细读:它从 outer() 开始,依次记录每一层函数调用,直到错误的真正发生位置 deeper()。函数调用会形成一条调用栈:outer 调用 inner,inner 再调用 deeper,每一层函数在被调期间,它的局部变量都保存在自己的栈帧里;函数 return 之后,对应的栈帧随之销毁。
另一个容易踩坑的现象是“函数定义在后面”的问题。下面这个写法会报 NameError:
python复制def use():
hello()
use()
def hello():
print("hi")
原因是调用 use() 时,hello 还没有被定义,解释器在全局命名空间里找不到这个名字。函数体里的名字是在调用时查找的,不是调用时才开始执行 def。所以推荐把入口调用统一放在所有函数定义之后,或者放在 if __name__ == "__main__" 入口里,这类错误基本可以避免。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备与练习基线:先跑通第一个函数文件
2.1 检查 Python 环境并创建练习目录
本部分练习只需要 Python 标准库,不需要安装第三方包,所以环境准备并不复杂。先确认你机器上的 Python 版本:
bash复制python --version
python3 --version
Windows 环境有时需要使用启动器命令,可以执行:
bash复制py -3 --version
确认版本后,创建一个干净的练习目录,并新建一个 Python 文件:
bash复制mkdir py_func_practice
cd py_func_practice
常见项目中,目录名一般使用小写字母加下划线,例如 py_func_practice。后续所有示例都放在这个目录下运行,减少路径混乱导致的 ModuleNotFoundError。
注意:学习阶段可以不用虚拟环境,直接用系统 Python;但进入真实项目后,每个项目都应该创建独立的 venv,并把依赖记录在
requirements.txt或pyproject.toml中。
2.2 从最简单的无参函数到有返回值函数
先写一个没有参数、没有返回值的函数,用来理解“函数体在调用时才执行”:
python复制def greet():
print("hello, python")
greet()
greet() 函数体内只有一条打印语句,没有 return。这种情况下,函数执行结束后会隐式返回 None。很多人刚开始会混淆“打印”和“返回”,看下面这个例子:
python复制def greet():
print("hello, python")
result = greet()
print(result)
运行结果是先打印 hello, python,再打印 None。result 拿到的并不是函数内部的输出内容,而是函数的返回值。要让函数把计算结果交回给调用方,必须使用 return:
python复制def add(a, b):
result = a + b
return result
total = add(10, 20)
print(total)
这里 add 接收两个参数,计算后通过 return 把结果交回。调用方拿到这个值后,可以继续做运算、拼接或其他处理。print 负责把内容显示到终端,return 负责把值传递给外层代码,两者职责不同,是函数学习里第一个要分清的边界。
2.3 用 if name == "main" 组织验证入口
随着练习的继续,一个文件里会同时出现多个函数和多个验证代码。如果验证代码直接写在文件顶层,以后别人用 import 导入这个模块时,验证代码也会跟着执行,这不是我们希望的行为。推荐的写法是把验证代码收进 main(),再用 __main__ 判断控制入口:
python复制def add(a, b):
return a + b
def main():
print(add(10, 20))
print(add("py", "thon"))
if __name__ == "__main__":
main()
直接运行这个文件时,Python 会把当前模块的 __name__ 设为字符串 "__main__",所以 main() 会执行,输出结果为:
text复制30
python
当其他文件用 import 导入这个模块时,__name__ 是模块名,不会等于 "__main__",验证代码就不会执行。养成把测试调用放进 __main__ 入口的习惯,后面学习模块拆分时会非常省事。
3. 参数传递:位置参数、关键字参数、默认值与不定长参数
3.1 位置参数与关键字参数:调用时的两种传参方式
函数定义里的参数决定了调用方要提供哪些信息。Python 支持两种传参方式:位置参数按顺序传入,关键字参数用 参数名=值 的方式传入。
python复制def describe(name, level):
print(f"{name} 的等级是 {level}")
# 位置参数:按定义顺序传
describe("Python", 3)
# 关键字参数:名字和值一一对应
describe(name="Python", level=3)
# 混合使用:位置参数必须放在关键字参数前面
describe("Python", level=3)
三条调用都能正确执行。混合调用时有一个语法约束:关键字参数不能出现在位置参数之前。下面这条会直接报 SyntaxError:
python复制describe(name="Python", 3)
还有一种相当常见的运行时错误,是同一个参数被传了两次。例如:
python复制describe("Python", name="C++")
调用时第一个 "Python" 会按位置绑定到 name,关键字里又指定了 name="C++",同一参数被赋值两次,Python 会报:
text复制TypeError: describe() got multiple values for argument 'name'
这类错误在删除参数名或调整参数顺序后尤其容易发生。排查时先看调用处的传参方式:位置参数、关键字参数、混合调用,三者占用的参数位必须互不冲突。
| 参数类型 | 调用示例 | 特点 |
|---|---|---|
| 位置参数 | describe("Python", 3) |
直观,但依赖参数顺序 |
| 关键字参数 | describe(level=3, name="Python") |
顺序可随意,可读性强 |
| 混合调用 | describe("Python", level=3) |
需要保证位置参数在前 |
3.2 默认参数的位置与可变默认值的坑
默认参数让调用方可以省略部分参数。定义时,带默认值的参数必须放在必选参数后面:
python复制def draw(color, line_width=1):
print(color, line_width)
draw("black")
draw("red", 3)
如果写成 def draw(color="black", line_width):,Python 会报 SyntaxError: non-default argument follows default argument。这是因为解释器无法判断 line_width 到底该默认覆盖到哪一位。这个规则本身不难,难的是可变默认值。
来看一段危险代码:
python复制def store(item, box=[]):
box.append(item)
return box
print(store("a"))
print(store("b"))
print(store("c"))
很多人预期每次调用都返回一个全新的列表,实际输出却可能是:
text复制['a']
['a', 'b']
['a', 'b', 'c']
原因在于默认列表 [] 只在函数定义时创建一次,之后所有调用共享同一个列表对象。store("b") 是在上一轮调用留下的列表上继续追加。这个坑在真实项目中会造成数据累积和难以复现的怪异行为。
推荐的写法是把可变默认值换成 None,在函数内部初始化:
python复制def store(item, box=None):
if box is None:
box = []
box.append(item)
return box
这样每次不传 box 时都会得到一个新的空列表,行为符合预期。原则是:默认值只用不可变对象,例如数字、字符串、None;列表、字典、集合这类可变对象要用 None 占位再初始化。
3.3 用 *args 和 **kwargs 接收不定数量参数
有些函数的参数数量不固定,比如计算任意多个数字的总和。*args 会把所有未匹配的位置参数收集成一个元组,**kwargs 会把所有未匹配的关键字参数收集成一个字典。
python复制def total(*numbers):
return sum(numbers)
print(total(1, 2, 3))
print(total(1, 2, 3, 4, 5))
python复制def show_info(**kwargs):
for key, value in kwargs.items():
print(f"{key}: {value}")
show_info(name="Python", version=3, level="Beginner")
*numbers 在函数内部是一个元组,即使只传入一个参数也可以正常遍历;**kwargs 在函数内部是一个字典,适合处理带名字的可选配置项。两个名字只是一个约定,叫 *args 和 **kwargs 是社区习惯,但换成 *items、**settings 同样合法。
这里要提醒:不要什么都收进 *args 和 **kwargs。如果参数的个数和含义本来就是明确的,显式写出参数名能让函数接口更清楚。*args 和 **kwargs 最常见的两种正确用途,一是处理数量不确定的同质参数,二是写装饰器或包装函数时把参数统一直传:
python复制def wrapper(*args, **kwargs):
return target(*args, **kwargs)
3.4 可变对象作为参数:引用传递还是值传递
Python 传参时,实际上传递的是对象引用,而不是把对象复制一份。但对“修改”要有更细的区分:修改引用指向的对象内容,和重新绑定引用,结果是两回事。
python复制def add_item(target, value):
target.append(value)
tags = ["python"]
add_item(tags, "function")
print(tags)
输出是 ['python', 'function'],因为 target.append(value) 修改的是外部列表对象本身,调用方会看到变化。下面这段则不会:
python复制def rebuild(target, value):
target = target + [value]
tags = ["python"]
rebuild(tags, "function")
print(tags)
输出仍是 ['python']。原因是 target = target + [value] 创建了一个新列表,并把函数内部的局部名 target 重新绑定到这个新列表上;外部变量 tags 仍然指向原来的列表,所以不受影响。
| 参数情况 | 函数内写法 | 调用方数据是否会变 |
|---|---|---|
| 直接操作原对象 | target.append(value) |
会变 |
| 重建对象并重新绑定 | target = target + [value] |
不变 |
| 复制后修改 | target = target[:] 再做修改 |
不变 |
实际写函数时,如果函数会修改传入的列表或字典,最好在函数名上体现出来,例如 add_item、remove_duplicated。如果函数名是中性的,比如 process_scores,调用方通常不会预期原数据被改写。要么复制一份再处理,要么在文档和注释里写清楚“本函数会原地修改入参”。
4. 返回值:从单个值到结构化数据
4.1 return 的作用与“隐式返回 None”的坑
return 有两个作用:结束当前函数的执行,并把后面的表达式作为结果交回给调用方。如果函数没有写 return,或者只写了 return 不带值,调用方拿到的是 None。
一个典型错误是函数里计算了结果,但忘记返回:
python复制def to_float(value):
value = float(value)
result = to_float("3.14")
print(result)
to_float 内部确实完成了类型转换,但没有把转换结果交回,result 是 None。调用方如果继续用 result + 1 这类运算,就会得到报错:
text复制TypeError: unsupported operand type(s) for +: 'NoneType' and 'int'
另一个容易混淆的场景是条件分支里的误用:
python复制def discount(price, percent):
if percent > 100:
print("折扣率不能超过 100")
return
return price * (100 - percent) / 100
print(discount(200, 120))
print(discount(200, 20))
第一条调用打印完提示后,函数执行到 return 结束,返回值是 None,外层再次 print(None)。这个行为本身没有错,但它提醒我们:不返回值的 return 是一种“提前结束”信号,调用方必须意识到结果是 None。在后续学习异常处理后,非法输入更适合用 raise ValueError(...) 来通知调用方,而不是静默返回 None。
4.2 返回元组、字典和命名元组:常见选择
一个函数通常只负责一件事,但一件事的结果可能由多个部分组成。比如计算一组数字的最小值和最大值,可以用元组返回:
python复制def min_max(numbers):
return min(numbers), max(numbers)
lowest, highest = min_max([3, 9, 1, 6])
print(lowest, highest)
元组用逗号分隔即可组成,返回多个值时调用方可以直接解包。但对于字段更多、语义更强的数据,比如一个学生的分数和等级,用字典更清楚:
python复制def calculate_grade(score):
if score >= 90:
level = "A"
elif score >= 75:
level = "B"
else:
level = "C"
return {"score": score, "level": level}
info = calculate_grade(88)
print(info["score"], info["level"])
字典的优势是字段有名字,调用方不会因为返回顺序变化而解包错位。缺点是字段缺少类型约束,拼写错误的键会在运行时才暴露。项目越来越大时,可以用 dataclass 定义更明确的结构:
python复制from dataclasses import dataclass
@dataclass
class Grade:
score: float
level: str
def calculate_grade_with_type(score):
if score >= 90:
level = "A"
elif score >= 75:
level = "B"
else:
level = "C"
return Grade(score=score, level=level)
g = calculate_grade_with_type(88)
print(g.score, g.level)
| 返回结构 | 适用场景 | 优点 | 注意点 |
|---|---|---|---|
| 元组 | 少量且顺序有约定的返回值 | 简单、解包方便 | 字段多时容易错位 |
| 字典 | 需要字段名的轻量结构 | 字段语义清楚 | 键名无静态检查 |
| dataclass | 结构复杂、字段固定的业务对象 | 字段强类型、IDE 提示 | 定义成本稍高 |
4.3 用一个小函数串联类型转换、切片与过滤
把前面几个概念放在一个函数里,就能看出函数封装的真实收益。假设有一批原始成绩数据,里面混入了字符串、None 和越界值,需要清洗后取前三名并计算平均分:
python复制def clean_scores(raw_scores):
nums = []
for x in raw_scores:
try:
num = float(x)
except (TypeError, ValueError):
continue
if 0 <= num <= 100:
nums.append(num)
nums.sort(reverse=True)
top3 = nums[:3]
return {
"valid_count": len(nums),
"top3": top3,
"average": round(sum(nums) / len(nums), 2) if nums else 0,
}
raw = ["85", "abc", None, "90", "70.5", "59", "102"]
result = clean_scores(raw)
print(result)
执行结果大致为:
text复制{'valid_count': 4, 'top3': [90.0, 85.0, 70.5], 'average': 76.12}
这个函数综合了类型转换、切片的取值方式、数值范围和结构化返回。try/except 在这里的作用是跳过无法转换的脏数据,避免整个清洗中断。调用方只需要传入原始列表,拿到的是一个带字段名的字典,不用关心内部如何过滤和排序。把类似逻辑封装成函数后,真实项目里无论数据来自 CSV、数据库还是接口,都能用同一个处理函数应对。
5. 作用域与名字查找:为什么函数内修改全局变量会报错
5.1 LEGB 查找顺序:局部、外层、全局、内置
Python 在函数内部查找一个名字时,按四层顺序进行:Local(当前函数局部作用域)、Enclosing(外层函数作用域)、Global(模块全局作用域)、Built-in(内置名字)。理解这个顺序,才能解释很多看似奇怪的现象。
python复制count = 10
def show():
count = 20
return count
print(show()) # 20
函数内部有局部 count,所以返回的是 20,外部全局 count 仍然是 10。如果函数内部没有局部 count,查找会继续向上,找到全局变量。如果全局也没有,最后会找到内置名字。
内置名字被遮蔽是一个更隐蔽的情况:
python复制def count_items(seq):
len = 0
for _ in seq:
len += 1
return len
上面的 len 是局部变量,遮蔽了内置函数 len。函数内部本身没有再调用内置 len,所以结果正确。但如果在函数里既定义局部 len,又调用 len(seq),就会得到 TypeError: 'int' object is not callable。因此不推荐用 list、dict、len、id、type 这类名字当变量名或参数名。
| 作用域名称 | 位置 | 生命周期 |
|---|---|---|
| Local | 当前函数内的变量和参数 | 函数调用期间存在 |
| Enclosing | 嵌套函数中的外层函数变量 | 外层函数调用期间存在 |
| Global | 模块顶层的变量 | 模块导入后常驻 |
| Built-in | 内置函数、内置类型 | 解释器启动时存在 |
5.2 读取全局变量可以,修改必须声明 global
函数内读取全局变量是允许的:
python复制api_retry = 3
def read_retry():
return api_retry
print(read_retry()) # 3
但如果想在函数里修改全局变量,直接写会报错:
python复制api_retry = 3
def increase_retry():
api_retry += 1
increase_retry()
运行后的报错是:
text复制UnboundLocalError: local variable 'api_retry' referenced before assignment
原因是函数体内出现了 api_retry += 1,Python 看到赋值操作后,会把这个名字当成局部变量。局部变量在赋值之前被读取,自然报错。解决办法是加一行 global 声明:
python复制api_retry = 3
def increase_retry():
global api_retry
api_retry += 1
increase_retry()
print(api_retry)
加 global 后,函数内不再创建局部变量,而是直接操作模块全局的 api_retry。这个写法能解决问题,但真实项目中要少用:全局可变量会让函数之间产生隐藏依赖,测试时也很难隔离状态。更稳妥的策略是把值传入函数,再通过返回新值的方式更新:
python复制def increase_retry(retry):
return retry + 1
api_retry = increase_retry(api_retry)
这样函数与外界的唯一通道还是参数和返回值,状态变化一目了然。
5.3 闭包与 nonlocal 的典型场景
与 global 对应的还有一个 nonlocal,它用于嵌套函数中修改外层函数的变量。一个典型例子是计数器工厂:
python复制def make_counter(step=1):
count = 0
def add():
nonlocal count
count += step
return count
return add
counter = make_counter(2)
print(counter()) # 2
print(counter()) # 4
这里 add 是内层函数,它引用了外层函数 make_counter 里的 count。由于 add 仍持有这个引用,外层函数返回后,count 的栈帧并没有被完全丢弃。nonlocal 告诉解释器:count += step 中的 count 指的是外层作用域里的变量,而不是创建一个新的局部变量。
闭包是后续学习装饰器、惰性计算和状态保持时会反复遇到的概念。初学者可以先记住两点:内层函数可以读取外层函数的变量;如果需要修改外层变量,必须显式写 nonlocal。现阶段不必追求彻底掌握闭包,知道它在嵌套函数场景下的作用即可。
6. 匿名函数与类型标注:让函数边界更清楚
6.1 lambda 适合的场景和该避免的场景
lambda 用来写简单的匿名函数,适合传递给其他函数做“一次性”参数。一个常见场景是排序时指定排序依据:
python复制points = [
{"name": "A", "distance": 12.5},
{"name": "B", "distance": 3.2},
{"name": "C", "distance": 9.0},
]
points.sort(key=lambda p: p["distance"])
print(points)
这段代码按 distance 字段从小到大排序。key 参数接收一个函数,lambda p: p["distance"] 就是这个函数。等价写法是定义普通函数:
python复制def by_distance(p):
return p["distance"]
points.sort(key=by_distance)
两条都正确。选择标准很简单:逻辑只有一条表达式且只在当前位置使用一次,用 lambda 顺手;逻辑超过一行,或者需要复用,就用 def。特别要提一条规范:不要写 add = lambda x, y: x + y 这种把匿名函数赋给名字的代码,PEP 8 建议这种情况直接使用 def add(x, y): return x + y。
6.2 类型标注:给调用者和自己补上使用说明书
Python 是动态类型语言,函数并不强制要求标注参数和返回类型。但给函数加上类型标注,能让“参数应该传什么、结果是什么”变得更清楚:
python复制def calculate_total(price: float, quantity: int = 1) -> float:
return price * quantity
这里 price: float 表示参数期望是浮点数,quantity: int = 1 表示整数参数且有默认值,-> float 表示返回浮点数。类型标注在运行时不强制检查,传字符串也能运行,但 IDE 会根据标注提示可疑调用,静态检查工具(如 mypy)也能提前发现类型错误。
对于更复杂的容器结构,可以用 typing 里的类型名:
python复制from typing import List, Optional
def first_valid(values: List[Optional[float]]) -> Optional[float]:
for value in values:
if value is not None:
return value
return None
Optional[float] 表示“可能是浮点数,也可能是 None”。标注本身不会消灭 bug,它的价值是把函数接口的约束显式写出来,让问题从运行阶段提前暴露到开发和检查阶段。学习函数阶段就养成标注习惯,对后面理解泛型、装饰器和数据类都有帮助。
6.3 用函数作为参数:sorted、filter 与 map 的典型用法
把函数当作参数传给另一个函数,是 Python 里非常常见的抽象方式。前面 sorted(key=...) 已经是一个例子。再看三个配套用法:
python复制words = ["python", "java", "c", "golang"]
# 用内置函数 len 作为排序依据
sorted_by_len = sorted(words, key=len)
print(sorted_by_len)
# filter 保留满足条件的元素
selected = list(filter(lambda w: len(w) > 3, words))
print(selected)
# map 对每个元素执行转换
upper_list = list(map(str.upper, words))
print(upper_list)
filter 和 map 返回的都是迭代器,要用 list() 包裹才能一次性拿到结果列表。这段代码的核心不是记住 filter 和 map 的语法,而是理解“函数可以作为参数传递”这件事。sorted 的 key 可以是内置函数 len,可以是 lambda,也可以是自己定义的 def 函数。
需要说明的是,很多简单场景用列表推导式更可读:
python复制selected = [w for w in words if len(w) > 3]
upper_list = [w.upper() for w in words]
在真实项目里,列表推导式通常比 filter 加 map 的组合更清晰。学习 filter 和 map 的意义在于理解函数式思维,以及在你接手别人代码时能看懂这种写法。
7. 调试与排错:从 traceback 里读懂函数的调用链
7.1 看懂最常出现的三类函数报错
第一类常见报错是语法层面的默认参数位置错误:
text复制def draw(color="black", line_width):
^
SyntaxError: non-default argument follows default argument
这是写参数列表时把带默认值的参数放在了必选参数前面。修复方法很简单:调整参数顺序。
第二类常出现在调用阶段,是参数数量不匹配:
text复制TypeError: add() missing 1 required positional argument: 'b'
TypeError: add() takes 2 positional arguments but 3 were given
TypeError: describe() got multiple values for argument 'name'
第一条是少传参数,第二条是多传参数,第三条是位置参数和关键字参数重复指定了同一个参数。这三条的共同排查方向是核对“函数定义需要多少参数”和“调用处实际传了多少参数”。
第三类是作用域相关报错:
text复制UnboundLocalError: local variable 'api_retry' referenced before assignment
看到这个报错,第一反应是检查函数体内有没有给同名变量赋值。只要出现了赋值,Python 就会把该名字当作局部变量。如果本意是操作全局变量,就加 global;如果只是想要一个局部变量,就换个名字,或者先给局部变量初始化赋值。
读懂 traceback 的顺序很重要。报错最后一行是异常类型和描述,往上每一段 File "xxx.py", line N, in func_name 都代表调用链上的一层。先读最下面的描述确定错误类型,再从最内层的函数开始检查,最后再判断是不是外层调用方传参不当。
7.2 用日志和断言代替散落 print
调试函数时,很多人习惯在关键位置写 print。学习阶段这样没问题,但真实项目里打印语句很难管理:不知道来自哪个模块、无法分级、上线时还要逐个删。一个更接近生产环境的做法是使用标准库 logging:
python复制import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("func_demo")
def divide(a, b):
logger.debug("divide called with %s, %s", a, b)
return a / b
print(divide(10, 2))
logger.debug 可以把参数流向打到终端,同时带着 logger 名字,方便定位消息来源。生产环境可以把 level 调到 INFO 或 WARNING,调试信息就不会刷屏。
验证函数结果时,可以用断言做最小检查:
python复制def normalize(value):
assert isinstance(value, (int, float)), "value must be number"
return float(value)
assert normalize(3) == 3.0
assert normalize("4.5") == 4.5
print("basic checks passed")
要清楚 assert 的边界:它是开发期检查工具,运行 Python 时加 -O 参数会跳过断言,所以不能用它做生产环境的业务校验。它的价值是在学习阶段帮你快速发现“函数结果和预期不一致”的问题。
7.3 函数相关常见问题排查路径
遇到函数层面的报错,可以按“现象 -> 原因 -> 检查方式 -> 处理建议”的顺序排查。下面的表格汇总了本部分最常出现的问题:
| 问题现象 | 常见原因 | 检查方式 | 处理建议 |
|---|---|---|---|
| 函数调用结果总是 None | 漏写 return 或 return 后没跟值 | 打印调用结果,检查函数体末尾 | 明确返回计算值;错误分支用异常机制 |
| 报 multiple values for argument | 位置参数和关键字参数重复传同一个参数 | 检查调用处传参组合 | 一个参数只通过一种方式传递 |
| 默认列表参数数据累积 | 使用了可变默认值,如 box=[] |
连续调用两次并打印返回值 | 改为 box=None 后在函数内初始化 |
| 函数内修改全局变量报 UnboundLocalError | 赋值操作让变量被当成局部变量 | 检查函数体内同名赋值语句 | 用 global 声明或改为参数传入、返回新值 |
| 调用发生在定义之前报 NameError | 函数定义在调用语句之后 | 看调用行号和函数定义行号 | 把调用统一放到所有定义之后或 __main__ 入口 |
| 列表参数被函数意外修改 | 函数内对入参调用 append 等方法 | 比较函数调用前后的入参内容 | 先复制 data[:],或在函数名里标明原地修改 |
| 类型运算报 unsupported operand | 把字符串或 None 当数值计算 | 打印参数类型 | 先做类型转换和校验 |
排查时优先检查输入是否正确,然后是函数定义和调用处的参数数量、位置、名字是否匹配,最后才是运行环境和依赖问题。对初学者来说,日志里明确打印参数类型和值,往往比盯着报错猜更快。
7.4 每个函数应该做的最小验证
函数写完不是结束,至少要验证三类输入:正常输入、边界输入、错误输入。以计算总价的函数为例:
python复制def calculate_total(price, quantity):
if price < 0 or quantity < 0:
return 0
return price * quantity
# 正常输入
assert calculate_total(10, 2) == 20
# 边界输入
assert calculate_total(0, 5) == 0
# 错误输入按约定处理
assert calculate_total(-5, 2) == 0
print("basic checks passed")
这套验证虽然简单,但足以在改函数内部逻辑时提供最基础的回归保护。后面学到 pytest 后,可以把这类断言改造成真正的测试用例,对不同输入组合做更系统的验证。现在的关键不是写多少用例,而是养成“每个函数至少跑一遍正常值、边界值和异常值”的检查习惯。
8. 最佳实践与下一步
8.1 函数设计的五个可执行原则
函数设计不需要一开始就追求完美,但有几条原则可以从第一次写函数时就照着做。
第一,一个函数只做一件事。函数名一般是动词加名词,例如 get_average_score、save_user_profile、parse_config。如果给函数起名时要加“并且”,说明这个函数承担了太多职责,应该拆开。
第二,参数尽量控制在四个以内。参数太多时,调用方很难记住顺序和含义。超过四个,可以考虑把相关参数收进一个字典或 dataclass。如果两个函数只有布尔参数不一样,通常意味着需要拆成两个更明确的函数。
第三,不要混合返回类型。同一个函数要么总是返回元组,要么总是返回字典,要么总是返回 None,不要这次返回一个列表,下次返回一个字符串。混合返回类型会让调用方必须到处判断分支。
第四,明确输入是否会被修改。如果函数会修改传入的列表或字典,要么在函数名里体现,要么先复制再处理。默认情况下,中性命名的函数不应让调用方的数据悄悄变化。
第五,默认值要安全。可变默认值统一使用 None 占位,函数内部再初始化。这个原则不仅避免数据共享问题,也让新读者更容易看懂函数的行为。
8.2 学习环境与生产环境的差异
本部分的练习环境是一台开发机加一个 .py 文件,运行通过即可。真实项目的要求比这严格得多,两者差异可以用一张表概括:
| 维度 | 学习环境 | 生产环境要求 |
|---|---|---|
| 验证输出 | print 直接打印 |
使用 logging,分级记录,能按日志检索 |
| 模块组织 | 单文件练习 | 按职责拆分模块,私有函数用 _ 前缀 |
| 错误处理 | 先避免,尽量让程序直接报错 | 用明确异常类型,记录上下文,考虑回滚 |
| 类型标注 | 可选 | 项目规范可能要求完整标注 |
| 配置参数 | 写在函数内部 | 参数外置到配置文件或环境变量 |
| 依赖管理 | 不强制 | venv 加锁文件,记录版本 |
| 验证手段 | 手动运行加断言 | pytest、CI 自动测试,覆盖正常、异常、边界场景 |
生产环境还要额外考虑日志是否包含足够上下文、权限是否收敛、监控是否能感知函数调用失败、异常是否会影响后续任务,以及发布后如何回滚。这些内容在后续各部分会逐步展开,但学习函数时就可以先建立意识:能复用、能测试、能排查,才是生产级代码的基本门槛。
8.3 下一步可以扩展的方向
本部分学完后,下一步有四个比较自然的延伸方向。
第一个是异常处理。函数遇到底层数据错误时,应该用 raise ValueError 或自定义异常明确通知调用方,而不是返回 None 或打印一句话后继续运行。第二个是文件读写。把 clean_scores 这类函数结果写入 CSV 或 JSON 文件,就能组成一个完整的数据处理流程。第三个是模块化。把相关函数拆到多个 .py 文件里,用 import 导入,这样会自然接触到 __all__、命名空间和包结构。第四个是测试。用 pytest 把函数的最小验证从 assert 升级成真正的测试用例,对参数组合和边界输入做系统覆盖。
对新手来说,最有价值的练习不是继续看教程,而是把前面已经写过的脚本逐个改造成函数版本。每个函数至少包含参数、返回值、默认值处理和一个 __main__ 入口,然后给每个函数补上三个断言。做完这一步,你会明显感觉到“顺手的代码”和“可复用的代码”之间的差别。
这一部分最重要的技术判断是:函数不是让代码变短的小技巧,而是让代码边界变清楚的手段。参数是输入契约,返回值是结果契约,作用域决定名字的可见范围。写函数时先想清楚这三件事,再去补代码;运行时先跑正常值、边界值和错误值,再谈功能完成。把这条流程练成习惯,比记住任何单个语法细节都更值得。
