Getting Started

Set Up Golang Development Environment

  1. If you haven’t set up your Golang Environment, you can refer to Golang Install.
  2. We recommend you to use the Golang latest version, or make sure it’s >= v1.15. You can choose to use the earlier versions, but the compatibility and stability are not assured.
  3. Make sure the go mod support is on (for Golang versions >= v1.15, it is on by default).

Currently, Hertz supports Linux, macOS, and Windows systems.

Quick Start

After you have prepared the Golang environment, the chapter will help you to quickly get familiar with Hertz.

Install the commend tool of hz

First, you need to install the commend tool hz which is used in this chapter

  1. Confirm the GOPATH environment has been defined correctly (For example export GOPATH=~/go) and the $GOPATH/bin has been added to PATH environment (For example export PATH=$GOPATH/bin:$PATH); Attention, do not set GOPATH to a directory that the current user does not have read/write access to.
  2. Install hz: go install github.com/cloudwego/hertz/cmd/hz@latest

For more information on how to use hz, please refer to: hz

Determine Where to Store Your Code

  1. If your codes are placed under $GOPATH/src, you need to create additional dictionary under $GOPATH/src and retrieve your code under the dictionary.
  $ mkdir -p $(go env GOPATH)/src/github.com/cloudwego
  $ cd $(go env GOPATH)/src/github.com/cloudwego
  1. If your codes are not placed under GOPATH, you can retrieve them directly.

Generate/Complete the Sample Code

  1. Create the hertz_demo folder in the current directory and go to that directory
  2. Generate code hz new
  3. Tidy & get dependencies
$ go mod tidy

If you are currently using a Windows system, you can write the following sample code.

  1. Create the hertz_demo folder in the current directory and go to that directory
  2. Create the main.go file
  3. Add the following code to the main.go file
package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
)

func main() {
    h := server.Default()

    h.GET("/ping", func(c context.Context, ctx *app.RequestContext) {
            ctx.JSON(consts.StatusOK, utils.H{"ping": "pong"})
    })

    h.Spin()
}
  1. Generate the go.mod file
  $ go mod init hertz_demo
  1. Tidy & get dependencies
  $ go mod tidy

Run the Sample Code

After you have completed the previous steps, you are able to compile & launch the server

$ go build -o hertz_demo && ./hertz_demo

If the server is launched successfully, you will see following message

2022/05/17 21:47:09.626332 engine.go:567: [Debug] HERTZ: Method=GET    absolutePath=/ping   --> handlerName=main.main.func1 (num=2 handlers)
2022/05/17 21:47:09.629874 transport.go:84: [Info] HERTZ: HTTP server listening on address=[::]:8888

Then, we can test the interface

$ curl http://127.0.0.1:8888/ping

If nothing goes wrong, we can see the following output

$ {"ping":"pong"}

Now, you have already launched Hertz Server successfully and completed an API call. More API examples can be found at API Examples.

As for the project dictionary layout, here is a project layout sample that you can refer to. You can also organize the layout based on your business scenario.

Directory Structure

As for the project directory structure, you may check Project Layout for reference, it can be organized according to the actual situation of the business logic.

More examples

Please refer:hertz-examples


Last modified December 2, 2022 : chore: add lark footer link (#460) (f41a884)