# Rust 微服务开发最佳实践：Workspace 与 Docker 高效协同

**日期**: 2025-11-29
**标签**: #Rust #Microservices #Docker #DevEx #Tilt #Workspace

---

## 1. 背景与痛点

在采用 Rust 开发微服务架构时，我们面临着一个经典的**两难选择**：

### 方案 A：单一仓库 (Monorepo) + Workspace
*   **优点**：所有服务共享依赖库版本（`Cargo.lock`），代码复用极其方便，一次编译所有公共库（`target` 共享）。
*   **缺点**：在 Docker 容器化部署时，每次修改哪怕一行代码，都会导致 Docker Cache 失效，触发整个 Workspace 的重新编译。对于拥有数十个服务的系统，这简直是灾难。

### 方案 B：多仓库 (Polyrepo) 或 独立构建
*   **优点**：服务间彻底隔离，互不影响。
*   **缺点**：每个服务都要重新下载和编译一遍 `tokio`, `axum` 等几百个依赖。磁盘占用爆炸（每个服务 2GB+ target），编译时间爆炸（CPU 重复劳动）。

### 我们的目标
我们需要一种**两全其美**的方案：
1.  **开发时 (Dev)**：享受 Workspace 的增量编译速度，改一行代码只需 2 秒重启。
2.  **部署时 (Prod)**：享受容器的隔离性，且构建尽可能快。
3.  **体验 (DevEx)**：自动化热重载 (Hot Reload)，无需手动重启容器。

---

## 2. 解决方案：共享缓存挂载 + 容器内增量编译

核心思想是**放弃在 Docker 构建阶段进行编译**（针对开发环境），改为**在容器运行时利用挂载的宿主机缓存进行增量编译**。

### 2.1 关键技术点

1.  **极简开发镜像 (`Dockerfile.dev`)**:
    *   不再 `COPY` 源代码。
    *   不再运行 `cargo build`。
    *   只安装必要工具（如 `cargo-watch`）。
    *   所有源码和依赖通过 Volume 挂载。

2.  **共享编译缓存 (`cargo-target` Volume)**:
    *   创建一个 Docker Volume（或挂载宿主机目录）专门存放 `/app/target`。
    *   所有微服务容器**共享**这个 Volume。
    *   **效果**：服务 A 编译过的 `tokio`，服务 B 启动时直接复用，无需再次编译。

3.  **Cargo Registry 缓存 (`cargo-cache` Volume)**:
    *   挂载 `/usr/local/cargo`。
    *   **效果**：避免每次启动容器都要重新下载 crates.io 的索引和源码。

4.  **Cargo Watch 热重载**:
    *   容器启动命令为 `cargo watch -x "run --bin my-service"`。
    *   配合 Docker Compose 的源码挂载，一旦宿主机修改代码，容器内立即触发增量编译并重启进程。

### 2.2 实施细节

#### Dockerfile.dev (通用开发镜像)
```dockerfile
FROM rust:1.90
# 安装热重载工具
RUN cargo install cargo-watch

WORKDIR /app

# 预创建挂载点，避免权限问题
RUN mkdir -p /app/target && mkdir -p /usr/local/cargo

# 默认命令：监听并运行
CMD ["cargo", "watch", "-x", "run"]
```

#### docker-compose.yml (编排配置)
```yaml
services:
  api-gateway:
    build:
      context: .
      dockerfile: docker/Dockerfile.dev
    # 覆盖启动命令，指定运行的 binary
    command: ["cargo", "watch", "-x", "run --bin api-gateway-server"]
    volumes:
      # 1. 挂载源码 (实时同步)
      - .:/app
      # 2. 挂载共享编译产物 (核心加速点!)
      - cargo-target:/app/target
      # 3. 挂载依赖库缓存
      - cargo-cache:/usr/local/cargo

  iam-service:
    # ... 同样的配置，复用相同的 cargo-target
    volumes:
      - .:/app
      - cargo-target:/app/target
      - cargo-cache:/usr/local/cargo

volumes:
  cargo-target:  # 这里的魔法在于所有容器共享同一个 target 目录
    driver: local
  cargo-cache:
    driver: local
```

---

## 3. 优势总结

| 指标 | 传统 Docker 构建 | 本方案 (共享挂载) |
| :--- | :--- | :--- |
| **首次启动时间** | 慢 (需编译所有) | 慢 (需编译所有，但只需一次) |
| **二次启动时间** | **极慢** (代码变动导致层失效，全量重编) | **极快** (复用 target，增量编译 < 5s) |
| **磁盘占用** | 高 (每个镜像都有 target) | **低** (所有服务共享一份 target) |
| **依赖冲突** | 严格 (Docker 构建会报错) | 宽松 (只要本地能跑，容器就能跑) |
| **开发体验** | 修改代码 -> 等待构建 -> 重启容器 | 修改代码 -> 自动热跟新 (Hot Reload) |

## 4. 注意事项与坑

1.  **文件锁 (File Locking)**:
    *   Rust 的 Cargo 能够很好地处理并发编译锁。多个服务同时启动时，它们会排队等待编译公共依赖（如 `tokio`），而不会发生冲突损坏文件。
    *   **注意**: 如果宿主机也是 Linux 且挂载了宿主机的 `target` 目录，可能会因为 glibc 版本不同导致宿主机和容器内的 `cargo` 互相“打架”（指纹不一致导致频繁重编）。**建议使用独立的 Docker Volume (`cargo-target`) 而不是挂载宿主机 `target` 目录**，以此隔离宿主机环境和容器环境。

2.  **权限问题**:
    *   Docker 容器内默认是 `root`，写入 Volume 的文件也是 `root` 权限。如果挂载的是宿主机目录，可能会导致宿主机用户无法清理 `target`。使用 Docker Volume 可以规避这个问题。

3.  **生产环境构建**:
    *   本方案**仅限于开发环境**。
    *   生产环境 (`Dockerfile.prod`) 依然需要使用标准的 `COPY . .` + `cargo build --release` 流程，或者使用 `cargo-chef` 进行多阶段构建以减小镜像体积。

---

## 5. 结论

通过 **Docker Compose Volume 挂载** + **Cargo Watch** + **共享 Target 目录**，我们成功地在微服务架构下保留了 Monorepo 的开发效率。这是一套经过验证的、适合中大型 Rust 项目的高效开发模式。