# 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` 配置。
