Hertz Documentation

Hertz is a high-performance, high-usability, and highly extensible Golang HTTP framework designed for building microservices. It is inspired by frameworks like Gin and Echo but optimized for high-performance requirements.

Key features include:

• High Performance: Uses the Netpoll network library by default, offering advantages in QPS and latency compared to the standard Go Net library.
• Multi-protocol Support: Natively supports HTTP/1.1 and ALPN, with support for custom protocol resolution logic.
• Network Layer Flexibility: Allows switching between Netpoll and Go Net, or extending the network layer via plugins.
• Extensibility: Features a layered design that supports extensions for protocols, network libraries, loggers, and monitoring.

Hertz provides several core capabilities:

• High Performance: Uses the Netpoll high-performance network library by default, offering advantages in QPS and latency over the standard Go net library.
• High Extensibility: Employs a layered design that allows users to extend network libraries, protocols, logging, monitoring, and service discovery.
• Multi-protocol Support: Natively supports HTTP/1.1 and ALPN. The layered design allows for custom protocol parsing logic.
• Network Layer Switching: Allows users to switch between Netpoll and the standard Go network library on demand or extend it via plugins.

Hertz v0.3.0 introduced several components for service discovery and registration:

• Service Registration: Use the WithRegistry option on the server to register services.
• Service Discovery: Use the Discovery client middleware to integrate with service discovery systems. The discovery package provides Resolver, Instance, Result, and NewInstance types.
• Registry: The registry package provides Registry and Info types for managing service registration.
• Load Balancing: The loadbalance package provides a Loadbalancer interface and NewWeightedBalancer for weighted random load balancing.

If you only need the Go struct definitions (models) without the full project scaffolding, use the model command. The module name is read from your go.mod file.

hz model --idl api.thrift

Use the client command to generate a Hertz HTTP client based on your service definitions.

Key Flags:

• --idl: Path to the IDL file.
• --base_domain: The default request domain for the generated client (e.g., localhost:8888).
• --client_dir: The output directory for client code. If omitted, it defaults to a path derived from the IDL namespace.
• --force_client_dir: If used, the client is output without IDL namespace subdirectories.
• --force_client: Force regeneration of hertz_client.go even if it exists.
• --query_enumint: Use numeric values for enum query parameters in the client.
• --enable_optional: Omit optional Thrift fields from queries if they are not set.

hz client --idl api.thrift --base_domain localhost:8888

To begin using Hertz, you can follow the official guides:

• Quick Start: Follow the Getting Started guide for initial setup.
• Examples: Browse the Hertz-Examples repository for ready-to-use code snippets and tutorials.

To use the hz CLI, you must first build it from the source code.

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

Hertz provides options to set timeouts for both servers and clients, as well as per-request configurations.

Server/Client Options: Use WithWriteTimeout to set a write timeout.

Per-request Options: Use the following options to configure specific requests:

• WithDialTimeout
• WithReadTimeout
• WithWriteTimeout

Error Handling: When a timeout occurs, the following errors are returned:

• ErrReadTimeout
• ErrWriteTimeout
• ErrDialTimeout