字节开源WEB框架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项目

$GOPATHsrchertz_demo

cd $GOPATH
mkdir src
cd src
mkdir hertz_demo
cd hertz_demo
复制代码

hz new

.
├── 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"
    }
}
复制代码

中间件

JWTCors

使用跨域中间件示例

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()
}
复制代码

错误处理

errors

errors

go get github.com/pkg/errors
复制代码

app.RequestContextc.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"
}
复制代码

代码生成

Hertzthriftgrpcgrpc

GRPCHertz

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
复制代码

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感兴趣的话，可以阅读一下对应的文档，文档写的非常通俗易懂，如果这篇文章对你有帮助的话，麻烦点个赞关注一下，谢谢~