Code Generation Tool

kitex is a command line tool for code generation provided by the RPC framework Kitex. At present, kitex accepts both thrift and protobuf IDLs, and supports generating a skeleton of a server side project.

Installation

go install github.com/cloudwego/kitex/tool/cmd/kitex@latest

You can use the go command to install kitex or build and install it from source. To check where kitex will be installed, try

go list -f {{.Target}} github.com/cloudwego/kitex/tool/cmd/kitex

Dependencies and Running Mode

The Underlying Compilers

To generate code for an IDL, the corresponding compiler must be installed ahead: thriftgo for thrift IDLs and protoc for protobuf IDLs.

Codes generated by kitex consists of two parts: some generated by the underlying compiler (usually serialization and deserialization codes for structures defined in the IDLs) and some glue codes generated by kitex to connect the former and the Kitex framework.

In a execution flow, when kitex is run to generate code for a thrift IDL, it invokes thriftgo to do code generation while itself as a plugin for thriftgo generates some glue codes, too. For protobuf IDLs, the process is similar.

$> kitex IDL
    |
    | thrift-IDL
    |---------> thriftgo --gen go:... -plugin=... -out ... IDL
    |
    | protobuf-IDL
    ----------> protoc --kitex_out=... --kitex_opt=... IDL

Library Dependencies

The codes generated by kitex may depends on certain Go libraries:

• For thrift IDLs, it is github.com/apache/thrift v0.13.0
• For protobuf IDLs, it is google.golang.org/protobuf v1.26.0

It is important to note that, from v0.14.0, the APIs in github.com/apache/thrift/lib/go/thrift are incompatible with previous versions. If you specify the -u flag when using go get to update dependencies, this library will be updated to the incompatible version and cause compilation failure. You can solve this problem by executing an extra command to choose the appropriate version:

go get github.com/apache/thrift@v0.13.0

or force the version with a replace command:

go mod edit -replace github.com/apache/thrift=github.com/apache/thrift@v0.13.0

Notes for Using Protobuf IDLs

The kitex only supports the proto3 version of the protocol buffers language.

The go_package option in the IDL is required. Its value is a package name sequence separated by dots (.) or by slashes (/). It determines the suffix of the result import path. For instance,

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

will generates an import path ${imoprt path of the current directory}/kitex_gen/hello/world.

If you assign a complete import path to go_package, then kitex will generate codes for this IDL only when the import path matches the kitex_gen directory. For example:

• go_package="${import path of current module}/kitex_gen/hello/world";: OK. Kitex will generate codes for this IDL;
• go_package="${import path of current module}/hello/world";: Kitex will not generate codes for this IDL;
• go_package="any.other.domain/some/module/kitex_gen/hello/world";: Kitex will not generate codes for this IDL;

You can overwrite the go_package value in a proto file with a command line option --protobuf Msome.proto=your.package.name/kitex_gen/wherever/you/like. For the usage of the option, please refer to the official document of Protocol Buffers.

Usage

Basic Usage

Syntax: kitex [options] IDL

The following examples uses thrift IDLs. Protobuf IDLs work the same way.

Generate Client Codes

kitex path_to_your_idl.thrift

When the command is done, there will be a folder named kitex_gen in the current directory. It contains data structure definitions from the IDL and some *service packages providing client APIs for the service definitions from the IDL.

Generate Serverr Codes

kitex -service service_name path_to_your_idl.thrift

When the command is done, in the current directory, there will be a folder named kitex_gen and some other files for building and running a server (namely a scaffold). See the description in section The Structure of Generated Codes.

The Structure of Generated Codes

Suppose we have two thrift IDLs, demo.thrift and base.thrift that demo.thrift includes base.thrift. In demo.thrift there is a service definition named demo.

Then in an empty directory, kitex -service demo dem.thrift produces a skeleton of project:

.
├── build.sh                     // A script to build a server. It creates necessary files and puts them into a folder named 'output'.
├── handler.go                   // Implementation of methods of the service defined in the IDL.
├── kitex_gen                    // IDL relevant generated codes.
│   ├── base                     // Code generated for base.thrift.
│   │   ├── base.go              // Output of thriftgo.
│   │   └── k-base.go            // Codes generated by kitex besides the output of thriftgo.
│   └── demo                     // Code generated for demo.thrift.
│       ├── demo.go              // Output of thriftgo.
│       ├── k-demo.go            // Codes generated by kitex besides the output of thriftgo.
│       └── demoservice          // Codes generated by kitex for services defined in demo.thrift.
│           ├── demoservice.go   // Provides some definitions shared by client.go and server.go.
│           ├── client.go        // Provides NewClient API.
│           └── server.go        // Provides NewServer API.
├── main.go                      // Entry of program.
└── script                       // Build scripts.
    └── bootstrap.sh             // The bootstraip script of server. Will be copied to output by build.sh.

If the -service flag is not specified, then only kitex_gen will be generated.

Options

The option description here may be outdated. Run kitex -h or kitex --help to get all usable options of kitex.

-service service_name

When this option is specified, kitex will generate a scaffold to build a server. Parameter service_name gives the name of the server itself when launched. Its value is usually up to the service registry and service disccovery components when using the Kitex framework.

-module module_name

This option is used to specify the Go module the generated codes belongs to. It affects import paths.

1. If the current directory is a child path of $GOPATH/src, this option can be omitted; kitex will use a path relative to $GOPATH/src as the prefix of import path in generated codes. For example, if you run kitex under $GOPATH/src/example.com/hello/world, the import path of kitex_gen/example_package/example_package.go for other package will be example.com/hello/world/kitex_gen/example_package.

2. If the current directory is not a child path of $GOPATH/src, this option must be specified.

3. If -module is specified, then kitex searches for go.mod from the current directory to the root.

   • If go.mod is not found, kitex will generated one with go mod init.
   • If go.mod is found, then kitex will check if the module name in go.mod is identical with the argument of -module; if they diffs, kitex will report an error and exit.
   • Finally, the position of go.mod and its module names determines the import path in generated codes.

-I path

Add a search path for IDLs.

-type type

Specify the type of IDLs. Currently available values are thrift and protobuf.

Kitex will guess the IDL type by the file extension. .thrift for thrift, .proto for protobuf.

-v or -verbose

Output more logs.

Advanced Options

-use path

When generating server codes (with -service), the -use option stops kitex from generating the kitex_gen and uses the import path given by the argument instead.

-combine-service

For thrift IDLs, when generating codes for a server, kitex only generates methods for the last service definition in the IDL. If there are multiple services in the IDL and you want to export all their abilities, the -combine-service option is for that.

This option creates a CombineService that assembles all methods of services in the target IDL and uses it in the main package. Notice that no two methods of services can have the same name.

-protobuf value

Pass an argument to protoc. The argument will be appended to the -go_out for protoc. See the documentation of protoc for available values.

-thrift value

Pass an argument to thriftgo. The argument will be appended to the -g go: for thriftgo. See the documentation of thriftgo for available values.

Kitex by default passes naming_style=golint,ignore_initialisms,gen_setter,gen_deep_equal to thriftgo and it can be overridden if you specify the same parameter in addition.