koa3-demo/docs/views-refactor.md

视图系统重构说明

重构目标

解决原有 views.js 中间件职责混乱的问题，实现更清晰的关注点分离。

问题分析

原有架构问题

1. 职责混乱：视图中间件承担了数据获取、全局变量注入等非渲染职责
2. 层级耦合：基础设施层直接依赖应用层服务
3. 性能问题：每次渲染都重新获取站点配置，无缓存机制
4. 可测试性差：强耦合导致单元测试困难

重构方案

1. 视图中间件 (views.js)

新职责：

• 纯粹的模板渲染功能
• 基础上下文处理（路径、登录状态等框架级数据）
• 错误处理和日志记录

移除的职责：

• 业务数据获取（站点配置、用户信息等）
• 复杂的上下文构建
• 服务层调用

2. 上下文中间件 (context.js)

新增职责：

• 全局数据注入（$config、$site、$user等）
• 站点配置管理（带缓存）
• 通用上下文变量设置

特性：

• 5分钟内存缓存机制
• 优雅的错误降级
• 可配置的数据注入选项

架构改进

中间件执行顺序

1. 错误处理
2. 响应时间统计  
3. 会话管理
4. 上下文数据注入 ← 新增
5. 请求体解析
6. 视图渲染
7. HTTP缓存

数据流向

Context Middleware → ctx.state → Views Middleware → Templates

使用方式

在控制器中渲染视图

// 基础渲染（使用全局上下文）
await ctx.render('index/home')

// 传递额外数据
await ctx.render('user/profile', {
  title: '个人资料',
  activeTab: 'profile'
})

// 所有模板都可以访问：
// - currentPath: 当前路径
// - isLogin: 登录状态
// - $config: 应用配置
// - $site: 站点配置
// - $user: 用户信息

缓存管理

import { clearSiteConfigCache } from '@/infrastructure/http/middleware/context.js'

// 在站点配置更新后清空缓存
await siteConfigService.updateConfig(data)
clearSiteConfigCache()

优势

1. 职责清晰：每个中间件只负责自己的核心功能
2. 性能优化：站点配置缓存减少数据库查询
3. 可维护性：代码结构更清晰，便于维护和测试
4. 可扩展性：上下文中间件可以轻松扩展新的全局数据
5. 错误隔离：即使某个数据获取失败，也不会影响整个渲染流程

注意事项

1. 上下文中间件必须在认证中间件之后注册，以便正确获取用户信息
2. 视图中间件必须在上下文中间件之后注册，以便使用注入的数据
3. 站点配置缓存会在应用重启时自动清空
4. 如需修改缓存TTL，可在 context.js 中调整 CACHE_TTL 常量