Rewriting a 20-year-old Python library
Python
API设计
软件工程
开源
背景
akismet库始于2005年，由Michael Foord创建，用于Python的Akismet反垃圾API客户端。作者于2015年接管维护，2024年开始重写。
重写动机
- 支持"blatant"spam特性 - Akismet API返回"blatant"时可直接丢弃内容，但原客户端只返回bool无法暴露此信息
- 异步Python支持 - 异步生态已成熟，需要支持async/non-blocking HTTP请求
类vs函数的取舍
尝试纯函数API后发现：如果一堆函数都需要接受共同的数据参数，说明它们真正需要的是一个类来内部持有这些共享状态。凭证验证需要共享状态，使类成为必然选择。
双类设计
SyncClient和AsyncClient分离：避免自动验证时的同步/异步冲突。用户不想在初始化时阻塞就使用异步验证。
💡 核心洞察:
"花时间思考甚至写样本文档通常能发现这类问题。很多人觉得扔掉文档比扔掉代码容易，但从发现设计问题的角度，文档价值极高。"
"花时间思考甚至写样本文档通常能发现这类问题。很多人觉得扔掉文档比扔掉代码容易，但从发现设计问题的角度，文档价值极高。"
异步初始化方案
- validated_client() - 工厂方法，AsyncClient版本可真正async
- 上下文管理器协议 - async with可为AsyncClient执行异步验证
设计建议
学习Lynn Root的"The Design of Everyday APIs"，了解如何让API更容易使用。