rs-zero 0.2.6

Rust-first microservice framework inspired by go-zero engineering practices
Documentation

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 语法解析器。

能力速览

能力 crate / 文档 说明
REST runtime rs-zero feature rest / REST 手册 基于 axum、tower、tower-http，提供统一响应、错误和默认中间件边界。
RPC helper rs-zero feature rpc / RPC 手册 基于 tonic，提供 endpoint、request-id、deadline、retry、discovery 选择和 streaming 观测边界。
Resilience rs-zero feature resil / Resilience 手册 提供滑动窗口熔断、fallback/acceptable error、并发保护、REST 中间件和 RPC unary helper。
API DSL/codegen rzcli api（rs-zero-cli）/ API 教程 解析 go-zero 风格 .api，导出 OpenAPI，并生成 Rust REST skeleton。
Model/cache rzcli model（rs-zero-cli）/ Model 教程 从 MySQL/goctl 或显式 PostgreSQL SQL schema 生成 entity、repository、SQLx repository、cache key helper 和 cache-aside repository；可显式选择 MySQL/PostgreSQL backend。
Discovery rs-zero feature discovery / Discovery 手册 static、memory、DNS adapter，真实 etcd registry，以及真实 Kubernetes EndpointSlice discovery watcher。
Observability rs-zero feature observability / Observability 手册 统一 Prometheus registry，自动记录 HTTP/gRPC/SQL/Redis/cache/resilience 指标和 span，支持结构化日志、request id / trace id 关联、脱敏、采样和错误聚合。
Profiling rs-zero feature profiling / Observability 手册 可选 Pyroscope + pprof-rs adapter，默认 feature 不引入 profiling 依赖。
DB/cache adapters rs-zero features db-*、cache-redis / Cache 手册 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 手册 REST scaffold、API validate/format/openapi/gen、model gen、rpc gen、goctl compatibility matrix。
goctl compatibility 兼容矩阵 记录 API/model/RPC 的已支持、部分支持、未支持和有意差异。

快速开始

前置条件：安装 Rust stable toolchain。当前 MSRV 是 Rust 1.87，详见 API 稳定性。

cargo metadata --format-version 1 --no-deps
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

运行 REST 示例：

cargo run -p rest-hello
curl http://127.0.0.1:8080/ready

运行 RPC health 示例：

cargo run -p rpc-hello

使用 CLI 生成项目骨架：

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：

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，例如：

rs-zero = { version = "0.1", default-features = false, features = ["rest", "observability"] }

完整上手步骤见 快速开始。

文档导航

工作区结构

  • 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/：项目方案包和交付记录。

验证命令

提交前至少运行：

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。