# 0.1.x 迁移基线

`0.1.x` 是 rs-zero 的早期生产能力成形阶段。项目尚未承诺 `1.0` 稳定，但从本基线开始，用户可按 [API 稳定性](../api-stability.md) 文档判断哪些变化需要迁移说明。

## 当前基线

- workspace 版本：`0.2.3`
- Rust edition：`2024`
- MSRV：Rust `1.87`
- 发布 crate：`rs-zero`、`rs-zero-cli`
- CLI binary：`rzcli`
- 默认 runtime features：`core`、`rest`、`rpc`、`resil`、`cache`、`discovery`、`observability`、`db-sqlite`
- 外部 adapter features：`cache-redis`、`discovery-etcd`、`discovery-kube`、`otlp`、`profiling`、`db-mysql`、`db-postgres`

## 升级检查清单

升级到新的 `0.1.x` patch 版本时：

1. 阅读 changelog 和本目录新增条目。
2. 运行项目默认测试：`cargo test --workspace`。
3. 如使用 no-default features，复跑自己的 feature 组合。
4. 如使用外部 adapter，按 [External integration CI](../external-integration-ci.md) 运行对应 ignored tests。
5. 如依赖生成代码，重新生成到临时目录并对比公开 trait、repository 方法和 Cargo feature。

## 已记录迁移条目

### RPC 生成代码切换到 Tower-first skeleton

- 影响版本：`0.2.3` 后续 patch
- 影响范围：generated code / observability / resilience
- 破坏性：否。旧 helper 仍保留，但新生成代码形态变化。
- 旧行为：`rzcli rpc gen` 生成 `RpcRequestParts`、`*_with_parts`，并在 unary method 中显式调用 `RpcResilienceLayer::run_unary*`。
- 新行为：`rzcli rpc gen` 默认导出并使用 `RpcServerLayerStack`，service 内只保留业务 `handle_*`，metadata、观测和韧性由 tonic server 外层 Tower layer 处理。
- 迁移步骤：
  1. 旧项目可以继续编译，不需要立即修改。
  2. 重新生成 RPC skeleton 后，在 tonic server builder 上挂载 `service.server_layer_stack().into_layer()`。
  3. trait method 内可直接 `request.into_inner()`，不再需要手动构造 `RpcRequestParts`。
- 验证命令：`cargo test -p rs-zero-cli --test rpc_codegen_integration`

## 未来条目模板

复制下面模板记录破坏性或需用户操作的变化：

```markdown
### 标题

- 影响版本：`0.1.x` -> `0.1.y`
- 影响范围：crate API / CLI / generated code / config / feature / observability
- 破坏性：是 / 否
- 旧行为：...
- 新行为：...
- 迁移步骤：
  1. ...
  2. ...
- 验证命令：`cargo test ...`
```
