Skip to main content

The Design of go-lynx

· 4 min read
tanzhuo

github.com/go-lynx is designed as a foundation framework that helps companies build out a microservice architecture fast. I split the whole codebase (29 repos under the go-lynx organization) into two parts: the lynx architectural base, and a family of lynx plugin modules.

https://github.com/go-lynx

The headline feature: Plug-and-Play—genuinely works out of the box, turning complex microservice architecture into "building blocks."

It doesn't reinvent wheels from scratch; it stands on the shoulders of giants:

  • Core runtime borrowed from Kratos (Bilibili's open-source framework)
  • Service discovery/governance via Polaris (Tencent's cloud-native service mesh) and Nacos (open-sourced by Alibaba)
  • Distributed transactions via Seata, DTM, and others
  • On top of that, I added a plugin management system + event bus + control plane of my own, enabling true hot-plugging.

Versus Kratos: Kratos is the "foundation framework"; Lynx is "Kratos hardened for production + a plugin system + zero configuration." If you like Kratos but find its configuration tedious and its plugins inconsistent, this framework was born from exactly that pain.

Scaffolding​

Zero config + a CLI scaffold—one command generates a complete project:

# Install the lynx CLI
go install github.com/go-lynx/lynx/cmd/lynx@latest

# Generate a complete microservice project skeleton
lynx new my-service

The Plugin Ecosystem So Far​

  • Existing plugins: gRPC, HTTP, Redis, PostgreSQL, Redis distributed lock, Swagger, Tracer, Seata, and more.
  • Plugins communicate through a built-in Event Bus, enabling inter-plugin messaging and control.
  • Service registration and discovery + health checks + multi-version + load balancing (Polaris)
  • Traffic governance: rate limiting, circuit breaking, blue-green/canary, fallback
  • Security: mutual TLS, JWT, OAuth2, RBAC/ABAC
  • Distributed transactions: fully automatic via Seata
  • Observability: Prometheus + OpenTelemetry + Zap (JSON logging)
  • Graceful shutdown, retries, dead-letter queues, recovery manager

Config-Driven​

  • Every plugin has a fixed confPrefix (e.g. lynx.grpc.service, lynx.grpc.client), with configuration loaded from the Lynx Runtime via rt.GetConfig().Value(confPrefix).Scan(...).
  • Supports hot updates via Configure(c): the server side guards config pointer replacement with confMu, ensuring concurrency safety and allowing partial capabilities to be updated without a restart.

Example lynx project configuration (YAML)​

lynx:
  polaris: {namespace: default}   # Service registration and discovery
  http: {addr: ":8080"}           # HTTP listen address
  grpc: {addr: ":9090"}           # gRPC listen address
  # Ready-made templates exist for metrics/tracing/logging/tls/rate_limit too

The overall feel is similar to Spring Boot: configure only the plugins you use, and every plugin works out of the box.

Plugin Architecture​

  • Unified plugin interface: plugins implement Lynx's plugins.Plugin interface, and embedding BasePlugin gives them common capabilities—ID, name, version, config prefix, weight, and so on.
  • Factory registration: client plugins register in init() via factory.GlobalTypedFactory().RegisterPlugin(clientPluginName, "lynx.grpc.client", ...), and the framework loads them by config prefix and manages their lifecycle.
  • Lifecycle: a standard three-phase model—InitializeResources (read and validate config), StartupTasks (start services/connections), CleanupTasks (graceful shutdown, resource release).
  • Dependency injection: server-side plugins receive the application name, Logger, certificates, control plane, etc. via SetDependencies, avoiding global singletons and making testing and multi-instance setups easier.

Security Module Design​

To secure communication between internal microservices, Lynx has built-in automatic TLS certificate management and rotation. Certificates update while the service is running with no restart required—newly established connections automatically pick up the latest certificate, delivering true zero-downtime updates. The design centers on a unified CertificateProvider for certificate management: internal gRPC servers fetch the current certificate dynamically during the TLS handshake, while clients obtain the Root CA through the same mechanism with support for credential refresh, so certificate updates take effect automatically. The mechanism can also hook into file watchers, cloud certificate services, or key management systems for automated certificate rotation and enterprise-grade secure communication—improving security while substantially cutting operational overhead.

Wrap-Up​

The core idea of go-lynx is not to rebuild the wheel but to fill in the layer that production environments need on top of Kratos: a unified plugin system, a config-driven out-of-the-box experience, and hot-plugging powered by the event bus and control plane. Service governance, distributed transactions, observability, and automatic TLS rotation are all delivered as plugins—use what you need, configure only that. If you're on Kratos and have been burned by inconsistent configuration and plugins, take a look at go-lynx and see whether this design solves your pain points.

COMMENTS