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