g2rain-gateway-webmvc（WebMVC 网关）

g2rain-gateway-webmvc 是基于 Spring Cloud Gateway Server WebMVC 的统一入口：RouterFuncHolder + RouteCompiler 将 g2rain-infra 下发的 RouteDefinitionVo 编译为 RouterFunction 并驻留内存；经 Nacos 与 OpenFeign 调用 infra/basis；集成 JWT / DPoP、静态 API Key、签名校验、主体作用域、链路日志与统一异常处理；默认启用 虚拟线程。

源码仓库：github.com/g2rain/g2rain-gateway-webmvc (opens new window)

与周边服务

客户端 → g2rain-gateway（Nacos 名 g2rain-gateway）→ lb://下游微服务
              ↓ OpenFeign
         g2rain-infra（路由、i18n 错误文案）
         g2rain-basis（组织/应用、API Key、审计事件等）

路由元数据以 infra 为权威来源；增量刷新经 Redis Stream（g2rain-syncer） 驱动 RouteSync。

核心能力

能力	说明
动态路由	RouteCompiler 通过 RouteDefinitionClient（Feign → infra）加载并编译路由
认证	JWT + DPoP 过滤器链
静态 API Key	ApiKeyFilter（+350）：sk- 前缀 Bearer，回源 basis 解析，兼容 OpenAI 式调用
Kafka 审计	TraceLoggingFilter 可选将 GatewayEvent 发往 gateway.exchange.event
国际化	ErrorMessageStorage + Feign ErrorMessageClient → infra /i18n_message
接口权限	ApiPermissionFilter 依赖 ApiPermissionService（默认 @Component 可注释，按需启用）

Servlet 过滤器

偏移	类	职责
+0	EdgePrincipalContextScopeFilter	请求级 EdgePrincipalContext 作用域
+100	GlobalErrorFilter	统一 JSON 异常
+200	CachedBodyFilter	请求/响应体缓存

路由级过滤器

偏移	类	职责
+300	TraceLoggingFilter	日志 + Kafka 审计事件
+350	ApiKeyFilter	静态 API Key
+400	GatewayTokenAuthFilter	JWT
+500	GatewayDPoPAuthFilter	DPoP
+600	ApiPermissionFilter	URI 级权限（可选启用）
+700	SignVerificationFilter	签名
+800	PrincipalForwardFilter	头转发
+900	ResponseAdjustFilter	响应调整

Kafka 网关审计（可选）

与 WebFlux 网关一致：KafkaLogSender → topic gateway.exchange.event。basis 侧 AuditEventListener 在 g2rain.audit.event.enabled=true 时消费并写入 audit_event。

# 网关侧（示例）
spring:
  kafka:
    enabled: true
    bootstrap-servers: 127.0.0.1:9092

静态 API Key

详见 WebFlux 文档同一机制：basis personal_static_access_token + /login_token 解析接口，网关 ApiKeyFilter 写入 Principal 后跳过 JWT/DPoP/签名。

环境要求与快速开始

• JDK 25+、Nacos、Redis、可发现的 infra/basis
• 默认端口 8083；Nacos 服务名 g2rain-gateway

git clone https://github.com/g2rain/g2rain-gateway-webmvc.git
mvn clean package -DskipTests
java -jar target/g2rain-gateway-webmvc-*.jar

配置要点

项	说明
spring.kafka.enabled	默认 false
gateway.limits.request-body-max-size	默认 10MB
gateway-white-list	白名单（Filter 类名为 key）

相关文档

• g2rain-gateway-webflux
• g2rain-basis · g2rain-infra