Why Higress Transformer Beats Spring Cloud Gateway Filters: Performance and Usage Guide

Background

Spring Cloud Gateway (SCG) offers a variety of built‑in GatewayFilter factories—such as AddRequestHeader, MapRequestHeader, AddRequestParameter, and DedupeResponseHeader —to modify HTTP requests and responses. A typical use case involves adding a header derived from the request path, mapping that header to another, adding query parameters, and deduping response headers.

SCG Example Configuration

# application.yaml:
spring:
  cloud:
    gateway:
      routes:
        - id: test_route
          uri: lb://httpbin-svc
          predicates:
            - Path=/{api}/**
          filters:
            - AddRequestHeader=X-First, {api}
            - MapRequestHeader=X-First, X-Second
            - AddRequestParameter=k1, v1
            - DedupeResponseHeader=X-Dedupe, RETAIN_FIRST

This YAML is familiar to developers who have used SCG.

Performance Comparison with Higress

Benchmarks were run at the same QPS while toggling the Higress Transformer plugin and the equivalent SCG filters. The results show:

When neither Higress Transformer nor SCG filters are enabled, SCG consumes roughly 3.30× CPU and 4.88× memory compared to Higress.

When Higress Transformer is enabled and SCG filters are enabled, SCG still uses about 2.98× CPU and 3.19× memory relative to Higress.

These figures demonstrate a clear resource advantage for the Higress Transformer plugin.

What Is Higress?

Higress is an open‑source cloud‑native gateway built on Alibaba’s internal Envoy‑based gateway, leveraging Istio and Envoy as its core. It integrates traffic, micro‑service, and security gateway capabilities, supports Dubbo, Nacos, Sentinel, and conforms to Ingress and Gateway API standards. It also offers a smooth migration path from Nginx Ingress.

Higress Transformer Plugin

The Transformer plugin, implemented as a WebAssembly (Wasm) extension, can modify request/response headers, query parameters, and body fields. Supported operations include remove, rename, replace, add, append, map, and dedupe.

Installation and Deployment Steps

Follow the official Higress quick‑start guide to install the control plane and data plane.

Add a domain (e.g., foo.bar.com) and a route that forwards traffic to an httpbin service via the Higress console.

Deploy the Transformer plugin (e.g., using the Docker image docker.io/weixinx/transformer:v0.1.0 or building from source).

Configure the plugin for request‑side transformations and a separate instance for response‑side transformations.

Transformer Configuration Example

# transformer:
  type: request  # request‑side
  rules:
    - operate: add
      headers:
        - key: X-First
          value: $1  # captured group from path
          path_pattern: ^\/(\w+)[\?]{0,1}.*$
      querys:
        - key: k1
          value: v1
    - operate: map
      headers:
        - key: X-First
          value: X-Second
---
# transformer-resp:
  type: response
  rules:
    - operate: dedupe
      headers:
        - key: X-Dedupe
          value: RETAIN_FIRST

Testing the Plugin

# Verify request‑side transformation
curl -v -H "host: foo.bar.com" "console.higress.io/get"
# Expected JSON fragment shows added header X-First and mapped X-Second, plus query k1=v1

# Verify response‑side transformation
curl -v -H "host: foo.bar.com" \
  "console.higress.io/response-headers?X-Dedupe=1&X-Dedupe=2&X-Dedupe=3"
# Response header X-Dedupe retains only the first value (1)

Core Code Logic

The plugin source resides in the Higress repository under plugins/wasm-go/extensions/transformer. It uses the Higress Wasm SDK and defines a TransformerConfig struct exposing type (request/response) and a slice of TransformRule. Each rule specifies an operate and optional headers, querys, and body parameters.

type TransformerConfig struct {
    typ   string
    rules []TransformRule
    trans Transformer // internal, not exposed to users
}

type TransformRule struct {
    operate string
    headers []Param
    querys  []Param
    body    []Param
}

type Param struct {
    key         string
    value       string
    valueType   string
    hostPattern string
    pathPattern string
}

type Transformer interface {
    TransformHeaders(host, path string, hs map[string][]string) error
    TransformQuerys(host, path string, qs map[string][]string) error
    TransformBody(host, path string, body interface{}) error
}

The implementation provides separate request and response transformers, each handling headers, query parameters, and bodies. Header and query handling share a unified kvHandler, while body handling uses requestBodyHandler (combining kvHandler and jsonHandler) and responseBodyHandler (JSON only). The processing order is hard‑coded as

remove → rename → replace → add → append → map → dedupe

, with plans for future optimization.

Conclusion

The Higress Transformer plugin offers a more efficient way to perform HTTP request/response modifications compared with SCG’s built‑in filters, consuming less CPU and memory. The article provides a complete walkthrough—from performance benchmarking to installation, configuration, testing, and an overview of the plugin’s internal code—helping users migrate from Spring Cloud Gateway to Higress.