rs-zero 0.1.1

Rust-first microservice framework inspired by go-zero engineering practices
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# 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 手册](docs/manual/rest.md) | 基于 `axum`、`tower`、`tower-http`，提供统一响应、错误和默认中间件边界。 |
| RPC helper | `rs-zero` feature `rpc` / [RPC 手册](docs/manual/rpc.md) | 基于 `tonic`，提供 client endpoint、request-id interceptor 和 health server 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 trait、SQLx skeleton 和 cache key helper；可显式选择 MySQL/PostgreSQL backend。 |
| Discovery | `rs-zero` feature `discovery` / [Discovery 手册](docs/manual/discovery.md) | static、memory、DNS adapter，以及 etcd/Kubernetes adapter feature 边界。 |
| Observability | `rs-zero` feature `observability` / [Observability 手册](docs/manual/observability.md) | Prometheus 文本指标、REST metrics middleware、OpenTelemetry/OTLP 配置入口。 |
| DB/cache adapters | `rs-zero` features `db-*`、`cache-redis` / [生产 adapter](docs/manual/production-adapters.md) | SQLx SQLite helper、MySQL/PostgreSQL feature helper、cache trait、in-memory backend、Redis facade。 |
| 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。

```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
# PostgreSQL schema:
cargo run -p rs-zero-cli -- model gen -s tests/fixtures/postgres/model/user.sql -d target/generated --dialect postgres --with-sqlx
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", features = ["rest"] }
```

完整上手步骤见 [快速开始](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) / [API DSL](docs/manual/api-dsl.md) / [Model/cache](docs/manual/model-cache.md)
- 生产能力：[Discovery](docs/manual/discovery.md) / [Observability](docs/manual/observability.md) / [Production adapters](docs/manual/production-adapters.md) / [生产检查清单](docs/production-checklist.md)
- 开发建议：[最佳实践](docs/best-practices.md) / [排障手册](docs/troubleshooting.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` 一起运行。