HTML代码质量共性取决于结构语义一致性、内容注入安全性与复用边界清晰性；需通过CI工具校验最终HTML而非源模板，强制区分静态/动态注入路径，并在接口层统一数据契约。
html/template 和 handlebars、EJS、Pug 等模板语言在混合架构中并存时，HTML 代码质量的共性不来自语法，而来自三类可验证行为：结构语义是否一致、内容注入是否安全、复用边界是否清晰。强行统一语法或工具链反而掩盖真实问题。
结构语义必须收敛到 HTML5 标准，而非模板语法
不同模板语言对“导航栏”可能写成 <nav-bar>（Web Components）、{{> partials/nav}}（Handlebars）、include("nav.pug")（Pug），但最终渲染出的 DOM 必须满足同一套语义约束：
-
<nav>元素内不能嵌套<div role="navigation">—— 重复语义，破坏可访问性 - 所有页脚
<footer>必须包含至少一个<time datetime>或aria-label，用于版权年份或服务标识 - 条件渲染生成的
<button>若含disabled，必须同步设置aria-disabled="true"，否则屏幕阅读器无法感知状态
这些规则无法靠模板引擎自身保证，需在 CI 中用 axe-core 或 html-validate 对最终 HTML 输出做断言，而不是检查源模板文件。
内容注入路径必须显式区分「静态」与「动态」
混合架构中最隐蔽的质量断层，发生在模板层和运行时层交界处。例如：
立即学习“前端免费学习笔记（深入）”；
-
html/template的{{.Title}}默认转义，但若写成{{.RawHTML | safeHTML}}，就跳出了安全边界 -
EJS的<%= title %>不转义，<%- title %>才转义 —— 符号差异极小，极易误用 -
Pug的p= title不转义，p!= title才不转义 —— 反直觉，且 IDE 往往不报错
解决方案不是禁用不转义语法，而是强制约定：所有跨服务传入的数据（如 API 响应字段、CMS 内容）必须走「动态通道」，且在模板入口处统一加前缀，如 {{.Unsafe.Title}}、data-unsafe-title。这样可在 lint 阶段用正则扫描所有 Unsafe\. 调用，触发人工审查。
复用单元必须声明作用域与生命周期，不能依赖文件路径隐含关系
常见错误是把 header.html 放进 /shared/ 目录，就认为它“天然可复用”。实际上：
- Go 模板中
{{template "header" .}}依赖全局模板注册，若某子模板未ParseFiles该文件，运行时报template: header: "header" is undefined - Webpack 的
html-loader用<%= require('./header.html') %>，但该路径是构建时解析，无法在 SSR 中复用 - Web Components 的
<site-header>若通过fetch()加载远程 HTML，首次渲染会白屏，且无法被爬虫索引
真正可控的复用，只存在于两个明确边界内：构建时（如 posthtml-include）或运行时（如 customElements.define()）。二者不可混用，也不能靠目录结构“自动推导”——必须在组件定义里显式声明其加载方式、缓存策略、fallback 行为。
最易被忽略的点：模板间的数据契约比 HTML 结构更难统一
当 Go 后端返回 map[string]interface{} 给 html/template，Node.js 服务却用 {title: string, items: Array<{id: number}>} 传给 Handlebars，前端组件拿到的数据形状不一致，会导致相同 CSS 类名下 DOM 结构错乱。这种问题不会触发任何模板语法错误，但会让 aria-labelledby 指向不存在的 ID，或让 JS 初始化逻辑静默失败。解决它不靠工具，而靠在接口层定义最小数据契约（如 OpenAPI 的 components/schemas），并让所有模板语言消费同一份 JSON Schema 衍生的 TypeScript 类型或 Go struct。
