go-zero/tools/goctl/rpc/README.md

# Rpc Generation
Goctl Rpc是`goctl`脚手架下的一个rpc服务代码生成模块，支持proto模板生成和rpc服务代码生成，通过此工具生成代码你只需要关注业务逻辑编写而不用去编写一些重复性的代码。这使得我们把精力重心放在业务上，从而加快了开发效率且降低了代码出错率。

# 特性
* 简单易用
* 快速提升开发效率
* 出错率低

# 快速开始

### 生成proto模板

```shell script
$ goctl rpc template -o=user.proto
```

```golang
syntax = "proto3";

package remoteuser;

message Request {
  // 用户名
  string username = 1;
  // 用户密码
  string password = 2;
}

message Response {
  // 用户名称
  string name = 1;
  // 用户性别
  string gender = 2;
}

service User{
  // 登录
  rpc Login(Request)returns(Response);
}
```
### 生成rpc服务代码

生成user rpc服务
```
$ goctl rpc proto -src=user.proto
```

代码tree

```
user
    ├── etc
    │   └── user.json
    ├── internal
    │   ├── config
    │   │   └── config.go
    │   ├── handler
    │   │   ├── loginhandler.go
    │   │   └── userhandler.go
    │   ├── logic
    │   │   └── loginlogic.go
    │   └── svc
    │       └── servicecontext.go
    ├── pb
    │   └── user.pb.go
    ├── shared
    │   ├── mockusermodel.go
    │   ├── types.go
    │   └── usermodel.go
    ├── user.go
    └── user.proto

```
# 准备工作
* 安装了go环境
* 安装了protoc，并且已经设置环境变量

# protoc-gen-go

在使用goctl生成rpc服务代码时，我们默认会根据开发人员正在开发的工程依赖的`github.com/golang/protobuf`自动将插件重新`go install`到`${GOPATH}/bin`中，
寻找方法：

### go mod 工程  
  对于`$ go version`不低于1.5版本的的工程，会优先寻找`$ go env GOMODCACHE`目录，如果没有则去`${GOPATH}`中查找（见下文）,而低于1.5版本的则会优先从`${GOPATH}/pkg/mod`目录下查找，否则也从`% GOPATH`中查找（见下文）
  
### go path工程
  对于没有使用go mod的工程，则默认当作在`${GOPATH}`中处理（暂不支持用户自定义的GOPATH），而这种情况下则会默认从`${GOPATH}/src`中查找
  
> 注意： 
 * 对于以上两种工程如果没有在对应目录查找到`protoc-gen-go`则会提示相应错误，尽管`protoc-gen-go`可能在其他已经设置环境变量的目录中，这个将在后面版本进行优化。
 * 对于go mod工程，如果工程没有依赖`github.com/golang/protobuf`则需要提前引入。
 
### 好处
* 保证grpc代码生成规范的一致性
 
# 用法
```shell script
$ goctl rpc proto -h
```

```shell script
NAME:
   goctl rpc proto - generate rpc from proto"

USAGE:
   goctl rpc proto [command options] [arguments...]

OPTIONS:
   --src value, -s value         the file path of the proto source file
   --dir value, -d value         the target path of the code,default path is "${pwd}". [option]
   --service value, --srv value  the name of rpc service. [option]
   --shared value                the dir of the shared file,default path is "${pwd}/shared. [option]"
   --idea                        whether the command execution environment is from idea plugin. [option]

```

* 参数说明
    * --src 必填，proto数据源，目前暂时支持单个proto文件生成，这里不支持（不建议）外部依赖
    * --dir 非必填，默认为proto文件所在目录，生成代码的目标目录
    * --service 服务名称，非必填，默认为proto文件所在目录名称，但是，如果proto所在目录为一下结构：
        ```shell script
        user
            ├── cmd
            │   └── rpc
            │       └── user.proto
        ```
        则服务名称亦为user，而非proto所在文件夹名称了，这里推荐使用这种结构，可以方便在同一个服务名下建立不同类型的服务(api、rpc、mq等)，便于代码管理与维护。
    * --shared 非必填，默认为$dir(xxx.proto)/shared，rpc client逻辑代码存放目录。
        
      > 注意：这里的shared文件夹名称将会是代码中的package名称。
    
    * --idea 非必填，是否为idea插件中执行，保留字段，终端执行可以忽略
     
# 开发人员需要做什么

关注业务代码编写，将重复性、与业务无关的工作交给goctl，生成好rpc服务代码后，开饭人员仅需要修改
* 服务中的配置文件编写(etc/xx.json、internal/config/config.go)
* 服务中业务逻辑编写(internal/logic/xxlogic.go)
* 服务中资源上下文的编写(internal/svc/servicecontext.go)

# 扩展
对于需要进行rpc mock的开发人员，在安装了`mockgen`工具的前提下可以在rpc的shared文件中生成好对应的mock文件。

# 注意事项
* proto不支持暂多文件同时生成
* proto不支持外部依赖包引入，message不支持inline
* 目前main文件、shared文件、handler文件会被强制覆盖，而和开发人员手动需要编写的则不会覆盖生成，这一类在代码头部均有
    ```shell script
    // Code generated by goctl. DO NOT EDIT.
    // Source: xxx.proto
    ```
  的标识，请注意不要将也写业务性代码写在里面。


# 下一步规划
* 尽快支持windows端rpc生成