文档教程【免费下载链接】advanced-go-programming-book:books: 《Go语言高级编程》开源图书涵盖CGO、Go汇编语言、RPC实现、Protobuf插件实现、Web框架实现、分布式系统等高阶主题(完稿)项目地址https://gitcode.com/gh_mirrors/ad/advanced-go-programming-book点击查看免费下载本篇技术指南以《Go语言高级编程》第 4 章第 8 节为核心系统讲解如何在无需编写任何客户端代码的前提下借助 gRPC 的 reflection 反射机制与纯 Go 实现的 grpcurl 命令行工具完成对 gRPC 服务的服务列表查询、方法描述查看、类型信息获取以及基于 JSON 的远程方法调用。读者读完本文后将掌握 grpcurl 的安装、配置、常用子命令与流式接口测试方案可直接应用于仓库ch4-rpc章节示例服务的日常调试与联调场景。1. 为什么需要 grpcurl反射机制与无客户端调试Protobuf 本身具备反射能力可以在运行时获取对象对应的 Proto 定义信息。gRPC 在此基础上提供了名为reflection的官方反射包用于为 gRPC 服务提供动态查询能力——客户端无需事先编译导入.proto文件即可在运行时发现服务的方法签名、参数与返回值类型。gRPC 官方曾提供一个基于 C 实现的grpc_cli工具能够查询 gRPC 服务列表或调用 gRPC 方法。但 C 版本的工具链安装过程较为复杂跨平台使用成本高。作为替代Go 开源社区实现了纯 Go 语言版本的grpcurl工具安装简单、开箱即用这也是本节重点推荐并演示的工具。grpcurl 的核心价值在于它把服务端 反射服务 通用 CLI组合成一套无需生成客户端桩代码的调试链路。只要服务端启动了反射服务任何环境下甚至是没有 Proto 文件的机器上都可以直接通过命令行对服务发起真实的 RPC 调用。2. 第一步在 gRPC 服务端启动反射服务grpcurl 能工作的前提是服务端注册了 reflection 反射服务。reflection包对外只暴露了一个Register函数用于将*grpc.Server注册到反射服务中。官方文档给出的用法如下import ( google.golang.org/grpc/reflection ) func main() { s : grpc.NewServer() pb.RegisterYourOwnServer(s, server{}) // Register reflection service on gRPC server. reflection.Register(s) s.Serve(lis) }注册顺序上没有强制要求但通常在实际业务服务注册完成之后调用reflection.Register(s)。注册完成后反射服务会以grpc.reflection.v1alpha.ServerReflection的服务名暴露在 gRPC 服务端任何支持反射协议的客户端都可以查询该服务端上全部的服务信息包括反射服务自身。结合本仓库中的示例代码可以更直观地理解这一过程。在 examples/ch4.4/basic/client/main.go 中HelloServiceImpl实现了Hello一元方法和Channel双向流方法两个 RPC服务监听在:1234端口func startGrpcServer() { grpcServer : grpc.NewServer() RegisterHelloServiceServer(grpcServer, HelloServiceImpl{}) lis, err : net.Listen(tcp, :1234) if err ! nil { log.Fatal(err) } grpcServer.Serve(lis) }若希望该示例服务能被 grpcurl 查询只需在上述RegisterHelloServiceServer之后追加一行reflection.Register(grpcServer)即可。对应的服务定义位于 examples/ch4.4/basic/client/hello.proto其中Hello与Channel两个方法正是后续 grpcurl 演示所使用的目标syntax proto3; package main; message String { string value 1; } service HelloService { rpc Hello (String) returns (String); rpc Channel (stream String) returns (stream String); }注意反射服务是调试性能力会向所有能访问该端口的客户端暴露完整的服务与方法元数据。在生产环境对外开放的服务端上是否开启 reflection 需要结合安全策略审慎评估。3. grpcurl 的安装grpcurl 是 Go 语言开源社区fullstorydev开发的工具需要手工安装。由于它是纯 Go 实现安装过程非常简单两条命令即可完成$ go get github.com/fullstorydev/grpcurl $ go install github.com/fullstorydev/grpcurl/cmd/grpcurlgo get负责将源码拉取到模块缓存go install .../cmd/grpcurl负责编译并将可执行文件安装到$GOBIN默认是$GOPATH/bin目录下。安装完成后确认$GOBIN已加入PATH环境变量即可在任意终端直接使用grpcurl命令。如果使用的是较新的 Go 版本直接执行go install github.com/fullstorydev/grpcurl/cmd/grpcurllatest同样可以完成安装。4. grpcurl 的连接参数TLS、明文与 Unix Socketgrpcurl 的调用形式为$ grpcurl [flags] address [list | describe | 方法调用] [参数...]与连接方式相关的核心参数如下参数作用-cert file指定客户端公钥证书文件用于连接启用 TLS 协议的服务-key file指定客户端私钥文件与-cert配合完成双向 TLS 认证-plaintext以明文非 TLS方式连接没有启用 TLS 协议的 gRPC 服务并跳过证书验证过程-unix指定使用 Unix Socket 协议进行连接此时 address 为 socket 文件路径-d data调用方法时传入的 JSON 格式请求参数表示从标准输入读取默认情况下grpcurl 假定目标服务启用了 TLS 加密因此对于启用了 TLS 的服务需要通过-cert和-key参数提供客户端公钥与私钥文件对于未启用 TLS 的明文服务必须显式加上-plaintext参数对于通过 Unix Socket 通信的服务则需要指定-unix参数。5. 常见连接错误与排障5.1 未配置 TLS 参数导致的握手失败如果服务端是明文服务而调用时既没有配置公钥和私钥文件也没有使用-plaintext忽略证书验证那么 grpcurl 会尝试用 TLS 握手从而遇到类似下面的错误$ grpcurl localhost:1234 list Failed to dial target host localhost:1234: tls: first record does not \ look like a TLS handshake错误信息中 first record does not look like a TLS handshake 的含义是grpcurl 按 TLS 协议向服务端发送了 ClientHello但服务端返回的首个数据包并不是 TLS 握手记录——即服务端根本没有开启 TLS。解决办法为明文服务追加-plaintext参数。5.2 服务未注册反射服务如果 gRPC 服务本身运行正常但服务端没有调用reflection.Register注册反射服务则会收到如下错误$ grpcurl -plaintext localhost:1234 list Failed to list services: server does not support the reflection API该错误是 grpcurl 排查中最常见的坑之一先确认服务端是否注册了反射服务再排查网络与端口问题。6. list 命令查看服务列表与方法列表6.1 查看服务列表grpcurl 中最常使用的是list子命令用于获取服务或服务方法的列表。例如$ grpcurl localhost:1234 list将获取本地 1234 端口上 gRPC 服务的列表。假设服务端已经注册了反射服务且服务对应的 Protobuf 文件如下与本文第 2 节示例一致syntax proto3; package HelloService; message String { string value 1; } service HelloService { rpc Hello (String) returns (String); rpc Channel (stream String) returns (stream String); }使用明文模式执行list命令将看到以下输出$ grpcurl -plaintext localhost:1234 list HelloService.HelloService grpc.reflection.v1alpha.ServerReflection输出中的两行分别对应HelloService.HelloServiceProtobuf 文件中定义的业务服务grpc.reflection.v1alpha.ServerReflectionreflection包注册的反射服务本身。可以看到通过ServerReflection服务可以查询包括其自身在内的全部 gRPC 服务信息——这正是 grpcurl 一切动态查询能力的基础。6.2 查看指定服务的方法列表继续使用list子命令并追加服务名作为参数即可查看该服务的方法列表$ grpcurl -plaintext localhost:1234 list HelloService.HelloService Channel Hello从输出可以看到HelloService服务提供了Channel和Hello两个方法与 Protobuf 文件中的定义完全一致。7. describe 命令查看服务与类型的详细描述如果list只满足于知道有哪些服务和方法那么describe子命令则用于查看更详细的描述信息其输出采用 JSON 格式。7.1 描述整个服务$ grpcurl -plaintext localhost:1234 describe HelloService.HelloService HelloService.HelloService is a service: { name: HelloService, method: [ { name: Hello, inputType: .HelloService.String, outputType: .HelloService.String, options: { } }, { name: Channel, inputType: .HelloService.String, outputType: .HelloService.String, options: { }, clientStreaming: true, serverStreaming: true } ], options: { } }输出列出了服务的每个方法、每个方法的输入参数类型inputType与返回值类型outputType。值得关注的是Hello方法没有clientStreaming/serverStreaming标记是标准的一元 RPCChannel方法带有clientStreaming: true与serverStreaming: true说明它是双向流方法——这与 examples/ch4.4/basic/client/hello.proto 中rpc Channel (stream String) returns (stream String);的定义严格对应。7.2 描述具体类型在获取到方法的参数和返回值类型之后还可以继续查看类型的字段信息。下面用describe命令查看参数HelloService.String类型的信息$ grpcurl -plaintext localhost:1234 describe HelloService.String HelloService.String is a message: { name: String, field: [ { name: value, number: 1, label: LABEL_OPTIONAL, type: TYPE_STRING, options: { }, jsonName: value } ], options: { } }这段 JSON 信息对应HelloService.String类型在 Protobuf 中的定义message String { string value 1; }对照可见字段name对应 Protobuf 字段名valuenumber对应字段编号1type为TYPE_STRING字符串类型。grpcurl 输出的 JSON 数据本质上是 Protobuf 文件元信息的另一种表示形式二者互为映射理解这一点有助于在Proto 定义 ↔ JSON 描述之间自由切换。8. invoke 调用方法用 JSON 完成远程 RPC在获取 gRPC 服务的详细信息之后就可以通过 JSON 直接调用 gRPC 方法了。8.1 一元方法调用下面命令通过-d参数传入一个 JSON 字符串作为输入参数调用HelloService服务的Hello方法$ grpcurl -plaintext -d {value:gopher} \ localhost:1234 HelloService.HelloService/Hello { value: hello:gopher }调用形式为grpcurl [flags] address ServiceName/MethodName。其中-d {value:gopher}以 JSON 形式给出String.value字段的值方法路径HelloService.HelloService/Hello由包名.服务名/方法名拼接而成返回的{value: hello:gopher}与服务端实现逻辑一致——参照 examples/ch4.4/basic/client/main.go 中的HelloServiceImpl.Hello其行为正是返回hello: args.GetValue()。8.2 从标准输入读取参数如果-d参数的值是则表示从标准输入读取 JSON 输入参数。这通常用于两类场景输入参数比较复杂的 JSON 数据在命令行中不便转义书写测试流式方法需要连续发送多条输入消息。8.3 流式方法调用下面的命令连接Channel双向流方法通过从标准输入逐行读取输入流参数$ grpcurl -plaintext -d localhost:1234 HelloService.HelloService/Channel {value: gopher} { value: hello:gopher } {value: wasm} { value: hello:wasm }执行时终端进入交互式输入状态每输入一行 JSON如{value: gopher}并回车grpcurl 就将其作为一条流消息发送给服务端服务端处理完毕后返回一条响应如{value: hello:gopher}。从上面的输出可以看到输入{value: gopher}得到响应{value: hello:gopher}输入{value: wasm}得到响应{value: hello:wasm}每条输入都触发了服务端Channel方法中的接收—拼接hello:前缀—回发处理逻辑同样可对照 examples/ch4.4/basic/client/main.go 中Channel方法的实现。输入结束后发送 EOF如 Ctrl-D流即关闭。9. 实战小结grpcurl 的典型调试流程综合以上内容使用 grpcurl 调试一个 gRPC 服务的完整工作流可以归纳为四步服务端开启反射在grpc.NewServer()之后调用reflection.Register(s)确认连通性根据服务是否启用 TLS 选择-cert/-key或-plaintext先用grpcurl [flags] localhost:1234 list验证能否列出服务探查接口用list Service查看方法列表用describe Service与describe Type查看方法签名与字段定义发起调用用grpcurl -d ... address Service/Method调用一元方法用grpcurl -d address Service/Method从标准输入驱动流式方法。通过 grpcurl 工具我们可以在完全没有客户端代码的环境下测试 gRPC 服务无论是验证服务是否存活、探查接口签名还是模拟真实请求与流式交互都能以零代码的方式完成。这也使其成为 gRPC 微服务开发、联调与线上排障中不可或缺的瑞士军刀。本文所演示的HelloService示例及其Hello/Channel方法实现均可在仓库 examples/ch4.4/basic/client/main.go 与 examples/ch4.4/basic/client/hello.proto 中对照查看本节的配套讲解位于 ch4-rpc/ch4-08-grpcurl.md更多 RPC 与 Protobuf 主题可参考 第 4 章导读。赞分享文档教程【免费下载链接】advanced-go-programming-book:books: 《Go语言高级编程》开源图书涵盖CGO、Go汇编语言、RPC实现、Protobuf插件实现、Web框架实现、分布式系统等高阶主题(完稿)项目地址https://gitcode.com/gh_mirrors/ad/advanced-go-programming-book点击查看免费下载相关推荐grpc-go 服务反射Server Reflection实战三步启用反射并用 gRPCurl 免 proto 文件调试 RPCgrpc go 服务反射Server Reflection实战三步启用反射并用 gRPCurl 免 proto 文件调试 RPC gRPC Server后端RPC框架gRPC-Go 服务端反射Server Reflection注册与 gRPCurl 调试实战指南gRPC Go 服务端反射Server Reflection注册与 gRPCurl 调试实战指南 gRPC Go 的 reflection https://后端RPC框架grpc-go Server Reflection 实战一行代码注册反射服务用 grpcurl 免 proto 文件调试任何 gRPC 服务grpc go Server Reflection 实战一行代码注册反射服务用 grpcurl 免 proto 文件调试任何 gRPC 服务 导读 gRPC后端RPC框架上一篇顶级UI体验gh_mirrors/ma/material交互组件详解下一篇Scoop终极指南从零基础到精通Windows软件包管理创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考