这是我参与「第五届青训营」伴学笔记创作活动的第 17 天

Hertz 简介

Hertz 是一个Go语言高性能 HTTP 框架，在设计之初参考了其他开源框架 fasthttp、gin、echo 的优势，并结合字节跳动内部的需求，使其具有高易用性、高性能、高扩展性等特点。如今越来越多的微服务选择使用 Golang，如果对微服务性能有要求，又希望框架能够充分满足内部的可定制化需求，Hertz 会是一个不错的选择。

架构设计：Hertz采用了4层分层设计（应用层、路由层、协议层、传输层），保证各个层级功能内聚，同时通过层级之间的接口达到灵活扩展的目标。

框架特点：

高易用性：在开发过程中，快速写出来正确的代码往往是更重要的。因此，在 Hertz 在迭代过程中，积极听取用户意见，持续打磨框架，希望为用户提供一个更好的使用体验，帮助用户更快的写出正确的代码。
高性能：Hertz 默认使用自研的高性能网络库 Netpoll，在一些特殊场景相较于 go net，Hertz 在 QPS、时延上均具有一定优势。
高扩展性：Hertz 采用了分层设计，提供了较多的接口以及默认的扩展实现，用户也可以自行扩展。同时得益于框架的分层设计，框架的扩展性也会大很多。
多协议支持：Hertz 框架原生提供 HTTP1.1、ALPN 协议支持。除此之外，由于分层设计，Hertz 甚至支持自定义构建协议解析逻辑，以满足协议层扩展的任意需求。
网络层切换能力：Hertz 实现了 Netpoll 和 Golang 原生网络库间按需切换能力，用户可以针对不同的场景选择合适的网络库，同时也支持以插件的方式为 Hertz 扩展网络库实现。

快速开始

安装命令行工具 hz
- 确保环境变量已经正确定义
- 安装 hz

go install github.com/cloudwego/hertz/cmd/hz@latest

生成/编写示例代码
- 在当前目录下创建 hertz_demo 文件夹，进入该目录中
- 创建 main.go 文件
- 在 main.go 文件中添加以下代码

package main
 
import (
    "context""github.com/cloudwego/hertz/pkg/app""github.com/cloudwego/hertz/pkg/app/server""github.com/cloudwego/hertz/pkg/common/utils""github.com/cloudwego/hertz/pkg/protocol/consts"
)
 
funcmain() {
    h := server.Default()
 
    h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
            ctx.JSON(consts.StatusOK, utils.H{"message": "pong"})
    })
 
    h.Spin()
}

生成 go.mod 文件

go mod init hertz_demo

整理 & 拉取依赖

go mod tidy

运行示例代码
- go build -o hertz_demo
- go run hertz_demo

如果成功，将看到

2023/01/30 11:26:27.824241 engine.go:617: [Debug] HERTZ: Method=GET    absolutePath=/ping                     --> handlerName=main.main.func1 (num=2 handlers)
2023/01/30 11:26:27.836518 engine.go:389: [Info] HERTZ: Using network library=standard
2023/01/30 11:26:27.837518 transport.go:65: [Info] HERTZ: HERTZ: HTTP server listening on address=[::]:8888

之后对接口进行测试：

curl http://127.0.0.1:8888/ping

如果成功就可以看到以下输出

StatusCode        : 200
StatusDescription : OK
Content           : {"message":"pong"}
RawContent        : HTTP/1.1 200 OK
                    Content-Length: 18
                    Content-Type: application/json; charset=utf-8
                    Date: Mon, 30 Jan 2023 03:26:53 GMT
                    Server: hertz
 
                    {"message":"pong"}
Forms             : {}
Headers           : {[Content-Length, 18], [Content-Type, application/json; charset=utf-8], [Date, Mon, 30 Jan 2023 03:26:53 GMT], [Server,  
                    hertz]}
Images            : {}
InputFields       : {}
Links             : {}
ParsedHtml        : mshtml.HTMLDocumentClass
RawContentLength  : 18

到此就已经成功启动了 Hertz Server，并完成了一次调用。

路由

路由注册

Hertz 提供了 GET、POST、PUT、DELETE、ANY 等方法用于注册路由。

方法

示例代码：

package main
 
import (
	"context"
	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/cloudwego/hertz/pkg/protocol/consts"
)
 
funcmain(){
	h := server.Default(server.WithHostPorts("127.0.0.1:8080"))
 
	h.StaticFS("/", &app.FS{Root: "./", GenerateIndexPages: true})
 
	h.GET("/get", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "get")
	})
	h.POST("/post", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "post")
	})
	h.PUT("/put", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "put")
	})
	h.DELETE("/delete", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "delete")
	})
	h.PATCH("/patch", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "patch")
	})
	h.HEAD("/head", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "head")
	})
	h.OPTIONS("/options", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "options")
	})
	h.Any("/ping_any", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "any")
	})
	h.Handle("LOAD","/load", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "load")
	})
	h.Spin()
}

路由组

Hertz 提供了路由组( Group )的能力，用于支持路由分组的功能，同时中间件也可以注册到路由组上。

示例代码：

package main
 
import (
	"context"
	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/cloudwego/hertz/pkg/protocol/consts"
)
 
funcmain(){
	h := server.Default(server.WithHostPorts("127.0.0.1:8080"))
	v1 := h.Group("/v1")
	v1.GET("/get", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "get")
	})
	v1.POST("/post", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "post")
	})
	v2 := h.Group("/v2")
	v2.PUT("/put", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "put")
	})
	v2.DELETE("/delete", func(ctx context.Context, c *app.RequestContext) {
		c.String(consts.StatusOK, "delete")
	})
	h.Spin()
}

路由类型

Hertz 支持丰富的路由类型用于实现复杂的功能，包括静态路由、参数路由、通配路由。

路由的优先级:静态路由 > 命名路由 > 通配路由

静态路由如上文
参数路由：
- Hertz 支持使用 :name 这样的命名参数设置路由，并且命名参数只匹配单个路径段。
- 如果我们设置/user/:name路由，匹配情况如下

通过使用 RequestContext.Param 方法，我们可以获取路由中携带的参数。

package main
 
import (
	"context"
	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/cloudwego/hertz/pkg/protocol/consts"
)
 
funcmain(){
	h := server.Default(server.WithHostPorts("127.0.0.1:8080"))
	// This handler will match: "/hertz/version", but will not match : "/hertz/" or "/hertz"
	h.GET("/hertz/:version", func(ctx context.Context, c *app.RequestContext) {
		version := c.Param("version")
		c.String(consts.StatusOK, "Hello %s", version)
	})
	h.Spin()
}

通配路由
- Hertz 支持使用 *path 这样的通配参数设置路由，并且通配参数会匹配所有内容。
- 如果我们设置/src/*path路由，匹配情况如下

通过使用 RequestContext.Param 方法，我们可以获取路由中携带的参数。

package main
 
import (
	"context"
	"github.com/cloudwego/hertz/pkg/app"
	"github.com/cloudwego/hertz/pkg/app/server"
	"github.com/cloudwego/hertz/pkg/protocol/consts"
)
 
funcmain(){
	h := server.Default(server.WithHostPorts("127.0.0.1:8080"))
	// However, this one will match "/hertz/v1/" and "/hertz/v2/send"
	h.GET("/hertz/:version/*action", func(ctx context.Context, c *app.RequestContext) {
		version := c.Param("version")
		action := c.Param("action")
		message := version + " is " + action
		c.String(consts.StatusOK, message)
	})
	h.Spin()
}

Hertz 代码生成工具 hz

hz 是 Hertz 框架提供的一个用于生成代码的命令行工具。目前，hz 可以基于 thrift 和 protobuf 的 IDL 生成 Hertz 项目的脚手架。

基本使用：

创建一个 Hertz 新项目

// GOPATH 下执行，go mod 名字默认为当前路径相对GOPATH的路径，也可自己指定 hz new

// 非GOPATH 下执行，需要指定 go mod 名 hz new -mod hertz/demo

// 整理 & 拉取依赖 go mod tidy

编译项目

go build

运行项目

./{{your binary}}

测试

curl 127.0.0.1:8888/ping 如果返回{"message":"pong"}，说明接口调通。

总结

本文主要总结了go语言高性能 HTTP 框架 Hertz，知识庞多，只是简单的入门练习，后续还需要深入学习。

Go语言之Hertz ｜ 青训营笔记