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 remote;

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
    │   ├── 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，并且已经设置环境变量
* mockgen(可选)

# 用法
```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
    ```
  的标识，请注意不要将也写业务性代码写在里面。