Awesome

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

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.