# rs-zero
rs-zero 是一个 Rust-first 微服务框架，借鉴 go-zero 的工程默认值，同时使用 Rust 生态中稳定的运行时、Web、RPC、观测和代码生成能力。它不是 go-zero 的逐行移植，也不承诺生成 Go 代码的字节级兼容。
适合使用 rs-zero 的场景：
- 想用 Rust 快速搭建 REST 或 RPC 服务。
- 需要统一响应、错误、配置、tracing、优雅停机、超时、限流和熔断等默认能力。
- 希望用 go-zero 风格 `.api` 或 SQL schema 生成 Rust-first skeleton。
- 希望按模块接入 discovery、observability、database、cache 和生产 adapter。
不适合的场景：
- 需要完整替代 `goctl` 的所有语言生成器。
- 需要默认测试连接真实数据库、Redis、etcd、Kubernetes 或 OTLP collector。
- 需要完整 protobuf 编译链或完整 MySQL 语法解析器。
## 能力速览
| REST runtime | `rs-zero` feature `rest` / [REST 手册](docs/manual/rest.md) | 基于 `axum`、`tower`、`tower-http`，提供统一响应、错误和默认中间件边界。 |
| RPC helper | `rs-zero` feature `rpc` / [RPC 手册](docs/manual/rpc.md) | 基于 `tonic`，提供 endpoint、request-id、deadline、retry、discovery 选择和 streaming 观测边界。 |
| Resilience | `rs-zero` feature `resil` / [Resilience 手册](docs/manual/resilience.md) | 提供滑动窗口熔断、fallback/acceptable error、并发保护、REST 中间件和 RPC unary helper。 |
| API DSL/codegen | `rzcli api`（`rs-zero-cli`）/ [API 教程](docs/tutorials/api-codegen.md) | 解析 go-zero 风格 `.api`，导出 OpenAPI，并生成 Rust REST skeleton。 |
| Model/cache | `rzcli model`（`rs-zero-cli`）/ [Model 教程](docs/tutorials/model-cache.md) | 从 MySQL/goctl 或显式 PostgreSQL SQL schema 生成 entity、repository、SQLx repository、cache key helper 和 cache-aside repository；可显式选择 MySQL/PostgreSQL backend。 |
| Discovery | `rs-zero` feature `discovery` / [Discovery 手册](docs/manual/discovery.md) | static、memory、DNS adapter，真实 etcd registry，以及真实 Kubernetes EndpointSlice discovery watcher。 |
| Observability | `rs-zero` feature `observability` / [Observability 手册](docs/manual/observability.md) | 统一 Prometheus registry，自动记录 HTTP/gRPC/SQL/Redis/cache/resilience 指标和 span，支持结构化日志、request id / trace id 关联、脱敏、采样和错误聚合。 |
| Profiling | `rs-zero` feature `profiling` / [Observability 手册](docs/manual/observability.md#profiling-与-pyroscope) | 可选 Pyroscope + pprof-rs adapter，默认 feature 不引入 profiling 依赖。 |
| DB/cache adapters | `rs-zero` features `db-*`、`cache-redis` / [Cache 手册](docs/manual/cache.md) | SQLx SQLite/MySQL/PostgreSQL helper、cache trait、in-memory/L1 LRU/two-level cache、真实 Redis store、Redis 分片和 cache-aside helper。 |
| CLI | `rzcli`（`rs-zero-cli` crate）/ [CLI 手册](docs/manual/cli.md) | REST scaffold、API validate/format/openapi/gen、model gen、rpc gen、goctl compatibility matrix。 |
| goctl compatibility | [兼容矩阵](docs/goctl-compatibility.md) | 记录 API/model/RPC 的已支持、部分支持、未支持和有意差异。 |
## 快速开始
前置条件：安装 Rust stable toolchain。当前 MSRV 是 Rust `1.87`，详见 [API 稳定性](docs/api-stability.md)。
```bash
cargo metadata --format-version 1 --no-deps
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
运行 REST 示例：
```bash
cargo run -p rest-hello
curl http://127.0.0.1:8080/ready
```
运行 RPC health 示例：
```bash
cargo run -p rpc-hello
```
使用 CLI 生成项目骨架：
```bash
cargo run -p rs-zero-cli -- new-rest hello-service --dir target/generated
cargo run -p rs-zero-cli -- api validate -f examples/api-hello/hello.api
cargo run -p rs-zero-cli -- api openapi -f examples/api-hello/hello.api -o target/openapi.json
cargo run -p rs-zero-cli -- model gen -s examples/model-cache/schema.sql -d target/generated --with-sqlx --with-redis-cache
# MySQL backend:
cargo run -p rs-zero-cli -- model gen -s examples/model-cache/schema.sql -d target/generated --with-sqlx --sqlx-backend mysql --with-redis-cache
# PostgreSQL schema:
cargo run -p rs-zero-cli -- model gen -s tests/fixtures/postgres/model/user.sql -d target/generated --dialect postgres --with-sqlx --with-redis-cache
cargo run -p rs-zero-cli -- rpc gen -p examples/rpc-hello/proto/hello.proto -d target/generated
```
安装 CLI 后可直接使用 `rzcli`：
```bash
cargo install rs-zero-cli --locked
# 本仓库开发时可使用本地路径安装：
cargo install --path crates/rs-zero-cli --locked
rzcli -v
rzcli --help
rzcli model gen -s examples/model-cache/schema.sql -d target/generated --with-sqlx
```
生成项目默认只依赖 `rs-zero` 运行时 crate，例如：
```toml
rs-zero = { version = "0.1", default-features = false, features = ["rest", "observability"] }
```
完整上手步骤见 [快速开始](docs/getting-started.md)。
## 文档导航
- 新手入口：[文档总览](docs/README.md) / [快速开始](docs/getting-started.md)
- 教程：[REST 服务](docs/tutorials/rest-service.md) / [API codegen](docs/tutorials/api-codegen.md) / [RPC 服务](docs/tutorials/rpc-service.md) / [Model/cache](docs/tutorials/model-cache.md)
- 用户手册：[CLI](docs/manual/cli.md) / [REST](docs/manual/rest.md) / [RPC](docs/manual/rpc.md) / [Resilience](docs/manual/resilience.md) / [API DSL](docs/manual/api-dsl.md) / [Model/cache](docs/manual/model-cache.md) / [Cache](docs/manual/cache.md)
- 生产能力：[Discovery](docs/manual/discovery.md) / [Observability](docs/manual/observability.md) / [Production adapters](docs/manual/production-adapters.md) / [External integration CI](docs/external-integration-ci.md) / [生产检查清单](docs/production-checklist.md)
- 开发建议：[最佳实践](docs/best-practices.md) / [排障手册](docs/troubleshooting.md)
- 稳定性与迁移：[API 稳定性](docs/api-stability.md) / [Feature matrix](docs/feature-matrix.md) / [迁移指南](docs/migrations/README.md)
- 兼容与路线图：[go-zero 映射](docs/go-zero-mapping.md) / [goctl 兼容矩阵](docs/goctl-compatibility.md) / [MVP roadmap](docs/mvp-roadmap.md)
## 工作区结构
- `src/`：`rs-zero` 运行时模块，包括 `core`、`rest`、`rpc`、`resil`、`db`、`cache`、`discovery`、`observability`。
- `crates/rs-zero-cli/`：`rzcli` 工具链 crate，内聚 API/model/RPC parser 和 codegen。
- `examples/`：可运行示例和 adapter 示例。
- `tests/`：workspace 级集成测试和兼容测试。
- `docs/`：教程、手册、最佳实践、排障和兼容文档。
- `.helloagents/plans/`：项目方案包和交付记录。
## 验证命令
提交前至少运行：
```bash
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
文档链接和敏感信息检查由 `tests/docs_links.rs` 覆盖，会随 `cargo test --workspace` 一起运行。生产 adapter 的真实 Redis、etcd、Kubernetes、OTLP、Pyroscope、MySQL 和 PostgreSQL 验证使用独立 external integration 流程：`scripts/external-integration.sh all`，详见 [External integration CI](docs/external-integration-ci.md)。