rs-zero 0.2.21

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
# API DSL 手册

本手册是查阅入口。完整语法说明保留在旧路径:[API DSL support](../api-dsl.md)。

## 能力概览

`rzcli api` 支持 go-zero 风格 `.api` 子集:

- `syntax = "v1"`
- `import "file.api"`
- `type` 和 field tags
- 多个同名 `service` 分块,用于拆分公开路由、JWT 路由、prefix/group 路由和 SSE 路由
- `@server` group、prefix、middleware、jwt、jwtTransition、sse
- `service`、`@handler`、HTTP route、request/response type
- HTTP method:`get`、`post`、`put`、`delete`、`patch`、`head`
- 无 request route、returns-only route、request + response route
- OpenAPI 导出
- 稳定格式化
- Rust REST skeleton 生成

## CLI

```bash
cargo run -p rs-zero-cli -- api validate -f examples/api-hello/hello.api
cargo run -p rs-zero-cli -- api format -f examples/api-hello/hello.api -o target/hello.api
cargo run -p rs-zero-cli -- api openapi -f examples/api-hello/hello.api -o target/openapi.json
cargo run -p rs-zero-cli -- api gen -f examples/api-hello/hello.api -d target/generated
```

## 相关测试

- `cargo test -p rs-zero-cli --test api_parser_integration`
- `cargo test -p rs-zero-cli --test api_openapi_integration`
- `cargo test -p rs-zero-cli --test api_codegen_integration`
- `cargo test -p rs-zero-cli --test goctl_api_compat`

## 生成行为

- 多 service 分块会生成到同一个 Rust REST 服务;分块 `prefix` 会进入 router path。
- `@server(jwt: Auth)` 按 service block 包裹路由,公开分块不会被 JWT middleware 保护。
- `@server(sse: true)` 生成 Axum SSE handler 和返回 `ReceiverStream<Result<Event, Infallible>>` 的 logic。
- SSE route 的 `returns (EventMessage)` 表示 `.api` response 类型会作为 JSON event payload。
- OpenAPI 会导出 `head` operation,并把 SSE response content type 标为 `text/event-stream`。

## 限制

rs-zero 关注 Rust-first 输入兼容,不承诺 goctl 输出逐字一致。一个解析入口中的多个 service block 必须同名;`jwtTransition` 会被解析和格式化,但还不会自动生成双 secret 过渡验证。