利用 `ngx_http_xslt_module` 实现 NGINX 的 XML → HTML 转换

一、模块简介

• 模块名称：ngx_http_xslt_module

• 首次引入版本：0.7.8

• 功能：在回传给客户端之前，用指定的 XSLT 样式表对 XML 响应进行转换。

• 依赖：

  • libxml2
  • libxslt

• 编译选项：需在 NGINX 编译时添加 --with-http_xslt_module。

二、使用场景

1. 静态站点：将后端生成的 XML 直接转换成 HTML，减少后端压力。
2. API 网关：API 返回 XML，可根据客户端类型动态指定不同 XSLT。
3. 多视图支持：同一份 XML，基于请求参数套用不同样式，实现多种展现。

三、核心指令

四、示例配置

http {
    # 声明全局 DTD（可选），支持自定义字符实体
    xml_entities /etc/nginx/dtd/entities.dtd;

    server {
        listen 80;
        server_name example.com;

        location /xml/ {
            # 只对 text/xml 和 application/xml 响应进行转换
            xslt_types text/xml application/xml;

            # 如果上游返回 Last-Modified，则保留
            xslt_last_modified on;

            # 应用两套样式表，先 one.xslt 再 two.xslt
            xslt_stylesheet /var/www/xslt/one.xslt version=1.0;
            xslt_stylesheet /var/www/xslt/two.xslt;
        }
    }
}

• DTD 文件内容示例（entities.dtd）：

  <!ENTITY nbsp "&#xa0;">
  <!ENTITY copy "&#xA9;">
  

• 动态传参：

  location /xml/ {
      xslt_stylesheet /xsl/apply.xslt
          lang=$arg_lang
          user=$cookie_user
          theme='$cookie_theme';
  }
  

  对于含有非字母数字的参数，使用 xslt_string_param 或以单/双引号包裹。

五、注意事项 & 性能调优

1. 样式表预编译

   • NGINX 在启动时编译 .xsl，运行时无需再次编译，性能开销主要在第一次加载。

2. 响应缓存

   • 配合 xslt_last_modified on 与 proxy_cache，可大幅提升重复请求性能。

3. 错误处理

   • 若待转换内容非有效 XML，模块会返回 500 错误，建议在上游加 add_header X-Debug ... 便于排查。

4. 内存占用

   • 较大的 XML 或 XSLT 会消耗更多内存，可通过 worker_processes 与 worker_rlimit_core 等指令调优。

5. DTD 文件

   • 仅声明必要的字符实体，避免过大或复杂的 DTD 导致编译缓慢。

六、总结

通过 ngx_http_xslt_module，我们可以让 NGINX 在代理层直接完成 XML → HTML（或其他 XML）转换，最大化利用 NGINX 的高性能、高并发优势，简化后端应用的逻辑复杂度。

• 简化架构：删除后端转换逻辑，统一由 NGINX 处理。
• 动态化：支持根据 URI、参数、Cookie 等动态传参。
• 高性能：样式表预编译 + 缓存策略，让转换成本可控。

欢迎将此模块纳入你的生产环境试点，并在评论区分享你的最佳实践与优化经验！