如何通过sub_filter在网关层动态调整缓存JSON资源域名解析？
- 内容介绍
- 文章标签
- 相关推荐
本文共计881个文字，预计阅读时间需要4分钟。
可以通过Nginx的sub_filter指令在反向代理响应前对客户端返回的内容（包括JSON）进行字符串替换，从而动态修正其中的域名。关键在于确保响应可被处理、替换精准且不影响JSON结构。
确保响应满足 sub_filter 处理前提
sub_filter 默认只处理 text/html 类型响应，而 JSON 通常返回 application/json。需显式启用对 JSON 的处理：
- 在 location 块中添加
sub_filter_types application/json; - 确认后端响应头未设置
Content-Encoding: gzip（压缩内容无法被 sub_filter 处理），必要时在 proxy_pass 前加proxy_set_header Accept-Encoding "";禁用压缩 - 确保响应体未被分块传输干扰（Nginx 1.9.4+ 默认支持流式 sub_filter，但建议配合
sub_filter_last_modified off;避免缓存头冲突）
精准替换 JSON 中的域名字段
JSON 是结构化文本，直接全局替换易出错（如误改字段名或数值）。推荐按语义定位替换：
- 只替换明确字段值：例如将
"avatar": "https://old.example.com/u/123.jpg"中的域名换成新地址，可用正则式sub_filter '"avatar":\s*"[^"]*://old\.example\.com';—— 但注意sub_filter不支持正则，只能用字面量；因此更稳妥的是约定格式，如统一使用https://old.example.com开头，再用sub_filter 'https://old.example.com' 'https://new.example.com'; - 避免跨字段污染：确保替换字符串不包含引号、逗号或斜杠等 JSON 特殊字符，否则可能破坏结构；例如不要替换
old.example.com为new.example.com/api/v1，除非原始字段值已预留足够路径空间 - 若需多处替换（如 avatar、cover、cdn_url），可链式使用多个
sub_filter指令，Nginx 会按顺序执行
配合缓存与 header 控制行为
动态修改响应后，需防止旧缓存干扰或触发不一致：
- 清除或绕过 ETag：添加
proxy_hide_header ETag;和sub_filter_once off;（允许多次替换），因为修改响应体后 ETag 已失效 - 重写 Cache-Control：若原响应带
Cache-Control: public, max-age=3600，修改后建议降级为private或缩短时间，避免下游缓存错误内容；可用add_header Cache-Control "public, max-age=60";覆盖 - 确保 sub_filter 在 proxy_buffering on 时仍生效：默认开启，无需额外配置；但若关闭 buffering，需确认响应完整到达后再处理（一般不建议关）
验证与调试技巧
上线前务必验证替换是否生效且 JSON 仍合法：
- 用
curl -H 'Accept: application/json' http://gateway/api/user获取原始响应，再对比启用 sub_filter 后输出 - 检查响应头中是否有
X-Sub-Filtered: true（可自定义添加用于调试：add_header X-Sub-Filtered "true" always;） - 用
jq校验 JSON：如curl ... | jq .avatar看值是否更新且无解析错误 - 注意大小写和协议：HTTP 和 HTTPS 域名需分别替换，
sub_filter 'http://old.example.com' 'https://new.example.com';和sub_filter 'https://old.example.com' 'https://new.example.com';需同时存在
本文共计881个文字，预计阅读时间需要4分钟。
可以通过Nginx的sub_filter指令在反向代理响应前对客户端返回的内容（包括JSON）进行字符串替换，从而动态修正其中的域名。关键在于确保响应可被处理、替换精准且不影响JSON结构。
确保响应满足 sub_filter 处理前提
sub_filter 默认只处理 text/html 类型响应，而 JSON 通常返回 application/json。需显式启用对 JSON 的处理：
- 在 location 块中添加
sub_filter_types application/json; - 确认后端响应头未设置
Content-Encoding: gzip（压缩内容无法被 sub_filter 处理），必要时在 proxy_pass 前加proxy_set_header Accept-Encoding "";禁用压缩 - 确保响应体未被分块传输干扰（Nginx 1.9.4+ 默认支持流式 sub_filter，但建议配合
sub_filter_last_modified off;避免缓存头冲突）
精准替换 JSON 中的域名字段
JSON 是结构化文本，直接全局替换易出错（如误改字段名或数值）。推荐按语义定位替换：
- 只替换明确字段值：例如将
"avatar": "https://old.example.com/u/123.jpg"中的域名换成新地址，可用正则式sub_filter '"avatar":\s*"[^"]*://old\.example\.com';—— 但注意sub_filter不支持正则，只能用字面量；因此更稳妥的是约定格式，如统一使用https://old.example.com开头，再用sub_filter 'https://old.example.com' 'https://new.example.com'; - 避免跨字段污染：确保替换字符串不包含引号、逗号或斜杠等 JSON 特殊字符，否则可能破坏结构；例如不要替换
old.example.com为new.example.com/api/v1，除非原始字段值已预留足够路径空间 - 若需多处替换（如 avatar、cover、cdn_url），可链式使用多个
sub_filter指令，Nginx 会按顺序执行
配合缓存与 header 控制行为
动态修改响应后，需防止旧缓存干扰或触发不一致：
- 清除或绕过 ETag：添加
proxy_hide_header ETag;和sub_filter_once off;（允许多次替换），因为修改响应体后 ETag 已失效 - 重写 Cache-Control：若原响应带
Cache-Control: public, max-age=3600，修改后建议降级为private或缩短时间，避免下游缓存错误内容；可用add_header Cache-Control "public, max-age=60";覆盖 - 确保 sub_filter 在 proxy_buffering on 时仍生效：默认开启，无需额外配置；但若关闭 buffering，需确认响应完整到达后再处理（一般不建议关）
验证与调试技巧
上线前务必验证替换是否生效且 JSON 仍合法：
- 用
curl -H 'Accept: application/json' http://gateway/api/user获取原始响应，再对比启用 sub_filter 后输出 - 检查响应头中是否有
X-Sub-Filtered: true（可自定义添加用于调试：add_header X-Sub-Filtered "true" always;） - 用
jq校验 JSON：如curl ... | jq .avatar看值是否更新且无解析错误 - 注意大小写和协议：HTTP 和 HTTPS 域名需分别替换，
sub_filter 'http://old.example.com' 'https://new.example.com';和sub_filter 'https://old.example.com' 'https://new.example.com';需同时存在