RPC Commands

Goctl Rpc is an rpc service code generation module under goctl scaffolding, supporting proto template generation and rpc service code generation, through this tool to generate code you only need to focus on business logic writing instead of writing some repetitive code. This allows us to focus on the business, thus speeding up the development efficiency and reducing the error rate of the code.

Features#

Easy to use
Fast and efficient development
Low error rate
Close to protoc

Quick start#

Way 1: Quickly generate greet services#

Generated by the command goctl rpc new ${servieName}

If you generate the greet rpc service.

$ goctl rpc new greet

The code structure after execution is as follows:

.
├── etc
│   └── greet.yaml
├── go.mod
├── go.sum
├── greet
│   ├── greet.go
│   ├── greet.pb.go
│   └── greet_grpc.pb.go
├── greet.go
├── greet.proto
└── internal
    ├── config
    │   └── config.go
    ├── logic
    │   └── pinglogic.go
    ├── server
    │   └── greetserver.go
    └── svc
        └── servicecontext.go

tip

See rpc directory for details of the new version of the directory.

Way 2: Generate rpc service by specifying proto#

生成proto模板
$ goctl rpc template -o=user.proto
syntax = "proto3";

package user;
option go_package=". /user";

message Request {
string ping = 1;
}

message Response {
string pong = 1;
}

service User {
rpc Ping(Request) returns(Response);
}
Generate rpc service code
$ goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

Preparing#

Installed the go environment
protoc & protoc-gen-go are installed, and environment variables have been set
For more questions, see Notes

Usage#

rpc service generation usage#

$ goctl rpc protoc -h
NAME:
   goctl rpc protoc - generate grpc code

USAGE:
   example: goctl rpc protoc xx.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.

DESCRIPTION:
   for details, see https://go-zero.dev/cn/goctl-rpc.html

OPTIONS:
   --zrpc_out value  the zrpc output directory
   --style value     the file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md]
   --home value      the goctl home path of the template
   --remote value    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
   --branch value    the branch of the remote repo, it does work with --remote
   --verbose, -v     enable log output

You can understand that zrpc code generation is done with goctl rpc $protoc_command --zrpc_out=${output} templates, as in the original command to generate grpc code

$ protoc user.proto --go_out=. --go-grpc_out=.

then the zrpc code command would be

$ goctl rpc protoc user.proto --go_out=. --go-grpc_out=. --zrpc_out=.

tip

--go_out and --go-grpc_out must generate the same final directory
The final directories generated by --go_out & --go-grpc_out and --zrpc_out must not be the same directory, otherwise pb.go and _grpc.pb.go are at the same level as the main function, which is not allowed.
The directories produced by --go_out and --go-grpc_out are affected by the go_package values in the --go_opt and --grpc-go_opt and proto source files. To understand the generation logic here, it is recommended to read the Official documentation: Go Generated Code

What developers need to do#

Focus on business code writing, leave the repetitive, non-business related work to goctl, after generating the rpc service code, developers only need to modify

write configuration files in the service (etc/xx.json, internal/config/config.go)
Business logic writing in the service (internal/logic/xxlogic.go)
Writing of resource contexts in services (internal/svc/servicecontext.go)

Caution#

proto does not support simultaneous generation of multiple files at the moment
proto does not support external dependency package introduction, message does not support inline
Currently main file, shared file, handler file will be forced to overwrite, and developers need to write manually will not overwrite the generation, this kind of code in the header are
// Code generated by goctl. do not EDIT!
// Source: xxx.proto
Please be careful not to write business code in it; and do not write it inside business code.

proto import#

For requestType and returnType in rpc must be defined in main proto file, for message in proto you can import other proto files like protoc.

proto example:

errorimport#

syntax = "proto3";

package greet;

option go_package = "./greet";

import "base/common.proto";

message Request {
  string ping = 1;
}

message Response {
  string pong = 1;
}

service Greet {
  rpc Ping(base.In) returns(base.Out);// request and return do not support import
}

Correct import#

syntax = "proto3";

package greet;

option go_package = "./greet";

import "base/common.proto";

message Request {
  base.In in = 1;// support import
}

message Response {
 base.Out out = 2;// support import
}

service Greet {
  rpc Ping(Request) returns(Response);
}