用 Twirp 构建 Protobuf RPC 服务:从 .proto 定义到自动生成客户端与服务端的 Go 实战指南
用 Twirp 构建 Protobuf RPC 服务:从 .proto 定义到自动生成客户端与服务端的 Go 实战指南
Twirp 是一个构建在 Protobuf 之上的极简 RPC 框架:你只需在一个 .proto 文件中声明服务,Twirp 就会自动生成服务端与客户端代码,剩下的"业务逻辑"由你填充。本文以本仓库的 Go 实现为对象,完整讲解 Twirp 的核心工作流——定义 Proto、用 protoc 生成代码、实现接口、挂载服务、调用客户端,并结合仓库源码剖析生成代码的内部结构与路由序列化细节。读完本文,你将能够独立创建并运行一个生产可用的 Twirp 服务,并理解其 HTTP 路由、双序列化协议与错误模型。
Twirp 是什么:一个基于 Protobuf 的极简 RPC 框架
Twirp 的核心思路可以用一句话概括:你定义服务,框架生成通信代码,你只写业务逻辑。与 gRPC 相比,Twirp 强调"简单与极简"(simplicity and minimalism):它没有自定义的 HTTP 服务器与传输实现,而是直接运行在 Go 标准库经过充分测试且高性能的 net/http Server 之上(见 README.md)。这意味着:
- 它可以运行在 HTTP 1.1 上(不只是 HTTP/2);
- 同时支持 JSON 序列化,便于调试;
- 自动生成强类型客户端;
- 提供一套简单、规范的错误传递机制。
从仓库结构看,这个仓库同时包含三部分能力:运行时库(根目录下的 context.go、errors.go、interceptors.go、client_options.go、server_options.go 等)、代码生成器 protoc-gen-twirp,以及一套完整可运行的 example 示例。
三步走:如何创建一个 Twirp 服务
按照官方 docs/intro.md 的定义,创建一个 Twirp 服务只需要三个步骤:
- 在 Proto 文件中定义服务:声明 RPC 方法以及请求、响应的消息类型。
- 用
protoc命令生成 Go 代码:它会生成一个接口(interface)、一个客户端(client)以及一些服务端工具(server utils,用于方便地启动 HTTP 监听)。 - 实现生成的接口:把你自己的业务逻辑填进去,服务即可对外提供能力。
下面用一个 HelloWorld 服务完整走一遍这三个步骤。
HelloWorld 实战:完整代码演练
1. 编写 .proto 服务定义文件
在任意目录(例如 rpc/helloworld/)创建 service.proto,内容如下:
syntax = "proto3";
package example.com.my.package.helloworld;
option go_package = "example.com/my/package/helloworld";
service HelloWorld {
rpc Hello(HelloReq) returns (HelloResp);
}
message HelloReq {
string subject = 1;
}
message HelloResp {
string text = 1;
}
要点说明:
syntax = "proto3"声明使用 Protocol Buffers v3 语法;package声明逻辑包名,用于路由与服务完整名称的拼接;option go_package指定生成的 Go 包路径,是protoc-gen-go与protoc-gen-twirp决定导入路径的依据(参考 docs/command_line.md);service块内的每个rpc方法声明一个远程调用,message块定义消息结构。
2. 用 protoc 生成代码与生成的接口
运行 protoc 编译器,同时指定 --go_out 和 --twirp_out 两个插件输出,就会在 proto 文件同目录下生成 .pb.go(由 protoc-gen-go 生成,包含消息类型)和 .twirp.go(由 protoc-gen-twirp 生成,包含服务代码)两个文件:
protoc --go_out=. --twirp_out=. rpc/helloworld/service.proto
Twirp 生成的 .twirp.go 文件中包含如下接口定义:
type HelloWorld interface {
Hello(context.Context, *HelloReq) (*HelloResp, error)
}
接口方法的签名规律是固定的:方法名(context.Context, *请求消息) (*响应消息, error)。这一点可以在仓库示例 example/service.twirp.go 中得到验证——Haberdasher 服务生成的接口正是:
type Haberdasher interface {
// MakeHat produces a hat of mysterious, randomly-selected color!
MakeHat(context.Context, *Size) (*Hat, error)
}
3. 实现服务端接口(业务逻辑)
接下来编写实现该接口的 struct,这就是你唯一需要手写的"业务逻辑"部分:
package main
import (
"context"
"net/http"
pb "github.com/twitchtv/twirp-example/rpc/helloworld"
)
type HelloWorldServer struct{}
func (s *HelloWorldServer) Hello(ctx context.Context, req *pb.HelloReq) (*pb.HelloResp, error) {
return &pb.HelloResp{Text: "Hello " + req.Subject}, nil
}
// Run the implementation in a local server
func main() {
twirpHandler := pb.NewHelloWorldServer(&HelloWorldServer{})
// You can use any mux you like - NewHelloWorldServer gives you an http.Handler.
mux := http.NewServeMux()
// The generated code includes a method, PathPrefix(), which
// can be used to mount your service on a mux.
mux.Handle(twirpHandler.PathPrefix(), twirpHandler)
http.ListenAndServe(":8080", mux)
}
代码中有两个值得注意的生成能力:
NewHelloWorldServer(&HelloWorldServer{}):生成的服务器构造函数,把接口实现包装成一个TwirpServer。在仓库当前版本(生成器 v8.1.3,见 example/service.twirp.go 头部注释)中,签名是NewHaberdasherServer(svc Haberdasher, opts ...interface{}) TwirpServer(见 example/service.twirp.go),它返回的TwirpServer本质上就是一个http.Handler;twirpHandler.PathPrefix():返回该服务的路由前缀,形如/twirp/<package>.<Service>/(见 example/service.twirp.go),可以直接用于在任意 mux 上挂载服务。仓库示例 example/cmd/server/main.go 甚至直接把它传给http.ListenAndServe(":8080", server)使用。
4. 用生成的客户端发起远程调用
服务端跑起来之后,客户端只需要一行构造函数加一次方法调用:
package main
import (
"context"
"fmt"
"net/http"
pb "github.com/twitchtv/twirp-example/rpc/helloworld"
)
func main() {
client := pb.NewHelloWorldProtobufClient("http://localhost:8080", &http.Client{})
resp, err := client.Hello(context.Background(), &pb.HelloReq{Subject: "World"})
if err == nil {
fmt.Println(resp.Text) // prints "Hello World"
}
}
运行后会在终端输出 Hello World。至此,一个完整的"定义 → 生成 → 实现 → 运行 → 调用"闭环就完成了。
生成代码的内部结构(源码级解读)
为了深入理解 Twirp,可以打开仓库中已生成的 example/service.twirp.go 观察其内部构成。该文件(1100+ 行)由 protoc-gen-twirp v8.1.3 生成,主要包含以下几部分:
(1)服务接口:每个 service 对应一个 Go interface(见 example/service.twirp.go)。
(2)两类客户端:每个服务生成两个客户端构造函数——
New{{Service}}ProtobufClient:使用application/protobuf序列化通信;New{{Service}}JSONClient:使用application/json序列化通信。
两者都实现同一个接口,可以互换。客户端构造函数接受 baseURL、HTTPClient 和可选的 twirp.ClientOption;如果传入的是 *http.Client,生成代码会自动禁用重定向跟随(withoutRedirects),避免 3xx 重定向把 POST 变成 GET 造成诡异错误(见 example/service.twirp.go)。客户端在发起请求时会自动附带 Accept、Content-Type 和 Twirp-Version 头(见 example/service.twirp.go)。
(3)服务端 Handler:New{{Service}}Server 包装你的接口实现,返回 TwirpServer。TwirpServer 接口(见 example/service.twirp.go)除了内嵌 http.Handler 之外,还提供三个低层元数据方法:
ServiceDescriptor():返回压缩后的.proto文件描述符,可用于反射工具;ProtocGenTwirpVersion():返回生成该文件所用的 twirp 版本;PathPrefix():返回 HTTP URL 路径前缀,形如/twirp/<package>.<Service>/。
(4)版本兼容断言:生成的代码顶部会引用运行时库中的版本常量,例如 const _ = twirp.TwirpPackageMinVersion_8_1_0。该常量定义在 version_constant.go,如果生成代码的版本与运行时库不匹配,会在编译期直接报错,防止"代码生成器升级而运行库未升级"的错配问题。
(5)服务端路径前缀默认值:生成的服务端与客户端默认使用 /twirp 作为路由前缀(见 example/service.twirp.go),同时支持通过 twirp.WithServerPathPrefix 等服务端选项自定义。
为什么选择 Twirp:设计带来的收益
原文档 docs/intro.md 给出了选择 Twirp 的核心理由,结合 docs/routing.md 可归纳如下:
- 路由与序列化由框架统一处理,降低引入 bug 的风险:HTTP 方法与路径拼接、请求反序列化、响应序列化全部由生成代码完成,业务代码中不再出现散落的 JSON/HTTP 处理逻辑;
- JSON 与 Protobuf 双序列化支持:调试期可用 JSON(尤其配合 cURL),生产环境建议使用 Protobuf;
- Protobuf 天生支持向后兼容的演进:与 JSON 不同,重命名字段对 Protobuf 而言是平凡操作(字段以数字编号标识),不会破坏已有客户端;
- Protobuf 序列化性能优秀;
.proto文件本身就是良好的服务文档:服务与消息的注释会原样进入生成代码(对比 example/service.proto 中的注释与 example/service.twirp.go 中的接口注释)。
安装与代码生成:从零搭建环境
详见 docs/install.md,这里给出完整流程。
前置条件
- Go:Twirp 与当前三个最新大版本 Go 均兼容;
protoc编译器(v3 及以上):Protocol Buffers 官方编译器;- 两个 protoc 插件:
protoc-gen-twirp(本仓库的生成器)与protoc-gen-go(消息类型生成器)。
用 tools.go 在 go.mod 中固化工具版本
推荐像管理其他 Go 工具一样,在 tools.go 中引入这两个生成器,以便用 go.mod 锁定版本:
// +build tools
package tools
import (
_ "google.golang.org/protobuf/cmd/protoc-gen-go"
_ "github.com/twitchtv/twirp/protoc-gen-twirp"
)
安装生成器
设置 GOBIN 指定安装目录(例如项目下的 bin/),并把它加入 PATH 以便 protoc 能找到插件:
export GOBIN=$PWD/bin
export PATH=$GOBIN:$PATH
然后安装两个生成器:
go install github.com/twitchtv/twirp/protoc-gen-twirp@latest
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
老版本注意:如果你的代码由 Twirp v5、v7 生成,需要的是 Protobuf APIv1(github.com/golang/protobuf)而非 APIv2(google.golang.org/protobuf),安装命令相应改为:
go get github.com/twitchtv/twirp/protoc-gen-twirp@v7.2.0
go get github.com/golang/protobuf/protoc-gen-go@1.5.2
对应关系可参考 docs/version_matrix.md。当前仓库的运行时库则要求 TwirpPackageMinVersion_8_1_0(见 version_constant.go)。
生成代码的标准调用
以 rpc/haberdasher/service.proto 为例,默认参数调用:
protoc --go_out=. --twirp_out=. rpc/haberdasher/service.proto
生成的 .pb.go 与 .twirp.go 会输出在与 .proto 相同的目录下。--twirp_out 支持与 --go_out 相同的参数(详见 docs/command_line.md 与 docs/install.md)。
生成器的高级参数
protoc-gen-twirp 支持以下常用参数,其解析逻辑可以在 protoc-gen-twirp/command_line.go 中看到:
-
paths=source_relative:让生成文件与.proto文件放在同一目录(默认import模式会按go_package组织目录)。实用写法:protoc --go_out=. --twirp_out=. \ --go_opt=paths=source_relative \ --twirp_opt=paths=source_relative \ rpc/haberdasher/service.proto -
module={PREFIX}:从输出文件名中去除go_package的指定前缀; -
import_prefix={PREFIX}(已弃用,但对旧版protoc-gen-go仍有用):为生成的导入路径统一加前缀; -
M{proto文件}={导入路径}与go_import_mapping@{proto文件}={导入路径}:为被导入的 proto 文件建立"proto 文件名 → Go 导入路径"的映射,适用于多包互导且不在$GOPATH/src根目录下生成代码的场景(见 docs/command_line.md 中的示例)。
参数格式为逗号分隔的 k=v 对,例如:
protoc \
--proto_path=$PROTO_SRC_PATH \
--twirp_out=M$IMPORT_MAPPING:$PROTO_SRC_PATH \
--go_out=M$IMPORT_MAPPING:$PROTO_SRC_PATH \
$PROTO_SRC_PATH/rpc/haberdasher/service.proto
路由与序列化:Twirp 的 HTTP 契约
Twirp 工作于 HTTP 1.1,所有 RPC 方法都映射到统一格式的路由上(详见 docs/routing.md):
POST [<prefix>]/[<package>.]<Service>/<Method>
其中:
<prefix>默认是/twirp,可选,可通过twirp.WithServerPathPrefix配置为其他路径(如/my/custom/prefix);<package>、<Service>、<Method>与.proto文件中的定义一一对应。
例如,对 Haberdasher 服务的 MakeHat 方法,路由是:
POST /twirp/twirp.example.haberdasher.Haberdasher/MakeHat
服务端 ServeHTTP 的处理流程(见 example/service.twirp.go)包括:校验请求方法必须是 POST、解析路径并比对 package 名与 prefix、按方法名分发到对应 serve{{Method}} 处理函数。完整协议细节见 docs/spec_v7.md。
命名规范:为最大兼容性,<Service> 与 <Method> 应遵循 Protocol Buffers 风格指南使用首字母大写的 CamelCase(如 MyMethod),否则 myMethod 与 my_method 会映射到同一个 MyMethod,在一些语言(如 Go)中造成编译期冲突。
Content-Type 头:请求必须携带 Content-Type,取值只能是 application/json 或 application/protobuf。服务端按该头选择反序列化方式(见 example/service.twirp.go)。JSON 便于用 cURL 调试,Protobuf 在其余各方面更优,生产代码建议使用 Protobuf(对比见 docs/protobuf_and_json.md)。
JSON 序列化规则:大体遵循官方 JSON 映射规范——所有字段都必须设置、不允许额外字段、null 表示"留空该字段";一个例外是字段名使用 proto 中的原始名字(而非 lowerCamelCase),这对编写自定义 JSON 客户端更可预测。
错误响应:Twirp 服务端出错时返回非 200 的 HTTP 状态码,错误体始终是 JSON(即使请求是 Protobuf 编码),包含 {code, msg, meta} 三个字段。例如请求一个不存在的路由:
POST /twirp/twirp.example.haberdasher.Haberdasher/INVALIDROUTE
404 Not Found
{
"code": "bad_route",
"msg": "no handler for path /twirp/twirp.example.haberdasher.Haberdasher/INVALIDROUTE",
"meta": {"twirp_invalid_route": "POST /twirp/twirp.example.haberdasher.Haberdasher/INVALIDROUTE"}
}
客户端收到非 200 响应时,会优先尝试解析上述 JSON 错误体,解析失败则把 HTTP 状态码映射为相近的 Twirp 错误码(例如 404 → bad_route、401 → unauthenticated、403 → permission_denied、429 → resource_exhausted、502/503/504 → unavailable),并附带 http_error_from_intermediary 元数据便于排查(见 example/service.twirp.go)。
进一步阅读
本仓库还提供了与本文配套的进阶文档,可直接在本仓库中继续深入:
- docs/install.md:完整的安装与升级 Twirp 工具链说明;
- docs/example.md:构建经典 Haberdasher 服务的逐步实战(含可运行的 example 与 服务端实现);
- docs/routing.md:路由与序列化的底层细节;
- docs/command_line.md:
protoc生成器参数详解; - docs/errors.md:Twirp 错误模型与最佳实践;
- docs/version_matrix.md:Twirp 与 Protobuf 各版本的兼容矩阵。