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

本期内容介绍：

1. Hertz 命令行东西 Hz 环境装备& 东西介绍

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

01 Hertz 命令行东西 Hz 环境装备

首要进行 Go 环境的装备。依据运用体系的不同，在 Go 言语官网中下载对应的装置包。

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

装置完成后，需求装备两个环境变量：

1. 界说 GOPATH 环境变量：export GOPATH=~/go。

2. 将 GOBIN 增加到 PATH 环境变量：export PATH=$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 类型的参数。

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

现在大多数 RPC 结构都需求用户界说 IDL ，并供给代码生成以及序列化和反序列化的功用。那么，既然 IDL 是为 RPC 结构服务的，为什么 HTTP 结构 Hertz 也需求运用 IDL 呢？

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

04 Hz 拓宽的注解

ThriftField 注解

Field 注解指在 IDL 界说的 Struct 每个域上增加的、主要用来和 Hertz 参数绑定及校验进行合作的注解。下面举几个简略的注解比如：

• api.query注解会在生成的 Go 代码中增加一个queryTag，当用户运用 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的成员变量为例：

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

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

除了内置的多种验证函数之外，Hertz 的参数校验才能还支持自界说校验函数。假如用户有一些特别的、杂乱的校验逻辑，就能够写在一个校验函数中，终究透传到咱们的 Vd 注解里。此外，Hertz 的参数校验和绑定才能还支持多种用法。

更多运用办法请参阅：www.cloudwego.io/zh/docs/her…

ThriftMethod 注解

method注解是指咱们在界说接口时描绘 HTTP 办法的注解。如图，每一个注解都对应了一个 HTTP 的恳求办法。

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

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

ProtobufField 注解

Protobuf 进行的注解拓宽与 Thrift 是一样的，只是在运用的写法上略有不同。

在运用 Protobuf 写 IDL 的时分，需求提前引用 Hz 文档中供给的api.proto注解拓宽文件，才能够正确地运用注解并生成想要的代码。

根据 Protobuf IDL 创建项目：www.cloudwego.io/zh/docs/her…

ProtobufMethod 注解

Protobuf 的 Method 注解和 Thrift 也是一致的，这儿不再赘述，详细能够到 Hz 的运用手册中查询。

Hz 命令行东西运用：www.cloudwego.io/zh/docs/her…

---

相关信息

官方 GitHub：github.com/cloudwego/h…

官方文档：www.cloudwego.io/zh/docs/her…

项目地址

GitHub：github.com/cloudwego

官网：www.cloudwego.io