trpc.group/trpc-go/trpc-cmdline@v1.0.9/README.md (about) 1 English | [中文](README.zh_CN.md) 2 3 # trpc-cmdline 4 5 [](https://pkg.go.dev/github.com/trpc-group/trpc-cmdline) 6 [](https://goreportcard.com/report/trpc.group/trpc-go/trpc-cmdline) 7 [](https://github.com/trpc-group/trpc-cmdline/blob/main/LICENSE) 8 [](https://github.com/trpc-group/trpc-cmdline/releases) 9 [](https://github.com/trpc-group/trpc-cmdline/actions/workflows/prc.yml) 10 [](https://app.codecov.io/gh/trpc-group/trpc-cmdline/tree/main) 11 12 trpc-cmdline is the command line tool for [trpc-cpp](https://github.com/trpc-group/trpc-cpp) and [trpc-go](https://github.com/trpc-group/trpc-go). 13 14 It supports the latest three major releases of [Go](https://go.dev/doc/devel/release). 15 16 ## Installation 17 18 ### Install trpc-cmdline 19 20 #### Install using go command 21 22 First, add the following into your `~/.gitconfig`: 23 24 ```bash 25 [url "ssh://git@github.com/"] 26 insteadOf = https://github.com/ 27 ``` 28 29 Then run the following to install `trpc-cmdline`: 30 31 ```bash 32 go install trpc.group/trpc-go/trpc-cmdline/trpc@latest 33 ``` 34 35 <!-- #### Install from release 36 37 <details><summary>Click to show the bash script</summary><br><pre> 38 $ TAG="v0.0.1" # Choose tag. 39 $ OS=linux # Choose from "linux", "darwin" or "windows". 40 $ wget -O trpc https://github.com/trpc-group/trpc-cmdline/releases/download/${TAG}/trpc_${OS} 41 $ mkdir -p ~/go/bin && chmod +x trpc && mv trpc ~/go/bin 42 $ export PATH=~/go/bin:$PATH # Add this to your `~/.bashrc`. 43 </pre></details> --> 44 45 ### Dependencies 46 47 Use one of the following methods to download: 48 49 #### Using trpc setup 50 51 After installation of trpc-cmdline, simply running `trpc setup` will automatically install all the dependencies. 52 53 #### Install separately 54 55 <details><summary>Install protoc </summary><br><pre> 56 $ # Reference: https://grpc.io/docs/protoc-installation/ 57 $ PB_REL="https://github.com/protocolbuffers/protobuf/releases" 58 $ curl -LO $PB_REL/download/v3.15.8/protoc-3.15.8-linux-x86_64.zip 59 $ unzip -o protoc-3.15.8-linux-x86_64.zip -d $HOME/.local 60 $ export PATH=~/.local/bin:$PATH # Add this to your `~/.bashrc`. 61 $ protoc --version 62 libprotoc 3.15.8 63 </pre></details> 64 65 <details><summary>Install flatc </summary><br><pre> 66 $ # Reference: https://github.com/google/flatbuffers/releases 67 $ wget https://github.com/google/flatbuffers/releases/download/v23.5.26/Linux.flatc.binary.g++-10.zip 68 $ unzip -o Linux.flatc.binary.g++-10.zip -d $HOME/.bin 69 $ export PATH=~/.bin:$PATH # Add this to your `~/.bashrc`. 70 $ flatc --version 71 flatc version 23.5.26 72 </pre></details> 73 74 <details><summary>Install protoc-gen-go</summary><br><pre> 75 $ # Reference: https://grpc.io/docs/languages/go/quickstart/ 76 $ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest 77 </pre></details> 78 79 <details><summary>Install goimports</summary><br><pre> 80 $ go install golang.org/x/tools/cmd/goimports@latest 81 </pre></details> 82 83 <details><summary>Install mockgen</summary><br><pre> 84 $ # Reference: https://github.com/uber-go/mock 85 $ go install go.uber.org/mock/mockgen@latest 86 </pre></details> 87 88 <details><summary>Install protoc-gen-validate and protoc-gen-validate-go</summary><br><pre> 89 $ # Please download the binaries in https://github.com/bufbuild/protoc-gen-validate/releases 90 $ # Or: 91 $ go install github.com/envoyproxy/protoc-gen-validate@latest 92 $ go install github.com/envoyproxy/protoc-gen-validate/cmd/protoc-gen-validate-go@latest 93 </pre></details> 94 95 ## Quick Start 96 97 ### Generation of Full Project 98 99 * Copy and paste the following to `helloworld.proto`, you can get it from [docs/helloworld/helloworld.proto](docs/helloworld/helloworld.proto): 100 101 ```protobuf 102 syntax = "proto3"; 103 package helloworld; 104 105 option go_package = "github.com/some-repo/examples/helloworld"; 106 107 // HelloRequest is hello request. 108 message HelloRequest { 109 string msg = 1; 110 } 111 112 // HelloResponse is hello response. 113 message HelloResponse { 114 string msg = 1; 115 } 116 117 // HelloWorldService handles hello request and echo message. 118 service HelloWorldService { 119 // Hello says hello. 120 rpc Hello(HelloRequest) returns(HelloResponse); 121 } 122 ``` 123 124 * Using trpc-cmdline to generate a full project: 125 ```go 126 $ trpc create -p helloworld.proto -o out 127 ``` 128 129 Note: `-p` specifies proto file, `-o` specifies the output directory, 130 for more information please run `trpc -h` and `trpc create -h` 131 132 * Enter the output directory and start the server: 133 ```bash 134 $ cd out 135 $ go run . 136 ... 137 ... trpc service:helloworld.HelloWorldService launch success, tcp:127.0.0.1:8000, serving ... 138 ... 139 ``` 140 141 * Open the output directory in another terminal and start the client: 142 ```bash 143 $ go run cmd/client/main.go 144 ... simple rpc receive: 145 ``` 146 147 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. 148 149 * 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](https://github.com/trpc-group/trpc-go/tree/main/examples/helloworld) for inspiration. 150 151 * The generated files are explained below: 152 153 ```bash 154 $ tree 155 . 156 |-- cmd 157 | `-- client 158 | `-- main.go # Generated client code. 159 |-- go.mod 160 |-- go.sum 161 |-- hello_world_service.go # Generated server service implementation. 162 |-- hello_world_service_test.go 163 |-- main.go # Server entrypoint. 164 |-- stub # Stub code. 165 | `-- github.com 166 | `-- some-repo 167 | `-- examples 168 | `-- helloworld 169 | |-- go.mod 170 | |-- helloworld.pb.go 171 | |-- helloworld.proto 172 | |-- helloworld.trpc.go 173 | `-- helloworld_mock.go 174 `-- trpc_go.yaml # Configuration file for trpc-go. 175 ``` 176 177 ### Generation of RPC Stub 178 179 * Simply add `--rpconly` flag to generate rpc stub instead of a full project: 180 ```go 181 $ trpc create -p helloworld.proto -o out --rpconly 182 $ tree out 183 out 184 |-- go.mod 185 |-- go.sum 186 |-- helloworld.pb.go 187 |-- helloworld.trpc.go 188 `-- helloworld_mock.go 189 ``` 190 191 ### Frequently Used Flags 192 193 The following lists some frequently used flags. 194 195 * `-f`: Force overwrite the existing code. 196 * `-d some-dir`: Search paths for pb files (including dependent pb files), can be specified multiple times. 197 * `--mock=false`: Disable generation of mock stub code. 198 * `--nogomod=true`: Do not generate go.mod file in the stub code, only effective when --rpconly=true, defaults to false. 199 * `-l cpp`：Generate stub code for cpp. 200 * `--validate=true`: Enables data validation. For detailed usage, see [/docs/examples/example-2/README.md](/docs/examples/example-2/README.md). 201 202 **Note:** The proto import paths for options like `alias/gotag/validate/swagger` usually vary: 203 204 * `trpc.alias`: `import "trpc/proto/trpc_options.proto";` 205 * `trpc.go_tag`: `import "trpc/proto/trpc_options.proto";` 206 * `validate.rules`: `import "validate/validate.proto";` 207 * `trpc.swagger`: `import "trpc/swagger/swagger.proto";` 208 209 For detailed usage, please refer to [/docs/examples/example-2/README.zh_CN.md](/docs/examples/example-2/README.zh_CN.md) 210 211 For additional flags please run `trpc -h` and `trpc [subcmd] -h`. 212 213 ### Functionalities 214 215 Please check [Documentation](docs/README.md) 216 217 ## Contributing 218 219 This project is open-source and accepts contributions. See the [contribution guide](CONTRIBUTING.md) for more information.