< img align = "right" width = "150px" src = "https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/go-zero.png" >
# go-zero
English | [简体中文 ](readme-cn.md )
[](https://github.com/zeromicro/go-zero/actions)
[](https://codecov.io/gh/zeromicro/go-zero)
[](https://goreportcard.com/report/github.com/zeromicro/go-zero)
[](https://github.com/zeromicro/go-zero)
[](https://opensource.org/licenses/MIT)
[](https://discord.gg/4JQvC5A4Fe)
< a href = "https://www.producthunt.com/posts/go-zero?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-go-zero" target = "_blank" > < img src = "https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=334030&theme=light" alt = "go-zero - A web & rpc framework written in Go. | Product Hunt" style = "width: 250px; height: 54px;" width = "250" height = "54" / > < / a >
**Note: To meet the requirements of Open Source Foundation, we moved go-zero from tal-tech to zeromicro (a neutral GitHub organization).**
> ***Important!***
>
> To upgrade from previous versions, run the following commands.
>
> `go install github.com/zeromicro/go-zero/tools/goctl@latest`
>
> `goctl migrate —verbose —version v1.3.0`
## 0. what is go-zero
go-zero (listed in CNCF Landscape: [https://landscape.cncf.io/?selected=go-zero ](https://landscape.cncf.io/?selected=go-zero )) is a web and rpc framework with lots of builtin engineering practices. It’
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:
* improve the stability of the services with tens of millions of daily active users
* builtin chained timeout control, concurrency control, rate limit, adaptive circuit breaker, adaptive load shedding, even no configuration needed
* builtin middlewares also can be integrated into your frameworks
* simple API syntax, one command to generate a couple of different languages
* auto validate the request parameters from clients
* plenty of builtin microservice management and concurrent toolkits
< img src = "https://raw.githubusercontent.com/zeromicro/zero-doc/main/doc/images/architecture-en.png" alt = "Architecture" width = "1500" / >
## 1. Backgrounds of go-zero
At the beginning of 2018, we decided to re-design our system, from monolithic architecture with Java+MongoDB to microservice architecture. After research and comparison, we chose to:
* Golang based
* great performance
* simple syntax
* proven engineering efficiency
* extreme deployment experience
* less server resource consumption
* Self-designed microservice architecture
* I have rich experience in designing microservice architectures
* easy to locate the problems
* easy to extend the features
## 2. Design considerations on go-zero
By designing the microservice architecture, we expected to ensure stability, as well as productivity. And from just the beginning, we have the following design principles:
* keep it simple
* high availability
* stable on high concurrency
* easy to extend
* resilience design, failure-oriented programming
* try best to be friendly to the business logic development, encapsulate the complexity
* one thing, one way
After almost half a year, we finished the transfer from a monolithic system to microservice system and deployed on August 2018. The new system guaranteed business growth and system stability.
## 3. The implementation and features of go-zero
go-zero is a web and rpc framework that integrates lots of engineering practices. The features are mainly listed below:
* powerful tool included, less code to write
* simple interfaces
* fully compatible with net/http
* middlewares are supported, easy to extend
* high performance
* failure-oriented programming, resilience design
* builtin service discovery, load balancing
* builtin concurrency control, adaptive circuit breaker, adaptive load shedding, auto-trigger, auto recover
* auto validation of API request parameters
* chained timeout control
* auto management of data caching
* call tracing, metrics, and monitoring
* high concurrency protected
As below, go-zero protects the system with a couple of layers and mechanisms:
## 4. Future development plans of go-zero
* auto-generate API mock server, make the client debugging easier
* auto-generate the simple integration test for the server-side just from the .api files
## 5. Installation
Run the following command under your project:
```shell
go get -u github.com/zeromicro/go-zero
```
## 6. Quick Start
0. full examples can be checked out from below:
[Rapid development of microservice systems ](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md )
[Rapid development of microservice systems - multiple RPCs ](https://github.com/zeromicro/zero-doc/blob/main/docs/zero/bookstore-en.md )
1. install goctl
`goctl` can be read as `go control` . `goctl` means not to be controlled by code, instead, we control it. The inside `go` is not `golang` . At the very beginning, I was expecting it to help us improve productivity, and make our lives easier.
```shell
# for Go 1.15 and earlier
GO111MODULE=on go get -u github.com/zeromicro/go-zero/tools/goctl@latest
# for Go 1.16 and later
go install github.com/zeromicro/go-zero/tools/goctl@latest
```
make sure goctl is executable.
2. create the API file, like greet.api, you can install the plugin of goctl in vs code, api syntax is supported.
```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)
}
```
the .api files also can be generated by goctl, like below:
```shell
goctl api -o greet.api
```
3. generate the go server-side code
```shell
goctl api go -api greet.api -dir greet
```
the generated files look like:
```Plain Text
├── 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
```
the generated code can be run directly:
```shell
cd greet
go mod init
go mod tidy
go run greet.go -f etc/greet-api.yaml
```
by default, it’
you can check it by curl:
```shell
curl -i http://localhost:8888/greet/from/you
```
the response looks like below:
```http
HTTP/1.1 200 OK
Date: Sun, 30 Aug 2020 15:32:35 GMT
Content-Length: 0
```
4. Write the business logic code
* the dependencies can be passed into the logic within servicecontext.go, like mysql, reds, etc.
* add the logic code in a logic package according to .api file
5. Generate code like Java, TypeScript, Dart, JavaScript, etc. just from the api file
```shell
goctl api java -api greet.api -dir greet
goctl api dart -api greet.api -dir greet
...
```
## 7. Benchmark
[Checkout the test code ](https://github.com/smallnest/go-web-framework-benchmark )
## 8. Documents (adding)
* [Documents ](https://go-zero.dev/en/ )
* [Rapid development of microservice systems ](https://github.com/zeromicro/zero-doc/blob/main/doc/shorturl-en.md )
* [Rapid development of microservice systems - multiple RPCs ](https://github.com/zeromicro/zero-doc/blob/main/docs/zero/bookstore-en.md )
* [Examples ](https://github.com/zeromicro/zero-examples )
## 9. Chat group
Join the chat via https://discord.gg/4JQvC5A4Fe
## 10. Cloud Native Landscape
< p float = "left" >
< img src = "https://landscape.cncf.io/images/left-logo.svg" width = "150" / >
< img src = "https://landscape.cncf.io/images/right-logo.svg" width = "200" / >
< / p >
go-zero enlisted in the [CNCF Cloud Native Landscape ](https://landscape.cncf.io/?selected=go-zero ).
## Give a Star! ⭐
If you like or are using this project to learn or start your solution, please give it a star. Thanks!
