# REST 手册
`rs-zero` 的 `rest` feature 提供 REST 服务常用边界：统一响应、REST 错误、服务配置和默认 middleware 组合点。
## 核心类型
- `ApiResponse<T>`：统一 JSON 响应。
- `PageResponse<T>`：分页响应。
- `RestConfig`：REST 服务配置。
- `RestServer`：封装 axum router 的服务启动 helper。
## 最小示例
```rust
use axum::{Router, routing::get};
use rs_zero::rest::{ApiResponse, RestConfig, RestServer};
}));
let addr = "127.0.0.1:8080".parse().unwrap();
RestServer::new(RestConfig::default(), router)
.serve_with_shutdown(addr, async {})
.await
.unwrap();
```
完整示例见 `examples/rest-hello/src/main.rs`。
## 韧性与指标
`RestConfig::middlewares` 可以显式开启 REST resilience 和 metrics。默认保持轻量兼容；生产服务可配置 request timeout、`max_concurrency`、route breaker、adaptive shedding 和 metrics registry。
```rust
use rs_zero::rest::{RestConfig, RestResilienceConfig};
let mut config = RestConfig::default();
config.middlewares.resilience = RestResilienceConfig {
breaker_enabled: true,
breaker_failure_threshold: 5,
breaker_reset_timeout: std::time::Duration::from_secs(30),
max_concurrency: Some(1024),
request_timeout: Some(std::time::Duration::from_secs(3)),
shedding_enabled: true,
shedding_max_in_flight: Some(1024),
shedding_min_request_count: 20,
shedding_max_latency: std::time::Duration::from_millis(250),
};
```
更完整的熔断、fallback、acceptable error、RPC unary 接入和指标说明见 [Resilience 手册](resilience.md)。
## Service group
需要在同一进程内同时运行 REST、RPC 或 worker 时，可用 `RestService` 接入 [`ServiceGroup`](service-group.md)：
```rust
use rs_zero::{
core::ServiceGroup,
rest::{RestConfig, RestServer, RestService},
};
let rest = RestService::new("api", addr, RestServer::new(RestConfig::default(), router));
let mut group = ServiceGroup::new();
group.add(rest);
group.start().await?;
# Ok::<(), Box<dyn std::error::Error>>(())
```
## 使用建议
- 业务 handler 返回统一响应，避免每个模块自定义错误格式。
- public path、JWT、timeout、request body limit 和 request-id 应在服务边界配置。
- 不要把 `axum::Router` 封装成不可扩展结构；rs-zero 保留 axum 原生扩展点。
## 相关测试
- `cargo test --test rest_integration`
- `cargo test --test resilience_rest_integration`