trpc-cmdline

README

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.