# zeromicro/go-zero: A Go Microservices Framework Where goctl Generates the Boilerplate

> go-zero pairs a net/http-compatible web framework and a gRPC layer (zrpc) with goctl, a code generator driven by .api and .proto files. It is for Go teams that want resilience middleware wired in by default; it is not a fit if you will not adopt its generated project layout.

**zeromicro/go-zero** — go-zero is a cloud-native Go web and RPC microservices framework with built-in resilience design and goctl, a CLI that generates multi-language code from .api files.

- Repository: https://github.com/zeromicro/go-zero
- Website: https://go-zero.dev
- Stars: 33,358 · Forks: 4,320
- Language: Go
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/zeromicro-go-zero

## The problem go-zero solves: resilience code you would otherwise write by hand

The README states the framework was born to ensure the stability of busy services with resilience design, and that it has been serving sites with tens of millions of users. That sentence is the whole pitch. In a plain net/http service, timeout control, concurrency limits, rate limiting, circuit breaking and load shedding are things each team writes, usually after an incident. go-zero ships them as built-in behavior. The README lists chained timeout control, concurrency control, rate limit, adaptive circuit breaker and adaptive load shedding, and adds that these need no configuration. The intended audience is a Go team running services where a slow dependency can cascade. It is less useful for a single internal tool with one endpoint and no downstream calls, because you pay the framework's conventions for protection you never exercise.

## How go-zero is put together: rest, zrpc, core, and the goctl generator

The repository layout tells most of the story. rest/ holds the HTTP side, zrpc/ the RPC side, core/ the shared machinery, gateway/ an API gateway, and tools/ the goctl command. The README describes go-zero as a web and rpc framework and says the API syntax is simple and fully compatible with net/http, which matters if you already have handlers you do not want to rewrite.

The data flow starts with a description file. You write an .api file for HTTP services or .proto for RPC, and goctl turns it into a directory tree. The README's generated example shows etc/greet-api.yaml for configuration, greet.go as the main file, internal/config/config.go for the configuration definition, internal/handler for routes, internal/logic for request logic, and internal/svc/servicecontext.go described in the README as the service context for mysql/redis. The split between handler and logic is the framework's main opinion: routing is generated, business code lives in logic files that regeneration does not overwrite.

The dependencies in go.mod show what the framework reaches for. etcd client v3 for service discovery, go-redis v9 and pgx v5 and the MySQL driver for storage, OpenTelemetry with OTLP, Zipkin and stdout exporters for tracing, Prometheus client_golang for metrics, and automaxprocs for container CPU limits. Those are framework-level choices, not a menu you assemble.

## Installing goctl and generating a first go-zero service

The README gives the library install as a go get against the module path, run from inside your project.

```shell
go get -u github.com/zeromicro/go-zero
```

That pulls the framework into an existing module. The generator is a separate binary. The README lists four ways to get it, and the README says to ensure goctl is executable and in your $PATH.

```shell
go install github.com/zeromicro/go-zero/tools/goctl@latest
```

macOS users have a Homebrew path, and there is a Docker image for all platforms.

```shell
brew install goctl
```

```shell
docker pull kevinwan/goctl
docker run --rm -it -v `pwd`:/app kevinwan/goctl --help
```

With goctl on your PATH, the README's quick start writes an .api file. The example uses a path parameter with an options list, and the README notes that parameters are auto validated.

```go
type (
  Request {
    Name string `path:"name,options=[you,me]"` // parameters are auto validated
  }

  Response {
    Message string `json:"message"`
  }
)

service greet-api {
  @handler GreetHandler
  get /greet/from/:name(Request) returns (Response)
}
```

If you would rather start from a template, the README gives goctl api -o greet.api. Then one command generates the server tree.

```shell
goctl api go -api greet.api -dir greet
```

You should end up with the structure quoted in the README: greet/etc/greet-api.yaml, greet/greet.go, and internal/config, internal/handler, internal/logic and internal/svc. Your first real edit is greet/internal/logic/greetlogic.go, where the response is filled in. The README does not show the body of that file, so read the generated stub before changing it.

## Where go-zero fights you: codegen assumptions and a thin README

The first limitation is structural. go-zero's advertised value is built-in resilience plus code generation, and the generation assumes a layout. If your team already has a project shape, adopting go-zero means either moving to the generated tree or using the rest/ and zrpc/ packages directly and giving up the parts the README leads with. There is no documented middle path in the README.

The second is documentation depth. The README is a landing page, not a manual. It links to two external walkthroughs, one on rapid development of microservice systems and one with multiple RPCs, and the quick start stops after generation. The README does not document rollback, does not describe what regeneration does to files you have edited, and does not explain the configuration keys inside etc/greet-api.yaml. For a framework whose selling point is built-in behavior that needs no configuration, the absence of a configuration reference in the README is a real gap.

The third is that the resilience features are described qualitatively. The README says chained timeout control, adaptive circuit breaker and adaptive load shedding are built in, but it gives no thresholds, no defaults, and no guidance on when adaptive behavior is the wrong choice. If you need to reason precisely about failure behavior before an incident, you will be reading the source in core/ rather than the README.

Finally, the AI tooling section is separate from the framework. The README points to ai-context, zero-skills and mcp-zero as three distinct repositories, with setup instructions per editor. That is a second integration to maintain, and the README's own example flow depends on all three.

## go-zero compared with assembling net/http and gRPC yourself

The realistic alternative is not another framework so much as the standard library plus a few libraries. A Go team can build HTTP services on net/http, use google.golang.org/grpc for RPC, wire etcd or Kubernetes service discovery manually, and add middleware for rate limiting and circuit breaking from separate packages. You keep full control of layout and you upgrade each piece on its own schedule.

The difference in approach is where the opinions live. With net/http and gRPC, the framework is a set of libraries you call; nothing generates your project tree, and nothing is enabled unless you enable it. go-zero inverts that. The README's design principles include encapsulate complexity and one way to do one thing, and the generated tree is how that principle is enforced. You get protection by default, and you get a directory structure you did not choose.

Because go-zero's HTTP layer is fully compatible with net/http per the README, the migration cost in one direction is lower than it looks: handlers written against net/http are not foreign. The cost sits in the generated scaffolding and in the configuration format, not in the handler signatures.

## Maintenance, releases and the MIT licence

The repository is not archived, and the last push was on 2026-08-01. That is recent enough that the project is not dormant. The release list shows v1.10.3 and tools/goctl/v1.10.2 both dated 2026-08-01, with v1.10.2 before that on 2026-05-31. The framework module and the goctl tool version independently, which matters for upgrades: bumping goctl does not imply a framework change, and vice versa.

go.mod declares go 1.25.0, so the toolchain floor is a real constraint on older CI images. The dependency list is long and includes etcd client v3, gRPC, OpenTelemetry, Prometheus, pgx, go-redis, the MongoDB driver v2 and several Kubernetes client libraries. Those are the transitive upgrade surface you inherit. If your organization pins Kubernetes client versions, check for conflicts before adopting.

The licence is MIT, which the README also links. MIT is permissive and places few obligations on how you distribute derived work, but this is not legal advice and the LICENSE file in the repository is the text that governs.

## Conclusion

Adopt go-zero if you are building Go services that need timeout control, rate limiting, circuit breaking and load shedding without assembling that stack yourself, and if you accept the layout goctl generates. Do not adopt it if you want to keep an existing project structure and add resilience as a library, because the framework's value is concentrated in generated code and its conventions. Before committing, install goctl, generate the greet example, edit greetlogic.go, and read the generated etc/greet-api.yaml to confirm the configuration shape matches how you deploy.

## FAQ

### What is zeromicro/go-zero?

It is a Go web and RPC framework that ships with engineering practices for service stability, plus a code generation tool called goctl. The README describes it as a web and rpc framework with lots of builtin engineering practices, and it is listed in the CNCF Landscape.

### How do I install goctl for go-zero?

The README gives four routes: go install github.com/zeromicro/go-zero/tools/goctl@latest, brew install goctl on macOS, or the Docker image kevinwan/goctl. It also says to ensure goctl is executable and in your $PATH.

### Does go-zero work with net/http?

Yes. The README states the API syntax is simple and fully compatible with net/http, and lists that compatibility as a feature of the framework's implementation.

### What is the licence for go-zero?

The repository licence is MIT, and the README links to the MIT licence badge. The LICENSE file in the repository is the governing text.

## Sources

- [Official documentation](https://go-zero.dev)
- [Official README](https://github.com/zeromicro/go-zero#readme)
- [Project repository](https://github.com/zeromicro/go-zero)
- [Release notes](https://github.com/zeromicro/go-zero/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zeromicro-go-zero