microgen

README

Microgen

Tool to generate microservices, based on go-kit, by specified service interface.
The goal is to generate code for service which not fun to write but it should be written.

Install

go get -u github.com/devimteam/microgen/cmd/microgen

Usage

microgen [OPTIONS]

microgen tool search in file first type * interface with docs, that contains // @microgen.

generation parameters provides through "tags" in interface docs after general // @microgen tag (space before @ required).

Options

Name	Default	Description
-file	service.go	Relative path to source file with service interface
-out	.	Relative or absolute path to directory, where you want to see generated files
-force	false	With flag generate stub methods.
-help	false	Print usage information

* Required option

Markers

Markers is a general tags, that participate in generation process. Typical syntax is: // @<tag-name>:

@microgen

Main tag for microgen tool. Microgen scan file for the first interface which docs contains this tag.
To add templates for generation, add their tags, separated by comma after @microgen: Example:

// @microgen middleware, logging
type StringService interface {
    ServiceMethod()
}

@protobuf

Protobuf tag is used for package declaration of compiled with protoc grpc package.
Example:

// @microgen grpc-server
// @protobuf github.com/user/repo/path/to/protobuf
type StringService interface {
    ServiceMethod()
}

@protobuf tag is optional, but required for grpc, grpc-server, grpc-client generation.

@grpc-addr

gRPC address tag is used for gRPC go-kit-based client generation. Example:

// @microgen grpc
// @protobuf github.com/user/repo/path/to/protobuf
// @grpc-addr some.service.address
type StringService interface {
    ServiceMethod()
}

@grpc-addr tag is optional, but required for grpc-client generation.

Method's tags

@logs-ignore

This tag is used for logging middleware, when some arguments or results should not be logged, e.g. passwords or files.
If context.Context is first, it ignored by default.
Provide parameters names, separated by comma, to exclude them from logs.
Example:

// @microgen logging
type FileService interface {
    // @logs-ignore data
    UploadFile(ctx context.Context, name string, data []byte) (link string, err error)
}

Tags

All allowed tags for customize generation provided here.

Tag	Description
middleware	General application middleware interface
logging	Middleware that writes to logger all request/response information with handled time
grpc-client	Generates client for grpc transport with request/response encoders/decoders
grpc-server	Generates server for grpc transport with request/response encoders/decoders
grpc	Generates client and server for grpc transport with request/response encoders/decoders

Example

Follow this short guide to try microgen tool.

1. Create file service.go inside GOPATH and add code below.

package stringsvc

import (
    "context"

    drive "google.golang.org/api/drive/v3"
)

// @microgen grpc, middleware, logging
// @protobuf github.com/devimteam/proto-utils
// @grpc-addr test.address
type StringService interface {
    Uppercase(ctx context.Context, str string) (ans string, err error)
    Count(ctx context.Context, text string, symbol string) (count int, positions []int)
    TestCase(ctx context.Context, comments []*drive.Comment) (err error)
}

1. Open command line next to your service.go.
2. Enter microgen. *
3. You should see something like that:

exchanges.go
endpoints.go
client.go
middleware/middleware.go
middleware/logging.go
transport/grpc/server.go
transport/grpc/client.go
transport/converter/protobuf/endpoint_converters.go
transport/converter/protobuf/type_converters.go
All files successfully generated

1. Now, add and generate protobuf file, write converters from protobuf to golang and vise versa.
2. Use endpoints and converters in your package main or wherever you want.

* GOPATH/bin should be in your PATH.

Interface declaration rules

For correct generation, please, follow rules below.

• All interface method's arguments and results should be named and should be different (name duplicating unacceptable).
• First argument of each method should be of type context.Context (from standard library).
• Last result should should be error type.

---

• Name of protobuf service should be the same, as interface name.
• Function names in protobuf should be the same, as in interface.
• Message names in protobuf should be named <FunctionName>Request or <FunctionName>Response for request/response message respectively.
• Field names in protobuf messages should be the same, as in interface methods (protobuf - snake_case, interface - camelCase).