【Hertz 新手小册】Day 5. 利用Hertz命令行工具 Hz 创建 HTTP 服务

本期内容介绍：

   1. Hz 运行模式介绍            

   2. Demo 实践：利用 Hz 创建 HTTP 服务

01 Hz 运行模式介绍

Hz 在生成代码的时候一共需要三个工具：Hz、Thriftgo 和 Thriftgo 插件 thrift-gen-hertz。

目前我们的命令行工具 Hz 有两种运行方式：其一，Hz 工具本身作为一个命令行工具存在；其二，它也会作为一个 Thriftgo 的插件来运行。

Hz 运行的整个流程如下：1. 当用户使用了 Hz 命令后，Hz 工具本身会被系统调用，生成一些 Layout 相关代码，比如 Main 函数、Gomod 等文件。同时，Hz 会拼接 Thriftgo 命令调用 Thriftgo 来生成与 IDL 定义相关的代码；2. Thriftgo 会解析 IDL 并生成对应的语法树，然后将语法树以及透传给插件的选项一起写入到标准输入中；3. 当插件得到了这些语法树以及选项之后，插件会先在标准输入中读取到 Thriftgo 传过来的内容，然后解析语法树，并根据用户在 IDL 中拓展的相关 HTTP 注解来生成目标文件的内容；4. 当 thrift-gen-hertz 插件执行完毕后，会通过标准输出的形式将结果返回，Thriftgo 会从中读入插件的执行结果，并生成目标文件；5. 将整个流程执行的结果返回给我们的命令行 Hz 工具，命令行工具会将最终的结果呈现给用户。

02 Demo 实践：利用 Hz 创建 HTTP 服务

本节 Demo 会将 CloudWeGo 项目下的 Hertz 与 Kitex 串联在一起，为大家的实践提供参考。

如链路图所示，在这个链路中，首先由客户端发起一个 HTTP 请求访问 Hertz-Server， Hertz-Server 在这里充当了一个 API 层的服务，它可以将用户的请求经过一些简单处理，然后再交由给 Kitex-Server ，最终所有的处理结果组合后，通过 HTTP 响应返回给客户端。

1. 链路执行的流程大致如下：

• 客户端发送 HTTP 请求给 Hertz-Server；
• Hertz-Server 把该请求打到对应路由的处理器函数中，完成一些业务逻辑的处理；
• 利用 Kitex-Client 将处理的结果发送 RPC 请求至 Kitex-Server；
• 通过 Kitex-Server 的处理，Kitex-client 会得到一个 RPC 响应的结果；此时，Hertz 的 Handler 可以对执行结果采取进一步的处理；
• 最终，将所有的业务逻辑都通过一个 HTTP 响应的方式返回给客户端。

2. 本节演示 Demo 需要实现的内容如下：

• 编写 RPC IDL 和 HTTP IDL。RPC IDL 用于生成 Kitex 代码,HTTP IDL 用来生成 Hertz 的脚手架代码；
• 生成 Kitex 代码，并完成 Kitex Server 端的逻辑编写；
• 使用 Hz 工具生成 Hertz server 侧的代码，并完成 Hertz Handler 逻辑的编写；
• 简单地发一个请求调试接口，判断逻辑是否已经调通。

此处还介绍了 Hz 的 update 命令：在 HTTP 的 IDL 中新增一个接口，使用 Hz update 命令，就可以更新 Hertz 侧的代码。代码更新完成后，编写新增的 Handler 逻辑，再进行接口的调试就完成所有的 Demo 内容了。

Demo 实践演示视频链接：meetings.feishu.cn/s/1i3fsqit6… 23 分钟开始演示）在演示中主要介绍了代码内容以及 Hz 生成脚手架的内容。以上 Demo 不讲解 Kitex 代码，如果对 Kitex 代码有兴趣，演示 Kitex Demo 的所有代码在下方链接中，如有需要可以扩容到本地进行实践。Kitex Demo：github.com/cloudwego/h…

3. 在完成本次 Demo 实践后，基于脚手架开发的重点总结如下：

• 需要在 main.go 中完成业务配置的初始化工作；

• 可以为特定的路由组添加中间件函数，以实现不同的路由组拥有不同的执行逻辑；

• 编写业务的 Handler 函数，实现具体的业务逻辑。

---

相关信息

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

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

项目地址

GitHub：github.com/cloudwego

官网：www.cloudwego.io