简介
本文件系统性说明 DouPHP 模板数据绑定机制，覆盖控制器向模板传递数据、模板变量访问语法、数据验证与类型转换、缓存策略（编译缓存与运行时上下文）、大数据渲染优化以及常见问题定位。文档以代码为依据，结合流程图与类图帮助读者快速掌握从控制器到模板渲染的完整链路。
项目结构
DouPHP 的前台视图响应由前台 BaseController 统一构造 ViewResponse，并委托给模板渲染器接口 TemplateRendererInterface；默认实现为 DouView，负责变量作用域管理、模板解析编译、运行期上下文 RenderContext 维护与子模板包含等。模板源位于 theme 目录，使用 .dwt/.htm/.html/.tpl 扩展名，并通过 {include} 组合页面片段。
graph TB
A["前台控制器<br/>BaseController::view()"] --> B["视图响应<br/>ViewResponse"]
B --> C["模板渲染器接口<br/>TemplateRendererInterface"]
C --> D["引擎实现<br/>DouView"]
D --> E["编译流水线<br/>DouViewCompiler"]
D --> F["运行期上下文<br/>RenderContext"]
D --> G["模板资源<br/>theme/*.dwt"]核心组件
- 模板渲染器接口：定义 assign/fetch 最小契约，供控制器与门面调用。
- 引擎 DouView：维护模板变量作用域 vars、全局 HTML 转义开关、编译缓存与编译器实例，提供 fetch/display/renderResource。
- 运行期上下文 RenderContext：承载 $ctx->vars、循环状态 loops/loopVarmap、过滤器 filter、子模板 includeTemplate。
- 编译器 DouViewCompiler：词法→语法→代码生成，注册内置标签编译器（echo/if/foreach/include/assign/url/strip/literal/comment/php/delim/break/continue）。
- 词法器 Lexer：单趟扫描模板源，识别注释、literal、php、普通标签，输出 TokenStream。
架构总览
控制器通过 view() 将“动作专属数据 + 布局公共变量”合并后交给 ViewResponse，后者按 TemplateRendererInterface 约定调用引擎 fetch。引擎在首次或需要重编时读取模板源，经 Prefilter 与 DouViewCompiler 产出 PHP 编译产物，随后 include 执行，期间通过 RenderContext 暴露变量与作用域能力。
sequenceDiagram
participant C as "控制器"
participant V as "ViewResponse"
participant I as "TemplateRendererInterface"
participant E as "DouView"
participant X as "RenderContext"
participant T as "模板文件"
C->>V : 构造(模板名, 数据+layoutVars)
V->>I : fetch(模板名)
I->>E : fetch(模板名)
E->>E : renderResource(模板名)
E->>E : 解析/编译(必要时)
E->>X : 绑定$ctx->vars
E->>T : include 编译产物
T-->>E : 输出HTML
E-->>V : 返回HTML
V-->>C : 响应详细组件分析
控制器到模板的数据传递
- 前台 BaseController::view() 将“动作数据”与“布局公共变量”数组合并（动作数据优先），再交由 ViewResponse 渲染。
- 模板引擎通过 assign 接收键值对，并在 fetch 时将 vars 引用注入 RenderContext，供模板访问。
flowchart TD
Start(["控制器方法"]) --> Merge["合并数据<br/>actionData + layoutVars"]
Merge --> ViewResp["构造 ViewResponse"]
ViewResp --> Fetch["调用引擎 fetch(模板)"]
Fetch --> Assign["引擎 assign(vars)"]
Assign --> Render["渲染模板"]
Render --> End(["返回HTML"])模板变量访问语法
- 简单变量：{$var}
- 数组索引：{$arr['key']} / {$arr[0]}
- 对象属性与方法：{$obj->prop} / {$obj->method()}
- 过滤器：{$value|filter:param}
- 循环与 @ 属性：{foreach ...} 中可使用 {$item@iteration/index/total/first/last/show}
- 条件与包含：{if ...} / {include file="..."}
上述语法由编译器与运行期上下文共同支持：
- 表达式与标签由 DouViewCompiler 的词法/语法/代码生成管线处理。
- 循环 @ 属性由 RenderContext::loopProp 提供运行时取值。
- 过滤器由 RenderContext::filter 分发到 FilterRegistry。
数据模型绑定与上下文传递
- 控制器将业务模型（如用户、商品）转为数组或对象后放入 action data，最终进入 $ctx->vars。
- 子模板通过 {include} 传入局部变量，RenderContext::includeTemplate 会保存父作用域、合并子变量、渲染后再恢复，避免污染父作用域。
- 可通过 assign 在模板内动态设置变量，或在 include 时指定 assignVar 捕获输出到变量。
数据验证与类型转换
- 模板层不直接承担复杂校验逻辑，建议在控制器或服务层完成输入校验与类型转换，再将干净数据传入模板。
- 模板侧可借助过滤器进行轻量格式化（如日期、金额），但不应替代服务端校验。
- 建议开启全局 HTML 转义（setEscapeHtml）防止 XSS，或在输出敏感字段时使用安全过滤器。
数据缓存策略
- 编译缓存：DouView 基于 CompileCache 判断是否需要重编译，依据源文件时间、force_compile、compile_check 与 COMPILE_REVISION/VERSION 头。
- 预加载：可在控制器或服务层预先查询并缓存结果（如 Redis/Memcached），模板仅消费已准备好的数据。
- 局部缓存：通过 {include} 拆分模块，减少重复渲染；或使用 assignVar 捕获片段输出复用。
- 全局缓存：站点级配置（如导航、SEO 信息）在服务层缓存，模板只读。
大数据量渲染优化
- 分页与限制：在控制器层限制列表大小，避免一次性加载过多数据。
- 懒加载与按需渲染：首屏只渲染关键内容，其余通过异步或延迟加载。
- 片段化模板：将大页面拆分为多个 {include} 片段，提升可维护性与缓存命中率。
- 避免在模板中进行昂贵计算：将计算下沉至服务层，模板只做展示。
- 合理使用过滤器：避免在循环中对每个元素做高开销处理。
依赖关系分析
- BaseController 依赖 TemplateRendererInterface，解耦具体引擎实现。
- DouView 依赖 DouViewCompiler、RenderContext、FilterRegistry 与 CompileCache。
- 编译器依赖 Lexer、Parser、TagClassifier、CodeGenerator 及 TagCompilerRegistry。
- 模板文件依赖主题路径与 include 片段。
classDiagram
class BaseController {
+view(template, data, statusCode)
}
class TemplateRendererInterface {
+assign(tpl_var, value)
+fetch(template) string
}
class DouView {
+assign(...)
+fetch(...)
-renderResource(...)
-resolveTemplatePath(...)
-getCompiler()
-getContext()
-getCache()
}
class DouViewCompiler {
+compile(resource, source) string
}
class RenderContext {
+set(name, value)
+filter(name, value)
+loopProp(var, prop)
+includeTemplate(file, vars, assignVar)
}
class Lexer {
+tokenize(source, left, right)
}
BaseController --> TemplateRendererInterface : "调用"
TemplateRendererInterface <|.. DouView : "实现"
DouView --> DouViewCompiler : "使用"
DouView --> RenderContext : "创建/绑定"
DouViewCompiler --> Lexer : "使用"性能考虑
- 启用编译缓存：确保 compile_dir 可写，合理设置 force_compile 与 compile_check。
- 控制模板复杂度：减少深层嵌套与过多 include，降低编译与运行开销。
- 避免在模板中执行数据库查询：所有 IO 应在控制器或服务层完成。
- 使用分页与限流：列表页限制条数，配合前端分页/懒加载。
- 谨慎使用全局转义：仅在必要时开启，避免额外转译成本。
- 复用片段：将高频片段缓存或预编译，减少重复渲染。
故障排查指南
- 模板找不到：检查 resolveTemplatePath 的路径白名单与 realpath 前缀校验，确认模板扩展名在白名单内且路径未越界。
- 编译失败：查看 DouViewCompiler 的标签注册与表达式编译错误；检查自定义标签是否注册。
- 变量未生效：确认控制器已将数据传入 view()，且未被 layoutVars 覆盖；检查 RenderContext::vars 是否正确绑定。
- 循环 @ 属性为空：确认 foreach 已正确命名 item，且 loopVarmap 已建立；检查 RenderContext::loopProp 分支。
- 递归 include 报错：RenderContext 限制最大包含深度，出现递归 include 会抛出异常，需重构模板结构。
- XSS 风险：开启 setEscapeHtml 或使用安全过滤器输出用户可控数据。
结论
DouPHP 的模板数据绑定以清晰的接口与分层设计实现：控制器通过 BaseController::view 将数据注入模板引擎；DouView 负责变量作用域、编译缓存与运行期上下文；RenderContext 提供循环、过滤器与子模板包含能力；编译器保证模板语法到 PHP 的安全高效转换。遵循“控制器/服务层负责数据准备与校验，模板专注展示”的原则，可获得稳定、安全且高性能的渲染体验。
附录：常见用法与示例
- 用户信息展示
- 控制器：查询用户模型，放入 action data，调用 view('user.dwt', ['user' => $user])。
- 模板：{$user.name}、{$user.email}、{$user.avatar_url}。
- 商品详情渲染
- 控制器：加载商品与规格，组装数组，传入 view('product.dwt', ['product' => $product])。
- 模板：{$product.title}、{$product.price}、循环遍历 {$product.specs}。
- 动态表单数据
- 控制器：获取表单字段定义与默认值，传入 view('form.dwt', ['fields' => $fields])。
- 模板：循环渲染字段，使用 {$field.label}、{$field.type}、{$field.value}。
- 列表分页
- 控制器：分页查询，传入 view('list.dwt', ['items' => $items, 'page' => $page])。
- 模板：{foreach $items as $item} 渲染项，使用 {$item@iteration} 等属性。