hzHertz 框架官方 IDL 代码生成器完整使用指南【免费下载链接】hertzGo HTTP framework with high-performance and strong-extensibility for building micro-services.项目地址: https://gitcode.com/GitHub_Trending/he/hertzhz是 Hertz 目录。它负责解析 Thrift / Protobuf 两种 IDLInterface Definition Language文件并一键生成完整可运行的 Hertz 项目脚手架包括 handler、路由、model 数据模型与 client 客户端代码。阅读本文后你将掌握hz new / update / model / client四大命令的完整用法、全部核心参数含义、自定义模板机制以及 CLI 与插件双模式运行的底层原理。快速上手在仓库的cmd/hz目录下构建二进制然后即可基于 IDL 生成项目# 构建 cd cmd/hz go build -o hz . # 从 Thrift IDL 生成新项目 hz new --idl api.thrift --module github.com/example/myservice # 从 Protobuf IDL 生成新项目 hz new --idl api.proto --module github.com/example/myservice # IDL 变更后增量更新已有项目模块名自动从 go.mod 读取 hz update --idl api.thrift # 仅生成 model 代码模块名自动从 go.mod 读取 hz model --idl api.thrift # 生成 client 代码模块名自动从 go.mod 读取 hz client --idl api.thrift --base_domain localhost:8888--module别名--mod用于指定 Go module 名称。若当前目录或其上层目录已存在go.modhz 会通过util.SearchGoMod自动探测模块名无需再手动指定若未指定且找不到go.mod则会以 GOPATH 相对路径作为模块名并自动生成go.mod对应源码逻辑见 config/argument.go 的checkPackage实现。四大命令命令说明new从 IDL 搭建全新 Hertz 项目生成工程布局、handler、路由与 modelupdate为 IDL 中新增的方法增量添加 handler/路由不覆盖已有代码model仅根据 IDL 类型生成 Go 结构体定义modelsclient根据 IDL service 定义生成 Hertz HTTP 客户端代码命令入口定义在 app/app.go 的Init()中每个命令都通过urfave/cli注册并绑定各自支持的 flag 集合main.go首先调用app.PluginMode()检查插件模式见下文架构部分随后进入正常 CLI 流程main.go。参数Flags全解全局参数参数说明--verbose,-vv开启 verbosedebug 级别日志--verbose会调用logs.SetLevel(logs.LevelDebug)输出详细调试信息不开时默认只输出 warning 级别以上日志app/app.go。项目结构相关参数参数适用命令说明--idl全部IDL 文件路径.thrift或.proto可多次指定--module,--mod全部Go module 名称若存在go.mod则自动探测--servicenew服务名默认hertz_service--out_dirnew,update,model项目输出目录默认当前目录--handler_dirnew,updatehandler 目录相对out_dir默认biz/handler--model_dir全部model 目录相对out_dir默认biz/model--router_dirnewrouter 目录相对out_dir默认biz/router--client_dirnew,update,clientclient 输出目录。对new/update不指定则不生成 client 代码对client默认使用由 IDL 推导的路径--force_client_dirclientclient 输出目录不带 IDL 命名空间子目录--usenew,update,client从外部包导入 model而非本地生成默认目录常量biz/model、biz/router、biz/handler定义于 meta/const.go。注意handler_dir、model_dir、router_dir等必须为相对out_dir的相对路径绝对路径会直接报错config/argument.go 的checkPath。--use的场景通常是 model 由独立的公共仓库统一维护此时 hz 会跳过本地的 model 生成Thrift 场景下还会输出提示信息model code is not generated due to the -use option见 meta/const.go。代码生成参数参数适用命令说明--handler_by_methodnew,update每个方法生成独立 handler 文件默认每个 service 一个文件--sort_routernew,update对路由注册代码排序保证输出确定性--no_recurse全部只生成主 IDL 的 model跳过 include/import 的依赖 IDL--force,-fnew强制覆盖已有项目--force_clientclient即使hertz_client.go已存在也强制重新生成--base_domainclient生成的 client 代码中默认请求域名--enable_extendsnew,update,client解析 Thrift IDL 中的extends关键字--handler_by_method对应两种 handler 生成模式默认的按 service模式将所有 handler 汇聚在一个文件如user_service.goupdate时通过handler_single.go模板追加新方法按方法模式则为每个方法生成独立文件如create_user.goupdate时新建文件但绝不修改已有文件详见 DESIGN.md 的 Handler Generation 小节。Struct Tag 参数参数适用命令说明--snake_tag全部form、query、jsontag 使用 snake_case 命名--json_enumstr全部JSON 枚举字段使用字符串值而非数字仅 Thrift--unset_omitempty全部移除生成结构体 tag 中的omitempty--pb_camel_json_tag全部JSON tag 使用 camelCase仅 Protobuf--rm_tag全部移除默认 tag如--rm_tag json。显式注解的 tag 会被保留--query_enumintclientclient 代码中枚举 query 参数使用数值--enable_optionalclientThrift 可选字段未设置时不放入 query 参数这些 tag 选项最终通过GetThriftgoOptions拼接到 thriftgo 的go:生成选项字符串中——默认选项为reserve_comments,gen_json_tagfalse--json_enumstr会追加json_enum_as_text并总是追加package_prefix以保证生成 import 路径与输出结构一致config/cmd.go。IDL 编译器透传参数参数适用命令说明--proto_path,-I全部添加 Protobuf import 的搜索路径--thriftgo,-t全部透传给 thriftgo 的参数如-t naming_stylegolint--protoc,-p全部透传给 protoc 的参数--thrift-pluginsnew,update,client额外的 thriftgo 插件{name}:{options}--protoc-pluginsnew,update,client额外的 protoc 插件{name}:{options}:{out_dir}--option_package,-Pnew,update将 IDL include 路径映射为 Go import 路径{include}{import}--trim_gopackage,--trim_pkg全部裁剪 protobufgo_package前缀避免生成过深的嵌套目录以 Protobuf 场景为例BuildPluginCmd会为 protoc 构造--pluginprotoc-gen-hertzhz二进制路径、--hertz_out输出目录与--hertz_opt序列化参数三个关键参数config/cmd.goprotoc 插件必须以plugin_name:options:out_dir三段式传入否则会直接报错退出。protoc 的 well-known types 需要额外的-Iinclude 路径这点在generate.sh中体现得很清楚自动探测 protoc 同级 include 目录或/usr/include、/usr/local/include等系统路径。模板定制参数参数适用命令说明--customize_layoutnew自定义工程布局模板 YAML 路径--customize_layout_data_pathnew渲染布局模板用的 JSON 数据文件路径--customize_packagenew,update,client自定义 package 模板 YAML覆盖 handler/router/middleware 模板--exclude_file,-E全部排除某文件路径不生成/不更新--customize_layout指定布局配置后GenerateLayout会读取该 YAML 替代默认布局app/app.go若同时提供了--customize_layout_data_path的 JSON 数据文件则完全由数据文件驱动渲染GenerateByConfig见 generator/layout.go否则仍然按 service 信息渲染。自定义模板Custom Templateshz 的全部生成代码都由 Go template 渲染。创建一个 YAML 配置文件并用--customize_package传入layouts: - path: biz/handler/handler.go # 覆盖默认 handler 模板 delims: [{{, }}] body: | package {{.PackageName}} // your custom handler template... - path: biz/custom/{{.ServiceName}}.go # 新建文件path 支持模板变量 delims: [{{, }}] loop_service: true # 每个 service 生成一个文件 update_behavior: type: append # update 时的行为skip/cover/append append_key: method # 按 method 或 service 追加 append_content_tpl: | // new method: {{.Name}} body: | package custom // your template...模板的 update 行为有三种skip—— 不修改已存在的文件cover—— 完全覆盖已有文件append—— 向已有文件追加新内容例如新增的 handler 方法。模板系统还支持自定义定界符当你的模板本身包含 Go template 语法、需要避开{{ }}冲突时非常有用、按 service 循环loop_service或按 method 循环loop_method生成多份文件等能力DESIGN.md。示例输出用 generate.sh 验证生成结果仓库提供了 generate.sh使用cmd/hz/testdata下的测试 IDL 文件Thrift 与 Protobuf2/3 两套 psm 用例完整跑一遍new → update → model → client全流程cd cmd/hz # 为所有 IDL 类型生成示例输出到 generate_out/ ./generate.sh # 只生成指定目标 ./generate.sh thrift proto3 # CI 模式生成 → 校验产物可编译 → 清理 ./generate.sh --verify --clean可选目标thrift、proto2、proto3、handler_by_method不传则默认全部。脚本细节--verify会对每个目标执行go mod tidy go build .确保生成的代码真实可编译--clean在验证通过后删除输出目录适合 CI 流水线--hz PATH可指定 hz 二进制路径默认从源码go build -o hz .构建每个目标在子目录中依次执行hz new带-f强制覆盖、hz update、hz model、hz client --client_dirhertz_client完整覆盖四个命令的可运行性Protobuf 目标会尝试定位 protoc 的 well-known types include 目录并作为-I传入generate.sh。对应的测试 IDL 文件位于 cmd/hz/testdata/thrift/psm.thrift、cmd/hz/testdata/protobuf3/psm/psm.proto 等路径可作为编写自定义 IDL 的参考样本。依赖的 IDL 编译器thriftgo—— Thrift 编译器。若系统中不存在hz 会自动安装最新版本若已存在但版本低于 v0.2.0也会自动更新到最新版逻辑见 config/cmd.go 的lookupToolprotoc—— Protobuf 编译器必须手动安装hz 不会自动安装若缺失会直接提示 please install it first。lookupTool的查找顺序为PATH中的thriftgo/protoc→$GOPATH/bin下的同名工具。Thrift 场景下若go.mod中缺少replace github.com/apache/thrift github.com/apache/thrift v0.13.0hz 还会在new结束时给出对应警告提示meta/const.go。架构CLI 与插件双模式执行hz 内部采用CLI 模式 插件模式双模式设计完整设计文档见 cmd/hz/DESIGN.md。双模式执行模型CLI 模式正常模式解析命令行参数、生成工程布局然后以子进程方式调用 IDL 编译器thriftgo/protoc插件模式当被 IDL 编译器以插件方式回调thrift-gen-hertz/protoc-gen-hertz时从 stdin 读取解析好的 AST生成 Hertz 专属代码。因此一条hz new命令实际上会运行两次 hzUser - hz (CLI mode) - thriftgo/protoc - hz (Plugin mode) - generated code插件模式通过环境变量HERTZ_PLUGIN_MODE检测——CLI 在调用编译器前会设置该变量config/cmd.gomain()开头的app.PluginMode()则检查该变量并决定是否以插件身份执行app/app.go、main.go。代码生成流水线布局生成仅new命令创建工程骨架——含 Hertz server 启动代码的main.go、含依赖声明的go.mod、路由注册入口router.go以及biz/handler/、biz/model/、biz/router/目录结构。默认main.go模板内容为server.Default()register(h)h.Spin()可直接在 generator/layout_tpl.go 中查看完整默认布局含biz/dal、biz/service、script、conf等目录也在该文件中定义插件执行IDL 编译器解析.thrift/.proto文件后把 AST 传给插件模式下的 hz。插件先转换AST 为内部的Service与HttpMethod结构体提取 HTTP 注解路径、方法、序列化方式再解析跨 IDL 文件的类型引用为 Go import 路径最后通过HttpPackageGenerator生成代码Handler 生成见上文--handler_by_method说明路由生成路由以树结构RouterNode组织通过插入每个方法的 HTTP path 构建随后遍历树为中间件分组分配唯一名称DyeGroupName渲染为r.Group()/r.GET()等 Go 路由注册代码并为每个路由组生成中间件 stub模板系统支持自定义定界符、三种 update 行为、按 service/method 循环生成以及通过--customize_package覆盖任意默认模板。.hz清单文件与参数传递项目根目录的.hzYAML 文件由hz new生成记录了三类信息生成该项目所用的 hz 版本handler、model、router 目录路径。这使hz update无需用户重复指定全部参数即可定位已有生成代码——update命令会先通过InitAndValidate加载并校验.hz缺失或版本非法都会报错再用其中的目录信息补全参数app/app.go、meta/manifest.go。.hz文件内容大致形如// Code generated by hz. DO NOT EDIT. hz version: v0.9.7 handlerDir: biz/handler modelDir: biz/model routerDir: biz/router由于插件是 IDL 编译器的子进程而非 hz 的直接子进程CLI 与插件之间的参数传递通过反射序列化完成util.PackArgs将参数打成逗号分隔字符串经编译器插件选项透传插件再用util.UnpackArgs反序列化还原DESIGN.md。格式形如FieldNamevalue,SliceFieldval1;val2;val3,MapFieldk1v1;k2v2。小结hz 为 Hertz 项目提供了一条IDL 即代码的完整链路new搭建骨架、update增量演进、model单独产出数据层、client一键生成调用方。通过丰富的 tag 风格选项、编译器参数透传、可深度定制的模板系统以及.hz清单驱动的增量更新机制它能够稳定适配从个人微服务到大规模团队协作的代码生成需求。若需深入源码建议从 app/app.go命令编排、generator生成引擎、thrift 与 protobuf两套 IDL 插件三条主线入手阅读。【免费下载链接】hertzGo HTTP framework with high-performance and strong-extensibility for building micro-services.项目地址: https://gitcode.com/GitHub_Trending/he/hertz创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考