• 数据库
• 时序数据库

core/influxdb_line_protocol是 InfluxDB 仓库中一个独立发布的 Rust crate，提供纯 Rust 实现的 InfluxDB Line Protocol 编写，完整讲解该 crate 从文档同步、版本号更新、PR 合入到 crates.io 发布的四步标准流程，并结合 Cargo.toml 与 lib.rs 等源码说明每一步背后的工程约束与注意事项。读完本文，你将掌握发布一个被 InfluxDB 仓库独立维护、独立发布的 Rust 库的标准操作流程，并能规避常见的发布前检查遗漏。

发布流程总览

该 crate 的发布流程在 RELEASE.md 中被明确划分为四个步骤：

1. 使用cargo-rdme同步更新 README.md（将 rustdoc 注释复制到 README）；
2. 更新 Cargo.toml 中的版本号；
3. 提交 PR 并合入主分支；
4. 依次执行cargo publish --dry-run与cargo publish发布到 crates.io。

下面逐一展开每个步骤的实操细节与原理。

Step 1：用 cargo-rdme 同步 README.md

发布的第一步不是改版本号，而是同步文档。仓库约定 README.md 直接复制自 crate 根文档（lib.rs顶部的//!rustdoc 注释），二者之间用一对<!-- cargo-rdme start -->与<!-- cargo-rdme end -->标记界定同步区域：

• README.md 中位于两个标记之间的内容，全部来自 lib.rs 顶部的 rustdoc 注释；
• 标记之外的头部（# influxdb_line_protocol）与尾部链接定义可自行维护，不会被覆盖。

安装 cargo-rdme

cargo-rdme是执行同步的工具，安装命令为：

cargo install cargo-rdme --locked

使用--locked参数可确保安装时严格遵循其Cargo.lock，避免依赖版本漂移导致工具行为不一致。

执行同步

在 crate 目录下运行：

cargo rdme

该命令会读取lib.rs的 crate 级 rustdoc 注释，并回写到 README 的标记区间内。因此，在修改了lib.rs顶部//!文档（例如新增 API 示例、调整描述）后，务必在发布前重新运行cargo rdme，否则 crates.io 上展示的 README 会与代码文档脱节。

为什么 README 需要与 rustdoc 保持一致

从源码结构看，lib.rs 的 crate 级文档既是docs.rs上渲染的 API 首页，又被cargo-rdme复制为 crates.io 的 README 展示页。二者共用一份内容，可以避免维护两份文档带来的漂移问题。README 中当前展示的核心内容包括：

• crate 定位：包含一个Line Protocol 解析器与一个Line Protocol 构建器；
• 解析器设计说明：基于 nom 组合子实现，目标是与 Go 实现 兼容（README 中也坦承两者可能存在少量差异）；
• 一个完整的解析示例（见下文）。

Step 2：更新 Cargo.toml 版本号

文档更新完成后，需要修改 Cargo.toml 中的version字段。RELEASE.md 给出的示例 diff 如下：

--- a/influxdb_line_protocol/Cargo.toml +++ b/influxdb_line_protocol/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "influxdb_line_protocol" -version = "1.0.0" +version = "2.0.0" authors = ["InfluxDB IOx Project Developers"] edition = "2024" license = "MIT OR Apache-2.0"

注意示例中 crate 名写作influxdb_line_protocol（下划线形式），而 Cargo.toml 中实际的name为influxdb-line-protocol（连字符形式，crates.io 包名）；diff 仅为示意，实际修改时只需改动version一行即可。

版本号的具体取值（1.0.0→2.0.0）应遵循 SemVer 语义：破坏性 API 变更升主版本号，新增兼容功能升次版本号，缺陷修复升补丁号。

版本更新的注意事项：独立发布的 crate 不能依赖未发布的 workspace crate

这是该 crate 发布流程中最重要的工程约束之一。查看 Cargo.toml 中的注释可以确认：

• 该 crate 以独立包的形式发布到 crates.io，但为了维护便利，源码保留在本仓库中；
• 因此它不允许在[dependencies]中使用path依赖指向本 workspace 内其他未发布的 crate（否则发布时 crates.io 无法解析这些本地路径依赖）；
• 唯一的例外是schema依赖，它位于optional = true的可选依赖中，且仅在启用test_helpersfeature 时才会被引入（见[features]段），不影响正常发布路径；
• 相比之下，[dev-dependencies]中的path依赖（如test_helpers）是被允许的，因为它们不参与发布产物。

因此，如果你为这个 crate 新增了对其他 workspace crate 的依赖，必须在发布前确认该依赖也已发布到 crates.io，或将其放入可选依赖，否则cargo publish会失败。

该 crate 的公开能力一览

版本号变更背后是对公开 API 的改动。当前 Cargo.toml 揭示了 crate 的功能面：

• 主要依赖：bytes（缓冲区操作）、log（解析日志）、nom（组合子解析器，关闭默认特性仅启用std）、smallvec（小向量优化）、snafu（错误类型推导）；
• 可选依赖与 feature：
  • test_helpers：启用后引入proptest与schema，提供测试辅助工具（对应 test_helpers.rs 模块，#[cfg(feature = "test_helpers")]条件编译于 lib.rs）；
  • large-strings：将字符串组件的最大长度限制从默认的 64 KiB（STRing_LENGTH_LIMIT_IN_BYTES = 65_536，对应 lib.rs）提升到 1 MiB，用于 v1 迁移兼容场景。

这些 feature 开关是发布说明（release notes）中需要重点交代的内容。

Step 3：提交 PR 并合入

版本号与 README 更新完成后，将改动提交为一个 Pull Request，经过评审与 CI 通过后合入主分支。

结合仓库的测试资产，合入前的 CI 会覆盖以下质量关卡：

• 单元测试：crate 内部包含大量针对解析与构建行为的测试，例如 builder.rs 中的test_string_escape系列用例，验证字符串转义规则（逗号、等号、空格、反斜杠、双引号的转义）；
• 模糊测试（fuzzing）：仓库为解析器维护了独立的 fuzz 工程 fuzz/Cargo.toml，其 fuzz target parsing_errors.rs 会对任意输入字符串调用parse_lines，并对除已知合法错误（如MeasurementValueInvalid、EndsWithBackslash、ExpectedTagKey、ExpectedTagValue、CannotParseEntireLine、TimestampValueInvalid等）之外的其他错误直接panic!。这保证了解析器对畸形输入不会产生未预期的错误类型——发布前的 PR 不应引入新的未覆盖错误路径。

Step 4：发布到 crates.io

先做干跑（dry-run）

正式发布前，先在 crate 目录下执行：

cargo publish --dry-run

--dry-run会完整模拟打包、校验与上传前的所有步骤，但不会真正发布。它能够提前暴露以下问题：

• 版本号冲突（该版本已存在于 crates.io）；
• 未发布的 path 依赖（前述"独立发布"约束的最终防线）；
• README 或许可证文件缺失、Cargo.toml元数据不合法；
• 打包文件意外包含本地大文件或敏感文件。

dry-run 通过后，正式发布：

cargo publish

命令执行成功后，新版本会立即在 crates.io 上可见，docs.rs也会自动构建并托管对应版本的 API 文档。

发布前自查清单

结合 RELEASE.md 与仓库源码，完整发布前应确认：

1. 文档已同步：cargo rdme已运行，README 与 rustdoc 一致；
2. 版本号已更新：遵循 SemVer 规则，且与本次改动范围匹配；
3. 无未发布的 path 依赖：[dependencies]中仅包含 crates.io 上已存在的 crate；
4. feature 变更已记录：如涉及test_helpers、large-strings的增删，应在 release notes 中说明；
5. CI 全绿：单元测试与 fuzz target 均通过，未引入新的未预期解析错误；
6. dry-run 通过：cargo publish --dry-run无告警与错误。

延伸：理解 crate 的解析器与构建器（发布内容的实体）

虽然发布流程本身是本文主线，但为了让你对"被发布的东西"有完整认知，这里结合源码简要说明 crate 的公开 API 实体——它们正是每次版本发布所承载的内容。

解析器：parse_lines

核心入口是parse_lines（定义于 lib.rs），它将按行分隔的输入解析为ParsedLine的迭代器：

• 每行先做前导空白裁剪，空行直接跳过；
• 单行解析成功后，若输入仍有剩余内容则返回CannotParseEntireLine错误（该行为与 Go 实现的逻辑对应，见代码中注释引用的 points_parser.go）；
• 解析出的字符串统一通过EscapedStr表示（lib.rs）：未转义时直接引用输入切片（SingleSlice），涉及转义时才复制为String（CopiedValue），兼顾性能与正确性。

README.md 中给出了开箱即用的解析示例，输入行：

cpu,host=A,region=west usage_system=64i 1590488773254420000

对应代码：

use influxdb_line_protocol::{ParsedLine, FieldValue}; let mut parsed_lines = influxdb_line_protocol::parse_lines( "cpu,host=A,region=west usage_system=64i 1590488773254420000" ); let parsed_line = parsed_lines .next() .expect("Should have at least one line") .expect("Should parse successfully"); let ParsedLine { series, field_set, timestamp, } = parsed_line; assert_eq!(series.measurement, "cpu"); let tags = series.tag_set.unwrap(); assert_eq!(tags[0].0, "host"); assert_eq!(tags[0].1, "A"); assert_eq!(tags[1].0, "region"); assert_eq!(tags[1].1, "west"); let field = &field_set[0]; assert_eq!(field.0, "usage_system"); assert_eq!(field.1, FieldValue::I64(64)); assert_eq!(timestamp, Some(1590488773254420000));

构建器：LineProtocolBuilder

另一个公开 API 是 LineProtocolBuilder，一个类型级状态机（typestate）构建器：

• 它永不返回运行时错误——非法调用顺序（如未 close_line 就 build、缺字段就 close_line、先写 field 再写 tag、先写 timestamp 再写 field）都会在编译期被拒绝（见 builder.rs 的compile_fail文档示例）；
• 它自动完成转义：measurement 与 tag 的 key/value 转义,、=、空格（COMMA_EQ_SPACE/COMMA_SPACE），字符串 field 值转义双引号（DOUBLE_QUOTE），反斜杠始终被转义（builder.rs）；
• 字段类型由FieldValuetrait 约束，支持&str（带引号）、f64、bool、i64（追加i后缀）、u64（追加u后缀）（builder.rs）。

典型用法：

use influxdb_line_protocol::LineProtocolBuilder; let lp = LineProtocolBuilder::new() .measurement("foo") .tag("bar", "baz") .field("qux", 42.0) .close_line(); assert_eq!(lp.build(), b"foo,bar=baz qux=42\n");

从设计看，该 builder 只保证语法合法性，不检查语义问题（如重复 tag/field 名、key 的命名限制），这一点在发布说明中应如实交代。

小结

influxdb_line_protocol的发布流程虽然只有四步，但每一步都承载着明确的工程约束：cargo-rdme保证 crates.io 展示文档与 rustdoc 同步；版本号更新遵循 SemVer；PR 合入依赖单测与 fuzz 双保险；cargo publish --dry-run则是发布前最后一道防线，尤其用于拦截"未发布的 path 依赖"这一独立发布 crate 特有的坑。对于希望在 InfluxDB 仓库内维护并对外发布独立 Rust 库的开发者，RELEASE.md 是一份可以直接照做的标准作业程序。

• 数据库
• 时序数据库