rs-zero 0.2.12

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
# API codegen 教程

## 目标

使用 go-zero 风格 `.api` 文件完成校验、格式化、OpenAPI 导出和 Rust REST skeleton 生成。

## 输入文件

示例文件:`examples/api-hello/hello.api`。

支持的核心语法见 [API DSL 手册](../manual/api-dsl.md)。goctl 兼容边界见 [goctl 兼容矩阵](../goctl-compatibility.md)。

## 校验 `.api`

```bash
cargo run -p rs-zero-cli -- api validate -f examples/api-hello/hello.api
```

校验会检查 service、handler、HTTP method、request/response type 引用等语义。

## 格式化 `.api`

```bash
cargo run -p rs-zero-cli -- api format \
  -f examples/api-hello/hello.api \
  -o target/hello.formatted.api
```

格式化会保留 import、docs、server options、handler 和 field tags。输出文件已存在时默认拒绝覆盖,需要覆盖时添加 `--force`。

## 导出 OpenAPI

```bash
cargo run -p rs-zero-cli -- api openapi \
  -f examples/api-hello/hello.api \
  -o target/openapi.json
```

OpenAPI 导出会使用 route path、path/query/header/form tags、response schema、`@server` prefix 和 group metadata。
`head` route 会导出为 OpenAPI `head` operation;`@server(sse: true)` 分块的响应会导出为 `text/event-stream`。

## 生成 REST skeleton

```bash
cargo run -p rs-zero-cli -- api gen \
  -f examples/api-hello/hello.api \
  -d target/generated
```

生成结果是 Rust-first REST skeleton,不承诺与 goctl 生成的 Go 文件逐字一致。

## 多 service 分块

同一个 `.api` 入口可以写多个同名 service block,用于拆分不同路由边界:

```api
service user-api {
    @handler PingHandler
    get /ping returns (PingReply)
}

@server(jwt: Auth, prefix: /api)
service user-api {
    @handler ProfileHandler
    get /profile returns (ProfileReply)
}
```

生成的 router 会把两个 block 合并到同一个 Rust 服务里。JWT middleware 只包裹带 `@server(jwt: Auth)` 的 block,公开 block 保持公开。

## Route 形态

支持带 request、无 request、returns-only 和 `head`:

```api
service user-api {
    @handler HealthHandler
    head /health

    @handler PingHandler
    get /ping returns (PingReply)

    @handler CreateHandler
    post /users(CreateReq) returns (CreateReply)
}
```

无 request route 生成的 handler 没有 extractor 入参。`path` tag 生成 `Path`,`query` / `form` tag 生成 `Query`,其余 request 默认生成 `Json`。

## SSE streaming skeleton

`@server(sse: true)` 标记一个 service block 内的 route 为 SSE endpoint:

```api
type EventMessage {
    Message string `json:"message"`
}

@server(prefix: /events, group: stream, sse: true)
service user-api {
    @handler EventsHandler
    get /feed returns (EventMessage)
}
```

生成的 handler 返回 `impl IntoResponse`,使用 Axum `Sse::new(stream).keep_alive(...)`。对应 logic 返回 `ReceiverStream<Result<Event, Infallible>>`,内部 starter skeleton 使用 `tokio::sync::mpsc::channel(16)`、`tokio::spawn`、`tokio::time::interval` 和 `ReceiverStream::new(rx)`。`EventMessage` 是 `.api` 中定义的 response 类型,会作为 `Event::json_data(...)` 的默认 payload 类型。

实际业务中应把默认 tick/payload 循环替换为领域事件来源,并明确断连、背压和 shutdown 行为。

## 验证

```bash
cargo test -p rs-zero-cli --test goctl_api_compat
cargo test -p rs-zero-cli --test api_codegen_integration
cargo test -p rs-zero-cli api
```

## 常见问题

- `unknown request type`:route 引用了未定义的 type,检查 `.api` 中 type 名称。
- `missing import`:相对 import 文件不存在,检查路径是否相对当前 `.api` 文件。
- `target file already exists`:CLI 默认不覆盖文件;确认无误后使用 `--force`。