micro/README.md

251 lines
10 KiB
Markdown
Raw Normal View History

2015-11-20 19:17:33 +03:00
# Go Micro [![GoDoc](https://godoc.org/github.com/micro/go-micro?status.svg)](https://godoc.org/github.com/micro/go-micro) [![Travis CI](https://travis-ci.org/micro/go-micro.svg?branch=master)](https://travis-ci.org/micro/go-micro)
2015-01-14 02:31:27 +03:00
2016-02-06 16:32:01 +03:00
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](https://github.com/micro/micro) toolkit. It supports Proto-RPC and JSON-RPC as the request/response protocol out of the box and defaults to Consul for discovery.
2015-11-29 23:46:31 +03:00
2016-02-06 16:32:01 +03:00
The Micro philosophy is "batteries included" with a pluggable architecture. We provide sane defaults but everything can be swapped out.
2015-01-14 11:38:39 +03:00
2016-01-05 03:27:58 +03:00
An example service can be found in [**examples/service**](https://github.com/micro/go-micro/tree/master/examples/service). The [**examples**](https://github.com/micro/go-micro/tree/master/examples) directory contains many more examples for using things such as middleware/wrappers, selector filters, pub/sub and code generation.
2015-01-14 11:38:39 +03:00
2016-02-06 16:32:01 +03:00
Join the community to learn more:
2015-11-05 03:27:21 +03:00
- [Mailing List](https://groups.google.com/forum/#!forum/micro-services)
2015-11-05 03:45:15 +03:00
- [Slack](https://micro-services.slack.com) : [auto-invite](http://micro-invites.herokuapp.com/)
2015-11-05 03:27:21 +03:00
2015-05-18 01:04:19 +03:00
## Features
2015-11-11 03:45:02 +03:00
2015-12-03 04:25:25 +03:00
Feature | Package | Built-in Plugin | Description
2015-12-03 04:28:20 +03:00
------- | ------- | --------- | -----------
2015-12-03 04:26:57 +03:00
Discovery | [Registry](https://godoc.org/github.com/micro/go-micro/registry) | consul | A way of locating services to communicate with
2015-12-03 14:07:31 +03:00
Client | [Client](https://godoc.org/github.com/micro/go-micro/client) | rpc | Used to make RPC requests to a service
2015-12-03 04:26:57 +03:00
Codec | [Codec](https://godoc.org/github.com/micro/go-micro/codec) | proto,json | Encoding/Decoding handler for requests
2015-12-10 00:41:55 +03:00
Balancer | [Selector](https://godoc.org/github.com/micro/go-micro/selector) | random | Service node filter and pool
2015-12-03 14:07:31 +03:00
Server | [Server](https://godoc.org/github.com/micro/go-micro/server) | rpc | Listens and serves RPC requests
2015-12-03 04:26:57 +03:00
Pub/Sub | [Broker](https://godoc.org/github.com/micro/go-micro/broker) | http | Publish and Subscribe to events
Transport | [Transport](https://godoc.org/github.com/micro/go-micro/transport) | http | Communication mechanism between services
2015-12-03 04:25:25 +03:00
2016-01-05 03:27:58 +03:00
## Example Services
Project | Description
----- | ------
[greeter](https://github.com/micro/micro/tree/master/examples/greeter) | A greeter service (includes Go, Ruby, Python examples)
[geo-srv](https://github.com/micro/geo-srv) | Geolocation tracking service using hailocab/go-geoindex
[geo-api](https://github.com/micro/geo-api) | A HTTP API handler for geo location tracking and search
[geocode-srv](https://github.com/micro/geocode-srv) | A geocoding service using the Google Geocoding API
[hailo-srv](https://github.com/micro/hailo-srv) | A service for the hailo taxi service developer api
[place-srv](https://github.com/micro/place-srv) | A microservice to store and retrieve places (includes Google Place Search API)
[slack-srv](https://github.com/micro/slack-srv) | The slack bot API as a go-micro RPC service
[twitter-srv](https://github.com/micro/twitter-srv) | A microservice for the twitter API
[user-srv](https://github.com/micro/user-srv) | A microservice for user management and authentication
2015-12-03 04:25:25 +03:00
## Go Plugins
By default go-micro only provides a single implementation of each interface. Plugins can be found at [github.com/micro/go-plugins](https://github.com/micro/go-plugins). Contributions welcome!
2015-05-18 01:04:19 +03:00
2016-02-06 16:32:01 +03:00
## How does it work?
2015-01-14 11:38:39 +03:00
2016-02-06 16:32:01 +03:00
Go Micro is a framework that addresses the fundamental requirements to write microservices.
2015-01-14 13:50:43 +03:00
2016-02-06 16:32:01 +03:00
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**.
2015-01-14 11:38:39 +03:00
2015-01-14 13:50:43 +03:00
## Getting Started
2016-02-06 16:32:01 +03:00
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](https://github.com/micro/go-plugins).
### Install Consul
[https://www.consul.io/intro/getting-started/install.html](https://www.consul.io/intro/getting-started/install.html)
2015-01-14 11:38:39 +03:00
### Run Consul
```
$ consul agent -dev -advertise=127.0.0.1
2015-01-14 11:38:39 +03:00
```
2015-01-14 13:50:43 +03:00
### Run Service
2015-01-14 11:38:39 +03:00
```
2016-01-02 03:38:57 +03:00
$ go run examples/service/main.go --logtostderr
I0102 00:22:26.413467 12018 rpc_server.go:297] Listening on [::]:62492
I0102 00:22:26.413803 12018 http_broker.go:115] Broker Listening on [::]:62493
I0102 00:22:26.414009 12018 rpc_server.go:212] Registering node: greeter-e6b2fc6f-b0e6-11e5-a42f-68a86d0d36b6
2015-01-14 11:38:39 +03:00
```
2015-01-14 13:50:43 +03:00
### Test Service
2015-01-14 11:38:39 +03:00
```
2016-01-02 03:38:57 +03:00
$ go run examples/service/main.go --client
Hello John
2015-01-14 11:38:39 +03:00
```
2015-01-14 13:50:43 +03:00
## Writing a service
### Create request/response proto
2016-01-02 03:38:57 +03:00
`go-micro/examples/service/proto/greeter.proto`:
2015-01-14 13:50:43 +03:00
2016-01-04 02:36:14 +03:00
```proto
2015-05-25 20:16:42 +03:00
syntax = "proto3";
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
service Greeter {
rpc Hello(HelloRequest) returns (HelloResponse) {}
2015-01-14 13:50:43 +03:00
}
2016-01-02 03:38:57 +03:00
message HelloRequest {
string name = 1;
2015-01-14 13:50:43 +03:00
}
2016-01-02 03:38:57 +03:00
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](https://github.com/micro/go-micro/blob/master/examples/server/main.go)
and [examples/client](https://github.com/micro/go-micro/blob/master/examples/client/main.go) for examples without code generation.
```shell
go get github.com/micro/protobuf
2015-01-14 13:50:43 +03:00
```
2016-01-02 03:38:57 +03:00
Compile proto `protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src $GOPATH/src/github.com/micro/go-micro/examples/service/proto/greeter.proto`
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
### Define the service
`go-micro/examples/service/main.go`:
2015-01-14 13:50:43 +03:00
2015-02-02 21:53:16 +03:00
```go
2016-01-02 03:38:57 +03:00
package main
2015-01-14 13:50:43 +03:00
import (
2016-01-02 03:38:57 +03:00
"fmt"
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
micro "github.com/micro/go-micro"
proto "github.com/micro/go-micro/examples/service/proto"
2015-11-08 14:12:09 +03:00
"golang.org/x/net/context"
2015-01-14 13:50:43 +03:00
)
2016-01-02 03:38:57 +03:00
type Greeter struct{}
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
func (g *Greeter) Hello(ctx context.Context, req *proto.HelloRequest, rsp *proto.HelloResponse) error {
rsp.Greeting = "Hello " + req.Name
2015-11-08 14:12:09 +03:00
return nil
2015-01-14 13:50:43 +03:00
}
2016-01-02 03:38:57 +03:00
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)
}
}
2015-01-14 13:50:43 +03:00
```
2016-01-02 03:38:57 +03:00
### Run service
```
go run examples/service/main.go --logtostderr
I0102 00:22:26.413467 12018 rpc_server.go:297] Listening on [::]:62492
I0102 00:22:26.413803 12018 http_broker.go:115] Broker Listening on [::]:62493
I0102 00:22:26.414009 12018 rpc_server.go:212] Registering node: greeter-e6b2fc6f-b0e6-11e5-a42f-68a86d0d36b6
```
### Define a client
`client.go`
2015-01-14 13:50:43 +03:00
2015-02-02 21:53:16 +03:00
```go
2015-01-14 13:50:43 +03:00
package main
import (
2016-01-02 03:38:57 +03:00
"fmt"
micro "github.com/micro/go-micro"
proto "github.com/micro/go-micro/examples/service/proto"
"golang.org/x/net/context"
2015-01-14 13:50:43 +03:00
)
2015-05-25 20:16:42 +03:00
2016-01-02 03:38:57 +03:00
func main() {
// Create a new service. Optionally include some options here.
service := micro.NewService(micro.Name("greeter.client"))
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
// Create new greeter client
greeter := proto.NewGreeterClient("greeter", service.Client())
2015-01-14 13:50:43 +03:00
2016-01-02 03:38:57 +03:00
// Call the greeter
rsp, err := greeter.Hello(context.TODO(), &proto.HelloRequest{Name: "John"})
if err != nil {
fmt.Println(err)
2015-01-14 13:50:43 +03:00
}
2016-01-02 03:38:57 +03:00
// Print response
fmt.Println(rsp.Greeting)
2015-01-14 13:50:43 +03:00
}
```
2016-01-02 03:38:57 +03:00
### Run the client
```shell
go run client.go
Hello John
2015-01-14 13:50:43 +03:00
```