Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/devimteam/microgen

Tool to generate go-kit microservices
https://github.com/devimteam/microgen

generator go gokit

Last synced: 21 days ago
JSON representation

Tool to generate go-kit microservices

Host: GitHub
URL: https://github.com/devimteam/microgen
Owner: devimteam
License: mit
Created: 2017-04-09T11:39:40.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2019-04-03T13:51:39.000Z (over 5 years ago)
Last Synced: 2024-08-05T15:05:31.574Z (4 months ago)
Topics: generator, go, gokit
Language: Go
Homepage:
Size: 716 KB
Stars: 151
Watchers: 9
Forks: 22
Open Issues: 16
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome - microgen - Tool to generate go-kit microservices (Go)

README

# Microgen

Tool to generate microservices, based on [go-kit](https://gokit.io/), 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
```

Note: If you have problems with building microgen, please, install [dep](https://github.com/golang/dep) and use `dep ensure` command to install correct versions of dependencies ([#29](https://github.com/devimteam/microgen/issues/29)).

## Usage
``` sh
microgen [OPTIONS]
```
microgen tool search in file first `type * interface` with docs, that contains `// @microgen`.

generation parameters provides through ["tags"](#tags) in interface docs after general `// @microgen` tag (space before @ __required__).

#### Recommended project layout
Microgen uses [standard-like](https://github.com/golang-standards/project-layout) layout for generating boilerplate.
Default layout of project:
```
├── cmd
│ └── user_service
│ └── main.go
├── pb
│ └── api.proto
├── service
│ ├── caching.go
│ ├── caching.microgen.go
│ ├── error_logging.microgen.go
│ ├── logging.microgen.go
│ ├── middleware.microgen.go
│ └── recovering.microgen.go
├── transport // And may be some others in future, NATS or AMQP for example
│ ├── grpc
│ │ ├── client.microgen.go
│ │ ├── protobuf_endpoint_converters.microgen.go
│ │ ├── protobuf_type_converters.microgen.go
│ │ └── server.microgen.go
│ ├── http
│ │ ├── client.microgen.go
│ │ ├── converters.microgen.go
│ │ └── server.microgen.go
│ ├── client.microgen.go
│ ├── endpoints.microgen.go
│ ├── exchanges.microgen.go
│ └── server.microgen.go
├── usersvc
│ ├── api.go
│ └── user.go
├── vendor/
├── Dockerfile
├── Gopkg.lock
├── Gopkg.toml
├── Makefile
└── README.md
```
##### root directory
Contains other dirs and top-level project files, like `Dockerfile, Makefile, Readme.md`, etc.
##### cmd
Contains applications.
##### transport
Contains all transport specific code for all transports: http, grpc, amqp, udp, and so on.
##### service
Middleware in past. Should contain service realisations and closures (middlewares).

If you need new implementation of service, just add directory `/v2/` or something else.
##### \
Contains domain-specific types.
##### and others
Contains everything you want, just separate them by purposes.

Q: How microgen generates for this layout?

A: `cd ; microgen -out=./..`

To find more, check examples folder.

### 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 |
| -v | 1 | Sets microgen verbose level. 0 - print only errors. |
| -help | false | Print usage information |
| -debug | false | Print all microgen messages. Equivalent to -v=100. |
| -.proto| | Package field in protobuf file. If not empty, service.proto file will be generated. |

\* __Required option__

### Markers
Markers is a general tags, that participate in generation process.
Typical syntax is: `// @:`

#### @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](#tags), separated by comma after `@microgen:`
Example:
```go
// @microgen middleware, logging
type StringService interface {
ServiceMethod(ctx context.Context) (err error)
}
```
#### @protobuf
Protobuf tag is used for package declaration of compiled with `protoc` grpc package.
Example:
```go
// @microgen grpc-server
// @protobuf github.com/user/repo/path/to/protobuf
type StringService interface {
ServiceMethod(ctx context.Context) (err error)
}
```
`@protobuf` tag is optional, but required for `grpc`, `grpc-server`, `grpc-client` generation.

#### @grpc-addr
This tag allows to add construction for default grpc server addr in generated grpc client.
```go
if addr == "" {
addr = "service.string.StringService"
}
```
Example:
```go
// @microgen grpc-client
// @grpc-addr service.string.StringService
type StringService interface {
ServiceMethod(ctx context.Context) (err error)
}
```

### Method's tags
#### @microgen -
Microgen will ignore method with this tag everywere it can.

```go
// @microgen main, logging
type StringService interface {
// @microgen -
Count(ctx context.Context, text string, symbol string) (count int, positions []int, err error)
}
```

#### @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 argument, it ignored by default.
Provide parameters names, separated by comma, to exclude them from logs.
Example:
```go
// @microgen logging
type FileService interface {
// @logs-ignore data
UploadFile(ctx context.Context, name string, data []byte) (link string, err error)
}
```

#### @logs-len
This tag is used for logging middleware. It prints length of parameters.
Example:
```go
// @microgen logging
type FileService interface {
// @logs-ignore data
// @logs-len data
UploadFile(ctx context.Context, name string, data []byte) (link string, err error)
}
```

#### @http-method
This tag is used for http server and client to set different from POST method. This tag has special validation rules for GET method.
Example:
```go
// @microgen logging
type StringService interface {
// @http-method GET
Count(ctx context.Context, text string, symbol string) (count int, positions []int, err error)
}
```

#### cache-key
This tag is used for caching middleware and allows user to write expression that should be used as key for cache instance.

Key may be any string: it will directly writes to generated code.

```go
// @microgen caching
type StringService interface {
// @cache-key strings.ToLower(text)
Count(ctx context.Context, text string, symbol string) (count int, positions []int, err error)
}
```

### Tags
All allowed tags for customize generation provided here.

| Tag | Description |
|:------------|:------------------------------------------------------------------------------------------------------------------------------|
| middleware | General application middleware interface. Generates every time. |
| logging | Middleware that writes to logger all request/response information with handled time. Generates every time. |
| error-logging | Middleware that writes to logger errors of method calls, if error is not nil. |
| recovering | Middleware that recovers panics and writes errors to logger. Generates every time. |
| caching | Middleware that caches responses of service. Adds missed functions. |
| grpc-client | Generates client for grpc transport with request/response encoders/decoders. Do not generates again if file exist. |
| grpc-server | Generates server for grpc transport with request/response encoders/decoders. Do not generates again if file exist. |
| grpc | Generates client and server for grpc transport with request/response encoders/decoders. Do not generates again if file exist. |
| http-client | Generates client for http transport with request/response encoders/decoders. Do not generates again if file exist. |
| http-server | Generates server for http transport with request/response encoders/decoders. Do not generates again if file exist. |
| http | Generates client and server for http transport with request/response encoders/decoders. Do not generates again if file exist. |
| main | Generates basic `package main` for starting service. Uses other tags for minimal user changes. |
| tracing | Generates options and params for opentracing. |
| metrics | Generates transport endpoints middlewares for common tracing purposes. |

## Example
You may find examples in `examples` directory, where `svc` contains all, what you need for successful generation, and `generated` contains what you will get after `microgen`.

Follow this short guide to try microgen tool.

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

import (
"context"

"github.com/devimteam/microgen/example/svc/entity"
)

// @microgen middleware, logging, grpc, http, recovering, main
// @protobuf github.com/devimteam/microgen/example/protobuf
type StringService interface {
// @logs-ignore ans, err
Uppercase(ctx context.Context, stringsMap map[string]string) (ans string, err error)
Count(ctx context.Context, text string, symbol string) (count int, positions []int, err error)
// @logs-len comments
TestCase(ctx context.Context, comments []*entity.Comment) (tree map[string]int, err error)
}
```
2. Open command line next to your `service.go`.
3. Enter `microgen`. __*__
4. You should see something like that:
```
@microgen 0.5.0
all files successfully generated
```
5. Now, add and generate protobuf file (if you use grpc transport) and write transport converters (from protobuf/json to golang and _vise versa_).
6. Use endpoints in your `package main` or wherever you want. (tag `main` generates some code for `package main`)

__*__ `GOPATH/bin` should be in your PATH.

## Interface declaration rules
For correct generation, please, follow rules below.

General:
* Interface should be valid golang code.
* 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](https://golang.org/pkg/context/)).
* Last result should be builtin `error` type.
---
GRPC and Protobuf:
* 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 `Request` or `Response` for request/response message respectively.
* Field names in _protobuf_ messages should be the same, as in interface methods (_protobuf_ - snake_case, interface - camelCase).
---
HTTP GET method (`// @http-method GET`)
* Parameters types should be `string`, `int`, `int32`, `int64`, `uint`, `uint32` or `uint64`.

## Dependency
list out of date!
After generation your service may depend on this packages:
```
"net/http" // for http purposes
"bytes"
"encoding/json" // for http purposes
"io/ioutil"
"strings"
"net" // for http and grpc listners
"net/url" // for http purposes
"fmt"
"context"
"time" // for logging
"os" // for signal handling and os.Stdout
"os/signal" // for signal handling
"syscall" // for signal handling
"errors" // for error handling

"google.golang.org/grpc" // for grpc purposes
"golang.org/x/net/context"
"github.com/go-kit/kit" // for grpc purposes
"github.com/golang/protobuf/ptypes/empty" // for grpc purposes
```