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.


  • 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

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=.


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


rpc service generation usage#

$ goctl rpc protoc -h
goctl rpc protoc - generate grpc code
example: goctl rpc protoc xx.proto --go_out=./pb --go-grpc_out=./pb --zrpc_out=.
for details, see https://go-zero.dev/cn/goctl-rpc.html
--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=.
  1. --go_out and --go-grpc_out must generate the same final directory
  2. 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)


  • 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:


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);
Last updated on