note

Notes on using protobuf IDL

hz currently supports the syntax of proto2 / proto3.

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.

For example, go_package can be defined like this:

option go_package = "hello.world"; // or hello/world

The generated path of model will be:

${project path}/${model_dir}/hello/world

The handler file will take the last level of go_package as the generation path, and its generation path will be:

${project path}/${handler_dir}/world

The router registration file will also take the last level of the go_package as the generation path, and the generation path will be:

${project path}/biz/router/world

Notes on 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}/biz/router/hello/world

Description of the behavior when using the update command

1. 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.

2. 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.

3. 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.