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.
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 ofkitex_gen/example_package/example_package.go
for other package will beexample.com/hello/world/kitex_gen/example_package
.If the current directory is not a child path of
$GOPATH/src
, this option must be specified.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.
- If go.mod is not found, kitex will generated one with
-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.