Twirp 实战指南:从 Protobuf 定义到运行 Haberdasher 服务与客户端

原创2026-09-27 13:20:251,911 阅读
文章标签:RPC框架后端微服务

Twirp 实战指南:从 Protobuf 定义到运行 Haberdasher 服务与客户端

Twirp 是一个强调简洁与极简的服务间通信框架:它从 Protobuf API 定义文件自动生成路由与序列化代码,让开发者专注业务逻辑,而无需操心 HTTP 方法与路径细节。本文以官方示例文档(docs/example.md)为主体,完整演示如何用 5 个步骤从零构建一个经典的 Haberdasher(制帽匠)服务:编写 .proto 定义、用 protoc 生成代码、实现服务端接口、挂载 HTTP 服务、调用自动生成的强类型客户端。读完本文,你将掌握 Twirp 服务的完整开发闭环,并能对照仓库内可运行的 example 实例加深理解。

快速总览:5 步构建一个 Twirp 服务

Haberdasher 服务只提供一个 RPC 方法 MakeHat:给定帽子尺寸(英寸),返回一顶随机颜色的新帽子。整个流程分 5 步:

  1. 编写 Protobuf 服务定义(.proto 文件)
  2. 用 protoc 生成 Go 代码(.pb.go 与 .twirp.go)
  3. 实现服务端接口(业务逻辑)
  4. 挂载并运行 HTTP 服务
  5. 使用自动生成的客户端调用

最终效果:跑起一个带强类型客户端的 Haberdasher 服务。仓库 example 目录下已有一个完整可运行的对应实现(cmd/server 与 cmd/client 两个可执行程序),可以边读边对照。

动手前请先确认环境就绪:参照 docs/install.md 安装 protoc、protoc-gen-go 与 protoc-gen-twirp。

第 1 步:编写 Protobuf 服务定义

在 rpc/haberdasher/service.proto 中编写 proto3 定义:

syntax = "proto3";

package twirp.example.haberdasher;
option go_package = "github.com/example/rpc/haberdasher";

// Haberdasher service makes hats for clients.
service Haberdasher {
  // MakeHat produces a hat of mysterious, randomly-selected color!
  rpc MakeHat(Size) returns (Hat);
}

// Size of a Hat, in inches.
message Size {
  int32 inches = 1; // must be > 0
}

// A Hat is a piece of headwear made by a Haberdasher.
message Hat {
  int32 inches = 1;
  string color = 2; // anything but "invisible"
  string name = 3; // i.e. "bowler"
}

几点建议与说明:

  • 文件即文档:为 .proto 文件补充注释非常值得,这些文件可以作为 API 的首要文档。注释还会原样出现在生成的 Go 类型上——打开 example/service.twirp.go 可以看到,// A Haberdasher makes hats for clients. 与 // MakeHat produces a hat of mysterious, randomly-selected color! 都直接透传到了生成的 Haberdasher 接口上。
  • option go_package:指定生成的 Go 代码所属的包导入路径,是生成器解析跨文件 import 的关键依据(详见 docs/command_line.md)。
  • 字段约束约定:inches 必须大于 0、颜色不能是 "invisible",这些约束在 proto 中只是注释约定,真正强制执行要靠服务端业务代码(见第 3 步的参数校验)。

仓库 example/service.proto 中的定义与文档略有差异(消息字段名为 size 而非 inches、包名为 twitch.twirp.example),但结构完全一致,可互为参考。

第 2 步:生成代码

使用 protoc 编译器,同时指定 --go_out(生成 Protobuf 消息代码)与 --twirp_out(生成 Twirp 路由与客户端代码):

$ protoc --go_out=. --twirp_out=. \
   --go_opt=paths=source_relative \
   --twirp_opt=paths=source_relative \
   rpc/haberdasher/service.proto

生成的文件会落在 .proto 文件同目录下:

/rpc
  /haberdasher
    service.proto
    service.pb.go     # generated by protoc-gen-go
    service.twirp.go  # generated by protoc-gen-twirp

关于生成参数的补充说明:

  • paths=source_relative 让生成文件与 .proto 源文件保持相对路径关系;仓库 example/gen.go 中的 go:generate 指令正是这样写的:protoc --go_out=paths=source_relative:. --twirp_out=paths=source_relative:. service.proto。
  • --twirp_out 与 --go_out 支持相同的参数体系,包括 import_prefix 导入前缀和 M 导入映射(用于多 proto 文件跨包 import 时的路径替换),详细说明见 docs/command_line.md。

打开生成的 .twirp.go 文件,会看到类似这样的 Go 接口:

// A Haberdasher makes hats for clients.
type Haberdasher interface {
    // MakeHat produces a hat of mysterious, randomly-selected color!
    MakeHat(context.Context, *Size) (*Hat, error)
}

此外生成文件还包含实例化客户端与服务端的代码。从 example/service.twirp.go 的源码可以看到生成物的完整结构:

  • 客户端实现:haberdasherProtobufClient 与 haberdasherJSONClient 两个结构体,分别通过 doProtobufRequest / doJSONRequest 发起请求;
  • 服务端处理器:haberdasherServer 结构体实现了 ServeHTTP,负责请求解析、路由匹配与方法分发(example/service.twirp.go);
  • 版本断言:文件开头有 const _ = twirp.TwirpPackageMinVersion_8_1_0,用于校验生成的代码与运行时库版本兼容(详见 docs/version_matrix.md)。

第 3 步:实现服务端

现在编写满足 Haberdasher 接口的业务代码,也就是处理请求的“后端逻辑”。实现可以放在 internal/haberdasherserver/server.go:

package haberdasherserver

import (
    "context"
    "math/rand"

    "github.com/twitchtv/twirp"
    pb "github.com/example/rpc/haberdasher"
)

// Server implements the Haberdasher service
type Server struct {}

func (s *Server) MakeHat(ctx context.Context, size *pb.Size) (hat *pb.Hat, err error) {
    if size.Inches <= 0 {
        return nil, twirp.InvalidArgumentError("inches", "I can't make a hat that small!")
    }
    return &pb.Hat{
        Inches:  size.Inches,
        Color: []string{"white", "black", "brown", "red", "blue"}[rand.Intn(5)],
        Name:  []string{"bowler", "baseball cap", "top hat", "derby"}[rand.Intn(4)],
    }, nil
}

这里的实现要点:

  • 接口实现即业务层:Twirp 的哲学是服务端只需实现生成接口,序列化、路由、错误包装全部由生成的处理器代劳。仓库 example/cmd/server/main.go 中的 randomHaberdasher 是同一模式的真实实现。
  • 参数校验与错误返回:当 Inches <= 0 时返回 twirp.InvalidArgumentError("inches", "I can't make a hat that small!")。查看 errors.go 的源码可知,该构造函数会创建 InvalidArgument 类型的错误,并把参数名写入错误元数据(meta "argument"),方便客户端定位是哪个参数校验失败。
  • 随机选择:rand.Intn 从预置的颜色/款式列表中随机挑选,正好呼应 proto 注释里“神秘随机颜色”的设定。

第 4 步:挂载并运行服务

要基于 HTTP 提供 Haberdasher 服务,使用生成的 New{{Service}}Server 构造函数。对 Haberdasher 而言,其签名是:

func NewHaberdasherServer(svc Haberdasher, opts ...interface{}) TwirpServer

这个构造函数把你的接口实现包装成一个 TwirpServer——它本质是一个带额外能力的 http.Handler。因此可以像挂载任何 HTTP handler 一样把它挂到标准库服务器上。在 cmd/server/main.go 中:

package main

import (
    "net/http"

    "github.com/example/internal/haberdasherserver"
    "github.com/example/rpc/haberdasher"
)

func main() {
  server := &haberdasherserver.Server{} // implements Haberdasher interface
  twirpHandler := haberdasher.NewHaberdasherServer(server)

  http.ListenAndServe(":8080", twirpHandler)
}

运行 go run ./cmd/server/main.go,服务即监听在 localhost:8080。

底层机制与扩展点,从 example/service.twirp.go 的源码可以确认:

  • 选项机制:NewHaberdasherServer 接受 twirp.ServerOption 修饰器(如 twirp.WithServerHooks(hooks)),并通过 ReadOpt 读取 jsonSkipDefaults、jsonCamelCase、pathPrefix 等选项,其中 pathPrefix 默认值为 /twirp。路由格式为 <a href="https://link.gitcode.com/i/3b32c097f41e6a72de7ea20b03f8fba9" target="_blank"><prefix>]/<package>.<Service>/<Method>,例如 POST /twirp/twitch.twirp.example.Haberdasher/MakeHat(参考 [example/service.twirp.go 中导出的 HaberdasherPathPrefix 常量,更多路由细节见 docs/routing.md)。
  • 只用 POST:ServeHTTP 会拒绝非 POST 请求并返回 badRouteError(example/service.twirp.go),这是 Twirp 路由协议的一部分(见 docs/mux.md)。
  • 可组合的中间件生态:TwirpServer 仍是普通 http.Handler,可与其他中间件链式组合,也可通过 ServerHooks(如 example/cmd/server/main.go 里接入的 statsd.NewStatsdServerHooks)观测指标——运行仓库示例服务时,控制台会打印类似 incr twirp.MakeHat.requests、time twirp.MakeHat.response 的统计日志(见 example/cmd/server/README.md)。

第 5 步:使用客户端

客户端存根是自动生成的。每个服务有 2 个客户端构造函数:

  • New{{Service}}ProtobufClient:使用 Protobuf 编码请求。
  • New{{Service}}JSONClient:使用 JSON 编码请求。

推荐使用 ProtobufClient(Protobuf 与 JSON 的取舍对比见 docs/protobuf_and_json.md)。其他语言也可通过各自语言的 protoc 插件生成客户端(例如 --twirp_ruby_out),Twirp 社区提供了 Ruby、Python、Rust、TypeScript 等多语言实现。

要在另一个 Go 项目中调用 Haberdasher 服务,导入自动生成的客户端即可。例如在 cmd/client/main.go 中:

package main

import (
    "context"
    "net/http"
    "os"
    "fmt"
    "github.com/example/rpc/haberdasher"
)

func main() {
    client := haberdasher.NewHaberdasherProtobufClient("http://localhost:8080", &http.Client{})

    hat, err := client.MakeHat(context.Background(), &haberdasher.Size{Inches: 12})
    if err != nil {
        fmt.Printf("oh no: %v", err)
        os.Exit(1)
    }
    fmt.Printf("I have a nice new hat: %+v", hat)
}

在另一个终端保持服务运行,然后执行 go run ./cmd/client/main.go,就能拿到一顶新帽子。

客户端内部的实现细节,可以从生成的源码中进一步印证:

  • URL 拼接:客户端构造时按 <baseURL><a href="https://link.gitcode.com/i/dbc2fb17d89e225453a97dfe673d388d" target="_blank"><prefix>]/<package>.<Service>/<Method> 拼接每个方法的 URL([example/service.twirp.go),默认前缀同样是 /twirp,并可通过 ClientOption 调整 pathPrefix、literalURLs 等选项。
  • 上下文标注:每个 RPC 调用都会通过 ctxsetters.WithPackageName / WithServiceName / WithMethodName 把服务与方法信息注入 context(example/service.twirp.go),供拦截器与 hooks 使用(见 ctxsetters/ctxsetters.go)。
  • 拦截器支持:客户端支持 twirp.ChainInterceptors 链式拦截器,在每次调用前后插入横切逻辑(example/service.twirp.go)。
  • 错误处理:非 2xx 响应会被转换为 twirp.Error 返回;仓库 example/cmd/client/main.go 演示了利用 twerr.Meta("retryable") 判断错误是否可重试、从而自动重试的用法。

小结与延伸阅读

至此,你已经走完了 Twirp 的完整开发闭环:写 proto → 生成代码 → 实现接口 → 挂载 HTTP → 调用客户端。核心体验是:路由、序列化、错误协议等“样板胶水”全部由代码生成器产出,你只需要专注 MakeHat 这样的业务方法本身。

如果希望进一步深入,仓库中的相关文档与源码值得继续探索:

登录后查看全文
twirp