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 应答 Bodybody典型应用场景有两种Mock 响应不访问真实上游直接由网关返回模拟数据按状态码定制应答判断上游或网关内部限流策略返回的特定状态码后替换为自定义响应例如触发网关限流策略时返回 302 重定向到降级页面。运行属性属性值插件执行阶段认证阶段Authentication Phase插件执行优先级910插件在认证阶段以 910 的优先级参与请求处理因此可以在限流等前置插件产生429之后再对本已发出的响应进行改写。配置字段说明新版本支持多种返回rules 数组新版本配置通过rules规则组支持同一次配置针对不同原始状态码返回不同应答。名称数据类型填写要求默认值描述rulesarray of object必填-规则组rules中每个规则的配置字段如下名称数据类型填写要求默认值描述status_codenumber选填200自定义 HTTP 应答状态码headersarray of string选填-自定义 HTTP 应答头key 和 value 用分隔bodystring选填-自定义 HTTP 应答 Bodyenable_on_statusarray of string or number选填-匹配原始状态码生成自定义响应。可填写精确值如200、404等也可模糊匹配如2xx匹配 200-299、20x匹配 200-209x代表任意一位数字。不填写时不判断原始状态码取第一个enable_on_status为空的规则作为默认规则从源码看配置解析在 main.go 的parseConfig中完成当配置中存在rules且为数组时走新版本逻辑逐条解析规则并将第一个enable_on_status为空的规则记为默认规则defaultRule同时把每个enable_on_status条目与规则建立映射enableOnStatusRuleMap同一状态码不能被两条规则重复使用否则插件启动直接失败返回错误enableOnStatus can only use once。模糊匹配规则模糊匹配模式需同时满足三个条件长度为 3至少一位数字至少一位x不区分大小写规则匹配内容40x400-409前两位为 40 的情况1x4104,114,124,134,144,154,164,174,184,194第一位和第三位分别为 1 和 4 的情况x23023,123,223,323,423,523,623,723,823,923第二位和第三位为 23 的情况4xx400-499第一位为 4 的情况x4x040-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_codenumber选填200自定义 HTTP 应答状态码headersarray of string选填-自定义 HTTP 应答头key 和 value 用分隔bodystring选填-自定义 HTTP 应答 Bodyenable_on_statusarray of number选填-匹配原始状态码生成自定义响应不填写时不判断原始状态码老版本配置在解析时会被自动包装成单条规则并作为默认规则处理见 main.go因此新旧两种写法可以平滑兼容。匹配优先级精确匹配 模糊匹配 默认配置第一个enable_on_status为空的配置该优先级在响应头处理阶段体现onHttpResponseHeadersmain.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: - key1value1 - key2value2 status_code: 200 - body: {hello:world 404} enable_on_status: - 404 headers: - key1value1 - key2value2 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; charsetutf-8否则为text/plain; charsetutf-8Content-Length则由代理按实际 Body 重新计算配置中的content-length响应头会被忽略。新版本模糊匹配场景rules: - body: {hello:world 200} enable_on_status: - 200 headers: - key1value1 - key2value2 status_code: 200 - body: {hello:world 40x} enable_on_status: - 40x headers: - key1value1 - key2value2 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命中x01203、213命中2x3450、451命中45x600、611、612命中6xx171命中x7x228命中xx8而111、161、229、123均不命中任何模式。老版本Mock 应答场景不同状态码相同应答enable_on_status: - 200 status_code: 200 headers: - Content-Typeapplication/json - HelloWorld 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: - Locationhttps://example.com触发网关限流时一般会返回429状态码此时请求将返回自定义应答HTTP/1.1 302 Found Location: https://example.com从而实现基于浏览器 302 重定向机制将限流后的用户引导到其他页面比如一个 CDN 上的静态页面。如果希望触发限流时返回其他应答而非重定向参考上述 Mock 应答场景配置相应的status_code、headers与body字段即可。配置注意事项与校验规则结合源码与测试以下边界情况会导致插件启动失败对应测试见 main_extra_test.goheaders中某项缺少SplitN(v, , 2)无法拆出 key/value报错invalid header pair formatstatus_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 gatewayEnvoy 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 应答 Bodybody典型应用场景有两种Mock 响应不访问真实上游直接由网关返回模拟数据按状态码定制应答判断上游或网关内部限流策略返回的特定状态码后替换为自定义响应例如触发网关限流策略时返回 302 重定向到降级页面。运行属性属性值插件执行阶段认证阶段Authentication Phase插件执行优先级910插件在认证阶段以 910 的优先级参与请求处理因此可以在限流等前置插件产生429之后再对本已发出的响应进行改写。配置字段说明新版本支持多种返回rules 数组新版本配置通过rules规则组支持同一次配置针对不同原始状态码返回不同应答。名称数据类型填写要求默认值描述rulesarray of object必填-规则组rules中每个规则的配置字段如下名称数据类型填写要求默认值描述status_codenumber选填200自定义 HTTP 应答状态码headersarray of string选填-自定义 HTTP 应答头key 和 value 用分隔bodystring选填-自定义 HTTP 应答 Bodyenable_on_statusarray of string or number选填-匹配原始状态码生成自定义响应。可填写精确值如200、404等也可模糊匹配如2xx匹配 200-299、20x匹配 200-209x代表任意一位数字。不填写时不判断原始状态码取第一个enable_on_status为空的规则作为默认规则从源码看配置解析在 main.go 的parseConfig中完成当配置中存在rules且为数组时走新版本逻辑逐条解析规则并将第一个enable_on_status为空的规则记为默认规则defaultRule同时把每个enable_on_status条目与规则建立映射enableOnStatusRuleMap同一状态码不能被两条规则重复使用否则插件启动直接失败返回错误enableOnStatus can only use once。模糊匹配规则模糊匹配模式需同时满足三个条件长度为 3至少一位数字至少一位x不区分大小写规则匹配内容40x400-409前两位为 40 的情况1x4104,114,124,134,144,154,164,174,184,194第一位和第三位分别为 1 和 4 的情况x23023,123,223,323,423,523,623,723,823,923第二位和第三位为 23 的情况4xx400-499第一位为 4 的情况x4x040-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_codenumber选填200自定义 HTTP 应答状态码headersarray of string选填-自定义 HTTP 应答头key 和 value 用分隔bodystring选填-自定义 HTTP 应答 Bodyenable_on_statusarray of number选填-匹配原始状态码生成自定义响应不填写时不判断原始状态码老版本配置在解析时会被自动包装成单条规则并作为默认规则处理见 main.go因此新旧两种写法可以平滑兼容。匹配优先级精确匹配 模糊匹配 默认配置第一个enable_on_status为空的配置该优先级在响应头处理阶段体现onHttpResponseHeadersmain.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: - key1value1 - key2value2 status_code: 200 - body: {hello:world 404} enable_on_status: - 404 headers: - key1value1 - key2value2 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; charsetutf-8否则为text/plain; charsetutf-8Content-Length则由代理按实际 Body 重新计算配置中的content-length响应头会被忽略。新版本模糊匹配场景rules: - body: {hello:world 200} enable_on_status: - 200 headers: - key1value1 - key2value2 status_code: 200 - body: {hello:world 40x} enable_on_status: - 40x headers: - key1value1 - key2value2 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命中x01203、213命中2x3450、451命中45x600、611、612命中6xx171命中x7x228命中xx8而111、161、229、123均不命中任何模式。老版本Mock 应答场景不同状态码相同应答enable_on_status: - 200 status_code: 200 headers: - Content-Typeapplication/json - HelloWorld 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: - Locationhttps://example.com触发网关限流时一般会返回429状态码此时请求将返回自定义应答HTTP/1.1 302 Found Location: https://example.com从而实现基于浏览器 302 重定向机制将限流后的用户引导到其他页面比如一个 CDN 上的静态页面。如果希望触发限流时返回其他应答而非重定向参考上述 Mock 应答场景配置相应的status_code、headers与body字段即可。配置注意事项与校验规则结合源码与测试以下边界情况会导致插件启动失败对应测试见 main_extra_test.goheaders中某项缺少SplitN(v, , 2)无法拆出 key/value报错invalid header pair formatstatus_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 gatewayEnvoy 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考