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

最后修改 November 14, 2024 : Feat: Documentation for Monolake (#1165) (2667d6a)