Getting Started
This section walks you from a blank machine to a running go-zero service. By the end you will have Go, goctl, and (optionally) protoc installed, and you will have run your first HTTP API and RPC service.
Estimated time: ~15 minutes for the full path, or ~5 minutes for Hello World only.
| Requirement | Minimum version | Notes |
|---|---|---|
| Go | 1.21 | Download |
| goctl | latest | go-zero’s code-generation CLI |
| protoc | 3.x | Required for RPC services only |
Recommended Learning Path
Follow the steps in order the first time:
1. Install Go → installation/golang
2. Install goctl → installation/goctl
3. Install protoc → installation/protoc (RPC only)
4. Configure IDE → installation/ide-plugins
5. Understand API DSL → ../reference/api-dsl
6. Hello World → ../guides/quickstart/hello-world ← start here if impatient
7. Full API service → ../guides/quickstart/api-service
8. Full RPC service → ../guides/quickstart/rpc-service
60-Second Quick Start
Already have Go ≥ 1.21? Run this:
# Install goctl
go install github.com/zeromicro/go-zero/tools/goctl@latest
# Scaffold and run a Hello World API
goctl api new greet
cd greet
go mod tidy
go run greet.go
Then in another terminal:
curl http://localhost:8888/from/you
# {"message":"Hello you"}
That’s it — you have a running API service. Continue to the full API quickstart to learn how to add handlers, middleware, and database access.
What goctl Generates
Running goctl api new greet produces a complete, production-ready layout:
greet/
├── etc/
│ └── greet-api.yaml # configuration file
├── internal/
│ ├── config/ # config struct
│ ├── handler/ # HTTP handlers (auto-registered)
│ ├── logic/ # business logic (edit this)
│ ├── middleware/ # custom middleware hooks
│ ├── svc/ # service context (shared dependencies)
│ └── types/ # request/response types
├── greet.go # entrypoint
└── greet.api # DSL source
Edit only the files in internal/logic/. Everything else is regenerated from the .api file whenever you run goctl api go.