hz usage(thrift)

Create a project based on thrift IDL

new: Create a new project

  1. Create the thrift IDL file in the current directory

    // idl/hello.thrift
    namespace go hello.example
    
    struct HelloReq {
        1: string Name (api.query="name"); // Add api annotations for easier parameter binding
    }
    
    struct HelloResp {
        1: string RespBody;
    }
    
    
    service HelloService {
        HelloResp HelloMethod(1: HelloReq request) (api.get="/hello");
    }
    
  2. Create a new project

    # For projects not under `$GOPATH`, specify a custom module name through the `-module` command provided by the tool:
    hz new -module example.com/m -idl idl/hello.thrift
    
    # Tidy & get dependencies
    go mod tidy
    
    # Check whether the github.com/apache/thrift version in go.mod is v0.13.0, if not, continue to execute the remaining code in section 2.2
    go mod edit -replace github.com/apache/thrift=github.com/apache/thrift@v0.13.0
    
    # Tidy & get dependencies
    go mod tidy
    
    # If the current project path is under `$GOPATH`, execute the following code block
    hz new -idl idl/hello.thrift
    
    go mod init
    
    go mod edit -replace github.com/apache/thrift=github.com/apache/thrift@v0.13.0
    
    # Tidy & get dependencies
    go mod tidy
    
  3. Modify the handler and add your own logic

    // handler path: biz/handler/hello/example/hello_service.go
    // where "hello/example" is the namespace of thrift IDL
    // "hello_service.go" is the name of the service in the thrift IDL, all methods defined by the service will be generated in this file
    
    // HelloMethod .
    // @router /hello [GET]
    func HelloMethod(ctx context.Context, c *app.RequestContext) {
            var err error
            var req example.HelloReq
            err = c.BindAndValidate(&req)
            if err != nil {
                    c.String(400, err.Error())
                    return
            }
    
            resp := new(example.HelloResp)
    
            // You can modify the logic of the entire function, not just the current template
            resp.RespBody = "hello," + req.Name // added logic
    
            c.JSON(200, resp)
    }
    
  4. Compile the project

    go build
    
  5. Run the project and test it

    Run the project:

    ./{{your binary}}
    

    Test:

    curl --location --request GET 'http://127.0.0.1:8888/hello?name=hertz'
    

    If it returns {"RespBody":"hello,hertz"}, it works.

update: Update an existing project

  1. If your thrift IDL is updated, for example:

    // idl/hello.thrift
    namespace go hello.example
    
    struct HelloReq {
        1: string Name (api.query="name");
    }
    
    struct HelloResp {
        1: string RespBody;
    }
    
    struct OtherReq {
        1: string Other (api.body="other");
    }
    
    struct OtherResp {
        1: string Resp;
    }
    
    
    service HelloService {
        HelloResp HelloMethod(1: HelloReq request) (api.get="/hello");
        OtherResp OtherMethod(1: OtherReq request) (api.post="/other");
    }
    
    service NewService {
        HelloResp NewMethod(1: HelloReq request) (api.get="/new");
    }
    
  2. Switch to the directory where the new command was executed and update the modified thrift IDL

    hz update -idl idl/hello.thrift
    
  3. As you can see

    Add new method under “biz/handler/hello/example/hello_service.go”
    The file “new_service.go” and the corresponding “NewMethod” method have been added under “biz/handler/hello/example”

    Now let’s develop the “OtherMethod” interface:

    // HelloMethod .
    // @router /hello [GET]
    func HelloMethod(ctx context.Context, c *app.RequestContext) {
    var err error
    var req example.HelloReq
    err = c.BindAndValidate(&req)
    if err != nil {
        c.String(400, err.Error())
        return
    }
    
    resp := new(example.HelloResp)
    
    // You can modify the logic of the entire function, not just the current template
    resp.RespBody = "hello," + req.Name // added logic
    
    c.JSON(200, resp)
    }
    
    // OtherMethod .
    // @router /other [POST]
    func OtherMethod(ctx context.Context, c *app.RequestContext) {
    var err error
    // The model file corresponding to example.OtherReq will also be regenerated
    var req example.OtherReq
    err = c.BindAndValidate(&req)
    if err != nil {
        c.String(400, err.Error())
        return
    }
    
    resp := new(example.OtherResp)
    
    // added logic
    resp.Resp = "Other method: " + req.Other
    
    c.JSON(200, resp)
    }
    
  4. Compile the project

    go build
    
  5. Run the project and test it

    Run the project:

    ./{{your binary}}
    

    Test:

    curl --location --request POST 'http://127.0.0.1:8888/other' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "Other": "other method"
    }'
    

    If it returns {"Resp":"Other method: other method"}, it works.


Last modified August 6, 2023 : docs: hz directory modification (#754) (20d9ea6)