hz

hz - Hertz Code Generator

hz is the official code generation tool for the Hertz HTTP framework. It parses IDL (Interface Definition Language) files — Thrift or Protobuf — and generates a complete, scaffolded Hertz project including handlers, routers, models, and client code.

Quick Start

# Build
cd cmd/hz && go build -o hz .

# Generate a new project from Thrift IDL
hz new --idl api.thrift --module github.com/example/myservice

# Generate a new project from Protobuf IDL
hz new --idl api.proto --module github.com/example/myservice

# Update an existing project after IDL changes (module read from go.mod)
hz update --idl api.thrift

# Generate model code only (module read from go.mod)
hz model --idl api.thrift

# Generate client code (module read from go.mod)
hz client --idl api.thrift --base_domain localhost:8888

Commands

Flags

Global

Project Structure

Code Generation

Struct Tags

IDL Compiler Options

Template Customization

Custom Templates

Create a YAML config file and pass it with --customize_package:

layouts:
  - path: biz/handler/handler.go        # overrides default handler template
    delims: ["{{", "}}"]
    body: |
      package {{.PackageName}}
      // your custom handler template...

  - path: biz/custom/{{.ServiceName}}.go  # new file, path supports templates
    delims: ["{{", "}}"]
    loop_service: true                     # generate one file per service
    update_behavior:
      type: append                         # on update: skip/cover/append
      append_key: method                   # append by method or service
      append_content_tpl: |
        // new method: {{.Name}}
    body: |
      package custom
      // your template...

Template update behaviors:

• skip — do not modify existing file
• cover — overwrite existing file completely
• append — append new content (e.g. new handler methods) to existing file

For middleware_single.go, MiddleWare is the default middleware name and RawName is that middleware name with its original method or path casing. It omits the generated leading underscore but retains any disambiguating suffix assigned by Hertz; the root remains root. Set update_behavior.insert_key to match a custom function name when checking for existing middleware. Without it, the default duplicate check is unchanged:

  - path: middleware_single.go
    update_behavior:
      insert_key: 'func {{if ne .MiddleWare "root"}}_{{end}}{{untitle .RawName}}Mw('
    body: |

      func {{if ne .MiddleWare "root"}}_{{end}}{{untitle .RawName}}Mw() []app.HandlerFunc {
        return nil
      }

Use matching names in router.go and the initial middleware.go template, where RawGroupMiddleware and RawHandlerMiddleware are available on each router node. For example, /:collectionUid can generate _collectionUidMw() and GetLLMResponse can generate _getLLMResponseMw(). Keep the built-in middleware.go template enabled for incremental updates.

Example Output

Run generate.sh to see what hz generates for the test IDL files:

cd cmd/hz

# Generate examples for all IDL types (output in generate_out/)
./generate.sh

# Generate specific targets only
./generate.sh thrift proto3

# CI mode: generate, verify the output compiles, then clean up
./generate.sh --verify --clean

Targets: thrift, proto2, proto3, handler_by_method.

Dependencies

• thriftgo — Thrift compiler (auto-installed if missing)
• protoc — Protobuf compiler (must be installed manually)

Architecture

See DESIGN.md for internal architecture, the dual-mode execution model, and the code generation pipeline.