跳转到主要内容

Python

15 面向对象进阶

继承/super/魔术方法/ABC/dataclass,看懂自定义存储类

  • Python
  • 进阶

目标:把入门课的「最小类」升级成真实代码里的类——讲透继承与 super() 背后的属性查找机制、魔术方法如何把自家的类接进 Python 语法、@property/@classmethod/@dataclass 这些框架代码的标配件;学完能读懂并写出 class JSONChatHistory(BaseChatMessageHistory) 这类框架惯用法。 与 LangChain 的关系:LangChain 的扩展点几乎全是「继承基类 + 实现约定方法」——自定义存储、自定义工具、自定义解析器,全是本章机制。

1. 为什么需要:入门课的类,和框架里的类差着一整层

第 9 章学的类是「最小类」:__init__ 存属性、def 几个方法,到头了。看一段真实代码(摘编自 013-Memory:实现自定义 Memory 存储.md,逐行解读在第 11 节):

class JSONChatHistory(BaseChatMessageHistory):   # ← 括号里的类是什么?为什么写这?
    def __init__(self, dir: str, session_id: str) -> None:
        self.dir = dir
        self.session_id = session_id

    @property                                     # ← 方法名不加括号就能用?
    def messages(self) -> list[BaseMessage]:
        ...

    def add_message(self, message: BaseMessage) -> None:  # ← 谁规定必须有这方法?
        ...

三行看不懂的东西,背后是入门课没讲的六件事:继承((BaseChatMessageHistory))、抽象类(谁规定必须实现 messages/clear)、@property、魔术方法(print(history) 为什么能显示有意义的内容)、@dataclass、from_xxx 构造器。真实框架代码几乎没有一个「裸类」——本章按机制逐个补齐。

2. 继承与 super():属性查找的接力

2.1 机制:点号沿「查找链」走

obj.name 的完整查找顺序:实例自己的属性字典 → 本类的属性字典 → 父类的属性字典(按一条确定的链),全都没有才报 AttributeError。继承就是让你的类接上别人的查找链——父类的东西,子类直接白拿。子类里定义同名方法会先被找到,等于拦下了父类的版本,这叫重写(override):

class Message:
    def __init__(self, content: str):
        self.content = content

    def role(self) -> str:
        return "unknown"

    def preview(self) -> str:
        return f"[{self.role()}] {self.content}"    # 这里的 self.role() 运行时才查找


class HumanMessage(Message):
    def role(self) -> str:                           # 重写:拦截父类版本
        return "human"


for m in [HumanMessage("你好"), HumanMessage("在吗")]:
    print(m.preview())
# → [human] 你好
# → [human] 在吗

关键机制:preview 定义在父类,但它调用的 self.role() 是运行时到实例的真实类上去找——实例是 HumanMessage,所以拿到重写版。「父类的代码反过来调用子类的实现」是所有框架扩展点的原理(第 11 节会再次出现)。

2.2 子类扩展 __init__:super() 的正确姿势

子类一旦定义 __init__,会整体顶掉父类的 __init__(同名重写),父类的属性初始化不再自动执行。正确姿势是两步:先 super().__init__(...) 让父类干它该干的,再干自己特有的:

class AIMessage(Message):
    def __init__(self, content: str, model: str):
        super().__init__(content)    # 第 1 步:父类负责的属性交给父类
        self.model = model           # 第 2 步:自己特有的自己来


ai = AIMessage("你好", "gpt-4o-mini")
print(ai.content, ai.model)          # → 你好 gpt-4o-mini

2.3 super() 到底做什么:不是「父类」,是「查找链的下一个」

每个类都有一条 MRO(Method Resolution Order,方法解析顺序)——Python 把这个类和所有祖先排成的一条线性链。super() 的准确含义:沿 MRO 找当前类的下一个。单继承时恰好是父类,多继承时未必:

print([c.__name__ for c in HumanMessage.__mro__])
# → ['HumanMessage', 'Message', 'object']   万类终点的 object 也在链上

class A:
    def __init__(self):
        print("A.__init__")
        super().__init__()           # 接力棒传给 MRO 的下一个(object)

class B(A):
    def __init__(self):
        print("B.__init__")
        super().__init__()

class C(B):
    def __init__(self):
        print("C.__init__")
        super().__init__()


C()                                  # 多级继承链:每一级都只写 super(),链自动接力
# → C.__init__
# → B.__init__
# → A.__init__

为什么不写死 Message.__init__(self, ...)?两个理由:父类改名要改两处;多继承时写死父类名会让接力链断掉(每级只认自己的直接父类,super() 却按 MRO 全局顺序走)。多继承本章不展开,只要记住结论:统一用 super(),别写死父类名。

3. 多态与鸭子类型:关心行为,不关心出身

3.1 多态:同一个调用,各自的表现

class EmailChannel:
    def send(self, text: str) -> None:
        print(f"邮件:{text}")

class WebhookChannel:
    def send(self, text: str) -> None:
        print(f"Webhook:{text}")

def notify(channel) -> None:          # 只要求:有 send 方法
    channel.send("部署完成")

for ch in [EmailChannel(), WebhookChannel()]:
    notify(ch)
# → 邮件:部署完成
# → Webhook:部署完成

notify 的参数没写「必须是某个类」——Python 从不检查出身,只在乎点出来的是什么。这就是鸭子类型:「走起来像鸭子、叫起来像鸭子,那它就是鸭子」。多态不用学新语法,它就是第 2.1 节的动态查找自然长出的能力。

3.2 你早已在用鸭子类型

len(x) 接受一切有 __len__ 的对象;json.dumps 接受一切可序列化的对象;open() 返回的文件对象和 io.StringIO() 没有任何继承关系,却都能 .read()。Python 标准库的接口几乎全按「行为」定义。

3.3 typing.Protocol:把鸭子类型写进注解

第 13 章的类型注解默认按「出身」检查(是不是那个类/它的子类)。Protocol 改为按「结构」检查:只要长得一样(有那些方法),就算实现了协议,不需要继承:

from typing import Protocol

class Sendable(Protocol):
    def send(self, text: str) -> None: ...

def notify(channel: Sendable) -> None:   # 注解承诺:任何有 send 方法的对象都行
    channel.send("部署完成")

notify(EmailChannel())                   # EmailChannel 没继承 Sendable,结构匹配即通过

协议 = 把鸭子类型从「口头约定」升级成「机器(类型检查器)可验证的合同」。LangChain 里「Runnable = 一切能 invoke 的对象」正是这套思想(22-读懂LangChain:语法桥)。

4. 抽象类 ABC:把「必须实现」写成合同

普通继承的约定只写在文档里:父类放个空方法,子类忘了重写不报错,直到运行到那行才发现——错误暴露得太晚。abc.ABC + @abstractmethod 把约定变成硬合同:

from abc import ABC, abstractmethod

class Notifier(ABC):
    @abstractmethod
    def send(self, text: str) -> None:
        """子类必须实现"""

    def notify_all(self, texts: list[str]) -> None:   # 普通方法照常有实现
        for t in texts:
            self.send(t)                              # 调子类的 send(2.1 的机制)

class EmailNotifier(Notifier):
    def send(self, text: str) -> None:
        print(f"邮件:{text}")

EmailNotifier().notify_all(["a", "b"])   # 正常:send 已补齐
# Notifier()                             # ❌ 直接实例化抽象类
TypeError: Can't instantiate abstract class Notifier without an implementation for abstract method 'send'

(3.11 及以前措辞略有不同,with abstract method 'send',意思一致。)机制:继承 ABC 后,被 @abstractmethod 标记的方法名登记进类身上的 __abstractmethods__ 集合;只要它非空,实例化就被拦截。和普通继承的区别:

普通继承抽象类 ABC
子类忘了实现约定方法静默继承父类的(可能是空壳)实例化直接 TypeError
错误暴露时机调用方法时(可能已上线)造对象那一刻
父类能有带实现的方法吗能能(ABC ≠ 纯接口,是「合同 + 工具箱」)
典型用途复用实现定义契约 / 框架扩展点

@abstractmethod 还能和 @property 叠加,要求子类提供某属性——LangChain 的 BaseMemory.memory_variables 就是这么写的(@property 在上、@abstractmethod 在下)。

5. 魔术方法:把自家的类接进 Python 的语法

[]、len()、print、==、for 这些语法不认识你的类——它们只是去对象身上找固定名字的方法(前后各两个下划线,昵称 dunder)。内置类型没有特权:len([1,2]) 同样是查 list.__len__。定义了对应的魔术方法,你的对象就「接入」了这门语言的语法。

5.1 __repr__ 与 __str__:两个打印面孔

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

p = Point(1, 2)
print(p)              # 没定义时:→ <__main__.Point object at 0x100c43380>,看不出任何信息

class Point:
    def __init__(self, x, y):
        self.x, self.y = x, y

    def __repr__(self):                 # 面向开发者:调试、日志、容器里显示
        return f"Point({self.x}, {self.y})"

    def __str__(self):                  # 面向用户:print() / str() 用
        return f"({self.x}, {self.y})"

p = Point(1, 2)
print(p)               # → (1, 2)
print([p, p])          # → [Point(1, 2), Point(1, 2)]   容器里的元素只用 __repr__
__repr____str__
给谁看开发者(调试、日志)用户(print、str)
目标无歧义,最好能照着重建对象可读
没定义时的兜底显示 <类名 object at 0x...>退回 __repr__
元素在列表/字典里 print用它不用

实用建议:只写 __repr__ 一个就够(print 会自动退回它);需要「面向用户换一副面孔」时再补 __str__。

5.2 __eq__:让 == 按值比较

默认 == 比身份(同一个对象才相等,等价于 is 的效果)。定义 __eq__ 后按内容比:

class Money:
    def __init__(self, yuan: int):
        self.yuan = yuan

    def __repr__(self):
        return f"Money({self.yuan})"

    def __eq__(self, other):
        if not isinstance(other, Money):
            return NotImplemented       # 不认识对方类型,交还给 Python 判定
        return self.yuan == other.yuan

print(Money(5) == Money(5))             # → True
print(Money(5) in [Money(3), Money(5)]) # → True,in 内部也走 __eq__

注意:手写 __eq__ 会顺带把对象变得不可哈希(不能进 set、当字典键),要恢复需再定义 __hash__——@dataclass 会替你处理(第 8 节)。

5.3 __len__ 与 __getitem__:让对象支持 len()、[] 和 for

class Playlist:
    def __init__(self, name: str):
        self.name = name
        self._songs: list[str] = []

    def add(self, song: str) -> None:
        self._songs.append(song)

    def __len__(self):
        return len(self._songs)

    def __getitem__(self, index):
        return self._songs[index]       # 转交给 list:负索引、切片全白送

pl = Playlist("夜跑")
pl.add("we don't talk anymore")
pl.add("photograph")

print(len(pl))          # → 2
print(pl[0])            # → we don't talk anymore
print(pl[-1])           # → photograph
for song in pl:         # for 也能用了!
    print("播放:", song)

for 的机制:Python 先找 __iter__(16-迭代器与生成器 细讲);找不到就退回最古老的协议——用 __getitem__ 从 0 开始取 0、1、2……直到抛 IndexError 停止。所以只实现 __getitem__,对象就能被 for 遍历。

5.4 __call__:让实例像函数一样可调用

class Multiplier:
    def __init__(self, factor: float):
        self.factor = factor

    def __call__(self, x: float) -> float:
        return x * self.factor

double = Multiplier(2)
print(double(21))       # → 42,实例名后直接跟括号

机制:obj(...) 会调用 type(obj).__call__。价值在于「带配置的可调用对象」:比函数多记了状态(factor 出厂时定格),又能出现在任何函数能出现的位置。真实代码高频场景:用类写的装饰器(第 14 章用闭包写,带状态时常用 __call__ 类写)、框架里「像函数一样传进流水线」的对象(LCEL 的 Runnable 全都实现了 invoke,道理同源)。

语法触发的魔术方法
obj[idx] / obj[a:b]__getitem__
len(obj)__len__
obj(...)__call__
print(obj) / str(obj)__str__ → 兜底 __repr__
a == b__eq__
for x in obj__iter__,兜底 __getitem__(16 章)
with obj:__enter__ / __exit__(19 章)

6. @property:把方法伪装成属性

6.1 机制与动机

圆的面积是「算出来的」,但用起来希望像属性:c.area 而不是 c.area()。@property 把方法注册成一个「访问时自动执行的属性」——读 obj.attr 时,Python 先看类里有没有叫 attr 的 property 对象,有就调用它的 getter 返回结果,调用方完全无感:

class Circle:
    def __init__(self, radius: float):
        self.radius = radius

    @property
    def area(self) -> float:
        return 3.14159 * self.radius ** 2

c = Circle(2)
print(c.area)           # → 12.56636,注意没有括号

6.2 只读属性:只给 getter

# c.area = 100          # ❌ 没有 setter 的 property 只读
AttributeError: property 'area' of 'Circle' object has no setter

6.3 setter:给赋值加校验

class Account:
    def __init__(self, balance: float = 0):
        self.balance = balance          # 这行赋值也走 setter,构造时就带校验

    @property
    def balance(self) -> float:
        return self._balance

    @balance.setter
    def balance(self, value: float) -> None:
        if value < 0:
            raise ValueError(f"余额不能为负:{value}")
        self._balance = value           # 真正的值存进 _balance(下划线=内部约定)

acc = Account(100)
acc.balance = 150                       # 赋值被拦截 → 先校验再存
print(acc.balance)                      # → 150
# acc.balance = -1                      # ❌ ValueError: 余额不能为负:-1

6.4 为什么说 @property 是「后悔药」

假如 balance 一开始做成普通属性,某天要加「不能为负」的规则:裸属性没法加逻辑;改成方法 balance() 又得改所有调用方(acc.balance → acc.balance())。@property 让你先当普通属性用,之后随时补逻辑,用法始终不变——很多库里「看起来是属性」的东西其实都是它。选用原则:计算廉价、无副作用 → property;动作昂贵或有副作用(发请求、写文件)→ 老实写成方法,括号本身就是提醒。

7. @classmethod 与 @staticmethod:不接 self 的两个装饰器

7.1 @classmethod:第一个参数是类本身

普通方法第一个参数 self(实例);classmethod 是 cls(类)。头号用途是替代构造器 from_xxx——从别的数据形态造实例:

class Date:
    def __init__(self, year: int, month: int, day: int):
        self.year, self.month, self.day = year, month, day

    @classmethod
    def from_string(cls, text: str) -> "Date":
        year, month, day = (int(p) for p in text.split("-"))
        return cls(year, month, day)    # 用 cls 造,而不是写死 Date

print(Date.from_string("2026-10-04").year)   # → 2026,调用走类,不需要先有实例

两个细节:调用形式是 Date.from_string(...)(不经过实例);体内用 cls(...) 造对象——将来子类调用 ChineseDate.from_string(...),造出来的自动是 ChineseDate。标准库同款惯用法:datetime.fromtimestamp()、dict.fromkeys();pydantic 的 model_validate 也是 classmethod(21-pydantic数据建模)。

7.2 @staticmethod:既不要 self 也不要 cls

就是搬进类命名空间的普通函数,通常放和这个类强相关的小工具:

class Date:
    def __init__(self, year: int, month: int, day: int):
        self.year, self.month, self.day = year, month, day

    @staticmethod
    def is_leap(year: int) -> bool:
        return year % 4 == 0 and (year % 100 != 0 or year % 400 == 0)

print(Date.is_leap(2024))   # → True

7.3 对比与选用

普通方法@classmethod@staticmethod
第一个参数self(实例)cls(类)无
访问实例属性能不能不能
不先造实例就能调不能能能
子类友好(自动拿到子类)—能(cls 是调用者)不能(无 cls)
典型用途操作单个对象from_xxx 构造器、工厂类相关的纯函数工具

口诀:要用 self → 普通方法;要造本类的对象 → classmethod;都不要 → staticmethod(或者干脆移出去当模块级函数)。

8. @dataclass:把重复劳动交给机器

8.1 手写三大件 vs 一行装饰器

「主要用来存数据」的类,手写 __init__、__repr__、__eq__ 三大件既重复又无聊:

class Point:
    def __init__(self, x: int, y: int):
        self.x = x
        self.y = y

    def __repr__(self):
        return f"Point(x={self.x}, y={self.y})"

    def __eq__(self, other):
        if not isinstance(other, Point):
            return NotImplemented
        return (self.x, self.y) == (other.x, other.y)

16 行换成 4 行,行为完全一致:

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

print(Point(1, 2))           # → Point(x=1, y=2)        自动 __repr__
print(Point(1, 2) == Point(1, 2))   # → True            自动 __eq__

机制:@dataclass 读取类身上的类型注解(第 13 章),把每个带注解的名字当作一个字段,自动生成三大件。注意注解在这里不是注释——它是 dataclass 的原料,没写注解的名字不参与生成。

8.2 生成清单与常用参数

写法得到什么
@dataclass(默认)__init__、__repr__、__eq__
order=True再加 < <= > >=(按字段逐个比,可排序)
frozen=True不可修改 + 可哈希(能进 set、当字典键)
field(...)单个字段的精细配置(默认值工厂、是否参与比较……)

8.3 可变默认值:field(default_factory=...)

from dataclasses import dataclass, field

@dataclass
class TaggedDoc:
    text: str
    score: float = 0.0                          # 不可变默认值直接写
    tags: list[str] = field(default_factory=list)   # 可变默认值必须走工厂

doc1, doc2 = TaggedDoc("a"), TaggedDoc("a")
doc1.tags.append("重要")
print(doc2.tags)        # → [],doc2 的 tags 独立

为什么不能写 tags: list[str] = []?dataclass 直接拒绝:

ValueError: mutable default <class 'list'> for field tags is not allowed: use default_factory

原因同第 10 节的「可变类属性共享」:默认值只有一份。default_factory=list 表示「每次实例化时现场调用 list() 造一个新的」。

8.4 frozen=True:不可变数据

@dataclass(frozen=True)
class Config:
    api_key: str
    timeout: float = 30.0

cfg = Config(api_key="sk-xxx")
# cfg.timeout = 10     # ❌
dataclasses.FrozenInstanceError: cannot assign to field 'timeout'

不可变 + 自动可哈希:能放心当字典键、放进 set、在多处传引用不怕被谁改坏。配置项、消息这类「一旦生成就不该变」的数据首选 frozen。

8.5 asdict:对象转字典,对接序列化

from dataclasses import asdict

print(asdict(TaggedDoc("hello", 9.5, ["a"])))
# → {'text': 'hello', 'score': 9.5, 'tags': ['a']}

嵌套的 dataclass 会递归转换,是「对象 ↔ JSON」的桥(第 11 节 LangChain 的 messages_to_dict 干的就是同类事)。dataclass 与 pydantic 的分工见 21-pydantic数据建模:dataclass 在标准库里、足够轻;pydantic 自带校验并能与 LangChain 无缝集成。

9. 组合还是继承?

继承的隐藏成本:子类能看到并依赖父类的实现细节(白盒复用),父类内部一改,子类跟着坏。另一条路是组合:把别的对象装进来当属性,调用它的公开方法(黑盒,只依赖接口):

class JSONChatHistory(BaseChatMessageHistory):   # 继承:是为了兑现框架合同
    def __init__(self, dir: str, session_id: str):
        self.dir = dir
        self.file_path = Path(dir) / f"{session_id}.json"   # 组合:把 Path 装进来用

JSONChatHistory 若写成 class JSONChatHistory(Path) 就荒谬了——它不是「一种路径」,只是「用到了路径」。判断标准,命中任何一条就别用继承:

  1. 说不出口「B 是一种 A」(is-a)——那多半只是「B 里有一个 A」(has-a)。
  2. 只想复用 A 的代码,但从不打算把 B 当 A 用(不会把 B 传给「接收 A」的函数)。
  3. 写 B 之前必须看懂 A 的内部实现——耦合过深的信号。
继承组合纯函数
关系is-a(是一种)has-a(有一个)无
复用什么实现细节(白盒)公开接口(黑盒)函数本身
耦合度紧:父类内部改动波及子类松:只依赖对方接口最松
适合真实分类关系、框架扩展点拼装能力、委托行为纯计算、数据进出
LangChain 对应自定义存储继承 BaseChatMessageHistoryChain 里组装 llm + promptRunnableLambda 包的函数

框架扩展点(第 11 节)是继承最正当的用法:基类就是为被继承设计的(第 4 节 notify_all 调 self.send 的模板法)。

10. 常见坑

  • 可变类属性被所有实例共享:写在类身上(不在 __init__ 里)的属性叫类属性,全类只有一份:
class TaggedDoc:
    tags: list = []            # ❌ 可变对象挂在类身上

doc1, doc2 = TaggedDoc(), TaggedDoc()
doc1.tags.append("重要")
print(doc2.tags)               # → ['重要'],doc2 被污染!

机制回看 2.1 节:doc2.tags 在实例身上找不到 → 沿查找链找到类身上的同一个列表,改的就是大家共用的那份。修法:可变值放进 __init__(self.tags = [])或 dataclass 的 default_factory(8.3)。数字、字符串、None、tuple 这类不可变默认值没有此坑。

  • 子类 __init__ 忘调 super().__init__():父类负责的属性根本没被初始化,用的时候才炸:
class Cat(Message):
    def __init__(self):        # ❌ 忘了 super().__init__(content)
        self.extra = "meow"

# Cat().content
# AttributeError: 'Cat' object has no attribute 'content'

修法:__init__ 第一行 super().__init__(...)(2.2 节)。

  • 在 __init__ 外随手新增属性:Python 允许任何时候 obj.anything = ...,于是 self.nmae = ... 这种拼错不报错、静默生成新属性,bug 藏得很深。想收紧:__slots__ = ("content", "model") 一句话声明「只允许这些属性」,再新增直接 AttributeError(顺带省内存);dataclass 加 slots=True 同理。

11. 在 LangChain 里的样子:自定义存储 = 继承 + 实现约定接口

场景:把对话历史存进自家基建(本地 JSON 文件)。LangChain 不可能预置所有存储后端,于是把「存储」抽象成一个基类,把「具体怎么存」留给你。先看基类骨架(摘编自 langchain-core 0.3 源码 langchain_core/chat_history.py,注释有简化):

from abc import ABC, abstractmethod

class BaseChatMessageHistory(ABC):
    messages: list[BaseMessage]       # 类上的注解 = 约定:子类要提供 messages

    def add_user_message(self, message): ...   # 便捷方法,带默认实现
    def add_ai_message(self, message): ...
    def add_message(self, message): ...        # 默认实现转调 add_messages
    def add_messages(self, messages): ...      # 默认实现逐条转调 add_message

    @abstractmethod
    def clear(self) -> None:          # 唯一的「硬合同」
        ...

第 4 节知识的直接印证:只有 clear 挂了 @abstractmethod(不实现就无法实例化);messages 只是类上的一条注解(第 13 章:注解不创建属性,运行时不强制),靠约定要求子类用 @property 或实例属性提供;其余 add_xxx 都尽量给了默认实现(子类都没实现 add_message/add_messages 时调用会得到 NotImplementedError——比 TypeError 温和的「软约定」)。抽象类是半合同、半工具箱。

用户侧的完整实现(摘编自 013-Memory:实现自定义 Memory 存储.md,逐行解读见下):

import json
from pathlib import Path
from typing import Sequence

from langchain_core.chat_history import BaseChatMessageHistory
from langchain_core.messages import BaseMessage, messages_from_dict, messages_to_dict


class JSONChatHistory(BaseChatMessageHistory):
    def __init__(self, dir: str, session_id: str) -> None:
        self.dir = dir                   # 存储目录
        self.session_id = session_id     # 一个会话一个文件

    @property
    def file_path(self) -> Path:         # 派生值:目录 + 会话 id → 文件路径
        return Path(self.dir) / f"{self.session_id}.json"

    @property
    def messages(self) -> list[BaseMessage]:   # 兑现基类约定:用时才读文件
        try:
            if not self.file_path.exists():
                self.save_messages_to_file([])
                return []
            data = json.loads(self.file_path.read_text(encoding="utf-8"))
            return messages_from_dict(data)
        except Exception as error:
            print(f"Failed to read chat history from {self.file_path}", error)
            return []

    def add_message(self, message: BaseMessage) -> None:
        messages = self.messages         # 读旧 → 追加 → 写回
        messages.append(message)
        self.save_messages_to_file(messages)

    def add_messages(self, messages: Sequence[BaseMessage]) -> None:
        self.save_messages_to_file(self.messages + list(messages))   # 批量一次写盘

    def clear(self) -> None:             # 兑现唯一的抽象方法:删文件即清空
        self.file_path.unlink()

    def save_messages_to_file(self, messages: Sequence[BaseMessage]) -> None:
        serialized = messages_to_dict(messages)     # 消息对象 → 带 type 的字典
        self.file_path.write_text(
            json.dumps(serialized, ensure_ascii=False, indent=2),
            encoding="utf-8",
        )

逐行对照本章机制:

  • class JSONChatHistory(BaseChatMessageHistory):2.1 节继承——接上查找链,基类 add_user_message 等默认实现白拿;4.1 节——clear 是硬合同,不写就无法实例化。
  • __init__ 只存配置(dir、session_id),不读文件不缓存——每次现读现写,「文件即唯一真相」。
  • @property file_path:6.1 节——算出来的派生值,所以用属性形态:history.file_path,不加括号。
  • @property messages:兑现基类的约定接口(基类注释原话就写着 “A property or attribute…”)。做成 property 的深意:读文件是要做 IO 的动作,但对外接口仍像一个无害的属性。读取失败的兜底是返回 []——宁可丢掉历史也不让整条链崩掉。
  • add_message / add_messages:典型的「读—改—写」;批量版只写一次盘,比基类默认的逐条转调高效。
  • save_messages_to_file:下划线开头 = 内部方法(第 9 章的约定);messages_to_dict / messages_from_dict 是 LangChain 自带的序列化工具(8.5 节 asdict 的「框架版」)——存成带 type 字段的字典,读回时按 type 还原成 HumanMessage / AIMessage 真对象。

接入现有体系——ConversationBufferMemory 从不检查 history 的出身,只调用它的 add_messages / messages / clear(3.2 节鸭子类型;这里 ABC 把口头约定升级成了合同):

history = JSONChatHistory(dir="chat_data", session_id="test")
history.add_messages([HumanMessage("Hi, 我叫小明"), AIMessage("你好")])
print(history.messages)
# → [HumanMessage(content='Hi, 我叫小明', ...), AIMessage(content='你好', ...)]

memory = ConversationBufferMemory(chat_memory=history)   # 自定义存储接入官方 memory

版本注记:ConversationBufferMemory 是 LangChain 0.x 的旧 API(1.x 已废弃),这里取它「只认约定接口、不问出身」的教学价值——BaseChatMessageHistory 基类和「继承 + 实现约定」的套路本身依然成立。1.x 的记忆体系(checkpointer + middleware)见仓库 docs/ 的 14-记忆系统。

一句话总结:自定义存储 = 继承基类 + 实现约定接口。同一套机制推而广之——自定义 OutputParser、自定义 DocumentLoader、pydantic 自定义类型,全是「继承 + 实现约定」。系统对照见 22-读懂LangChain:语法桥。

小练习

  1. 继承与重写:写 Employee 基类(__init__ 存 name、salary,方法 monthly_cost() 返回 salary);子类 Manager 扩展 __init__ 增加 bonus(记得 super()),并重写 monthly_cost() 返回 salary + bonus。验证 Manager("Ann", 20000, 3000).monthly_cost() 为 23000。
  2. 抽象类与多态:写 Shape(ABC),area() 挂 @abstractmethod;实现 Circle(radius) 和 Rect(w, h);写 total_area(shapes) 对混合列表求和;再试 Shape(),观察报错。
  3. 魔术方法:写 Sentence 类(__init__ 接收整句,内部按空格拆成单词列表),实现 __len__(单词数)、__getitem__(第 i 个单词)、__repr__(Sentence('...') 形式)。验证 len、[0]、for、print 都能用。
  4. dataclass + classmethod:写 @dataclass(frozen=True) 的 Version(major、minor、patch 三个 int),加 classmethod from_string("1.4.2");验证相等比较、字典键用法(可哈希),以及直接赋值会报什么错。
练习答案
# 练习 1
class Employee:
    def __init__(self, name: str, salary: float):
        self.name = name
        self.salary = salary

    def monthly_cost(self) -> float:
        return self.salary

class Manager(Employee):
    def __init__(self, name: str, salary: float, bonus: float):
        super().__init__(name, salary)      # 父类负责的先交出去
        self.bonus = bonus

    def monthly_cost(self) -> float:        # 重写
        return super().monthly_cost() + self.bonus   # 也可以站在父类肩膀上改

print(Manager("Ann", 20000, 3000).monthly_cost())   # → 23000.0

# 练习 2
from abc import ABC, abstractmethod

class Shape(ABC):
    @abstractmethod
    def area(self) -> float: ...

class Circle(Shape):
    def __init__(self, radius: float):
        self.radius = radius

    def area(self) -> float:
        return 3.14159 * self.radius ** 2

class Rect(Shape):
    def __init__(self, w: float, h: float):
        self.w, self.h = w, h

    def area(self) -> float:
        return self.w * self.h

def total_area(shapes: list) -> float:
    return sum(s.area() for s in shapes)    # 多态:只认 area(),不认出身

print(total_area([Circle(1), Rect(2, 3)]))  # → 9.14159
# Shape() → TypeError: Can't instantiate abstract class Shape
#           without an implementation for abstract method 'area'

# 练习 3
class Sentence:
    def __init__(self, text: str):
        self.words = text.split()

    def __len__(self):
        return len(self.words)

    def __getitem__(self, index):
        return self.words[index]

    def __repr__(self):
        return f"Sentence('{' '.join(self.words)}')"

s = Sentence("python 面向对象 进阶")
print(len(s))      # → 3
print(s[0])        # → python
print([w for w in s])              # for 遍历:['__getitem__ 兜底协议']
print(s)           # → Sentence('python 面向对象 进阶')

# 练习 4
from dataclasses import dataclass

@dataclass(frozen=True)
class Version:
    major: int
    minor: int
    patch: int

    @classmethod
    def from_string(cls, text: str) -> "Version":
        major, minor, patch = (int(p) for p in text.split("."))
        return cls(major, minor, patch)

v = Version.from_string("1.4.2")
print(v == Version(1, 4, 2))       # → True,自动 __eq__
print({v: "stable"})               # → {Version(major=1, minor=4, patch=2): 'stable'}
# v.patch = 3 → dataclasses.FrozenInstanceError: cannot assign to field 'patch'