douyu/jupiter: a Go microservice framework built around governance, not just transport

What douyu/jupiter solves, and who it is for

Most Go service frameworks answer one question: how do I route a request? Jupiter answers a different one. The README describes it as a "governance-oriented microservice framework" that has been used for years at Douyu, and the repository layout backs that up. Alongside the usual HTTP and RPC concerns, the module graph pulls in etcd-related discovery, Sentinel for flow control, Prometheus client libraries, OpenTracing, Apollo config, Redis, RocketMQ, and multiple HTTP engines (gin, echo, gogf/gf).

The intended user is a platform or infrastructure team running many Go services that must behave the same way in production: same config loading, same metrics endpoint, same tracing hooks, same shutdown path. If you maintain one small service, that uniformity costs more than it returns. If you maintain thirty, writing it once in a framework is the point.

What Jupiter is not is a thin library you drop into an existing main function and forget. The quick start routes through a project template (jupiter-layout) and a CLI (cmd/jupiter), which tells you the framework expects to own application startup, not just serve as a dependency.

How the framework is put together

Two files sit at the repository root: jupiter.go and jupiter_option.go. That pairing is the architectural signal. An application is constructed as an object and then configured through options, so the framework controls the lifecycle (initialization, run, shutdown) while the caller supplies choices.

Around that core, the repository is split into cmd/, pkg/, proto/, test/ and website/. The pkg/ tree is where the framework's own building blocks live, and the Makefile confirms this by scoping its lint and format targets to pkg/ specifically. The proto/ directory holds protobuf definitions, with buf.gen.yaml and buf.work.yaml driving code generation, and the Makefile exposes generate targets that run buf generate, including a second pass with buf.gen.tag.yaml. The test/ directory holds a docker-compose file and an e2e suite run through Ginkgo.

The dependency list is the clearest statement of scope. A service built on Jupiter inherits client libraries for etcd-era discovery, Sentinel-based rate limiting, Prometheus metrics, OpenTracing spans, Apollo config, Redis, and RocketMQ, plus a cron scheduler and a local cache. That is a lot of surface area to inherit at once, and it is the main reason the framework is opinionated rather than minimal.

Installing the jupiter toolkit and running a first service

The README's Quick Start lists five steps, and the code block below reproduces them in order. The first command installs the CLI from the module path. The second generates a project from the jupiter-layout template into a directory named example-go. The third resolves dependencies. The fourth starts the supporting containers defined in the repository's test/docker-compose.yml. The fifth runs the example server with an explicit config file.

go install github.com/douyu/jupiter/cmd/jupiter@latest
jupiter new example-go
cd example-go
go mod tidy
docker compose -f test/docker-compose.yml up -d
jupiter run -c cmd/exampleserver/.jupiter.toml

Two things are worth noticing before you type any of it. The requirements section states Go version 1.19 or newer and Docker, and go.mod declares go 1.23.0, so a 1.19 toolchain may not build the module as it currently stands. The Docker step is not optional decoration: the compose file is what supplies the backing services the example expects, and skipping it will surface as connection errors rather than a clear message.

The config path passed to jupiter run is cmd/exampleserver/.jupiter.toml, so the generated project keeps its example server under cmd/ and its configuration next to it. That is the layout to copy when you add your own service: one directory per binary, config file beside it, and the run command pointing at the file explicitly rather than relying on a default location.

Where Jupiter is the wrong choice

The README does not document rollback, and it does not describe a migration path off the framework once a service is built on it. That absence matters, because the framework owns startup and configuration, so removing it later means rewriting the entry point and the config layer of every service.

The heavier constraint is the infrastructure assumption. Governance features in this style of framework generally need a registry and a config source to be useful, and the repository's dependency list includes etcd, Apollo and Sentinel integrations. The README never states a minimum viable deployment for a single service, so a reader cannot tell from the documentation alone which components can be omitted. If you want a service that runs with no external registry, Jupiter's value proposition largely disappears, and a plain router plus a metrics library would be less to operate.

There is also a versioning signal to weigh. The most recent release listed is v0.11.21 from 2025-10-20, following v0.11.20 in July 2025 and v0.11.19 in January 2025. The project is still on a 0.x line, which is worth knowing before you standardize a large fleet on it.

Juno and jupiter-layout: the parts outside the framework

Jupiter is not a single repository in practice. The README's Learn More section points to three companion projects. juno is described as a Microservice Governance System for jupiter, jupiter-layout is the project template, and jupiter-examples holds further samples. There is also a hosted console at jupiterconsole.douyu.com, listed with the demo credentials admin / admin.

This split is the practical difference from a framework like go-kit or a plain gRPC setup. go-kit gives you composable middleware and leaves operational tooling to you; Jupiter ships the framework and expects a companion console and template to go with it. The trade is real: you get a consistent starting point and an operations view, and you take on a second system to deploy and keep in step with the framework version.

Anyone evaluating Jupiter should look at juno before deciding. If you are not prepared to run the console, you are using roughly half of what the project offers, and the framework's own governance features become libraries you call manually rather than a managed surface.

Building, testing and upgrading

The Makefile is the honest description of maintenance cost. Its default target is help, and the all target chains fmt, errcheck, lint and build. Linting runs through golangci-lint, and the init target installs tooling by reading tools/tools.go and piping the underscore-prefixed imports into go install, which means tool versions are pinned in the repository rather than on each developer's machine.

Testing is split. unit-test runs go test with the race detector and an atomic coverage profile across the whole module. e2e-test changes into test/e2e, tidies that module, and runs Ginkgo with randomization and tracing, collecting coverage against github.com/douyu/jupiter/... Coverage is then inspected with gocovsh through the covsh-unit and covsh-e2e targets.

The protobuf workflow is the part most likely to surprise a new team. Code generation is driven by buf, with generate running buf generate and a second pass using buf.gen.tag.yaml, lint running buf lint, and breaking running buf breaking against the repository's own git history. Upgrading Jupiter therefore means upgrading a buf toolchain as well as a Go module.

On licensing: the repository carries Apache-2.0, the README displays an Apache-2.0 badge, and LICENSE is present at the root. Apache-2.0 is permissive and includes an explicit patent grant, but it also carries notice and attribution obligations that your own legal review should confirm for your distribution model. Nothing here is legal advice.

Editorial conclusion

Adopt douyu/jupiter if your team already runs Go services and wants discovery, config, metrics and tracing behind one application type instead of assembling them per service. Do not adopt it if you need a small HTTP router, or if you are unwilling to run the etcd and other infrastructure its governance features assume. Before committing, install the toolkit, generate the jupiter-layout example, and confirm that the modules your service needs are present in go.mod and that the config keys in .jupiter.toml match your environment.

Frequently asked questions

Official sources

1. douyu/jupiter on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases