在JSF（JavaServer Faces）项目中，经常会有这样的需求：产品文档、帮助手册以Markdown格式存储在数据库或文件系统中，页面需要把这些内容渲染出来展示给用户。问题在于，Markdown里写死的链接往往是静态的，而实际跳转地址可能依赖当前登录用户、请求参数甚至权限级别。硬编码显然不行，这就需要一套动态链接处理机制。本文从整体思路到具体实现，逐步拆解这个问题。
整体思路：为什么要在渲染层做链接替换
先说结论，处理Markdown里的动态链接，最佳位置是在后端渲染层，也就是把Markdown转换成HTML之后、返回给浏览器之前。原因有三个。第一，Markdown源文件应该保持纯净，写Markdown的人不应该关心运行时的用户状态，文档里可以用占位符表达意图，比如 {{docUrl}} 或 {userId}，具体值由运行环境决定。第二，JSF本身有完整的生命周期和视图状态管理，在渲染阶段介入可以自然地拿到会话信息、请求参数和托管Bean的数据。第三，集中处理便于统一做安全校验和日志记录，避免散落在各个页面里难以维护。
常见的做法是定义一套占位符规范。比如文档作者这样写：
详细配置请参考 [配置手册]({{helpUrl}}/config?uid={userId})
[下载模板]({{downloadUrl}}?token={sessionToken})渲染时，后端用一个解析器把这些占位符替换成真实值。这样文档与代码解耦，链接规则变更只需要改配置或替换逻辑，不用重写文档。
具体实现：基于PhaseListener和自定义渲染的方案
在JSF里，可以通过自定义组件或者简单的Bean方法完成替换。如果文档渲染逻辑集中在一个托管Bean中，直接在Bean方法里处理最简单：
@ManagedBean
@ViewScoped
public class DocRenderer implements Serializable {
@ManagedProperty("#{userSession}")
private UserSession userSession;
public String renderMarkdown(String rawMarkdown) {
// 第一步：Markdown 转 HTML
String html = flexmarkRender(rawMarkdown);
// 第二步：动态替换链接占位符
html = html.replace("{{helpUrl}}", ConfigHolder.getHelpUrl())
.replace("{{downloadUrl}}", ConfigHolder.getDownloadUrl())
.replace("{userId}", String.valueOf(userSession.getUserId()))
.replace("{sessionToken}", userSession.getSessionToken());
return html;
}
private String flexmarkRender(String md) {
MutableDataSet options = new MutableDataSet();
Parser parser = Parser.builder(options).build();
HtmlRenderer renderer = HtmlRenderer.builder(options).build();
Node document = parser.parse(md);
return renderer.render(document);
}
}如果链接替换规则比较复杂，比如需要根据用户角色决定是否渲染某个链接，建议操作解析后的DOM而不是简单字符串替换。以flexmark-java为例，可以在解析后遍历节点：
Node doc = parser.parse(rawMarkdown);
doc.accept(new NodeVisitor(VisitAction(Link.class)) {
@Override
public void visit(Link link) {
String url = link.getUrl().toString();
if (url.contains("{{helpUrl}}")) {
link.setUrl(ConfigHolder.getHelpUrl()
+ url.substring(url.indexOf("}") + 1));
}
// 权限不足时可以直接移除链接，保留文本
if (!userSession.hasPermission(url)) {
link.unlink();
}
}
});相比正则替换，DOM遍历方式的好处是能精确控制每个节点的行为，不会误伤代码块里恰好长得像链接的内容。
安全与性能：动态链接处理中不能忽视的两件事
动态链接意味着链接的目标受用户输入或配置影响，必须防范开放重定向和XSS。如果占位符的值可能来自请求参数，一定要做白名单校验，只允许跳转到预定义的域名。渲染Markdown时务必开启HTML过滤，因为Markdown标准允许内嵌原始HTML，恶意用户可能借文档注入脚本。flexmark可以通过扩展禁用原始HTML：
MutableDataSet options = new MutableDataSet();
// 禁用原始HTML标签，防止XSS
options.set(Parser.EXTENSIONS, Arrays.asList(
TablesExtension.create(),
AutolinkExtension.create()
));
options.set(HtmlRenderer.SUPPRESSED_LINKS, "javascript:.*");性能方面，如果文档内容较大且访问频繁，不要每次请求都重新解析Markdown。推荐把渲染结果按文档版本加用户维度做缓存，例如用Guava Cache缓存原始HTML，占位符替换留到每次请求时执行，因为这一步开销极小。占位符替换和Markdown解析分开，正是为了缓存解析这个重活。
最后一点实践建议：为占位符建立统一的注册表机制，所有可用占位符集中定义，文档作者写错了占位符时渲染日志能明确报错，而不是留下一个残缺的链接静默失败。这套机制搭好之后，Markdown文档在JSF应用里就能像模板一样灵活运转，链接随用户、随环境动态变化，而文档源文件始终保持稳定。