微服务效率工具 goctl 深度解析（上）

# Go 1.16 之前版本
$ GO111MODULE=on GOPROXY=https://goproxy.cn/,direct go get -u github.com/zeromicro/go-zero/tools/goctl@latest
# Go 1.16 及以后版本
$ GOPROXY=https://goproxy.cn/,direct go install github.com/zeromicro/go-zero/tools/goctl@latest
# macOS
$ brew install goctl
# 验证
$ goctl --version
goctl version 1.3.5 darwin/amd64
# 查看 goctl
$ cd $GOPATH/bin && ls | grep "goctl"

# 1. pull
$ docker pull kevinwan/goctl
....
# 2. ls
$ docker image ls | grep "goctl"
kevinwan/goctl        latest    7fd46843de3d   5 weeks ago    383MB
# 3. run
$ docker run -it kevinwan/goctl /bin/sh

$ goctl --help                                                       
A cli tool to generate api, zrpc, model code
Usage:
goctl [command]
Available Commands:
api         Generate api related files
bug         Report a bug
completion  Generate the autocompletion script for the specified shell
docker      Generate Dockerfile
env         Check or edit goctl environment
help        Help about any command
kube        Generate kubernetes files
migrate     Migrate from tal-tech to zeromicro
model       Generate model code
quickstart  quickly start a project
rpc         Generate rpc code
template    Template operation
upgrade     Upgrade goctl to latest version
Flags:
-h, --help      help for goctl
-v, --version   version for goctl
Use "goctl [command] --help" for more information about a command.

$ goctl --version
goctl version 1.3.5 darwin/amd64

$ goctl completion --help                                
   NAME:
   goctl completion - generation completion script, it only works for unix-like OS
USAGE:
goctl completion [command options] [arguments...]
OPTIONS:
--name value, -n value  the filename of auto complete script, default is [goctl_autocomplete]

$ goctl completion
generation auto completion success!
executes the following script to setting shell:
echo PROG=goctl source /Users/keson/.goctl/.auto_complete/zsh/goctl_autocomplete >> ~/.zshrc && source ~/.zshrc
# 或者
echo PROG=goctl source /Users/keson/.goctl/.auto_complete/bash/goctl_autocomplete >> ~/.bashrc && source ~/.bashrc

$ echo $SHELL                                                  
/bin/zsh

$ echo PROG=goctl source /Users/keson/.goctl/.auto_complete/zsh/goctl_autocomplete >> ~/.zshrc && source ~/.zshrc

# 键入 goctl 后按下 tab 键查看自动补全提示
$ goctl # tab
api            -- generate api related files
bug            -- report a bug
completion     -- generation completion script, it only works for unix-like OS
docker         -- generate Dockerfile
env            -- check or edit goctl environment
help        h  -- Shows a list of commands or help for one command
kube           -- generate kubernetes files
migrate        -- migrate from tal-tech to zeromicro
model          -- generate model code
rpc            -- generate rpc code
template       -- template operation
upgrade        -- upgrade goctl to latest version

# 编辑 ~/.zshrc
$ vim ~/.zshrc
# 找到 PROG=goctl 所在行并删除
# source
$ source ~/.zshrc && rm .zcompdump*
# 重启终端

$ goctl completion --help
Generate the autocompletion script for goctl for the specified shell.
See each sub-command's help for details on how to use the generated script.
Usage:
goctl completion [command]
Available Commands:
bash        Generate the autocompletion script for bash
fish        Generate the autocompletion script for fish
powershell  Generate the autocompletion script for powershell
zsh         Generate the autocompletion script for zsh
Flags:
-h, --help   help for completion
Use "goctl completion [command] --help" for more information about a command.

$ echo $SHELL                                                  
/bin/zsh

$ goctl completion zsh --help
Generate the autocompletion script for the zsh shell.
If shell completion is not already enabled in your environment you will need
to enable it.  You can execute the following once:
        echo "autoload -U compinit; compinit" >> ~/.zshrc
To load completions for every new session, execute once:
#### Linux:
        goctl completion zsh > "${fpath[1]}/_goctl"
#### macOS:
        goctl completion zsh > /usr/local/share/zsh/site-functions/_goctl
You will need to start a new shell for this setup to take effect.
Usage:
goctl completion zsh [flags]
Flags:
-h, --help              help for zsh
--no-descriptions   disable completion descriptions

$ goctl completion zsh > /usr/local/share/zsh/site-functions/_goctl

# 键入 goctl 后按下 tab 键查看自动补全提示
$ goctl # tab
api         -- Generate api related files
bug         -- Report a bug
completion  -- Generate the autocompletion script for the specified shell
docker      -- Generate Dockerfile
env         -- Check or edit goctl environment
help        -- Help about any command
kube        -- Generate kubernetes files
migrate     -- Migrate from tal-tech to zeromicro
model       -- Generate model code
quickstart  -- quickly start a project
rpc         -- Generate rpc code
template    -- Template operation
upgrade     -- Upgrade goctl to latest version

module awesomemigrate
go 1.18
require github.com/tal-tech/go-zero v1.2.5
...

# 1. 查看当前 goctl 版本
$ goctl --version
goctl version 1.2.5 darwin/amd64
# 2. 由于 goctl 版本小于 v1.3.2，则需要升级至最新，如果 goctl 版本已经是1.3.2及之后了，则可以不用升级
$ go install github.com/zeromicro/go-zero/tools/goctl@latest
# 3. 查看一下迁移指令使用帮助
$ goctl migrate --help                                  
NAME:
goctl migrate - migrate from tal-tech to zeromicro
USAGE:
goctl migrate [command options] [arguments...]
DESCRIPTION:
migrate is a transition command to help users migrate their projects from tal-tech to zeromicro version
OPTIONS:
--verbose, -v    verbose enables extra logging
--version value  the target release version of github.com/zeromicro/go-zero to migrate
# 4. 进入待迁移的项目下，执行迁移指令
$ goctl migrate --version 1.3.3
# 5. 验证依赖是否存在问题
$ go test .
?       awesomemigrate  [no test files]

module awesomemigrate
go 1.18
require github.com/zeromicro/go-zero v1.3.3
...

$ goctl env --help                                    
NAME:
goctl env - check or edit goctl environment
USAGE:
goctl env command [command options] [arguments...]
COMMANDS:
install  goctl env installation
check    detect goctl env and dependency tools
OPTIONS:
--write value, -w value  edit goctl environment
--help, -h               show help

$ goctl env                                             
GOCTL_OS=darwin                        
GOCTL_ARCH=amd64
GOCTL_HOME=/Users/keson/.goctl
GOCTL_DEBUG=false
GOCTL_CACHE=/Users/keson/.goctl/cache
GOCTL_VERSION=1.3.5
PROTOC_VERSION=3.19.4
PROTOC_GEN_GO_VERSION=v1.27.1
PROTO_GEN_GO_GRPC_VERSION=1.2.0

# 修改前
$ goctl env | grep 'GOCTL_DEBUG'
GOCTL_DEBUG=false
# 修改 GOCTL_DEBUG 为 true
$ goctl env -w GOCTL_DEBUG=true
# 修改后
goctl env | grep 'GOCTL_DEBUG'
GOCTL_DEBUG=true

# 我们来检查一下依赖安装
$ goctl env check --verbose                              
[goctl-env]: preparing to check env
[goctl-env]: looking up "protoc"
[goctl-env]: "protoc" is not found in PATH
[goctl-env]: looking up "protoc-gen-go"
[goctl-env]: "protoc-gen-go" is not found in PATH
[goctl-env]: looking up "protoc-gen-go-grpc"
[goctl-env]: "protoc-gen-go-grpc" is not found in PATH
[goctl-env]: check env finish, some dependencies is not found in PATH, you can execute
command 'goctl env check --install' to install it, for details, please execute command
'goctl env check --help'
# 安装依赖，安装依赖有2中方式
# 方式一
# $ goctl env check --install --force --verbose
# 方式二
$ goctl env install --verbose -f                       
[goctl-env]: preparing to check env
[goctl-env]: looking up "protoc"
[goctl-env]: "protoc" is not found in PATH
[goctl-env]: preparing to install "protoc"
[goctl-env]: "protoc" is already installed in "/Users/keson/go/bin/protoc"
[goctl-env]: looking up "protoc-gen-go"
[goctl-env]: "protoc-gen-go" is not found in PATH
[goctl-env]: preparing to install "protoc-gen-go"
[goctl-env]: "protoc-gen-go" is already installed in "/Users/keson/go/bin/protoc-gen-go"
[goctl-env]: looking up "protoc-gen-go-grpc"
[goctl-env]: "protoc-gen-go-grpc" is not found in PATH
[goctl-env]: preparing to install "protoc-gen-go-grpc"
[goctl-env]: "protoc-gen-go-grpc" is already installed in "/Users/keson/go/bin/protoc-gen-go-grpc"
[goctl-env]: congratulations! your goctl environment is ready!

goctl rpc -h                                                       
Generate rpc code
Usage:
goctl rpc [flags]
goctl rpc [command]
Available Commands:
new         Generate rpc demo service
protoc      Generate grpc code
template    Generate proto template
Flags:
--branch string   The branch of the remote repo, it does work with --remote
-h, --help            help for rpc
--home string     The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
--o string        Output a sample proto file
--remote string   The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
Use "goctl rpc [command] --help" for more information about a command.

goctl rpc protoc -h                                              
Generate grpc code
Usage:
goctl rpc protoc [flags]
Examples:
goctl rpc protoc xx.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.
Flags:
--branch string     The branch of the remote repo, it does work with --remote
-h, --help              help for protoc
--home string       The goctl home path of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
--remote string     The remote git repo of the template, --home and --remote cannot be set at the same time, if they are, --remote has higher priority
The git repo directory must be consistent with the https://github.com/zeromicro/go-zero-template directory structure
--style string      The file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md] (default "gozero")
-v, --verbose           Enable log output
--zrpc_out string   The zrpc output directory

# 进入 greet.proto 所在目录
$ protoc greet.proto --go_out . --go-grpc_out .
$ tree
.
├── greet.proto
└── pb
├── greet.pb.go
└── greet_grpc.pb.go

# 这里多了一个 --zrpc_out 用于指定 zrpc 代码的输出目录
$ goctl rpc protoc greet.proto --go_out=. --go-grpc_out=. --zrpc_out=. --verbose
[goctl-env]: preparing to check env
[goctl-env]: looking up "protoc"
[goctl-env]: "protoc" is installed
[goctl-env]: looking up "protoc-gen-go"
[goctl-env]: "protoc-gen-go" is installed
[goctl-env]: looking up "protoc-gen-go-grpc"
[goctl-env]: "protoc-gen-go-grpc" is installed
[goctl-env]: congratulations! your goctl environment is ready!
[command]: protoc greet.proto --go_out . --go-grpc_out .
Done.
$ tree
.
├── etc
│   └── greet.yaml
├── go.mod
├── greet
│   └── greet.go
├── greet.go
├── greet.proto
├── internal
│   ├── config
│   │   └── config.go
│   ├── logic
│   │   └── pinglogic.go
│   ├── server
│   │   └── greetserver.go
│   └── svc
│       └── servicecontext.go
└── pb
├── greet.pb.go
└── greet_grpc.pb.go
8 directories, 11 files

# 1. golang
# github.com/golang/protobuf/protoc-gen-go
# 2. protocolbuffers
# github.com/protocolbuffers/protobuf-go/cmd/protoc-gen-go

# 1. golang 维护的仓库，目前已不推荐使用
# github.com/golang/protobuf/protoc-gen-go
# 2. protocolbuffers 维护的，目前推荐使用的
# github.com/protocolbuffers/protobuf-go/cmd/protoc-gen-go
# 3. goolge 安装，这其实和第二种安装的是一个二进制，他的源码就是protocolbuffers 维护的相同仓库
# google.golang.org/protobuf/cmd/protoc-gen-go

goctl.exe api go -api test.api -dir .
Stat : The system cannot find the path specified.

protoc-gen-go: unable to determine Go import path for "greet.proto"
Please specify either:
• a "go_package" option in the .proto source file, or
• a "M" argument on the command line.
See https://developers.google.com/protocol-buffers/docs/reference/go-generated#package for more information.
--go_out: protoc-gen-go: Plugin failed with status code 1.

the output of pb.go and _grpc.pb.go must not be the same with --zrpc_out:
pb output: /Users/keson/workspace/awesome-goctl/zwesome-zrpc/pb_in_main
zrpc out: /Users/keson/workspace/awesome-goctl/zwesome-zrpc/pb_in_main