unistack-org/micro
4
0
Fork 3
Code Issues 20 Pull Requests 1 Actions Packages Projects Releases 281 Wiki Activity

update readme

Browse Source
This commit is contained in:
Asim Aslam 2017-10-03 11:03:46 +01:00
parent d29b5e2fab
commit 236cfd6a3b
1 changed files with 56 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
README.md
View File

@ -27,28 +27,30 @@ For more detailed information on the architecture, installation and use of go-mi
## Learn By Example ## 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. 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).
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). The [**examples**](https://github.com/micro/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**](https://github.com/micro/examples/tree/master/greeter). Other examples can be found throughout the GitHub repository.
Watch the [Golang UK Conf 2016](https://www.youtube.com/watch?v=xspaDovwk34) video for a high level overview.
## Getting Started ## Getting Started
This is a quick getting started guide with the greeter service example. This is a quick getting started guide with the greeter service example.
### Prerequisites: Service Discovery ### Prereq: Service Discovery
There's just one prerequisite. We need a service discovery system to resolve service names to their address. Service discovery is required to resolve services to their addresses.
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). The default discovery plugin is consul. Discovery is however pluggable so you can use
etcd, kubernetes, zookeeper, etc. Plugins are in [micro/go-plugins](https://github.com/micro/go-plugins).
### Multicast DNS ### Multicast DNS
We can use multicast DNS with the built in MDNS registry for a zero dependency configuration. [Multicast DNS](https://en.wikipedia.org/wiki/Multicast_DNS) can alternatively be used for service discovery as a zero dependency configuration.
Just pass `--registry=mdns` to any command Pass `--registry=mdns` to any command or the enviroment variable MICRO_REGISTRY=mdns
``` ```
$ go run main.go --registry=mdns go run main.go --registry=mdns
``` ```
### Consul ### Consul
@ -71,7 +73,11 @@ docker run consul
### Run Service ### Run Service
``` ```
$ go get github.com/micro/examples/service && service go get github.com/micro/examples/service && service
```
Output
```
2016/03/14 10:59:14 Listening on [::]:50137 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 Broker Listening on [::]:50138
2016/03/14 10:59:14 Registering node: greeter-ca62b017-e9d3-11e5-9bbb-68a86d0d36b6 2016/03/14 10:59:14 Registering node: greeter-ca62b017-e9d3-11e5-9bbb-68a86d0d36b6
@ -79,18 +85,25 @@ $ go get github.com/micro/examples/service && service
### Call Service ### Call Service
``` ```
$ service --run_client service --run_client
```
Output
```
Hello John Hello John
``` ```
## Writing a service ## Writing a service
This is a simple greeter RPC service example
Find this example at [examples/service](https://github.com/micro/examples/tree/master/service).
### Create service proto ### 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. One of the key requirements of microservices is strongly defined interfaces. Micro uses protobuf to achieve this.
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`: Here we define the Greeter handler with the method Hello. It takes a HelloRequest and HelloResponse both with one string arguments.
```proto ```proto
syntax = "proto3"; syntax = "proto3";
@ -110,28 +123,33 @@ message HelloResponse {
### Install protobuf ### 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) Install [protobuf](https://developers.google.com/protocol-buffers/)
and [examples/client](https://github.com/micro/examples/blob/master/client/main.go) for examples without code generation.
Now install the micro fork of protoc-gen-go. The protobuf compiler for Go.
```shell ```shell
go get github.com/micro/protobuf/{proto,protoc-gen-go} 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`. ### Generate the proto
### Compile the proto After writing the proto definition we must compile it using protoc with the micro plugin.
```shell ```shell
protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src \ protoc -I$GOPATH/src --go_out=plugins=micro:$GOPATH/src \
$GOPATH/src/github.com/micro/examples/service/proto/greeter.proto $GOPATH/src/github.com/micro/examples/service/proto/greeter.proto
``` ```
### Define the service ### Write the service
Below is the code sample for the Greeter service. It basically implements the interface defined above for the Greeter handler, Below is the code for the greeter service.
initialises the service, registers the handler and then runs itself. Simple as that.
`go-micro/examples/service/main.go`: It does the following:
1. Implements the interface defined for the Greeter handler
2. Initialises a micro.Service
3. Registers the Greeter handler
4. Runs the service
```go ```go
package main package main
@ -174,6 +192,10 @@ func main() {
### Run service ### Run service
``` ```
go run examples/service/main.go go run examples/service/main.go
```
Output
```
2016/03/14 10:59:14 Listening on [::]:50137 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 Broker Listening on [::]:50138
2016/03/14 10:59:14 Registering node: greeter-ca62b017-e9d3-11e5-9bbb-68a86d0d36b6 2016/03/14 10:59:14 Registering node: greeter-ca62b017-e9d3-11e5-9bbb-68a86d0d36b6
@ -181,10 +203,9 @@ go run examples/service/main.go
### Define a client ### Define a client
Below is the client code to query the greeter service. Notice we're using the code generated client interface `proto.NewGreeterClient`. Below is the client code to query the greeter service.
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` The generated proto includes a greeter client to reduce boilerplate code.
```go ```go
package main package main
@ -220,13 +241,18 @@ func main() {
```shell ```shell
go run client.go go run client.go
```
Output
```
Hello John Hello John
``` ```
## Writing a Function ## 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 Go Micro includes the Function programming model.
after completing a request. A function is defined much like a service and called in exactly the same way.
A Function is a one time executing Service which exits after completing a request.
### Defining a Function ### Defining a Function
@ -265,13 +291,13 @@ func main() {
It's that simple. It's that simple.
## How does it work? ## How it works
<p align="center"> <p align="center">
<img src="go-micro.png" /> <img src="go-micro.png" />
</p> </p>
Go Micro is a framework that addresses the fundamental requirements to write microservices. Go Micro is a framework that addresses the fundamental requirements for writing microservices.
Let's dig into the core components. Let's dig into the core components.