What Is Pixiu? A Cloud‑Native API Gateway for Dubbo‑Go Explained

What is Pixiu

Pixiu (dubbo-go-pixiu) is an open‑source API gateway for the dubbo-go ecosystem. It provides a Golang gateway that exposes Dubbo services as RESTful APIs and supports protocol conversion between HTTP and Dubbo.

Key Design Goals

High performance: millisecond‑level latency and high throughput.

Extensibility via Go plugins.

Ease of use with minimal configuration.

Architecture

Pixiu consists of four core modules:

Listener – exposes the gateway (currently HTTP, gRPC planned).

Router – stores URL trees, matches incoming requests, and forwards routing information.

Filters – implements cross‑cutting concerns (rate limiting, access control, logging) through a configurable filter chain.

Client – invokes backend services (HTTP, Dubbo, future gRPC).

A Registry Center provides service discovery and a Metadata Center stores configuration.

Configuration Example – Listener

listeners:
  - name: "net/http"
    address:
      socket_address:
        protocol_type: "HTTP"
        address: "0.0.0.0"
        port: 8888
    config:
      idle_timeout: 5s
      read_timeout: 5s
      write_timeout: 5s

Router Capabilities

The router supports one‑to‑one and wildcard routing, HTTP forwarding, and conversion of HTTP requests to Dubbo generic calls.

Custom Filters via Go‑Plugin

pluginFilePath: ""
pluginsGroup:
  - groupName: "group1"
    plugins:
      - name: "rate limit"
        version: "0.0.1"
        priority: 1000
        externalLookupName: "ExternalPluginRateLimit"
      - name: "access"
        version: "0.0.1"
        priority: 1000
        externalLookupName: "ExternalPluginAccess"
  - groupName: "group2"
    plugins:
      - name: "blacklist"
        version: "0.0.1"
        priority: 1000
        externalLookupName: "ExternalPluginBlackList"

Dubbo Generic Invocation (Client)

referenceConfig := dg.NewReferenceConfig(irequest.Interface, context.TODO())
referenceConfig.InterfaceName = irequest.Interface
referenceConfig.Cluster = constant.DEFAULT_CLUSTER
var registers []string
for k := range dgCfg.Registries {
    registers = append(registers, k)
}
referenceConfig.Registry = strings.Join(registers, ",")
if len(irequest.DubboBackendConfig.Protocol) == 0 {
    referenceConfig.Protocol = dubbo.DUBBO
} else {
    referenceConfig.Protocol = irequest.DubboBackendConfig.Protocol
}
referenceConfig.Version = irequest.DubboBackendConfig.Version
referenceConfig.Group = irequest.Group
referenceConfig.Generic = true
if len(irequest.DubboBackendConfig.Retries) == 0 {
    referenceConfig.Retries = "3"
} else {
    referenceConfig.Retries = irequest.DubboBackendConfig.Retries
}
referenceConfig.GenericLoad(key)
clientService := referenceConfig.GetRPCService().(*dg.GenericService)

Generic Filter Implementation

func (ef *GenericFilter) Invoke(ctx context.Context, invoker protocol.Invoker, invocation protocol.Invocation) protocol.Result {
    if invocation.MethodName() == constant.GENERIC && len(invocation.Arguments()) == 3 {
        oldArguments := invocation.Arguments()
        if oldParams, ok := oldArguments[2].([]interface{}); ok {
            newParams := make([]hessian.Object, 0, len(oldParams))
            for i := range oldParams {
                newParams = append(newParams, hessian.Object(struct2MapAll(oldParams[i])))
            }
            newArguments := []interface{}{
                oldArguments[0],
                oldArguments[1],
                newParams,
            }
            newInvocation := invocation2.NewRPCInvocation(invocation.MethodName(), newArguments, invocation.Attachments())
            newInvocation.SetReply(invocation.Reply())
            return invoker.Invoke(ctx, newInvocation)
        }
    }
    return invoker.Invoke(ctx, invocation)
}

Roadmap

Version 0.2.1 provides HTTP↔Dubbo proxying and basic gateway functions. Upcoming 0.4.x releases will add gRPC support, Spring Cloud service calls, and MQ integration. Future plans include simplifying configuration, enhancing built‑in filters, supporting the xDS API for sidecar deployment, and evolving Pixiu into a multi‑language Dubbo mesh sidecar.

Related Repositories

Dubbo-go: https://github.com/apache/dubbo-go

Pixiu: https://github.com/apache/dubbo-go-pixiu