Python函数设计进阶：参数契约、闭包、装饰器与生成器实战

写了几年 Python 的人，最容易栽跟头的往往不是类、不是异步、也不是什么框架，而是函数——准确地说，是函数的参数设计和返回值约定。我见过太多项目，一个函数长到八百行，参数列表横跨三行，调用处全靠 IDE 提示猜，改一个参数全仓库爆炸。Python 函数这东西，语法三分钟就能学会，但要写得让同事愿意读、让三个月后的自己看得懂，是另一回事。

这篇不打算从def怎么写讲起，那个太浅了。我准备把函数拆成几个层次来讲：它在解释器里到底是个什么东西、参数机制有哪些反直觉的细节、作用域和闭包会在什么时候咬你一口、装饰器和生成器该怎么用才不别扭，最后聊聊函数层面的性能与调试。不管你是刚学完语法的新手，还是写了一两年业务代码想往上走一步的人，应该都能从里面捞到点能直接用的东西。文中所有代码我都实际跑过，坑也是真踩过的。

1. 函数写不好，多半是没想清楚"边界"这件事

1.1 一个函数多长算合适：从职责说起

我不太信"函数不能超过 50 行"这种硬指标，但我信一条：一个函数只做一件事，且这件事能用一句话说清楚，不带"并且"。你试着用自然语言描述你的函数，如果描述里出现了"然后再""同时""顺便"，那它就该拆了。

举个我在一个模拟项目里见过的真实例子。有个函数叫process_order，干的事包括：校验参数、查库存、算价格、写日志、发通知、更新缓存。六件事塞在一起，结果是任何一件事要改动，都得把这个函数完整读一遍，还得担心动到别的地方。后来拆成六个小函数，每个三十行左右，主函数变成一个编排流程的骨架，可读性立刻不一样了。

拆的时候有个判断标准挺好用：看这个函数里出现了几种"变化的原因"。如果需求变更来自不同方向——价格规则变了、通知渠道变了、缓存策略变了——那它们本来就该是独立的函数。放一起的唯一后果是，每次改动都在同一个地方制造冲突。

还有一种情况是函数本身不长，但嵌套层级深。三层if套for再套try，缩进已经到屏幕右边了。这种我一般用"提前返回"处理：把异常分支和边界条件在函数开头一次性挡掉，主逻辑保持在最外层。代码行数可能没少，但阅读路径从"之字形"变成了"直线"。

1.2 参数列表是函数的接口契约

参数列表的信息量比函数体还大。一个函数如果有八个位置参数，调用处基本就是灾难——create_report(data, True, False, None, 3, "pdf", True, 0)，除了写的人，没人知道那几个布尔值是什么意思。

我处理这种情况的固定套路是：参数超过四个，就考虑收成一个配置对象。Python 3.7 之后有dataclass，几行代码就能定义清楚：

from dataclasses import dataclass @dataclass class ReportOptions: fmt: str = "pdf" include_charts: bool = True page_size: str = "A4" timeout: int = 30 def create_report(data, options: ReportOptions): ...

调用处变成create_report(data, ReportOptions(fmt="xlsx", include_charts=False))，每个字段自带名字，改起来也不会错位。代价是多了一个类，但这个代价换来的是半年的可维护性。

参数顺序也有讲究。我的习惯是：必填在前、可选在后；数据主体在前、配置项在后；容易搞混的类型不要挨着放。最后这条是因为我吃过亏——有个函数签名是(source, target)，两个都是字符串，某次调用写反了，测试没覆盖到，跑到线上才发现文件写到了错误目录。

1.3 返回值的设计：None 的滥用与显式失败

return None是 Python 里最暧昧的表达。它可能意味着"没找到"，也可能意味着"出错了但我不想说"，还可能是"函数正常执行完了但没啥可返回"。调用方拿到None根本分不清是哪种。

我的原则是：能用异常表达的失败，就别用 None。查一个用户，查不到就抛UserNotFound，调用方要么处理要么让它往上冒，至少不会静默地继续往下跑然后在一个莫名其妙的地方崩掉。

如果确实需要用"空值"语义，那就明确区分。比如一个批量查询接口，返回dict而不是list，key 是查询条件，value 是结果或None，这样调用方一眼能看出哪些没查到。再比如用哨兵对象：

_MISSING = object() def get_config(key, default=_MISSING): if key in _CONFIG: return _CONFIG[key] if default is _MISSING: raise KeyError(key) return default

这样调用方传不传 default 是两种行为，语义清晰，不会出现"我想传 None 当默认值，结果和没传一样"的尴尬。

2. def 语句背后：函数对象、帧与调用链路

2.1 函数是一等公民：能被赋值、传参、返回

很多人把"函数是一等公民"当成一句口号背下来，但没真正用起来。它的实际含义是：def执行完之后，函数名只是一个普通变量，绑定的值是一个函数对象。你可以把它存进列表、放进字典、当参数传、当返回值返回。

这个特性最实用的场景是用字典替代长串 if-elif：

def handle_create(payload): ... def handle_update(payload): ... def handle_delete(payload): ... HANDLERS = { "create": handle_create, "update": handle_update, "delete": handle_delete, } def dispatch(action, payload): handler = HANDLERS.get(action) if handler is None: raise ValueError(f"unknown action: {action}") return handler(payload)

比十几个elif action == "xxx"好在哪？新增一种动作只需要往字典里加一行，不用动dispatch函数本体，也不容易漏改。这就是"数据驱动"比"控制流驱动"省事的地方。

函数作为返回值也很常用，典型的是"带配置的工厂"：make_validator(max_len=10)返回一个校验函数，校验逻辑写一次，参数不同就返回不同的函数实例。这种写法在需要批量生成回调的地方特别顺手。

2.2__defaults__、__closure__、__code__各存了什么

函数对象上挂着几个双下划线属性，理解了它们，很多"玄学"现象就有解释了。

实测一下：

def greet(name, prefix="Hi"): return f"{prefix}, {name}" print(greet.__defaults__) # ('Hi',) print(greet.__code__.co_varnames) # ('name', 'prefix') print(greet.__code__.co_argcount) # 2

co_argcount是位置参数个数（含带默认值的），co_kwonlyargcount是仅限关键字参数个数，co_varnames前几个就是参数名。写装饰器的时候如果不加functools.wraps，这些东西全会被wrapper覆盖掉，help()出来一片空白，签名也变成(*args, **kwargs)，这就是下一节要讲的问题。

2.3 一次调用在解释器里走过的路径

理解调用链路，最直接的好处是能读懂 traceback。

当你写result = calc(a, b)的时候，CPython 大致做了这些事：先在当前帧的局部变量、闭包、全局、内置里按顺序找calc这个名字，找到函数对象；然后把a、b压栈；接着创建一个新的帧对象（frame），里面包含这个函数的局部变量表、指令指针、以及一个指向上层帧的f_back；之后解释器开始在新帧里执行字节码；执行完返回值压回调用方的栈，帧被销毁（除非被 traceback 引用住）。

traceback 之所以能打印出完整调用链，就是因为它沿着f_back一路往上追。这也是为什么在except块里保存异常对象会导致内存占用升高——异常对象持有 traceback，traceback 持有帧，帧持有局部变量，整条链上的对象都释放不掉。长期存活的服务里如果频繁捕获异常又不清理，内存会缓慢上涨。处理办法是except Exception as exc: ...里只取str(exc)，或者用traceback.format_exc()转成字符串，别把异常对象本身存进列表里。

顺带提一句，sys._getframe()能拿到当前帧，但那是私有 API，行为在不同实现上不一定一致，业务代码里别依赖它，调试时用用还行。

3. 参数机制拆解：从默认值陷阱到仅限关键字参数

3.1 默认参数为什么不能写可变对象

这是 Python 函数里最经典的坑，几乎每个教程都会提，但每年还是有人踩。看这段：

def add_item(item, bucket=[]): bucket.append(item) return bucket print(add_item(1)) # [1] print(add_item(2)) # [1, 2] ← 不是 [2] print(add_item.__defaults__) # ([1, 2],)

原因在 2.2 节已经埋了伏笔：默认值在def语句执行的那一刻求值一次，结果存在__defaults__里，之后每次调用都复用同一个对象。def是模块级语句，只在导入时执行一次，所以那个空列表从头到尾就只有一个。

正确写法是拿None当哨兵：

def add_item(item, bucket=None): if bucket is None: bucket = [] bucket.append(item) return bucket

判断必须用is None而不是== None，也别用if not bucket——空列表传进来会被误判成没传，这属于修了一个坑又挖了一个坑。

同样的道理适用于{}、set()，以及任何自定义的可变对象作为默认值。有一个反直觉的例外：如果默认值是函数调用比如now=datetime.now()，虽然它不是可变的，但同样只在定义时求值一次，想拿"当前时间"的话仍然得在函数体里取。

3.2*args和**kwargs不是万能胶

*args收集多余的位置参数成元组，**kwargs收集多余的关键字参数成字典。它们的正当用途其实很有限，我总结下来主要就两类：

一是透传。装饰器的 wrapper 要接受任意签名，只能写成def wrapper(*args, **kwargs)；子类重写父类方法想原样转发，也用它。

二是接口预留。比如一个插件系统，主流程不知道插件需要什么参数，就统一**kwargs塞过去。但这种设计要谨慎，它把参数检查从编译期推到了运行期，代价是 bug 发现得晚。

反面的用法是"我不知道要传什么，干脆全收着"。这种函数签名对调用方完全不设防，写错了参数名也不会报错，静静地在函数体里变成一个没人用的键。我的建议是：能用显式参数就别用**kwargs，非要用就在函数开头做一次键的校验：

ALLOWED = {"timeout", "retries", "headers"} def request(url, **options): unknown = set(options) - ALLOWED if unknown: raise TypeError(f"unexpected options: {unknown}") ...

3.3 那个孤零零的星号：仅限关键字参数

Python 3 里有个特别好用但用的人不多的语法：参数列表里单独一个*，它后面的参数必须用关键字传。

def resize(image, width, height, *, keep_ratio=False, max_side=None): ...

调用时resize(img, 100, 200, True)会直接报TypeError，必须写resize(img, 100, 200, keep_ratio=True)。

为什么值得用？两个理由。第一，布尔参数在调用处毫无可读性，前面那个True到底代表什么，只有写的人知道。第二，后续加参数不会破坏现有调用。如果keep_ratio是普通位置参数，你以后想在它前面插一个新参数，所有老调用全错位。加个星号，后面就是"只增不改"的扩展区。

我现在的习惯是：必填的数据参数用位置传，所有带默认值的配置项一律放到*后面。这条规则执行下来，调用处的可读性提升非常明显。

3.4 传参本质是对象引用的传递

"Python 是值传递还是引用传递"这个问题吵了很多年，准确的说法是按对象引用传递（call by object reference）：函数收到的是实参对象的引用，形参和实参指向同一块内存，但形参本身是局部变量，重新赋值不会影响外面。

def f1(lst): lst = lst + [1] # 创建新列表并绑定到局部名，外部不变 def f2(lst): lst += [1] # list 的 __iadd__ 原地扩展，外部跟着变 def f3(lst): lst.append(1) # 原地修改，外部跟着变 data = [] f1(data); print(data) # [] f2(data); print(data) # [1] f3(data); print(data) # [1, 1]

关键区别在+=和+。对可变对象，+=调用__iadd__，是原地操作；对不可变对象（int、str、tuple），+=会退化成+，产生新对象。所以def inc(n): n += 1对外部完全没影响，这不是 bug，是语义。

理解了这层，就能解释另一个常见困惑：为什么给函数传一个大列表，函数里只是"读一读"，内存却没降下来。因为传的是引用，原对象一直被调用方的变量持有。想真正释放，得让调用方也断掉引用。

4. 作用域、闭包与延迟绑定：三个高频翻车点

4.1 LEGB 与global/nonlocal的边界

Python 找名字的顺序是 LEGB：Local（当前函数局部）、Enclosing（外层函数）、Global（模块级）、Builtin（内置）。这个顺序本身不复杂，麻烦的是赋值会把名字变成局部的。

count = 0 def bump(): count += 1 # UnboundLocalError bump()

报错的原因是count += 1里有一次赋值，Python 在编译期就把count标记成了局部变量，于是读取它的时候发现还没赋值，直接抛异常。解决办法是加global count，但我不推荐这么写——模块级可变状态在稍大的项目里就是灾难，测试也不好写。

更好的做法是把状态封在闭包里用nonlocal，或者干脆用一个类。nonlocal的作用是声明"这个名字来自外层函数，我要改它"：

def make_counter(): count = 0 def bump(): nonlocal count count += 1 return count return bump c = make_counter() print(c(), c(), c()) # 1 2 3

nonlocal只能指向最近的外层函数作用域，跳不到模块级；而且如果外层根本没有这个变量，会直接报语法错误。这两条限制经常被人忽略。

4.2 闭包保存的是变量而不是值

闭包捕获的是变量本身，也就是一个 cell 对象，不是当时那个值。这意味着如果外层变量后来变了，闭包里读到的也是新值。

def make_funcs(): result = [] for i in range(3): result.append(lambda: i) return result for f in make_funcs(): print(f()) # 2 2 2，不是 0 1 2

三个 lambda 共享同一个i的 cell，循环结束后i是 2，所以全是 2。这是很多人在写回调注册、事件绑定的时候会撞上的问题，而且症状很迷惑：打印出来发现全都一样，但代码逻辑看起来完全正确。

修复方式有两种。一是用默认参数在定义时把值绑死：

result.append(lambda i=i: i)

默认参数在def执行时求值，这里的def是 lambda 的定义时刻，所以每个 lambda 拿到的是当时的i的引用——注意是引用，只不过int不可变，效果上等于拷贝。如果i是个可变对象，这个办法就不保险了。

二是再套一层函数工厂，显式创建一个新的作用域：

def make_one(n): return lambda: n result.append(make_one(i))

我个人更倾向第二种，语义更明确，也不会因为阅读者没注意到默认参数的小技巧而困惑。

4.3 循环里创建函数：为什么结果全都一样

上一节的坑在真实项目里最常见的形式不是 lambda，而是循环里注册回调：

buttons = [] for name in ["save", "cancel", "reset"]: buttons.append({"label": name, "on_click": lambda: print(f"clicked {name}")}) for b in buttons: b["on_click"]() # 全部打印 clicked reset

不管点哪个按钮，行为都是"reset"。这种 bug 在 UI 代码和事件系统里杀伤力很大，因为它不会报错，只是行为不对。

除了上面两种修复，还有一个思路是把循环变量通过参数传进一个立即执行的函数，本质上和make_one是一回事，只是写得更紧凑。不管用哪种，核心都是"让每个函数拥有自己独立的作用域绑定"。

顺带说一句，for循环在 Python 3 里不会创建独立作用域，循环变量在循环结束后仍然存在，值是最后一个。所以[x for x in range(5)]之后x是 4，这点和某些语言不一样，写代码时留意一下。

5. 装饰器：把横切逻辑从函数体里剥出来

5.1 装饰发生的时刻与等价写法

@deco这个语法糖，等价于在函数定义之后立刻执行func = deco(func)。它在模块导入时执行，不是在函数调用时。这一点决定了装饰器里不能放"每次调用都想跑"的逻辑，也解释了为什么装饰器里写print会在导入阶段就打出来。

def trace(func): print(f"decorating {func.__name__}") def wrapper(*args, **kwargs): return func(*args, **kwargs) return wrapper @trace def work(): pass

导入这个模块，你会立刻看到decorating work。如果是带参数的装饰器@retry(times=3)，那retry(times=3)会先被调用并返回真正的装饰器，然后才是func = decorator(func)。这个"先调用、后装饰"的顺序是理解三层结构的关键。

因为这个特性，装饰器里做重活（读配置、连数据库）要小心——模块一导入就跑，测试环境可能直接炸。真要初始化，用惰性方式，等到第一次调用时再建。

5.2functools.wraps省掉的那些麻烦

不加wraps的装饰器会把原函数的元信息全部覆盖掉：__name__变成wrapper，__doc__变成wrapper的文档（通常是 None），inspect.signature拿到的是(*args, **kwargs)。后果是日志里全是wrapper，自动生成的 API 文档一片空白，某些依赖签名做参数校验的框架直接失灵。

import functools def log_calls(func): @functools.wraps(func) def wrapper(*args, **kwargs): print(f"calling {func.__name__}") return func(*args, **kwargs) return wrapper

加这一行的成本几乎为零，收益是避免了后面一连串"为什么我的函数名变了"的排查。wraps还会设置__wrapped__属性指向原函数，inspect.unwrap能顺着它找回去，这对写测试和调试很有用。

有一个细节：wraps复制的是__dict__的浅拷贝，如果你给原函数挂过自定义属性，它们会被带过去。绝大多数情况下这是想要的行为，但如果你在 wrapper 上也挂同名属性，注意赋值顺序。

5.3 带参数装饰器的三层结构怎么读

很多人卡在带参数的装饰器上，其实只要记住"最外层是配置，中间层是装饰，最内层是执行"，结构就很清楚了。以重试装饰器为例：

import time import functools def retry(times=3, delay=0.5, exceptions=(Exception,)): def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): last_exc = None for attempt in range(1, times + 1): try: return func(*args, **kwargs) except exceptions as exc: last_exc = exc if attempt < times: time.sleep(delay) raise last_exc return wrapper return decorator @retry(times=3, delay=0.2) def fetch(url): ...

读的顺序：retry(times=3, delay=0.2)先执行，返回decorator；然后decorator(fetch)执行，返回wrapper；最后fetch这个名字绑到wrapper上。times和delay被闭包捕获，func也是。

写这种装饰器有几个容易忽略的点。一是异常要留着最后再抛，别在循环里直接raise，那样重试就没意义了。二是要区分哪些异常值得重试，网络超时可以重试，参数错误重试一万次也没用，所以我把exceptions做成参数。三是退避策略，固定delay在高并发下会形成同步冲击，真实场景里一般用指数退避，这里为了简洁没展开。

5.4 装饰器叠加顺序与常见误用

多个装饰器叠加时，应用顺序是从下往上，执行顺序是从上往下：

@a @b def f(): ... # 等价于 f = a(b(f)) # 调用 f() 时，先进入 a 的 wrapper，再进入 b 的 wrapper

这个顺序在混用缓存和鉴权时特别重要。比如@cache放在@require_login外面，意味着未登录的请求也会命中缓存，权限检查被绕过——这是个真实存在的安全事故模式。正确的做法是让鉴权在外层。

另一个常见误用是在装饰器里吞异常：

def safe(func): @functools.wraps(func) def wrapper(*args, **kwargs): try: return func(*args, **kwargs) except Exception: return None return wrapper

这个装饰器看起来很"安全"，实际上把所有错误都变成了None，调用方根本不知道出了什么事，最后 bug 在一个完全无关的地方浮现。除非是做最外层的兜底（而且必须记日志），否则别这么写。

6. 生成器函数：yield 到底让函数变成了什么

6.1return与yield的分水岭

函数体里只要出现yield，这个函数就不再是普通函数，而是生成器函数。调用它不会执行任何一行函数体，只是返回一个生成器对象。这一点极其重要，很多人以为yield之前的代码会立即执行，其实不会。

def gen(): print("start") yield 1 print("middle") yield 2 print("end") g = gen() # 什么都不会打印 print(next(g)) # 打印 start，返回 1 print(next(g)) # 打印 middle，返回 2 next(g) # 打印 end，抛 StopIteration

return是"算完了，给你结果，我退出"；yield是"先给你这个，我在这儿停一下，下次接着来"。用生活化的比喻，普通函数像一次性的自动售货机，投币出货结束；生成器像流水线上的工位，产出一个零件就暂停，等下游来取，取完继续。

6.2 生成器的暂停/恢复与状态保存

生成器暂停的时候，它的局部变量、指令位置全都保存在生成器对象内部。这意味着它天然是一个状态机，而且不用你手动维护状态变量。

def running_sum(): total = 0 while True: x = yield total if x is None: continue total += x s = running_sum() next(s) # 预热，返回 0 print(s.send(5)) # 5 print(s.send(3)) # 8

send把值送进生成器，作为yield表达式的返回值。第一次必须先next或send(None)预热，让执行走到第一个yield，否则会报TypeError。这个模式在需要"流式累积"的场景很好用，比如实时统计、协程式的事件处理。

还有一个细节：生成器函数里的return value不会作为返回值传出，而是塞进StopIteration异常的value属性里。想在外部拿到，得捕获异常：

def worker(): yield 1 return "done" g = worker() next(g) try: next(g) except StopIteration as e: print(e.value) # done

这个设计初看别扭，但它是yield from能正确传递返回值的基础。

6.3 大文件流式处理实战

生成器最实用的场景是处理超出内存的数据。假设要统计一个几百 G 的日志文件里各状态码出现的次数，一次性read()直接爆内存，用生成器分块读就很稳：

def read_lines(path, chunk_size=1024 * 1024): buffer = "" with open(path, "r", encoding="utf-8", errors="ignore") as f: while True: chunk = f.read(chunk_size) if not chunk: if buffer: yield buffer break buffer += chunk lines = buffer.split("\n") buffer = lines.pop() for line in lines: yield line def parse_status(lines): for line in lines: parts = line.split() if len(parts) >= 9: yield parts[8] from collections import Counter counter = Counter(parse_status(read_lines("access.log"))) print(counter.most_common(10))

这个管道的好处是每一段都只做一件事，而且全程内存占用基本恒定在chunk_size量级。中间那个buffer是用来处理"一行被切在两个 chunk 中间"的情况，这个细节如果漏了，会出现少量解析失败的行，而且很难复现——只有行正好落在块边界上才出问题。

实测下来，chunk_size选 1MB 左右在大多数磁盘上比较平衡，太小了系统调用次数多，太大了缓存利用率下降。这个值不用太纠结，量级对了就行。

7. 性能与调试：函数层面那些容易被忽略的成本

7.1 调用开销、递归深度与改写思路

Python 的函数调用不算便宜。一次调用要创建帧、压栈、查名字，跟 C 比差着数量级。在热点循环里频繁调用小函数，累积起来是能测出差异的。

但这不代表要把所有小函数都内联掉。我的判断标准是：先测量，再优化。用timeit跑一下，如果单次调用在微秒级而总循环只有几千次，那点开销根本不影响。真正需要关注的是百万级循环里嵌套调用，或者每帧都要跑的游戏循环。

递归是另一个话题。Python 默认递归深度限制是 1000（sys.getrecursionlimit()），超过就抛RecursionError。而且递归的帧开销比迭代大得多，深度稍微上去就容易出问题。我处理递归的一般思路是：

改写递归的时候，显式栈的写法是把"待处理节点"压进列表，循环弹出，把子节点再压进去。这个模式不难，但要注意压栈顺序，否则遍历顺序会和递归版相反。

7.2lru_cache的适用边界与坑

functools.lru_cache是函数层面最实用的优化工具之一，但它的限制条件经常被忽略：

• 参数必须可哈希。传list或dict进去会直接抛TypeError。想缓存这类参数，得先转成tuple或者自己算个 key。
• 缓存不会自动失效。它按参数值缓存，如果函数依赖外部状态（数据库、文件、时间），缓存会返回过期结果。这种情况要么别用，要么手动加版本号参数。
• maxsize=None会无限增长。短期脚本无所谓，长期运行的服务里就是内存泄漏。
• 方法上的缓存会持有self。给实例方法加lru_cache，缓存 key 里包含self，对象就一直被引用着释放不掉。要么用maxsize限制，要么改成在类外部缓存。

from functools import lru_cache @lru_cache(maxsize=512) def parse_config(key: str) -> dict: ...

这个缓存对纯函数是安全的，对 IO 函数就要谨慎。我一般的判断是：函数的输出只由参数决定，才适合加缓存。

7.3 用inspect和dis看清函数内部

调试第三方库或者接手别人的代码时，inspect和dis能省很多时间。

import inspect def build(a, b=1, *args, c, d=2, **kwargs): pass sig = inspect.signature(build) print(sig) for name, param in sig.parameters.items(): print(name, param.kind, param.default)

inspect.signature会把手写的函数签名完整还原出来，param.kind告诉你这是位置参数、仅限关键字、可变位置还是可变关键字。写参数校验、自动生成 API 文档、做依赖注入的时候，这个是核心 API。注意它对内置函数（C 实现的）经常拿不到签名，会抛ValueError，得包一层 try。

dis.dis(func)打印字节码，平时用得不多，但排查"为什么这行代码没执行""为什么这里有性能问题"的时候很管用。比如你想确认某个循环里有没有意外的属性查找，看字节码里的LOAD_ATTR位置就能定位。另外，从 Python 3.11 开始字节码做了大幅优化，如果你在网上看到老的字节码教程，指令可能对不上。

8. 复盘：几个真实场景里的函数写法对比

8.1 三个改写前后的对比

这几个例子都来自实际项目，脱敏之后整理成了对照表。

第一个是参数过多的报表函数：

第二个是异常处理方式：

第三个是循环注册回调：

这三个改动的共同点是：都没有改变功能，只是把"隐式的东西"变成了"显式的"。参数从位置变成名字，失败从None变成异常，绑定从延迟变成即时。函数设计里的大部分问题，本质都是隐式约定太多。

8.2 我现在写函数的几条固定习惯

写到这里，把个人习惯整理一下，可能对刚开始写业务代码的人有点参考价值。

参数超过四个就收成对象，带默认值的放*后面。这条执行下来，调用处的可读性提升最明显。

默认值永远不用可变对象，判断用is None。这是肌肉记忆级别的，写的时候手会自动这么打。

装饰器必加functools.wraps，带参数的装饰器写之前先想清楚三层谁是谁。不想清楚就写，十有八九会漏一层，然后花半小时调试。

函数里不碰模块级可变状态。需要状态就封进闭包或者类里，global能不用就不用，测试的时候会感谢自己。

能抛异常就不返回None。除非真的是"查不到"这种正常业务分支，否则别让调用方猜。

生成器函数只做"产出"，不做"副作用"。一旦生成器里夹带写文件、发请求这种操作，它的惰性执行时机就很难控制了，list(gen)和for x in gen的行为差异能坑死人。

最后分享一个我自己吃过亏的细节：给函数写 docstring 的时候，把参数类型、返回值、可能抛的异常都写上，哪怕没人在用。因为写的过程本身就在逼你想清楚这个函数的边界，很多时候写着写着就发现"这个参数其实不需要""这个返回值设计得不合理"。这比事后 code review 的时候被指出来要划算得多。