0
0

字节开源WEB框架Hertz太香啦！

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项目

  1. 进入到$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项目

  1. 执行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的错误堆栈，方便我们排查问题

  1. 引入errors
go get github.com/pkg/errors
复制代码
  1. 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/[email protected]/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/[email protected]/pkg/app/context.go:611
github.com/cloudwego/hertz/pkg/app/middlewares/server/recovery.Recovery.func1
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/app/middlewares/server/recovery/recovery.go:51
github.com/cloudwego/hertz/pkg/app.(*RequestContext).Next
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/app/context.go:611
github.com/cloudwego/hertz/pkg/route.(*Engine).ServeHTTP
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/route/engine.go:607
github.com/cloudwego/hertz/pkg/protocol/http1.Server.Serve
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/protocol/http1/server.go:244
github.com/cloudwego/hertz/pkg/route.(*Engine).Serve
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/route/engine.go:456
github.com/cloudwego/hertz/pkg/route.(*Engine).onData
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/route/engine.go:353
github.com/cloudwego/hertz/pkg/network/netpoll.(*transporter).ListenAndServe.func2
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/pkg/network/netpoll/transport.go:83
github.com/cloudwego/netpoll.(*connection).onRequest.func2
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/connection_onevent.go:153
github.com/cloudwego/netpoll.(*connection).onProcess.func1
    /Users/xxx/gopath/pkg/mod/github.com/cloudwego/[email protected]/connection_onevent.go:176
github.com/bytedance/gopkg/util/gopool.(*worker).run.func1.1
    /Users/xxx/gopath/pkg/mod/github.com/bytedance/[email protected]/util/gopool/worker.go:69
github.com/bytedance/gopkg/util/gopool.(*worker).run.func1
    /Users/xxx/gopath/pkg/mod/github.com/bytedance/[email protected]/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

代码的方式

  1. 安装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
复制代码
  1. 项目根目录新建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;
}
复制代码
  1. 新建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";
  }
}
复制代码
  1. 整个idl的路径如下：
├── idl
│   ├── api.proto
│   └── person
│       └── person.proto
复制代码
  1. 生成代码
hz new  -I idl -idl idl/person/person.proto
复制代码
  1. 整理代码
go mod tidy
复制代码
  1. 生成代码后，项目路径如下：
.
├── 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感兴趣的话，可以阅读一下对应的文档，文档写的非常通俗易懂，如果这篇文章对你有帮助的话，麻烦点个赞关注一下，谢谢~

标签： 开源 前端 java
本文转载自: https://blog.csdn.net/xhbzl/article/details/126507859
版权归原作者 一堆土豆33 所有， 如有侵权，请联系我们删除。
登录后发布评论

“字节开源WEB框架Hertz太香啦！”的评论:

还没有评论
关于作者
...
overfit同步小助手
文章同步
相关阅读

TCP&UDP测试工具

MacOS 命令行详解使用教程

EchoMimicV2：阿里推出的开源数字人项目，能生成完整数字人半身动画

前端框架 react 性能优化

RabbitMQ基础知识

CSS(十六）——CSS导航栏

webrtc开发实战系列2 – windows下编译WebRTC支持H264

文章导航