go-eagle/eagle: a Go scaffolding framework for HTTP and gRPC services

What go-eagle/eagle solves, and who it is aimed at

Starting a Go backend usually means making the same set of decisions before any business logic exists: which router, how to structure handlers and services, how configuration is loaded per environment, where the ORM sits, how gRPC and HTTP share one process. Eagle's answer is a fixed layout plus a generator. The README describes it as "a Go framework suitable for rapid business development, which can quickly build API services or Web sites", and the directory listing in the README shows the shape it imposes: api/ for proto definitions, cmd/ with separate entry points for server, consumer and code generation, internal/ split into dal, handler, repository, service and event/subscribe, plus config/, deploy/ and scripts/.

The audience is a team that has already decided on gin and gRPC and does not want to argue about folder names. The README's feature list is essentially a curated stack: gin for HTTP, grpc-go for RPC, viper for configuration, zap for logging, gorm or the MongoDB driver for persistence, go-redis and ristretto for caching, RabbitMQ or asynq for queues, JWT for auth, validator for request validation, cron for scheduled tasks, Prometheus and Grafana for metrics, OpenTelemetry for tracing, and etcd, Consul or Nacos for service registration. That is a lot of surface area, and the value is in the wiring rather than in any one component.

It is not a general-purpose web framework in the sense of net/http middleware you add to an existing program. The generator produces a project; you then edit inside it. If your codebase already has its own layering, Eagle's contribution drops to near zero.

The layered architecture and Wire dependency injection

The README states that Eagle "utilizes a classic layered structure and employs the Wire dependency injection framework to enhance modularity and reduce coupling between components". The request path implied by the directory tree runs from internal/routers, which registers routes and middleware, into internal/handler, then internal/service for business logic, then internal/repository, which wraps the data access interfaces, and finally internal/dal, where db/model holds data models, db/method holds custom query methods and db/query holds gorm/gen generated queries. Cache and RPC clients live under dal as well.

Two details are worth noting. First, gorm/gen appears in the layout, which means query code is generated rather than hand-written, and the Makefile is the place where generation and build commands live. Second, Wire resolves the dependency graph at generation time, so constructor wiring is checked by the compiler rather than at runtime. That is a real difference from reflection-based containers: a missing provider is a build error, not a panic on the first request. The cost is that adding a dependency means regenerating the Wire output, and the README does not walk through that workflow.

The repository also ships examples/ directories for config, crontab, helloworld, log, queue, registry and trace. Those are the practical reference for how each component is meant to be wired, since the README itself stays at the level of a feature list.

Installing the eagle CLI and generating a first service

Eagle is installed as a CLI, not added as a module dependency. The README's installation section sets GOPROXY and then installs the command with go install. Note that the README shows two forms depending on Go version, and the module path ends in cmd/eagle.

GOPROXY="https://goproxy.cn,direct"

# go >= 1.16
go install github.com/go-eagle/eagle/cmd/eagle@latest

After this, the eagle binary should be on your PATH. The quick start then generates a project that contains both an HTTP and a gRPC server, resolves dependencies, and runs it through the Makefile. The README gives a bare name and a full module path as two accepted forms.

eagle new eagle-demo
# or
eagle new github.com/foo/eagle-demo

go mod tidy
make run

What you should see is a generated tree matching the README's layout, with config files under config/, entry points under cmd/server and cmd/consumer, and a Makefile carrying build, test and code generation targets. The Makefile's build target runs go build with ldflags that inject gitTag, buildDate, gitCommit and gitTreeState into github.com/go-eagle/eagle/pkg/version, so a binary built this way reports version information.

For a container run, the repository ships a Dockerfile and a docker-compose.yml. The Dockerfile builds on golang:1.21-alpine3.20, copies go.mod and go.sum first to cache dependency download, runs make build, and the final stage runs /bin/eagle with -c /data/conf/eagle/config and exposes port 8080. The compose file starts app, a mysql:5.7.33 service and redis:6.0.9-alpine on a shared network, maps 8080:8080, and healthchecks the app by curling http://localhost:8080/health. The Dockerfile comments give the equivalent manual commands, including building the image with docker build -t eagle:v1.0.1 -f Dockerfile . and testing with curl -i http://localhost:8080/health.

Where Eagle gets in the way

The strongest limitation is structural: Eagle is a project generator, so the moment you generate a project you inherit its opinions. Swapping gin for another router, or replacing the repository/service split with something flatter, means working against the layout rather than with it. Teams that already have a working Go service and only want a few of Eagle's pieces will find the extraction cost higher than the benefit.

The dependency set is also wide. go.mod pulls in gin, gRPC, viper, zap, gorm, the Elasticsearch v7 client, ristretto, asynq, RabbitMQ, NATS, Consul, Nacos, Prometheus, OpenTracing and more. A small service that needs an HTTP handler and a database connection still carries that module graph unless the generated code is pruned. The README does not document a minimal profile or a way to generate a project without the components you do not use.

Toolchain consistency deserves a check. The repository's go.mod declares go 1.22, while the Dockerfile's builder stage is golang:1.21-alpine3.20. Whether the generated project builds cleanly under the Dockerfile's toolchain depends on the Go version you select at generation time, and the README does not address the mismatch. Verify it on your own machine before assuming the container path works unchanged.

Finally, the README does not document rollback, migration or an upgrade path for generated projects. Once you have generated a tree and edited it, there is no described mechanism for pulling in later template changes; the CHANGELOG and release tags are the only upgrade signal the repository offers. Maintenance status is worth stating plainly: the last push to the repository was on 2026-04-22, and the most recent release listed is v1.11.0 from 2025-10-14.

How Eagle differs from Kratos and go-zero

The closest alternatives in the same space are go-kratos/kratos and zeromicro/go-zero, both Go microservice frameworks that combine a CLI, code generation and a component set. A relevant detail sits in Eagle's own go.mod: it depends on github.com/go-kratos/aegis, the Kratos adaptive load shedding library, so Eagle is borrowing from that ecosystem rather than ignoring it.

The practical difference is in how much structure is imposed and how the service is described. Eagle's README centers on a generated directory layout and proto files under api/, with HTTP and gRPC servers generated together and Wire handling dependency injection. If you want a framework that hands you a conventional layered project and lets you fill it in, that is the fit. If you want the service contract to drive everything, including generated clients and middleware, Kratos and go-zero lean harder in that direction. Eagle's own documentation is at go-eagle.org and the README points there, so the component-level details live outside the repository README.

Maintenance, licensing and what to verify before adopting

Eagle is MIT licensed, per the README's license section and the LICENSE file in the repository root. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. That is a statement about the licence text, not legal advice; if your organisation has rules about attribution or about the licences of transitive dependencies, review the full dependency list in go.mod, since Eagle pulls in a large number of third-party modules with their own terms.

On maintenance, the facts are these: the repository is not archived, the last push was on 2026-04-22, and the release history shows v1.11.0 on 2025-10-14, v1.10.0 on 2024-12-27 and v1.9.0 on 2024-08-11. The gap between v1.10.0 and v1.11.0 is roughly ten months, so release cadence is not fast. The README does not describe a deprecation policy, a support window or a migration guide between major template changes.

Before adopting, verify three concrete things. Run eagle new in a scratch directory and confirm the generated project builds with your installed Go version. Check that the generated config under config/ matches your environments, since the README does not enumerate the config keys. And confirm the container path: build the image from the shipped Dockerfile and hit /health on port 8080, because the Dockerfile's builder image and the go.mod Go version are not aligned.

Editorial conclusion

Adopt go-eagle/eagle if you are starting a Go service from scratch and want a layered layout, Wire dependency injection and pre-wired gin, gRPC, gorm, viper, zap and etcd rather than assembling them yourself. Do not adopt it if you have an existing service structure you are happy with, or if you need a library that adds HTTP routing to code you already have; the CLI generates a whole tree and expects you to work inside it. Before committing, run eagle new on a scratch directory, check that the generated config matches your environment, and confirm the generated code builds against your Go toolchain, since the repository's own go.mod targets go 1.22 while its Dockerfile builds on golang:1.21-alpine3.20.

Frequently asked questions

Official sources

1. go-eagle/eagle on GitHub
2. License: MIT
3. Project website
4. README
5. Releases