hz access plugin
Currently, hz code generation is based on the plugin model of “thriftgo” and “protoc”, which is a great help in accessing some third party plugins, especially for “protoc” which currently supports a rich plugin ecosystem.
So hz provides the means to extend third-party plug-ins.
ThriftGo Plugin
Usage
hz new --idl={YOUR-IDL.thrift} --thrift-plugins={PLUGIN-NAME}
If the plugin needs to pass some options, they are as follows:
hertztool new --idl={YOUR-IDL.thrift} --thrift-plugins={PLUGIN-NAME}:{YOUR-OPTION1,YOUR-OPTION2}
Example
Currently, thriftgo
provides a plugin “thrift-gen-validator” for generating structural parameter validation functions that can be generated along with the model.
-
Install :
go install github.com/cloudwego/thrift-gen-validator@latest
-
Use :
hz new --idl=idl/hello.thrift --thrift-plugins=validator
-
Code : code
Protoc Plugin
go_package Detail
The path to the go file generated by the Protoc plugin depends on the definition of the “go_package” option. So let’s take a closer look at the role of “go_package”: “option go_package” in the proto file refers to the import location of the go file generated by this file, as follows
If the go_package option is defined this way:
option go_package = "github.com/a/b/c";
If you then want to cite the content that generated it, you can do so as follows:
import "github.com/a/b/c"
var req c.XXXStruct
In addition, the “option go_package” is also related to the path to the generated code. It is as follows:
If the option go_package is defined this way:
// psm.proto
option go_package = "github.com/a/b/c";
The generated go file will be located at: github.com/a/b/c/psm.pb.go
In addition, “option go_package” can be used in conjunction with the go module as follows
If the option go_package is defined like this:
// psm.proto
option go_package = "github.com/a/b/c";
Initialize the go module
go mod init github.com/a/b
Generate code and specify module
protoc go_out=. --go_opt=module=github.com/a/b psm.proto
Then the generated file will be: c/psm.pb.go
However, since the module for this project is “github.com/a/b”; so, if you refer to the generated content of this file,
the import path would still be “github.com/a/b/c”
Usage
Currently, hz is doing some processing of “go_package” in order to unify the generated models, with the following rules:
Suppose the current project is github.com/a/b:
- go_package=“github.com/a/b/c/d”: the code will be generated under “/biz/model/c/d”; (no change)
- go_package=“github.com/a/b/biz/model/c/d”: will generate the model under “/biz/model/c/d”, where “biz/model” is the default model generation path, which can be changed with the “-model_dir” option.
- go_package=“x/y/z”: will generate the code under “biz/model/x/y/z” (relative path completion) (no change).
- go_package=“google.com/whatever”: no code (external IDL) will be generated (no change).
- go_package=“github.com/a/b/c”: code will be generated under “biz/model/c” (no change).
So you can simply define a “go_package” such as “{$MODULE}/{$MODEL_DIR}/x/y/z” (where {$MODEL_DIR} defaults to “biz/model”, or you can use the “model_dir” option to define it) to enable access to third-party plugins on the hz side.
Use the command :
hertztool new --idl={YOUR-IDL.proto} --protoc-plugins={PLUGIN_NAME}:{OPTION1,OPTION2}:{OUT_DIR} --mod={YOUR_MODULE}
Example
Here is an example of using the Hz integration protoc-gen-openapi
plugin to generate openapi 3.0 documentation.
-
Install :
go install github.com/google/gnostic/cmd/protoc-gen-openapi@latest
-
Define go_package for idl: “middleware/hertz/biz/model/psm”
-
Usage :
hz new -I=idl --idl=idl/hello/hello.proto --protoc-plugins=openapi::./docs --mod=middleware/hertz
-
Code : code