# API 稳定性
rs-zero 仍处于 `0.1.x` 阶段。本页定义当前阶段的兼容承诺和发布纪律，避免把尚未达到 `1.0` 的能力误写成长期稳定 API。
## 版本策略
`rs-zero` 与 `rs-zero-cli` 使用同一个 workspace 版本。发布时遵循 Cargo semver 规则，并在 `0.x` 阶段采用更明确的兼容边界：
- patch 版本用于 bug fix、文档修正、非破坏性新增 API、默认不启用的新 feature、测试和内部实现改进。
- minor 版本可包含破坏性变更，但必须在 [迁移指南](migrations/README.md) 中记录动机、影响范围和升级步骤。
- 同一个 minor 线内尽量保持已文档化公共 API 兼容；如果必须破坏，优先推迟到下一个 minor。
- 不承诺 `1.0` 稳定性；达到 `1.0` 前，兼容性以本页和迁移指南为准。
## MSRV
当前 MSRV 是 Rust `1.87`，单一来源是 workspace `Cargo.toml` 的 `rust-version`。选择该版本是因为项目使用 Rust 2024 edition，且当前依赖集合中存在需要较新 stable 的 crate。
维护规则：
- MSRV 提升必须作为用户可见变更记录到迁移文档和 changelog。
- 发布前默认验证使用当前 stable toolchain；如果本机或 CI 未安装 MSRV toolchain，发布说明必须明确该轮未执行 `cargo +1.87 check`。
- 依赖升级导致 MSRV 提升时，先评估是否可降级依赖或延后升级；不能静默提高用户构建门槛。
推荐发布前检查：
```bash
cargo +1.87 check -p rs-zero --no-default-features
cargo +1.87 check -p rs-zero --no-default-features --features rest,rpc
cargo +1.87 check -p rs-zero --no-default-features --features db-mysql,db-postgres,cache-redis,discovery-etcd,discovery-kube,otlp
cargo +1.87 check -p rs-zero-cli
```
## 稳定面
| `rs-zero` 文档化公共 API | `0.1.x` 内尽量保持源代码兼容。新增方法、字段默认非破坏。 | 删除/重命名类型、函数、trait、module；更改公开字段类型；改变错误语义。 |
| `rs-zero-cli` / `rzcli` | 命令名、主要参数、退出码语义尽量保持兼容。 | 命令重命名、参数删除、退出码语义变化、脚本可解析输出变化。 |
| 生成代码模板 | 保持可编译和可迁移；允许内部组织优化。Tower-first skeleton 可移除旧胶水，但必须保留迁移说明。 | 生成项目依赖 feature、文件名、公开 trait 或 repository 方法签名变化。 |
| 配置结构 | 文档化 `*Config` 字段尽量只新增，不删除。 | 字段删除/重命名、默认值语义变化、单位变化。 |
| feature flags | feature 名称和依赖关系受 [feature matrix](feature-matrix.md) 约束。 | 删除 feature、默认 feature 变更、引入新的默认外部服务依赖。 |
| metrics/logging/tracing 字段 | 低基数标签和 documented log fields 尽量保持。 | 标签名、状态码/结果值枚举、trace/log correlation 字段变化。 |
| 错误类型 | 文档化错误枚举和转换语义尽量保持。 | 删除 variant、改变可观察错误分类或 tonic/http 映射。 |
| external adapters | feature gate、配置字段、失败策略需保持可预测。 | 默认 fail-open/fail-closed 改变、健康状态语义或 watch/registry 行为变化。 |
## 非承诺项
以下内容仍可在 `0.x` 阶段调整，不视为破坏稳定承诺，但影响用户时仍应写入 changelog：
- 未在 README、manual 或 rustdoc 作为用户入口说明的内部 helper。
- 测试 fixture、示例内部变量名和非脚本化的人类可读提示文案。
- 日志的时间戳、排序、空白、颜色和非结构化文本细节。
- 性能优化导致的内部缓存、重试或调度实现变化，但不能改变文档化错误语义。
- external integration 使用的本地端口、容器镜像 patch 版本和诊断输出。
## 发布前检查
每次发布或合并破坏性变更前至少运行：
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
cargo test --test api_stability
cargo test --test docs_links
cargo check -p rs-zero --no-default-features
cargo check -p rs-zero --no-default-features --features rest,rpc
cargo check -p rs-zero --no-default-features --features rest,observability
cargo check -p rs-zero --no-default-features --features rpc,resil,observability
cargo check -p rs-zero --no-default-features --features db-mysql,db-postgres,cache-redis,discovery-etcd,discovery-kube,otlp
cargo package -p rs-zero --allow-dirty
cargo package -p rs-zero-cli --allow-dirty
```
生产 adapter 的真实外部服务验证仍使用 opt-in 流程，详见 [External integration CI](external-integration-ci.md)。