Mikaelemmmm/go-zero-looklook: a full-stack go-zero microservices reference project

What go-zero-looklook is for, and who it is for

The README states the motivation plainly: the author kept meeting people who felt go-zero had no complete project example, so an available version was open sourced. That sentence defines the audience. This is not a library, a framework or a service you install and call. It is a repository of business code, deployment files and documents that shows one way to assemble a go-zero system end to end.

The stack listed in the README is long: k8s, go-zero, nginx-gateway, filebeat, kafka, go-stash, elasticsearch, kibana, prometheus, grafana, jaeger, go-queue, asynq, asynqmon, dtm, docker, docker-compose, mysql, redis, modd, jenkins, gitlab and harbor. The README itself warns that if you are unfamiliar with these, you should start with MySQL and Redis, run those two middleware components first, and expand later. That is the honest framing. The value here is seeing how the pieces connect, not acquiring a dependency.

It suits an engineer who has already chosen go-zero and wants a worked example of API plus RPC plus message queue plus observability in one tree. It does not suit someone shopping for a framework, or someone who wants a minimal template with no infrastructure attached.

The API plus RPC split and the direct chain decision

The README describes the development mode directly: API (HTTP) plus RPC (gRPC), where the API acts as an aggregation service and complex or shared business calls are written in RPC. Simple business that no other service depends on can live in the API logic. That is a conventional split, and it is stated as a rule of thumb rather than enforced by tooling.

The more interesting decision is the one the README calls the direct chain method. In the Docker Compose development environment, the project gives up service registration and discovery middleware such as etcd, Nacos and consul, and connects services directly. The README says this is to avoid the trouble those components cause during development. For testing and online deployment it points to k8s, where etcd, Nacos and consumer setups are covered by tutorials in the repository documents.

That trade-off is worth naming. You get a simpler local loop, and you get a development topology that does not match the production topology you will eventually run. Anything you learn about how services find each other locally does not transfer to the k8s path. The README does not describe a rollback or a fallback if you want discovery locally later.

The repository layout supports the split. Top-level entries include app/ for business code, common/ for shared components such as error, middleware, interceptor, tool and ctxdata, deploy/ for filebeat, go-stash, nginx, prometheus and scripts, and doc/ for the project documents. The data/ directory holds generated state for MySQL, Elasticsearch, Redis and Grafana, and the README says everything in it belongs in .gitignore and should not be committed.

Logs, queues and transactions: the middleware choices

For logs the README is explicit about why go-stash is used instead of logstash: logstash "knows everything and the resource occupation is too exaggerated". Filebeat collects logs and reports them to Kafka, and go-stash, developed by the go-zero team, synchronizes the Kafka data source to Elasticsearch by configuration. The README notes that go-stash does not support Elasticsearch account and password by default, and that the author forked a copy to add simple account and password support. That is a real caveat: if your Elasticsearch requires authentication, check which go-stash image and configuration the deployment files actually reference.

Publish and subscribe use kafka through go-queue, and the README names kq as the high-performance publish and subscribe component built on Kafka. Message queues, delayed queues and scheduled tasks use asynq, described as middleware built on Redis, with asynqmon available for inspection. The README notes you could also use go-queue for the message queue role, so the two overlap rather than divide cleanly.

Distributed transactions are handled with DTM. The README is unusually candid here: it links a separate DTM tutorial repository and says this project has not used DTM yet, describing it as preparation for future integration. So the DTM entry in the stack list is aspirational for this codebase. If you are reading the repository to learn how distributed transactions are wired into a live business flow, the README tells you that flow does not exist yet.

Monitoring uses Prometheus, which the README says go-zero supports natively and needs only configuration. Link tracking uses Jaeger, with Zipkin also supported by go-zero by default. Both are described as configuration exercises, and the README points at the project configuration rather than explaining the wiring.

Installing it and getting the development environment up

The README recommends Docker Compose for the development environment, and the repository separates the application services from their dependencies. The docker-compose.yml file at the top level carries a comment stating that before starting this project you must start the environment the project depends on in docker-compose-env.yml. Start with the dependencies, then the application stack.

docker-compose -f docker-compose-env.yml up -d
docker-compose up -d

The second file defines two services. nginx-gateway uses the nginx:1.21.5 image, maps host port 8888 to container port 8081, mounts ./deploy/nginx/conf.d and ./data/nginx/log, and depends on the looklook service. The looklook service uses the image lyumikael/gomodd:v1.22.1, sets TZ to Asia/Shanghai and GOPROXY to https://goproxy.cn,direct, and mounts the repository at /go/looklook as its working directory. Both join the looklook_net bridge network on subnet 172.20.0.0/16. After the stack is up, the port mapping in docker-compose.yml means the gateway is reachable on localhost:8888.

ports:
  - 8888:8081

That snippet is the gateway port mapping as written in docker-compose.yml. If the gateway container is running and nothing answers on 8888, the problem is almost always in ./deploy/nginx/conf.d rather than in the port binding, because the compose file mounts that directory as the nginx configuration source.

The README also mentions modd.conf for hot reloading, and says the project image is built on golang-1.17.7-alpine with modd installed internally, while the compose file pins lyumikael/gomodd:v1.22.1. Those two statements do not agree on the Go version, so confirm which image tag you are actually running before you trust the toolchain version. The README notes that macOS on M1 or M2 should build the Dockerfile themselves rather than pull the image.

For code generation, the deploy/script directory contains gencode for auto-generating API and RPC code and for Kafka scripts, plus a mysql script for auto-generating model code, described as copy-and-paste usage. The deploy/goctl directory holds the project's goctl templates, which the README says you copy into your home directory for goctl to pick up. Those scripts are the practical entry point for adapting the example to your own schema.

Where the project stops being the right tool

The clearest limitation is the DTM gap already noted: the README says the project has not used distributed transactions yet. Anything you read about DTM here is preparation, not a working pattern in the business code.

The second is the version drift. The compose file pins lyumikael/gomodd:v1.22.1, go.mod declares go 1.22, and the README text about the image says golang-1.17.7-alpine. The README was written against an earlier state of the repository than the current files describe. Treat the prose as intent and the files as current.

The third is release cadence. The newest release listed is v1.0.7 from 2024-11-23, following v1.0.6 in 2023-06-08 and v1.0.5 in 2022-12-03. The last push to the repository was on 2026-09-18, so work continues, but releases are not frequent and there is no stated upgrade path between tags. If you fork this as the base of a product, you own the merge burden for every middleware version you track.

The fourth is that the project is a whole system, not a component. There is no importable package here that solves a narrow problem. If your need is a single piece of functionality, the underlying projects are the right places to look: go-zero itself, go-queue, go-stash, asynq or DTM. go-zero-looklook is the assembly, and an assembly is only useful if you want that assembly.

How it compares with the alternatives people actually weigh

The obvious comparison is the go-zero project's own examples and templates. Those are smaller and focused on one mechanism at a time, and they carry no deployment stack. go-zero-looklook goes the other way: it includes nginx as the external gateway, filebeat, kafka, go-stash, elasticsearch, kibana, prometheus, grafana, jaeger, jenkins, gitlab, harbor and k8s deployment material. The difference is depth of integration versus cost of setup. If you want to see a log pipeline and a CI path in the same tree, this repository shows one; if you want to learn a single go-zero concept, the smaller examples get you there with far less running.

A second comparison is a general-purpose Go microservices framework with its own service discovery and configuration model. Those tend to make discovery mandatory rather than optional, which is the opposite of the direct chain choice here. The trade is that you get a local environment that resembles production. go-zero-looklook deliberately does not give you that in development, and the README points to k8s for the realistic topology.

A third comparison is the gateway layer. The README acknowledges that many readers question nginx as a gateway, says the principle is basically the same, and notes you can replace it with apisix or kong. That is a fair statement of scope: the gateway configuration in deploy/nginx/conf.d is an example, not a commitment.

Licence, maintenance and the cost of keeping a fork alive

The repository is MIT licensed, which is permissive and places few conditions on reuse beyond preserving the licence notice. That applies to this repository. It does not automatically cover the third-party components the stack depends on, and those carry their own licences: go-zero, go-queue, go-stash, asynq, DTM, Kafka, Elasticsearch, Prometheus and the rest. If you plan to ship a product derived from this tree, the licence review that matters is over the dependency set, not over this one LICENSE file. That is a factual boundary, not legal advice.

On maintenance, the last push was on 2026-09-18 and the repository is not archived. Releases, however, are sparse: v1.0.7 dates from 2024-11-23 and the two before it from 2023-06-08 and 2022-12-03. The README does not document an upgrade procedure between releases, and it does not document rollback. The upgrade cost you should budget for is therefore the middleware versions you inherit, not the repository's own tags.

The practical consequence is that adopting this as a base means owning the assembly. The deploy/script/gencode and deploy/script/mysql scripts regenerate code from your own definitions, and the deploy/goctl templates are copied into your home directory, which means template changes are yours to manage. The README points readers at the go zero community group for k8s deployment questions rather than a documented support channel, so plan for self-service.

Editorial conclusion

Adopt it as a reading and scaffolding reference if you are already committed to go-zero and want to see API, RPC, MQ and observability wired together in one repository; its last push was on 2026-09-18 and the newest release is v1.0.7 from 2024-11-23. Do not adopt it if you need a supported library, a starter template with a documented upgrade path, or a stack you can run without Docker Compose and the surrounding middleware. Before you commit, verify that docker-compose-env.yml brings up the dependencies you actually intend to use, that the deploy/script/gencode and deploy/script/mysql scripts match your own schema and service names, and that the doc/english pages cover the deployment path you plan to take.

Frequently asked questions

Official sources

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