模板拓展
cwgo 工具也支持传递自己的模板,模版语法为 go template 的语法。cwgo 也欢迎用户贡献自己的模板。由于 RPC 和 HTTP 概念不同,其对应的模版变量也有一些差异,详细请参考下文。
如需传递自定义模板,请给命令添加 -template
参数,如:
cwgo server -type RPC -service {service name} -idl {idl path} -template {tpl path}
模板读取
cwgo 支持从本地或 git 中读取模板。其中 git 支持 https 或 ssh 的形式,-template
指定模板路径,-branch
指定模板分支(默认为主分支)。
RPC Server、Client, HTTP Server、Client 均支持模板拓展,具体用法见下文。
本地
cwgo server -type RPC -service {service name} -idl {idl path} -template {local tpl path}
git https
cwgo server -type RPC -service {service name} -idl {idl path} -template https://github.com/***/cwgo_template.git -branch {branch path}
git ssh
cwgo server -type RPC -service {service name} -idl {idl path} -template git@github.com:***/cwgo_template.git -branch {branch path}
RPC
模板文件通过包含 yaml 文件的文件夹传递,该文件夹下的所有 yaml 文件都会被渲染,模版解析失败会直接退出。请注意是否存在未知的隐藏文件。
Yaml 文件定义如下:
# 生成文件的路径及文件名,这会在项目根目录下创建 a 文件夹,并在文件夹内生成 main.go 文件,支持模版渲染语法 path: /handler/{{ .Name }}.go update_behavior: type: skip / cover / append # 指定更新行为,如果 loop_method 为true,则不支持 append。默认是 skip key: Test{{.Name}} # 查找的函数名,如果渲染后的函数名存在,则认为该方法不用追加 append_tpl: # 更新的内容模板 import_tpl: # 新增的 import 内容,是一个 list,可以通过模版渲染 loop_method: true # 是否开启循环渲染 body: template content # 模板内容
extensions.yaml
为特定文件,该文件的内容为扩展 Service 代码的配置文件。请注意文件命名冲突问题。模板使用的数据为 PackageInfo,认为这部分内包含所有的元数据,如 methodInfo 等,用户只需要传递模板文件即可,模板内的数据为 PackageInfo 数据。PackageInfo 内常用的内容见附录。
cwgo 支持根据 methodInfo 循环渲染文件。循环渲染时的 methodInfo list 内只有一个元素,为当前正在渲染的 method。
更新时,目前支持覆盖、跳过和根据 methods 增加文件三种,支持在一个文件当中 append。如果开启了循环渲染文件,则只支持 skip 和 cover。
最佳实践的 rpc 示例 tpl 可参考这里。
HTTP
- 模版文件通过 yaml 文件夹传递,但是与 RPC 的 layout 不同的是 HTTP 的 layout 是基于 hertz 的自定义模版实现的,这里我们需要指定的 yaml 文件名需要固定为
layout.yaml
与package.yaml
,对于自定义模版的使用可以参考 Hz 自定义模版使用文档。
最佳实践的 http 示例 tpl 可参考这里。
附录
Kitex PackageInfo 结构体含义
type PackageInfo struct {
Namespace string // idl namespace,pb 下建议不要使用
Dependencies map[string]string // package name => import path, used for searching imports
*ServiceInfo // the target service
Codec string
NoFastAPI bool
Version string
RealServiceName string
Imports map[string]map[string]bool
ExternalKitexGen string
Features []feature
FrugalPretouch bool
Module string // go module 名称
}
type ServiceInfo struct {
PkgInfo
ServiceName string
RawServiceName string
ServiceTypeName func() string
Base *ServiceInfo
Methods []*MethodInfo
CombineServices []*ServiceInfo
HasStreaming bool
}
type PkgInfo struct {
PkgName string // namespace 最后一段
PkgRefName string
ImportPath string // 这个方法的 req 和 resp 的 import path
}
type MethodInfo struct {
PkgInfo
ServiceName string // 这个 service 的 name
Name string // 这个 method 的 name
RawName string // 同上
Oneway bool
Void bool
Args []*Parameter // 入参信息,包括入参名称、import 路径、类型
Resp *Parameter // 出参,包括入参名称、import 路径、类型
Exceptions []*Parameter
ArgStructName string
ResStructName string
IsResponseNeedRedirect bool // int -> int*
GenArgResultStruct bool
ClientStreaming bool
ServerStreaming bool
}
最后修改
November 29, 2024
: Update protobuf.md (#1176) (16ce168)