hz annotation

The IDL annotation provided by hz.

Supported api annotations

Field annotation can be used

for parameter binding and validation

Method annotation can be used to generate code that related to route registration

Supported api annotations

hz

Field annotation tag description can be referenced supported-tags.

Field annotation
annotationdescription
api.raw_bodygenerate “raw_body” tag
api.querygenerate “query” tag
api.headergenerate “header” tag
api.cookiegenerate “cookie” tag
api.bodygenerate “json” tag
api.pathgenerate “path” tag
api.formgenerate “form” tag
api.go_tag (protobuf)
go.tag (thrift)		passing go_tag through will generate the content defined in go_tag
api.vdgenerate “vd” tag
api.noneGenerate “-” tag, please refer to api.none annotation usage for details
Method annotation
annotationdescription
api.getdefine GET methods and routes
api.postdefine POST methods and routes
api.putdefine PUT methods and routes
api.deletedefine DELETE methods and routes
api.patchdefine PATCH methods and routes
api.optionsdefine OPTIONS methods and routes
api.headdefine HEAD methods and routes
api.anydefine ANY methods and routes

hz client

In addition to the annotations provided by hz, one additional annotation has been added for client scenarios.

Client annotation
annotationdescription
api.base_domainspecify the default access request domain

Usage

Field annotation

Thrift:

struct Demo {
    1: string Demo (api.query="demo", api.path="demo");
    2: string GoTag (go.tag="goTag:"tag"");
    3: string Vd (api.vd="$!='your string'");
}

Protobuf:

message Demo {
    string Demo = 1[(api.query) = "demo", (api.path) = "demo"];
    string GoTag = 2[(api.go_tag) = "goTag:\"tag\""];
    string Vd = 3[(api.vd) = "$!='your string'"];
}

Method annotation

Thrift:

service Demo {
    Resp Method(1: Req request) (api.get="/route");
}

Protobuf:

service Demo {
    rpc Method(Req) returns(Resp) {
        option (api.get) = "/route";
    }
}

Client annotation

Thrift：

struct Demo {
    1: string HeaderValue (api.header="file1");
}

service Demo {
    Resp Method(1: Req request) (api.get="/route");
}(
    api.base_domain="http://127.0.0.1:8888";
)

Protobuf:

message Demo {
    string HeaderValue = 1[(api.header) = "file1"];
}

service Demo {
    rpc Method(Req) returns(Resp) {
        option (api.get) = "/route";
    }
    option (api.base_domain) = "http://127.0.0.1:8888";
}

Last modified December 9, 2024 : Update prerequisite.md (#1178) (b5e2299)