采集基类设计遇到的描述符bug

Python 描述符协议导致的隐式参数绑定 Bug 分析与修复

1. 问题背景

在数据采集项目的基类设计中，提供了一个可扩展的校验钩子 validate_fn，允许子类覆盖以自定义记录校验逻辑。

基类设计（简化版）

class BaseInserter:
validate_fn = None # 子类覆盖为具体校验函数

def _upsert(self, records):
for rec in records:
if self.validate_fn(rec): # 通过实例访问类属性
# 执行入库逻辑
pass

子类覆盖

from src.provinces.anhui.parser import validate_record

class AnhuiInserter(BaseInserter):
validate_fn = validate_record # 覆盖为纯函数

校验函数签名

def validate_record(rec: dict) –> bool:
# 入库前校验: city 和 source_name 不能为空
return bool(rec.get("city")) and bool(rec.get("source_name"))

2. Bug 现象

触发条件

• 使用 –dry-run 时不会调用 _upsert()，bug 被隐藏
• 生产环境（非 dry-run）调用 _upsert() 时触发

错误信息

TypeError: validate_record() takes 1 positional argument but 2 were given

调用栈（示意）

base.py:50 in _upsert()
if self.validate_fn(rec):
^^^^^^^^^^^^^^^^^^^^^
TypeError: validate_record() takes 1 positional argument but 2 were given

3. 根因分析: Python 描述符协议

3.1 什么是描述符

Python 中，函数是一种描述符（Descriptor）。当通过实例访问函数类型的类属性时，描述符协议会自动将该函数**绑定（bind）**到实例上，变成 bound method。

3.2 绑定前后的差异

class Dog:
validate = lambda x, y: y > 0

d = Dog()

# 通过类访问 -> 原始函数，未绑定
print(Dog.validate)
# <function Dog.<lambda> at 0x7f8b8c0d2f70>
# 签名: validate(x, y) -> 需要 2 个参数

# 通过实例访问 -> 绑定方法，自动插入 self
print(d.validate)
# <bound method Dog.<lambda> of <__main__.Dog object at 0x7f8b8c0d5f90>>
# 签名: validate(y) -> 只需要 1 个参数，self 自动传入

3.3 本项目的绑定过程

# 子类定义
class AnhuiInserter(BaseInserter):
validate_fn = validate_record # validate_record(rec) 只有 1 个参数

# 实例化
inserter = AnhuiInserter()

# 通过实例访问
inserter.validate_fn
# Python 描述符协议自动绑定
# validate_record.__get__(inserter, AnhuiInserter)
# 返回 bound method
# <bound method validate_record of <AnhuiInserter object>>

# 实际调用
inserter.validate_fn(rec)
# 等价于 validate_record(inserter, rec)
# 但 validate_record 只接受 1 个参数 -> TypeError

3.4 图示

+———————————————————+
| 类属性 validate_fn = validate_record(rec) |
| （纯函数，1 个参数） |
+———————————————————+
|
v 通过 self.validate_fn 访问
+———————————————————+
| Python 描述符协议介入 |
| validate_record.__get__(self, type(self)) |
| -> 返回 bound method: validate_record(self, rec) |
| （隐式插入 self，变成 2 个参数） |
+———————————————————+
|
v 调用时
+———————————————————+
| self.validate_fn(rec) |
| 实际执行: validate_record(inserter_instance, rec) |
| 期望参数: 1 个 (rec) |
| 实际传入: 2 个 (inserter_instance, rec) |
| -> TypeError: takes 1 positional argument but 2 given |
+———————————————————+

4. 为什么 –dry-run 没发现

# pipeline.py
if dry_run:
logger.info(" %d 条 (dry-run，未入库)", len(records))
all_records.extend(records)
else:
ins, upd, sk = _upsert_records(records) # 只有这里触发 _upsert()

教训: dry-run 只能验证"解析链路"，无法覆盖"入库链路"，基类设计缺陷需要单独测试。

5. 修复方案

5.1 修复思路

绕过描述符协议，直接获取未经绑定的原始函数对象。

5.2 修复代码

# base.py 第 50-51 行

# 修复前（有 bug）
if self.validate_fn(rec):
# self.validate_fn -> bound method，多传 self

# 修复后
raw_fn = type(self).__dict__.get("validate_fn")
if raw_fn and raw_fn(rec):
# type(self).__dict__ 直接取类字典中的原始函数
# 不经过描述符协议，不会绑定，参数正确

5.3 修复原理

type(self) # 获取实际类（AnhuiInserter）
.__dict__ # 获取类的属性字典（未经继承链解析）
.get("validate_fn") # 直接取出原始函数对象

# 这种方式绕过了 Python 的属性查找机制（包括描述符协议）
# 拿到的是 "裸函数"，不会自动绑定 self

5.4 对比验证

class Base:
validate_fn = None

class Child(Base):
validate_fn = lambda rec: rec > 0

obj = Child()

# 方式 1: 有 bug（描述符绑定）
print(obj.validate_fn) # <bound method …>
# obj.validate_fn({"city": "合肥"}) # TypeError!

# 方式 2: 修复后（原始函数）
raw = type(obj).__dict__.get("validate_fn")
print(raw) # <function …>
raw({"city": "合肥"}) # 正常执行

6. 替代方案（其他修复思路）

方案 A: 使用 staticmethod（推荐用于新设计）

class AnhuiInserter(BaseInserter):
@staticmethod
def validate_fn(rec): # 静态方法不会被绑定
return bool(rec.get("city")) and bool(rec.get("source_name"))

优点: 语义清晰，符合 Python 惯例 缺点: 需要修改所有子类，无法直接赋值模块级函数

方案 B: 实例属性赋值

class AnhuiInserter(BaseInserter):
def __init__(self):
self.validate_fn = validate_record # 实例属性不会触发描述符

优点: 简单直接 缺点: 每个实例都持有函数引用，略浪费内存

方案 C: 显式传入函数（最 Pythonic）

def _upsert(self, records, validate_fn=None):
validator = validate_fn or self.validate_fn
for rec in records:
if validator(rec): # 局部变量，不触发描述符
pass

优点: 灵活，测试友好 缺点: 需要修改基类接口

7. 经验总结

7.1 核心教训

7.2 防御性编程建议

# 1. 需要原始函数时，优先使用类直接访问
if ClassName.validate_fn(rec): # 明确、无绑定

# 2. 或者显式解绑定
import inspect
fn = inspect.unwrap(self.validate_fn.__func__) # 获取原始函数

# 3. 设计基类钩子时，文档注明陷阱
class BaseInserter:
#
# validate_fn: 校验函数，注意通过 type(self).__dict__ 访问以避免绑定
#
validate_fn = None

7.3 一句话总结

“类属性挂函数，实例访问要小心——Python 会自动给你塞个 self，而你未必想要。”

8. 相关知识点扩展