rs-zero 0.2.21

Rust-first microservice framework inspired by go-zero engineering practices
Documentation
# Model/cache 手册

本手册是 `rzcli model gen` 的查阅入口。扩展说明保留在旧路径:[Model/cache generation](../model-cache.md)。

## 能力概览

`rzcli model gen` 从 SQL schema 生成:

- entity struct
- repository trait
- 可选 SQLx repository
- 受保护的 repository 扩展文件
- cache key helper
- 可选 Redis/L1/L2 cache alias
- 可选 cache-aside repository

## CLI

默认命令保持 MySQL/goctl SQL 子集和 SQLite SQLx backend:

```bash
cargo run -p rs-zero-cli -- model gen \
  -s examples/model-cache/schema.sql \
  -d target/generated \
  --with-sqlx \
  --with-redis-cache
```

显式选择 MySQL SQLx backend:

```bash
cargo run -p rs-zero-cli -- model gen \
  -s examples/model-cache/schema.sql \
  -d target/generated \
  --with-sqlx \
  --sqlx-backend mysql \
  --with-redis-cache
```

PostgreSQL schema 使用显式方言。未指定 `--sqlx-backend` 时,`--dialect postgres --with-sqlx` 默认生成 `rs_zero::db::PostgresDatabasePool`:

```bash
cargo run -p rs-zero-cli -- model gen \
  -s tests/fixtures/postgres/model/user.sql \
  -d target/generated \
  --dialect postgres \
  --with-sqlx \
  --with-redis-cache
```

## 生成的 repository

启用 `--with-sqlx` 后,每个 `src/repository/<table>.rs` 会包含:

- `Sqlx{Entity}Repository::new()`,repository 本身不持有 pool。
- 主键和唯一索引的 `find_by_*(&pool, ...)` 或 `find_by_*(&mut *tx, ...)` 方法,返回 `DatabaseResult<Option<Entity>>`。
- 普通非唯一索引的 `find_all_by_*(&pool, ...)` 或 `find_all_by_*(&mut *tx, ...)` 方法,返回 `DatabaseResult<Vec<Entity>>`。
- `save(executor, value)` 和主键 `delete_by_*(executor, ...)` 方法。
- `bind(&pool)` 适配器,用于需要 repository trait 的非事务路径。

生成 crate 会包含 `src/repository_ext.rs`,用于手写自定义查询和扩展方法。该文件只在缺失时创建,`model gen --force` 不会覆盖已有内容;不要直接修改生成的 `src/repository/<table>.rs` 文件。

`src/entity/mod.rs`、`src/repository/mod.rs` 和 `src/cache/mod.rs` 会 re-export 按表拆分的模块,因此 `use user_model::entity::Users`、`use user_model::repository::SqlxUsersRepository`、`use user_model::cache::user_by_id_key` 等路径保持可用。从旧生成结构迁移时,旧 `src/entity.rs`、`src/repository.rs`、`src/cache.rs` 不能与新目录共存;`rzcli model gen` 会拒绝生成并提示先删除或迁移这些旧聚合文件。

启用 `--with-sqlx --with-redis-cache` 后,还会生成 `Cached{Entity}Repository<S>`。它包装 SQLx repository、runtime pool 与 `rs_zero::cache::CacheAside<S>`:

- 主键和唯一索引读取走 cache-aside。
- `save` 后删除主键和唯一索引 key。
- `delete_by_*` 会删除主键 key;如删除前读取到实体,也会删除唯一索引 key。
- 普通非唯一索引不会生成单对象 cache key,避免把多行结果错误缓存为单条记录。

示例 wiring:

```rust
use rs_zero::cache::{CacheAside, CacheAsideConfig, LruCacheStore, TwoLevelCacheStore};
use rs_zero::cache::redis::{RedisCacheConfig, RedisCacheStore};
use user_model::repository::{CachedUserRepository, SqlxUserRepository};

let sql_repo = SqlxUserRepository::new();
let l1 = LruCacheStore::new(10_000)?;
let l2 = RedisCacheStore::new(RedisCacheConfig::default())?;
let cache = CacheAside::new(TwoLevelCacheStore::new(l1, l2), CacheAsideConfig::default());
let repo = CachedUserRepository::new(sql_repo, pool.clone(), cache, "user-service");
let user = repo.find_by_id(42).await?;
```

事务内写入直接使用 SQLx repository 和事务 executor:

```rust
let users = SqlxUserRepository::new();
let mut tx = pool.begin().await?;
users.save(&mut *tx, &user).await?;
tx.commit().await?;
```

不要在事务内使用 `Cached*Repository` 写入。事务成功提交后,再显式失效受影响的缓存 key,避免 commit 失败但缓存已变更。

## SQL parser 边界

支持常见 MySQL `CREATE TABLE` 子集,包含字段 metadata、table metadata、primary/unique/normal index 和复合索引。MySQL SQLx backend 需显式传 `--sqlx-backend mysql`,会生成 `rs_zero::db::MySqlDatabasePool`。

PostgreSQL 支持常见 `CREATE TABLE` 子集:双引号标识符、schema-qualified table name、`SERIAL` / `BIGSERIAL`、`GENERATED ... AS IDENTITY`、table-level constraint、`CREATE INDEX`、`COMMENT ON TABLE/COLUMN` 和常见字段类型映射。

完整 SQL grammar、数据库 introspection、迁移管理和 ORM 不是当前目标。

## 相关测试

- `cargo test -p rs-zero-cli --test model_codegen_integration`
- `cargo test -p rs-zero-cli --test model_adapter_codegen`
- `cargo test -p rs-zero-cli --test goctl_model_compat`
- `cargo test -p rs-zero-cli --test model_mysql_cli`
- `cargo test -p rs-zero-cli --test model_postgres_codegen`
- `cargo test -p rs-zero-cli --test model_postgres_cli`
- `cargo check -p rs-zero --no-default-features --features db-mysql,cache-redis`
- `cargo check -p rs-zero --no-default-features --features db-postgres,cache-redis`