README ¶
Go Micro
Go Micro is a pluggable RPC framework for distributed systems development.
The Micro philosophy is sane defaults with a pluggable architecture. We provide defaults to get you started quickly but everything can be easily swapped out. It comes with built in support for {json,proto}-rpc encoding, consul or multicast dns for service discovery, http for communication and random hashed client side load balancing.
Everything in go-micro is pluggable. You can find and contribute to plugins at github.com/micro/go-plugins.
Follow us on Twitter or join the Slack community.
Features
Go Micro abstracts away the details of distributed systems. Here are the main features.
- Service Discovery - Automatic service registration and name resolution
- Load Balancing - Client side load balancing built on discovery
- Sync Comms - RPC based communication with support for bidirectional streaming
- Async Comms - Native PubSub messaging built in for event driven architectures
- Message Encoding - Dynamic encoding based on content-type with protobuf and json out of the box
- Service Interface - All features are wrapped up in a simple high level interface
Go Micro supports both the Service and Function programming models. Read on to learn more.
Docs
For more detailed information on the architecture, installation and use of go-micro checkout the docs.
Learn By Example
An example service can be found in examples/service and function in examples/function.
The examples directory contains examples for using things such as middleware/wrappers, selector filters, pub/sub, grpc, plugins and much more. For the complete greeter example look at examples/greeter. Other examples can be found throughout the GitHub repository.
Watch the Golang UK Conf 2016 video for a high level overview.
Getting started
Service Discovery
Service discovery is used to resolve service names to addresses. It's the only dependency of go-micro.
Consul
Consul is used as the default service discovery system.
Discovery is pluggable. Find plugins for etcd, kubernetes, zookeeper and more in the micro/go-plugins repo.
Multicast DNS
Multicast DNS is a built in service discovery plugin for a zero dependency configuration.
Pass --registry=mdns
to any command or the enviroment variable MICRO_REGISTRY=mdns
go run main.go --registry=mdns
Writing a service
This is a simple greeter RPC service example
Find this example at examples/service.
Create service proto
One of the key requirements of microservices is strongly defined interfaces. Micro uses protobuf to achieve this.
Here we define the Greeter handler with the method Hello. It takes a HelloRequest and HelloResponse both with one string arguments.
syntax = "proto3";
service Greeter {
rpc Hello(HelloRequest) returns (HelloResponse) {}
}
message HelloRequest {
string name = 1;
}
message HelloResponse {
string greeting = 2;
}
Install protobuf
Install protobuf
Now install the micro fork of protoc-gen-go. The protobuf compiler for Go.
go get github.com/micro/protobuf/{proto,protoc-gen-go}
Generate the proto
After writing the proto definition we must compile it using protoc with the micro plugin.
protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src \
$GOPATH/src/github.com/micro/examples/service/proto/greeter.proto
Write the service
Below is the code for the greeter service.
It does the following:
- Implements the interface defined for the Greeter handler
- Initialises a micro.Service
- Registers the Greeter handler
- Runs the service
package main
import (
"fmt"
micro "github.com/micro/go-micro"
proto "github.com/micro/examples/service/proto"
"golang.org/x/net/context"
)
type Greeter struct{}
func (g *Greeter) Hello(ctx context.Context, req *proto.HelloRequest, rsp *proto.HelloResponse) error {
rsp.Greeting = "Hello " + req.Name
return nil
}
func main() {
// Create a new service. Optionally include some options here.
service := micro.NewService(
micro.Name("greeter"),
)
// Init will parse the command line flags.
service.Init()
// Register handler
proto.RegisterGreeterHandler(service.Server(), new(Greeter))
// Run the server
if err := service.Run(); err != nil {
fmt.Println(err)
}
}
Run service
go run examples/service/main.go
Output
2016/03/14 10:59:14 Listening on [::]:50137
2016/03/14 10:59:14 Broker Listening on [::]:50138
2016/03/14 10:59:14 Registering node: greeter-ca62b017-e9d3-11e5-9bbb-68a86d0d36b6
Define a client
Below is the client code to query the greeter service.
The generated proto includes a greeter client to reduce boilerplate code.
package main
import (
"fmt"
micro "github.com/micro/go-micro"
proto "github.com/micro/examples/service/proto"
"golang.org/x/net/context"
)
func main() {
// Create a new service. Optionally include some options here.
service := micro.NewService(micro.Name("greeter.client"))
// Create new greeter client
greeter := proto.NewGreeterClient("greeter", service.Client())
// Call the greeter
rsp, err := greeter.Hello(context.TODO(), &proto.HelloRequest{Name: "John"})
if err != nil {
fmt.Println(err)
}
// Print response
fmt.Println(rsp.Greeting)
}
Run the client
go run client.go
Output
Hello John
Writing a Function
Go Micro includes the Function programming model.
A Function is a one time executing Service which exits after completing a request.
Defining a Function
package main
import (
proto "github.com/micro/examples/function/proto"
"github.com/micro/go-micro"
"golang.org/x/net/context"
)
type Greeter struct{}
func (g *Greeter) Hello(ctx context.Context, req *proto.HelloRequest, rsp *proto.HelloResponse) error {
rsp.Greeting = "Hello " + req.Name
return nil
}
func main() {
// create a new function
fnc := micro.NewFunction(
micro.Name("go.micro.fnc.greeter"),
)
// init the command line
fnc.Init()
// register a handler
fnc.Handle(new(Greeter))
// run the function
fnc.Run()
}
It's that simple.
Plugins
By default go-micro only provides a few implementation of each interface at the core but it's completely pluggable. There's already dozens of plugins which are available at github.com/micro/go-plugins. Contributions are welcome!
Build with plugins
If you want to integrate plugins simply link them in a separate file and rebuild
Create a plugins.go file
import (
// etcd v3 registry
_ "github.com/micro/go-plugins/registry/etcdv3"
// nats transport
_ "github.com/micro/go-plugins/transport/nats"
// kafka broker
_ "github.com/micro/go-plugins/broker/kafka"
)
Build binary
// For local use
go build -i -o service ./main.go ./plugins.go
Flag usage of plugins
service --registry=etcdv3 --transport=nats --broker=kafka
Plugin as option
Alternatively you can set the plugin as an option to a service
import (
"github.com/micro/go-micro"
// etcd v3 registry
"github.com/micro/go-plugins/registry/etcdv3"
// nats transport
"github.com/micro/go-plugins/transport/nats"
// kafka broker
"github.com/micro/go-plugins/broker/kafka"
)
func main() {
registry := etcdv3.NewRegistry()
broker := kafka.NewBroker()
transport := nats.NewTransport()
service := micro.NewService(
micro.Name("greeter"),
micro.Registry(registry),
micro.Broker(broker),
micro.Transport(transport),
)
service.Init()
service.Run()
}
Write plugins
Plugins are a concept built on Go's interface. Each package maintains a high level interface abstraction. Simply implement the interface and pass it in as an option to the service.
The service discovery interface is called Registry. Anything which implements this interface can be used as a registry. The same applies to the other packages.
type Registry interface {
Register(*Service, ...RegisterOption) error
Deregister(*Service) error
GetService(string) ([]*Service, error)
ListServices() ([]*Service, error)
Watch() (Watcher, error)
String() string
}
Browse go-plugins to get a better idea of implementation details.
Wrappers
Go-micro includes the notion of middleware as wrappers. The client or handlers can be wrapped using the decorator pattern.
Handler
Here's an example service handler wrapper which logs the incoming request
// implements the server.HandlerWrapper
func logWrapper(fn server.HandlerFunc) server.HandlerFunc {
return func(ctx context.Context, req server.Request, rsp interface{}) error {
fmt.Printf("[%v] server request: %s", time.Now(), req.Method())
return fn(ctx, req, rsp)
}
}
It can be initialised when creating the service
service := micro.NewService(
micro.Name("greeter"),
// wrap the handler
micro.WrapHandler(logWrapper),
)
Client
Here's an example of a client wrapper which logs requests made
type logWrapper struct {
client.Client
}
func (l *logWrapper) Call(ctx context.Context, req client.Request, rsp interface{}, opts ...client.CallOption) error {
fmt.Printf("[wrapper] client request to service: %s method: %s\n", req.Service(), req.Method())
return l.Client.Call(ctx, req, rsp)
}
// implements client.Wrapper as logWrapper
func logWrap(c client.Client) client.Client {
return &logWrapper{c}
}
It can be initialised when creating the service
service := micro.NewService(
micro.Name("greeter"),
// wrap the client
micro.WrapClient(logWrap),
)
Other Languages
Check out ja-micro to write services in Java
Sponsors
Open source development of Micro is sponsored by Sixt
Documentation ¶
Overview ¶
Package micro is a pluggable RPC framework for microservices
Index ¶
- Variables
- func NewContext(ctx context.Context, s Service) context.Context
- func RegisterHandler(s server.Server, h interface{}, opts ...server.HandlerOption) error
- func RegisterSubscriber(topic string, s server.Server, h interface{}, opts ...server.SubscriberOption) error
- type Function
- type Option
- func Action(a func(*cli.Context)) Option
- func AfterStart(fn func() error) Option
- func AfterStop(fn func() error) Option
- func BeforeStart(fn func() error) Option
- func BeforeStop(fn func() error) Option
- func Broker(b broker.Broker) Option
- func Client(c client.Client) Option
- func Cmd(c cmd.Cmd) Option
- func Context(ctx context.Context) Option
- func Flags(flags ...cli.Flag) Option
- func Metadata(md map[string]string) Option
- func Name(n string) Option
- func RegisterInterval(t time.Duration) Option
- func RegisterTTL(t time.Duration) Option
- func Registry(r registry.Registry) Option
- func Selector(s selector.Selector) Option
- func Server(s server.Server) Option
- func Transport(t transport.Transport) Option
- func Version(v string) Option
- func WrapCall(w ...client.CallWrapper) Option
- func WrapClient(w ...client.Wrapper) Option
- func WrapHandler(w ...server.HandlerWrapper) Option
- func WrapSubscriber(w ...server.SubscriberWrapper) Option
- type Options
- type Publisher
- type Service
Constants ¶
This section is empty.
Variables ¶
var (
HeaderPrefix = "X-Micro-"
)
Functions ¶
func NewContext ¶
NewContext returns a new Context with the Service embedded within it.
func RegisterHandler ¶
func RegisterHandler(s server.Server, h interface{}, opts ...server.HandlerOption) error
RegisterHandler is syntactic sugar for registering a handler
func RegisterSubscriber ¶
func RegisterSubscriber(topic string, s server.Server, h interface{}, opts ...server.SubscriberOption) error
RegisterSubscriber is syntactic sugar for registering a subscriber
Types ¶
type Function ¶
type Function interface { // Inherits Service interface Service // Done signals to complete execution Done() error // Handle registers an RPC handler Handle(v interface{}) error // Subscribe registers a subscriber Subscribe(topic string, v interface{}) error }
Function is a one time executing Service
func NewFunction ¶
NewFunction returns a new Function for a one time executing Service
type Option ¶
type Option func(*Options)
func AfterStart ¶
func BeforeStart ¶
func BeforeStop ¶
func Context ¶
Context specifies a context for the service. Can be used to signal shutdown of the service. Can be used for extra option values.
func RegisterInterval ¶
RegisterInterval specifies the interval on which to re-register
func RegisterTTL ¶
RegisterTTL specifies the TTL to use when registering the service
func WrapCall ¶
func WrapCall(w ...client.CallWrapper) Option
WrapCall is a convenience method for wrapping a Client CallFunc
func WrapClient ¶
WrapClient is a convenience method for wrapping a Client with some middleware component. A list of wrappers can be provided.
func WrapHandler ¶
func WrapHandler(w ...server.HandlerWrapper) Option
WrapHandler adds a handler Wrapper to a list of options passed into the server
func WrapSubscriber ¶
func WrapSubscriber(w ...server.SubscriberWrapper) Option
WrapSubscriber adds a subscriber Wrapper to a list of options passed into the server
type Options ¶
type Options struct { Broker broker.Broker Cmd cmd.Cmd Client client.Client Server server.Server Registry registry.Registry Transport transport.Transport // Register loop interval RegisterInterval time.Duration // Before and After funcs BeforeStart []func() error BeforeStop []func() error AfterStart []func() error AfterStop []func() error // Other options for implementations of the interface // can be stored in a context Context context.Context }
type Publisher ¶
type Publisher interface {
Publish(ctx context.Context, msg interface{}, opts ...client.PublishOption) error
}
Publisher is syntactic sugar for publishing
type Service ¶
type Service interface { Init(...Option) Options() Options Client() client.Client Server() server.Server Run() error String() string }
Service is an interface that wraps the lower level libraries within go-micro. Its a convenience method for building and initialising services.
func FromContext ¶
FromContext retrieves a Service from the Context.
func NewService ¶
NewService creates and returns a new Service based on the packages within.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package broker is an interface used for asynchronous messaging
|
Package broker is an interface used for asynchronous messaging |
Package client is an interface for an RPC client
|
Package client is an interface for an RPC client |
Package cmd is an interface for parsing the command line
|
Package cmd is an interface for parsing the command line |
Package codec is an interface for encoding messages
|
Package codec is an interface for encoding messages |
protorpc
Package proto is a generated protocol buffer package.
|
Package proto is a generated protocol buffer package. |
Package errors provides a way to return detailed information for an RPC request error.
|
Package errors provides a way to return detailed information for an RPC request error. |
Package metadata is a way of defining message headers
|
Package metadata is a way of defining message headers |
Package registry is an interface for service discovery
|
Package registry is an interface for service discovery |
Package selector is a way to load balance service nodes
|
Package selector is a way to load balance service nodes |
cache
Package cache is a caching selector.
|
Package cache is a caching selector. |
Package server is an interface for a micro server
|
Package server is an interface for a micro server |
debug/proto
Package debug is a generated protocol buffer package.
|
Package debug is a generated protocol buffer package. |
Package is an interface for synchronous communication
|
Package is an interface for synchronous communication |