Formily Reactive toJS 详解：从 observable 到普通 JS 对象的深度递归转换
2026/9/23 22:27:18
开篇：为什么过了这么久还在写 Genshi
距离上一篇 Genshi 笔记已经有一阵子了，这段时间我又在几个实际项目里把 Genshi 翻来覆去地用了几轮，踩了些新坑，也补上了一些之前没讲透的细节。趁印象还热乎，赶紧整理出来。这篇本来是接着上一篇往下的，但内容上独立成章，没看过之前那篇也不影响理解。
先说个背景：Genshi 是 Python 生态里一个比较老的模板引擎，主打 XML/HTML 流式处理。很多人第一次听到它是在折腾 Trac 或者一些早期 Python Web 框架时，那时候国内社区讨论度还算高，后来 Django 自带模板和 Jinja2 实在太强势，Genshi 慢慢淡出了主流视野。但如果你要做 XML 结构转换、类 SOAP 消息拼接、或者对“模板中输入输出必须严格合法”这种场景有硬性要求，Genshi 反而比 Jinja2 这类字符串拼接型模板靠谱得多。
这篇笔记适合这几类人：正在维护遗留项目、被迫面对 Genshi 模板的；在选型阶段纠结“到底要不要用 Genshi”的；以及想了解一套完全不同思路的模板引擎、给自己技术储备添砖加瓦的。我会尽量把原理、实操、还有那些文档里查不到的经验都写清楚。
1. Genshi 的设计思路，到底反直觉在哪里
1.1 流式处理：模板不是一个“字符串”而是一棵“树”
我们平时用 Jinja2 或者 Django 模板时，脑子里通常会建立一个模型：模板是一段带占位符的文本，我们往里塞数据，它帮我们替换并拼出最终文本。这个过程有个潜在问题，就是模板文本本身并不一定合法——标签没闭合、属性少个引号、特殊字符没转义，这类错误在替换之前不会被发现。
Genshi 从出发点就不一样。它先把模板文本解析成一棵 XML/HTML 树，然后保留原始树结构，再通过路径表达式在树上定位节点进行替换和填充。换句话说：
用户请求 -> 解析模板(构建 XML 树) -> 用数据对树进行变换 -> 序列化输出合法 XML/HTML这样做的第一个好处是：模板必须写对。如果你给 Genshi 一段标签不闭合的 HTML，它直接抛异常，根本不给你“碰运气”的机会。第二个好处是输出必然合法，因为树本身就是合法的，序列化出来自然也是合法文档。
我用一个生活化类比来说明：Jinja2 像是拿一张贴满便利贴的纸质调查表，你根据便利贴要求把内容填进空格里，只要格子填对了就能交差；Genshi 则像是先用积木搭好一个房子，每块积木对应一个位置，然后你只需要往特定积木上刷颜色，最后房子必然是完整的。
1.2 为什么选用 XPath 风格表达式而不是普通的 {{ 变量 }}
用py:if、py:for、py:choose这些指令代替传统{% if %}、{% for %}标签，看着很别扭，但实际用下来效率其实很高。Genshi 的关联数据方式不是“整段文本替换”，而是“定位到某个节点，然后对这个节点做操作”。
你写<div py:if="user.logged_in">欢迎回来</div>，Genshi 不会等渲染时才去判断，而是遍历树到这个 div 节点时，发现user.logged_in为假，就把这个节点直接剪掉，子节点也一并消失。这种“删除节点”的逻辑写起来非常顺手，尤其适合做条件区块和循环区块的排版，模板结构能始终保持清晰。
还有一个贴近前端直觉的好处：设计稿什么样，Genshi 模板初始状态就什么样。你拿一个静态 HTML 原型，加上几个py:属性，它就变成了一个动态模板。这比把整块 HTML 塞进{% block %}里更符合“所见即所得”的工作流。
2. 核心细节解析与实操要点
2.1 路径表达式中的数据绑定：py:for和py:with
py:with可以给表达式定义局部变量，避免同一个表达算了两次：
<py:with vars="total = sum(item.price for item in items)"> <p>合计：${total}</p> </py:with>这里值得注意的是，vars 里的表达式是“惰性计算”还是“立即计算”。Genshi 的表达式在树遍历到那个节点时才执行，所以如果你把一些昂贵的查询放到py:with里，而且外面又包了一层py:if，那么条件不满足时查询根本不会执行。这属于一个容易被忽视的优化点。
2.2 大小写和属性名的坑
XML 标签是大小写敏感的。你写<Div>会被当成一个完全不同的元素，而不是<div>。从 HTML5 原型搬过来时，如果原型里有<DIV>或者<SPAN>，务必统一成小写，否则 Genshi 解析时不会报错，但序列化出来会保留这种大小写状态，浏览器倒是认，但后续你用 XPath 匹配时容易出问题。
属性的命名也有讲究。Genshi 在输出时不会帮你自动补充布尔属性（比如<input disabled>这种），它希望你把属性写成disabled="disabled"才算完整属性。用模板时尽量按 XHTML 的标准来写属性，这样 Genshi 序列化不别扭，后面接前端框架也更顺。
2.3 模板继承与py:def宏
Genshi 里没有 Django 那种{% extends %}加{% block %}的组合拳，它用的是基于 XPath 的py:match。这个指令允许你用选择器去“命中”模板中的某些节点，然后整体替换成你写好的内容块。
父模板layout.html写法：
<html xmlns:py="http://genshi.edgewall.org/"> <head> <title>我的站点</title> </head> <body> <div id="content"> <!-- 子模板中的内容会替换这里 --> </div> </body> </html>子模板中这样用：
<py:match path="//div[@id='content']"> <div id="content"> <h1>${page_title}</h1> ${select('*')} </div> </py:match>这里用到了select('*')，它的含义是：将原节点下的所有子节点原样拿过来，放在当前这个位置。这个能力非常强大，相当于你在“模板内部”又做了一次节点转移。
2.4 输出安全：Genshi 默认不会帮你转义，需要自己把关
Genshi 默认情况下，${var}输出普通文本时会做 XML 转义，防止你把<script>注入进页面。这是它默认的安全行为。
但如果你确实想输出 HTML 片段，比如从数据库里取了一段富文本，显式地告诉 Genshi “这是安全的 HTML”，可以用 HTML 类包装：
from genshi.core import Markup html_content = Markup('<b>粗体内容</b>')然后在模板里${html_content}直接输出，Genshi 不会再转义。这里我建议：永远不要对用户直接提交的内容使用 Markup，只对经过白名单过滤或后台可信编辑录入的内容这样做。做模板开发的朋友最容易在这里翻车，导致存储型 XSS。
2.5 i18n 和表单控件
Genshi 官方提供了一套 i18n 指令，但说实话用起来不如 Jinja2 的 Babel 集成方便。你要是项目有国际化需求，我更推荐把 Genshi 模板做成纯结构，文本内容全部通过变量注入。虽然这样模板维护时会稍多一点工作量，但配合 gettext 翻译文件反而更直接。
关于表单控件，Genshi 有py:attrs可以动态拼属性，比如做 select 的 selected 状态：
<option py:attrs="{'selected': (item.id == selected_id) and 'selected'}"> ${item.name} </option>注意这里selected属性的值是字符串 'selected' 或 None。Genshi 序列化时遇到 None 属性会自动忽略，而遇到字符串就原样输出。用这个方式，你就避免了手写if else拼 HTML 的脏活。
3. 实操过程与核心环节实现
3.1 环境准备与起步模板
建议在虚拟环境里操作：
mkdir genshi_demo && cd genshi_demo python -m venv venv source venv/bin/activate pip install genshi验证安装是否成功：
import genshi print(genshi.__version__)我用的是 Genshi 0.7.7，在 Python 3.10 环境下完全正常。老版本 0.6 在 Python 3 下面有一些编码问题，有条件的话尽量用新版本。
3.2 一个完整的报表页面：从数据到 HTML
我们做一个商品库存报表页，数据源用 Python 字典和列表模拟。创建report.py：
from genshi.template import TemplateLoader from genshi.core import Markup def load_data(): products = [ {"name": "机械键盘", "price": 399, "stock": 23, "status": "in"}, {"name": "显示器", "price": 1299, "stock": 0, "status": "out"}, {"name": "USB Hub", "price": 89, "stock": 45, "status": "in"}, ] summary = { "total_products": len(products), "total_stock": sum(p["stock"] for p in products), } return {"products": products, "summary": summary} loader = TemplateLoader("templates", auto_reload=True) template = loader.load("report.html") data = load_data() data["page_title"] = "商品库存报表" data["today"] = "2024-11-15" output = template.generate(**data) print(output.render("html", doctype="html"))模板templates/report.html写成这样：
<html xmlns:py="http://genshi.edgewall.org/" xmlns:xi="http://www.w3.org/2001/XInclude"> <head> <title>${page_title}</title> </head> <body> <h1>${page_title}</h1> <p>统计日期：${today}</p> <h2>商品列表</h2> <table border="1"> <tr> <th>名称</th> <th>价格</th> <th>库存</th> <th>状态</th> </tr> <tr py:for="product in products" py:attrs="{'class': product['status'] == 'out' and 'out-of-stock'}"> <td>${product['name']}</td> <td>${product['price']}</td> <td>${product['stock']}</td> <td> <py:choose> <p py:when="product['status'] == 'in'">在售</p> <p py:otherwise="">缺货</p> </py:choose> </td> </tr> </table> <h2>统计</h2> <ul> <li>商品总数：${summary['total_products']}</li> <li>总库存：${summary['total_stock']}</li> </ul> </body> </html>然后终端执行：
python report.py你会看到控制台输出一整个完整、合法的 HTML 文档。注意两点：第一，模板根节点必须加上xmlns:py命名空间，否则 Genshi 不认识这些指令；第二，xmlns:xi是给 XInclude 用的，你要是没用到可以不加，但加上也不影响。
3.3 渲染成 HTML 片段而不是完整页面
用render("html", doctype="html")输出的是完整文档。如果只需要片段，比如给前端返回一段商品列表的局部 HTML，直接render("html")不带 doctype 就行。或者更细一点，只想要某个节点内部的子内容，可以用select在生成结果上继续筛选。
我在一个实际项目里就是这么干的：后端渲染好整个报表页面，通过同一个模板文件，利用参数控制输出完整页面还是仅输出 tbody 内容，这样前端在单页应用里刷新局部数据时，不用维护两套模板。
3.4 调试技巧：怎么看 Genshi 到底生成了什么
Genshi 的优势之一是调试相对直观。你在 Python 里可以逐步查看：
stream = template.generate(**data) # stream 是一个事件流，可以转换成列表查看 events = list(stream) for kind, data, pos in events: print(kind, data, pos)这样输出的是 Genshi 内部事件序列，你会看到 START、END、TEXT 这些事件，对理解“流式处理”很有帮助。如果你在写复杂模板时行为不符合预期，先看事件流，再去改模板，效率比盲猜高很多。
如果模板有语法错误，Genshi 抛出的异常里会带行列号，直接定位到模板文件的具体位置。这个比 Jinja2 偶尔的“哪儿出错看不出来”要友好。
3.5 性能优化：该缓存时就缓存
TemplateLoader默认会把解析后的模板缓存起来，所以不要在每次请求时重复创建 loader。auto_reload=True在开发期很有用，改完模板刷新就能看到新内容；但生产环境建议改成auto_reload=False，减少不必要的文件时间戳检查。
对于真正的性能敏感场景，Genshi 的流式处理本身比较轻量，但树构建还是不如纯字符串替换快。我有一个经验值：页面很小（几十 KB）时差别不大；页面很大且模板中包含多层循环时，Genshi 会比 Jinja2 慢 30% 到 50% 左右。如果你明确知道项目是超高并发的小页面请求，那 Genshi 不是最优选。反过来，如果你需要输出的结构严谨、不能出错，Genshi 的稳健性价值远超这点性能差距。
4. 常见问题与排查技巧实录
4.1 现象一：模板写对了，但${}表达式就是不被解析
排查步骤：
- 检查 XML 命名空间：根元素或模板的指令元素上必须声明
xmlns:py="http://genshi.edgewall.org/"，没有声明时 Genshi 会把py:属性当成普通属性，直接原样输出。 - 检查文件编码：Genshi 默认期望 UTF-8，如果你文件是 GBK 保存的，解析阶段可能报编码错误，或后面渲染中文乱码。统一用 UTF-8 保存。
- 检查
${}是否写在了属性里：title="${some_var}"这种是支持的，但如果你忘了用引号包住，写成title=${some_var}，XML 解析器会报错。
提示：几乎所有“表达式没生效”的案例，最后都发现是命名空间缺失或引号问题，先查这两条，再查别的。
4.2 现象二：py:match替换后，原生内容重复出现
py:match的语义是“匹配到节点后，用你的内容替换掉原节点，但原节点内部可以通过select()重新引入”。如果你忘记写select('*')，原节点的所有子内容就全丢了。反过来，如果你写了select('/')，这表示选中文档根节点，而不是当前节点，那就可能把整个文档结构卷进来，导致内容异常。
一个稳妥写法是：
<py:match path="//div[@id='content']"> <section id="content"> ${select('*|text()')} </section> </py:match>这里select('*|text()')同时选取子元素和文本节点，能完整保留原来 div 里面的文字和标签。
4.3 现象三：输出结果里多出很多xmlns:py命名空间
Genshi 默认会保留模板上声明的命名空间。如果你觉得xmlns:py="http://genshi.edgewall.org/"出现在最终输出的 HTML 上很碍眼，注意一点：render("html")模式下，Genshi 会自动移除它认识的指令命名空间。没移除的话，大概率是你某个属性写错了——节点上出现了 Genshi 不认识但仍然带py:前缀的属性，它默认认为这个命名空间是文档的一部分，于是保留。
解决方法是检查所有带py:前缀的属性是否都正确。还有，避免自定义xmlns:mypy这类前缀，Genshi 不做智能判断，只要不是它认识的指令，就可能原样输出。
4.4 现象四：在循环里重复使用同一个变量名导致数据串了
Genshi 的作用域规则和 Python 类似，但模板里的优先级容易混淆。看这个例子：
<py:for each="product in products"> <py:with vars="name = product['name']"> <p>${name}</p> </py:with> </py:for>你在内层用name存了产品名，外层如果也有个变量叫name，不会冲突。但如果你在同一个py:for的不同分支里重复给name赋值，最后的输出就是你最后一次赋值的结果，这在逻辑复杂时很难排查。
我建议：模板内所有临时变量名统一加前缀，比如tmp_name、row_product，避免和全局数据 key 撞名。虽然不是最优雅，但能省去很多抓狂的时间。
4.5 常见问题速查表
| 问题 | 可能原因 | 处理建议 |
|---|---|---|
${}原样输出 | 缺少 xmlns:py 命名空间 | 在模板根元素补上命名空间声明 |
| 中文乱码 | 文件编码不是 UTF-8 | 统一用 UTF-8 保存模板文件 |
| 模板继承不生效 | py:match路径写错 | 检查 XPath 表达式，用//div[@id='content']先测试 |
| 输出多了 xmlns:py | 属性写错导致命名空间未识别 | 检查所有 py: 开头属性 |
| 找不到模板文件 | TemplateLoader 路径不对 | 用 os.path.abspath 确认路径 |
| 布尔属性输出异常 | Genshi 没有自动补充布尔属性 | 显式写成disabled="disabled" |
| 数据渲染慢 | 循环里重复调用了函数 | 用py:with缓存中间结果 |
| 模板改完不生效 | auto_reload=False 还在跑旧缓存 | 开发期设 auto_reload=True |
4.6 一个很隐蔽的坑：注释节点和空白文本节点会被原样保留
Genshi 对模板中的 HTML 注释<!-- ... -->和空白文本节点是“手下留情”的，不会主动删除。这意味着，如果你循环输出一个列表，模板里每一行的缩进和换行，会原样出现在最终 HTML 中。
这在视觉上通常没问题，但有个隐患：如果你把渲染结果和某个字符串做精确匹配（比如给代码生成器用），会因为多余空白字符导致不一致。解决办法有两个思路：第一个是调render()时用strip_whitespace=True参数（Genshi 的 HTML 渲染默认就会去掉一些多余 whitespace，但 XML 模式不会）；第二个是在模板里尽量少留空行和缩进，把循环体的内容写在更紧凑的层级中。
output = template.generate(**data).render("html", strip_whitespace=True)这样处理后输出会紧凑很多，适合机器读取。
5. 进阶技巧：把 Genshi 当作 XML 文档转换器来用
5.1 不只是网页模板，还能做 RSS 生成和数据清洗
Genshi 的底层能力决定了它不只是网页模板。你可以拿它生成 RSS 2.0、Sitemap、XML 配置文件，甚至做简单的 XML 结构转换。
举个例子，要生成 RSS：
<?xml version="1.0" encoding="utf-8"?> <rss version="2.0" xmlns:py="http://genshi.edgewall.org/"> <channel> <title>${site_name}</title> <link>${site_url}</link> <item py:for="post in posts"> <title>${post['title']}</title> <link>${post['url']}</link> <description>${post['summary']}</description> <pubDate>${post['pub_date']}</pubDate> </item> </channel> </rss>这个模板生成的 XML 完全合法，不会被字符串拼接漏掉转义。
5.2 利用 XPath 在渲染后进一步处理
渲染完获得的是事件流，而不是普通字符串，这意味着你可以继续对结果做“结构化操作”：
from genshi.template import TemplateLoader from genshi.filters import Transformer loader = TemplateLoader("templates") template = loader.load("base.html") stream = template.generate(title="测试", content="内容") # 在渲染结果中，给所有 a 标签追加 target="_blank" stream = stream | Transformer('//a').attr('target', '_blank') output = stream.render("html")这种方式在你需要统一给链接加追踪参数、或者给表格加样式类时非常方便，不用把逻辑塞进模板自身。
5.3 懒加载与片段缓存
如果项目里用 Genshi 承担部分页面的渲染，又不想每次都完整跑一遍模板，可以把某些固定区块先渲染成字符串缓存起来。Genshi 的流式处理是把双刃剑：它非常灵活，但也意味着每次都重新走一遍树遍历。
我实际项目的做法是：每个页面的模板尽量拆小，公共头部尾部用 XInclude 或py:match组合，但缓存的是组装后的完整字符串。这样在负载上来时，可以在 Web 框架的缓存层直接命中，不用再碰模板引擎。Genshi 本身解决“怎么生成”，缓存解决“别每次都生成”，两者配合就很舒服。
6. 关于“续”的部分：和上一篇的衔接思路
6.1 从“能跑”到“跑得明白”
上一篇笔记重点讲了 Genshi 的安装、基础语法、以及怎么从一个简单模板渲染出页面，定位是快速上手。而这篇的内容我刻意往“高级用法”和“排错经验”方向走，原因很简单：模板引擎这类工具的入门壁垒不在语法，而在思维模式。
遇到像 Genshi 这种比较规整、底层思路不一样的框架，很多人一开始照着示例写没问题，但一旦牵扯到模板继承、XPath 匹配、事件流转换，就会觉得“不得劲”。这份别扭往往不是能力问题，而是没把 Genshi 的“树和流”模型内化。可以多试几次在 Python 端打印事件流，看它到底在遍历什么，这时候容易有豁然开朗的感觉。
6.2 和 Jinja2 的共存场景
同一个项目里，你完全可以在模板引擎之间做共存：Jinja2 用来渲染营销页和简单页面，Genshi 用来渲染结构化要求高的区域（比如数据报表、XML 接口）。我在一个后台系统里就同时用了两者，主框架页面走 Jinja2，表格组件和数据导出部分走 Genshi，两边互不干扰。
刚开始团队也觉得多一个技术栈负担偏大，但后来大家发现 Genshi 处理表格行列合并、条件样式这类场景时，模板比 Jinja2 容易维护得多。所以不要被“只能用一个模板引擎”的想法框住，按场景混用是可行的。
6.3 如果新项目选型，我会怎么判断
你要问我新项目还会不会主动选 Genshi，我的答案是看场景。做传统 Web 页面、追求开发速度和社区生态，Jinja2 依然是更稳妥的选择；做 XML 接口、严格结构化输出、或者需要模板内做复杂节点操作，Genshi 值得考虑。另外，如果你的内容形态天然是“文档树”（比如邮件模板、合同模板、电子处方这类有确定结构的文书），Genshi 的表达力明显更好。
这不算是什么“过时技术情怀”，只是回到工具本身：选模板引擎不是选“最新”，而是选“和你的数据形态、输出要求最匹配的”。
在这里收个尾：一些坚持到现在的使用心得
最后分享一点我自己的使用习惯。我平时写 Genshi 模板，会刻意保持“每行标签完整闭合”，即使输出 HTML 不需要那么严格，也会按 XML 的标准来写。半个模板写完，直接扔到浏览器看一眼，再继续往下写，整体效率反而比一口气写完再调试高很多。
另外，Genshi 的报错信息虽然定位准确，但异常堆栈有时会套几层迭代器，初次遇到容易慌。我的经验是：不要看最底层的堆栈，直接找带模板文件名和行列号的那一行，问题十有八九就出在那里。
写这份“续”篇时我自己又翻了一遍之前项目的模板文件，发现有几个地方可以用py:with减少重复运算，也顺手动了一下。模板引擎就是这样，写得越多、回头看得越多，越能品味出那些设计上的巧思。希望这篇笔记能帮你少走一些我走过的弯路，也欢迎在评论区或者邮件里聊聊你自己用 Genshi 时踩到过的坑，一起把经验沉淀下来。