修改多语言数据程序库，不破坏文件格式和API

## 了解原生核心与各语言的轻量绑定 将代码库视为一个原生核心加上其他语言的轻量绑定。核心负责数据格式行为、编码、压缩、文件、索引、I/O、对象存储、线性代数、表操作、可选领域、测试基础设施和开发者工具。绑定负责公开这些行为，不应重复验证或业务逻辑。 保留架构的主要特征：异步I/O、原生列式内存、通过清单跟踪的版本化写入、面向工作负载的编码，以及跨本地和远程对象存储的统一存储抽象。 在规划命令或代码变更前，阅读代码库指南以及每个受影响语言或目录的指南。目录特定规则用于细化代码库契约，而不是取代它。 ## 稳定格式保持兼容，不稳定格式可自由修改 将每种声明为稳定的格式视为持久的兼容性契约。对稳定数据的变更必须同时保持向后兼容性和向前兼容性。 将每种声明为不稳定的格式视为可抛弃格式。它可以自由变更；不得为早期不稳定修订版所写入的文件添加兼容代码、迁移、回退处理或测试。 以最新发布的稳定版本为基准评估新的兼容性工作，同时继续遵守所有稳定格式契约。只存在于当前开发分支中的状态不构成兼容性约束。不得仅仅为了保留尚未发布的中间状态，而削弱更简洁或更完整的设计。 ## 使用规定的命令和构建配置，不换用其他工具链 运行前，先找到受影响语言已记录的检查、测试、代码规范检查、格式化、覆盖率、基准测试和集成命令。使用代码库提供的软件包与测试选择器，不要另创一套并行流程。 不得因为某条命令似乎缺失、缓慢或不可用，就换用其他环境管理器或工具链。如果语言特定命令在已记录流程之外失败，应先纠正环境使用方式，再重新运行规定的命令。只有完成这些步骤后，才能断定依赖项或工具不可用。 使用代码库定义的编译配置，不要临时覆盖优化设置。进行基准测试和性能分析时，使用保留调试符号的优化构建。只有在本地调试、受I/O限制的基准测试，或链接时优化不会影响所测瓶颈的编译时间调查中，才可禁用链接时优化。 进行集成测试时，只启动所需的夹具服务，设置已记录的环境值，并运行指定的集成目标。 ## 编写聚焦的代码，以流式处理数据而不堆进内存 代码、示例和注释使用英语。代码不仅要考虑执行，也要优化可读性。只有在说明不明显的原因时才添加注释；审查前应移除直接调试打印，改用既有的跟踪或日志系统。 将两处或更多位置重复的逻辑提取为共享辅助函数。仅使用一次的逻辑应保留在调用位置。只有辅助函数能实质降低认知负担或消除大量重复时才引入；不要添加只改名或转发调用的轻薄包装器。 保持变更聚焦。避免顺手重构、重新格式化和仅涉及外观的编辑。保留流式行为，不要将批次收集到内存中；对于密集整数成员关系，优先使用紧凑位图结构，而不是通用哈希集合。 ## 保持绑定轻量，旧公共API先弃用而不是直接破坏 将验证和逻辑集中在原生核心中，并让每个语言绑定保持为轻量包装器。所有绑定使用相同的参数名；要么在所有位置一起重命名，要么任何位置都不重命名。 绝不能就地破坏现有公共签名。使用相应语言支持的注解将旧方法标记为弃用，并添加新方法。将一组互斥的布尔标志替换为一个枚举或模式参数。 核心行为发生变更时，应同时更新每个适用绑定、生成的接口、示例和兼容性测试。绑定不得暗中以另一种含义解释核心会拒绝的值。 ## 按值的含义命名，并用清晰的错误拒绝无效输入 根据变量的值是什么来命名，而不是根据它碰巧如何使用来命名。当所属类型或模块已经说明领域时，应去掉多余前缀。在API和文档中始终使用一种获准的复数形式，并优先使用不依赖存储供应商的名称，而不是供应商特定术语。 重命名类型、结构或枚举时，应同时更新方法、字段、变量、测试和文档。 在API边界验证输入，并通过说明清楚的错误拒绝无效值。绝不能暗中将值限制到上下限或进行调整。当构建器或配置中的互斥选项同时存在时，应拒绝输入。错误消息应包含相关变量名、值、大小和类型。 ## 谨慎添加依赖项，并保持锁定文件同步 添加外部软件包前，优先考虑标准库或现有工作区依赖项。确保锁定文件只包含有意变更，还原无关升级；只有注释中包含指向上游议题的链接时，才能固定存在缺陷的依赖项。 工作区依赖项发生变更时，通过已记录的清单特定检查，刷新根锁定文件以及每个被排除绑定的锁定文件，然后提交所有对应更新。保持离线锁定文件同步挂钩启用。 将可选或领域特定依赖项置于功能标志之后。对于实质性的领域功能，优先使用独立软件包，以免默认构建和使用方继承不需要的代码。 ## 每个缺陷修复和新功能都配上测试 每项缺陷修正和功能都必须有对应测试。不得接受没有测试的代码。 如果各个案例仅输入不同，应使用相应语言的参数化测试功能，并为案例指定易读名称。测试中的打印应替换为断言，因为仅产生文本不能发现回归。 如果现有测试已经负责相关行为，应扩展该测试，而不是添加重叠的测试文件。新增内容放在既定测试位置。跳过的测试必须链接到跟踪议题；绝不能添加没有持久理由的裸跳过注解。 ## 用空值、空数据和旧稳定版文件做测试 读取、索引和扫描测试应包括多片段场景。索引测试应覆盖null元素、全为null的集合、空集合和null列。向量索引测试必须断言召回率至少为0.5，不能只检查索引是否创建成功。 进行向后兼容性测试时，使用由早期稳定版本生成并纳入版本控制的数据集。保留一个用于断言生成方版本的数据生成脚本，并在读取前将这些夹具复制到临时存储。 不得仅仅为了避开编译而禁用文档测试。编写能在函数形态上下文中编译的示例。不要降低生产代码的覆盖率阈值；应使用项目获准的覆盖率注解，将仅用于测试的辅助工具排除在覆盖率之外。 ## 为每个公共API写文档，并附上可编译的示例 记录每个公共API并提供示例。链接到相关类型和方法；每次重构代码时，都要让示例与真实签名保持同步。 对于编码层、文件格式和存储布局等层次结构，使用ASCII树状图。遵守文档系统的缩进契约，包括在提示指令下使用四个空格缩进。 审查前检查注释和文档中的错别字。无法继续编译或使用了过时API名称的文档属于兼容性缺陷，而不是外观问题。 ## 给议题加标签，提交变更请求前先通过lint检查 通过命令行工具或API创建议题时，应显式传入用于缺陷、功能或性能工作的标签，因为这一途径可能绕过模板自动化。为标题添加与分类匹配的前缀，让基于内容的自动化获得可靠的备用信号。 使用代码库规定的常规变更标题前缀，并在有用时添加作用域。创建或更新变更请求前，即使检查成本很高，也要对每个被修改的语言界面运行必需的代码规范检查。 按照各语言指南中的环境流程运行相应代码规范检查命令。如果无法运行某项必需检查，应在变更请求摘要中明确说明阻断原因，不得暗示验证已经完成。 ## 审查集中在严重缺陷和安全问题上 贡献者和维护者的精力有限。审查应保持简洁清楚，并聚焦最高严重度的缺陷、性能回归和安全问题。 不要复述详细变更，也不要重复已经正确的内容。检查命名一致性、既有错误处理模式和测试覆盖率。引用受影响位置，并说明每项阻断性发现的具体后果。