# Model/cache 教程
## 目标
从 MySQL/goctl 或显式 PostgreSQL SQL schema 生成 Rust entity、repository trait、SQLx skeleton 和 cache key helper。
## 输入文件
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.rs`：Rust entity struct。
- `src/repository.rs`：repository trait 和可选 SQLx repository skeleton。
- `src/cache.rs`：cache key helper 和可选 Redis cache 标记。
- `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 命令会生成 `sqlx::PgPool` repository skeleton；MySQL backend 命令会生成 `sqlx::MySqlPool` repository skeleton。
## 支持的 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`
- `user_by_name_key`
复合索引会按列顺序生成 key segment。
## 验证
```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` 子集，或在文档中标注为未支持。