字节开源WEB框架Hertz太香啦！
发布时间：2024-01-12 19:30
![\"\"](\"https://img-blog.csdnimg.cn/1c59b327a24b4e568d3b76e0752b7003.png\")
Hertz[həːts] 是一个 Golang 微服务 HTTP 框架，在设计之初参考了其他开源框架 fasthttp、gin、echo 的优势， 并结合字节跳动内部的需求，使其具有高易用性、高性能、高扩展性等特点，目前在字节跳动内部已广泛使用。 如今越来越多的微服务选择使用 Golang，如果对微服务性能有要求，又希望框架能够充分满足内部的可定制化需求，Hertz 会是一个不错的选择。
安装Hertz命令行工具
请确保您的Go版本在1.15及以上版本，笔者用的版本是1.18 配置好GO的环境后，按照Hertz的命名行工具
go install github.com/cloudwego/hertz/cmd/hz@latest
复制代码验证Hertz工具是否安装成功，执行下面指令
hz -v
复制代码对应的输出hertz命令行工具版本
hz version v0.2.0
复制代码新建一个Hertz项目
- 进入到
$GOPATH下面，新建src文件夹,创建hertz_demo作为项目的根目录
cd $GOPATH
mkdir src
cd src
mkdir hertz_demo
cd hertz_demo
复制代码执行hz new初始化项目，项目初始化后，hertz会自动创建对应项目文件，文件结构如下
.
├── biz
│ ├── handler
│ │ └── ping.go
│ └── router
│ └── register.go
├── go.mod
├── main.go
├── router.go
└── router_gen.go
复制代码运行Hertz项目
- 执行
go mod tidy整理项目
启动hertz 控制台输出如下：
2022[/07/24]() 23:08:10.114348 engine.go:524: [Debug] HERTZ: Method=GET absolutePath=[/ping]() --> handlerName=hertz_demo[/biz/handler.Ping]() (num=2 handlers)
2022[/07/24]() 23:08:10.115227 transport.go:91: [Info] HERTZ: HTTP server listening on address=[::]:8888
复制代码此时访问localhost:8888/ping服务器返回
{"message":"pong"}
复制代码Hertz获取请求参数
Query参数
通过c.Query获取路径参数
func Person(ctx context.Context, c *app.RequestContext) {
name := c.Query("name")
c.JSON(200, utils.H{
"data": name,
})
}
复制代码curl http://localhost:8888/person?name=erik
复制代码输出：
{"data":"erik"}
复制代码路径参数
通过c.Param获取路径参数
func HelloPerson(ctx context.Context, c *app.RequestContext) {
name := c.Query("name")
age := c.Param("age")
c.JSON(200, utils.H{
"age": age,
"name": name,
})
}
复制代码路由注册
r.GET("/person/:age", hello.HelloPerson)
复制代码请求：
curl http://localhost:8888/hello/person/12?name=erik
复制代码{
"age": "12",
"name": "erik"
}
复制代码获取请求Body
func PersonInfo(ctx context.Context, c *app.RequestContext) {
type Person struct {
Age int `json:"age"`
Name string `json:"name"`
}
body, err := c.Body()
if err != nil {
panic(err)
}
var p Person
if err := json.Unmarshal(body, &p); err != nil {
panic(err)
}
c.JSON(200, utils.H{
"person": p,
})
}
复制代码curl
curl --location --request POST 'localhost:8888/person_info' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"age":12,
"name":"erik"
}'
复制代码{
"person": {
"age": 12,
"name": "erik"
}
}
复制代码表单参数
func PersonForm(ctx context.Context, c *app.RequestContext) {
age, _ := c.GetPostForm("age")
name, _ := c.GetPostForm("name")
c.JSON(200, utils.H{
"age": age,
"name": name,
})
}
复制代码curl --location --request POST 'localhost:8888/person_form' \\
--form 'name="erik"' \\
--form 'age="12"'
复制代码{
"age": "12",
"name": "erik"
}
复制代码文件上传&文件下载
func PersonUpload(ctx context.Context, c *app.RequestContext) {
fileHeader, err := c.FormFile("file")
if err != nil {
panic(err)
}
open, err := fileHeader.Open()
if err != nil {
panic(err)
}
// 读取文件到字节数组
fileRaw, err := ioutil.ReadAll(open)
if err != nil {
panic(err)
}
// 将读取到的文件写入到响应
_, err = c.Write(fileRaw)
if err != nil {
panic(err)
}
}
复制代码curl --location --request POST 'localhost:8888/person_upload' \\
--form 'file=@"/img.jpeg"'
复制代码参数绑定
代码绑定是Hertz超级赞的一部分，可以非常优雅的完成请求参数映射到结构体与请求参数的验证
此处参数绑定使用了 github.com/bytedance/g…
上面分别介绍了http中常见的参数获取api，hertz出了提供api获取参数信息，还提供了参数绑定功能，帮助我们直接将请求参数绑定到结构体上并校验参数的合法性。
func PersonBind(ctx context.Context, c *app.RequestContext) {
type person struct {
Age int `path:"age" json:"age"` // 从路径中获取参数
Name string `query:"name" json:"name"` // 从query中获取参数
City string `json:"city"` // 从body中获取参数
}
var p person
if err := c.BindAndValidate(&p); err != nil {
panic(err)
}
c.JSON(200, utils.H{
"person": p,
})
}
复制代码curl
curl --location --request POST 'http://localhost:8888/person_bind/12?name=erik' \\
--header 'Content-Type: application/json' \\
--data-raw '{
"city":"BeiJing"
}'
复制代码{
"person": {
"age": 12,
"name": "erik",
"city": "BeiJing"
}
}
复制代码中间件
中间件首尾相连最终形成一个过滤器链，用户可以在中间件中设定一些通用的处理规则，比如：统一错误处理，用户信息验证，跨域处理等 Hertz提供了两个通用的中间件，一个是JWT验证，一个是Cors跨域中间件，开箱即用,详情可以参考：www.cloudwego.io/zh/docs/her…
使用跨域中间件示例
func main() {
h := server.Default()
// CORS for https://foo.com and https://github.com origins, allowing:
// - PUT and PATCH methods
// - Origin header
// - Credentials share
// - Preflight requests cached for 12 hours
h.Use(cors.New(cors.Config{
AllowOrigins: []string{"https://foo.com"},
AllowMethods: []string{"PUT", "PATCH"},
AllowHeaders: []string{"Origin"},
ExposeHeaders: []string{"Content-Length"},
AllowCredentials: true,
AllowOriginFunc: func(origin string) bool {
return origin == "https://github.com"
},
MaxAge: 12 * time.Hour,
}))
h.Spin()
}
复制代码错误处理
我们可以借助Hertz提供的中间件的能力，统一对错误进行处理。即在最外层的中间件捕获错误，然后根据错误类型做对应的处理。 这里需要借助三方库errors来获取go的错误堆栈，方便我们排查问题
- 引入
errors
go get github.com/pkg/errors
复制代码- hertz的
app.RequestContext提供了c.Error(err)方法用于保存业务中产生的错误，c.Errors()获取业务中产生的错误。所以如果程序运行时产生错误，我们可以将错误保存到app.RequestContext中，并在中间件中获取这个错误，判断错误的类型进行对应的处理。
统一异常处理中间件代码如下：
package middleware
import (
"context"
"errors"
"fmt"
"github.com/bytedance/gopkg/util/logger"
"github.com/cloudwego/hertz/pkg/app"
"github.com/cloudwego/hertz/pkg/common/utils"
)
func GlobalErrorHandler(ctx context.Context, c *app.RequestContext) {
c.Next(ctx)
if len(c.Errors) == 0 {
// 没有收集到异常直接返回
fmt.Println("retun")
return
}
hertzErr := c.Errors[0]
// 获取errors包装的err
err := hertzErr.Unwrap()
// 打印异常堆栈
logger.CtxErrorf(ctx, "%+v", err)
// 获取原始err
err = errors.Unwrap(err)
// todo 进行错误类型判断
c.JSON(400, utils.H{
"code": 400,
"message": err.Error(),
})
}
复制代码配置中间件
package main
import (
"hertz_demo/biz/middleware"
"github.com/cloudwego/hertz/pkg/app/server"
)
func main() {
h := server.Default()
h.Use(middleware.GlobalErrorHandler)
register(h)
h.Spin()
}
复制代码业务代码中将错误存放到app.RequestContext中直接退出
err = c.BindAndValidate(&req)
if err != nil {
fmt.Printf("%v", err.Error())
_ = c.Error(errors.WithStack(err))
return
}
复制代码参数校验异常时，异常堆栈信息如下：
validating: expr_path=Name, cause=invalid
2022/07/25 23:41:47.977087 logger.go:190: [Error] [validating: expr_path=Name, cause=invalid
hertz_demo/biz/handler/person.PersonInfo
/Users/xxx/gopath/src/hertz_demo/biz/handler/person/person_service.go:23
github.com/cloudwego/hertz/pkg/app.(*RequestContext).Next
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/app/context.go:611
hertz_demo/biz/middleware.GlobalErrorHandler
/Users/xxx/gopath/src/hertz_demo/biz/middleware/global_error_handler.go:14
github.com/cloudwego/hertz/pkg/app.(*RequestContext).Next
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/app/context.go:611
github.com/cloudwego/hertz/pkg/app/middlewares/server/recovery.Recovery.func1
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/app/middlewares/server/recovery/recovery.go:51
github.com/cloudwego/hertz/pkg/app.(*RequestContext).Next
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/app/context.go:611
github.com/cloudwego/hertz/pkg/route.(*Engine).ServeHTTP
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/route/engine.go:607
github.com/cloudwego/hertz/pkg/protocol/http1.Server.Serve
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/protocol/http1/server.go:244
github.com/cloudwego/hertz/pkg/route.(*Engine).Serve
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/route/engine.go:456
github.com/cloudwego/hertz/pkg/route.(*Engine).onData
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/route/engine.go:353
github.com/cloudwego/hertz/pkg/network/netpoll.(*transporter).ListenAndServe.func2
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/hertz@v0.2.0/pkg/network/netpoll/transport.go:83
github.com/cloudwego/netpoll.(*connection).onRequest.func2
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/netpoll@v0.2.4/connection_onevent.go:153
github.com/cloudwego/netpoll.(*connection).onProcess.func1
/Users/xxx/gopath/pkg/mod/github.com/cloudwego/netpoll@v0.2.4/connection_onevent.go:176
github.com/bytedance/gopkg/util/gopool.(*worker).run.func1.1
/Users/xxx/gopath/pkg/mod/github.com/bytedance/gopkg@v0.0.0-20220623074550-9d6d3df70991/util/gopool/worker.go:69
github.com/bytedance/gopkg/util/gopool.(*worker).run.func1
/Users/xxx/gopath/pkg/mod/github.com/bytedance/gopkg@v0.0.0-20220623074550-9d6d3df70991/util/gopool/worker.go:70
runtime.goexit
/usr/local/go/src/runtime/asm_amd64.s:1571]
复制代码响应结果：
{
"code": 400,
"message": "validating: expr_path=Name, cause=invalid"
}
复制代码代码生成
上面所有的代码都可以通过Hertz提供的代码生成器生成，Hertz代码生成是通过thrift或者grpc的idl生成的。详情可以查看www.cloudwego.io/zh/docs/her… 这里推荐使用grpc生成代码
这里介绍通过GRPC生成Hertz代码的方式
- 安装
protobuf工具
// brew 安装
brew install protobuf
// 官方镜像安装，以 macos 为例
wget https://github.com/protocolbuffers/protobuf/releases/download/v3.19.4/protoc-3.19.4-osx-x86_64.zip
unzip protoc-3.19.4-osx-x86_64.zip
cp bin/protoc /usr/local/bin/protoc
// 确保 include/google 放入 /usr/local/include下
cp -r include/google /usr/local/include/google
复制代码- 项目根目录新建idl文件夹,添加
api.proto
syntax = "proto3";
package api;
import "google/protobuf/descriptor.proto";
option go_package = "/api";
extend google.protobuf.FieldOptions {
optional string raw_body = 50101;
optional string query = 50102;
optional string header = 50103;
optional string cookie = 50104;
optional string body = 50105;
optional string path = 50106;
optional string vd = 50107;
optional string form = 50108;
optional string go_tag = 51001;
optional string js_conv = 50109;
}
extend google.protobuf.MethodOptions {
optional string get = 50201;
optional string post = 50202;
optional string put = 50203;
optional string delete = 50204;
optional string patch = 50205;
optional string options = 50206;
optional string head = 50207;
optional string any = 50208;
optional string gen_path = 50301;
optional string api_version = 50302;
optional string tag = 50303;
optional string name = 50304;
optional string api_level = 50305;
optional string serializer = 50306;
optional string param = 50307;
optional string baseurl = 50308;
}
extend google.protobuf.EnumValueOptions {
optional int32 http_code = 50401;
}
复制代码- 新建person文件夹，新建person.proto文件
syntax = "proto3";
package person;
option go_package = "hertz/person";
import "api.proto";
message PersonReq {
string name = 1[(api.query)="name",(api.vd)="len($)>0"];
int32 age = 2[(api.path)="age"];
string city = 3[(api.body)="city"];
}
message PersonResp {
string name = 1;
int32 age = 2;
string city = 3;
}
service PersonService {
rpc PersonInfo(PersonReq) returns(PersonResp) {
option (api.post) = "/person_info/:age";
}
}
复制代码- 整个idl的路径如下：
├── idl
│ ├── api.proto
│ └── person
│ └── person.proto
复制代码- 生成代码
hz new -I idl -idl idl/person/person.proto
复制代码- 整理代码
go mod tidy
复制代码- 生成代码后，项目路径如下：
.
├── biz
│ ├── handler
│ │ ├── person
│ │ │ └── person_service.go
│ │ └── ping.go
│ ├── model
│ │ ├── api
│ │ │ └── api.pb.go
│ │ └── hertz
│ │ └── person
│ │ └── person.pb.go
│ └── router
│ ├── person
│ │ ├── middleware.go
│ │ └── person.go
│ └── register.go
├── go.mod
├── go.sum
├── idl
│ ├── api.proto
│ └── person
│ └── person.proto
├── main.go
├── router.go
└── router_gen.go
复制代码我们只需要在对应的person_service.go中添加业务逻辑即可
// Code generated by hertz generator.
package person
import (
"context"
person "hertz_demo/biz/model/hertz/person"
"github.com/cloudwego/hertz/pkg/app"
"github.com/pkg/errors"
)
// PersonInfo .
// @router /person_info [GET]
func PersonInfo(ctx context.Context, c *app.RequestContext) {
var err error
var req person.PersonReq
err = c.BindAndValidate(&req)
if err != nil {
_ = c.Error(errors.WithStack(err))
return
}
resp := &person.PersonResp{
Name: req.Name,
Age: req.Age,
City: req.City,
}
c.JSON(200, resp)
}
复制代码关于Hertz的平时日常开发的相关知识点差不多就是这些，如果你对Hertz感兴趣的话，可以阅读一下对应的文档，文档写的非常通俗易懂，如果这篇文章对你有帮助的话，麻烦点个赞关注一下，谢谢~