编写不悄悄改动数值、不泄露数据的数据复制（ETL）代码

## 除非被要求，不推送代码，也不改迁移 让每项变更都聚焦于正在解决的问题。除非为了保持正确性而必须进行范围更广的重构，否则优先采用最小且完整的差异。 引入模式、依赖项、辅助程序或测试夹具前，先检查附近的代码，并遵循既有的工作区约定。把格式化工具配置、编译器诊断和工作区静态检查设置视为可强制执行样式的权威来源。 除非用户明确要求相应操作，否则不得写入代码库、发布分支、创建变更请求或重写历史记录。 除非请求的工作明确需要更改迁移，否则不要改动数据库迁移。这也包括迁移文件中的注释和不可执行文本。 只有在范围确有依据时，才运行成本较高的全工作区检查。对于低风险的文档或配置变更，使用最小且相关的验证，并准确报告实际运行了什么。 ## 按数据概念组织模块，API 默认设为私有 按领域概念组织，而不是放入通用分类。将复制行为和复制专用类型放在一起；将可复用的数据库基本组件、源端辅助程序、槽位辅助程序和元数据访问放在集成边界中。 只有当另一个软件包真正依赖该API时，才使用软件包边界。在一个领域内，优先采用名为 `schema`、`data`、`event`、`store`、`source` 或 `slots` 的模块。 让顶层二进制程序专注于编排。把实现细节移入职责集中的辅助程序和模块。 默认采用私有可见性，只有存在真实调用方时才扩大范围。依次优先采用私有、软件包范围、公共可见性。把每次重新导出都视为API契约： - 避免从内部模块进行通配符重新导出； - 只公开最小且有用的设置作用面； - 将工作器编排、编解码器、运行时衔接逻辑和实现细节保持为私有； - 除非兼容性门面是有意设计的稳定API，否则不要使用。 相比巧妙的抽象，优先采用清晰且符合惯例的代码。按易读的顺序组织类型、构造函数、公共方法和私有辅助程序。 ## 防止舍入、截断等悄悄改变数值 当目标端可能静默接受语义变化时，应在本地验证值，例如舍入、截断、钳制、强制转换、溢出或精度损失。 如果目标端已经通过明确错误拒绝不支持的值，而写入路径中重复进行高成本验证的必要性尚未得到证明，就不要重复验证。 当检查式或基于特征的数值转换无损且可用时，应使用这些转换。只有在理解损失、适当时已检查范围，并且目标表示确实要求时，才使用有意的有损类型转换。 只有当映射不可能失败、语义无损、保持值不变且显而易见时，才使用隐式转换。 使用三个不同状态来建模补丁更新： - 省略的字段保留已存储的值； - 明确的null会清空可选值，或重置带默认值的字段； - 非null值替换已存储的值。 把完整配置转换为补丁语义时，应使用明确的转换辅助程序。不要把从保留变为清空的变化隐藏在通用转换特征之后。 ## 遇到错误输入时返回清楚的错误，而不是崩溃 对可恢复故障使用类型化错误和结果值。在保留原始错误作为来源链的同时，加入自有上下文，例如操作、标识符、计数、类型或语句。 除非经过有意净化的消息对调用方更安全，否则不要把底层错误压平为字符串。公共API响应不得暴露数据库驱动程序错误、内部查询、客户数据或基础设施细节。 只有程序员不变量被破坏时才允许panic。外部输入、格式错误的语法、不支持的值和系统状态故障必须返回明确错误。 解析器入口必须在不发生panic的情况下处理空输入、意外的输入结束、格式错误的转义、无效字节序列、无效范围、溢出、下溢和不支持的语法。 当输入控制偏移量时，优先采用检查式访问、迭代器和字节切片解析。只有局部边界或精确分块不变量使安全性显而易见时，才可直接索引。 为每个过去可能发生panic或被静默误解析的格式错误输入边界添加回归测试。 ## 根据任务持有的状态选择后台任务的停止方式 除非确有必要，否则避免使用unsafe代码。每个unsafe块旁边都必须有安全性说明，指出使该操作保持安全正确的不变量。 相比不必要的克隆或内部可变性，优先采用所有权和借用。 把长时间运行的异步工作置于有名称的任务或辅助程序之后，并根据其拥有的状态选择关闭行为： - 丢弃任务句柄会使任务脱离管理；当可丢弃的后台工作需要立即停止时，应显式中止； - 丢弃任务集会中止其拥有的每项任务； - 不要在即将退出并自动丢弃任务集的作用域前，重复中止该任务集； - 当任务集仍然存活但其中的任务必须停止时，使用显式中止操作； - 当任务拥有事务、已缓冲的目标端写入或对重试敏感的复制状态时，发送优雅停止信号并等待任务结束。 对于状态可以安全丢弃的轮询或遥测任务，不要添加复杂的关闭协调。 ## 不把秘密和客户数据放进代码和日志 把受跟踪的文件、分支、提交、审查、日志、屏幕截图、夹具、生成的工件和终端输出都视为可能对外可见。 绝不要把凭据、令牌、私有端点、客户数据、生产载荷、个人数据或专有配置放入代码、测试、文档、示例、注释、消息、遥测、panic详情或生成文件。 在示例中使用虚构的占位符。真实机密只能存储在已获批准的环境变量、被忽略的本地文件、机密管理器或CI机密存储中。 如果可疑值看起来是真实的，或来自私有环境，不要重现它。停止发布路径，在不引用该值的情况下报告其位置；如果可能已经发生泄漏，建议轮换或吊销。 对于可观测性： - 优先采用低基数标签； - 记录结构化元数据，例如表名、列名、类型、计数、长度、位置和操作名称； - 绝不要记录行值、单元格内容、敏感的请求或响应正文、凭据或令牌； - 对错误和结构化字段使用安全的显示格式； - 对敏感路由和监控范围捕获的正文进行净化。 ## 测试真实的复制事件，并确认测试真的运行了 先运行范围最窄的相关测试，再在共享行为、回归问题或请求确有依据时扩大范围。验证预期的测试确实已经执行；如果没有任何匹配测试，即使命令成功，也不能算作验证通过。 应用不确定的过滤器前先列出测试。如果主要测试运行器不支持文档测试，应单独运行文档测试。 创建自定义测试基础设施前，先复用附近的夹具、数据库辅助程序、等待原语和断言。 对于事件驱动的集成测试： 1. 在生成方能够发出事件前，注册通知或等待句柄。 2. 执行源端写入。 3. 等待预期通知。 4. 除非测试明确覆盖进行中的行为，否则应先关闭并等待流水线结束，再断言目标端状态。 5. 除非重启或隔离阶段要求清空历史，否则应对累积事件历史进行断言。 让预期的变更数据捕获事件符合源数据库实际的副本身份行为。对于无法发出部分更新行的模式，不要期待这种行。 ## 为代码写好文档，并报告运行过的检查 用简洁、准确的文字记录公共和私有条目。使用文档系统支持的引用方式链接类型和方法。为注释添加标点，并把注释放在所说明代码的上方。 将指标名称和标签键定义为常量，集中管理共享标签，并且只注册一次说明。每个源保留一个职责集中的指标任务，并配以较小的编排作用面。 完成前，确认受影响的范围： - 更改的目标能够编译； - 格式化检查通过； - 静态分析使用工作区静态检查配置并通过； - 相关单元测试和集成测试通过，而且确实已经运行； - 适用时，文档测试通过； - 注释和文档与最终行为一致； - 指标、日志和标签符合命名规则与数据安全规则。 报告已执行的检查、检查范围和任何有意省略的检查。如果命令输出显示没有实际测试任何有意义的目标，不要仅凭命令的退出状态声称完成。