rs-zero 0.2.21

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
# 排障手册

## 编译失败

症状:`cargo build`、`cargo test` 或 `cargo clippy` 失败。

原因:Rust toolchain 过旧、依赖未解析、代码或生成文件不符合 workspace 约束。

解决步骤:
1. 运行 `cargo metadata --format-version 1 --no-deps` 确认 workspace 可解析。
2. 运行 `cargo fmt --all -- --check` 检查格式。
3. 运行 `cargo clippy --workspace --all-targets -- -D warnings` 查看具体 lint。
4. 按第一个错误修复,不要同时修改无关模块。

验证方式:重新运行失败命令和 `cargo test --workspace`。

## CLI 拒绝覆盖文件

症状:命令返回 `already exists`。

原因:rs-zero 生成器默认保护已有文件。

解决步骤:
1. 确认目标目录是否已有生成结果。
2. 查看现有文件是否包含手写改动。
3. 确认要覆盖后添加 `--force`。

验证方式:重新运行对应 `api gen`、`model gen`、`rpc gen` 或 `api format` 命令。

## MQTT legacy envelope 冲突

症状:`rzcli mqtt gen` 返回 `legacy src/envelope.rs conflicts with generated src/envelope/ module`。

原因:旧版本生成的是单文件 `src/envelope.rs`,新版本生成 `src/envelope/mod.rs` 加 backend 文件。Rust 不能同时存在同名文件模块和目录模块,生成器会在写入前拒绝,避免部分输出。

解决步骤:
1. 如果旧 `src/envelope.rs` 有自定义 payload 解析逻辑,先迁移到 `src/envelope/custom.rs`。
2. 在 `.mqtt` 中设置 `@server(envelope: custom)`。
3. 删除旧 `src/envelope.rs`。
4. 重新运行 `rzcli mqtt gen`。

验证方式:确认生成了 `src/envelope/mod.rs`,并且后续重复运行不会覆盖 `src/envelope/custom.rs`。

## API parser 报 unknown type

症状:`api validate` 返回 `unknown request type` 或 `unknown response type`。

原因:route 引用了未定义的 type,或 import 文件没有被正确解析。

解决步骤:
1. 检查 `.api` 中 type 名称大小写。
2. 检查 `import "..."` 是否相对当前 `.api` 文件存在。
3. 用 `cargo test -p rs-zero-cli --test goctl_api_compat` 对照兼容 fixture。

验证方式:重新运行 `cargo run -p rs-zero-cli -- api validate -f <file.api>`。

## RPC import missing

症状:`rpc gen` 返回 missing import。

原因:proto import 路径既不能相对 root proto 解析,也不能相对当前 proto 文件解析。

解决步骤:
1. 检查 import 路径拼写。
2. 确认 sibling、subdir 或 transitive import 文件存在。
3. well-known import 如 `google/protobuf/timestamp.proto` 不需要本地文件。

验证方式:运行 `cargo test -p rs-zero-cli --test goctl_rpc_compat`。

## Model parser 无法识别 SQL

症状:`model gen` 返回 schema 不包含 `CREATE TABLE` 或 parse error。

原因:输入不是当前支持的 MySQL `CREATE TABLE` 子集,或 SQL 被迁移语句包裹。

解决步骤:
1. 先提取单个 `CREATE TABLE` 验证。
2. 检查字段、索引、comment/default/on-update 是否符合常见 MySQL DDL。
3. 对照 `tests/fixtures/goctl/model/user.sql`。

验证方式:运行 `cargo test -p rs-zero-cli --test goctl_model_compat`。

## 外部 adapter 测试被 ignored

症状:测试输出显示 etcd、OTLP 等 external placeholder ignored。

原因:默认测试不依赖外部服务,这是预期行为。

解决步骤:
1. 阅读 `examples/production-adapters/README.md`。
2. 启动对应 docker compose 或外部服务。
3. 显式运行 ignored/external 测试。

验证方式:外部服务就绪后运行对应 `cargo test --ignored ...` 命令。