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.


go install

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}}

Notice: kitex will creates symbol links to itself, so please ensure kitex has a write permission to the directory where it is placed.

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 (so called ‘thrift-gen-kitex’) generates some glue codes, too. For protobuf IDLs, the process is similar.

Thus, the name of the kitex executable when it is run decides its running mode – as a command line entry or a plugin (either thriftgo’s or protoc’s). So the directory where kitex is installed must be writable by kitex for it to creates necessary symbol links to distinguish each running mode.

$> kitex IDL
    | thrift-IDL
    |---------> thriftgo --gen go:... -plugin=... -out ... IDL
    |        |
    |        -----> thrift-gen-kitex (symbol link to kitex)
    | protobuf-IDL
    ----------> protoc --kitex_out=... --kitex_opt=... IDL
             -----> protoc-gen-kitex (symbol link to kitex)

Library Dependencies

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

  • For thrift IDLs, it is v0.13.0
  • For protobuf IDLs, it is v1.26.0

It is important to note that, from v0.14.0, the APIs in 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

or force the version with a replace command:

go mod edit -replace

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 = ""; // or hello/world

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


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:

├──                     // 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.
    └──             // The bootstraip script of server. Will be copied to output by

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


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/, the import path of kitex_gen/example_package/example_package.go for other package will be

  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 (default value) and 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.


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.