go-micro.dev/v5@v5.12.0/cmd/protoc-gen-micro/README.md (about)

     1  # protoc-gen-micro
     2  
     3  This is protobuf code generation for go-micro. We use protoc-gen-micro to reduce boilerplate code.
     4  
     5  ## Install
     6  
     7  ```
     8  go install go-micro.dev/v5/cmd/protoc-gen-micro@v5.10.0
     9  ```
    10  
    11  Also required: 
    12  
    13  - [protoc](https://github.com/google/protobuf)
    14  - [protoc-gen-go](https://google.golang.org/protobuf)
    15  
    16  ## Usage
    17  
    18  Define your service as `greeter.proto`
    19  
    20  ```
    21  syntax = "proto3";
    22  
    23  package greeter;
    24  option go_package = "/proto;greeter";
    25  
    26  service Greeter {
    27  	rpc Hello(Request) returns (Response) {}
    28  }
    29  
    30  message Request {
    31  	string name = 1;
    32  }
    33  
    34  message Response {
    35  	string msg = 1;
    36  }
    37  ```
    38  
    39  Generate the code
    40  
    41  ```
    42  protoc --proto_path=. --micro_out=. --go_out=. greeter.proto
    43  ```
    44  
    45  Your output result should be:
    46  
    47  ```
    48  ./
    49      greeter.proto	# original protobuf file
    50      greeter.pb.go	# auto-generated by protoc-gen-go
    51      greeter.micro.go	# auto-generated by protoc-gen-micro
    52  ```
    53  
    54  The micro generated code includes clients and handlers which reduce boiler plate code
    55  
    56  ### Server
    57  
    58  Register the handler with your micro server
    59  
    60  ```go
    61  type Greeter struct{}
    62  
    63  func (g *Greeter) Hello(ctx context.Context, req *proto.Request, rsp *proto.Response) error {
    64  	rsp.Msg = "Hello " + req.Name
    65  	return nil
    66  }
    67  
    68  proto.RegisterGreeterHandler(service.Server(), &Greeter{})
    69  ```
    70  
    71  ### Client
    72  
    73  Create a service client with your micro client
    74  
    75  ```go
    76  client := proto.NewGreeterService("greeter", service.Client())
    77  ```
    78  
    79  ### Errors
    80  
    81  If you see an error about `protoc-gen-micro` not being found or executable, it's likely your environment may not be configured correctly. If you've already installed `protoc`, `protoc-gen-go`, and `protoc-gen-micro` ensure you've included `$GOPATH/bin` in your `PATH`.
    82  
    83  Alternative specify the Go plugin paths as arguments to the `protoc` command
    84  
    85  ```
    86  protoc --plugin=protoc-gen-go=$GOPATH/bin/protoc-gen-go --plugin=protoc-gen-micro=$GOPATH/bin/protoc-gen-micro --proto_path=. --micro_out=. --go_out=. greeter.proto
    87  ```
    88  
    89  ### Endpoint
    90  
    91  Add a micro API endpoint which routes directly to an RPC method
    92  
    93  Usage:
    94  
    95  1. Clone `github.com/googleapis/googleapis` to use this feature as it requires http annotations.
    96  2. The protoc command must include `-I$GOPATH/src/github.com/googleapis/googleapis` for the annotations import.
    97  
    98  ```diff
    99  syntax = "proto3";
   100  
   101  package greeter;
   102  option go_package = "/proto;greeter";
   103  
   104  import "google/api/annotations.proto";
   105  
   106  service Greeter {
   107  	rpc Hello(Request) returns (Response) {
   108  		option (google.api.http) = { post: "/hello"; body: "*"; };
   109  	}
   110  }
   111  
   112  message Request {
   113  	string name = 1;
   114  }
   115  
   116  message Response {
   117  	string msg = 1;
   118  }
   119  ```
   120  
   121  The proto generates a `RegisterGreeterHandler` function with a [api.Endpoint](https://godoc.org/go-micro.dev/v3/api#Endpoint). 
   122  
   123  ```diff
   124  func RegisterGreeterHandler(s server.Server, hdlr GreeterHandler, opts ...server.HandlerOption) error {
   125  	type greeter interface {
   126  		Hello(ctx context.Context, in *Request, out *Response) error
   127  	}
   128  	type Greeter struct {
   129  		greeter
   130  	}
   131  	h := &greeterHandler{hdlr}
   132  	opts = append(opts, api.WithEndpoint(&api.Endpoint{
   133  		Name:    "Greeter.Hello",
   134  		Path:    []string{"/hello"},
   135  		Method:  []string{"POST"},
   136  		Handler: "rpc",
   137  	}))
   138  	return s.Handle(s.NewHandler(&Greeter{h}, opts...))
   139  }
   140  ```
   141  
   142  ## LICENSE
   143  
   144  protoc-gen-micro is a liberal reuse of protoc-gen-go hence we maintain the original license