micro/README.md

138 lines
4.5 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
2015-11-29 23:45:11 +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) toolchain. It supports Proto-RPC and JSON-RPC as the request/response protocol out of the box and defaults to Consul for discovery. Every aspect of go-micro is pluggable.
2015-01-14 11:38:39 +03:00
2015-05-25 20:16:42 +03:00
An example server can be found in examples/server.
2015-01-14 11:38:39 +03:00
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
Feature | Package | Description
------- | ------- | ---------
2015-11-20 19:17:33 +03:00
Discovery | [Registry](https://godoc.org/github.com/micro/go-micro/registry) | A way of locating services to communicate with
Client | [Client](https://godoc.org/github.com/micro/go-micro/client) | Used to make RPC requests to a service
2015-11-29 23:45:43 +03:00
Codec | [Codec](https://godoc.org/github.com/micro/go-micro/codec) | Encoding/Decoding handler for requests
2015-11-20 19:17:33 +03:00
Server | [Server](https://godoc.org/github.com/micro/go-micro/server) | Listens and serves RPC requests
Pub/Sub | [Broker](https://godoc.org/github.com/micro/go-micro/broker) | Publish and Subscribe to events
Transport | [Transport](https://godoc.org/github.com/micro/go-micro/transport) | Communication mechanism between services
2015-05-18 01:04:19 +03:00
2015-01-14 11:38:39 +03:00
## Prerequisites
2015-01-14 13:50:43 +03:00
Consul is the default discovery mechanism provided in go-micro. Discovery is however pluggable.
2015-01-14 11:38:39 +03:00
### Install Consul
[https://www.consul.io/intro/getting-started/install.html](https://www.consul.io/intro/getting-started/install.html)
2015-01-14 13:50:43 +03:00
## Getting Started
2015-01-14 11:38:39 +03:00
### Run Consul
```
$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul
```
2015-01-14 13:50:43 +03:00
### Run Service
2015-01-14 11:38:39 +03:00
```
2015-11-08 14:12:09 +03:00
$ go run examples/server/main.go --logtostderr
I1108 11:08:19.926071 11358 server.go:96] Starting server go.micro.srv.example id go.micro.srv.example-04de4cf0-8609-11e5-bf3a-68a86d0d36b6
I1108 11:08:19.926407 11358 rpc_server.go:233] Listening on [::]:54080
I1108 11:08:19.926500 11358 http_broker.go:80] Broker Listening on [::]:54081
I1108 11:08:19.926632 11358 rpc_server.go:158] Registering node: go.micro.srv.example-04de4cf0-8609-11e5-bf3a-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
```
2015-05-25 20:16:42 +03:00
$ go run examples/client/main.go
go.micro.srv.example-59b6e0ab-0300-11e5-b696-68a86d0d36b6: 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
2015-05-25 20:16:42 +03:00
`go-micro/examples/server/proto/example/example.proto`:
2015-01-14 13:50:43 +03:00
```
2015-05-25 20:16:42 +03:00
syntax = "proto3";
2015-01-14 13:50:43 +03:00
message Request {
2015-05-25 20:16:42 +03:00
string name = 1;
2015-01-14 13:50:43 +03:00
}
message Response {
2015-05-25 20:16:42 +03:00
string msg = 1;
2015-01-14 13:50:43 +03:00
}
```
2015-11-20 19:17:33 +03:00
Compile proto `protoc -I$GOPATH/src --go_out=$GOPATH/src $GOPATH/src/github.com/micro/go-micro/examples/server/proto/example/example.proto`
2015-01-14 13:50:43 +03:00
### Create request handler
2015-05-25 20:16:42 +03:00
`go-micro/examples/server/handler/example.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 handler
import (
2015-11-08 14:12:09 +03:00
log "github.com/golang/glog"
2015-11-20 19:17:33 +03:00
c "github.com/micro/go-micro/context"
example "github.com/micro/go-micro/examples/server/proto/example"
"github.com/micro/go-micro/server"
2015-01-14 13:50:43 +03:00
2015-11-08 14:12:09 +03:00
"golang.org/x/net/context"
2015-01-14 13:50:43 +03:00
)
type Example struct{}
func (e *Example) Call(ctx context.Context, req *example.Request, rsp *example.Response) error {
2015-11-08 14:12:09 +03:00
md, _ := c.GetMetadata(ctx)
log.Infof("Received Example.Call request with metadata: %v", md)
rsp.Msg = server.Config().Id() + ": Hello " + req.Name
return nil
2015-01-14 13:50:43 +03:00
}
```
### Init server
2015-05-25 20:16:42 +03:00
`go-micro/examples/server/main.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 (
2015-01-31 18:49:21 +03:00
log "github.com/golang/glog"
2015-11-20 19:17:33 +03:00
"github.com/micro/go-micro/cmd"
"github.com/micro/go-micro/examples/server/handler"
"github.com/micro/go-micro/server"
2015-01-14 13:50:43 +03:00
)
func main() {
2015-05-25 20:16:42 +03:00
// optionally setup command line usage
cmd.Init()
2015-01-14 13:50:43 +03:00
// Initialise Server
2015-05-27 00:42:41 +03:00
server.Init(
server.Name("go.micro.srv.example"),
)
2015-01-14 13:50:43 +03:00
// Register Handlers
server.Handle(
server.NewHandler(
2015-01-14 13:50:43 +03:00
new(handler.Example),
),
)
// Run server
if err := server.Run(); err != nil {
log.Fatal(err)
}
}
```
### Run service
```
2015-11-08 14:12:09 +03:00
$ go run examples/server/main.go --logtostderr
I1108 11:08:19.926071 11358 server.go:96] Starting server go.micro.srv.example id go.micro.srv.example-04de4cf0-8609-11e5-bf3a-68a86d0d36b6
I1108 11:08:19.926407 11358 rpc_server.go:233] Listening on [::]:54080
I1108 11:08:19.926500 11358 http_broker.go:80] Broker Listening on [::]:54081
I1108 11:08:19.926632 11358 rpc_server.go:158] Registering node: go.micro.srv.example-04de4cf0-8609-11e5-bf3a-68a86d0d36b6
2015-01-14 13:50:43 +03:00
```