二十二、包管理与发布 (Cargo 进阶)

以下是关于 Rust 包管理与发布的详细介绍，包含 Cargo 高级用法、私有仓库配置、发布流程：

一、Cargo 包管理进阶

1. Cargo.toml 详细配置

[package]
name = "my-crate"           # 包名（必须全小写，用短横线分隔）
version = "0.1.0"           # 语义化版本 (SemVer)
edition = "2021"            # Rust 版本（2015/2018/2021/2024）
authors = ["Your Name <you@example.com>"]
description = "A fantastic Rust library"  # 简短描述（显示在 crates.io）
license = "MIT OR Apache-2.0"            # SPDX 许可证标识
repository = "https://github.com/you/my-crate"  # 源代码仓库
documentation = "https://docs.rs/my-crate"      # 文档链接
readme = "README.md"                     # 项目介绍文件
keywords = ["web", "parser", "no-std"]   # 搜索关键词（最多5个）
categories = ["web-programming", "parsing"] # crates.io 分类（最多5个）

# 依赖配置示例
[dependencies]
tokio = { version = "1.0", features = ["full"] }  # 指定版本和特性
serde = { version = "1.0", optional = true }       # 可选依赖
wasm-bindgen = { git = "https://github.com/rustwasm/wasm-bindgen" } # Git 依赖

[dev-dependencies]  # 测试/示例专用依赖
tempfile = "3.3"

[build-dependencies]  # 构建脚本依赖
cc = "1.0"

[features]  # 条件编译特性
default = ["serde"]  # 默认启用的特性
wasm = ["dep-wasm/some-feature"]  # 自定义特性

2. 版本控制策略

• 语义化版本 (SemVer)：

  • MAJOR.MINOR.PATCH（如 1.2.3）
  • MAJOR：不兼容的 API 变更
  • MINOR：向后兼容的功能新增
  • PATCH：向后兼容的问题修复

• 版本约束语法：

  dep = "1.2.3"    # 严格匹配
  dep = "^1.2.3"   # 兼容更新（相当于 >=1.2.3, <2.0.0）
  dep = "~1.2.3"   # 仅更新补丁（相当于 >=1.2.3, <1.3.0）
  dep = ">=1.2.3, <1.5.0"  # 范围约束

二、私有包管理

1. 配置私有 Cargo 源

在 ~/.cargo/config.toml 中添加：

[registries]
my-registry = { index = "https://git.example.com/git/crates.io-index.git" }

[source.crates-io]
replace-with = "my-registry"  # 默认使用私有源

2. 发布到私有源

# 1. 登录私有源
cargo login --registry my-registry your-token

# 2. 发布
cargo publish --registry my-registry

3. 使用私有 Git 依赖

[dependencies]
my-private-lib = { git = "https://github.com/your/private-repo", branch = "main" }

三、发布到 crates.io

1. 发布准备

# 1. 注册账号并获取 API Token
#   访问 https://crates.io 获取

# 2. 本地登录
cargo login your-api-token

# 3. 检查包元数据
cargo publish --dry-run

# 4. 生成文档（可选）
cargo doc --no-deps --open

2. 发布流程

# 1. 更新版本号（遵循 SemVer）
cargo set-version 0.2.0  # 需要安装 cargo-edit: `cargo install cargo-edit`

# 2. 提交代码并打标签
git commit -am "Release v0.2.0"
git tag v0.2.0
git push --tags

# 3. 正式发布
cargo publish

3. 发布后操作

• 撤回版本（仅限 24 小时内）：

  cargo yank --vers 0.2.0

• 取消撤回：

  cargo yank --vers 0.2.0 --undo

四、高级包管理技巧

1. 工作空间 (Workspace)

Cargo.toml 配置：

[workspace]
members = [
    "crates/core",
    "crates/cli",
    "examples/demo"
]
resolver = "2"  # 统一特性解析（2021 Edition 默认）

2. 条件编译与特性

// src/lib.rs
#[cfg(feature = "wasm")]
pub mod wasm {
    pub fn greet() { println!("WASM mode"); }
}

#[cfg(not(feature = "wasm"))]
pub mod native {
    pub fn greet() { println!("Native mode"); }
}

3. 平台特定依赖

[target.'cfg(windows)'.dependencies]
winapi = "0.3"

[target.'cfg(unix)'.dependencies]
libc = "0.2"

五、最佳实践

1. 文档规范

/// 计算两个数的和
///
/// # Examples
/// ```
/// assert_eq!(my_crate::add(2, 3), 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

2. 测试策略

# Cargo.toml
[[test]]
name = "integration"
path = "tests/integration.rs"

[dev-dependencies]
assert_fs = "1.0"  # 文件系统测试工具

3. 持续集成 (CI) 示例

.github/workflows/ci.yml：

name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions-rs/toolchain@v1
        with:
          profile: minimal
          toolchain: stable
          override: true
      - run: cargo test --all-features
      - run: cargo doc --no-deps

六、常见问题解决

1. 发布失败：api errors

• 检查 Cargo.toml 中是否有重复的 [package] 段
• 确保 description 和 license 已填写

2. 依赖冲突

使用 cargo tree 分析依赖树：

cargo tree -d  # 显示重复依赖
cargo update -p some-crate  # 更新特定包

通过以上配置和流程，你可以高效管理 Rust 包的开发、测试和发布。关键点：

1. 严格遵循 SemVer 规范
2. 合理使用工作空间和条件编译
3. 完善的文档和测试保障质量
4. 利用 CI/CD 自动化流程