xiis声明式插件的五种响应类型与插值

声明式插件以零代码方式提供接口：响应类型共五种，内容支持七类插值变量，重定向目标经过安全校验。整个插件只有一个清单文件，复制进插件目录几秒后即可访问，适合验证文件、健康探针与固定跳转等场景。

五种响应类型

纯文本与 HTML 类型输出固定内容，HTML 类型会把插值结果做转义；JSON 类型要求内容为合法 JSON，不合法时该路由被丢弃；重定向类型需要目标与状态码，状态码限于四个跳转值；静态文件类型按相对路径返回文件，越界路径直接丢弃该路由。

响应类型的选择按输出形态决定：固定文本选纯文本，需要浏览器渲染的简短内容选 HTML，供其他程序读取的结构化数据选 JSON；地址变更与文件分发分别对应重定向与静态文件。类型字段与内容字段的搭配在加载期校验，配错会丢弃该条路由。

插值变量

插值只做字面替换，不支持条件、运算与函数调用，因此不存在代码注入面。可用变量覆盖配置值与请求上下文：配置键、站点编号、站点名称、域名、请求路径、请求方法与查询串以及客户端地址，七类变量可以混写在同一段内容里，输出随请求变化。

插值适合做随请求变化的静态内容：同一条路由可以按站点编号输出不同文案，按请求路径回显探针信息，或把查询串原样带进响应用于联调。变量不存在时按字面保留，便于排查拼写问题。

重定向目标校验

重定向目标必须为非空字符串，不允许含反斜杠，不允许以双斜杠开头，以斜杠开头视为站内跳转，其余情况必须以完整协议头开头并能解析出主机名。校验不通过时该路由被丢弃，防止开放重定向被误用。

自定义响应头与配置联动

声明式路由可以附加自定义响应头，值同样支持插值，常见用途是给验证文件或探针接口设置索引控制头。配置值来自清单的配置项，使用者改值后随热更新生效，响应内容随之变化，不需要触碰任何程序文件。

接入与生效节奏

声明式插件的上线方式与程序形态完全一致：把插件目录复制进站点插件目录，随后随热更新节拍加载；临时停用改启用字段即可，不需要删除目录。主程序未装任何插件时，相关匹配逻辑首行判空即返回，对既有性能零影响。

与程序形态的边界

两种形态的边界清晰：需要读取数据、执行计算或访问数据库的路由都应归入程序形态；声明层只处理已知内容的转发与变换。按这条边界选择形态，插件的维护复杂度可以保持在最低，排查问题时也更容易定位责任范围。

零代码示例与校验规则

最小可用的声明式插件只需要清单：标识、名称、版本、协议版本与一条路由，路由声明路径、方法、处理方式与响应。清单加载时执行结构校验，配置项类型、路由路径格式、方法集合、形态一致性与保留路径逐项检查，失败只跳过对应插件或路由，主程序与其他插件不受影响。

声明式插件把能配置的都放进声明层：内容、跳转与文件三类输出覆盖了零代码需求的绝大多数场景，接口上线从写代码变成写清单，维护成本随之降到最低。