tRPC-Go 框架 02：从 0 到 1 搭建 Hello World 服务

tRPC-Go 框架 02从 0 到 1 搭建 Hello World 服务理论铺垫够多本篇我们动手实战——从环境准备、proto 编写、代码生成、服务实现、到客户端调用一步步跑通第一个 tRPC-Go 服务。一、环境准备1.1 Go 环境go version# 要求 1.18goenv-wGOPROXYhttps://goproxy.cn,direct goenv-wGOPRIVATEgit.code.oa.com# 公司内部仓库需要1.2 安装 protocbrewinstallprotobuf protoc--version# libprotoc 241.3 安装 trpc-cmdlinegoinstalltrpc.group/trpc-go/trpc-cmdline/trpclatest trpc versiontrpc命令会自动安装下列工具protoc-gen-goprotoc-gen-go-trpcmockgen…如果失败可手动安装goinstallgoogle.golang.org/protobuf/cmd/protoc-gen-golatest goinstalltrpc.group/trpc-go/trpc-cmdline/protoc-gen-go-trpclatest goinstallgo.uber.org/mock/mockgenlatest二、定义 IDL新建项目目录mkdir-p~/study/trpc/helloworldcd~/study/trpc/helloworld创建helloworld.protosyntax proto3; package helloworld; option go_package git.code.oa.com/examples/helloworld; service HelloWorld { rpc Hello(HelloReq) returns (HelloRsp); } message HelloReq { string msg 1; } message HelloRsp { string msg 1; }要点package helloworldproto 内部命名空间option go_package生成 Go 代码的 import pathservice服务名PascalCase 习惯。三、生成项目骨架trpc create-phelloworld.proto-o.--modhelloworld参数解释-pproto 文件-o输出目录.即当前目录--modgo module 名。生成的目录结构helloworld/ ├── go.mod ├── go.sum ├── helloworld.proto ├── hello_world_service.go # 业务实现 ├── hello_world_service_test.go # 单测骨架 ├── main.go # 入口 ├── trpc_go.yaml # 配置 └── stub/ └── git.code.oa.com/examples/helloworld/ ├── helloworld.pb.go # message 类型 ├── helloworld.trpc.go # 服务端/客户端 stub └── helloworld_mock.go # mock 类型四、阅读生成代码4.1 helloworld.trpc.gotypeHelloWorldServiceinterface{Hello(ctx context.Context,req*HelloReq)(*HelloRsp,error)}funcRegisterHelloWorldService(s server.Service,svr HelloWorldService){...}typeHelloWorldClientProxyinterface{Hello(ctx context.Context,req*HelloReq,opts...client.Option)(*HelloRsp,error)}funcNewHelloWorldClientProxy(opts...client.Option)HelloWorldClientProxy{...}4.2 hello_world_service.go你来实现packagemainimport(contextpbgit.code.oa.com/examples/helloworld)typehelloWorldImplstruct{}func(s*helloWorldImpl)Hello(ctx context.Context,req*pb.HelloReq)(*pb.HelloRsp,error){returnpb.HelloRsp{Msg:Hello, req.Msg},nil}4.3 main.gopackagemainimport(trpc.group/trpc-go/trpc-gopbgit.code.oa.com/examples/helloworld)funcmain(){s:trpc.NewServer()pb.RegisterHelloWorldService(s,helloWorldImpl{})iferr:s.Serve();err!nil{panic(err)}}4.4 trpc_go.yamlglobal:namespace:Developmentenv_name:testserver:app:examplesserver:helloworldservice:-name:trpc.examples.helloworld.HelloWorldip:127.0.0.1port:8000protocol:trpctimeout:1000plugins:log:default:-writer:consolelevel:info五、运行服务端go mod tidy go run.正常启动会输出类似2026-05-19 10:00:00 INFO [server] service trpc.examples.helloworld.HelloWorld start六、写一个客户端新建cmd/client/main.gopackagemainimport(contextfmttimetrpctrpc.group/trpc-go/trpc-gotrpc.group/trpc-go/trpc-go/clientpbgit.code.oa.com/examples/helloworld)funcmain(){// 加载配置也可不加载使用默认_,err:trpc.LoadConfig(../../trpc_go.yaml)iferr!nil{panic(err)}proxy:pb.NewHelloWorldClientProxy(client.WithTarget(ip://127.0.0.1:8000),client.WithProtocol(trpc),client.WithTimeout(time.Second),)ctx:context.Background()rsp,err:proxy.Hello(ctx,pb.HelloReq{Msg:World})iferr!nil{fmt.Println(call failed:,err)return}fmt.Println(response:,rsp.Msg)}运行go run cmd/client/main.go# response: Hello, World七、用 trpc-cli 调试goinstalltrpc.group/trpc-go/trpc-cli/cmd/trpc-clilatest trpc-cli-func/helloworld.HelloWorld/Hello\-targetip://127.0.0.1:8000\-body{msg:World}输出{msg:Hello, World}非常方便无需写客户端代码就能调用任何 tRPC 服务。八、协议切换HTTP只需修改配置service:-name:trpc.examples.helloworld.HelloWorldip:127.0.0.1port:8000protocol:http重启后用 curl 直接访问curl-XPOST http://127.0.0.1:8000/helloworld.HelloWorld/Hello\-HContent-Type: application/json\-d{msg:World}# {msg:Hello, World}同一份代码 改一行配置 切到 HTTP 协议这就是 tRPC 协议可插拔的威力。九、加一个简单的 filter修改 main.go 注册自定义 filterimporttrpc.group/trpc-go/trpc-go/filterfuncloggingFilter(ctx context.Context,req,rsp any,next filter.ServerHandleFunc)error{start:time.Now()err:next(ctx,req,rsp)log.Printf(call took %v err%v,time.Since(start),err)returnerr}funcmain(){filter.Register(logging,loggingFilter,nil)// ...}trpc_go.yaml启用server:filter:[logging]十、单元测试hello_world_service_test.gofuncTestHello(t*testing.T){svc:helloWorldImpl{}rsp,err:svc.Hello(context.Background(),pb.HelloReq{Msg:tRPC})assert.NoError(t,err)assert.Equal(t,Hello, tRPC,rsp.Msg)}gotest-v./...十一、构建二进制并部署GOOSlinuxGOARCHamd64 go build-ohelloworld_server.部署时把二进制 trpc_go.yaml一起放到目标机器运行./helloworld_server-conftrpc_go.yaml十二、常见问题Q1:cannot find module ...仓库路径在go_package中而本地没有该路径。让 stub 存在于本地相对路径option go_package github.com/myname/helloworld/stub;或在go.mod中用 replace 指向本地目录replace git.code.oa.com/examples/helloworld ./stub/git.code.oa.com/examples/helloworldQ2: 服务启动后端口占用lsof-i:8000kill-9PID或修改trpc_go.yaml里的 port。Q3: trpc create 报 protoc 找不到确认已安装protobufwhich protoc输出非空且 PATH 包含$GOPATH/bin。十三、小结至此你完成了编写.prototrpc create一键生成项目骨架实现Hello方法启动服务端 客户端 trpc-cli 调试修改协议为 HTTP添加自定义 filter编写单测。整个流程不超过 30 分钟这就是 tRPC 的工程化能力。下一篇我们将深入服务端开发handler、filter、错误处理。