github.com/phpstudyer/protoreflect@v1.7.2/desc/doc.go (about) 1 // Package desc contains "rich descriptors" for protocol buffers. The built-in 2 // descriptor types are simple protobuf messages, each one representing a 3 // different kind of element in the AST of a .proto source file. 4 // 5 // Because of this inherent "tree" quality, these build-in descriptors cannot 6 // refer to their enclosing file descriptor. Nor can a field descriptor refer to 7 // a message or enum descriptor that represents the field's type (for enum and 8 // nested message fields). All such links must instead be stringly typed. This 9 // limitation makes them much harder to use for doing interesting things with 10 // reflection. 11 // 12 // Without this package, resolving references to types is particularly complex. 13 // For example, resolving a field's type, the message type an extension extends, 14 // or the request and response types of an RPC method all require searching 15 // through symbols defined not only in the file in which these elements are 16 // declared but also in its transitive closure of dependencies. 17 // 18 // "Rich descriptors" avoid the need to deal with the complexities described 19 // above. A rich descriptor has all type references resolved and provides 20 // methods to access other rich descriptors for all referenced elements. Each 21 // rich descriptor has a usefully broad API, but does not try to mimic the full 22 // interface of the underlying descriptor proto. Instead, every rich descriptor 23 // provides access to that underlying proto, for extracting descriptor 24 // properties that are not immediately accessible through rich descriptor's 25 // methods. 26 // 27 // Rich descriptors can be accessed in similar ways as their "poor" cousins 28 // (descriptor protos). Instead of using proto.FileDescriptor, use 29 // desc.LoadFileDescriptor. Message descriptors and extension field descriptors 30 // can also be easily accessed using desc.LoadMessageDescriptor and 31 // desc.LoadFieldDescriptorForExtension, respectively. 32 // 33 // It is also possible create rich descriptors for proto messages that a given 34 // Go program doesn't even know about. For example, they could be loaded from a 35 // FileDescriptorSet file (which can be generated by protoc) or loaded from a 36 // server. This enables interesting things like dynamic clients: where a Go 37 // program can be an RPC client of a service it wasn't compiled to know about. 38 // 39 // Also see the grpcreflect, dynamic, and grpcdynamic packages in this same 40 // repo to see just how useful rich descriptors really are. 41 package desc