Hertz 入门

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

Hello World

本节将介绍如何搭建 Hertz 的基础环境。

1. 创建一个文件夹，文件夹名称为 learn_hertz
1. 创建 main.go 文件，文件内容如下

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"
)

func main() {
    h := server.Default()

    h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
        ctx.JSON(consts.StatusOK, utils.H{"message": "pong"})
    })

    h.Spin()
}

1. 通过 go mod init learn_hertz 命令创建 go.mod 文件
1. 通过 go mod tidy 下载依赖库
1. 通过 go build 构建项目，构建后会生成 learn_heartz.exe 文件双击执行后会看到如下信息。

ini 复制代码

2023/12/16 13:06:32.991979 engine.go:668: [Debug] HERTZ: Method=GET    absolutePath=/ping                     --> handlerName=main.main.func1 (num=2 handlers)
2023/12/16 13:06:33.004723 engine.go:396: [Info] HERTZ: Using network library=standard
2023/12/16 13:06:33.005809 transport.go:65: [Info] HERTZ: HTTP server listening on address=[::]:8888

1. 访问 http://localhost:8888/ping ，可以在浏览器中看到如下效果

image-20231216130749035

至此基本功能已经完成。

路由

本节将详细介绍在 Hertz 中如何创建路由以及支持 GET、POST、DELETE、PUT 四种请求的方法。在 Hertz 中，路由的创建通过以下方式进行：

javascript 复制代码

goCopy code
h.GET("路由地址", func(c context.Context, ctx *app.RequestContext) {
    ctx.JSON(consts.StatusBadRequest, utils.H{"message": "error"})
})

在上述代码中，.GET 表示对外提供 GET 请求方式，而后面的函数则用于处理具体的业务逻辑。如果需要处理其他请求类型，可以相应地使用 .POST、.DELETE、.PUT。

示例代码如下：

less 复制代码

goCopy code
h.POST("路由地址", func(c context.Context, ctx *app.RequestContext) {
    // 处理 POST 请求业务逻辑
})

h.DELETE("路由地址", func(c context.Context, ctx *app.RequestContext) {
    // 处理 DELETE 请求业务逻辑
})

h.PUT("路由地址", func(c context.Context, ctx *app.RequestContext) {
    // 处理 PUT 请求业务逻辑
})

如果需要将多个路由统一添加一个前缀，可以使用路由组。以下是一个路由组的示例：

css 复制代码

goCopy code
group := h.Group("/group")
group.GET("路由地址", func(c context.Context, ctx *app.RequestContext) {
    // 处理业务逻辑
})

通过这样的方式，可以更好地组织和管理不同类型的路由，并使代码结构更清晰。希望这些扩展能够更全面地解释如何在 Hertz 中进行路由的创建和管理。

请求参数获取

在 Hertz 中，实现请求参数的获取是一项常见的任务。本节将详细介绍在 Hertz 中如何获取不同类型的请求参数。

路由参数获取

首先，我们来看如何获取路由参数。下面的示例代码定义了一个路由 /hertz/:version，其中 :version 是一个动态的路由参数。在路由处理函数中，通过使用 c.Param("version") 来获取路由参数的值，并将其返回给客户端。

go 复制代码

h.GET("/hertz/:version", func(ctx context.Context, c *app.RequestContext) {
    // 获取路由参数
    version := c.Param("version")
    c.String(consts.StatusOK, "Hello %s", version)
})

通过以下命令可以测试该路由：

bash 复制代码

curl http://localhost:8888/hertz/v1.0

返回信息将是：

Hello v1.0

Form 表单参数获取

接下来，我们看如何获取来自 Form 表单的参数。下面的示例代码定义了一个路由 /form，并在路由处理函数中使用 ctx.GetPostForm("age") 来获取 Form 表单中名为 "age" 的参数。

css 复制代码

h.POST("/form", func(c context.Context, ctx *app.RequestContext) {
    age, _ := ctx.GetPostForm("age")
    ctx.JSON(consts.StatusOK, utils.H{"age": age})
})

通过以下命令可以测试该路由：

rust 复制代码

curl --location 'http://localhost:8888/form' \
--form 'age="10"'

返回信息将是：

json 复制代码

{"age":"10"}

QueryString 参数获取

在 Hertz 中，获取 QueryString 参数也是很简单的。下面的示例代码定义了一个路由 /hertz，并使用 c.Query("version") 来获取 QueryString 参数的值。

go 复制代码

h.GET("/hertz", func(ctx context.Context, c *app.RequestContext) {
    // 获取 QueryString 参数
    version := c.Query("version")
    c.String(consts.StatusOK, "Hello %s", version)
})

通过以下命令可以测试该路由：

bash 复制代码

curl http://localhost:8888/hertz\?version\=123

返回信息将是：

Hello 123

Body 参数获取

最后，我们来看如何从请求的 Body 中获取参数。下面的示例代码定义了一个路由 /body，并使用 c.Bind(&p) 来将请求的 JSON 数据绑定到一个结构体中。

go 复制代码

h.POST("/body", func(ctx context.Context, c *app.RequestContext) {
    type Person struct {
       Age  int    `json:"age"`
       Name string `json:"name"`
    }
    var p Person
    err := c.Bind(&p)
    if err != nil {
       c.String(consts.StatusBadRequest, "bind error: %s", err.Error())
       return
    }
    c.JSON(consts.StatusOK, utils.H{"p": p})
})

通过以下命令可以测试该路由：

css 复制代码

curl --location 'http://localhost:8888/body' \
--header 'Content-Type: application/json' \
--data '{
    "age":10,
    "name":"zhangsan"
}'

返回信息将是：

css 复制代码

{"p":{"age":10,"name":"zhangsan"}}

通过这些示例，有助于更好地理解在 Hertz 中如何获取不同类型的请求参数。

.hljs.code__pre::before { position: initial; padding: initial; content: ''; display: block; height: 25px; background-color: transparent; background-image: url("doocs.oss-cn-shenzhen.aliyuncs.com/img/123.svg"); background-position: 14px 10px; background-repeat: no-repeat; background-size: 40px; } .hljs.code__pre { padding: 0!important; } .hljs.code__pre code { display: -webkit-box; padding: 0.5em 1em 1em; overflow-x: auto; text-indent: 0; }

本文使用文章同步助手同步