note
Location of biz layer code generation when using protobuf IDL
hz currently supports the syntax of proto2 / proto3.
Location of model files
We hope that users specify go_package when defining the protobuf IDL, so that one is consistent with the semantics of protobuf and the location of the generated model can be determined by go_package. If the user does not specify go_package, hz will default the package of the proto file to go_package, which may have some unintended naming conflicts.
At present, hz has implemented some processing on “go_package” for the model generated for unified management, with the following rules:
Assuming the current project is (module=github.com/a/b):
- go_package=“github.com/a/b/c/d”: Generate code under “/biz/model/c/d”;
- go_package=“github.com/a/b/biz/model/c/d”: Model will be generated under “/biz/model/c/d”, where “biz/model” is the default model generation path and can be modified using the “–model_dir” option;
- go_package=“x/y/z”: Generate code under “biz/model/x/y/z” (relative path completion);
- go_package=“biz/model/c/d”: Generate code under “biz/model/biz/model/c/d”.
It is recommended that users define “go_package” such as “{$MODULE}/{$MODEL_DIR}/x/y/z” (where {$MODEL_DIR} defaults to “biz/model”, and users can also use the “model_dir” option to define it).
The location of the handler file
The handler file will take the last level of go_package as the generation path.
For example, if go_package = “hello.world”, the generated path will be:
${project path}/${handler_dir}/world
The location of the router file
The router registration file will also take the last level of go_package as the generation path.
For example, if go_package = “hello.world”, the generated path will be:
${project path}/${router_dir}/world
Location of biz layer code generation when using thrift IDL
hz has no special requirements for the definition of thrift IDL, it only needs to comply with the grammar specification. The code generation path will be related to the thrift namespace
For example, a namespace can be defined like this:
namespace go hello.world
The generated path of model will be:
${project path}/${model_dir}/hello/world
The handler file will take namespace as the generation path, and its generation path will be:
${project path}/${handler_dir}/hello/world
The router registration file will also take namespace as the generation path, and its generation path will be:
${project path}/${router_dir}/hello/world
Description of the behavior when using the update command
Notes on using custom path
For the convenience of user, hz provides custom handler paths, model paths, templates, etc. However, hz does not save the current project information when creating a new project, so it can be considered as a stateless update when using the update command. Therefore, for the same set of IDL in new and update, using different custom information may result in duplicate code, for example, as follows:
Create a new project:
hz new -idl demo.thrift // In this case, hz will generate the model under "biz/model"
Update an existing project:
hz update -idl demo.thrift --model_dir=my_model // In this case, hz will not update the model code under "biz/model", but under "my_model"; then the code under "biz/model" and "my_model" will be duplicated, and the new handler will depend on "my_model",while the previous handler will depend on "biz/model". In this case, you need to delete & change some code manually.
Therefore, we hope that user use the update command with custom paths “client_dir”, “model_dir”, “handler_dir”, preferably same as new.
Behavior of update handler
hz will generate handlers based on default/custom template when creating a new project, where each service generates a file that contains all the handler code defined by the service; if IDL defines multiple services, each service will generate a file, and these files are in the same path; for example:
// demo.thrift namespace go hello.example service Service1 { HelloResp Method1(1: HelloReq request) (api.get="/hello"); } service Service2 { HelloResp Method2(1: HelloReq request) (api.get="/new"); } // Then the handler file generated by the IDL is as follows: ${handler_dir}/${namespace}/service1.go -> method1 ${handler_dir}/${namespace}/service2.go -> method2
When a new method is added to the IDL, the handler template will be added at the end of the corresponding service file; note that the handler added here will use the default template, and the new service file will use a custom template if appropriate.
Behavior of update router
The router code generated by hz in new mainly includes the following three:
- biz/router/${namespace}/${idlName}.go: Each primary IDL generates a corresponding routing registration code file, which registers all the routes defined in the IDL in a routing group, and sets the default middleware.
- biz/router/${namespace}/middleware.go: The default middleware function corresponding to each primary IDL, which can be modified by the user to add specific middleware logic to a particular route.
biz/router/register.go: This file is responsible for calling the route registration generated by different IDL; for example, if i define service in both IDL “demo1.thrift” and “demo2.thrift”, then both files will generate the corresponding route registration code. register.go is responsible for calling the route registration functions of these two parts.
Based on the above description, a description of the router’s behavior during update is given:
biz/${namespace}/${idlName}.go: Regenerate based on IDL every time, users should not change the code of this file, otherwise the code will be lost.
- biz/${namespace}/middleware.go: Appends a currently unavailable middleware to the end each time.
- biz/router/register.go: If there is a new IDL, the route registration method of the new IDL will be inserted.
Notes on using Windows Operating System
Hz uses symlink
when creating & updating projects. For Windows, you may need to enable your device’s development mode to get permission for your Windows user.
When creating projects based on protobuf IDL, you need to manually download & install the protoc
command from https://github.com/protocolbuffers/protobuf/releases. If your protobuf IDL contains a dependency on the google/protobuf
package, you need to unzip protoc-win64.zip
and put everything under the include directory in the same directory as your protoc binary file.