【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解

站长

2024年04月15日 19:43 · 阅读数 5

本期内容介绍：

1. Hertz 命令行工具 Hz 环境配置 & 工具介绍

2. IDL 介绍 & Hz拓展的IDL注解

01 Hertz 命令行工具 Hz 环境配置

首先进行 Go 环境的配置。根据使用系统的不同，在 Go 语言官网中下载对应的安装包。

安装包链接：go.dev/doc/install

安装完成后，需要配置两个环境变量：

定义 GOPATH 环境变量：export GOPATH=~/go。
将 GOBIN 添加到 PATH 环境变量：export PATH=GOPATH/bin:GOPATH/bin:GOPATH/bin:PATH。

02 工具介绍

Hz：Hertz 命令行工具，基于 IDL 生成 Hertz 代码脚手架；
Kitex：Kitex 命令行工具，基于 IDL 生成 Kitex 代码脚手架；
Thriftgo：基于 Go 语言的 Thrift 编译器，可以将定义的 Thrift IDL 编译生成相应的 Go 代码。此外它还提供插件模式，可以拓展生成的代码；
Protoc：Protobuf 的官方编译器。支持多种语言代码生成，同样提供插件模式拓展生成的代码。

目前 Hz 的开发是基于 Thriftgo 和 Protoc 的插件模式进行拓展代码的生成，如果大家需要安装这些工具，欢迎到 CloudWeGo 官网找到对应的下载链接进行安装。

03 IDL 的定义

IDL 的全称是 Interface Definition language，即接口定义语言。为对接口进行通用性的描述，其一般都包含以下两个部分：1. 通用的数据类型及关键字。 IDL 与目标语言的类型存在映射关系，例如 i32 对应到 Go 语言就是 Int 类型，关键字 Struct 会对应为 Go 语言中的结构体。2. 通用的接口描述能力。一般 IDL 会提供一个类似函数调用的形式来描述接口，并使用通用的数据类型组合给出请求参数和返回参数的类型。

例如，如下图所示定义一个接口：通过通用的数据类型定义请求体 Req 和返回体 Resp，拼接出一个名为 Method1 的接口，它接收的是一个 Req 类型的请求参数，并向调用者返回一个 Resp 类型的参数。

【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解

由于 IDL 是一种通用性的描述语言，它独立于特定的语言及环境，因此它为跨机器通信提供了便利，相当于提供了一个供服务者和调用者共同遵守的协议。

目前大多数 RPC 框架都需要用户定义 IDL ，并提供代码生成以及序列化和反序列化的功能。那么，既然 IDL 是为 RPC 框架服务的，为什么 HTTP 框架 Hertz 也需要使用 IDL 呢？

事实上，Hertz 并不是强依赖于 IDL 的，我们只是利用了 IDL 提供的接口描述能力以及拓展注解的能力，进而为用户生成一个可以快速开发服务的代码脚手架。

04 Hz 拓展的注解

Thrift Field 注解

Field 注解指在 IDL 定义的 Struct 每个域上添加的、主要用来和 Hertz 参数绑定及校验进行配合的注解。下面举几个简单的注解例子：

【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解

api.query 注解会在生成的 Go 代码中添加一个 query Tag，当用户使用 Hertz 的参数绑定功能后，会根据 Tag 的内容为结构体赋值。例如 query 注解中，如果用户请求的 query 参数为 query=hertz，那么使用了 Hertz 的绑定能力后，对应的成员变量也将会被赋值为 hertz。
Gotag 会将其定义的所有内容透传给 Go Struct，并且允许用户自定义生成 Tag 以满足其需求。例如上图 Field 7 中就会生成一个名为 json 的 Tag 和一个名为 goTag 的 Tag。
VdTag 用来进行参数校验。目前 Hertz 的参数校验能力就是利用了 Vd 注解。

Vd 参数校验注解

一般 Vd 也是作为一个注解存在的，它会在生成的 Go 代码中以 Go Tag 的形式存在。

如图所示，以 Name 的成员变量为例：

【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解

首先，Name 成员变量的 VdTag 声明了很多信息，这些内容也是相关的校验规则。

$ 表示该变量本身，图中表示该变量的值不能为 Alice；
&& 表示"与"操作，后面的表达式表示该变量的长度必须小于 100；
msg 关键字，表示验证失败返回的报错信息。例如图中如果用户的 Name 为 Alice，就会返回 Name can not be Alice 的报错信息。

除了内置的多种验证函数之外，Hertz 的参数校验能力还支持自定义校验函数。如果用户有一些特别的、复杂的校验逻辑，就可以写在一个校验函数中，最后透传到我们的 Vd 注解里。此外，Hertz 的参数校验和绑定能力还支持多种用法。

更多使用方法请参考：www.cloudwego.io/zh/docs/her…

Thrift Method 注解

method 注解是指我们在定义接口时描述 HTTP 方法的注解。如图，每一个注解都对应了一个 HTTP 的请求方法。

【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解

例如 Method1 接口，如果请求 Method1，就需要在客户端或者请求端发送一个 HTTP 的 Get 请求。在生成代码之后 Hz 工具会读取请求的路由地址，并为这些接口生成对应的路由注册以及路由组的注册，此外还会生成一个默认的处理器函数。

下图展示了用 IDL 给上图中定义的接口生成的代码。以红框为例，给出了一个 userid 的路由组，我们在路由组里面可以注册一些中间件函数，当用户路由与中间件函数的前缀相匹配时即可执行。之后 Hz 工具会将所有的路由进行最终的注册，例如这里注册的 DELETE、GET、PUT、POST等方法，此外 Hz 还会为其生成一个默认的 Handler 逻辑。

【Hertz 新手小册】Day 4. Hertz 高效命令行工具 Hz 详解