Cargo 工作区 #

传统多仓库
├── repo-a/          # 独立仓库
│   ├── Cargo.toml
│   └── Cargo.lock
├── repo-b/          # 独立仓库
│   ├── Cargo.toml
│   └── Cargo.lock
└── repo-c/          # 独立仓库
    ├── Cargo.toml
    └── Cargo.lock

工作区（Monorepo）
├── Cargo.toml       # 工作区配置
├── Cargo.lock       # 共享锁定文件
├── crates/
│   ├── crate-a/
│   ├── crate-b/
│   └── crate-c/
└── apps/
    ├── app-1/
    └── app-2/

mkdir my_workspace
cd my_workspace

[workspace]
members = [
    "crates/*",
    "apps/*",
]
resolver = "2"

# 创建库包
mkdir -p crates
cd crates
cargo new my_lib --lib
cargo new my_utils --lib

# 创建应用包
mkdir -p ../apps
cd ../apps
cargo new my_app
cargo new my_cli

my_workspace/
├── Cargo.toml           # 工作区配置
├── Cargo.lock           # 共享锁定文件
├── crates/
│   ├── my_lib/
│   │   ├── Cargo.toml
│   │   └── src/
│   │       └── lib.rs
│   └── my_utils/
│       ├── Cargo.toml
│       └── src/
│           └── lib.rs
└── apps/
    ├── my_app/
    │   ├── Cargo.toml
    │   └── src/
    │       └── main.rs
    └── my_cli/
        ├── Cargo.toml
        └── src/
            └── main.rs

# 创建工作区根目录
mkdir my_workspace && cd my_workspace

# 初始化工作区
cargo init --name my_workspace

# 编辑 Cargo.toml 添加工作区配置
# 然后创建成员
cargo new crates/my_lib --lib
cargo new apps/my_app

[workspace]
# 成员列表
members = [
    "crates/*",      # 通配符匹配
    "apps/*",
    "tools/cli",     # 具体路径
]

# 排除成员
exclude = [
    "crates/experimental",
    "examples/old",
]

# 解析器版本（推荐使用 v2）
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"
repository = "https://github.com/user/my_workspace"

# crates/my_lib/Cargo.toml
[package]
name = "my_lib"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"
thiserror = "1.0"

# crates/my_lib/Cargo.toml
[dependencies]
serde.workspace = true
tokio.workspace = true

[dev-dependencies]
anyhow.workspace = true

[workspace]
members = ["crates/*", "apps/*"]
exclude = ["crates/experimental"]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"
rust-version = "1.70"
license = "MIT OR Apache-2.0"
repository = "https://github.com/user/my_workspace"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tokio = { version = "1.0", features = ["full"] }
anyhow = "1.0"
thiserror = "1.0"
tracing = "0.1"
tracing-subscriber = "0.3"

# 内部包
my_lib = { path = "crates/my_lib" }
my_utils = { path = "crates/my_utils" }

# 构建所有成员
cargo build

# 构建特定成员
cargo build -p my_lib
cargo build -p my_app

# 构建多个成员
cargo build -p my_lib -p my_utils

# 发布构建
cargo build --release

# 构建所有目标
cargo build --all-targets

# 运行特定二进制
cargo run -p my_app
cargo run -p my_cli

# 运行并传递参数
cargo run -p my_cli -- --help

# 运行示例
cargo run -p my_lib --example basic

# 测试所有成员
cargo test

# 测试特定成员
cargo test -p my_lib

# 测试特定测试
cargo test -p my_lib test_name

# 测试所有成员（并行）
cargo test --workspace

# 检查所有成员
cargo check

# 检查特定成员
cargo check -p my_lib

# 检查所有目标
cargo check --all-targets

# 清理所有构建输出
cargo clean

# 清理特定成员
cargo clean -p my_lib

# apps/my_app/Cargo.toml
[dependencies]
my_lib = { path = "../../crates/my_lib" }
my_utils = { path = "../../crates/my_utils" }

# 使用工作区依赖
[dependencies]
my_lib.workspace = true
my_utils.workspace = true

[dependencies]
my_lib = { version = "0.1.0", path = "../../crates/my_lib" }

my_app
├── my_lib
│   └── my_utils
└── my_utils

my_cli
└── my_lib
    └── my_utils

# 列出所有成员
cargo metadata --format-version 1 | jq '.workspace_members'

# 或使用
cargo tree --depth 0

# 使用 --package 或 -p
cargo build -p my_lib

# 使用 --workspace 或 --all
cargo build --workspace
cargo build --all

# 排除成员
cargo build --workspace --exclude my_cli

# 并行构建（默认）
cargo build -j 4

# 串行构建
cargo build -j 1

my_workspace/
├── Cargo.toml
├── Cargo.lock
├── README.md
├── .gitignore
├── crates/              # 库包
│   ├── core/
│   ├── utils/
│   └── macros/
├── apps/                # 应用程序
│   ├── server/
│   └── cli/
├── examples/            # 示例
│   └── basic/
├── tests/               # 集成测试
│   └── integration/
└── docs/                # 文档
    └── guide/

# 根 Cargo.toml
[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"
authors = ["Team <team@example.com>"]
repository = "https://github.com/org/repo"

[workspace.dependencies]
# 共享依赖版本
serde = "1.0"
tokio = "1.0"

# 内部包
core = { path = "crates/core" }
utils = { path = "crates/utils" }

# 统一版本号
cargo install cargo-workspaces
cargo workspaces version patch

# 或手动更新
# 编辑所有 Cargo.toml 的 version 字段

# 发布所有成员
cargo workspaces publish

# 发布特定成员
cargo publish -p my_lib

# .github/workflows/ci.yml
name: CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: dtolnay/rust-toolchain@stable
      - uses: Swatinem/rust-cache@v2
      
      - name: Check
        run: cargo check --all-targets
      
      - name: Test
        run: cargo test --workspace
      
      - name: Lint
        run: cargo clippy --workspace -- -D warnings
      
      - name: Format
        run: cargo fmt --check

# 安装
cargo install cargo-workspaces

# 创建新包
cargo workspaces create crates/new_lib --lib

# 列出包
cargo workspaces list

# 版本管理
cargo workspaces version patch
cargo workspaces version minor
cargo workspaces version major

# 发布
cargo workspaces publish

# 执行命令
cargo workspaces run -- cargo something

# 安装
cargo install cargo-hack

# 检查所有特性组合
cargo hack check --each-feature

# 检查所有目标
cargo hack check --target-thumbv7m-none-eabi

# 安装
cargo install cargo-nextest

# 运行测试
cargo nextest run --workspace

# 错误：cyclic package dependency
# 解决：重构代码，提取公共部分

# 错误结构
my_app → my_lib → my_app

# 正确结构
my_app → my_lib
       → my_utils
my_lib → my_utils

# 确保使用工作区依赖
[dependencies]
serde.workspace = true  # ✅

# 而不是
serde = "1.0"           # ❌ 可能版本不一致

# 使用增量编译
# .cargo/config.toml
[build]
incremental = true

# 减少并行任务
cargo build -j 2

# 查看依赖树
cargo tree --duplicates

# 使用 patch 解决
[patch.crates-io]
conflicting-dep = { path = "../fixed" }

[workspace]
members = [
    "crates/api",
    "crates/db",
    "crates/models",
    "crates/utils",
    "apps/server",
    "apps/cli",
    "apps/migrations",
]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"

[workspace.dependencies]
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
sqlx = { version = "0.7", features = ["runtime-tokio", "postgres"] }
axum = "0.7"
anyhow = "1.0"
thiserror = "1.0"

# 内部包
api = { path = "crates/api" }
db = { path = "crates/db" }
models = { path = "crates/models" }
utils = { path = "crates/utils" }

[workspace]
members = [
    "crates/core",
    "crates/derive",
    "crates/macros",
    "examples/*",
]
resolver = "2"

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "MIT"

[workspace.dependencies]
syn = { version = "2.0", features = ["full"] }
quote = "1.0"
proc-macro2 = "1.0"

core = { path = "crates/core" }