proxy-wasm-rust-sdk官方8大示例全解析：从Hello World到Envoy过滤状态一网打尽

proxy-wasm-rust-sdk官方8大示例全解析从Hello World到Envoy过滤状态一网打尽【免费下载链接】proxy-wasm-rust-sdkWebAssembly for Proxies (Rust SDK)项目地址: https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdkproxy-wasm-rust-sdk 是 Envoy 生态中用 Rust 编写 WebAssembly 代理过滤器Wasm Filter的官方 SDK让你无需修改 Envoy 源码即可用插件扩展网关能力。本文带你一次通关它的 8 个官方示例从最简单的 Hello World 定时日志到跨过滤器读取 Envoy 过滤状态Filter State/Metadata、再到 L4 层动态 TCP 路由每个示例都能用 Docker Compose 一键跑起来 为什么值得学Proxy-Wasm 插件模型速览在 Envoy 中一个 Wasm 插件由两类上下文组成这也是理解全部 8 个示例的钥匙RootContext根上下文负责插件生命周期如on_vm_startVM 启动、on_configure读取插件配置、定时任务on_tickHttpContext / StreamContext流上下文每个请求/连接一个实例负责处理请求头、响应头、请求体、响应体等回调所有示例统一编译目标为wasm32-wasip1构建命令一致cargo build --target wasm32-wasip1 --release然后把产物挂到 Envoy 中每个示例目录都自带docker-compose.yaml和envoy.yamldocker compose up即可体验完整链路。第一关Hello World —— 5分钟跑通第一个 Wasm 插件 示例位置examples/hello_world/核心代码见examples/hello_world/src/lib.rs这是所有 Proxy-Wasm 插件的最小可运行程序。它没有 HTTP 流量而是做两件事在on_vm_start中打印 Hello, World!并通过set_tick_period设置 5 秒定时任务在on_tick中周期性打印当前时间和一个随机数预期日志每 5 秒一行wasm log: Hello, World! wasm log: Its 2022-11-22 03:39:17.849616 UTC, your lucky number is 41.学到什么proxy_wasm::main!宏的注册方式、RootContext 的生命周期回调、定时任务机制——掌握它后面 7 个示例都是同一套骨架的变体。第二关HTTP 三件套——头、体、配置示例②http_headers —— 打印请求/响应全量头examples/http_headers/源码examples/http_headers/src/lib.rs向localhost:10000/hello发请求Envoy 日志会逐条打印所有请求头与响应头例如wasm log http_headers: #2 - :path: /hello wasm log http_headers: #2 - :method: GET wasm log http_headers: #2 - :status: 200 wasm log http_headers: #2 - powered-by: proxy-wasm学到什么如何在on_http_request_headers/on_http_response_headers回调中遍历、读取 HTTP 头是后续所有鉴权、改写类插件的基本功。示例③http_body —— 自动脱敏敏感响应体examples/http_body/源码examples/http_body/src/lib.rs访问/hello返回原文访问/secret时插件拦截响应体并整体替换为Original message body (50 bytes) redacted.学到什么on_http_response_body中读取、修改响应的分片数据body chunk。这是实现响应脱敏、内容过滤类安全插件的标准姿势。示例④http_config —— 从 Envoy 配置中读取参数examples/http_config/源码examples/http_config/src/lib.rs插件在on_configure中通过get_plugin_configuration读取 Envoy 配置里写入的字符串并在每个响应头中注入custom-header: The secret to life is meaningless unless you discover it yourself学到什么插件配置如何从envoy.yaml流转到 Rust 代码做到改配置不改二进制。第三关Callout 鉴权 —— 把决策权交给外部服务示例⑤http_auth_random —— HTTP 外呼决定放行或拦截examples/http_auth_random/源码examples/http_auth_random/src/lib.rs插件在处理请求前发起一次 HTTP callout外呼根据返回结果随机放行或拒绝放行正常返回上游 JSON 响应拒绝直接返回Access forbidden.并打印wasm log http_auth_random: Access forbidden.学到什么on_http_request_headers中返回Action::Pause暂停请求处理、发起dispatch_http_call并处理异步回调的完整鉴权流程。示例⑥grpc_auth_random —— gRPC 版鉴权examples/grpc_auth_random/源码examples/grpc_auth_random/src/lib.rs与示例⑤逻辑相同但外呼走 gRPC 协议hello.HelloService/SayHello。用 grpcurl 测试时被拒绝的请求会收到Code: Aborted Message: Aborted by Proxy-Wasm!学到什么同一套 callout 模型在 gRPC 场景下的差异——头部格式Content-Type: application/grpc与响应体处理。第四关Envoy 进阶——过滤状态与 L4 动态路由示例⑦envoy_filter_metadata —— 读取其他过滤器写入的 Metadataexamples/envoy_filter_metadata/源码examples/envoy_filter_metadata/src/lib.rs这是过滤器协同的教科书案例Lua 过滤器先把请求头x-custom-metadata的值大写化并写入 Envoy 的filter_metadata本插件通过get_property读取该元数据并直接构造响应curl localhost:10000 -H x-custom-metadata: some-value Custom response with Envoy metadata: SOME-VALUE同时响应头会带上uppercased-metadata: SOME-VALUE。学到什么Wasm 插件与 Envoy 生态Lua、OPA 等过滤器之间通过 Filter Metadata 交换数据的标准模式实现跨过滤器共享状态。示例⑧envoy_tcp_routing —— 基于源 IP 的 L4 动态路由 ⭐examples/envoy_tcp_routing/源码examples/envoy_tcp_routing/src/lib.rs配套协议定义examples/envoy_tcp_routing/src/set_envoy_filter_state.proto这是 8 个示例中最硬核的一个工作在TCP 流上下文L4而非 HTTP 层检查每条入站 TCP 连接取出源 IP 地址按最后一位八位组奇偶分流偶数 →egress-router1奇数 →egress-router2借助 Envoy 的set_envoy_filter_state外部函数在运行时动态改写默认 TCP Proxy 集群Docker 网络下用不同源 IP 发请求访问日志即可看到流量确实落在了不同上游集群。学到什么StreamContextTCP 流生命周期、get_listener_address/get_remote_address等主机调用、以及通过 Protobuf 编码调用 Envoy 私有外部函数的高阶玩法。8 大示例一张表 上手清单#示例核心能力关键回调1hello_world生命周期、定时任务on_vm_start/on_tick2http_headers读写 HTTP 头on_http_request/response_headers3http_body修改响应体、脱敏on_http_response_body4http_config读取插件配置on_configure5http_auth_randomHTTP callout 鉴权dispatch_http_call6grpc_auth_randomgRPC callout 鉴权dispatch_http_call7envoy_filter_metadata跨过滤器共享 Metadataget_property8envoy_tcp_routingL4 动态路由、Filter Stateon_connect/ 外部函数快速上手 3 步# 1. 克隆仓库 git clone https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdk # 2. 进入任意示例目录编译 cd examples/hello_world cargo build --target wasm32-wasip1 --release # 3. 一键启动 Envoy 插件 docker compose up小结 8 个示例正好构成一条完整学习路径生命周期 → HTTP 请求处理 → 配置注入 → 外部鉴权 → 过滤器协同 → L4 路由。它们全部位于examples/目录下每个都是可直接运行的独立工程配合根目录的README.md、DEVELOPMENT.md与CONTRIBUTING.md足够支撑你从零写出生产级 Envoy Wasm 插件。建议按上文顺序逐个跑通两周即可掌握 Rust Wasm 网关开发的核心技能 【免费下载链接】proxy-wasm-rust-sdkWebAssembly for Proxies (Rust SDK)项目地址: https://gitcode.com/gh_mirrors/pr/proxy-wasm-rust-sdk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考