trpc.group/trpc-go/trpc-cmdline@v1.0.9/README.zh_CN.md (about) 1 [English](README.md) | 中文 2 3 # trpc-cmdline 4 5 [![Go Reference](https://pkg.go.dev/badge/github.com/trpc-group/trpc-cmdline.svg)](https://pkg.go.dev/github.com/trpc-group/trpc-cmdline) 6 [![Go Report Card](https://goreportcard.com/badge/trpc.group/trpc-go/trpc-cmdline)](https://goreportcard.com/report/trpc.group/trpc-go/trpc-cmdline) 7 [![LICENSE](https://img.shields.io/badge/license-Apache--2.0-green.svg)](https://github.com/trpc-group/trpc-cmdline/blob/main/LICENSE) 8 [![Releases](https://img.shields.io/github/release/trpc-group/trpc-cmdline.svg?style=flat-square)](https://github.com/trpc-group/trpc-cmdline/releases) 9 [![Tests](https://github.com/trpc-group/trpc-cmdline/actions/workflows/prc.yml/badge.svg)](https://github.com/trpc-group/trpc-cmdline/actions/workflows/prc.yml) 10 [![Coverage](https://codecov.io/gh/trpc-group/trpc-cmdline/branch/main/graph/badge.svg)](https://app.codecov.io/gh/trpc-group/trpc-cmdline/tree/main) 11 12 trpc-cmdline 是 [trpc-cpp](https://github.com/trpc-group/trpc-cpp) 和 [trpc-go](https://github.com/trpc-group/trpc-go) 的命令行工具。 13 14 本项目支持 [Go](https://go.dev/doc/devel/release) 最新发布的三个版本。 15 16 ## 安装 17 18 ### 安装 trpc-cmdline 19 20 #### 使用 go 命令进行安装 21 22 首先将以下内容添加到你的 `~/.gitconfig` 中: 23 24 ```bash 25 [url "ssh://git@github.com/"] 26 insteadOf = https://github.com/ 27 ``` 28 29 然后执行以下命令以安装 `trpc-cmdline`: 30 31 ```bash 32 go install trpc.group/trpc-go/trpc-cmdline/trpc@latest 33 ``` 34 35 如果在大陆报错 EOF,需配置代理,具体步骤请查看: https://goproxy.cn/ 36 37 <!-- #### Install from release 38 39 <details><summary>Click to show the bash script</summary><br><pre> 40 $ TAG="v0.0.1" # Choose tag. 41 $ OS=linux # Choose from "linux", "darwin" or "windows". 42 $ wget -O trpc https://github.com/trpc-group/trpc-cmdline/releases/download/${TAG}/trpc_${OS} 43 $ mkdir -p ~/go/bin && chmod +x trpc && mv trpc ~/go/bin 44 $ export PATH=~/go/bin:$PATH # Add this to your `~/.bashrc`. 45 </pre></details> --> 46 47 ### 安装依赖 48 49 通过以下两种方式之一可以安装所有的依赖。 50 51 #### 使用 trpc setup 一键安装所有依赖 52 53 只需要运行 `trpc setup` 便可安装所有依赖。假如有些依赖安装不成功,可以参考下一节进行手动安装。 54 55 #### 手动安装各种依赖 56 57 <details><summary>Install protoc </summary><br><pre> 58 $ # Reference: https://grpc.io/docs/protoc-installation/ 59 $ PB_REL="https://github.com/protocolbuffers/protobuf/releases" 60 $ curl -LO $PB_REL/download/v3.15.8/protoc-3.15.8-linux-x86_64.zip 61 $ unzip -o protoc-3.15.8-linux-x86_64.zip -d $HOME/.local 62 $ export PATH=~/.local/bin:$PATH # Add this to your `~/.bashrc`. 63 $ protoc --version 64 libprotoc 3.15.8 65 </pre></details> 66 67 <details><summary>Install flatc </summary><br><pre> 68 $ # Reference: https://github.com/google/flatbuffers/releases 69 $ wget https://github.com/google/flatbuffers/releases/download/v23.5.26/Linux.flatc.binary.g++-10.zip 70 $ unzip -o Linux.flatc.binary.g++-10.zip -d $HOME/.bin 71 $ export PATH=~/.bin:$PATH # Add this to your `~/.bashrc`. 72 $ flatc --version 73 flatc version 23.5.26 74 </pre></details> 75 76 <details><summary>Install protoc-gen-go</summary><br><pre> 77 $ # Reference: https://grpc.io/docs/languages/go/quickstart/ 78 $ go install google.golang.org/protobuf/cmd/protoc-gen-go@latest 79 </pre></details> 80 81 <details><summary>Install goimports</summary><br><pre> 82 $ go install golang.org/x/tools/cmd/goimports@latest 83 </pre></details> 84 85 <details><summary>Install mockgen</summary><br><pre> 86 $ # Reference: https://github.com/uber-go/mock 87 $ go install go.uber.org/mock/mockgen@latest 88 </pre></details> 89 90 <details><summary>Install protoc-gen-validate and protoc-gen-validate-go</summary><br><pre> 91 $ # Please download the binaries in https://github.com/bufbuild/protoc-gen-validate/releases 92 $ # Or: 93 $ go install github.com/envoyproxy/protoc-gen-validate@latest 94 $ go install github.com/envoyproxy/protoc-gen-validate/cmd/protoc-gen-validate-go@latest 95 </pre></details> 96 97 ## 快速上手 98 99 ### 生成完整项目 100 101 * 将以下内容复制到 `helloworld.proto`, 原始文件为 [docs/helloworld/helloworld.proto](docs/helloworld/helloworld.proto): 102 103 ```protobuf 104 syntax = "proto3"; 105 package helloworld; 106 107 option go_package = "github.com/some-repo/examples/helloworld"; 108 109 // HelloRequest is hello request. 110 message HelloRequest { 111 string msg = 1; 112 } 113 114 // HelloResponse is hello response. 115 message HelloResponse { 116 string msg = 1; 117 } 118 119 // HelloWorldService handles hello request and echo message. 120 service HelloWorldService { 121 // Hello says hello. 122 rpc Hello(HelloRequest) returns(HelloResponse); 123 } 124 ``` 125 126 * 使用 trpc-cmdline 来生成完整项目: 127 ```go 128 $ trpc create -p helloworld.proto -o out 129 ``` 130 131 注意: `-p` 用于指定 proto 文件, `-o` 用于指定输出目录, 132 更多 flag 信息可以运行 `trpc -h` 以及 `trpc create -h` 来进行查看。 133 134 * 进入输出目录,运行服务端: 135 ```bash 136 $ cd out 137 $ go run . 138 ... 139 ... trpc service:helloworld.HelloWorldService launch success, tcp:127.0.0.1:8000, serving ... 140 ... 141 ``` 142 143 * 在另一个终端中进入输出目录,运行客户端: 144 ```bash 145 $ go run cmd/client/main.go 146 ... simple rpc receive: 147 ``` 148 149 注意: 由于生成的代码默认都是空操作,因此日志中显示的收到的数据内容也为空。 150 151 * 现在你可以尝试修改 `hello_world_service.go` 中的服务端代码以及 `cmd/client/main.go` 中的客户端代码来创建一个 echo 服务器。你可以参考 [https://github.com/trpc-group/trpc-go/tree/main/examples/helloworld](https://github.com/trpc-group/trpc-go/tree/main/examples/helloworld) 以获取灵感 152 153 * 生成文件的详细解释如下: 154 155 ```bash 156 $ tree 157 . 158 |-- cmd 159 | `-- client 160 | `-- main.go # Generated client code. 161 |-- go.mod 162 |-- go.sum 163 |-- hello_world_service.go # Generated server service implementation. 164 |-- hello_world_service_test.go 165 |-- main.go # Server entrypoint. 166 |-- stub # Stub code. 167 | `-- github.com 168 | `-- some-repo 169 | `-- examples 170 | `-- helloworld 171 | |-- go.mod 172 | |-- helloworld.pb.go 173 | |-- helloworld.proto 174 | |-- helloworld.trpc.go 175 | `-- helloworld_mock.go 176 `-- trpc_go.yaml # Configuration file for trpc-go. 177 ``` 178 179 ### 仅生成桩代码 180 181 * 只需要添加 `--rpconly` 选项就可以只生成桩代码: 182 ```go 183 $ trpc create -p helloworld.proto -o out --rpconly 184 $ tree out 185 out 186 |-- go.mod 187 |-- go.sum 188 |-- helloworld.pb.go 189 |-- helloworld.trpc.go 190 `-- helloworld_mock.go 191 ``` 192 193 ### 常用的指令 194 195 下面列举了一些常用的命令行选项: 196 197 * `-f`: 用于强制覆盖输出目录中的内容 198 * `-d some-dir`: 添加 proto 文件的查找路径(包括依赖的 proto 文件),可以指定多次 199 * `--mock=false`: 禁止生成 mock 代码 200 * `--nogomod=true`: 在生成桩代码时不生成 `go.mod` 文件,只在 `--rpconly=true` 的时候生效, 默认为 `false` 201 * `-l cpp`:生成 cpp 桩代码 202 * `--validate=true`: 开启数据校验,详细用法见 [/docs/examples/example-2/README.zh_CN.md](/docs/examples/example-2/README.zh_CN.md) 203 204 **注意:** `alias/gotag/validate/swagger` 这些 option 使用时的 proto import 路径通常有所不同: 205 206 * `trpc.alias`: `import "trpc/proto/trpc_options.proto";` 207 * `trpc.go_tag`: `import "trpc/proto/trpc_options.proto";` 208 * `validate.rules`: `import "validate/validate.proto";` 209 * `trpc.swagger`: `import "trpc/swagger/swagger.proto";` 210 211 详细用法请参考 [/docs/examples/example-2/README.zh_CN.md](/docs/examples/example-2/README.zh_CN.md) 212 213 更多命令行选项可以执行 `trpc -h` 以及 `trpc [subcmd] -h` 来进行查看。 214 215 ### 更多功能 216 217 请查看 [文档](docs/README.zh_CN.md) 218 219 ## 贡献 220 221 本开源项目欢迎任何贡献,请阅读 [贡献指南](CONTRIBUTING.zh_CN.md) 以获取更多信息。