# 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 router = Router::new().route("/ready", get(|| async {
    ApiResponse::success("ok")
}));
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`
