⚡

Cargo依赖管理Skill managing-cargo-dependencies

这个技能用于管理 Rust 项目中 Cargo.toml 文件的依赖项。它包括添加、更新、移除依赖项，组织依赖项到公共和私有部分，配置版本和默认功能，并在工作区中统一管理依赖。关键词：Cargo, 依赖管理, Rust, workspace, Cargo.toml, 依赖项。

其他 0 次安装 0 次浏览 更新于 3/11/2026

name: managing-cargo-dependencies description: HASH 工作区中 Cargo.toml 依赖管理模式的指南。用于添加、更新或移除依赖，组织 Cargo.toml 部分，配置版本固定和默认功能，或管理公共依赖。 license: AGPL-3.0 metadata: triggers: type: domain enforcement: suggest priority: high keywords: - cargo - dependency - Cargo.toml - crate - workspace.dependencies - default-features intent-patterns: - “\b(add|update|remove|manage)\b.*?\b(dependency|dependencies|crate|crates)\b” - “\bCargo\.toml\b” - “\b(public|private)\s+dependency\b”

Cargo 依赖项管理

在 HASH 仓库的工作区结构中，为 Cargo.toml 文件添加和管理依赖项的指南。

核心原则

HASH 使用严格的工作区依赖模式：

✅ 应该做：

  • 将外部依赖项添加到工作区根目录 [workspace.dependencies]
  • 使用插入符版本说明符（例如，version = "1.0.0" = ^1.0.0）
  • 对所有依赖项设置 default-features = false，除非特别需要
  • 在包 Cargo.toml 中使用 workspace = true
  • 使用注释标题将依赖项组织成 4 个部分
  • 对于在公共 API 中暴露的依赖项，使用 public = true
  • 使用空格对齐依赖项名称以提高可读性

❌ 不应该做：

  • 直接在包 Cargo.toml 中添加版本号
  • 在工作区根目录使用带有 = 前缀的精确版本（例如，=1.0.0）
  • 不考虑影响就启用 default-features
  • 混合不同的依赖项类型而不添加部分注释
  • 忘记为在公共 API 中暴露的依赖项设置 public = true

快速参考

四部分模式

每个包 Cargo.toml 必须将依赖项组织成以下部分：

[dependencies]
# 公共工作区依赖项
hash-graph-types = { workspace = true, public = true }
hashql-core      = { workspace = true, public = true }

# 公共第三方依赖项
serde     = { workspace = true, public = true, features = ["derive"] }
tokio     = { workspace = true, public = true }

# 私有工作区依赖项
error-stack = { workspace = true }
hash-codec  = { workspace = true }

# 私有第三方依赖项
tracing     = { workspace = true }
regex       = { workspace = true }

即使某个部分为空，也要保留所有 4 个部分注释。

快速添加过程

  1. 检查工作区根目录 - 依赖项是否已经存在？
  2. 如果需要，添加到工作区 - 使用插入符版本 1.2.3
  3. 确定部分 - 公共工作区/第三方还是私有？
  4. 添加到包 - 使用 workspace = true（如果需要，加上 public = true）

详细指南

选择与任务匹配的指南：

workspace-setup.md

使用时机： 向工作区根目录添加新依赖项

  • 如何向工作区添加外部 crate
  • 使用精确版本进行版本固定
  • 默认功能配置
  • 工作区成员路径

package-dependencies.md

使用时机： 向包 Cargo.toml 添加依赖项

  • 四部分组织结构
  • 公共与私有依赖项
  • 何时使用 public = true
  • 对齐和格式化规则
  • 功能配置

examples-reference.md

使用时机： 查找来自 HASH 代码库的真实示例

  • 来自 @local/codec 的完整示例
  • 来自 @local/hashql/core 的完整示例
  • 可选依赖项模式
  • 开发依赖项结构

常见模式

添加新外部依赖项

# 1. 添加到工作区根目录 Cargo.toml
[workspace.dependencies]
my-crate = { version = "1.2.3", default-features = false }

# 2. 添加到包 Cargo.toml（适当部分）
[dependencies]
# 私有第三方依赖项
my-crate = { workspace = true }

使依赖项公共

# 当依赖项出现在你的公共 API 时使用
serde = { workspace = true, public = true, features = ["derive"] }
tokio = { workspace = true, public = true }

可选依赖项

[dependencies]
serde = { workspace = true, optional = true, features = ["derive"] }

[features]
serde = ["dep:serde", "other-dep/serde"]

参考文献