English | 中文

trpc-cmdline

trpc-cmdline is the command line tool for trpc-cpp and trpc-go.

It supports the latest three major releases of Go.

Installation

Install trpc-cmdline

Install using go command

First, add the following into your ~/.gitconfig:

[url "ssh://git@github.com/"]
    insteadOf = https://github.com/

Then run the following to install trpc-cmdline:

go install trpc.group/trpc-go/trpc-cmdline/trpc@latest

Dependencies

Use one of the following methods to download:

Using trpc setup

After installation of trpc-cmdline, simply running trpc setup will automatically install all the dependencies.

Install separately

Install protoc

$ # Reference: https://grpc.io/docs/protoc-installation/
$ PB_REL="https://github.com/protocolbuffers/protobuf/releases"
$ curl -LO $PB_REL/download/v3.15.8/protoc-3.15.8-linux-x86_64.zip
$ unzip -o protoc-3.15.8-linux-x86_64.zip -d $HOME/.local
$ export PATH=~/.local/bin:$PATH # Add this to your `~/.bashrc`.
$ protoc --version
libprotoc 3.15.8

Install flatc

$ # Reference: https://github.com/google/flatbuffers/releases
$ wget https://github.com/google/flatbuffers/releases/download/v23.5.26/Linux.flatc.binary.g++-10.zip
$ unzip -o Linux.flatc.binary.g++-10.zip -d $HOME/.bin
$ export PATH=~/.bin:$PATH # Add this to your `~/.bashrc`.
$ flatc --version
flatc version 23.5.26

Install protoc-gen-go

$ # Reference: https://grpc.io/docs/languages/go/quickstart/
$ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest

Install goimports

$ go install golang.org/x/tools/cmd/goimports@latest

Install mockgen

$ # Reference: https://github.com/uber-go/mock
$ go install go.uber.org/mock/mockgen@latest

Install protoc-gen-validate and protoc-gen-validate-go

$ # Please download the binaries in https://github.com/bufbuild/protoc-gen-validate/releases
$ # Or:
$ go install github.com/envoyproxy/protoc-gen-validate@latest
$ go install github.com/envoyproxy/protoc-gen-validate/cmd/protoc-gen-validate-go@latest

Quick Start

Generation of Full Project

Copy and paste the following to helloworld.proto, you can get it from docs/helloworld/helloworld.proto:

syntax = "proto3";
package helloworld;

option go_package = "github.com/some-repo/examples/helloworld";

// HelloRequest is hello request.
message HelloRequest {
  string msg = 1;
}

// HelloResponse is hello response.
message HelloResponse {
  string msg = 1;
}

// HelloWorldService handles hello request and echo message.
service HelloWorldService {
  // Hello says hello.
  rpc Hello(HelloRequest) returns(HelloResponse);
}

Using trpc-cmdline to generate a full project:

$ trpc create -p helloworld.proto -o out

Note: -p specifies proto file, -o specifies the output directory, for more information please run trpc -h and trpc create -h

Enter the output directory and start the server:

$ cd out
$ go run .
...
... trpc service:helloworld.HelloWorldService launch success, tcp:127.0.0.1:8000, serving ...
...

Open the output directory in another terminal and start the client:

$ go run cmd/client/main.go 
... simple  rpc   receive:

Note: Since the implementation of server service is an empty operation and the client sends empty data, therefore the log shows that the simple rpc receives an empty string.

Now you may try to modify the service implementation located in hello_world_service.go and the client implementation located in cmd/client/main.go to create an echo server. You can refer to https://github.com/trpc-group/trpc-go/tree/main/examples/helloworld for inspiration.
The generated files are explained below:

$ tree
.
|-- cmd
|   `-- client
|       `-- main.go  # Generated client code.
|-- go.mod
|-- go.sum
|-- hello_world_service.go  # Generated server service implementation.
|-- hello_world_service_test.go
|-- main.go  # Server entrypoint.
|-- stub  # Stub code.
|   `-- github.com
|       `-- some-repo
|           `-- examples
|               `-- helloworld
|                   |-- go.mod
|                   |-- helloworld.pb.go
|                   |-- helloworld.proto
|                   |-- helloworld.trpc.go
|                   `-- helloworld_mock.go
`-- trpc_go.yaml  # Configuration file for trpc-go.

Generation of RPC Stub

Simply add --rpconly flag to generate rpc stub instead of a full project:

$ trpc create -p helloworld.proto -o out --rpconly
$ tree out
out
|-- go.mod
|-- go.sum
|-- helloworld.pb.go
|-- helloworld.trpc.go
`-- helloworld_mock.go

Frequently Used Flags

The following lists some frequently used flags.

-f: Force overwrite the existing code.
-d some-dir: Search paths for pb files (including dependent pb files), can be specified multiple times.
--mock=false: Disable generation of mock stub code.
--nogomod=true: Do not generate go.mod file in the stub code, only effective when --rpconly=true, defaults to false.
-l cpp：Generate stub code for cpp.
--validate=true: Enables data validation. For detailed usage, see /docs/examples/example-2/README.md.

Note: The proto import paths for options like alias/gotag/validate/swagger usually vary:

trpc.alias: import "trpc/proto/trpc_options.proto";
trpc.go_tag: import "trpc/proto/trpc_options.proto";
validate.rules: import "validate/validate.proto";
trpc.swagger: import "trpc/swagger/swagger.proto";

For detailed usage, please refer to /docs/examples/example-2/README.zh_CN.md

For additional flags please run trpc -h and trpc [subcmd] -h.

Functionalities

Please check Documentation

Contributing

This project is open-source and accepts contributions. See the contribution guide for more information.

clowniii/trpc-cmdline