RPC Commands

[!TIP] This document is machine-translated by Google. If you find grammatical and semantic errors, and the document description is not clear, please PR

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


  • Simple and easy to use
  • Quickly improve development efficiency
  • Low error rate
  • Close to protoc

Quick start

The way one: Quickly generate greet service

Generated by the command goctl rpc new ${servieName}

Such as generating greet rpc service:

  goctl rpc new greet

The code structure after execution is as follows:

├── etc             // yaml configuration file
│   └── greet.yaml
├── go.mod
├── greet           // pb.go folder①
│   └── greet.pb.go
├── greet.go        // main entry
├── greet.proto     // proto source file
├── greetclient     // call logic ②
│   └── greet.go
└── internal        
    ├── config      // yaml configuration corresponding entity
    │   └── config.go
    ├── logic       //business code
    │   └── pinglogic.go
    ├── server      // rpc server
    │   └── greetserver.go
    └── svc         // dependent resources
        └── servicecontext.go

① The name of the pb folder (the old version folder is fixed as pb) is taken from the value of option go_package in the proto file. The last level is converted according to a certain format. If there is no such declaration, it is taken from the value of package. The approximate code is as follows:

  if option.Name == "go_package" {
    ret.GoPackage = option.Constant.Source
  if len(ret.GoPackage) == 0 {
    ret.GoPackage = ret.Package.Name
  ret.PbPackage = GoSanitized(filepath.Base(ret.GoPackage))

For GoSanitized method, please refer to google.golang.org/protobuf@v1.25.0/internal/strs/strings.go:71

② The name of the call layer folder is taken from the name of the service in the proto. If the name of the sercice is equal to the name of the pb folder, the client will be added after service to distinguish between pb and call.

if strings.ToLower(proto.Service.Name) == strings.ToLower(proto.GoPackage) {
    callDir = filepath.Join(ctx.WorkDir, strings.ToLower(stringx.From(proto.Service.Name+"_client").ToCamel()))

rpc one-click generation to solve common problems, see Error

The way two: Generate rpc service by specifying proto

  • Generate proto template

    goctl rpc template -o=user.proto
    syntax = "proto3";
    package remote;
    option go_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);
  • Generate rpc service code

    goctl rpc proto -src user.proto -dir .


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


rpc service generation usage

goctl rpc proto -h
   goctl rpc proto - generate rpc from proto

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

   --src value, -s value         the file path of the proto source file
   --proto_path value, -I value  native command of protoc, specify the directory in which to search for imports. [optional]
   --dir value, -d value         the target path of the code
   --style value                 the file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md]
   --idea                        whether the command execution environment is from idea plugin. [optional]


  • --src: required, the proto data source, currently supports the generation of a single proto file
  • --proto_path: optional. The protoc native subcommand is used to specify where to find proto import. You can specify multiple paths, such as goctl rpc -I={path1} -I={path2} ..., in You can leave it blank when there is no import. The current proto path does not need to be specified, it is already built-in. For the detailed usage of -I, please refer to protoc -h
  • --dir: optional, the default is the directory where the proto file is located, the target directory of the generated code
  • --style value the file naming format, see [https://github.com/zeromicro/go-zero/tree/master/tools/goctl/config/readme.md]
  • --idea: optional, whether it is executed in the idea plug-in, terminal execution can be ignored

What developers need to do

Pay attention to business code writing, hand over repetitive and business-unrelated work to goctl, after generating the rpc service code, developers only need to modify.

  • Preparation of configuration files in the service (etc/xx.json, internal/config/config.go)
  • Writing business logic in the service (internal/logic/xxlogic.go)
  • Preparation of resource context in the service (internal/svc/servicecontext.go)


  • proto does not support the generation of multiple files at the same time
  • proto does not support the introduction of external dependency packages, and message does not support inline
  • At present, the main file, shared file, and handler file will be forcibly overwritten, and those that need to be written manually by the developer will not be overwritten and generated. This category has the code header

        // Code generated by goctl. DO NOT EDIT!
        // Source: xxx.proto

    If it contains the DO NOT EDIT logo, please be careful not to write business code in it.

proto import

  • The requestType and returnType in rpc must be defined in the main proto file. For the message in proto, other proto files can be imported like protoc.

proto example:

Wrong import

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

Import correctly

syntax = "proto3";

package greet;

option go_package = "greet";

import "base/common.proto"

message Request {
  base.In in = 1;

message Response {
 base.Out out = 2;

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

Guess you wants

Copyright © 2019-2021 go-zero all right reserved,powered by GitbookLast UpdateTime: 2021-12-05 09:48:50

results matching ""

    No results matching ""