Guide · Open source

How to use go-zero: install, generate code and run a Go API

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

go-zero is a web and RPC framework for Go with built-in engineering features such as timeouts, rate limiting, circuit breaking and load shedding. It also ships with goctl, a code generator that builds Go server code from a simple .api description file. This guide shows how to install both, generate a small REST service and run it.

go-zerozeromicro/go-zero · ★ 33.4k · MIT Install options & downloads

Quick start

1Install go-zero. Run go get -u github.com/zeromicro/go-zero inside your project directory.
2Install goctl. Install the generator with go install github.com/zeromicro/go-zero/tools/goctl@latest and confirm it runs with goctl --version.
3Write a .api file. Describe your request types, response types and routes in a plain-text greet.api file.
4Generate the server code. Run goctl api go -api greet.api -dir greet to create the project structure.
5Write your logic. Add your business code in internal/logic, where the generated logic file is.
6Run the service. Run go mod tidy, then start the service with go run greet.go using the config file in etc.

Check the prerequisites and install go-zero

go-zero is written in Go, so you need a Go toolchain installed. The README excerpt does not state a minimum Go version, so check the project's documentation for that.

Run the following command inside your project directory to add the library.

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

Install the goctl code generator

goctl is the command-line tool that generates code from .api files. The README lists three ways to get it: the Go installer, Homebrew on Mac, and a Docker image. Make sure goctl is executable and on your $PATH.

After installing, you can confirm it works by checking the version.

Go installer: use the go install command shown in the code block.
Mac: brew install goctl.
Any platform with Docker: run goctl through the kevinwan/goctl image.

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

Describe your API in a .api file

A .api file is a plain-text description of your request and response types and your routes. The example below defines a single GET route that takes a name in the path and returns a message. The name parameter is validated automatically by go-zero, using the options tag, so only the listed values are accepted.

You can also start from a template by running goctl api -o greet.api.

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

Generate the Go server code

Pass the .api file to goctl to create a project folder. goctl writes a configuration file, a main file, and internal packages for config, handlers, logic, service context and types. Your business logic goes in the logic package, and the handler and routes files are generated for you.

The README shows this layout for the greet example:

greet/etc/greet-api.yaml: configuration file.
greet/greet.go: main file.
greet/internal/config/config.go: configuration definition.
greet/internal/handler/greethandler.go: get, put, post and delete routes.
greet/internal/handler/routes.go: routes list.
greet/internal/logic/greetlogic.go: where request logic is written.
greet/internal/svc/servicecontext.go: service context, where MySQL or Redis can be passed in.
greet/internal/types/types.go: request and response types.

goctl api go -api greet.api -dir greet

Run the service

Move into the generated folder, download dependencies and start the service. The README excerpt ends mid-command on the config path, so use the file name that goctl generated in the etc folder (greet-api.yaml, as shown in the layout above) when you pass the -f flag.

go mod tidy resolves the dependencies for the generated project.
go run greet.go -f etc/ starts the service with the config file from the etc folder.

cd greet
go mod tidy
go run greet.go -f etc/greet-api.yaml

What people use it for

Building REST APIs in Go where you want routes, request parsing and parameter validation generated from one description file.
Creating microservices that call each other over RPC, using the same framework for web and RPC services.
Adding rate limiting, timeouts and circuit breaking to busy services without writing those mechanisms by hand.
Generating client code in other languages such as TypeScript, Dart or Kotlin from the same .api file.

Frequently asked questions

Is go-zero free to use?

go-zero is released under the MIT licence, which the README links to. You can use, modify and distribute it under those terms. Check the licence file in the repository for the full text.

What do I need to install before go-zero?

You need Go installed, since go-zero is a Go framework. The README excerpt does not specify a minimum Go version, so check the project documentation for compatibility. Docker is an optional way to run goctl.

How do I install goctl?

Run go install github.com/zeromicro/go-zero/tools/goctl@latest, or use brew install goctl on Mac, or run the kevinwan/goctl Docker image. Then confirm it works with goctl --version.

Can go-zero generate code for other languages?

Yes. The README says goctl can generate Go, iOS, Android, Kotlin, Dart, TypeScript and JavaScript code from .api files. It is the client side for these languages that the README describes.

How does go-zero compare to Gin or Echo?

Gin and Echo are web frameworks that you mostly write by hand. go-zero adds code generation from .api files and built-in resilience features like rate limiting and circuit breakers, but it also generates more boilerplate and adds its own conventions. Pick go-zero if you want those features built in, and a lighter framework if you prefer to write everything yourself.

Why does my go-zero service fail to start?

The README excerpt does not cover troubleshooting. Start by confirming that go mod tidy ran without errors and that the -f flag points to the config file in the etc folder, such as etc/greet-api.yaml. The go-zero documentation linked from the project is the next place to look.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

go-zero suits Go developers building REST APIs or microservices who want resilience features and code generation from a .api file. If you prefer to write everything by hand, want only the standard library, or work in a non-Go stack, a lighter framework such as Gin or Echo, or go-kit or Kratos for microservices, is a better fit.

Install options & downloads