github.com/phpstudyer/protoreflect@v1.7.2/README.md (about)

     1  # Protocol Buffer and gRPC Reflection
     2  [![Build Status](https://travis-ci.com/phpstudyer/protoreflect.svg?branch=master)](https://travis-ci.com/github/phpstudyer/protoreflect/branches)
     3  [![Go Report Card](https://goreportcard.com/badge/github.com/phpstudyer/protoreflect)](https://goreportcard.com/report/github.com/phpstudyer/protoreflect)
     4  
     5  This repo provides reflection APIs for [protocol buffers](https://developers.google.com/protocol-buffers/) (also known as "protobufs" for short)
     6  and [gRPC](https://grpc.io/). The core of reflection in protobufs is the
     7  [descriptor](https://github.com/google/protobuf/blob/199d82fde1734ab5bc931cd0de93309e50cd7ab9/src/google/protobuf/descriptor.proto).
     8  A descriptor is itself a protobuf message that describes a `.proto` source file or any element
     9  therein. So a collection of descriptors can describe an entire schema of protobuf types, including
    10  RPC services.
    11  
    12  [![GoDoc](https://godoc.org/github.com/phpstudyer/protoreflect?status.svg)](https://godoc.org/github.com/phpstudyer/protoreflect)
    13  
    14  ----
    15  ## Descriptors: The Language Model of Protocol Buffers
    16  
    17  ```go
    18  import "github.com/phpstudyer/protoreflect/desc"
    19  ```
    20  
    21  The `desc` package herein introduces a `Descriptor` interface and implementations of it that
    22  correspond to each of the descriptor types. These new types are effectively smart wrappers around
    23  the [generated protobuf types](https://github.com/golang/protobuf/blob/master/protoc-gen-go/descriptor/descriptor.pb.go)
    24  that make them *much* more useful and easier to use.
    25  
    26  You can construct descriptors from file descriptor sets (which can be generated by `protoc`), and
    27  you can also load descriptors for messages and services that are linked into the current binary.
    28  "What does it mean for messages and services to be linked in?" you may ask. It means your binary
    29  imports a package that was generated by `protoc`. When you generate Go code from your `.proto`
    30  sources, the resulting package has descriptor information embedded in it. The `desc` package allows
    31  you to easily extract those embedded descriptors.
    32  
    33  Descriptors can also be acquired directly from `.proto` source files (using the `protoparse` sub-package)
    34  or by programmatically constructing them (using the `builder` sub-package).
    35  
    36  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/desc)*
    37  
    38  ```go
    39  import "github.com/phpstudyer/protoreflect/desc/protoparse"
    40  ```
    41  
    42  The `protoparse` package allows for parsing of `.proto` source files into rich descriptors. Without
    43  this package, you must invoke `protoc` to either generate a file descriptor set file or to generate
    44  Go code (which has descriptor information embedded in it). This package allows reading the source
    45  directly without having to invoke `protoc`.
    46  
    47  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/desc/protoparse)*
    48  
    49  ```go
    50  import "github.com/phpstudyer/protoreflect/desc/protoprint"
    51  ```
    52  
    53  The `protoprint` package allows for printing of descriptors to `.proto` source files. This is
    54  effectively the inverse of the `protoparse` package. Combined with the `builder` package, this
    55  is a useful tool for programmatically generating protocol buffer sources.
    56  
    57  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/desc/protoprint)*
    58  
    59  ```go
    60  import "github.com/phpstudyer/protoreflect/desc/builder"
    61  ```
    62  
    63  The `builder` package allows for programmatic construction of rich descriptors. Descriptors can
    64  be constructed programmatically by creating trees of descriptor protos and using the `desc` package
    65  to link those into rich descriptors. But constructing a valid tree of descriptor protos is far from
    66  trivial.
    67  
    68  So this package provides generous API to greatly simplify that task. It also allows for converting
    69  rich descriptors into builders, which means you can programmatically modify/tweak existing
    70  descriptors.
    71  
    72  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/desc/builder)*
    73  
    74  ----
    75  ## Dynamic Messages and Stubs
    76  
    77  ```go
    78  import "github.com/phpstudyer/protoreflect/dynamic"
    79  ```
    80  
    81  The `dynamic` package provides a dynamic message implementation. It implements `proto.Message` but
    82  is backed by a message descriptor and a map of fields->values, instead of a generated struct. This
    83  is useful for acting generically with protocol buffer messages, without having to generate and link
    84  in Go code for every kind of message. This is particularly useful for general-purpose tools that
    85  need to operate on arbitrary protocol buffer schemas. This is made possible by having the tools load
    86  descriptors at runtime.
    87  
    88  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/dynamic)*
    89  
    90  ```go
    91  import "github.com/phpstudyer/protoreflect/dynamic/grpcdynamic"
    92  ```
    93  
    94  There is also sub-package named `grpcdynamic`, which provides a dynamic stub implementation. The stub can
    95  be used to issue RPC methods using method descriptors instead of generated client interfaces.
    96  
    97  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/dynamic/grpcdynamic)*
    98  
    99  ----
   100  ## gRPC Server Reflection
   101  
   102  ```go
   103  import "github.com/phpstudyer/protoreflect/grpcreflect"
   104  ```
   105  
   106  The `grpcreflect` package provides an easy-to-use client for the
   107  [gRPC reflection service](https://github.com/grpc/grpc-go/blob/6bd4f6eb1ea9d81d1209494242554dcde44429a4/reflection/grpc_reflection_v1alpha/reflection.proto#L36),
   108  making it much easier to query for and work with the schemas of remote services.
   109  
   110  It also provides some helper methods for querying for rich service descriptors for the
   111  services registered in a gRPC server.
   112  
   113  *[Read more ≫](https://godoc.org/github.com/phpstudyer/protoreflect/grpcreflect)*