https://plumephp.com/tags/%E8%AF%AD%E4%B9%89%E5%8C%96%E7%89%88%E6%9C%AC/Recent content in 语义化版本 on PlumePHPHugozh-CNMon, 28 Sep 2026 13:00:00 +0800https://plumephp.com/python-api-library-design/Mon, 28 Sep 2026 13:00:00 +0800https://plumephp.com/python-api-library-design/<blockquote> <p>写一个「能跑」的脚本容易，写一个「好用」的库难。本文从 Python 库作者视角，拆解公开 API 面设计、兼容性保障与文档工程的完整方法论。</p> </blockquote> <hr> <h2 id="目录">目录</h2> <ol> <li><a href="#1-%E5%BA%93-vs-%E5%BA%94%E7%94%A8%E8%AE%BE%E8%AE%A1%E7%9B%AE%E6%A0%87%E5%B7%AE%E5%BC%82">库 vs 应用：设计目标差异</a></li> <li><a href="#2-%E5%8C%85%E7%BB%93%E6%9E%84%E4%B8%8E%E6%A8%A1%E5%9D%97%E5%88%92%E5%88%86">包结构与模块划分</a></li> <li><a href="#3-%E5%85%AC%E5%BC%80-api-%E9%9D%A2%E8%AE%BE%E8%AE%A1">公开 API 面设计</a></li> <li><a href="#4-%E7%B1%BB%E5%9E%8B%E6%A0%87%E6%B3%A8%E4%B8%8E-protocol">类型标注与 Protocol</a></li> <li><a href="#5-%E8%AF%AD%E4%B9%89%E5%8C%96%E7%89%88%E6%9C%AC%E4%B8%8E%E5%85%BC%E5%AE%B9%E6%80%A7">语义化版本与兼容性</a></li> <li><a href="#6-%E5%90%91%E5%90%8E%E5%85%BC%E5%AE%B9%E7%AD%96%E7%95%A5">向后兼容策略</a></li> <li><a href="#7-%E6%96%87%E6%A1%A3%E5%B7%A5%E7%A8%8B">文档工程</a></li> <li><a href="#8-%E9%94%99%E8%AF%AF%E8%AE%BE%E8%AE%A1">错误设计</a></li> <li><a href="#9-%E5%8F%91%E5%B8%83%E4%B8%8E%E7%A4%BE%E5%8C%BA%E6%B2%BB%E7%90%86">发布与社区治理</a></li> <li><a href="#10-%E6%A1%88%E4%BE%8B%E6%8B%86%E8%A7%A3%E4%B8%8E%E9%80%9F%E6%9F%A5%E8%A1%A8">案例拆解与速查表</a></li> </ol> <hr> <h2 id="1-库-vs-应用设计目标差异">1. 库 vs 应用：设计目标差异</h2> <table> <thead> <tr> <th>维度</th> <th>应用</th> <th>库</th> </tr> </thead> <tbody> <tr> <td>使用者</td> <td>你（可控）</td> <td>陌生用户（不可控）</td> </tr> <tr> <td>变更</td> <td>随意改</td> <td>必须兼容</td> </tr> <tr> <td>日志</td> <td>随便打</td> <td>用 <code>logger = logging.getLogger(__name__)</code> 但要克制</td> </tr> <tr> <td>依赖</td> <td>随意</td> <td>尽量少，避免依赖地狱</td> </tr> <tr> <td>错误</td> <td>可崩溃</td> <td>抛明确异常</td> </tr> <tr> <td>接口</td> <td>内部实现</td> <td>长期契约</td> </tr> </tbody> </table> <blockquote> <p><strong>第一原则</strong>：库作者要「克制」。每个新增功能都是未来要维护的契约。</p>