Struct SchemaCache 

pub struct SchemaCache { /* private fields */ }

数据表字段缓存（对齐 PHP think\db\Fetch 字段缓存机制）

基于 Cache facade 实现表字段元数据的缓存，支持：

• 按 key 读写单表字段缓存
• remember_schema 缓存未命中时自动回源加载
• 按表名清除单表缓存
• 按标签批量清除所有表字段缓存

线程安全

SchemaCache 自身状态在构造后不可变（key_prefix、tag_name）， 所有并发安全由底层 Cache 保证。SchemaCache 是 Send + Sync。

缓存 key 格式

默认格式：schema_cache:<table_name>

可通过 SchemaCache::with_prefix 自定义前缀。

标签批量清除

所有通过 SchemaCache::set_schema 写入的缓存 key 自动注册到标签 （标签名 = key 前缀），SchemaCache::clear 通过标签一次性清除所有 表字段缓存，不影响 Cache 中的其他缓存。

Implementations

impl SchemaCache

pub fn new(cache: Arc<Cache>) -> Self

创建 SchemaCache（使用默认前缀 schema_cache）

参数

• cache: Cache facade 实例（Arc<Cache>）

pub fn with_prefix(cache: Arc<Cache>, prefix: impl Into<String>) -> Self

创建 SchemaCache（使用自定义缓存 key 前缀）

用于多实例隔离场景，如不同数据库连接使用不同前缀： schema_cache_db1:users、schema_cache_db2:users。

参数

• cache: Cache facade 实例
• prefix: 缓存 key 前缀（同时用作标签名）

pub fn cache_key(&self, table_name: &str) -> String

构造完整缓存 key（{prefix}:{table_name}）

对齐 PHP Fetch::getFieldCacheKey($tableName)。

参数

• table_name: 表名

pub fn get_schema( &self, table_name: &str, ) -> Result<Option<TableSchema>, SchemaCacheError>

从缓存获取表字段元数据（对齐 PHP Fetch::getFields 缓存读取）

参数

• table_name: 表名

返回

• Ok(Some(schema)): 缓存命中
• Ok(None): 缓存未命中或已过期

pub fn remember_schema<F>( &self, table_name: &str, loader: F, ) -> Result<TableSchema, SchemaCacheError>

where F: FnOnce(&str) -> Result<TableSchema, SchemaCacheError>,

缓存未命中时调用 loader 加载并缓存（对齐 PHP Fetch::getFields 回源逻辑）

1. 先从缓存读取，命中则直接返回
2. 未命中时调用 loader(table_name) 加载字段元数据
3. 将 loader 返回的 schema 写入缓存（TTL = None，永不过期）
4. 返回 schema

参数

• table_name: 表名
• loader: 回源加载闭包，接收表名，返回 Result<TableSchema, SchemaCacheError>

pub fn set_schema( &self, table_name: &str, schema: &TableSchema, ttl: Option<Duration>, ) -> Result<(), SchemaCacheError>

写入表字段缓存（对齐 PHP Fetch::setFieldCache）

缓存 key 自动注册到标签，支持 SchemaCache::clear 批量清除。

参数

• table_name: 表名
• schema: 表字段元数据
• ttl: 过期时间（None 永不过期，对齐 PHP 默认行为）

pub fn forget_schema(&self, table_name: &str) -> Result<(), SchemaCacheError>

清除单表字段缓存（对齐 PHP Cache::delete($key)）

参数

• table_name: 表名

pub fn clear(&self) -> Result<(), SchemaCacheError>

清除所有表字段缓存（对齐 PHP Cache::clear() 批量语义）

通过标签批量清除所有 set_schema 写入的缓存 key，不影响 Cache 中的 其他缓存（如业务缓存、Session 等）。

pub fn has_schema(&self, table_name: &str) -> Result<bool, SchemaCacheError>

判断表字段缓存是否存在（对齐 PHP Cache::has($key)）

参数

• table_name: 表名