# Go Micro [![License](https://img.shields.io/:license-apache-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![GoDoc](https://godoc.org/github.com/micro/go-micro?status.svg)](https://godoc.org/github.com/micro/go-micro) [![Travis CI](https://api.travis-ci.org/micro/go-micro.svg?branch=master)](https://travis-ci.org/micro/go-micro) [![Go Report Card](https://goreportcard.com/badge/micro/go-micro)](https://goreportcard.com/report/github.com/micro/go-micro) Go Micro is a pluggable RPC framework for **microservices**. It is part of the [Micro](https://github.com/micro/micro) toolkit. 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](https://github.com/micro/go-plugins). Follow us on Twitter at [@MicroHQ](https://twitter.com/microhq), join the [Slack](https://micro-services.slack.com) community [here](http://slack.micro.mu/) or check out the [Mailing List](https://groups.google.com/forum/#!forum/microhq). ## Features Go Micro abstracts way the details of distributed systems. Here are the main features. - **Service Discovery** - Applications are automatically registered with service discovery so they can find each other. - **Load Balancing** - Smart client side load balancing is used to balance requests between instances of a service. - **Synchronous Communication** - Request-response is provided as a bidirectional streaming transport layer. - **Asynchronous Communication** - Microservices should promote an event driven architecture. Publish and Subscribe semantics are built in. - **Message Encoding** - Micro services can encode requests in a number of encoding formats and seamlessly decode based on the Content-Type header. - **RPC Client/Server** - The client and server leverage the above features and provide a clean simple interface for building microservices. 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](https://micro.mu/docs). ## Learn By Example An example service can be found in [**examples/service**](https://github.com/micro/examples/tree/master/service) and function in [**examples/function**](https://github.com/micro/examples/tree/master/function). The [**examples**](https://github.com/micro/examples) directory contains many more examples for using things such as middleware/wrappers, selector filters, pub/sub and code generation. For the complete greeter example look at [**examples/greeter**](https://github.com/micro/examples/tree/master/greeter). Other examples can be found throughout the GitHub repository. Check out the blog post to learn how to write go-micro services [https://micro.mu/blog/2016/03/28/go-micro.html](https://micro.mu/blog/2016/03/28/go-micro.html) or watch the talk from the [Golang UK Conf 2016](https://www.youtube.com/watch?v=xspaDovwk34). ## Getting Started This is a quick getting started guide with the greeter service example. ### Prerequisites: Service Discovery 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. Plugins can be found in [micro/go-plugins](https://github.com/micro/go-plugins). ### Multicast DNS We can use multicast DNS with the built in MDNS registry for a zero dependency configuration. Just pass `--registry=mdns` to any command ``` $ go run main.go --registry=mdns ``` ### Consul Alternatively we can use the default discovery system which is Consul. **Mac OS** ``` brew install consul consul agent -dev ``` **Docker** ``` docker run consul ``` [Further installation instructions](https://www.consul.io/intro/getting-started/install.html) ### Run Service ``` $ go get github.com/micro/examples/service && service 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 ``` ### Call Service ``` $ service --run_client Hello John ``` ## Writing a service ### Create service 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`: ```proto syntax = "proto3"; service Greeter { rpc Hello(HelloRequest) returns (HelloResponse) {} } message HelloRequest { string name = 1; } message HelloResponse { string greeting = 2; } ``` ### Install protobuf We use a protobuf plugin for code generation. This is completely optional. Look at [examples/server](https://github.com/micro/examples/blob/master/server/main.go) and [examples/client](https://github.com/micro/examples/blob/master/client/main.go) for examples without code generation. ```shell 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 proto ```shell protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src \ $GOPATH/src/github.com/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`: ```go 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"), 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` ```go 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 ```shell go run client.go Hello John ``` ## Writing a Function Go Micro includes the Function programming model. This is the notion of a one time executing Service which operates much like a service except exiting after completing a request. A function is defined much like a service and called in exactly the same way. ### Defining a Function ```go 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. ## How does it work?