Apache APISIX Java插件开发指南不换语言完成网关能力扩展【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix你的团队用 Java 维护业务却要为一个网关插件去啃 LuaAPISIX 的 Java 插件开发走的是外部插件机制ext-plugin网关把请求经本地 Unix Socket 转给一个 Java 子进程处理你的业务逻辑留在熟悉的语言里。为什么需要Java插件开发Lua插件体系的门槛先看清楚现状APISIX 的原生插件全部是 Luaapisix/plugins/ 目录下百来个文件从鉴权到限流到日志全是。对 Java 团队来说这意味着写网关逻辑等于第二套代码库——语言要重新学、调试工具换一套、发布流程多一份维护成本而且 Lua 生态里的成熟中间件客户端比如你们内部的风险决策 SDK、统一认证网关的 Java 客户端根本没法复用。外部插件机制的价值在于分工路由、限流这类高频小逻辑继续留在网关内核跑认证、审计、请求改写这类重业务、轻吞吐的逻辑丢给 Java 进程。换句话说你用一次本地进程间 RPC 的开销换来了整个 Java 生态。但要注意边界——RPC 通信发生在本地 Unix Socket 上开销虽低每跳仍比内核内直接执行贵所以不是所有场景都适合外移。外部插件机制怎么工作Java插件与网关的通信边界请求链路的关键点在于通信边界到底在哪网关在 privileged agent 阶段把 runner 拉起来当子进程管理APISIX 重启时 runner 跟着重启。两者之间不是 HTTP而是 FlatBuffers 二进制协议——ext-plugin 核心实现 里能看到完整的消息编解码消息类型对应A6命名空间下的一组 schema。关键在这里同一份路由配置第一次被命中时网关会先发 PrepareConf 握手把conf数组每项是 name/value交给 runnerrunner 回一个 conf token之后每个请求只带 token不再传完整配置。token 有 lrucache shared dict 两级缓存这就是 Java 侧配置热更新的实现基础——你 PATCH 路由配置后缓存失效下一个请求触发重新握手全程不重启任何进程。Java 插件对请求只有两种决定权Rewrite改路径、请求头、query、body 后继续转发和 Stop直接短路返回状态码和响应体。响应阶段同理ext-plugin-post-resp能在回包前插手。runner 挂掉时网关重试 3 次最终返回 503如果配置里开了allow_degradation则放行请求牺牲这个插件保可用性。插件骨架怎么搭最小可运行路径网关侧只需在 conf/config.yaml 声明 runner 命令# conf/config.yaml ext-plugin: cmd: [java, -jar, /opt/apisix-java-plugin-runner.jar]runner 本体是 Apache 社区的独立项目 apisix-java-plugin-runner在 Apache 基金会下检索即可Maven 打出 jar 后由上面的cmd指向它。开发阶段建议把 runner 拆出来单独跑给进程设环境变量APISIX_LISTEN_ADDRESSunix:/tmp/runner.sock同时在config.yaml里配path_for_test: /tmp/runner.sock这样改 Java 代码只需重启 runner不用动网关。插件本身是一个接口实现类名按 kebab-case 对应插件名public class TenantHeaderPlugin implements Plugin { Override public void execute(HttpReq req, HttpResp resp) { req.header(X-Tenant, acme); // 追加请求头调用返回后由网关下发 } Override public void setConfig(Configuration conf) { // 解析路由配置里 value 字段的 JSON初始化插件参数 } }落地就三条命令git clone https://gitcode.com/GitHub_Trending/ap/apisix cd apisix-java-plugin-runner mvn package -DskipTests # 重启 APISIX或按上文拆进程方式重启 runner请求头改写插件怎么验证从代码到生效的闭环拿 TenantHeaderPlugin 走一遍完整链路。第一步是通过 Admin API 给路由挂上插件——ext-plugin-pre-req的conf是 name/value 数组value就是上面setConfig收到的 JSONcurl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: your-admin-key -X PUT -d { uri: /get, upstream: { type: roundrobin, nodes: { httpbin.org:80: 1 } }, plugins: { ext-plugin-pre-req: { conf: [{ name: tenant-header, value: {\tenant\:\acme\} }] }} }第二步验证curl -i http://127.0.0.1:9080/get用 httpbin 的/headers类接口回显上游实际收到的请求头看到X-Tenant: acme即生效。第三步验证热更新PATCH该路由只改value内容再发一次请求——因为 token 缓存已失效新配置随下一次握手进入 runnerJava 侧setConfig重新执行。若插件不生效按顺序查路由是否命中、config.yaml的plugins列表里有没有ext-plugin-pre-req它默认优先级 12000被裁剪过的列表要补回来、conf里的 name 是否与插件名严格一致。插件不生效怎么排查踩坑与调优清单插件不加载先确认 plugins 列表中ext-plugin-pre-req存在且未被注释再看 name 是否 kebab-case、是否与类映射名逐字一致schema 校验会静默拒绝错误项。runner 读不到环境变量Nginx 默认隐藏全部环境变量从 v2.7 起需在nginx_config.envs里显式声明后才会透传给 runner。性能退化每请求多两次进程间往返Java 侧用固定线程池、避免每请求建连高频小逻辑如简单限流留在 Lua 侧Java 插件承担认证、改写、审计这类可容忍毫秒级延迟的逻辑。可用性权衡生产建议评估allow_degradation——runner 故障时是 503 挡掉全部流量还是放行并丢失该插件的防护取决于这条链路的业务性质。调试手段runner 的 stdout 会被网关以 warn 级别打进 error.log开发期最直观配合path_for_test固定 socketJava 进程可独立重启热更。JVM 加-XX:HeapDumpOnOutOfMemoryError排查泄漏指标侧挂 prometheus 插件看整体 QPS 与延迟对比。外部插件机制让 APISIX 的插件边界从Lua 文件扩展成了任何一个能被 cmd 拉起的进程代价是每次调用一次本地 RPC收益是语言与生态的完全自由。外部插件机制完整文档docs/en/latest/external-plugin.mdrunner 协议实现细节docs/en/latest/internal/plugin-runner.md插件配置 schema 与优先级docs/en/latest/plugins/ext-plugin-pre-req.md【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache APISIX Java插件开发指南：不换语言完成网关能力扩展
Apache APISIX Java插件开发指南不换语言完成网关能力扩展【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix你的团队用 Java 维护业务却要为一个网关插件去啃 LuaAPISIX 的 Java 插件开发走的是外部插件机制ext-plugin网关把请求经本地 Unix Socket 转给一个 Java 子进程处理你的业务逻辑留在熟悉的语言里。为什么需要Java插件开发Lua插件体系的门槛先看清楚现状APISIX 的原生插件全部是 Luaapisix/plugins/ 目录下百来个文件从鉴权到限流到日志全是。对 Java 团队来说这意味着写网关逻辑等于第二套代码库——语言要重新学、调试工具换一套、发布流程多一份维护成本而且 Lua 生态里的成熟中间件客户端比如你们内部的风险决策 SDK、统一认证网关的 Java 客户端根本没法复用。外部插件机制的价值在于分工路由、限流这类高频小逻辑继续留在网关内核跑认证、审计、请求改写这类重业务、轻吞吐的逻辑丢给 Java 进程。换句话说你用一次本地进程间 RPC 的开销换来了整个 Java 生态。但要注意边界——RPC 通信发生在本地 Unix Socket 上开销虽低每跳仍比内核内直接执行贵所以不是所有场景都适合外移。外部插件机制怎么工作Java插件与网关的通信边界请求链路的关键点在于通信边界到底在哪网关在 privileged agent 阶段把 runner 拉起来当子进程管理APISIX 重启时 runner 跟着重启。两者之间不是 HTTP而是 FlatBuffers 二进制协议——ext-plugin 核心实现 里能看到完整的消息编解码消息类型对应A6命名空间下的一组 schema。关键在这里同一份路由配置第一次被命中时网关会先发 PrepareConf 握手把conf数组每项是 name/value交给 runnerrunner 回一个 conf token之后每个请求只带 token不再传完整配置。token 有 lrucache shared dict 两级缓存这就是 Java 侧配置热更新的实现基础——你 PATCH 路由配置后缓存失效下一个请求触发重新握手全程不重启任何进程。Java 插件对请求只有两种决定权Rewrite改路径、请求头、query、body 后继续转发和 Stop直接短路返回状态码和响应体。响应阶段同理ext-plugin-post-resp能在回包前插手。runner 挂掉时网关重试 3 次最终返回 503如果配置里开了allow_degradation则放行请求牺牲这个插件保可用性。插件骨架怎么搭最小可运行路径网关侧只需在 conf/config.yaml 声明 runner 命令# conf/config.yaml ext-plugin: cmd: [java, -jar, /opt/apisix-java-plugin-runner.jar]runner 本体是 Apache 社区的独立项目 apisix-java-plugin-runner在 Apache 基金会下检索即可Maven 打出 jar 后由上面的cmd指向它。开发阶段建议把 runner 拆出来单独跑给进程设环境变量APISIX_LISTEN_ADDRESSunix:/tmp/runner.sock同时在config.yaml里配path_for_test: /tmp/runner.sock这样改 Java 代码只需重启 runner不用动网关。插件本身是一个接口实现类名按 kebab-case 对应插件名public class TenantHeaderPlugin implements Plugin { Override public void execute(HttpReq req, HttpResp resp) { req.header(X-Tenant, acme); // 追加请求头调用返回后由网关下发 } Override public void setConfig(Configuration conf) { // 解析路由配置里 value 字段的 JSON初始化插件参数 } }落地就三条命令git clone https://gitcode.com/GitHub_Trending/ap/apisix cd apisix-java-plugin-runner mvn package -DskipTests # 重启 APISIX或按上文拆进程方式重启 runner请求头改写插件怎么验证从代码到生效的闭环拿 TenantHeaderPlugin 走一遍完整链路。第一步是通过 Admin API 给路由挂上插件——ext-plugin-pre-req的conf是 name/value 数组value就是上面setConfig收到的 JSONcurl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: your-admin-key -X PUT -d { uri: /get, upstream: { type: roundrobin, nodes: { httpbin.org:80: 1 } }, plugins: { ext-plugin-pre-req: { conf: [{ name: tenant-header, value: {\tenant\:\acme\} }] }} }第二步验证curl -i http://127.0.0.1:9080/get用 httpbin 的/headers类接口回显上游实际收到的请求头看到X-Tenant: acme即生效。第三步验证热更新PATCH该路由只改value内容再发一次请求——因为 token 缓存已失效新配置随下一次握手进入 runnerJava 侧setConfig重新执行。若插件不生效按顺序查路由是否命中、config.yaml的plugins列表里有没有ext-plugin-pre-req它默认优先级 12000被裁剪过的列表要补回来、conf里的 name 是否与插件名严格一致。插件不生效怎么排查踩坑与调优清单插件不加载先确认 plugins 列表中ext-plugin-pre-req存在且未被注释再看 name 是否 kebab-case、是否与类映射名逐字一致schema 校验会静默拒绝错误项。runner 读不到环境变量Nginx 默认隐藏全部环境变量从 v2.7 起需在nginx_config.envs里显式声明后才会透传给 runner。性能退化每请求多两次进程间往返Java 侧用固定线程池、避免每请求建连高频小逻辑如简单限流留在 Lua 侧Java 插件承担认证、改写、审计这类可容忍毫秒级延迟的逻辑。可用性权衡生产建议评估allow_degradation——runner 故障时是 503 挡掉全部流量还是放行并丢失该插件的防护取决于这条链路的业务性质。调试手段runner 的 stdout 会被网关以 warn 级别打进 error.log开发期最直观配合path_for_test固定 socketJava 进程可独立重启热更。JVM 加-XX:HeapDumpOnOutOfMemoryError排查泄漏指标侧挂 prometheus 插件看整体 QPS 与延迟对比。外部插件机制让 APISIX 的插件边界从Lua 文件扩展成了任何一个能被 cmd 拉起的进程代价是每次调用一次本地 RPC收益是语言与生态的完全自由。外部插件机制完整文档docs/en/latest/external-plugin.mdrunner 协议实现细节docs/en/latest/internal/plugin-runner.md插件配置 schema 与优先级docs/en/latest/plugins/ext-plugin-pre-req.md【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考