zeromicro
/
go-zero
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Markdown lint (#58)

Browse Source 
* markdown linter

* format markdown docs

* format exiting markdown docs
master
Sergey Cheung 4 years ago committed by GitHub
parent 7f0ec14704
commit 21e811887c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
24 changed files with 537 additions and 436 deletions
Show Stats Download Patch File Download Diff File

22
.github/workflows/markdown.yml vendored
Unescape Escape View File

@ -0,0 +1,22 @@
name: Markdown linter
on:
push:
branches: [ master ]
pull_request:
branches: [ master ]
jobs:
linter:
name: markdown linter
runs-on: ubuntu-latest
steps:
- name: Check out code
uses: actions/checkout@v2
- name: Markdown Linting Action
uses: avto-dev/markdown-lint@v1.3.1
with:
args: 'find . -name "*.md"'

6
.markdownlint.json
Unescape Escape View File

@ -0,0 +1,6 @@
{
"MD010": false,
"MD013": false,
"MD033": false,
"MD034": false
}

21
doc/bookstore-en.md
Unescape Escape View File

@ -1,8 +1,8 @@
English | [简体中文](bookstore.md)
# Rapid development of microservices - multiple RPCs # Rapid development of microservices - multiple RPCs
## 0. Why building microservices are so difficult? English | [简体中文](bookstore.md)
## 0. Why building microservices are so difficult
To build a well working microservice, we need lots of knowledges from different aspects. To build a well working microservice, we need lots of knowledges from different aspects.
@ -25,7 +25,7 @@ As well, we always adhere to the idea that **prefer tools over conventions and d
Let’s take the shorturl microservice as a quick example to demonstrate how to quickly create microservices by using [go-zero](https://github.com/tal-tech/go-zero). After finishing this tutorial, you’ll find that it’s so easy to write microservices! Let’s take the shorturl microservice as a quick example to demonstrate how to quickly create microservices by using [go-zero](https://github.com/tal-tech/go-zero). After finishing this tutorial, you’ll find that it’s so easy to write microservices!
## 1. What is a bookstore service? ## 1. What is a bookstore service
For simplicity, the bookstore service only contains two functionalities, adding books and quering prices. For simplicity, the bookstore service only contains two functionalities, adding books and quering prices.
@ -71,7 +71,7 @@ And now, let’s walk through the complete flow of quickly create a microservice
* use goctl to generate `api/bookstore.api` * use goctl to generate `api/bookstore.api`
``` ```Plain Text
goctl api -o bookstore.api goctl api -o bookstore.api
``` ```
@ -128,7 +128,7 @@ And now, let’s walk through the complete flow of quickly create a microservice
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
api api
├── bookstore.api // api definition ├── bookstore.api // api definition
├── bookstore.go // main entrance ├── bookstore.go // main entrance
@ -220,7 +220,7 @@ syntax = "proto3";
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
rpc/add rpc/add
├── add.go // rpc main entrance ├── add.go // rpc main entrance
├── add.proto // rpc definition ├── add.proto // rpc definition
@ -243,7 +243,6 @@ syntax = "proto3";
└── add.pb.go └── add.pb.go
``` ```
just run it, looks like: just run it, looks like:
```shell ```shell
@ -290,7 +289,7 @@ syntax = "proto3";
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
rpc/check rpc/check
├── check.go // rpc main entrance ├── check.go // rpc main entrance
├── check.proto // rpc definition ├── check.proto // rpc definition
@ -444,7 +443,7 @@ Till now, we’ve done the modification of API Gateway. All the manually added c
source book.sql; source book.sql;
``` ```
* under the directory `rpc/model execute the following command to genrate CRUD+cache code, `-c` means using `redis cache` * under the directory `rpc/model` execute the following command to genrate CRUD+cache code, `-c` means using `redis cache`
```shell ```shell
goctl model mysql ddl -c -src book.sql -dir . goctl model mysql ddl -c -src book.sql -dir .
@ -454,7 +453,7 @@ Till now, we’ve done the modification of API Gateway. All the manually added c
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
rpc/model rpc/model
├── bookstore.sql ├── bookstore.sql
├── bookstoremodel.go // CRUD+cache code ├── bookstoremodel.go // CRUD+cache code

18
doc/bookstore.md
Unescape Escape View File

@ -1,8 +1,8 @@
[English](bookstore-en.md) | 简体中文
# 快速构建微服务-多RPC版 # 快速构建微服务-多RPC版
## 0. 为什么说做好微服务很难？ [English](bookstore-en.md) | 简体中文
## 0. 为什么说做好微服务很难
要想做好微服务，我们需要理解和掌握的知识点非常多，从几个维度上来说： 要想做好微服务，我们需要理解和掌握的知识点非常多，从几个维度上来说：
@ -71,7 +71,7 @@
* 在`bookstore/api`目录下通过goctl生成`api/bookstore.api`： * 在`bookstore/api`目录下通过goctl生成`api/bookstore.api`：
``` ```bash
goctl api -o bookstore.api goctl api -o bookstore.api
``` ```
@ -128,7 +128,7 @@
生成的文件结构如下： 生成的文件结构如下：
``` ```Plain Text
api api
├── bookstore.api // api定义 ├── bookstore.api // api定义
├── bookstore.go // main入口定义 ├── bookstore.go // main入口定义
@ -222,7 +222,7 @@
文件结构如下： 文件结构如下：
``` ```Plain Text
rpc/add rpc/add
├── add.go // rpc服务main函数 ├── add.go // rpc服务main函数
├── add.proto // rpc接口定义 ├── add.proto // rpc接口定义
@ -245,7 +245,6 @@
└── add.pb.go └── add.pb.go
``` ```
直接可以运行，如下： 直接可以运行，如下：
```shell ```shell
@ -294,7 +293,7 @@
文件结构如下： 文件结构如下：
``` ```Plain Text
rpc/check rpc/check
├── check.go // rpc服务main函数 ├── check.go // rpc服务main函数
├── check.proto // rpc接口定义 ├── check.proto // rpc接口定义
@ -454,7 +453,7 @@
生成后的文件结构如下： 生成后的文件结构如下：
``` ```Plain Text
rpc/model rpc/model
├── bookstore.sql ├── bookstore.sql
├── bookstoremodel.go // CRUD+cache代码 ├── bookstoremodel.go // CRUD+cache代码
@ -615,4 +614,3 @@ go-zero不只是一个框架，更是一个建立在框架+工具基础上的，
通过go-zero+goctl生成的代码，包含了微服务治理的各种组件，包括：并发控制、自适应熔断、自适应降载、自动缓存控制等，可以轻松部署以承载巨大访问量。 通过go-zero+goctl生成的代码，包含了微服务治理的各种组件，包括：并发控制、自适应熔断、自适应降载、自动缓存控制等，可以轻松部署以承载巨大访问量。
有任何好的提升工程效率的想法，随时欢迎交流！👏 有任何好的提升工程效率的想法，随时欢迎交流！👏

1
doc/breaker.md
Unescape Escape View File

@ -1,4 +1,5 @@
# 熔断机制设计 # 熔断机制设计
## 设计目的 ## 设计目的
* 依赖的服务出现大规模故障时，调用方应该尽可能少调用，降低故障服务的压力，使之尽快恢复服务 * 依赖的服务出现大规模故障时，调用方应该尽可能少调用，降低故障服务的压力，使之尽快恢复服务

4
doc/collection.md
Unescape Escape View File

@ -29,6 +29,7 @@ v, err := c.Take("key", func() (interface{}, error) {
``` ```
cache 实现的建的功能包括 cache 实现的建的功能包括
* 缓存自动失效，可以指定过期时间 * 缓存自动失效，可以指定过期时间
* 缓存大小限制，可以指定缓存个数 * 缓存大小限制，可以指定缓存个数
* 缓存增删改 * 缓存增删改
@ -38,6 +39,7 @@ cache 实现的建的功能包括
实现原理： 实现原理：
Cache 自动失效，是采用 TimingWheel(https://github.com/tal-tech/go-zero/blob/master/core/collection/timingwheel.go) 进行管理的 Cache 自动失效，是采用 TimingWheel(https://github.com/tal-tech/go-zero/blob/master/core/collection/timingwheel.go) 进行管理的
``` go ``` go
timingWheel, err := NewTimingWheel(time.Second, slots, func(k, v interface{}) { timingWheel, err := NewTimingWheel(time.Second, slots, func(k, v interface{}) {
key, ok := k.(string) key, ok := k.(string)
@ -50,6 +52,7 @@ timingWheel, err := NewTimingWheel(time.Second, slots, func(k, v interface{}) {
``` ```
Cache 大小限制，是采用 LRU 淘汰策略，在新增缓存的时候会去检查是否已经超出过限制，具体代码在 keyLru 中实现 Cache 大小限制，是采用 LRU 淘汰策略，在新增缓存的时候会去检查是否已经超出过限制，具体代码在 keyLru 中实现
``` go ``` go
func (klru *keyLru) add(key string) { func (klru *keyLru) add(key string) {
if elem, ok := klru.elements[key]; ok { if elem, ok := klru.elements[key]; ok {
@ -71,6 +74,7 @@ func (klru *keyLru) add(key string) {
Cache 的命中率统计，是在代码中实现 cacheStat,在缓存命中丢失的时候自动统计，并且会定时打印使用的命中率, qps 等状态. Cache 的命中率统计，是在代码中实现 cacheStat,在缓存命中丢失的时候自动统计，并且会定时打印使用的命中率, qps 等状态.
打印的具体效果如下 打印的具体效果如下
```go ```go
cache(proc) - qpm: 2, hit_ratio: 50.0%, elements: 0, hit: 1, miss: 1 cache(proc) - qpm: 2, hit_ratio: 50.0%, elements: 0, hit: 1, miss: 1
``` ```

46
doc/goctl-model-sql.md
Unescape Escape View File

@ -2,28 +2,28 @@
goctl model 为go-zero下的工具模块中的组件之一，目前支持识别mysql ddl进行model层代码生成，通过命令行或者idea插件（即将支持）可以有选择地生成带redis cache或者不带redis cache的代码逻辑。 goctl model 为go-zero下的工具模块中的组件之一，目前支持识别mysql ddl进行model层代码生成，通过命令行或者idea插件（即将支持）可以有选择地生成带redis cache或者不带redis cache的代码逻辑。
# 快速开始 ## 快速开始
* 通过ddl生成 * 通过ddl生成
```shell script ```shell script
$ goctl model mysql ddl -src="./sql/user.sql" -dir="./sql/model" -c=true goctl model mysql ddl -src="./sql/user.sql" -dir="./sql/model" -c=true
``` ```
执行上述命令后即可快速生成CURD代码。 执行上述命令后即可快速生成CURD代码。
``` ```Plain Text
model model
│   ├── error.go │   ├── error.go
│   └── usermodel.go │   └── usermodel.go
``` ```
* 通过datasource生成 * 通过datasource生成
```shell script ```shell script
$ goctl model mysql datasource -url="user:password@tcp(127.0.0.1:3306)/database" -table="table1,table2" -dir="./model" goctl model mysql datasource -url="user:password@tcp(127.0.0.1:3306)/database" -table="table1,table2" -dir="./model"
``` ```
* 生成代码示例 * 生成代码示例
``` go ``` go
@ -175,13 +175,13 @@ goctl model 为go-zero下的工具模块中的组件之一，目前支持识别m
} }
``` ```
# 用法 ### 用法
``` ```Plain Text
$ goctl model mysql -h goctl model mysql -h
``` ```
``` ```Plain Text
NAME: NAME:
goctl model mysql - generate mysql model" goctl model mysql - generate mysql model"
@ -196,7 +196,7 @@ OPTIONS:
--help, -h show help --help, -h show help
``` ```
# 生成规则 ## 生成规则
* 默认规则 * 默认规则
@ -205,12 +205,13 @@ OPTIONS:
* ddl * ddl
```shell script ```shell script
$ goctl model mysql -src={filename} -dir={dir} -cache=true goctl model mysql -src={filename} -dir={dir} -cache=true
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=true goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=true
``` ```
目前仅支持redis缓存，如果选择带缓存模式，即生成的`FindOne(ByXxx)`&`Delete`代码会生成带缓存逻辑的代码，目前仅支持单索引字段（除全文索引外），对于联合索引我们默认认为不需要带缓存，且不属于通用型代码，因此没有放在代码生成行列，如example中user表中的`id`、`name`、`mobile`字段均属于单字段索引。 目前仅支持redis缓存，如果选择带缓存模式，即生成的`FindOne(ByXxx)`&`Delete`代码会生成带缓存逻辑的代码，目前仅支持单索引字段（除全文索引外），对于联合索引我们默认认为不需要带缓存，且不属于通用型代码，因此没有放在代码生成行列，如example中user表中的`id`、`name`、`mobile`字段均属于单字段索引。
@ -220,28 +221,31 @@ OPTIONS:
* ddl * ddl
```shell script ```shell script
$ goctl model -src={filename} -dir={dir} goctl model -src={filename} -dir={dir}
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} goctl model mysql datasource -url={datasource} -table={tables} -dir={dir}
``` ```
or or
* ddl * ddl
```shell script ```shell script
$ goctl model -src={filename} -dir={dir} -cache=false goctl model -src={filename} -dir={dir} -cache=false
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=false goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=false
``` ```
生成代码仅基本的CURD结构。 生成代码仅基本的CURD结构。
# 缓存 ## 缓存
对于缓存这一块我选择用一问一答的形式进行罗列。我想这样能够更清晰的描述model中缓存的功能。 对于缓存这一块我选择用一问一答的形式进行罗列。我想这样能够更清晰的描述model中缓存的功能。
@ -261,14 +265,8 @@ OPTIONS:
目前，我认为除了基本的CURD外，其他的代码均属于<i>业务型</i>代码，这个我觉得开发人员根据业务需要进行编写更好。 目前，我认为除了基本的CURD外，其他的代码均属于<i>业务型</i>代码，这个我觉得开发人员根据业务需要进行编写更好。
# QA ## QA
* goctl model除了命令行模式，支持插件模式吗？ * goctl model除了命令行模式，支持插件模式吗？
很快支持idea插件。 很快支持idea插件。

45
doc/goctl-rpc.md
Unescape Escape View File

@ -1,12 +1,14 @@
# Rpc Generation # Rpc Generation
Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持proto模板生成和rpc服务代码生成，通过此工具生成代码你只需要关注业务逻辑编写而不用去编写一些重复性的代码。这使得我们把精力重心放在业务上，从而加快了开发效率且降低了代码出错率。 Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持proto模板生成和rpc服务代码生成，通过此工具生成代码你只需要关注业务逻辑编写而不用去编写一些重复性的代码。这使得我们把精力重心放在业务上，从而加快了开发效率且降低了代码出错率。
# 特性 ## 特性
* 简单易用 * 简单易用
* 快速提升开发效率 * 快速提升开发效率
* 出错率低 * 出错率低
# 快速开始 ## 快速开始
### 方式一：快速生成greet服务 ### 方式一：快速生成greet服务
@ -15,7 +17,7 @@ Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持prot
如生成greet rpc服务： 如生成greet rpc服务：
```shell script ```shell script
$ goctl rpc new greet goctl rpc new greet
``` ```
执行后代码结构如下: 执行后代码结构如下:
@ -46,12 +48,13 @@ Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持prot
``` ```
rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题解决</a> rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题解决</a>
### 方式二：通过指定proto生成rpc服务 ### 方式二：通过指定proto生成rpc服务
* 生成proto模板 * 生成proto模板
```shell script ```shell script
$ goctl rpc template -o=user.proto goctl rpc template -o=user.proto
``` ```
```golang ```golang
@ -78,15 +81,16 @@ rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题
rpc Login(Request)returns(Response); rpc Login(Request)returns(Response);
} }
``` ```
* 生成rpc服务代码 * 生成rpc服务代码
``` ```shell script
$ goctl rpc proto -src=user.proto goctl rpc proto -src=user.proto
``` ```
代码tree 代码tree
``` ```Plain Text
user user
├── etc ├── etc
│   └── user.json │   └── user.json
@ -109,19 +113,20 @@ rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题
└── user.proto └── user.proto
``` ```
# 准备工作
## 准备工作
* 安装了go环境 * 安装了go环境
* 安装了protoc&protoc-gen-go，并且已经设置环境变量 * 安装了protoc&protoc-gen-go，并且已经设置环境变量
* mockgen(可选,将移除) * mockgen(可选,将移除)
* 更多问题请见 <a href="#注意事项">注意事项</a> * 更多问题请见 <a href="#注意事项">注意事项</a>
# 用法 ## 用法
### rpc服务生成用法 ### rpc服务生成用法
```shell script ```shell script
$ goctl rpc proto -h goctl rpc proto -h
``` ```
```shell script ```shell script
@ -145,12 +150,14 @@ OPTIONS:
* --src 必填，proto数据源，目前暂时支持单个proto文件生成，这里不支持（不建议）外部依赖 * --src 必填，proto数据源，目前暂时支持单个proto文件生成，这里不支持（不建议）外部依赖
* --dir 非必填，默认为proto文件所在目录，生成代码的目标目录 * --dir 非必填，默认为proto文件所在目录，生成代码的目标目录
* --service 服务名称，非必填，默认为proto文件所在目录名称，但是，如果proto所在目录为一下结构： * --service 服务名称，非必填，默认为proto文件所在目录名称，但是，如果proto所在目录为一下结构：
```shell script ```shell script
user user
├── cmd ├── cmd
│   └── rpc │   └── rpc
│   └── user.proto │   └── user.proto
``` ```
则服务名称亦为user，而非proto所在文件夹名称了，这里推荐使用这种结构，可以方便在同一个服务名下建立不同类型的服务(api、rpc、mq等)，便于代码管理与维护。 则服务名称亦为user，而非proto所在文件夹名称了，这里推荐使用这种结构，可以方便在同一个服务名下建立不同类型的服务(api、rpc、mq等)，便于代码管理与维护。
* --shared[⚠️已废弃] 非必填，默认为$dir(xxx.proto)/shared，rpc client逻辑代码存放目录。 * --shared[⚠️已废弃] 非必填，默认为$dir(xxx.proto)/shared，rpc client逻辑代码存放目录。
@ -158,31 +165,38 @@ OPTIONS:
* --idea 非必填，是否为idea插件中执行，保留字段，终端执行可以忽略 * --idea 非必填，是否为idea插件中执行，保留字段，终端执行可以忽略
# 开发人员需要做什么 ## 开发人员需要做什么
关注业务代码编写，将重复性、与业务无关的工作交给goctl，生成好rpc服务代码后，开饭人员仅需要修改 关注业务代码编写，将重复性、与业务无关的工作交给goctl，生成好rpc服务代码后，开饭人员仅需要修改
* 服务中的配置文件编写(etc/xx.json、internal/config/config.go) * 服务中的配置文件编写(etc/xx.json、internal/config/config.go)
* 服务中业务逻辑编写(internal/logic/xxlogic.go) * 服务中业务逻辑编写(internal/logic/xxlogic.go)
* 服务中资源上下文的编写(internal/svc/servicecontext.go) * 服务中资源上下文的编写(internal/svc/servicecontext.go)
# 扩展 ## 扩展
对于需要进行rpc mock的开发人员，在安装了`mockgen`工具的前提下可以在rpc的shared文件中生成好对应的mock文件。 对于需要进行rpc mock的开发人员，在安装了`mockgen`工具的前提下可以在rpc的shared文件中生成好对应的mock文件。
# 注意事项 ## 注意事项
* `google.golang.org/grpc`需要降级到v1.26.0,且protoc-gen-go版本不能高于v1.3.2（see [https://github.com/grpc/grpc-go/issues/3347](https://github.com/grpc/grpc-go/issues/3347)）即 * `google.golang.org/grpc`需要降级到v1.26.0,且protoc-gen-go版本不能高于v1.3.2（see [https://github.com/grpc/grpc-go/issues/3347](https://github.com/grpc/grpc-go/issues/3347)）即
```
```shell script
replace google.golang.org/grpc => google.golang.org/grpc v1.26.0 replace google.golang.org/grpc => google.golang.org/grpc v1.26.0
``` ```
* proto不支持暂多文件同时生成 * proto不支持暂多文件同时生成
* proto不支持外部依赖包引入，message不支持inline * proto不支持外部依赖包引入，message不支持inline
* 目前main文件、shared文件、handler文件会被强制覆盖，而和开发人员手动需要编写的则不会覆盖生成，这一类在代码头部均有 * 目前main文件、shared文件、handler文件会被强制覆盖，而和开发人员手动需要编写的则不会覆盖生成，这一类在代码头部均有
```shell script ```shell script
// Code generated by goctl. DO NOT EDIT! // Code generated by goctl. DO NOT EDIT!
// Source: xxx.proto // Source: xxx.proto
``` ```
的标识，请注意不要将也写业务性代码写在里面。 的标识，请注意不要将也写业务性代码写在里面。
# 常见问题解决(go mod工程) ## 常见问题解决(go mod工程)
* 错误一: * 错误一:
@ -192,6 +206,7 @@ OPTIONS:
pb/xx.pb.go:234:5: undefined: grpc.ClientConnInterface pb/xx.pb.go:234:5: undefined: grpc.ClientConnInterface
pb/xx.pb.go:237:24: undefined: grpc.ClientConnInterface pb/xx.pb.go:237:24: undefined: grpc.ClientConnInterface
``` ```
解决方法：请将`protoc-gen-go`版本降至v1.3.2及一下 解决方法：请将`protoc-gen-go`版本降至v1.3.2及一下
* 错误二: * 错误二:

54
doc/goctl.md
Unescape Escape View File

@ -1,6 +1,7 @@
# goctl使用说明 # goctl使用
## goctl用途 ## goctl用途
* 定义api请求 * 定义api请求
* 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter) * 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter)
* 生成MySQL CURD+Cache * 生成MySQL CURD+Cache
@ -8,7 +9,8 @@
## goctl使用说明 ## goctl使用说明
#### 快速生成服务 ### 快速生成服务
* api: goctl api new xxxx * api: goctl api new xxxx
* rpc: goctl rpc new xxxx * rpc: goctl rpc new xxxx
@ -17,15 +19,22 @@
`goctl api [go/java/ts] [-api user/user.api] [-dir ./src]` `goctl api [go/java/ts] [-api user/user.api] [-dir ./src]`
> api 后面接生成的语言，现支持go/java/typescript > api 后面接生成的语言，现支持go/java/typescript
>
> -api 自定义api所在路径 > -api 自定义api所在路径
>
> -dir 自定义生成目录 > -dir 自定义生成目录
#### 保持goctl总是最新版
第一次运行会在~/.goctl里增加下面两行：
```Plain Text
url = http://47.97.184.41:7777/
```
#### API 语法说明 #### API 语法说明
``` golang ``` golang
info( info(
title: doc title title: doc title
desc: > desc: >
@ -132,6 +141,7 @@ service user-api {
请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。 请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。
#### api vscode插件 #### api vscode插件
开发者可以在vscode中搜索goctl的api插件，它提供了api语法高亮，语法检测和格式化相关功能。 开发者可以在vscode中搜索goctl的api插件，它提供了api语法高亮，语法检测和格式化相关功能。
1. 支持语法高亮和类型导航。 1. 支持语法高亮和类型导航。
@ -143,7 +153,7 @@ service user-api {
命令如下： 命令如下：
`goctl api go -api user/user.api -dir user` `goctl api go -api user/user.api -dir user`
``` ```Plain Text
. .
├── internal ├── internal
@ -173,17 +183,20 @@ service user-api {
└── user.go └── user.go
``` ```
生成的代码可以直接跑，有几个地方需要改： 生成的代码可以直接跑，有几个地方需要改：
* 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等 * 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等
* 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码 * 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码
#### 根据定义好的api文件生成java代码 #### 根据定义好的api文件生成java代码
```shell ```shell
goctl api java -api user/user.api -dir ./src goctl api java -api user/user.api -dir ./src
``` ```
#### 根据定义好的api文件生成typescript代码 #### 根据定义好的api文件生成typescript代码
```shell ```shell
goctl api ts -api user/user.api -dir ./src -webapi *** goctl api ts -api user/user.api -dir ./src -webapi ***
@ -191,6 +204,7 @@ ts需要指定webapi所在目录
``` ```
#### 根据定义好的api文件生成Dart代码 #### 根据定义好的api文件生成Dart代码
```shell ```shell
goctl api dart -api user/user.api -dir ./src goctl api dart -api user/user.api -dir ./src
``` ```
@ -198,18 +212,22 @@ goctl api dart -api user/user.api -dir ./src
## 根据mysql ddl或者datasource生成model文件 ## 根据mysql ddl或者datasource生成model文件
```shell script ```shell script
$ goctl model mysql -src={filename} -dir={dir} -cache={true|false} goctl model mysql -src={filename} -dir={dir} -cache={true|false}
``` ```
详情参考[model文档](https://github.com/tal-tech/go-zero/blob/master/tools/goctl/model/sql/README.MD) 详情参考[model文档](https://github.com/tal-tech/go-zero/blob/master/tools/goctl/model/sql/README.MD)
## 根据定义好的简单go文件生成mongo代码文件(仅限golang使用) ## 根据定义好的简单go文件生成mongo代码文件(仅限golang使用)
```shell ```shell
goctl model mongo -src {{yourDir}}/xiao/service/xhb/user/model/usermodel.go -cache yes goctl model mongo -src {{yourDir}}/xiao/service/xhb/user/model/usermodel.go -cache yes
```
* src需要提供简单的usermodel.go文件，里面只需要提供一个结构体即可
* cache 控制是否需要缓存 yes=需要 no=不需要
-src需要提供简单的usermodel.go文件，里面只需要提供一个结构体即可
-cache 控制是否需要缓存 yes=需要 no=不需要
src 示例代码如下 src 示例代码如下
```
```go ```go
package model package model
@ -219,6 +237,7 @@ type User struct {
School string `c:"学校"` School string `c:"学校"`
} }
``` ```
结构体中不需要提供Id,CreateTime,UpdateTime三个字段，会自动生成 结构体中不需要提供Id,CreateTime,UpdateTime三个字段，会自动生成
结构体中每个tag有两个可选标签 c 和 o 结构体中每个tag有两个可选标签 c 和 o
c 是改字段的注释 c 是改字段的注释
@ -232,15 +251,15 @@ type User struct {
参数说明： 参数说明：
- ${proto}: proto文件 * ${proto}: proto文件
- ${serviceName}: rpc服务名称 * ${serviceName}: rpc服务名称
- ${projectName}: 所属项目，如xjy,xhb,crm,hera，具体查看help，主要为了根据不同项目服务往redis注册key，可选 * ${projectName}: 所属项目，如xjy,xhb,crm,hera，具体查看help，主要为了根据不同项目服务往redis注册key，可选
- ${directory}: 输出目录 * ${directory}: 输出目录
- ${shared}: shared文件生成目录，可选，默认为${pwd}/shared * ${shared}: shared文件生成目录，可选，默认为${pwd}/shared
生成目录结构示例： 生成目录结构示例：
``` go ```Plain Text
. .
├── shared [示例目录，可自己指定，强制覆盖更新] ├── shared [示例目录，可自己指定，强制覆盖更新]
│   └── contentservicemodel.go │   └── contentservicemodel.go
@ -276,4 +295,5 @@ type User struct {
│   └── test.go [强制覆盖更新] │   └── test.go [强制覆盖更新]
└── test.proto └── test.proto
``` ```
- 注意 ：目前rpc目录生成的proto文件暂不支持import外部proto文件
注意 ：目前rpc目录生成的proto文件暂不支持import外部proto文件

8
doc/keywords.md
Unescape Escape View File

@ -22,7 +22,8 @@ fmt.Println(replacer.Replace("日本的首都是东京"))
``` ```
可以得到： 可以得到：
```
```Plain Text
东京是日本的首都 东京是日本的首都
``` ```
@ -46,7 +47,7 @@ fmt.Println(keywords)
可以得到： 可以得到：
``` ```Plain Text
[苍井空 日本AV女优 AV演员色情 AV AV演员] [苍井空 日本AV女优 AV演员色情 AV AV演员]
``` ```
@ -70,7 +71,7 @@ fmt.Println(found)
可以得到： 可以得到：
``` ```Plain Text
日本????兼电视、电影演员。?????女优是xx出道, ??????们最精彩的表演是??????表演 日本????兼电视、电影演员。?????女优是xx出道, ??????们最精彩的表演是??????表演
[苍井空 日本AV女优 AV演员色情 AV AV演员] [苍井空 日本AV女优 AV演员色情 AV AV演员]
true true
@ -83,4 +84,3 @@ true
| Sentences | Keywords | Regex | go-zero | | Sentences | Keywords | Regex | go-zero |
| --------- | -------- | -------- | ------- | | --------- | -------- | -------- | ------- |
| 10000 | 10000 | 16min10s | 27.2ms | | 10000 | 10000 | 16min10s | 27.2ms |

5
doc/loadshedding.md
Unescape Escape View File

@ -1,10 +1,12 @@
# 服务自适应降载保护设计 # 服务自适应降载保护设计
## 设计目的 ## 设计目的
* 保证系统不被过量请求拖垮 * 保证系统不被过量请求拖垮
* 在保证系统稳定的前提下，尽可能提供更高的吞吐量 * 在保证系统稳定的前提下，尽可能提供更高的吞吐量
## 设计考虑因素 ## 设计考虑因素
* 如何衡量系统负载 * 如何衡量系统负载
* 是否处于虚机或容器内，需要读取cgroup相关负载 * 是否处于虚机或容器内，需要读取cgroup相关负载
* 用1000m表示100%CPU，推荐使用800m表示系统高负载 * 用1000m表示100%CPU，推荐使用800m表示系统高负载
@ -12,6 +14,7 @@
* 不考虑服务本身所依赖的DB或者缓存系统问题，这类问题通过熔断机制来解决 * 不考虑服务本身所依赖的DB或者缓存系统问题，这类问题通过熔断机制来解决
## 机制设计 ## 机制设计
* 计算CPU负载时使用滑动平均来降低CPU负载抖动带来的不稳定，关于滑动平均见参考资料 * 计算CPU负载时使用滑动平均来降低CPU负载抖动带来的不稳定，关于滑动平均见参考资料
* 滑动平均就是取之前连续N次值的近似平均，N取值可以通过超参beta来决定 * 滑动平均就是取之前连续N次值的近似平均，N取值可以通过超参beta来决定
* 当CPU负载大于指定值时触发降载保护机制 * 当CPU负载大于指定值时触发降载保护机制
@ -36,11 +39,13 @@
* 1e3表示1000毫秒，minRT单位也是毫秒，QPS*minRT/1e3得到的就是平均每个时间点有多少并发请求 * 1e3表示1000毫秒，minRT单位也是毫秒，QPS*minRT/1e3得到的就是平均每个时间点有多少并发请求
## 降载的使用 ## 降载的使用
* 已经在ngin和rpcx框架里增加了可选激活配置 * 已经在ngin和rpcx框架里增加了可选激活配置
* CpuThreshold，如果把值设置为大于0的值，则激活该服务的自动降载机制 * CpuThreshold，如果把值设置为大于0的值，则激活该服务的自动降载机制
* 如果请求被drop，那么错误日志里会有`dropreq`关键字 * 如果请求被drop，那么错误日志里会有`dropreq`关键字
## 参考资料 ## 参考资料
* [滑动平均](https://www.cnblogs.com/wuliytTaotao/p/9479958.html) * [滑动平均](https://www.cnblogs.com/wuliytTaotao/p/9479958.html)
* [Sentinel自适应限流](https://github.com/alibaba/Sentinel/wiki/%E7%B3%BB%E7%BB%9F%E8%87%AA%E9%80%82%E5%BA%94%E9%99%90%E6%B5%81) * [Sentinel自适应限流](https://github.com/alibaba/Sentinel/wiki/%E7%B3%BB%E7%BB%9F%E8%87%AA%E9%80%82%E5%BA%94%E9%99%90%E6%B5%81)
* [Kratos自适应限流保护](https://github.com/bilibili/kratos/blob/master/doc/wiki-cn/ratelimit.md) * [Kratos自适应限流保护](https://github.com/bilibili/kratos/blob/master/doc/wiki-cn/ratelimit.md)

24
doc/mapreduce.md
Unescape Escape View File

@ -24,7 +24,7 @@ MapReduce主要有三个参数，第一个参数为generate用以生产数据，
场景一: 某些功能的结果往往需要依赖多个服务，比如商品详情的结果往往会依赖用户服务、库存服务、订单服务等等，一般被依赖的服务都是以rpc的形式对外提供，为了降低依赖的耗时我们往往需要对依赖做并行处理 场景一: 某些功能的结果往往需要依赖多个服务，比如商品详情的结果往往会依赖用户服务、库存服务、订单服务等等，一般被依赖的服务都是以rpc的形式对外提供，为了降低依赖的耗时我们往往需要对依赖做并行处理
``` ```go
func productDetail(uid, pid int64) (*ProductDetail, error) { func productDetail(uid, pid int64) (*ProductDetail, error) {
var pd ProductDetail var pd ProductDetail
err := mr.Finish(func() (err error) { err := mr.Finish(func() (err error) {
@ -46,11 +46,12 @@ func productDetail(uid, pid int64) (*ProductDetail, error) {
return &pd, nil return &pd, nil
} }
``` ```
该示例中返回商品详情依赖了多个服务获取数据，因此做并发的依赖处理，对接口的性能有很大的提升 该示例中返回商品详情依赖了多个服务获取数据，因此做并发的依赖处理，对接口的性能有很大的提升
场景二: 很多时候我们需要对一批数据进行处理，比如对一批用户id，效验每个用户的合法性并且效验过程中有一个出错就认为效验失败，返回的结果为效验合法的用户id 场景二: 很多时候我们需要对一批数据进行处理，比如对一批用户id，效验每个用户的合法性并且效验过程中有一个出错就认为效验失败，返回的结果为效验合法的用户id
``` ```go
func checkLegal(uids []int64) ([]int64, error) { func checkLegal(uids []int64) ([]int64, error) {
r, err := mr.MapReduce(func(source chan<- interface{}) { r, err := mr.MapReduce(func(source chan<- interface{}) {
for _, uid := range uids { for _, uid := range uids {
@ -85,9 +86,11 @@ func check(uid int64) (bool, error) {
return true, nil return true, nil
} }
``` ```
该示例中，如果check过程出现错误则通过cancel方法结束效验过程，并返回error整个效验过程结束，如果某个uid效验结果为false则最终结果不返回该uid 该示例中，如果check过程出现错误则通过cancel方法结束效验过程，并返回error整个效验过程结束，如果某个uid效验结果为false则最终结果不返回该uid
**MapReduce使用注意事项** ***MapReduce使用注意事项***
* mapper和reducer中都可以调用cancel，参数为error，调用后立即返回，返回结果为nil, error * mapper和reducer中都可以调用cancel，参数为error，调用后立即返回，返回结果为nil, error
* mapper中如果不调用writer.Write则item最终不会被reducer聚合 * mapper中如果不调用writer.Write则item最终不会被reducer聚合
* reducer中如果不调用writer.Wirte则返回结果为nil, ErrReduceNoOutput * reducer中如果不调用writer.Wirte则返回结果为nil, ErrReduceNoOutput
@ -96,7 +99,8 @@ func check(uid int64) (bool, error) {
***实现原理分析:*** ***实现原理分析:***
MapReduce中首先通过buildSource方法通过执行generate(参数为无缓冲channel)产生数据，并返回无缓冲的channel，mapper会从该channel中读取数据 MapReduce中首先通过buildSource方法通过执行generate(参数为无缓冲channel)产生数据，并返回无缓冲的channel，mapper会从该channel中读取数据
```
```go
func buildSource(generate GenerateFunc) chan interface{} { func buildSource(generate GenerateFunc) chan interface{} {
source := make(chan interface{}) source := make(chan interface{})
go func() { go func() {
@ -109,7 +113,8 @@ func buildSource(generate GenerateFunc) chan interface{} {
``` ```
在MapReduceWithSource方法中定义了cancel方法，mapper和reducer中都可以调用该方法，调用后主线程收到close信号会立马返回 在MapReduceWithSource方法中定义了cancel方法，mapper和reducer中都可以调用该方法，调用后主线程收到close信号会立马返回
```
```go
cancel := once(func(err error) { cancel := once(func(err error) {
if err != nil { if err != nil {
retErr.Set(err) retErr.Set(err)
@ -125,7 +130,8 @@ cancel := once(func(err error) {
``` ```
在mapperDispatcher方法中调用了executeMappers，executeMappers消费buildSource产生的数据，每一个item都会起一个goroutine单独处理，默认最大并发数为16，可以通过WithWorkers进行设置 在mapperDispatcher方法中调用了executeMappers，executeMappers消费buildSource产生的数据，每一个item都会起一个goroutine单独处理，默认最大并发数为16，可以通过WithWorkers进行设置
```
```go
var wg sync.WaitGroup var wg sync.WaitGroup
defer func() { defer func() {
wg.Wait() // 保证所有的item都处理完成 wg.Wait() // 保证所有的item都处理完成
@ -159,7 +165,8 @@ for {
``` ```
reducer单goroutine对数mapper写入collector的数据进行处理，如果reducer中没有手动调用writer.Write则最终会执行finish方法对output进行close避免死锁 reducer单goroutine对数mapper写入collector的数据进行处理，如果reducer中没有手动调用writer.Write则最终会执行finish方法对output进行close避免死锁
```
```go
go func() { go func() {
defer func() { defer func() {
if r := recover(); r != nil { if r := recover(); r != nil {
@ -173,12 +180,11 @@ go func() {
``` ```
在该工具包中还提供了许多针对不同业务场景的方法，实现原理与MapReduce大同小异，感兴趣的同学可以查看源码学习 在该工具包中还提供了许多针对不同业务场景的方法，实现原理与MapReduce大同小异，感兴趣的同学可以查看源码学习
* MapReduceVoid 功能和MapReduce类似但没有结果返回只返回error * MapReduceVoid 功能和MapReduce类似但没有结果返回只返回error
* Finish 处理固定数量的依赖，返回error，有一个error立即返回 * Finish 处理固定数量的依赖，返回error，有一个error立即返回
* FinishVoid 和Finish方法功能类似，没有返回值 * FinishVoid 和Finish方法功能类似，没有返回值
* Map 只做generate和mapper处理，返回channel * Map 只做generate和mapper处理，返回channel
* MapVoid 和Map功能类似，无返回 * MapVoid 和Map功能类似，无返回
本文主要介绍了go-zero框架中的MapReduce工具，在实际的项目中非常实用。用好工具对于提升服务性能和开发效率都有很大的帮助，希望本篇文章能给大家带来一些收获。 本文主要介绍了go-zero框架中的MapReduce工具，在实际的项目中非常实用。用好工具对于提升服务性能和开发效率都有很大的帮助，希望本篇文章能给大家带来一些收获。

4
doc/periodicalexecutor.md
Unescape Escape View File

@ -1,6 +1,6 @@
# PeriodicalExecutor设计 # PeriodicalExecutor设计
# 添加任务 ## 添加任务
* 当前没有未执行的任务 * 当前没有未执行的任务
* 添加并启动定时器 * 添加并启动定时器
@ -9,7 +9,7 @@
* 如到，执行所有缓存任务 * 如到，执行所有缓存任务
* 未到，只添加 * 未到，只添加
# 定时器到期 ## 定时器到期
* 清除并执行所有缓存任务 * 清除并执行所有缓存任务
* 再等待N个定时周期，如果等待过程中一直没有新任务，则退出 * 再等待N个定时周期，如果等待过程中一直没有新任务，则退出

17
doc/shorturl-en.md
Unescape Escape View File

@ -1,8 +1,8 @@
English | [简体中文](shorturl.md)
# Rapid development of microservices # Rapid development of microservices
## 0. Why building microservices are so difficult? English | [简体中文](shorturl.md)
## 0. Why building microservices are so difficult
To build a well working microservice, we need lots of knowledges from different aspects. To build a well working microservice, we need lots of knowledges from different aspects.
@ -25,7 +25,7 @@ As well, we always adhere to the idea that **prefer tools over conventions and d
Let’s take the shorturl microservice as a quick example to demonstrate how to quickly create microservices by using [go-zero](https://github.com/tal-tech/go-zero). After finishing this tutorial, you’ll find that it’s so easy to write microservices! Let’s take the shorturl microservice as a quick example to demonstrate how to quickly create microservices by using [go-zero](https://github.com/tal-tech/go-zero). After finishing this tutorial, you’ll find that it’s so easy to write microservices!
## 1. What is a shorturl service? ## 1. What is a shorturl service
A shorturl service is that it converts a long url into a short one, by well designed algorithms. A shorturl service is that it converts a long url into a short one, by well designed algorithms.
@ -129,7 +129,7 @@ And now, let’s walk through the complete flow of quickly create a microservice
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
. .
├── api ├── api
│   ├── etc │   ├── etc
@ -232,7 +232,7 @@ And now, let’s walk through the complete flow of quickly create a microservice
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
rpc/transform rpc/transform
├── etc ├── etc
│   └── transform.yaml // configuration file │   └── transform.yaml // configuration file
@ -375,7 +375,7 @@ Till now, we’ve done the modification of API Gateway. All the manually added c
source shorturl.sql; source shorturl.sql;
``` ```
* under the directory `rpc/transform/model execute the following command to genrate CRUD+cache code, `-c` means using `redis cache` * under the directory `rpc/transform/model` execute the following command to genrate CRUD+cache code, `-c` means using `redis cache`
```shell ```shell
goctl model mysql ddl -c -src shorturl.sql -dir . goctl model mysql ddl -c -src shorturl.sql -dir .
@ -385,7 +385,7 @@ Till now, we’ve done the modification of API Gateway. All the manually added c
the generated file structure looks like: the generated file structure looks like:
``` ```Plain Text
rpc/transform/model rpc/transform/model
├── shorturl.sql ├── shorturl.sql
├── shorturlmodel.go // CRUD+cache code ├── shorturlmodel.go // CRUD+cache code
@ -533,4 +533,3 @@ We not only keep the framework simple, but also encapsulate the complexity into
For the generated code by goctl, lots of microservice components are included, like concurrency control, adaptive circuit breaker, adaptive load shedding, auto cache control etc. And it’s easy to deal with the busy sites. For the generated code by goctl, lots of microservice components are included, like concurrency control, adaptive circuit breaker, adaptive load shedding, auto cache control etc. And it’s easy to deal with the busy sites.
If you have any ideas that can help us to improve the productivity, tell me any time! 👏 If you have any ideas that can help us to improve the productivity, tell me any time! 👏

17
doc/shorturl.md
Unescape Escape View File

@ -1,8 +1,8 @@
[English](shorturl-en.md) | 简体中文
# 快速构建高并发微服务 # 快速构建高并发微服务
## 0. 为什么说做好微服务很难？ [English](shorturl-en.md) | 简体中文
## 0. 为什么说做好微服务很难
要想做好微服务，我们需要理解和掌握的知识点非常多，从几个维度上来说： 要想做好微服务，我们需要理解和掌握的知识点非常多，从几个维度上来说：
@ -25,7 +25,7 @@
下面我通过短链微服务来演示通过[go-zero](https://github.com/tal-tech/go-zero)快速的创建微服务的流程，走完一遍，你就会发现：原来编写微服务如此简单！ 下面我通过短链微服务来演示通过[go-zero](https://github.com/tal-tech/go-zero)快速的创建微服务的流程，走完一遍，你就会发现：原来编写微服务如此简单！
## 1. 什么是短链服务？ ## 1. 什么是短链服务
短链服务就是将长的URL网址，通过程序计算等方式，转换为简短的网址字符串。 短链服务就是将长的URL网址，通过程序计算等方式，转换为简短的网址字符串。
@ -123,7 +123,7 @@
生成的文件结构如下： 生成的文件结构如下：
``` ```Plain Text
. .
├── api ├── api
│   ├── etc │   ├── etc
@ -228,7 +228,7 @@
文件结构如下： 文件结构如下：
``` ```Plain Text
rpc/transform rpc/transform
├── etc ├── etc
│   └── transform.yaml // 配置文件 │   └── transform.yaml // 配置文件
@ -321,7 +321,6 @@
} }
``` ```
通过调用`transformer`的`Expand`方法实现短链恢复到url 通过调用`transformer`的`Expand`方法实现短链恢复到url
* 修改`internal/logic/shortenlogic.go`，如下： * 修改`internal/logic/shortenlogic.go`，如下：
@ -343,7 +342,6 @@
} }
``` ```
通过调用`transformer`的`Shorten`方法实现url到短链的变换 通过调用`transformer`的`Shorten`方法实现url到短链的变换
至此，API Gateway修改完成，虽然贴的代码多，但是期中修改的是很少的一部分，为了方便理解上下文，我贴了完整代码，接下来处理CRUD+cache 至此，API Gateway修改完成，虽然贴的代码多，但是期中修改的是很少的一部分，为了方便理解上下文，我贴了完整代码，接下来处理CRUD+cache
@ -383,7 +381,7 @@
生成后的文件结构如下： 生成后的文件结构如下：
``` ```Plain Text
rpc/transform/model rpc/transform/model
├── shorturl.sql ├── shorturl.sql
├── shorturlmodel.go // CRUD+cache代码 ├── shorturlmodel.go // CRUD+cache代码
@ -531,4 +529,3 @@ go-zero不只是一个框架，更是一个建立在框架+工具基础上的，
通过go-zero+goctl生成的代码，包含了微服务治理的各种组件，包括：并发控制、自适应熔断、自适应降载、自动缓存控制等，可以轻松部署以承载巨大访问量。 通过go-zero+goctl生成的代码，包含了微服务治理的各种组件，包括：并发控制、自适应熔断、自适应降载、自动缓存控制等，可以轻松部署以承载巨大访问量。
有任何好的提升工程效率的想法，随时欢迎交流！👏 有任何好的提升工程效率的想法，随时欢迎交流！👏

1
doc/sql-cache.md
Unescape Escape View File

@ -21,4 +21,3 @@
* 通过Primary到DB查询行记录，并写入缓存 * 通过Primary到DB查询行记录，并写入缓存
* 有Primary到行记录的缓存 * 有Primary到行记录的缓存
* 直接返回缓存结果 * 直接返回缓存结果

1
example/load/simulate/cpu/cpu-accuracy.md
Unescape Escape View File

@ -25,4 +25,3 @@
`watch -n 5 kubectl top pod -n adhoc` `watch -n 5 kubectl top pod -n adhoc`
可以看到`kubectl`报告的`CPU`使用率，两者进行对比，即可知道是否准确 可以看到`kubectl`报告的`CPU`使用率，两者进行对比，即可知道是否准确

12
readme-en.md
Unescape Escape View File

@ -1,14 +1,14 @@
English | [简体中文](readme.md)
# go-zero # go-zero
English | [简体中文](readme.md)
[![Go](https://github.com/tal-tech/go-zero/workflows/Go/badge.svg?branch=master)](https://github.com/tal-tech/go-zero/actions) [![Go](https://github.com/tal-tech/go-zero/workflows/Go/badge.svg?branch=master)](https://github.com/tal-tech/go-zero/actions)
[![codecov](https://codecov.io/gh/tal-tech/go-zero/branch/master/graph/badge.svg)](https://codecov.io/gh/tal-tech/go-zero) [![codecov](https://codecov.io/gh/tal-tech/go-zero/branch/master/graph/badge.svg)](https://codecov.io/gh/tal-tech/go-zero)
[![Go Report Card](https://goreportcard.com/badge/github.com/tal-tech/go-zero)](https://goreportcard.com/report/github.com/tal-tech/go-zero) [![Go Report Card](https://goreportcard.com/badge/github.com/tal-tech/go-zero)](https://goreportcard.com/report/github.com/tal-tech/go-zero)
[![Release](https://img.shields.io/github/v/release/tal-tech/go-zero.svg?style=flat-square)](https://github.com/tal-tech/go-zero) [![Release](https://img.shields.io/github/v/release/tal-tech/go-zero.svg?style=flat-square)](https://github.com/tal-tech/go-zero)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
## 0. what is go-zero? ## 0. what is go-zero
go-zero is a web and rpc framework that with lots of engineering practices builtin. It’s born to ensure the stability of the busy services with resilience design, and has been serving sites with tens of millions users for years. go-zero is a web and rpc framework that with lots of engineering practices builtin. It’s born to ensure the stability of the busy services with resilience design, and has been serving sites with tens of millions users for years.
@ -99,7 +99,7 @@ go get -u github.com/tal-tech/go-zero
1. install goctl 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 the productivity, and make our lives easier. `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 the productivity, and make our lives easier.
```shell ```shell
GO111MODULE=on go get -u github.com/tal-tech/go-zero/tools/goctl GO111MODULE=on go get -u github.com/tal-tech/go-zero/tools/goctl
@ -140,7 +140,7 @@ go get -u github.com/tal-tech/go-zero
the generated files look like: the generated files look like:
``` ```Plain Text
├── greet ├── greet
│   ├── etc │   ├── etc
│   │   └── greet-api.yaml // configuration file │   │   └── greet-api.yaml // configuration file
@ -159,6 +159,7 @@ go get -u github.com/tal-tech/go-zero
│   └── types.go // request/response defined here │   └── types.go // request/response defined here
└── greet.api // api description file └── greet.api // api description file
``` ```
the generated code can be run directly: the generated code can be run directly:
```shell ```shell
@ -186,6 +187,7 @@ go get -u github.com/tal-tech/go-zero
* the dependencies can be passed into the logic within servicecontext.go, like mysql, reds etc. * the dependencies can be passed into the logic within servicecontext.go, like mysql, reds etc.
* add the logic code in logic package according to .api file * add the logic code in logic package according to .api file
5. Generate code like Java, TypeScript, Dart, JavaScript etc. just from the api file 5. Generate code like Java, TypeScript, Dart, JavaScript etc. just from the api file
```shell ```shell

6
readme.md
Unescape Escape View File

@ -1,7 +1,7 @@
[English](readme-en.md) | 简体中文
# go-zero # go-zero
[English](readme-en.md) | 简体中文
[![Go](https://github.com/tal-tech/go-zero/workflows/Go/badge.svg?branch=master)](https://github.com/tal-tech/go-zero/actions) [![Go](https://github.com/tal-tech/go-zero/workflows/Go/badge.svg?branch=master)](https://github.com/tal-tech/go-zero/actions)
[![codecov](https://codecov.io/gh/tal-tech/go-zero/branch/master/graph/badge.svg)](https://codecov.io/gh/tal-tech/go-zero) [![codecov](https://codecov.io/gh/tal-tech/go-zero/branch/master/graph/badge.svg)](https://codecov.io/gh/tal-tech/go-zero)
[![Go Report Card](https://goreportcard.com/badge/github.com/tal-tech/go-zero)](https://goreportcard.com/report/github.com/tal-tech/go-zero) [![Go Report Card](https://goreportcard.com/badge/github.com/tal-tech/go-zero)](https://goreportcard.com/report/github.com/tal-tech/go-zero)
@ -131,6 +131,8 @@ Content-Length: 0
编写业务代码： 编写业务代码：
* 可以在servicecontext.go里面传递依赖给logic，比如mysql, redis等
* 在api定义的get/post/put/delete等请求对应的logic里增加业务处理逻辑
* api文件定义了服务对外暴露的路由，可参考[api规范](https://github.com/tal-tech/go-zero/blob/master/doc/goctl.md) * api文件定义了服务对外暴露的路由，可参考[api规范](https://github.com/tal-tech/go-zero/blob/master/doc/goctl.md)
* 可以在servicecontext.go里面传递依赖给logic，比如mysql, redis等 * 可以在servicecontext.go里面传递依赖给logic，比如mysql, redis等
* 在api定义的get/post/put/delete等请求对应的logic里增加业务处理逻辑 * 在api定义的get/post/put/delete等请求对应的logic里增加业务处理逻辑

35
tools/goctl/goctl.md
Unescape Escape View File

@ -1,31 +1,34 @@
# goctl使用说明 # goctl使用
## goctl用途 ## goctl用途
* 定义api请求 * 定义api请求
* 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter) * 根据定义的api自动生成golang(后端), java(iOS & Android), typescript(web & 晓程序)，dart(flutter)
* 生成MySQL CURD 详情见[goctl model模块](model/sql) * 生成MySQL CURD 详情见[goctl model模块](model/sql)
## goctl使用说明 ## goctl使用说明
#### goctl参数说明
### goctl 参数说明
`goctl api [go/java/ts] [-api user/user.api] [-dir ./src]` `goctl api [go/java/ts] [-api user/user.api] [-dir ./src]`
> api 后面接生成的语言，现支持go/java/typescript > api 后面接生成的语言，现支持go/java/typescript
>
> -api 自定义api所在路径 > -api 自定义api所在路径
>
> -dir 自定义生成目录 > -dir 自定义生成目录
#### 保持goctl总是最新版 #### 保持goctl总是最新版
第一次运行会在~/.goctl里增加下面两行： 第一次运行会在~/.goctl里增加下面两行：
``` ```Plain Text
url = http://47.97.184.41:7777/ url = http://47.97.184.41:7777/
``` ```
#### API 语法说明 #### API 语法说明
``` ```Plain Text
info( info(
title: doc title title: doc title
desc: > desc: >
@ -122,6 +125,7 @@ service user-api {
head /api/ping() head /api/ping()
} }
``` ```
1. info部分：描述了api基本信息，比如Auth，api是哪个用途。 1. info部分：描述了api基本信息，比如Auth，api是哪个用途。
2. type部分：type类型声明和golang语法兼容。 2. type部分：type类型声明和golang语法兼容。
3. service部分：service代表一组服务，一个服务可以由多组名称相同的service组成，可以针对每一组service配置jwt和auth认证，另外通过folder属性可以指定service生成所在子目录。 3. service部分：service代表一组服务，一个服务可以由多组名称相同的service组成，可以针对每一组service配置jwt和auth认证，另外通过folder属性可以指定service生成所在子目录。
@ -130,6 +134,7 @@ service user-api {
请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。 请求getRequest里面的属性赋值，getResponse为返回的结构体，这两个类型都定义在2描述的类型中。
#### api vscode插件 #### api vscode插件
开发者可以在vscode中搜索goctl的api插件，它提供了api语法高亮，语法检测和格式化相关功能。 开发者可以在vscode中搜索goctl的api插件，它提供了api语法高亮，语法检测和格式化相关功能。
1. 支持语法高亮和类型导航。 1. 支持语法高亮和类型导航。
@ -141,7 +146,7 @@ service user-api {
命令如下： 命令如下：
`goctl api go -api user/user.api -dir user` `goctl api go -api user/user.api -dir user`
``` ```Plain Text
. .
├── internal ├── internal
@ -171,20 +176,28 @@ service user-api {
└── user.go └── user.go
``` ```
生成的代码可以直接跑，有几个地方需要改： 生成的代码可以直接跑，有几个地方需要改：
* 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等 * 在`servicecontext.go`里面增加需要传递给logic的一些资源，比如mysql, redis，rpc等
* 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码 * 在定义的get/post/put/delete等请求的handler和logic里增加处理业务逻辑的代码
#### 根据定义好的api文件生成java代码 #### 根据定义好的api文件生成java代码
`goctl api java -api user/user.api -dir ./src`
```Plain Text
goctl api java -api user/user.api -dir ./src
```
#### 根据定义好的api文件生成typescript代码 #### 根据定义好的api文件生成typescript代码
`goctl api ts -api user/user.api -dir ./src -webapi ***`
```Plain Text
goctl api ts -api user/user.api -dir ./src -webapi ***
```
ts需要指定webapi所在目录 ts需要指定webapi所在目录
#### 根据定义好的api文件生成Dart代码 #### 根据定义好的api文件生成Dart代码
`goctl api dart -api user/user.api -dir ./src`
* 如有不理解的地方，随时问Kim/Kevin ```Plain Text
goctl api dart -api user/user.api -dir ./src
```

6
tools/goctl/model/sql/CHANGELOG.md
Unescape Escape View File

@ -1,10 +1,12 @@
# Change log # Change log
# 2020-08-20 ## 2020-08-20
* 新增支持通过连接数据库生成model * 新增支持通过连接数据库生成model
* 支持数据库多表生成 * 支持数据库多表生成
* 优化stringx * 优化stringx
# 2020-08-19 ## 2020-08-19
* 重构model代码生成逻辑 * 重构model代码生成逻辑
* 实现从ddl解析表信息生成代码 * 实现从ddl解析表信息生成代码

46
tools/goctl/model/sql/README.MD
Unescape Escape View File

@ -2,28 +2,28 @@
goctl model 为go-zero下的工具模块中的组件之一，目前支持识别mysql ddl进行model层代码生成，通过命令行或者idea插件（即将支持）可以有选择地生成带redis cache或者不带redis cache的代码逻辑。 goctl model 为go-zero下的工具模块中的组件之一，目前支持识别mysql ddl进行model层代码生成，通过命令行或者idea插件（即将支持）可以有选择地生成带redis cache或者不带redis cache的代码逻辑。
# 快速开始 ## 快速开始
* 通过ddl生成 * 通过ddl生成
```shell script ```shell script
$ goctl model mysql ddl -src="./sql/user.sql" -dir="./sql/model" -c=true goctl model mysql ddl -src="./sql/user.sql" -dir="./sql/model" -c=true
``` ```
执行上述命令后即可快速生成CURD代码。 执行上述命令后即可快速生成CURD代码。
``` ```Plain Text
model model
│   ├── error.go │   ├── error.go
│   └── usermodel.go │   └── usermodel.go
``` ```
* 通过datasource生成 * 通过datasource生成
```shell script ```shell script
$ goctl model mysql datasource -url="user:password@tcp(127.0.0.1:3306)/database" -table="table1,table2" -dir="./model" goctl model mysql datasource -url="user:password@tcp(127.0.0.1:3306)/database" -table="table1,table2" -dir="./model"
``` ```
* 生成代码示例 * 生成代码示例
``` go ``` go
@ -175,13 +175,13 @@ goctl model 为go-zero下的工具模块中的组件之一，目前支持识别m
} }
``` ```
# 用法 ## 用法
``` ```Plain Text
$ goctl model mysql -h goctl model mysql -h
``` ```
``` ```Plain Text
NAME: NAME:
goctl model mysql - generate mysql model" goctl model mysql - generate mysql model"
@ -196,7 +196,7 @@ OPTIONS:
--help, -h show help --help, -h show help
``` ```
# 生成规则 ## 生成规则
* 默认规则 * 默认规则
@ -205,12 +205,13 @@ OPTIONS:
* ddl * ddl
```shell script ```shell script
$ goctl model mysql -src={filename} -dir={dir} -cache=true goctl model mysql -src={filename} -dir={dir} -cache=true
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=true goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=true
``` ```
目前仅支持redis缓存，如果选择带缓存模式，即生成的`FindOne(ByXxx)`&`Delete`代码会生成带缓存逻辑的代码，目前仅支持单索引字段（除全文索引外），对于联合索引我们默认认为不需要带缓存，且不属于通用型代码，因此没有放在代码生成行列，如example中user表中的`id`、`name`、`mobile`字段均属于单字段索引。 目前仅支持redis缓存，如果选择带缓存模式，即生成的`FindOne(ByXxx)`&`Delete`代码会生成带缓存逻辑的代码，目前仅支持单索引字段（除全文索引外），对于联合索引我们默认认为不需要带缓存，且不属于通用型代码，因此没有放在代码生成行列，如example中user表中的`id`、`name`、`mobile`字段均属于单字段索引。
@ -220,28 +221,31 @@ OPTIONS:
* ddl * ddl
```shell script ```shell script
$ goctl model -src={filename} -dir={dir} goctl model -src={filename} -dir={dir}
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} goctl model mysql datasource -url={datasource} -table={tables} -dir={dir}
``` ```
or or
* ddl * ddl
```shell script ```shell script
$ goctl model -src={filename} -dir={dir} -cache=false goctl model -src={filename} -dir={dir} -cache=false
``` ```
* datasource * datasource
```shell script ```shell script
$ goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=false goctl model mysql datasource -url={datasource} -table={tables} -dir={dir} -cache=false
``` ```
生成代码仅基本的CURD结构。 生成代码仅基本的CURD结构。
# 缓存 ## 缓存
对于缓存这一块我选择用一问一答的形式进行罗列。我想这样能够更清晰的描述model中缓存的功能。 对于缓存这一块我选择用一问一答的形式进行罗列。我想这样能够更清晰的描述model中缓存的功能。
@ -261,14 +265,8 @@ OPTIONS:
目前，我认为除了基本的CURD外，其他的代码均属于<i>业务型</i>代码，这个我觉得开发人员根据业务需要进行编写更好。 目前，我认为除了基本的CURD外，其他的代码均属于<i>业务型</i>代码，这个我觉得开发人员根据业务需要进行编写更好。
# QA ## QA
* goctl model除了命令行模式，支持插件模式吗？ * goctl model除了命令行模式，支持插件模式吗？
很快支持idea插件。 很快支持idea插件。

10
tools/goctl/rpc/CHANGELOG.md
Unescape Escape View File

@ -1,14 +1,16 @@
# Change log # Change log
# 2020-08-29 ## 2020-09-10
* rpc greet服务一键生成 * rpc greet服务一键生成
* 修复相对路径生成rpc服务package引入错误bug * 修复相对路径生成rpc服务package引入错误bug
* 移除`--shared`参数 * 移除`--shared`参数
# 2020-08-29 ## 2020-08-29
* 新增支持windows生成 * 新增支持windows生成
# 2020-08-27 ## 2020-08-27
* 新增支持rpc模板生成 * 新增支持rpc模板生成
* 新增支持rpc服务生成 * 新增支持rpc服务生成

46
tools/goctl/rpc/README.md
Unescape Escape View File

@ -1,12 +1,14 @@
# Rpc Generation # Rpc Generation
Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持proto模板生成和rpc服务代码生成，通过此工具生成代码你只需要关注业务逻辑编写而不用去编写一些重复性的代码。这使得我们把精力重心放在业务上，从而加快了开发效率且降低了代码出错率。 Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持proto模板生成和rpc服务代码生成，通过此工具生成代码你只需要关注业务逻辑编写而不用去编写一些重复性的代码。这使得我们把精力重心放在业务上，从而加快了开发效率且降低了代码出错率。
# 特性 ## 特性
* 简单易用 * 简单易用
* 快速提升开发效率 * 快速提升开发效率
* 出错率低 * 出错率低
# 快速开始 ## 快速开始
### 方式一：快速生成greet服务 ### 方式一：快速生成greet服务
@ -15,7 +17,7 @@ Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持prot
如生成greet rpc服务： 如生成greet rpc服务：
```shell script ```shell script
$ goctl rpc new greet goctl rpc new greet
``` ```
执行后代码结构如下: 执行后代码结构如下:
@ -46,12 +48,13 @@ Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持prot
``` ```
rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题解决</a> rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题解决</a>
### 方式二：通过指定proto生成rpc服务 ### 方式二：通过指定proto生成rpc服务
* 生成proto模板 * 生成proto模板
```shell script ```shell script
$ goctl rpc template -o=user.proto goctl rpc template -o=user.proto
``` ```
```golang ```golang
@ -78,15 +81,16 @@ rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题
rpc Login(Request)returns(Response); rpc Login(Request)returns(Response);
} }
``` ```
* 生成rpc服务代码 * 生成rpc服务代码
``` ```shell script
$ goctl rpc proto -src=user.proto goctl rpc proto -src=user.proto
``` ```
代码tree 代码tree
``` ```Plain Text
user user
├── etc ├── etc
│   └── user.json │   └── user.json
@ -107,21 +111,21 @@ rpc一键生成常见问题解决见 <a href="#常见问题解决">常见问题
│   └── usermodel.go │   └── usermodel.go
├── user.go ├── user.go
└── user.proto └── user.proto
``` ```
# 准备工作
## 准备工作
* 安装了go环境 * 安装了go环境
* 安装了protoc&protoc-gen-go，并且已经设置环境变量 * 安装了protoc&protoc-gen-go，并且已经设置环境变量
* mockgen(可选,将移除) * mockgen(可选,将移除)
* 更多问题请见 <a href="#注意事项">注意事项</a> * 更多问题请见 <a href="#注意事项">注意事项</a>
# 用法 ## 用法
### rpc服务生成用法 ### rpc服务生成用法
```shell script ```shell script
$ goctl rpc proto -h goctl rpc proto -h
``` ```
```shell script ```shell script
@ -145,12 +149,14 @@ OPTIONS:
* --src 必填，proto数据源，目前暂时支持单个proto文件生成，这里不支持（不建议）外部依赖 * --src 必填，proto数据源，目前暂时支持单个proto文件生成，这里不支持（不建议）外部依赖
* --dir 非必填，默认为proto文件所在目录，生成代码的目标目录 * --dir 非必填，默认为proto文件所在目录，生成代码的目标目录
* --service 服务名称，非必填，默认为proto文件所在目录名称，但是，如果proto所在目录为一下结构： * --service 服务名称，非必填，默认为proto文件所在目录名称，但是，如果proto所在目录为一下结构：
```shell script ```shell script
user user
├── cmd ├── cmd
│   └── rpc │   └── rpc
│   └── user.proto │   └── user.proto
``` ```
则服务名称亦为user，而非proto所在文件夹名称了，这里推荐使用这种结构，可以方便在同一个服务名下建立不同类型的服务(api、rpc、mq等)，便于代码管理与维护。 则服务名称亦为user，而非proto所在文件夹名称了，这里推荐使用这种结构，可以方便在同一个服务名下建立不同类型的服务(api、rpc、mq等)，便于代码管理与维护。
* --shared[⚠️已废弃] 非必填，默认为$dir(xxx.proto)/shared，rpc client逻辑代码存放目录。 * --shared[⚠️已废弃] 非必填，默认为$dir(xxx.proto)/shared，rpc client逻辑代码存放目录。
@ -158,31 +164,38 @@ OPTIONS:
* --idea 非必填，是否为idea插件中执行，保留字段，终端执行可以忽略 * --idea 非必填，是否为idea插件中执行，保留字段，终端执行可以忽略
# 开发人员需要做什么 ### 开发人员需要做什么
关注业务代码编写，将重复性、与业务无关的工作交给goctl，生成好rpc服务代码后，开饭人员仅需要修改 关注业务代码编写，将重复性、与业务无关的工作交给goctl，生成好rpc服务代码后，开饭人员仅需要修改
* 服务中的配置文件编写(etc/xx.json、internal/config/config.go) * 服务中的配置文件编写(etc/xx.json、internal/config/config.go)
* 服务中业务逻辑编写(internal/logic/xxlogic.go) * 服务中业务逻辑编写(internal/logic/xxlogic.go)
* 服务中资源上下文的编写(internal/svc/servicecontext.go) * 服务中资源上下文的编写(internal/svc/servicecontext.go)
# 扩展 ## 扩展
对于需要进行rpc mock的开发人员，在安装了`mockgen`工具的前提下可以在rpc的shared文件中生成好对应的mock文件。 对于需要进行rpc mock的开发人员，在安装了`mockgen`工具的前提下可以在rpc的shared文件中生成好对应的mock文件。
# 注意事项 ### 注意事项
* `google.golang.org/grpc`需要降级到v1.26.0,且protoc-gen-go版本不能高于v1.3.2（see [https://github.com/grpc/grpc-go/issues/3347](https://github.com/grpc/grpc-go/issues/3347)）即 * `google.golang.org/grpc`需要降级到v1.26.0,且protoc-gen-go版本不能高于v1.3.2（see [https://github.com/grpc/grpc-go/issues/3347](https://github.com/grpc/grpc-go/issues/3347)）即
```
```shell script
replace google.golang.org/grpc => google.golang.org/grpc v1.26.0 replace google.golang.org/grpc => google.golang.org/grpc v1.26.0
``` ```
* proto不支持暂多文件同时生成 * proto不支持暂多文件同时生成
* proto不支持外部依赖包引入，message不支持inline * proto不支持外部依赖包引入，message不支持inline
* 目前main文件、shared文件、handler文件会被强制覆盖，而和开发人员手动需要编写的则不会覆盖生成，这一类在代码头部均有 * 目前main文件、shared文件、handler文件会被强制覆盖，而和开发人员手动需要编写的则不会覆盖生成，这一类在代码头部均有
```shell script ```shell script
// Code generated by goctl. DO NOT EDIT! // Code generated by goctl. DO NOT EDIT!
// Source: xxx.proto // Source: xxx.proto
``` ```
的标识，请注意不要将也写业务性代码写在里面。 的标识，请注意不要将也写业务性代码写在里面。
# 常见问题解决(go mod工程) ## 常见问题解决(go mod工程)
* 错误一: * 错误一:
@ -192,6 +205,7 @@ OPTIONS:
pb/xx.pb.go:234:5: undefined: grpc.ClientConnInterface pb/xx.pb.go:234:5: undefined: grpc.ClientConnInterface
pb/xx.pb.go:237:24: undefined: grpc.ClientConnInterface pb/xx.pb.go:237:24: undefined: grpc.ClientConnInterface
``` ```
解决方法：请将`protoc-gen-go`版本降至v1.3.2及一下 解决方法：请将`protoc-gen-go`版本降至v1.3.2及一下
* 错误二: * 错误二:

Write Preview
Loading…
Cancel
Save