如何在函数签名变更时保持向后兼容性（以Path.glob为例）

阿华AIGC实验室

2026-3-31

这种新参数适配旧Python版本的问题我之前维护跨版本库时也碰到过，确实挺闹心的——既要用上新版本的好用特性，又不能让旧版本的用户报错。先聊聊你提到的几种方案的小问题，再给你个我自己常用的更优雅的解决思路。

首先说你提到的几个思路的不足：

版本/属性检查每次调用都跑：确实冗余，虽然单次判断性能影响可以忽略，但代码里每次调用都加个if总觉得不够干净，而且平台是静态的，完全没必要重复判断
捕获TypeError：这种“试错”写法虽然能work，但可读性太差，而且如果未来glob函数因为其他原因抛出TypeError（比如传错了参数类型），会被误当成是参数不存在的情况，容易埋坑
依赖其他属性（比如full_match）：本质和版本检查没区别，还是每次调用都判断，而且依赖的属性和recurse_symlinks的生命周期不一定完全绑定，万一哪天full_match被调整了？虽然概率低，但不够稳妥

最优解：模块加载时一次性适配，之后直接用

核心思路就是把兼容性判断从每次函数调用移到模块加载阶段——模块只会加载一次，所以判断逻辑也只执行一次，完美解决你嫌“每次都检查”的问题，而且代码结构也更清晰。

给你两种具体实现方式，按需选：

方式1：封装专属适配函数

直接在模块开头写好适配逻辑，之后业务代码里直接调用封装后的函数就行：

from pathlib import Path
import sys

# 模块加载时只判断一次，之后全程用这个封装函数
if sys.version_info >= (3, 13):
    def my_glob(path: Path, pattern: str):
        return path.glob(pattern, recurse_symlinks=True)
else:
    def my_glob(path: Path, pattern: str):
        # 旧版本没有recurse_symlinks，这里直接用默认行为（如果需要模拟跟随符号链接，得自己实现递归逻辑，后面会提）
        return path.glob(pattern)

业务代码里调用：

my_path = Path("./my_dir")
for file in my_glob(my_path, "**/*.py"):
    print(file)

方式2：用functools.partial提前绑定参数

如果不想写新函数，用functools.partial提前把参数绑定好，更简洁：

from pathlib import Path
import sys
import functools

# 模块加载时完成适配
if sys.version_info >= (3, 13):
    # 给新版本的glob绑定recurse_symlinks=True参数
    adapted_glob = functools.partial(Path.glob, recurse_symlinks=True)
else:
    # 旧版本直接用原生glob
    adapted_glob = Path.glob

业务代码调用：

my_path = Path("./my_dir")
for file in adapted_glob(my_path, "**/*.py"):
    print(file)

更严谨的判断：直接检查函数签名

如果你不想依赖Python版本号（比如担心未来版本参数变更时间调整），可以直接检查Path.glob的函数签名，看它是否支持recurse_symlinks参数——这个判断也是模块加载时做一次：

from pathlib import Path
import inspect
import functools

# 直接检查目标函数的参数列表
glob_sig = inspect.signature(Path.glob)
supports_recurse_symlinks = "recurse_symlinks" in glob_sig.parameters

if supports_recurse_symlinks:
    adapted_glob = functools.partial(Path.glob, recurse_symlinks=True)
else:
    adapted_glob = Path.glob

这种方式比版本判断更直接，完全和Python版本解绑，只看函数本身的能力，更稳妥。

补充：旧版本需要跟随符号链接怎么办？

如果你的需求是旧版本也必须跟随符号链接递归查找，那旧版本的Path.glob默认不支持，得自己实现递归逻辑，比如：

def my_glob_with_symlinks(path: Path, pattern: str):
    for item in path.iterdir():
        if item.is_symlink():
            # 跟随符号链接，获取真实路径
            real_item = item.resolve()
            if real_item.is_dir():
                # 递归处理子目录，注意要处理循环符号链接的情况
                if real_item != path:
                    yield from my_glob_with_symlinks(real_item, pattern)
            elif real_item.match(pattern):
                yield real_item
        elif item.is_dir():
            yield from my_glob_with_symlinks(item, pattern)
        elif item.match(pattern):
            yield item

把这个函数放到旧版本的分支里就行，注意要加上循环符号链接的判断，避免无限递归。