github.com/micro/go-micro/examples@v0.0.0-20210105173217-bf4ab679e18b/plugins/README.md (about)

     1  # Plugins
     2  
     3  The micro toolkit supports plugins for the binary itself. These are separate from go-micro plugins.
     4  
     5  Plugins can be used to add flags, commands and middleware handlers. An example would be authentication, 
     6  logging, tracing, etc. Existing plugins can be found in [go-plugins/micro](https://github.com/micro/go-plugins/tree/master/micro).
     7  
     8  ## A simple example
     9  
    10  Here's a simple example of a plugin that adds a flag and then prints the value
    11  
    12  ### The plugin
    13  
    14  Create a plugin.go file in the top level dir
    15  
    16  ```go
    17  package main
    18  
    19  import (
    20  	"log"
    21  	"github.com/micro/cli/v2"
    22  	"github.com/micro/micro/v2/plugin"
    23  )
    24  
    25  func init() {
    26  	plugin.Register(plugin.NewPlugin(
    27  		plugin.WithName("example"),
    28  		plugin.WithFlag(cli.StringFlag{
    29  			Name:   "example_flag",
    30  			Usage:  "This is an example plugin flag",
    31  			EnvVars: []string{"EXAMPLE_FLAG"},
    32  			Value: "avalue",
    33  		}),
    34  		plugin.WithInit(func(ctx *cli.Context) error {
    35  			log.Println("Got value for example_flag", ctx.String("example_flag"))
    36  			return nil
    37  		}),
    38  	))
    39  }
    40  ```
    41  
    42  ### Build with plugin
    43  
    44  Simply build micro with the plugin
    45  
    46  ```shell
    47  go build -o micro ./main.go ./plugin.go
    48  ```
    49  
    50  ## Go-Micro Plugins
    51  
    52  Plugins can be added to go-micro in the following ways. By doing so they'll be available to set via command line args or environment variables.
    53  
    54  ### Import Plugins
    55  
    56  ```go
    57  import (
    58  	"github.com/micro/go-micro/v2/config/cmd"
    59  	_ "github.com/micro/go-plugins/broker/rabbitmq"
    60  	_ "github.com/micro/go-plugins/registry/kubernetes"
    61  	_ "github.com/micro/go-plugins/transport/nats"
    62  )
    63  
    64  func main() {
    65  	// Parse CLI flags
    66  	cmd.Init()
    67  }
    68  ```
    69  
    70  The same is achieved when calling ```service.Init```
    71  
    72  ```go
    73  import (
    74  	"github.com/micro/go-micro/v2"
    75  	_ "github.com/micro/go-plugins/broker/rabbitmq"
    76  	_ "github.com/micro/go-plugins/registry/kubernetes"
    77  	_ "github.com/micro/go-plugins/transport/nats"
    78  )
    79  
    80  func main() {
    81  	service := micro.NewService(
    82  		// Set service name
    83  		micro.Name("my.service"),
    84  	)
    85  
    86  	// Parse CLI flags
    87  	service.Init()
    88  }
    89  ```
    90  
    91  ### Use via CLI Flags
    92  
    93  Activate via a command line flag
    94  
    95  ```shell
    96  go run service.go --broker=rabbitmq --registry=kubernetes --transport=nats
    97  ```
    98  
    99  ### Use Plugins Directly
   100  
   101  CLI Flags provide a simple way to initialise plugins but you can do the same yourself.
   102  
   103  ```go
   104  import (
   105  	"github.com/micro/go-micro/v2"
   106  	"github.com/micro/go-plugins/registry/kubernetes"
   107  )
   108  
   109  func main() {
   110  	registry := kubernetes.NewRegistry() //a default to using env vars for master API
   111  
   112  	service := micro.NewService(
   113  		// Set service name
   114  		micro.Name("my.service"),
   115  		// Set service registry
   116  		micro.Registry(registry),
   117  	)
   118  }
   119  ```
   120  
   121  ## Build Pattern
   122  
   123  You may want to swap out plugins using automation or add plugins to the micro toolkit. 
   124  An easy way to do this is by maintaining a separate file for plugin imports and including it during the build.
   125  
   126  Create file plugins.go
   127  ```go
   128  package main
   129  
   130  import (
   131  	_ "github.com/micro/go-plugins/broker/rabbitmq"
   132  	_ "github.com/micro/go-plugins/registry/kubernetes"
   133  	_ "github.com/micro/go-plugins/transport/nats"
   134  )
   135  ```
   136  
   137  Build with plugins.go
   138  ```shell
   139  go build -o service main.go plugins.go
   140  ```
   141  
   142  Run with plugins
   143  ```shell
   144  service --broker=rabbitmq --registry=kubernetes --transport=nats
   145  ```