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.

Features

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

Prepare

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

Usage

rpc service generation usage

goctl rpc proto -h

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
   --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/tal-tech/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/tal-tech/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)

Precautions

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);
}