Twirp（Twitch RPC）是一个轻量级RPC框架，它的核心思想是把Protobuf定义的服务转换为普通HTTP接口。与gRPC强制使用HTTP/2不同，Twirp可以在标准HTTP/1.1环境下工作，这让它在现有网关、负载均衡和浏览器环境中更容易落地。Twirp保留了Protobuf的强类型契约，同时把编码格式简化为JSON和Protobuf二进制两种选项，开发者可以用curl或者浏览器直接调试接口，不需要额外的调试工具。
Twirp的通信模型与路由规则
Twirp的路由规则非常固定，每个RPC方法都会自动映射到一个HTTP路径，格式为/twirp/包名.服务名/方法名。请求方法只接受POST，请求体根据Content-Type头部的不同，可以是JSON格式或者Protobuf二进制格式。响应同样遵循这一规则：客户端发送JSON就返回JSON，发送Protobuf二进制就返回Protobuf二进制。这种设计让Twirp既保留了RPC的语义，又不需要像gRPC那样依赖HTTP/2的流式特性。
对于跨语言调用场景，JSON模式非常实用。前端浏览器、移动端或者脚本语言无需安装Protobuf运行时，直接发送普通JSON对象就能调用服务。而在后端服务之间，切换到Protobuf二进制可以显著降低序列化开销和网络传输体积。Twirp本身不强制使用TLS，但在生产环境中建议配合HTTPS使用，因为请求体可能包含敏感数据。
syntax = "proto3";
package twirp.example.haberdasher;
option go_package = "github.com/yourorg/twirp-example/rpc/haberdasher";
service Haberdasher {
rpc MakeHat(Size) returns (Hat);
}
message Size {
int32 inches = 1;
}
message Hat {
int32 inches = 1;
string color = 2;
string name = 3;
}
上面的proto文件定义了一个简单的帽子制作服务，包含一个MakeHat方法。编译后，这个服务会生成一个HTTP路由，完整路径为/twirp/twirp.example.haberdasher.Haberdasher/MakeHat。Twirp的路径前缀/twirp可以通过中间件修改，但默认值已经足够大多数项目使用。需要注意的是，路径中的包名和Proto包名一致，其中点号会保留，这就避免了不同命名空间下的方法冲突。
从Protobuf定义到代码生成
要生成Twirp代码，首先需要安装protoc编译器和Twirp插件。安装命令如下，假设已经安装Go工具链：
go install github.com/twitchtv/twirp/protoc-gen-twirp@latest export PATH=$PATH:$(go env GOPATH)/bin protoc --twirp_out=. --go_out=. rpc/haberdasher/service.proto
执行完成后，目录下会生成两个文件：service.pb.go包含Protobuf消息结构，service.twirp.go包含Twirp服务端接口和客户端构造函数。生成的服务端接口定义大致如下：
type Haberdasher interface {
MakeHat(context.Context, *Size) (*Hat, error)
}
任何实现了这个接口的类型都可以注册为Twirp服务。生成代码还提供了NewHaberdasherServer函数，它接受实现接口的对象并返回一个http.Handler，可以直接挂载到标准库的http.ServeMux或者任何兼容的HTTP路由上。客户端部分则会生成两种构造函数：NewHaberdasherProtobufClient用于二进制通信，NewHaberdasherJSONClient用于JSON通信。两者都基于同一个RPC路径，只是默认的Content-Type不同。
代码生成阶段还可以通过proto文件中的option控制Go包路径。如果团队使用多个Proto包，建议在go_package中使用完整的模块路径，避免生成代码的导入冲突。同时，生成后的.twirp.go文件应该提交到版本库，这样不参与代码生成的消费者也能直接使用客户端。
实现服务端与客户端
服务端实现非常简单，只需要实现生成接口中定义的方法。业务逻辑可以直接写在方法体内，错误通过返回twirp.Error来传递给客户端。下面是一个完整的服务端示例：
package main
import (
"context"
"net/http"
"github.com/twitchtv/twirp"
"github.com/yourorg/twirp-example/rpc/haberdasher"
)
type hatServer struct{}
func (s *hatServer) MakeHat(ctx context.Context, size *haberdasher.Size) (*haberdasher.Hat, error) {
if size.Inches <= 0 {
return nil, twirp.InvalidArgumentError("Inches", "must be a positive number")
}
return &haberdasher.Hat{
Inches: size.Inches,
Color: "red",
Name: "fedora",
}, nil
}
func main() {
server := &hatServer{}
twirpHandler := haberdasher.NewHaberdasherServer(server)
http.Handle(haberdasher.HaberdasherPathPrefix, twirpHandler)
http.ListenAndServe(":8080", nil)
}
客户端调用时，默认使用Protobuf二进制编码。如果希望使用JSON编码，则调用JSON客户端构造函数即可。Twirp客户端都实现了相同的接口，因此可以在二进制和JSON之间平滑切换，而不需要修改业务逻辑。下面展示两种客户端的调用方式：
// Protobuf 客户端
client := haberdasher.NewHaberdasherProtobufClient("http://localhost:8080", &http.Client{})
hat, err := client.MakeHat(context.Background(), &haberdasher.Size{Inches: 22})
if err != nil {
// 处理错误
}
// JSON 客户端
jsonClient := haberdasher.NewHaberdasherJSONClient("http://localhost:8080", &http.Client{})
hat, err = jsonClient.MakeHat(context.Background(), &haberdasher.Size{Inches: 23})
Twirp还支持通过WithHooks给客户端或服务端添加拦截器，用于日志记录、鉴权、指标采集等横切关注点。例如可以在每次请求前打印路径，在请求后记录耗时。这些钩子函数接收context.Context和req信息，返回新的上下文或错误，可以灵活控制请求流程。
错误处理与生产化建议
Twirp的错误模型比裸HTTP状态码更结构化。服务端返回的任何非nil错误都会被包装成统一的JSON响应，包含code、msg和可选的meta字段。错误码沿用gRPC的语义，例如invalid_argument、not_found、unauthenticated、internal等。客户端可以根据错误码做精确的恢复逻辑，而不是解析HTTP状态码或者字符串消息。
if err != nil {
twerr, ok := err.(twirp.Error)
if ok && twerr.Code() == twirp.NotFound {
// 资源不存在
}
}
生产环境中，Twirp服务应该和标准HTTP服务一样做好超时控制、请求大小限制和访问日志。由于Twirp的路由固定，可以很容易地在反向代理层配置路径前缀的限流和鉴权。例如只暴露/twirp/前缀给内部服务，对公网只开放经过认证的JSON网关。TLS可以使用标准HTTPS，不需要像gRPC那样依赖特定证书配置。
另一个容易忽略的点是，Twirp默认没有内建重试和负载均衡策略。在微服务架构中，建议在客户端封装一层重试逻辑，或者使用Service Mesh来统一处理服务发现和熔断。Twirp的轻量特性使得它非常适合作为内部RPC框架，尤其是在既有HTTP基础设施已经完善的组织中。
总之，Twirp在类型安全和部署简单之间取得了很好的平衡。通过Protobuf定义服务契约，自动生成服务端和客户端，配合JSON调试与二进制高效传输，它适合快速构建可维护的API服务。开发团队只需关注业务逻辑实现，剩下的路由、编解码和错误传播都由框架统一处理。