IDL 注解说明

hz 提供的 IDL 注解说明。

支持的 api 注解

Field 注解可用于 参数绑定及校验

Method 注解可用于生成路由注册相关代码

支持的 api 注解

hz

Field 注解 tag 说明可参考 支持的-tag。

Field 注解
注解说明
api.raw_body生成 “raw_body” tag
api.query生成 “query” tag
api.header生成 “header” tag
api.cookie生成 “cookie” tag
api.body生成 “json” tag
api.path生成 “path” tag
api.form生成 “form” tag
api.go_tag (protobuf)
go.tag (thrift)		透传 go_tag，会生成 go_tag 里定义的内容
api.vd生成 “vd” tag
api.none生成 “-” tag，详情参考 api.none 注解说明
Method 注解
注解说明
api.get定义 GET 方法及路由
api.post定义 POST 方法及路由
api.put定义 PUT 方法及路由
api.delete定义 DELETE 方法及路由
api.patch定义 PATCH 方法及路由
api.options定义 OPTIONS 方法及路由
api.head定义 HEAD 方法及路由
api.any定义 ANY 方法及路由

hz client

除 hz 提供的注解外，为针对 client 的场景，额外增加了一种注解。

Client 注解
注解说明
api.base_domain指定默认访问的请求 domain

使用方法

Field 注解

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 注解

Thrift：

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

Protobuf:

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

Client 注解

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";
}

最后修改 May 19, 2024 : docs: add FAQ and best practice docs (#1060) (c7da1fe)