# RPC 服务教程
## 目标
运行 tonic health 示例，理解 `rs-zero` 的 `rpc` helper，并用 proto 生成 RPC skeleton。
## 运行 health 示例
```bash
cargo run -p rpc-hello
```
示例入口在 `examples/rpc-hello/src/main.rs`，proto 文件在 `examples/rpc-hello/proto/hello.proto`。
示例使用：
- `init_tracing(LogConfig::default())` 初始化 tracing。
- `serve_health_with_shutdown` 启动 tonic health server。
- `shutdown_signal()` 处理优雅停机。
## 生成 RPC skeleton
```bash
cargo run -p rs-zero-cli -- rpc gen \
-p examples/rpc-hello/proto/hello.proto \
-d target/generated
```
生成结果包含 tonic-oriented skeleton。当前 `rzcli rpc gen` 支持 proto3 的 package、option、import、message、service、rpc method 和 stream 标记子集。
## 当前边界
- RPC codegen 不替代 `protoc`。
- well-known imports 会被识别并保留语义，不会要求本地存在 `google/protobuf/*.proto`。
- local import 支持 sibling、subdir 和 transitive import。
- 生成代码是 Rust-first skeleton，业务逻辑需要用户补齐。
## 验证
```bash
cargo test --test rpc_integration
cargo test -p rs-zero-cli --test goctl_rpc_compat
```
## 常见问题
- `missing import`：检查 proto import 是否相对 root proto 或当前 proto 文件可解析。
- skeleton 中方法返回 unimplemented：这是预期结果，用户需要填充业务逻辑。
- 需要完整 prost build：在生成项目中接入自己的 `tonic-build`/`prost-build` 配置。