rs-zero 0.2.19

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

## 目标

从 MySQL/goctl 或显式 PostgreSQL SQL schema 生成 Rust entity、repository trait、SQLx repository、cache key helper 和可选 cache-aside repository。

## 输入文件

MySQL/goctl 示例 schema:`examples/model-cache/schema.sql`。PostgreSQL 示例 schema:`tests/fixtures/postgres/model/user.sql`。

## 生成 skeleton

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

生成结果包含:

- `src/entity/<table>.rs`:Rust entity struct。
- `src/repository/<table>.rs`:repository trait、可选 SQLx repository 和可选 cached repository。
- `src/repository_ext.rs`:手写扩展文件,`model gen --force` 不覆盖。
- `src/cache/<table>.rs`:主键/唯一索引 cache key helper;启用 Redis cache 时 `src/cache/mod.rs` 还会导出 Redis/L1/L2 cache alias。
- `Cargo.toml`、`README.md`。

## PostgreSQL schema

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

显式 MySQL backend:

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

PostgreSQL 命令会生成接受 `rs_zero::db::PostgresDatabasePool` executor 的 repository;MySQL backend 命令会生成接受 `rs_zero::db::MySqlDatabasePool` executor 的 repository。SQLx repository 本身不持有 pool。

## 支持的 SQL 子集

默认 parser 面向常见 MySQL `CREATE TABLE` 子集,覆盖:

- 字段名、SQL 类型、nullable、primary key、unique。
- `DEFAULT`、`COMMENT`、`AUTO_INCREMENT`、`ON UPDATE`。
- table charset、collation、comment。
- primary key、unique key、normal index、复合索引。

MySQL backend 支持 unsigned integer、decimal、timestamp/datetime/date、json 和 blob/binary 等常见类型映射。PostgreSQL 显式方言覆盖双引号标识符、schema-qualified table、identity、`CREATE INDEX`、`COMMENT ON` 和常见 PostgreSQL 类型。

完整边界见 [Model/cache 手册](../manual/model-cache.md)。

## Cache key 命名

cache helper 使用稳定命名,例如:

- `user_by_id_key`
- `user_by_email_mobile_key`

普通非唯一索引不会生成单对象 cache key;它们在 repository 中以 `find_all_by_*` 形式保留为 DB 查询。复合唯一索引会按列顺序生成 key segment。

## Cache-aside repository

同时启用 `--with-sqlx --with-redis-cache` 时,生成的 `Cached{Entity}Repository<S>` 会使用 `CacheAside<S>`:

- `find_by_id` 和唯一索引 `find_by_*` 先查缓存,miss 后读取 SQLx repository 并写回缓存。
- `save` 和 `delete_by_*` 会删除相关主键/唯一索引 key。
- L1 可使用 `LruCacheStore`,L2 可使用 `RedisCacheStore` 或 `RedisShardedCacheStore`,也可通过 `TwoLevelCacheStore` 组合。

SQLx 直接调用示例:

```rust
let users = SqlxUsersRepository::new();
let user = users.find_by_id(&pool, 42).await?;

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

Cached repository 绑定 pool,用于普通 cache-aside 读写:

```rust
let users = SqlxUsersRepository::new();
let repo = CachedUsersRepository::new(users, pool.clone(), cache, "user-service");
let user = repo.find_by_id(42).await?;
```

事务内写入不要走 `Cached*Repository`。应先用 `Sqlx*Repository` 和 `&mut tx` 完成 DB 事务,commit 成功后再显式失效缓存。

## 验证

```bash
cargo test -p rs-zero-cli --test model_codegen_integration
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
```

## 常见问题

- `schema does not contain a CREATE TABLE statement`:输入 SQL 中没有可解析的 `CREATE TABLE`。
- 生成文件已存在:默认拒绝覆盖;确认需要覆盖时使用 `--force`。
- 复杂 MySQL 或 PostgreSQL 语法无法解析:先缩小到当前支持的 `CREATE TABLE` 子集,或在文档中标注为未支持。