Higress custom-response 插件完全指南：自定义 HTTP 应答状态码、响应头与 Body

Higress custom-response 插件完全指南：自定义 HTTP 应答状态码、响应头与 Body

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress

本篇技术指南以 Higress 开源仓库中 custom-response 示例插件 的官方文档为核心，系统讲解该插件如何实现自定义 HTTP 应答（状态码、响应头、Body），覆盖新旧两种配置格式、精确与模糊状态码匹配规则、Mock 响应以及触发限流时自定义响应等实战场景，并深入源码与测试验证底层实现。读完本文，你将掌握在 Higress 网关上按需"篡改"上游应答、实现 Mock 与限流兜底页面的完整方案。

功能说明

custom-response插件允许网关为请求返回完全自定义的 HTTP 响应，可配置的部分包括：

• 自定义 HTTP 应答状态码（status_code）
• 自定义 HTTP 应答头（headers）
• 自定义 HTTP 应答 Body（body）

典型应用场景有两种：

1. Mock 响应：不访问真实上游，直接由网关返回模拟数据；
2. 按状态码定制应答：判断上游（或网关内部限流策略）返回的特定状态码后，替换为自定义响应，例如触发网关限流策略时返回 302 重定向到降级页面。

运行属性

属性	值
插件执行阶段	认证阶段（Authentication Phase）
插件执行优先级	910

插件在认证阶段以 910 的优先级参与请求处理，因此可以在限流等前置插件产生429之后，再对本已发出的响应进行改写。

配置字段说明

新版本：支持多种返回（rules 数组）

新版本配置通过rules规则组支持同一次配置针对不同原始状态码返回不同应答。

名称	数据类型	填写要求	默认值	描述
rules	array of object	必填	-	规则组

rules中每个规则的配置字段如下：

名称	数据类型	填写要求	默认值	描述
status_code	number	选填	200	自定义 HTTP 应答状态码
headers	array of string	选填	-	自定义 HTTP 应答头，key 和 value 用=分隔
body	string	选填	-	自定义 HTTP 应答 Body
enable_on_status	array of string or number	选填	-	匹配原始状态码，生成自定义响应。可填写精确值如200、404等，也可模糊匹配如2xx（匹配 200-299）、20x（匹配 200-209），x代表任意一位数字。不填写时，不判断原始状态码，取第一个enable_on_status为空的规则作为默认规则

从源码看，配置解析在 main.go 的parseConfig中完成：当配置中存在rules且为数组时走新版本逻辑，逐条解析规则，并将第一个enable_on_status为空的规则记为默认规则（defaultRule）；同时把每个enable_on_status条目与规则建立映射（enableOnStatusRuleMap），同一状态码不能被两条规则重复使用，否则插件启动直接失败（返回错误enableOnStatus can only use once）。

模糊匹配规则

模糊匹配模式需同时满足三个条件：

• 长度为 3
• 至少一位数字
• 至少一位x（不区分大小写）

规则	匹配内容
40x	400-409；前两位为 40 的情况
1x4	104,114,124,134,144,154,164,174,184,194；第一位和第三位分别为 1 和 4 的情况
x23	023,123,223,323,423,523,623,723,823,923；第二位和第三位为 23 的情况
4xx	400-499；第一位为 4 的情况
x4x	040-049,140-149,240-249,340-349,440-449,540-549,640-649,740-749,840-849,940-949；第二位为 4 的情况
xx4	尾数为 4 的情况

模糊模式的合法性校验在源码 isValidFuzzyMatchString 中实现：长度必须为 3、只能包含数字和x/X、必须同时包含至少一个x和至少一个数字。例如123（缺少x）、xxx（缺少数字）、xYx（非法字符）、x1（长度不足）都会被判定为非法配置，导致插件启动失败，对应测试见 main_test.go。

老版本：只支持一种返回

为兼容旧配置，插件仍然支持不带rules的单规则写法：

名称	数据类型	填写要求	默认值	描述
status_code	number	选填	200	自定义 HTTP 应答状态码
headers	array of string	选填	-	自定义 HTTP 应答头，key 和 value 用=分隔
body	string	选填	-	自定义 HTTP 应答 Body
enable_on_status	array of number	选填	-	匹配原始状态码，生成自定义响应，不填写时，不判断原始状态码

老版本配置在解析时会被自动包装成单条规则并作为默认规则处理（见 main.go），因此新旧两种写法可以平滑兼容。

匹配优先级

精确匹配 > 模糊匹配 > 默认配置（第一个enable_on_status为空的配置）

该优先级在响应头处理阶段体现：onHttpResponseHeaders（main.go）先读取上游响应的:status，在enableOnStatusRuleMap中做精确查找，未命中再通过 fuzzyMatchCode 逐模式做模糊匹配（要求模式长度与状态码一致、数字位精确匹配、x位自动放行）；若配置中存在默认规则，则在请求头阶段（onHttpRequestHeaders）就直接返回默认应答。

配置示例

以下示例均可直接用于 Higress 网关的插件配置（WasmPlugin 或 Ingress 注解）。使用环境可参考 docker-compose.yaml 与 envoy.yaml 提供的本地 Envoy + echo-server 调试环境。

新版本：不同状态码返回不同应答

rules: - body: '{"hello":"world 200"}' enable_on_status: - 200 - 201 headers: - key1=value1 - key2=value2 status_code: 200 - body: '{"hello":"world 404"}' enable_on_status: - 404 headers: - key1=value1 - key2=value2 status_code: 200

根据该配置，200、201 请求将返回自定义应答：

HTTP/1.1 200 OK Content-Type: application/json key1: value1 key2: value2 Content-Length: 21 {"hello":"world 200"}

404 请求将返回自定义应答：

HTTP/1.1 200 OK Content-Type: application/json key1: value1 key2: value2 Content-Length: 21 {"hello":"world 404"}

注意：应答的状态码由每条规则内的status_code决定，上例中 404 请求虽然命中的是原始404规则，但返回给客户端的是该规则配置的200。关于 Body 对应的Content-Type，源码 parseRuleItem 会自动推断：若 Body 是合法 JSON 则设置为application/json; charset=utf-8，否则为text/plain; charset=utf-8；Content-Length则由代理按实际 Body 重新计算，配置中的content-length响应头会被忽略。

新版本：模糊匹配场景

rules: - body: '{"hello":"world 200"}' enable_on_status: - 200 headers: - key1=value1 - key2=value2 status_code: 200 - body: '{"hello":"world 40x"}' enable_on_status: - '40x' headers: - key1=value1 - key2=value2 status_code: 200

根据该配置，200 状态码将返回自定义应答：

HTTP/1.1 200 OK Content-Type: application/json key1: value1 key2: value2 Content-Length: 21 {"hello":"world 200"}

401-409 之间的状态码将返回自定义应答：

HTTP/1.1 200 OK Content-Type: application/json key1: value1 key2: value2 Content-Length: 21 {"hello":"world 40x"}

模糊匹配的位级语义在 main_test.go 的Test_prefixMatchCode中有详尽覆盖：例如101、201命中x01，203、213命中2x3，450、451命中45x，600、611、612命中6xx，171命中x7x，228命中xx8，而111、161、229、123均不命中任何模式。

老版本：Mock 应答场景（不同状态码相同应答）

enable_on_status: - 200 status_code: 200 headers: - Content-Type=application/json - Hello=World body: "{\"hello\":\"world\"}"

根据该配置，200 请求将返回自定义应答：

HTTP/1.1 200 OK Content-Type: application/json key1: value1 key2: value2 Content-Length: 21 {"hello":"world"}

触发限流时自定义响应

enable_on_status: - 429 status_code: 302 headers: - Location=https://example.com

触发网关限流时一般会返回429状态码，此时请求将返回自定义应答：

HTTP/1.1 302 Found Location: https://example.com

从而实现基于浏览器 302 重定向机制，将限流后的用户引导到其他页面，比如一个 CDN 上的静态页面。

如果希望触发限流时返回其他应答（而非重定向），参考上述 Mock 应答场景配置相应的status_code、headers与body字段即可。

配置注意事项与校验规则

结合源码与测试，以下边界情况会导致插件启动失败（对应测试见 main_extra_test.go）：

• headers中某项缺少=：SplitN(v, "=", 2)无法拆出 key/value，报错invalid header pair format；
• status_code非数字或超出 100-599 范围：解析报错，-1、99、600等均被拒绝；
• 同一enable_on_status被多条规则重复使用：报错enableOnStatus can only use once；
• 新版本rules数组为空：既无默认规则也无状态码映射时，报错no valid config is found；
• 上游响应缺少:status头：插件采取 fail-soft 策略，仅记录日志并放行（返回ActionContinue），不会发送本地应答，见 main_extra_test.go。

运行与调试

插件源码位于 plugins/wasm-go/examples/custom-response，版本号见 VERSION（当前为 1.1.0）。仓库提供了本地联调环境：

• docker-compose.yaml：拉起 Higress gateway（Envoy）+ echo-server，将编译产物plugin.wasm挂载到/etc/envoy/plugin.wasm，并可通过--component-log-level wasm:debug开启 Wasm 插件 debug 日志；
• envoy.yaml：配置了wasmdemoWasm HTTP 过滤器，内嵌了多组注释/启用的配置样例（多规则精确匹配、40x模糊匹配、单规则默认应答等），可直接切换验证上述所有场景；
• main_test.go 与 main_extra_test.go：覆盖配置解析、请求/响应头阶段的规则命中、模糊匹配矩阵以及各类错误路径，是理解插件行为与回归验证的最佳参考。

整体实现基于 Higress 的 wasm-go 插件框架（github.com/higress-group/proxy-wasm-go-sdk与github.com/higress-group/wasm-go），核心通过proxywasm.SendHttpResponseWithDetail在认证阶段（请求头/响应头回调）直接向客户端下发本地应答，从而实现零上游访问的 Mock 与状态码改写能力。

【免费下载链接】higress🤖 AI Gateway | AI Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/hi/higress