go-zero: the handler, the routes and the config are all generated from one .api file

One .api file becomes the server, the routes and the config

The quick start is the clearest explanation of the project, because it shows the whole workflow in one file and two commands.

You create an API file describing the request type, the response type and the route, with a handler annotation. Then you ask the tool for a template of that file, or write your own, and generate the Go server code from it. The generated structure is a directory containing a configuration file, a main file, and an internal tree with a configuration definition, a handler file where the get, put, post and delete routes are defined, and a routes file listing them.

The commands are:

goctl api -o greet.api

to produce the template, and then:

goctl api go -api greet.api -dir greet

to produce the server.

So the division of labour is that the tool owns the shape and the developer owns the behaviour. It writes the routing table, the configuration structure and the stubs; you fill in the handler. The design consequence is that the framework's expectations about your code are visible in the directory it generates, which is a far better starting point than a documentation page describing where things go.

options=[you,me] turns a path parameter into a checked enum

The API file in the example is a Go-looking block, and one line in it carries most of the framework's argument about validation.

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)
}

The path parameter is tagged with a list of permitted values, and the comment states that parameters are auto validated. That is the feature list's claim about validating request parameters from clients, made concrete: the enumeration lives in the interface description, and the README says the parameters are auto validated.

Adding a third permitted value is an edit to the API file and a regeneration. That is the right default for an enumeration, and it is a constraint worth noticing if your route parameters are free-form.

Seven client languages from one description, and the tool versions separately

The project is not only a server framework. The API description syntax and the generator together can produce Go, iOS, Android, Kotlin, Dart, TypeScript and JavaScript from the same .api file, and the feature list puts it as one command generating a couple of different languages.

That is the argument for a description file at all. A hand-written client in seven languages drifts; a generated one is a build artefact, and the cost of regenerating is a command.

The version lines are the practical wrinkle. The release tags show the framework at 1.10.3 and the tool at a separately tagged 1.10.2, and both were published on the same day within about twenty minutes of each other. So the tool trails the framework by a version, and it is versioned independently.

That matters for a team pinning dependencies, because upgrading the framework and upgrading the generator are two decisions. The tool is installed separately, three ways in the quick start, and the README ends that step by telling you to ensure it is executable and in your path, which is the step people skip and then wonder why nothing generates.

The recommended AI workflow is a terminal, and the protocol adapter is optional

The project has a section on AI-native development, and it is more concrete than most.

Three companion repositories are named. One holds workflow guidance, described as how to approach a go-zero development task and when to reach for the generator. A second holds implementation patterns, examples and a command reference for the tool, loaded as needed rather than all at once. A third is an optional adapter that exposes code generation through the Model Context Protocol.

The recommended flow is described in three steps: consult the workflow guidance and the patterns, define the specification, then run the generator in a terminal to produce the code, then implement the logic and build and test. The worked example is a REST API: write the description, run the generator, implement using the patterns, then run the module tidy, build and test commands.

And the README says the quiet part out loud: assistants with terminal access can use the direct workflow without needing a protocol server. That is worth reading before anyone stands up an adapter, because the project's own position is that the tool is a terminal program and the protocol is a convenience for clients that cannot reach a shell.

Four trace exporters and a profiler are direct dependencies

The module definition is the honest description of what the framework expects to run alongside it, and the observability entries are the most telling.

Tracing is OpenTelemetry, with the core library, the software development kit and the trace API, plus four exporters in the same list: one over gRPC, one over HTTP, one to standard output, and one for Zipkin. So trace export is a supported set of transports rather than a single default, and choosing one is a deployment decision.

Alongside that sits a continuous profiling client, a Prometheus client, and a library that sets container CPU limits for Go processes, which is what makes a Go service inside a container respect the limit it was given rather than the machine's core count. There is also a progress bar library, a JSON5 parser for configuration, a TOML parser, JSON Web Tokens, a MySQL driver, a Postgres driver, a Redis client, a MongoDB driver, a mock Redis for tests, a database mock, an HTTP mock, a goroutine leak detector, and the Kubernetes client libraries at a recent version.

The design brief is one 2018 migration off a Java and MongoDB monolith

The project explains where it came from, and the explanation is the reason to believe the feature list.

In early 2018 the team moved from a Java and MongoDB monolithic architecture to microservices, and it chose two things: the language, for performance, simple syntax, deployment experience and low resource consumption, and a self-designed microservice framework, for better problem isolation, easier feature extension and faster issue resolution.

Now read the feature list against that. Builtin chained timeout control, concurrency control, rate limiting, an adaptive circuit breaker and adaptive load shedding, with the claim that some need no configuration at all. Service discovery, load balancing and call tracing. Those are not generic framework features; they are the things that go wrong when you decompose a monolith that was holding traffic, and they are the reason the project says it has been serving sites with tens of millions of users.

The principles the project states follow the same logic: simplicity as the first principle, stability under high concurrency, failure-oriented programming with adaptive protection, one way to do one thing, and a flexible architecture for growth.

Compatibility with net/http is the interoperability claim, and Go 1.25 is the floor

One feature is stated as an interface property rather than a capability: the API is described as clean and fully compatible with the standard library's HTTP package.

That is the load-bearing interoperability claim in a Go framework. It means the framework is not asking you to give up the standard library's server, its handler signature or its middleware shape, so a service can move in and out of it without rewriting its transport layer. The generated routes file and handler file are where you would see whether that holds in practice.

The module definition sets the language floor at Go 1.25, which is recent enough that a build image or a CI image will need updating rather than inheriting whatever is installed.

The repository layout has these top-level directories: a core directory, an RPC layer, a REST layer, a gateway, internal packages, an mcp directory, and the tools directory that holds the generator.

Editorial conclusion

Use go-zero if you are building Go microservices and you want the routing table, the configuration file and the parameter validation to be generated rather than maintained, and you want resilience features in place by default rather than added later. Do not choose it because of the AI tooling, because the project's own recommendation is to run goctl in a terminal and treat the protocol adapter as optional. Before you start: note that the framework and the tool have separate version lines and the tool can trail the framework, so pin both; expect a Go 1.25 floor from the module definition, which is newer than most production images; and read the generated directory layout before you write your first handler, because the layout tells you where the framework expects your code and where it expects yours.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes