# 快速开始

本指南帮助第一次接触 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)。
