name: yweb-infra description: YWeb 基础设施模块规范。在使用缓存（@cached）、异常处理（Err/register_exception_handlers）、日志（get_logger）、配置（AppSettings/YAML）、文件存储（本地/OSS/S3）、定时任务（Scheduler）、限流（setup_ratelimit）时使用。

YWeb 基础设施模块规范

缓存

• 使用 @cached(ttl=秒数) 装饰器缓存函数返回值
• 缓存 ORM 对象：使用 @cached(ttl=60, orm_model=Model) 自动将 detached 对象 merge 回当前 Session（load=False，零查询）
• 缓存键前缀：默认自动使用 module.qualname 全限定名，避免同名函数在 Redis 后端下的键冲突；也可手动指定 key_prefix="xxx"
• 自动缓存失效（双路径）：cache_invalidator.register(Model, func) 监听 ORM after_update/after_delete 事件
  • 路径 1 — key_extractor：实体变更时用 key_extractor(entity) 精确失效，适合 get_user(user_id) 等单实体查询
  • 路径 2 — 依赖追踪：缓存写入时自动扫描结果中的实体建立反向索引，实体变更时按索引精确失效，适合列表/组合查询
• M2M 关系变更失效：watch_relationships 参数默认 True，自动监听 ManyToMany 集合的 append/remove 事件触发失效
• 支持 Memory 和 Redis 两种后端
• 详细规范：yweb-core/docs/11_cache_guide.md

异常处理

• 使用 register_exception_handlers(app) 注册全局异常处理器
• 推荐使用 Err 快捷类抛出业务异常
• 业务规则违反使用标准 ValueError，不定义自定义异常类
• 支持验证约束模块（类似 .NET MVC 特性）
• 详细规范：yweb-core/docs/05_exception_handling.md

日志

• 使用 get_logger() 获取日志记录器（自动推断模块名）
• 支持时间+大小双重轮转
• 支持敏感数据过滤
• 详细规范：yweb-core/docs/04_log_guide.md

配置管理

• 使用 AppSettings 基础配置类
• 支持 YAML 文件 + 环境变量混合配置
• 使用配置加载器和配置管理器
• 详细规范：yweb-core/docs/02_config_guide.md

文件存储

• 支持本地存储、阿里云 OSS、AWS S3 / MinIO
• 支持文件验证
• 详细规范：yweb-core/docs/10_storage_guide.md

定时任务

• 基于 APScheduler 封装
• 支持 Builder 模式链式配置
• 支持失败重试、HTTP 任务、持久化
• 详细规范：yweb-core/docs/09_scheduler_guide.md

限流

• 基于 slowapi 轻度封装，使用 setup_ratelimit(app) 一站式初始化
• 路由中使用 slowapi 原生 @limiter.limit("10/minute") 装饰器
• 默认按 JWT user_id 限流，匿名时按 IP 限流（get_user_or_ip）
• 超限返回 yweb 统一 429 格式（Resp.TooManyRequests()）
• 支持事件订阅：rate_limit_event_bus.subscribe(callback) 可将限流事件记录到数据库
• 配置集成：AppSettings.ratelimit（RateLimitSettings），环境变量前缀 YWEB_RL_
• 支持 Memory 和 Redis 两种存储后端
• 可选依赖：pip install yweb[ratelimit]
• 详细规范：yweb-core/docs/14_ratelimit_guide.md

快速开始

• 框架安装与基础示例：yweb-core/docs/01_quickstart.md

工作流程

1. 使用任何基础设施模块前，先阅读对应文档
2. 缓存使用：阅读 11_cache_guide.md，重点关注 TTL 设置和失效策略
3. 异常处理：阅读 05_exception_handling.md，了解 Err 快捷类和验证约束
4. 日志使用：阅读 04_log_guide.md，使用 get_logger() 而非 logging.getLogger()
5. 配置相关：阅读 02_config_guide.md，了解 YAML + 环境变量的优先级
6. 限流使用：阅读 14_ratelimit_guide.md，了解 setup_ratelimit 初始化和事件订阅