Go 每日一库之 twirp
简介
twirp是一个基于 Google Protobuf 的 RPC 框架。twirp
通过在.proto
文件中定义服务,然后自动生产服务器和客户端的代码。让我们可以将更多的精力放在业务逻辑上。咦?这不就是 gRPC 吗?不同的是,gRPC 自己实现了一套 HTTP 服务器和网络传输层,twirp 使用标准库net/http
。另外 gRPC 只支持 HTTP/2 协议,twirp 还可以运行在 HTTP 1.1 之上。同时 twirp 还可以使用 JSON 格式交互。当然并不是说 twirp 比 gRPC 好,只是多了解一种框架也就多了一个选择?
快速使用
首先需要安装 twirp 的代码生成插件:
$ go get github.com/twitchtv/twirp/protoc-gen-twirp
上面命令会在GOPATH/bin目录下生成可执行程序protoc-gen-twirp。我的习惯是将GOPATH/bin放到 PATH 中,所以可在任何地方执行该命令。
接下来安装 protobuf 编译器,直接到 GitHub 上https://github.com/protocolbuffers/protobuf/releases下载编译好的二进制程序放到 PATH 目录即可。
最后是 Go 语言的 protobuf 生成插件:
$ go get github.com/golang/protobuf/protoc-gen-go
同样地,命令protoc-gen-go
会安装到$GOPATH/bin
目录中。
本文代码采用Go Modules。先创建目录,然后初始化:
$ mkdir twirp && cd twirp
$ go mod init github.com/darjun/go-daily-lib/twirp
接下来,我们开始代码编写。先编写.proto
文件:
syntax = "proto3";
option go_package = "proto";
service Echo {
rpc Say(Request) returns (Response);
}
message Request {
string text = 1;
}
message Response {
string text = 2;
}
我们定义一个service
实现echo功能,即发送什么就返回什么。切换到echo.proto
所在目录,使用protoc
命令生成代码:
$ protoc --twirp_out=. --go_out=. ./echo.proto
上面命令会生成echo.pb.go
和echo.twirp.go
两个文件。前一个是 Go Protobuf 文件,后一个文件中包含了twirp
的服务器和客户端代码。
然后我们就可以编写服务器和客户端程序了。服务器:
package main
import (
"context"
"net/http"
"github.com/darjun/go-daily-lib/twirp/get-started/proto"
)
type Server struct{}
func (s *Server) Say(ctx context.Context, request *proto.Request) (*proto.Response, error) {
return &proto.Response{Text: request.GetText()}, nil
}
func main() {
server := &Server{}
twirpHandler := proto.NewEchoServer(server, nil)
http.ListenAndServe(":8080", twirpHandler)
}
使用自动生成的代码,我们只需要 3 步即可完成一个 RPC 服务器:
- 定义一个结构,可以存储一些状态。让它实现我们定义的
service
接口; - 创建一个该结构的对象,调用生成的
New{{ServiceName}}Server
方法创建net/http
需要的处理器,这里的ServiceName
为我们的服务名; - 监听端口。
客户端:
package main
import (
"context"
"fmt"
"log"
"net/http"
"github.com/darjun/go-daily-lib/twirp/get-started/proto"
)
func main() {
client := proto.NewEchoProtobufClient("http://localhost:8080", &http.Client{})
response, err := client.Say(context.Background(), &proto.Request{Text: "Hello World"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("response:%sn", response.GetText())
}
twirp
也生成了客户端相关代码,直接调用NewEchoProtobufClient
连接到对应的服务器,然后调用rpc
请求。
开启两个控制台,分别运行服务器和客户端程序。服务器:
$ cd server && go run main.go
客户端:
$ cd client && go run main.go
正确返回结果:
response:Hello World
为了便于对照,下面列出该程序的目录结构。也可以去我的 GitHub 上查看示例代码:
get-started
├── client
│ └── main.go
├── proto
│ ├── echo.pb.go
│ ├── echo.proto
│ └── echo.twirp.go
└── server
└── main.go
JSON 客户端
除了使用 Protobuf,twirp
还支持 JSON 格式的请求。使用也非常简单,只需要在创建Client
时将NewEchoProtobufClient
改为NewEchoJSONClient
即可:
func main() {
client := proto.NewEchoJSONClient("http://localhost:8080", &http.Client{})
response, err := client.Say(context.Background(), &proto.Request{Text: "Hello World"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("response:%sn", response.GetText())
}
Protobuf Client 发送的请求带有Content-Type: application/protobuf
的Header
,JSON Client 则设置Content-Type
为application/json
。服务器收到请求时根据Content-Type
来区分请求类型:
// proto/echo.twirp.go
unc (s *echoServer) serveSay(ctx context.Context, resp http.ResponseWriter, req *http.Request) {
header := req.Header.Get("Content-Type")
i := strings.Index(header, ";")
if i == -1 {
i = len(header)
}
switch strings.TrimSpace(strings.ToLower(header[:i])) {
case "application/json":
s.serveSayJSON(ctx, resp, req)
case "application/protobuf":
s.serveSayProtobuf(ctx, resp, req)
default:
msg := fmt.Sprintf("unexpected Content-Type: %q", req.Header.Get("Content-Type"))
twerr := badRouteError(msg, req.Method, req.URL.Path)
s.writeError(ctx, resp, twerr)
}
}
提供其他 HTTP 服务
实际上,twirpHandler
只是一个http
的处理器,正如其他千千万万的处理器一样,没什么特殊的。我们当然可以挂载我们自己的处理器或处理器函数(概念有不清楚的可以参见我的《Go Web 编程》系列文章:
type Server struct{}
func (s *Server) Say(ctx context.Context, request *proto.Request) (*proto.Response, error) {
return &proto.Response{Text: request.GetText()}, nil
}
func greeting(w http.ResponseWriter, r *http.Request) {
name := r.FormValue("name")
if name == "" {
name = "world"
}
w.Write([]byte("hi," + name))
}
func main() {
server := &Server{}
twirpHandler := proto.NewEchoServer(server, nil)
mux := http.NewServeMux()
mux.Handle(twirpHandler.PathPrefix(), twirpHandler)
mux.HandleFunc("/greeting", greeting)
err := http.ListenAndServe(":8080", mux)
if err != nil {
log.Fatal(err)
}
}
上面程序挂载了一个简单的/greeting
请求,可以通过浏览器来请求地址http://localhost:8080/greeting
。twirp
的请求会挂载到路径twirp/{{ServiceName}}
这个路径下,其中ServiceName
为服务名。上面程序中的PathPrefix()
会返回/twirp/Echo
。
客户端:
func main() {
client := proto.NewEchoProtobufClient("http://localhost:8080", &http.Client{})
response, _ := client.Say(context.Background(), &proto.Request{Text: "Hello World"})
fmt.Println("echo:", response.GetText())
httpResp, _ := http.Get("http://localhost:8080/greeting")
data, _ := ioutil.ReadAll(httpResp.Body)
httpResp.Body.Close()
fmt.Println("greeting:", string(data))
httpResp, _ = http.Get("http://localhost:8080/greeting?name=dj")
data, _ = ioutil.ReadAll(httpResp.Body)
httpResp.Body.Close()
fmt.Println("greeting:", string(data))
}
先运行服务器,然后执行客户端程序:
$ go run main.go
echo: Hello World
greeting: hi,world
greeting: hi,dj
发送自定义的 Header
默认情况下,twirp
实现会发送一些 Header。例如上面介绍的,使用Content-Type
辨别客户端使用的协议格式。有时候我们可能需要发送一些自定义的 Header,例如token
。twirp
提供了WithHTTPRequestHeaders
方法实现这个功能,该方法返回一个context.Context
。发送时会将保存在该对象中的 Header 一并发送。类似地,服务器使用WithHTTPResponseHeaders
发送自定义 Header。
由于twirp
封装了net/http
,导致外层拿不到原始的http.Request
和http.Response
对象,所以 Header 的读取有点麻烦。在服务器端,NewEchoServer
返回的是一个http.Handler
,我们加一层中间件读取http.Request
。看下面代码:
type Server struct{}
func (s *Server) Say(ctx context.Context, request *proto.Request) (*proto.Response, error) {
token := ctx.Value("token").(string)
fmt.Println("token:", token)
err := twirp.SetHTTPResponseHeader(ctx, "Token-Lifecycle", "60")
if err != nil {
return nil, twirp.InternalErrorWith(err)
}
return &proto.Response{Text: request.GetText()}, nil
}
func WithTwirpToken(h http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
token := r.Header.Get("Twirp-Token")
ctx = context.WithValue(ctx, "token", token)
r = r.WithContext(ctx)
h.ServeHTTP(w, r)
})
}
func main() {
server := &Server{}
twirpHandler := proto.NewEchoServer(server, nil)
wrapped := WithTwirpToken(twirpHandler)
http.ListenAndServe(":8080", wrapped)
}
上面程序给客户端返回了一个名为Token-Lifecycle
的 Header。客户端代码:
func main() {
client := proto.NewEchoProtobufClient("http://localhost:8080", &http.Client{})
header := make(http.Header)
header.Set("Twirp-Token", "test-twirp-token")
ctx := context.Background()
ctx, err := twirp.WithHTTPRequestHeaders(ctx, header)
if err != nil {
log.Fatalf("twirp error setting headers: %v", err)
}
response, err := client.Say(ctx, &proto.Request{Text: "Hello World"})
if err != nil {
log.Fatalf("call say failed: %v", err)
}
fmt.Printf("response:%sn", response.GetText())
}
运行程序,服务器正确获取客户端传过来的 token。
请求路由
我们前面已经介绍过了,twirp
的Server
实际上也就是一个http.Handler
,如果我们知道了它的挂载路径,完全可以通过浏览器或者curl
之类的工具去请求。我们启动get-started
的服务器,然后用curl
命令行工具去请求:
$ curl --request "POST"
--location "http://localhost:8080/twirp/Echo/Say"
--header "Content-Type:application/json"
--data '{"text":"hello world"}'
--verbose
{"text":"hello world"}
这在调试的时候非常有用。
总结
本文介绍了 Go 的一个基于 Protobuf 生成代码的 RPC 框架,非常简单,小巧,实用。twirp
对许多常用的编程语言都提供了支持。可以作为 gRPC 等的备选方案考虑。
大家如果发现好玩、好用的 Go 语言库,欢迎到 Go 每日一库 GitHub 上提交 issue?
参考
- twirp GitHub:https://github.com/twitchtv/twirp
- twirp 官方文档:https://twitchtv.github.io/twirp/docs/intro.html
- Go 每日一库 GitHub:https://github.com/darjun/go-daily-lib
- JavaScript 教程
- JavaScript 编辑工具
- JavaScript 与HTML
- JavaScript 与Java
- JavaScript 数据结构
- JavaScript 基本数据类型
- JavaScript 特殊数据类型
- JavaScript 运算符
- JavaScript typeof 运算符
- JavaScript 表达式
- JavaScript 类型转换
- JavaScript 基本语法
- JavaScript 注释
- Javascript 基本处理流程
- Javascript 选择结构
- Javascript if 语句
- Javascript if 语句的嵌套
- Javascript switch 语句
- Javascript 循环结构
- Javascript 循环结构实例
- Javascript 跳转语句
- Javascript 控制语句总结
- Javascript 函数介绍
- Javascript 函数的定义
- Javascript 函数调用
- Javascript 几种特殊的函数
- JavaScript 内置函数简介
- Javascript eval() 函数
- Javascript isFinite() 函数
- Javascript isNaN() 函数
- parseInt() 与 parseFloat()
- escape() 与 unescape()
- Javascript 字符串介绍
- Javascript length属性
- javascript 字符串函数
- Javascript 日期对象简介
- Javascript 日期对象用途
- Date 对象属性和方法
- Javascript 数组是什么
- Javascript 创建数组
- Javascript 数组赋值与取值
- Javascript 数组属性和方法
- 打卡群2刷题总结1007——反转链表
- 打卡群2刷题总结1001——两数之和 II - 输入有序数组
- 复杂一点的SQL语句
- PL/SQL Developer连接本地Oracle 11g 64位数据库
- 打卡群刷题总结1007——买卖股票的最佳时机 II
- 事务Transaction
- 打卡群2刷题总结1006—— 删除链表的倒数第N个节点
- 打卡群刷题总结1006——跳跃游戏 II
- 面试官常问的Spring依赖注入和Bean的装配问题,今天给大家讲清楚!
- 打卡群刷题总结1003——分割等和子集
- 打卡群2刷题总结1005——有效的括号
- 腾讯云服务器操作系统TencentOS安装与体验
- 打卡群2刷题总结1004——无重复字符的最长子串
- 如何恢复故障KVM虚拟机qcow2磁盘镜像文件LVM分区中的数据
- 8000字 | 32 张图 | 一文搞懂事务+隔离级别+阻塞+死锁