# 快速开始
本指南帮助第一次接触 rs-zero 的用户在本地完成一次可验证闭环。
## 1. 前置条件
- Rust stable toolchain。
- `cargo` 可用。
- Docker、etcd、Kubernetes、Redis、OTLP collector 都是可选项；默认测试不会连接这些外部服务。
## 2. 验证 workspace
```bash
cargo metadata --format-version 1 --no-deps
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
```
如果这些命令通过，说明本地 toolchain 和 workspace 基本可用。
## 3. 运行 REST 示例
```bash
cargo run -p rest-hello
```
另开终端验证：
```bash
curl http://127.0.0.1:8080/ready
```
预期返回统一 JSON 响应，`data` 为 `ok`。
## 4. 运行 RPC health 示例
```bash
cargo run -p rpc-hello
```
该示例启动 tonic health server，用于验证 RPC 服务启动、tracing 初始化和优雅停机路径。
## 5. 使用 CLI 生成 skeleton
发布安装方式：
```bash
cargo install rs-zero-cli --locked
rzcli -v
```
仓库开发时也可以通过 `cargo run -p rs-zero-cli -- ...` 直接运行。
生成 REST 服务骨架：
```bash
cargo run -p rs-zero-cli -- new-rest hello-service --dir target/generated
```
验证并生成 API skeleton：
```bash
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 -- api gen -f examples/api-hello/hello.api -d target/generated
```
从 SQL schema 生成 model/cache skeleton：
```bash
cargo run -p rs-zero-cli -- model gen \
-s examples/model-cache/schema.sql \
-d target/generated \
--with-sqlx \
--with-redis-cache
```
从 proto 生成 RPC skeleton：
```bash
cargo run -p rs-zero-cli -- rpc gen \
-p examples/rpc-hello/proto/hello.proto \
-d target/generated
```
CLI 默认拒绝覆盖已有文件；确认需要覆盖时使用 `--force`。
生成项目默认只依赖 `rs-zero` 运行时 crate。需要数据库、Redis、etcd、Kubernetes 或 OTLP 时，通过 `rs-zero` feature 开启对应能力。
## 6. 下一步
- 想开发 HTTP 服务：阅读 [REST 服务教程](tutorials/rest-service.md)。
- 想从 `.api` 生成代码：阅读 [API codegen 教程](tutorials/api-codegen.md)。
- 想开发 tonic 服务：阅读 [RPC 服务教程](tutorials/rpc-service.md)。
- 想生成 model/cache skeleton：阅读 [Model/cache 教程](tutorials/model-cache.md)。
- 准备上线：阅读 [生产检查清单](production-checklist.md)。