构建 API 易找、用真实数值测试的数据处理库

## 把复杂的源数据藏在简单对象后面 用直观的领域对象封装源格式的复杂性，同时不隐藏重要功能。让常见操作可以直接完成，再在用户需要时逐步呈现专门的解析、报告和检查功能。 先读后写。修改代码前，检查既有抽象、命名模式、模块边界和附近的测试。除非存在具体的不兼容问题，必须采用新模式，否则应扩展现有设计。 ## 修改前先理清各模块负责什么 维护一份简洁的导航图，从用户需求指向负责该需求的模块和关键领域类。图中应包含用于定位记录、加载实体、解析结构化数据、构建报表、读取附注、打开文档和创建类型化报告的公共入口。 编辑前，端到端追踪具有代表性的数据流。跟随一个请求从公共入口依次经过数据获取、解析、类型化对象、报表、附注、报告和文档提取。确认每项转换由哪一层负责，以及用户应从何处深入查看支撑细节。 利用导航图选择承担该职责的最小模块。如果另一个层已经负责某项行为，就不得仅因方便而将该行为放入其他文件。 ## 大文件分小块阅读，只做小范围修改 对于大于 30 KB 的模块，应将其视为多个局部上下文，而不是作为一个整体读取或重写。搜索相关符号，检查包含它的类或函数，然后阅读足够多的相邻代码，以理解不变条件和调用位置。 修改大型文件前，找到相关测试、import、子类和公共引用。保持补丁范围狭窄，遵循周边约定，并避免与本次功能改动无关的重新格式化或重构，以免掩盖实际变更。 ## 在议题系统中记录并更新工作 将项目的议题系统作为进行中工作的持久记录。查看待处理和进行中的项目，选择相关议题，并在实现前将其移至活动状态。对于新发现的缺陷或任务，应使用清晰的标题、类型和优先级进行记录，不得只留在注释或聊天中。 当范围、阻碍因素或结论发生变化时，更新同一个议题。只有完成必要验证后才能关闭。保留待处理、进行中、受阻和已关闭这些已定义状态。如果跟踪系统使用五级优先级，则保持以 `0` 表示关键工作、以 `4` 表示待办工作，不得临时发明其他标签。 ## 测试库是否做到文档承诺的内容 验证要确认的不是内部代码能否运行，而是程序库能否兑现文档中的承诺。应用以下三项原则： 1. 文档就是规范，因此文档中的每个示例都必须可验证。 2. 数据正确性至关重要，因此检查必须断言具体的预期值，而不能只确认结果存在。 3. API 必须能够解决问题，因此用户和代理必须可以从问题出发，找到适当的对象、方法和支撑证据。 用这些原则统一评估功能设计、文档、测试用例和失败行为。 ## 为每个新功能配上真实数值测试和可运行的文档示例 每项新的面向用户功能都必须包含： - 一项基于真实源记录中具体数值的基准事实断言，并且该数值已经过独立核验； - 一个同时可以作为自动验证运行的文档示例； - 一项静默失败检查，用于证明无效或缺失的输入会产生有用的错误，而不是空值或无提示失败； - 一次可发现性更新，使该功能出现在项目导航、功能目录或代理指南中。 即使正常路径的实现可以运行，只要缺少上述任何一项，该功能就仍未完成。 ## 先跑快速的本地测试，网络测试逐个运行 分别提供用于快速本地验证、联网验证、回归验证和覆盖率报告的命令。先运行与改动相关的最小本地检查，只有在聚焦检查通过后才扩大范围。 只有不接触外部服务的快速测试才可并行执行。联网验证必须按顺序运行，并遵守服务速率限制。如果记录的响应夹具能在不掩盖待验证契约的情况下，使外部行为快速且可确定，就应使用这些夹具。 将回归用例放在专用区域，并用稳定的名称把每个用例与其原始缺陷关联起来。覆盖率只能作为辅助证据，不能替代对行为和数据的断言。 ## 用多样的源数据检查准确数值和清楚的报错 断言准确的领域值、规范化结构和有意义的错误消息。如果正确性取决于数值本身，那么只断言结果存在是不够的。 不要只依赖一个熟悉的示例，应让源记录覆盖不同组织、行业、格式和报告期间。明确检验格式错误、不完整和不受支持的输入。确认失败会返回可执行的处理建议，且绝不会无提示地退化为空结果。 需要外部数据时，保留确定性的夹具，并记录其预期值的确定方式。上游契约发生变化时，应有意识地更新夹具；不得仅为让失败的检查通过而刷新夹具。 ## 让版本和文档与能运行的代码保持一致 从指定的元数据文件读取项目版本，避免在无关模块中重复保存该版本。让代码库导航、验证指南、公共示例和功能目录与实际支持的行为保持同步。 API 路径发生变化时，在同一工作项中更新文档和可执行示例。即使替代实现本身正确，只要文档所述路径已无法运行，面向用户的契约就已经失效。