API网关后端云原生【免费下载链接】tykOpen Source API and AI Gateway supporting REST, GraphQL, TCP, gRPC and MCP (Model Context Protocol)项目地址https://gitcode.com/gh_mirrors/ty/tyk点击查看免费下载Tyk Gateway 的error_overrides功能允许运维与平台团队将网关生成的各种错误认证失败、限流、TLS 故障、上游超时等统一替换为自定义的响应体、HTTP 状态码与响应头从而向客户端输出一致的错误契约。本文以仓库内 ci/tests/error-overrides 这套 CI 端到端测试为骨架完整讲解它的目录结构、测试运行方式、覆盖的错误分类 Flag、tyk.conf与 API 定义两级配置写法并深入到 gateway/error_overrides.go 与 apidef/error_overrides.go 的源码实现说明匹配与覆盖的底层原理。读完本文你将能独立搭建并运行这套测试理解匹配优先级、模板渲染与常见环境差异并能在自己的网关环境中复刻同样的错误覆盖策略。这套测试是什么Error Overrides 的 CI 回归保障error_overrides错误覆盖解决的核心问题是网关内部产生的错误响应不可控。例如认证失败返回 400 还是 401、限流被拒返回什么 JSON、上游 TLS 证书过期返回什么错误信息在不同中间件、不同版本下可能各不相同。通过错误覆盖可以在网关级别全局与API 定义级别单 API两个维度配置规则命中某错误分类 Flag如RLT限流、TLETLS 证书过期后将原始响应替换为指定的状态码、Body 与 Header。ci/tests/error-overrides 目录正是为这一功能提供的端到端回归测试套件它拉起真实 Gateway 容器和一批模拟故障的后端服务逐一触发各种错误分类然后断言响应体包含预期的覆盖内容响应头包含自定义错误 Flag如X-Error-FlagHTTP 状态码被正确覆盖如 400 → 413、500 → 502访问日志access log中仍然记录正确的response_flag——这一点很关键覆盖的是客户端看到的响应但审计与监控所需的错误分类信息不能丢失。测试套件结构每个目录的职责ci/tests/error-overrides/ ├── apps/ # 待测试的 API 定义JSON每个错误场景一个 API ├── configs/ # 网关配置 │ ├── tyk.conf # 启用了 error_overrides 的网关配置全局覆盖规则 │ └── nginx-ok.conf # 健康后端 nginx 配置 ├── policies/ # 策略定义供 OAuth 等场景使用 ├── scripts/ # 测试执行脚本 │ └── run-override-tests.sh # 核心测试脚本约 1800 行 ├── templates/ # 错误响应模板文件模板与内联模板测试用 ├── docker-compose.yml # 测试环境编排网关 Redis 多个故障后端 证书生成器 ├── test.sh # CI 入口脚本 ├── Taskfile.yml # Task 任务定义setup / test / teardown 等 └── README.md # 本文件其中 configs/tyk.conf 负责承载网关级全局覆盖规则apps/下约 40 个 API 定义则用来分别触发不同的错误分类其中部分 API如test-api-override-aki.json在自身定义里携带error_overrides用于验证API 级覆盖与网关级覆盖的优先级。如何运行CI 与本地两种方式在 CI 中运行test.sh会被.github/workflows/release-tests.yml中的ci-tests任务自动发现并执行。CI 通过环境变量注入待测的 Gateway 镜像# CI 设置 GATEWAY_IMAGE 环境变量 export GATEWAY_IMAGEecr-registry/tyk:sha-commit ./test.shtest.sh 的逻辑很简短先setup默认 tag 为v0.0.0若本地没有该镜像则先docker pull随后通过trap task teardown EXIT保证退出时清理环境再依次执行task setup、task info、task test。本地运行cd ci/tests/error-overrides # 指定一个具体的网关镜像版本 export TYK_GATEWAY_IMAGEtykio/tyk-gateway:v5.3 ./test.sh # 或者使用默认镜像 ./test.sh实际驱动测试的底层命令是 Taskfile.yml 中定义的 Tasktask deps校验templates/error_upstream.json、templates/error_validation.json等测试依赖模板存在task setup先执行clean-certs清理证书避免过期/不匹配的脏数据再用docker compose up -d --force-recreate拉起整个环境task test导出TYK_OVERRIDE_URL、容器名与日志文件路径后调用./scripts/run-override-tests.sh runtask teardowndocker compose down --remove-orphans --volumes彻底清理。测试脚本的使用方式scripts/run-override-tests.sh 支持三个子命令./scripts/run-override-tests.sh run # 运行全部错误覆盖测试默认 ./scripts/run-override-tests.sh check # 仅做前置检查网关是否可用 ./scripts/run-override-tests.sh help # 查看用法它支持三个环境变量TYK_OVERRIDE_URL网关地址默认http://localhost:8081、TYK_OVERRIDE_CONTAINER网关容器名默认test-access-logs-tyk-gateway-overrides-1、TYK_LOG_FILE访问日志存放路径默认/tmp/tyk-override-access.log。注意 Taskfile 里task test会把 URL 覆盖为http://localhost:8080并动态解析容器名说明两处入口的默认值不同以实际注入为准。测试覆盖的错误分类从 4xx 到 5xx 的完整 Flag 矩阵测试套件依据错误分类 Flag 组织测试用例。Flag 定义在 internal/errors/classification.go是标准化的错误分类编码。README 中列出的覆盖范围如下4xx 错误AMF认证字段缺失、AKIAPI Key 无效、RLT限流、QEX配额超限、BTL请求体过大、CLM缺少 Content-Length、BIV请求体非法、IHD请求头非法、TKIToken 无效、TKEToken 过期、EAD外部认证被拒5xx 错误TLETLS 证书过期、TLITLS 证书无效、TLMTLS 主机名不匹配、TLNTLS 证书不受信任、TLHTLS 握手失败、TLPTLS 协议错误、UCF上游连接失败、URT上游请求超时、URR上游请求被拒、UPE上游协议错误、DNSDNS 解析失败、NRH无路由到主机其他CBO熔断器打开、NHU无健康上游、CDC客户端断开classification.go中还有UCT上游连接超时、EPI管道断裂、CAB连接中止、NRS网络重置、CRQ需要证书、CMM证书不匹配、URS上游 5xx 通用等 Flag 参与测试。每个测试用例通过统一的run_override_test函数执行其参数为测试名、API 路径、期望的response_flag、期望响应体包含的字符串、期望的X-Error-Flag头值、期望状态码可选以及附加 curl 参数。每次请求后脚本会等待 3 秒WAIT_FOR_LOG_SECONDS通过docker logs刷新访问日志再用grep -E prefixaccess-log提取对应api_id的日志条目最后用sed从response_flag字段中解析出实际 Flag 与期望值比对。全局配置tyk.conf 中的 error_overrides配置结构configs/tyk.conf 中启用了完整的全局覆盖规则。其 JSON 结构为顶层error_overrides是一个以状态码字符串为键、以规则数组为值的 Map每条规则由match匹配条件可选与response覆盖响应必填组成{ error_overrides: { 429: [ { match: {flag: RLT}, response: { status_code: 429, body: {\error\: \rate_limit_exceeded\, \code\: \RATE_LIMITED\, \flag\: \RLT\, \retry_after\: 60}, headers: { X-Error-Flag: RLT, X-Override-Applied: true, Retry-After: 60 } } } ] } }这条规则的含义当网关产生 429 状态码、且错误分类 Flag 为RLT时返回上面这段 JSON 响应体并附带X-Error-Flag: RLT、X-Override-Applied: true、Retry-After: 60三个自定义响应头。数据模型与字段说明对应源码 apidef/error_overrides.goErrorOverridesMap即map[string][]ErrorOverride键是状态码字符串ErrorOverride由可选的Match *ErrorMatcher与必填的Response ErrorResponse组成ErrorMatcher支持三类匹配条件flag匹配请求上下文中的错误分类 Flagerrors.ResponseFlag类型message_pattern对响应体做正则匹配加载时会预编译编译失败会告警并跳过该规则body_fieldbody_value用 gjson 语法从 JSON 响应体中提取字段并比对值ErrorResponse包含四个字段status_code覆盖后的状态码body响应体可以是字面 JSON 字符串也可以内联模板含{{.StatusCode}}、{{.Message}}等变量message语义化错误消息作为模板变量{{.Message}}传入template引用templates/目录下的模板文件如error_upstream、error_validationheaders附加的响应头 Map。全局配置中的典型规则样例以下是从tyk.conf中提炼的代表性规则覆盖了多种覆盖形态状态码改写400 → 413BTL请求体过大规则将状态码从 400 改写为 413并返回payload_too_large语义体400: [ { match: {flag: BTL}, response: { status_code: 413, body: {\error\: \payload_too_large\, \code\: \BODY_TOO_LARGE\, \flag\: \BTL\}, headers: {X-Error-Flag: BTL, X-Override-Applied: true} } } ]模板文件渲染500 → 502TLITLS 证书无效规则使用template: error_upstream指向文件模板并把语义消息传给模板500: [ { match: {flag: TLI}, response: { status_code: 502, template: error_upstream, message: TLS certificate is invalid or not properly configured, headers: { X-Error-Flag: TLI, X-Override-Applied: true, X-Template-Type: file } } } ]对应模板文件 templates/error_upstream.json 内容为{ type: https://tyk.io/errors/upstream-error, title: Upstream Service Error, status: {{.StatusCode}}, detail: {{.Message}} }内联模板与变量替换TLMTLS 主机名不匹配规则直接在body中嵌入模板变量{ match: {flag: TLM}, response: { status_code: 502, body: {\error\: \tls_hostname_mismatch\, \status\: {{.StatusCode}}, \message\: \{{.Message}}\, \type\: \inline_template\}, message: TLS certificate hostname does not match target, headers: {X-Error-Flag: TLM, X-Override-Applied: true, X-Template-Type: inline} } }仅消息message-onlyTLN证书不受信任规则只提供message由网关默认模板渲染{ match: {flag: TLN}, response: { status_code: 502, message: TLS certificate is not trusted by the gateway, headers: {X-Error-Flag: TLN, X-Override-Applied: true, X-Template-Type: message-only} } }仅头部headers-onlyTLHTLS 握手失败规则完全不改 Body只追加自定义头{ match: {flag: TLH}, response: { status_code: 502, headers: { X-Error-Flag: TLH, X-Override-Applied: true, X-Template-Type: headers-only, X-Error-Category: tls, X-Error-Detail: handshake-failed } } }通配状态码5xxURS上游 5xx 通用规则挂在5xx前缀键下任何 5xx 状态码未命中精确规则时都会回落到它5xx: [ { match: {flag: URS}, response: { status_code: 503, message: Upstream service error occurred, headers: {X-Error-Flag: URS, X-Override-Applied: true} } } ]基于响应体内容的匹配404下的两条规则分别演示body_field/body_value上游返回{error:{code:RESOURCE_NOT_FOUND}}时命中与message_pattern响应体匹配(?i)page not found时命中并渲染error_validation模板404: [ { match: {body_field: error.code, body_value: RESOURCE_NOT_FOUND}, response: { status_code: 404, body: {\error\: \resource_not_found\, \message\: \The requested resource was not found\}, headers: {X-Error-Flag: NOT_FOUND, X-Override-Applied: true} } }, { match: {message_pattern: (?i)page not found}, response: { status_code: 404, template: error_validation, message: The requested page does not exist, headers: {X-Error-Flag: PAGE_NOT_FOUND, X-Override-Applied: true} } } ]API 级覆盖与优先级单 API 定义内的 error_overrides除了网关全局配置还可以在单个 API 定义中声明error_overrides实现某些 API 用特殊错误契约的诉求。以 apps/test-api-override-aki.json 为例{ name: Test API Override Precedence, api_id: test-api-override-aki, use_keyless: false, auth: {auth_header_name: Authorization}, proxy: { listen_path: /test-api-override-aki/, target_url: http://backend-ok:80, strip_listen_path: true }, error_overrides: { 403: [ { match: {flag: AKI}, response: { status_code: 418, body: {\error\: \api_level_override\, \flag\: \AKI\}, headers: {X-Error-Flag: AKI-API, X-Override-Applied: true} } } ] } }这个 API 把 AKI 错误覆盖为状态码418而网关全局规则是 403并输出X-Error-Flag: AKI-API。测试套件据此验证了三层行为API 级优先请求/test-api-override-aki/get传入非法 Key返回 418、api_level_override与AKI-API头——API 级规则压过网关全局规则未匹配则回退全局同一 API 缺认证AMF 而非 AKI时API 级没有对应规则回落到网关全局的 AMF 规则返回 401 与authentication_required未配置则用全局/test-api-override-disabled/get未在 API 定义中声明覆盖AKI 错误按全局规则返回 403 与invalid_api_key。这与 gateway/error_overrides.go 中ApplyOverride的实现完全对应见下文原理部分先查 API 级编译结果命中即返回未命中再查网关级编译结果。源码级原理匹配、编译与覆盖的执行链路编译阶段O(1) 索引与预编译CompileErrorOverridesgateway/error_overrides.go在网关配置加载与 API 加载时被调用产出CompiledErrorOverridesByExactCode map[int][]*apidef.ErrorOverride精确状态码索引ByPrefix map[int][]*apidef.ErrorOverride前缀索引如4xx、5xx。编译期间会做三件事逐规则校验并编译message_pattern正则失败则记录 warning 并跳过该规则、预编译内联 Body 模板text/template 与 html/template 两份按响应 Content-Type 选择、建立状态码索引从而在请求路径上实现 O(1) 的状态码定位。匹配阶段精确码优先、前缀兜底、规则按序首中findMatchingRuleGenericgateway/error_overrides.go的匹配顺序是先查ByExactCode[statusCode]精确状态码未命中再查ByPrefix[statusCode/100]如 502 会查5xx通配规则同一状态码下的多条规则按声明顺序逐个求值首个命中即胜出first match wins。应用阶段网关级与 API 级的两级回退ApplyOverridegateway/error_overrides.go体现了两级覆盖的优先级逻辑if apiCompiled ! nil { if rule : o.findMatchingRule(r, apiCompiled, statusCode, body); rule ! nil { return o.createOverrideResult(rule, statusCode) } } if gwCompiled ! nil { if rule : o.findMatchingRule(r, gwCompiled, statusCode, body); rule ! nil { return o.createOverrideResult(rule, statusCode) } }即API 级规则先于网关全局规则匹配API 级未命中才回退到网关级。createOverrideResult会把原始状态码保存在OverrideResult.OriginalCode并携带命中的规则供模板渲染使用。匹配条件的附加校验matchesAdditionalCriteria与matchFlag、matchMessagePattern、matchBodyField负责在状态码命中的基础上进一步校验match条件flag直接与请求上下文中的errors.ResponseFlag比对message_pattern用预编译正则作用于响应体body_field用 gjson 提取 JSON 字段并与body_value比对。值得注意的是 gateway/error_overrides.go 中定义了maxBodySizeForMatching 40964KB上游返回的超大错误体HTML、堆栈在正则/JSON 路径匹配前会被截断到 4KB避免大体积正则匹配的性能问题测试中的/500-truncation场景正是验证该边界——上游返回超过 4KB 的响应体时API 级匹配因截断跳过但网关全局的URS规则基于 Flag不依赖 Body仍然命中。测试环境的故障后端编排如何真实触发每种错误docker-compose.yml 是整个测试能真实触发错误的关键。它编排了 Gateway、Redis以及一组专门制造故障的后端backend-ok健康 nginx 后端用于正常流量与认证/限流类错误backend-slow所有请求延迟 120 秒的 Python 后端用于触发上游请求超时URTbackend-multi-error可路由返回 400/404/500/502/503/504、404 JSON、404 HTML、超大 4KB 响应体的多场景后端覆盖URS、body_field、message_pattern、截断等用例backend-reset收到请求后通过SO_LINGER发送 RST 而非 FIN 的 TCP 后端触发URR连接重置backend-malformed返回非 HTTP 垃圾字节触发UPE上游协议错误backend-tls-handshake-fail对 TLS ClientHello 返回协议版本告警字节触发TLH四个 TLS 后端backend-tls-expired/selfsigned/wronghost/invalid分别用过期证书、自签证书、主机名不匹配证书、key usage 错误的 CA 签名证书触发TLE/TLN/TLM/TLIcert-generator一次性容器用 openssl 生成全部测试证书注意它特意给过期证书与自签证书加上 SAN 扩展——因为没有 SAN 时 Go 的 TLS 栈会先报 HostnameError归类为 TLM根本走不到过期/不受信任的检查这是测试编写者踩过的坑也是复现 TLS 类错误时最容易忽略的细节。每个 TLS 后端的 nginx 配置都在容器启动时动态生成等待证书就绪后写入/etc/nginx/conf.d/default.conf保证了证书与服务的时序一致性。测试脚本的实现细节断言与特殊用例run-override-tests.sh的核心函数run_override_test用 curl 发送请求支持附加头参数随后进行五重断言Body 包含期望字符串、X-Error-Flag头正确、X-Override-Applied: true存在、状态码匹配若指定、访问日志中response_flag正确。脚本还针对复杂场景实现了专用函数run_override_test_rate_limit先发一次请求耗尽 1 次/分钟的全局限流对应 apps/test-rlt.json 的global_rate_limit第二次请求断言 429 与Retry-After: 60run_override_test_large_body发送超过 10 字节限制的 POST断言 413 状态码改写400 → 413run_override_test_invalid_json/run_override_test_biv_invalid_params发送非法 JSON 与 schema 校验失败请求断言BIV覆盖并额外做两个回归断言——模板中的{{.InvalidParams}}变量能正确渲染出校验器错误明细且单引号不会被 HTML 实体编码为#39;对应 templates/error_validation_invalid_params.jsonrun_override_test_no_content_length用Transfer-Encoding: chunked发请求无 Content-Length断言CLMrun_override_test_quota_exceeded通过网关 Admin APIPOST /tyk/keys/create创建配额为 1 的 Key用完配额后断言QEXrun_override_test_external_auth_denied创建 OAuth client、换取 token、删除 client 后再用旧 token断言EADrun_override_test_client_disconnected用 2 秒客户端超时请求 120 秒慢后端客户端先断开断言日志中出现CDCrun_override_test_circuit_breaker连续发送 10 次失败请求触发熔断阈值 10%、样本 3断言CBOrun_override_test_upstream_passthrough上游返回 400 且无规则命中时断言Body 原样透传、不出现X-Override-Applied头、状态码保持 400——这是对未命中不改写语义的负向验证。此外还有run_override_test_with_alternatives用于环境相关的用例如UCT连接超时在 Go 的 HTTP 客户端中context.DeadlineExceeded会被分类为URT而非UCTNRH无路由到主机在 Docker/macOS 环境中不可达 IP 通常表现为超时URT而非EHOSTUNREACH。脚本注释中明确记录了这些已知环境限制因此这类断言接受两个 Flag 中的任意一个体现了测试对运行环境差异的务实处理。测试结束后print_summary汇总 Passed / Failed / Skipped 计数只要FAILED为 0 即整体通过。在 CI 中的集成方式与适用前提这套测试的 CI 集成点是.github/workflows/release-tests.yml的ci-tests任务通过GATEWAY_IMAGE注入待验证的构建产物镜像保证每次发布前对error_overrides的改动做完整回归。本地复现时前提条件是安装了 Docker 与 Docker Compose能拉取tykio/tyk-gateway镜像或自定义 tag端口 8080/8081 及 5001–5011 等后端端口未被占用测试网络名固定为qa-test-network见 compose 文件末尾。由于test.sh的setup函数默认 tag 为v0.0.0本地手动运行时建议通过TYK_GATEWAY_IMAGE或GATEWAY_IMAGE显式指定一个真实存在的镜像版本例如tykio/tyk-gateway:v5.3。总结从 ci/tests/error-overrides 这套端到端测试可以完整看到 Tyk Gatewayerror_overrides功能的工程全貌全局与 API 级两级配置模型、基于错误分类 Flag 与状态码前缀的匹配机制、文件模板/内联模板/仅消息/仅头部四种响应形态、以及覆盖客户端响应但保留审计 Flag的设计原则。对应的 gateway/error_overrides.go 与 apidef/error_overrides.go 则从实现上印证了这些行为——精确码优先、前缀兜底、API 优先于全局、4KB 截断保护。对于需要在生产网关中统一错误契约的团队这套测试既是可直接运行的回归工具也是一份可对照参考的配置手册。赞分享API网关后端云原生【免费下载链接】tykOpen Source API and AI Gateway supporting REST, GraphQL, TCP, gRPC and MCP (Model Context Protocol)项目地址https://gitcode.com/gh_mirrors/ty/tyk点击查看免费下载相关推荐Open MCT e2e 测试指南基于 Playwright 的端到端测试架构、实践与 CI 集成Open MCT e2e 测试指南基于 Playwright 的端到端测试架构、实践与 CI 集成 导读 本文以 Open MCT 仓库中的 e2e/READ数据可视化前端WinUtil一条命令批量装软件、整理与修复 WindowsWinUtil一条命令批量装软件、整理与修复 Windows 大多数人装完 Windows 11 后从没打开过注册表却花了整整一下午找下载链接、和捆绑勾选作桌面应用运维react-error-boundary与CI/CD集成自动化测试流程react error boundary与CI/CD集成自动化测试流程 你是否还在为React应用的错误捕获和测试流程头疼当生产环境中出现白屏或崩溃时能否创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考