# REST 服务教程
## 目标
用 `rs-zero` 的 `rest` feature 启动一个可验证的 HTTP 服务，并理解统一响应、错误处理和服务边界。
## 前置条件
先完成 [快速开始](../getting-started.md) 的 workspace 验证。
## 运行现有示例
```bash
cargo run -p rest-hello
```
验证 ready endpoint：
```bash
curl http://127.0.0.1:8080/ready
```
示例入口在 `examples/rest-hello/src/main.rs`。它使用：
- `init_tracing(LogConfig::default())` 初始化 tracing。
- `ApiResponse::success("ok")` 返回统一响应。
- `RestServer::new(RestConfig::default(), router)` 启动 axum router。
- `shutdown_signal()` 处理优雅停机。
## 生成 REST skeleton
```bash
cargo run -p rs-zero-cli -- new-rest hello-service --dir target/generated
```
生成结果位于 `target/generated/hello-service/`。默认不会覆盖已存在文件。
## 关键约定
- REST 路由仍由 `axum::Router` 组织，rs-zero 不封死 axum 扩展点。
- 统一响应使用 `ApiResponse`，分页响应使用 `PageResponse`。
- 认证、超时、body limit、request-id 等能力在 `rs-zero` 的 `rest` 模块中以可组合边界提供。
- 业务错误应显式转换为 REST 错误，避免返回不可诊断的 panic。
## 验证
```bash
cargo test --test rest_integration
```
该测试覆盖 ready path、统一错误、JWT public path、request-id 和受保护路由。
## 常见问题
- 端口被占用：修改示例中的监听地址或停止占用进程。
- 返回格式不符合预期：检查 handler 是否返回 `ApiResponse` 或可被 axum 正确转换的类型。
- 认证失败：先确认 public path 配置和 JWT token 是否匹配测试中的配置。