源码深度学习 · 零基础友好 · higress-group 5/5（收官站）

wasm-go 源码学习

20 天 · 每天 30 分钟 · 逐层读懂 Higress 的 Go 语言 Wasm 插件开发 SDK——它让你用 Go 写网关插件（限流、鉴权、AI 处理…），编译成 Wasm 跑进 Envoy。这是 higress-group 系列的收官站：前四站教你网关怎么工作，这一站教你怎么给网关加自己的能力。

00

开篇 · 这是个什么项目

wasm-go（github.com/higress-group/wasm-go）是 Higress 官方的 Go 语言 Wasm 插件 SDK。你用 Go 写一个插件（比如"拦截含某关键词的请求"），用它提供的封装 SetCtx/ParseConfig/ProcessRequestHeaders 等，编译成 .wasm 文件，打成 OCI 镜像，Higress 网关就能加载运行。

🎯 一句话：wasm-go = proxy-wasm ABI 的 Go 友好封装。它把 Envoy 底层晦涩的 Wasm 宿主调用，包装成"填几个回调函数就能写插件"的极简 SDK。你只写业务逻辑，生命周期/配置解析/规则匹配/HTTP&Redis 调用 SDK 全帮你搞定。

🔌

极简插件模型

init 里 SetCtx 注册回调，填 parseConfig + 各阶段钩子即可。

🎯

规则匹配

RuleMatcher 按路由/域名/服务匹配不同配置。

📞

外部调用

HttpCall / RedisCall 异步调后端，回调式编程。

🤖

AI 能力

tokenusage 多协议解析 LLM Token 用量。

与前四站的关系（收官）：Envoy（数据面）里跑 Wasm 虚拟机，Istio/Higress（控制面）把插件配置下发下来。wasm-go 就是"写那些 Wasm 插件"的工具——你在 Higress Console（上一站）里配的插件，很多就是用 wasm-go 写的。源码在 higress-group/wasm-go/{pkg,examples}，是个只有约 2500 行的精悍 SDK。
01

架构全景（动起来看）

下图那颗发光小球是"一个请求进网关 → 触发你的 Wasm 插件 → 插件处理"的旅程。从上到下：请求 → Envoy Wasm VM → wasm-go SDK 封装 → 你的插件逻辑。

L1 · 请求进入 Envoy（数据面）
HTTP 请求headers/body
Wasm VM按线程克隆
proxy-wasm ABI宿主调用
L2 · wasm-go SDK 封装
CommonVmCtxVM 级
PluginCtx配置级
HttpContext请求级
L3 · 配置与匹配
ParseConfiggjson 解析
RuleMatcher路由/域名/服务
GetMatchConfig运行时匹配
L4 · 你的插件逻辑
各阶段钩子headers/body
外部调用Http/Redis
ActionContinue/Pause

写一个插件的心智模型是"注册回调 → 解析配置 → 匹配规则 → 处理请求 → 返回 Action"：

SetCtx注册回调→ ParseConfig解析 JSON→ GetMatchConfig匹配规则→ ProcessHeaders处理并返回 Action
Wasm 插件和网关怎么协作？ 网关（Envoy）为每个 worker 线程克隆一份 Wasm VM，请求到来时在对应阶段调用你插件的回调函数。你的插件不是独立进程，而是嵌进 Envoy 的一段沙箱代码——安全隔离、热插拔、多语言（Go/Rust/C++）。这正是前面 Envoy 课讲的 proxy-wasm 机制。
02

怎么用这份教程

⏱️

每天 30 分钟

一天一个独立页面，跟着"今日小结 + 动手"收尾。

👶

零基础友好

不假设你懂 Wasm/Go 泛型/回调式编程，术语首次出现都有大白话解释。

📍

精确到行号

关键代码标 文件:行号，可在真源码里跳转对照。

一条主线：从"写第一个插件、生命周期怎么走",到"配置怎么解析、规则怎么匹配",到"怎么处理 HTTP、怎么调外部 HTTP/Redis",最后是"日志/Leader 选举/AI Token/性能重建/构建部署"。建议先学完 Envoy 和 Higress。
W1

第 1 周 · 入门与生命周期

全景、第一个插件、proxy-wasm ABI、三级 Context、SetCtx 选项
01

项目全景（插件 SDK）

wasm-go 是什么、和 Envoy/Higress/proxy-wasm 的关系。

≈30 min开始学 →
02

第一个插件 request-block

main/init/SetCtx/ParseConfig/钩子全流程。

≈30 min开始学 →
03

proxy-wasm 与 ABI

Wasm 虚拟机、宿主调用、下行/上行钩子。

≈30 min开始学 →
04

三级 Context

CommonVmCtx/PluginCtx/HttpContext + iface 接口。

≈30 min开始学 →
05

SetCtx 与函数式选项

CtxOption 模式、8 个 Process* 钩子、新旧 API。

≈30 min开始学 →
W2

第 2 周 · 配置与匹配

配置解析、RuleMatcher、运行时匹配、全局vs规则、生命周期
06

配置解析

ParseConfig 家族、gjson、raw/context 变体。

≈30 min开始学 →
07

RuleMatcher 规则匹配

_rules_、四种 category、匹配数据结构。

≈30 min开始学 →
08

运行时匹配 GetMatchConfig

按 :authority/route_name/cluster_name 选配置。

≈30 min开始学 →
09

全局配置 vs 规则配置

ParseOverrideConfig、规则级隔离容错。

≈30 min开始学 →
10

OnPluginStart 生命周期

配置加载、pluginID、tick 注册、IO 限流。

≈30 min开始学 →
W3

第 3 周 · HTTP 与外部调用

HTTP 钩子、HttpContext、Cluster、HttpCall、RedisCall
11

HTTP 请求/响应钩子

headers/body/streaming/streamDone、Action 语义。

≈30 min开始学 →
12

HttpContext 能力

UserAttribute/自定义日志/DontReadBody/RouteCall。

≈30 min开始学 →
13

Cluster 集群抽象

8 种集群：Route/K8s/Nacos/FQDN/Static/Dns/Consul。

≈30 min开始学 →
14

HTTP 外部调用

HttpCall/ClusterClient、异步回调、Pause/Resume。

≈30 min开始学 →
15

Redis 调用

RedisClusterClient、Init、Get/Set/Eval、resp。

≈30 min开始学 →
W4

第 4 周 · 高级特性与实战

日志、Leader 选举、AI Token、性能重建、构建部署收官
16

日志与安全日志

Log 接口、SafeLog、Unsafe*、custom_log。

≈30 min开始学 →
17

Leader 选举与共享数据

DoLeaderElection/Lease/SharedData CAS。

≈30 min开始学 →
18

AI Token 用量解析

tokenusage 多协议 GetTokenUsage、gjson path。

≈30 min开始学 →
19

性能、稳定性与测试

rebuild 重建、IO 限流、streaming inject、单元测试。

≈30 min开始学 →
20

构建部署与收官串讲

编译 wasm + Docker + WasmPlugin CRD + 五站串讲。

≈30 min开始学 →

✅ 全部 20 天已就绪（higress-group 系列 5/5 收官完成）。建议先学 Envoy 和 Higress 再学本课。