rs-zero 0.2.6

# Feature matrix

本矩阵记录 `rs-zero` runtime crate 的 feature gate、外部服务边界和发布前验证命令。代码以 `Cargo.toml` 为准；本页由 `tests/api_stability.rs` 做关键漂移检查。

## 组合原则

- 默认 feature 适合本地开发和无外部服务 CI，不连接 Redis、etcd、Kubernetes、OTLP collector、Pyroscope、MySQL 或 PostgreSQL。
- adapter feature 必须显式启用，并通过 ignored external tests 或 `scripts/external-integration.sh` 验证真实服务。
- `--no-default-features` 是最小依赖检查入口；用户应只启用实际需要的能力。
- `db-mysql`、`db-postgres`、`cache-redis`、`discovery-etcd`、`discovery-kube`、`otlp`、`profiling` 不属于默认 feature。

## Runtime features

| Feature | 默认 | 依赖 feature | 外部服务 | 稳定等级 | 验证命令 |
| --- | --- | --- | --- | --- | --- |
| `default` | 是 | `core`, `rest`, `rpc`, `resil`, `cache`, `discovery`, `observability`, `db-sqlite` | 无 | 演进中；不应引入外部服务 | `cargo test --workspace` |
| `core` | 是 | 无 | 无 | 稳定面：配置、错误、日志、服务信息、shutdown、service group | `cargo check -p rs-zero --no-default-features --features core` |
| `rest` | 是 | `core` | 无 | 稳定面：`RestConfig`、`RestLayerStack`、router/service helper、`RestService`、响应类型 | `cargo check -p rs-zero --no-default-features --features rest` |
| `rpc` | 是 | `core` | 无 | 稳定面：client/server config、`RpcClientBuilder`、interceptor、health helper、`TonicService`、`RpcServerLayerStack`、unary resilience layer、streaming wrapper | `cargo check -p rs-zero --no-default-features --features rpc` |
| `resil` | 是 | 无 | 无 | 稳定面：breaker、timeout、concurrency、shedder、Linux CPU provider public API | `cargo test --test resilience_stress` |
| `cache` | 是 | 无 | 无 | 稳定面：cache trait、memory/LRU/two-level/cache-aside | `cargo test --test cache_stress` |
| `cache-redis` | 否 | `cache`、`resil` | Redis 可选；默认测试不连接 | 演进中；Redis cache、cluster、limiter rescue、distributed lock 行为需 external test | `cargo test -p rs-zero --features cache-redis --test cache_redis_cluster` |
| `discovery` | 是 | 无 | DNS 可选；默认无 registry 服务 | 稳定面：instance、trait、selector、static/memory/DNS adapter | `cargo test --test discovery_integration` |
| `discovery-etcd` | 否 | `discovery` | etcd v3 | 演进中；registry/watch 行为需 external test | `cargo test --no-default-features --features discovery-etcd --test discovery_etcd_codec` |
| `discovery-kube` | 否 | `discovery` | Kubernetes API | 演进中；watcher 行为需 external test | `cargo test --no-default-features --features discovery-kube --test discovery_kube_mapper` |
| `observability` | 是 | 无 | 无 | 稳定面：metrics registry、trace/log correlation helpers | `cargo test -p rs-zero --features observability,rest,rpc --test observability_trace_correlation` |
| `observability-prometheus-client` | 否 | `observability` | 无 | 演进中；成熟 Prometheus client adapter，默认不启用 | `cargo check -p rs-zero --no-default-features --features observability-prometheus-client` |
| `otlp` | 否 | `observability` | OTLP collector 可选 | 演进中；transport 行为需 external test | `cargo check -p rs-zero --no-default-features --features otlp` |
| `profiling` | 否 | `core` | Pyroscope 可选 | 实验性、opt-in；默认不启用，生产前需压测采样开销 | `cargo check -p rs-zero --features profiling` |
| `db` | 否 | 无 | 无 | 稳定面：SQLx pool config、health、transaction helper | `cargo check -p rs-zero --no-default-features --features db` |
| `db-sqlite` | 是 | `db` | 无 | 稳定面：SQLite pool helper | `cargo test --test db_integration` |
| `db-mysql` | 否 | `db` | MySQL 可选 | 演进中；真实 pool lifecycle 需 external test | `cargo check -p rs-zero --no-default-features --features db-mysql` |
| `db-postgres` | 否 | `db` | PostgreSQL 可选 | 演进中；真实 pool lifecycle 需 external test | `cargo check -p rs-zero --no-default-features --features db-postgres` |

## 已验证组合

| 组合 | 目的 | 命令 |
| --- | --- | --- |
| no-default | 最小依赖构建 | `cargo check -p rs-zero --no-default-features` |
| REST + RPC | 常用服务入口，无默认其它模块 | `cargo check -p rs-zero --no-default-features --features rest,rpc` |
| REST observability | REST Tower-first request context 与 metrics 边界 | `cargo check -p rs-zero --no-default-features --features rest,observability` |
| RPC resilience observability | RPC Tower-first server/client layer 与观测边界 | `cargo check -p rs-zero --no-default-features --features rpc,resil,observability` |
| service group | 同进程多服务生命周期 | `cargo test -p rs-zero --test service_group` |
| adapter matrix | 数据库、Redis、discovery、OTLP adapter 编译边界 | `cargo check -p rs-zero --no-default-features --features db-mysql,db-postgres,cache-redis,discovery-etcd,discovery-kube,otlp` |
| Redis distributed lock | Redis lock 编译和本地边界 | `cargo test -p rs-zero --features cache-redis --test redis_lock` |
| profiling | 可选 profiling 依赖边界 | `cargo check -p rs-zero --features profiling` |
| package | crates.io 打包边界 | `cargo package -p rs-zero --allow-dirty`、`cargo package -p rs-zero-cli --allow-dirty` |

## 外部集成

真实外部服务不进入默认 CI。需要验证生产 adapter 时运行：

```bash
scripts/external-integration.sh all
```

单项命令和环境变量见 [External integration CI](external-integration-ci.md)。Redis distributed lock 使用 `scripts/external-integration.sh redis-lock` 验证真实 Redis 获取、竞争、释放和 TTL 过期。