go-zero README

The project's README from github.com/zeromicro/go-zero. As one markdown file: README.md.

go-zero

go-zero is a web and rpc framework with lots of builtin engineering practices. It’s born to ensure the stability of the busy services with resilience design and has been serving sites with tens of millions of users for years.

codecov Go Report Card Release Go Reference Awesome Go License: MIT Discord

🤷‍ What is go-zero?

English | 简体中文 | 한국어

zeromicro%2Fgo-zero | Trendshift go-zero - A web & rpc framework written in Go. | Product Hunt

go-zero (listed in CNCF Landscape: https://landscape.cncf.io/?selected=go-zero) is a web and rpc framework with lots of builtin engineering practices. It’s born to ensure the stability of the busy services with resilience design and has been serving sites with tens of millions of users for years.

go-zero contains simple API description syntax and code generation tool called goctl. You can generate Go, iOS, Android, Kotlin, Dart, TypeScript, JavaScript from .api files with goctl.

Advantages of go-zero:

Architecture

Backgrounds of go-zero

In early 2018, we transitioned from a Java+MongoDB monolithic architecture to microservices, choosing:

Design considerations on go-zero

go-zero follows these core design principles:

The implementation and features of go-zero

go-zero integrates engineering best practices:

Resilience

Architecture with go-zero

image

Installation

Run the following command under your project:

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

AI-Native Development

The go-zero team provides workflow guidance and implementation patterns for AI coding assistants such as Claude Code, GitHub Copilot, and Cursor. For assistants with terminal access, the recommended workflow is to run goctl directly to generate framework-compliant code.

AI Tooling Projects

Quick Setup

Install goctl and ensure it is available in your $PATH:

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

Follow the ai-context setup guide and zero-skills integration guides to configure your assistant's workflow instructions and pattern library.

How It Works

  1. Consult ai-context for the workflow and zero-skills for relevant patterns.
  2. Define the .api or .proto specification, then run goctl in the terminal to generate code.
  3. Implement business logic, resolve dependencies, build, and test the service.

Example: Create a REST API → write the .api specification → run goctl api go → implement the logic using zero-skills patterns → run go mod tidy, go build ./..., and go test ./....

Optional MCP Integration

For clients that use MCP tools, such as Claude Desktop, configure mcp-zero to invoke goctl through MCP. It uses the same code generation engine; assistants with terminal access can use the direct workflow above without an MCP server.

Quick Start

  1. Full examples:

    Rapid development of microservice systems

    Rapid development of microservice systems - multiple RPCs

  2. Install goctl

    # for Go
go install github.com/zeromicro/go-zero/tools/goctl@latest

# For Mac
brew install goctl

# docker for all platforms
docker pull kevinwan/goctl
# run goctl
docker run --rm -it -v `pwd`:/app kevinwan/goctl --help

    Ensure goctl is executable and in your $PATH.

  3. Create the API file (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 .api template:

    goctl api -o greet.api

  4. Generate Go server code

    goctl api go -api greet.api -dir greet

    Generated structure:

    ├── greet
│   ├── etc
│   │   └── greet-api.yaml        // configuration file
│   ├── greet.go                  // main file
│   └── internal
│       ├── config
│       │   └── config.go         // configuration definition
│       ├── handler
│       │   ├── greethandler.go   // get/put/post/delete routes are defined here
│       │   └── routes.go         // routes list
│       ├── logic
│       │   └── greetlogic.go     // request logic can be written here
│       ├── svc
│       │   └── servicecontext.go // service context, mysql/redis can be passed in here
│       └── types
│           └── types.go          // request/response defined here
└── greet.api                     // api description file

    Run the service:

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

    Default port: 8888 (configurable in etc/greet-api.yaml)

    Test with curl:

    curl -i http://localhost:8888/greet/from/you

    Response:

    HTTP/1.1 200 OK
Date: Sun, 30 Aug 2020 15:32:35 GMT
Content-Length: 0

  5. Write business logic

    • Pass dependencies (mysql, redis, etc.) via servicecontext.go
    • Add logic code in the logic package per .api definition

  6. Generate client code for multiple languages

    goctl api java -api greet.api -dir greet
goctl api dart -api greet.api -dir greet
...

Benchmark

benchmark

Checkout the test code

Documents

Chat group

Join the chat via https://discord.gg/4JQvC5A4Fe

Cloud Native Landscape

   

go-zero enlisted in the CNCF Cloud Native Landscape.

Give a Star! ⭐

If you like this project or are using it to learn or start your own solution, give it a star to get updates on new releases. Your support matters!

go-zero (zeromicro/go-zero)

Searching Database…

33.4K ·GitHub
Go-zero
What is this?go-zero is a cloud-native Go framework for building web and RPC microservices, packed with built-in engineering practices. It has been serving sites with tens of millions of users for years and is listed in the CNCF Landscape.
Is it a framework or a separate command-line tool?Both: the core is a web and RPC framework for Go, and it ships with goctl, a CLI that turns simple .api description files into generated code.
How do I get a service running?Describe your service in go-zero's simple .api syntax and run goctl — one command generates the service code, and you build your logic on top of the framework.
Does it force me off the standard Go HTTP stack?No — its simple API keeps interfaces fully compatible with net/http, and the built-in middlewares can also be integrated into your own frameworks.
Is this aimed at big production systems or hobby projects?It targets busy production services: go-zero is designed for stability under high concurrency and cites services with tens of millions of daily active users.
Which languages can goctl generate besides Go?From the same .api files it can generate Go, iOS, Android, Kotlin, Dart, TypeScript and JavaScript, so web and mobile clients get SDKs straight from the service definition.
Why did the team build their own framework instead of using an existing one?In early 2018 they migrated a Java+MongoDB monolith to microservices: they chose Go for performance and low resource consumption, and a self-designed framework for better problem isolation and faster issue resolution.
What do I get out of the box without writing resilience code myself?Chained timeout control, concurrency control, rate limiting, adaptive circuit breaker and adaptive load shedding are built in, typically with zero configuration; service discovery, load balancing and call tracing are included too.
Does it validate incoming requests for me?Yes — client request parameters are validated automatically, one of the built-in developer tools alongside cache management and metrics and monitoring.
What are similar projects?kratos, gofr, spring-cloud-alibaba, fiber, grpc-gateway, echo, resty, chi
Which topics is it in?restful-api, restful, circuit-breaker, microservices-architecture, service-discovery, spec-driven-development, microservice, rate-limiting, tracing, gateway, load-balancer, rpc
Creator
zeromicro
Size
32.4 MB
Stars
33.4K
Updated
CommitOct 14Releasev1.10.3Aug 01
Age
6y
Commits · 90 Days