micro

package module
v0.0.0-...-257333a Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2016 License: Apache-2.0 Imports: 14 Imported by: 0

README

Go Micro License GoDoc Travis CI Go Report Card

Go Micro is a pluggable RPC based microservice library which provides the fundamental building blocks for writing distributed applications. It is part of the Micro toolkit. It supports Proto-RPC and JSON-RPC as the request/response protocol out of the box and defaults to Consul for discovery.

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.

An example service can be found in examples/service. The examples directory contains many more examples for using things such as middleware/wrappers, selector filters, pub/sub and code generation.

Check out the blog post to learn how to write go-micro services https://blog.micro.mu/2016/03/28/go-micro.html.

Join the community to learn more:

Features

Feature Package Built-in Plugin Description
Discovery Registry consul A way of locating services to communicate with
Client Client rpc Used to make RPC requests to a service
Codec Codec proto,json Encoding/Decoding handler for requests
Balancer Selector random Service node filter and pool
Server Server rpc Listens and serves RPC requests
Pub/Sub Broker http Publish and Subscribe to events
Transport Transport http Communication mechanism between services

Example Services

Project Description
greeter A greeter service (includes Go, Ruby, Python examples)
geo-srv Geolocation tracking service using hailocab/go-geoindex
geo-api A HTTP API handler for geo location tracking and search
geocode-srv A geocoding service using the Google Geocoding API
hailo-srv A service for the hailo taxi service developer api
place-srv A microservice to store and retrieve places (includes Google Place Search API)
slack-srv The slack bot API as a go-micro RPC service
twitter-srv A microservice for the twitter API
user-srv A microservice for user management and authentication

Go Plugins

By default go-micro only provides a single implementation of each interface. Plugins can be found at github.com/micro/go-plugins. Contributions welcome!

How does it work?

Go Micro is a framework that addresses the fundamental requirements to write microservices.

Let's dig into the core components.

Registry

The registry provides a service discovery mechanism to resolve names to addresses. It can be backed by consul, etcd, zookeeper, dns, gossip, etc. Services should register using the registry on startup and deregister on shutdown. Services can optionally provide an expiry TTL and reregister on an interval to ensure liveness and that the service is cleaned up if it dies.

Selector

The selector is a load balancing abstraction which builds on the registry. It allows services to be "filtered" using filter functions and "selected" using a choice of algorithms such as random, roundrobin, leastconn, etc. The selector is leveraged by the Client when making requests. The client will use the selector rather than the registry as it provides that built in mechanism of load balancing.

Transport

The transport is the interface for synchronous request/response communication between services. It's akin to the golang net package but provides a higher level abstraction which allows us to switch out communication mechanisms e.g http, rabbitmq, websockets, NATS. The transport also supports bidirectional streaming. This is powerful for client side push to the server.

Broker

The broker provides an interface to a message broker for asynchronous pub/sub communication. This is one of the fundamental requirements of an event driven architecture and microservices. By default we use an inbox style point to point HTTP system to minimise the number of dependencies required to get started. However there are many message broker implementations available in go-plugins e.g RabbitMQ, NATS, NSQ, Google Cloud Pub Sub.

Codec

The codec is used for encoding and decoding messages before transporting them across the wire. This could be json, protobuf, bson, msgpack, etc. Where this differs from most other codecs is that we actually support the RPC format here as well. So we have JSON-RPC, PROTO-RPC, BSON-RPC, etc. It separates encoding from the client/server and provides a powerful method for integrating other systems such as gRPC, Vanadium, etc.

Server

The server is the building block for writing a service. Here you can name your service, register request handlers, add middeware, etc. The service builds on the above packages to provide a unified interface for serving requests. The built in server is an RPC system. In the future there maybe other implementations. The server also allows you to define multiple codecs to serve different encoded messages.

Client

The client provides an interface to make requests to services. Again like the server, it builds on the other packages to provide a unified interface for finding services by name using the registry, load balancing using the selector, making synchronous requests with the transport and asynchronous messaging using the broker.

The above components are combined at the top-level of micro as a Service.

Getting Started

This is a quick getting started guide with the greeter service example.

Prerequisites

There's just one prerequisite. We need a service discovery system to resolve service names to their address. The default discovery mechanism used in go-micro is Consul. Discovery is however pluggable so you can used etcd, kubernetes, zookeeper, etc. Other implementations can be found in go-plugins.

Install Consul

https://www.consul.io/intro/getting-started/install.html

Run Consul
$ consul agent -dev -advertise=127.0.0.1
Run Service
$ go run examples/service/main.go
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
Test Service
$ go run examples/service/main.go --client
Hello John

Writing a service

Create request/response proto

One of the key requirements of microservices is strongly defined interfaces so we utilised protobuf to define the handler and request/response. Here's a definition for the Greeter handler with the method Hello which takes a HelloRequest and HelloResponse both with one string arguments.

go-micro/examples/service/proto/greeter.proto:

syntax = "proto3";

service Greeter {
	rpc Hello(HelloRequest) returns (HelloResponse) {}
}

message HelloRequest {
	string name = 1;
}

message HelloResponse {
	string greeting = 2;
}
Install protobuf for code generation

We use a protobuf plugin for code generation. This is completely optional. Look at examples/server and examples/client for examples without code generation.

go get github.com/micro/protobuf/{proto,protoc-gen-go}

There's still a need for proto compiler to generate Go stub code from our proto file. You can either use the micro fork above or the official repo github.com/golang/protobuf.

Compile the protobuf file
`protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src $GOPATH/src/github.com/micro/go-micro/examples/service/proto/greeter.proto`
Define the service

Below is the code sample for the Greeter service. It basically implements the interface defined above for the Greeter handler, initialises the service, registers the handler and then runs itself. Simple as that.

go-micro/examples/service/main.go:

package main

import (
	"fmt"

	micro "github.com/micro/go-micro"
	proto "github.com/micro/go-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"),
		micro.Version("latest"),
		micro.Metadata(map[string]string{
			"type": "helloworld",
		}),
	)

	// Init will parse the command line flags. Any flags set will
	// override the above settings. Options defined here will
	// override anything set on the command line.
	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
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. Notice we're using the code generated client interface proto.NewGreeterClient. This reduces the amount of boiler plate code we need to write. The greeter client can be reused throughout the code if need be.

client.go

package main

import (
	"fmt"

	micro "github.com/micro/go-micro"
	proto "github.com/micro/go-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
Hello John

Sponsors

Next steps

Contributing

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	HeaderPrefix = "X-Micro-"
)

Functions

func NewContext 

func NewContext(ctx context.Context, s Service) context.Context

Types

type Option 

type Option func(*Options)

func Action 

func Action(a func(*cli.Context)) Option

func AfterStop 

func AfterStop(fn func() error) Option

func BeforeStart 

func BeforeStart(fn func() error) Option

func Broker 

func Broker(b broker.Broker) Option

func Client 

func Client(c client.Client) Option

func Cmd 

func Cmd(c cmd.Cmd) Option

func Flags 

func Flags(flags ...cli.Flag) Option

func Metadata 

func Metadata(md map[string]string) Option

Metadata associated with the service

func Name 

func Name(n string) Option

Name of the service

func RegisterInterval 

func RegisterInterval(t time.Duration) Option

func RegisterTTL 

func RegisterTTL(t time.Duration) Option

func Registry 

func Registry(r registry.Registry) Option

Registry sets the registry for the service and the underlying components

func Server 

func Server(s server.Server) Option

func Transport 

func Transport(t transport.Transport) Option

Transport sets the transport for the service and the underlying components

func Version 

func Version(v string) Option

Version of the service

func WrapClient 

func WrapClient(w ...client.Wrapper) Option

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
	AfterStop   []func() error

	// Other options for implementations of the interface
	// can be stored in a context
	Context context.Context
}

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 

func FromContext(ctx context.Context) (Service, bool)

func NewService 

func NewService(opts ...Option) Service

Source Files

View all Source files

Directories

Path Synopsis
Package broker is an interface used for asynchronous messaging.
 Package broker is an interface used for asynchronous messaging.
http
mock
mqtt
Package client is an interface for making requests.
 Package client is an interface for making requests.
mock
rpc
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.
jsonrpc
protorpc
Package proto is a generated protocol buffer package.
 Package proto is a generated protocol buffer package.
Package errors is an interface for defining detailed errors.
 Package errors is an interface for defining detailed errors.
examples
client
client/codegen
client/dc_filter
client/dc_selector
client/pub
client/selector
client/wrapper
pubsub
pubsub/consumer
pubsub/producer
server
server/codegen
server/handler
server/proto/example
Package go_micro_srv_example is a generated protocol buffer package.
 Package go_micro_srv_example is a generated protocol buffer package.
server/subscriber
server/wrapper
service
service/proto
Package greeter is a generated protocol buffer package.
 Package greeter is a generated protocol buffer package.
service/wrapper
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.
consul
mdns
mock
Package selector is a way to load balance service nodes.
 Package selector is a way to load balance service nodes.
cache
internal/blacklist
Package server is an interface for a micro server.
 Package server is an interface for a micro server.
debug
debug/proto
Package debug is a generated protocol buffer package.
 Package debug is a generated protocol buffer package.
mock
rpc
Package is an interface for synchronous communication.
 Package is an interface for synchronous communication.
http
mock

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.