trpc.group/trpc-go/trpc-go@v1.0.3/naming/README.md (about)

     1  English | [中文](README.zh_CN.md)
     2  
     3  ## Background
     4  
     5  Package `naming` can register nodes under the corresponding service name. In addition to `ip:port`, the registration information will also include the running environment, container and other customized metadata information. After the caller obtains all nodes based on the service name, the routing module filters the nodes based on metadata information. Finally, the load balancing algorithm selects a node from the nodes that meet the requirements to make the final request. The name provides a unified abstraction for service management and avoids the operation and maintenance difficulties caused by directly using `ip:port`.
     6  
     7  In tRPC-Go, the `register` package defines the registration specification of the server, and `discovery`, `servicerouter`, `loadbalance`, and `circuitebreaker` together form the `slector` package and define the client's service discovery specification.
     8  
     9  ## Principle
    10  
    11  Let's first look at the design of the `naming`:
    12  
    13  ![naming design](/.resources/naming/naming.png)
    14  
    15  Based on the above diagram, let's briefly introduce the approximate design and implementation.
    16  
    17  ## Implementation
    18  
    19  ### Discovery
    20  
    21  Discovery defines the common interface for service discovery, which returns a list of service addresses based on the given service name.
    22  
    23  Discovery supports custom implementation for business needs. The framework provides a default IpDiscovery that returns a list of IP addresses specified in the configuration file.
    24  
    25  ### Node
    26  
    27  Node defines the data structure of a single service node.
    28  
    29  ### Registry
    30  
    31  Registry defines the common interface for service registration and supports custom implementation for Register and Deregister operations.
    32  
    33  ### LoadBalancer
    34  
    35  LoadBalancer defines the common interface for load balancing, which takes in an array of Nodes and returns a load-balanced Node.
    36  
    37  trpc-go provides default implementations of load balancing algorithms such as round-robin and weighted round-robin. Businesses can also customize their own load balancing algorithms.
    38  - [Consistent Hash](/naming/loadbalance/consistenthash)
    39  - [Round-robin](/naming/loadbalance/roundrobin)
    40  - [Weighted Round-robin](/naming/loadbalance/weightroundrobin)
    41  
    42  ### ServiceRouter
    43  
    44  ServiceRouter defines the interface for routing and filtering service Nodes, such as routing based on Set configuration, Namespace/Env environment, etc.
    45  
    46  ### Selector
    47  
    48  Selector provides a common interface for obtaining a service node by service name. Within the selector, service discovery, load balancing, and circuit breaking isolation are called, making it an assembly of these capabilities.
    49  
    50  trpc-go provides the default implementation of the selector, which uses default service discovery, load balancing, and circuit breaker. For more information, please refer to [./selector/trpc_selector.go](/naming/selector/trpc_selector.go).
    51  
    52  Default selector logic: Discovery -> ServiceRouter -> LoadBalance -> Node -> Business usage -> CircuitBreaker.Report.
    53  
    54  ### CircuitBreaker
    55  
    56  CircuitBreaker provides a common interface for determining whether a service node is available, and also provides the ability to report the success or failure of the current service node.
    57  
    58  ### How to use
    59  
    60  tRPC-Go supports [polaris mesh](https://github.com/trpc-ecosystem/go-naming-polarismesh), which can discovery nodes by service name. If the business sets the target when calling, the endpoint of the target will be used to discovery.
    61  
    62  ```go
    63  client.WithTarget(fmt.Sprintf("%s://%s", exampleScheme, exampleServiceName)),
    64  ```
    65  
    66  Target is the backend service address in the format of `name://endpoint`. For example, `ip://127.0.0.1:80` will directly access `127.0.0.1:80` according to `ip:port`; `polaris://service_name` will address the service name `service_name` through the Polaris plug-in .
    67  
    68  The following example provides an implementation of custom service discovery for business use.
    69  
    70  1. Implement the Selector interface.
    71     ```go
    72     type exampleSelector struct{}
    73     // Select obtains a backend node by service name.
    74     func (s *exampleSelector) Select(serviceName string, opt ...selector.Option) (*registry.Node,    error) {
    75         fmt.Println(serviceName)
    76         if serviceName == exampleServiceName {
    77             return &registry.Node{
    78                 Address: "127.0.0.1:8000",
    79             }, nil
    80         }
    81         return nil, errors.New("no available node")
    82     }
    83     // Report reports the success or failure of the current request.
    84     func (s *exampleSelector) Report(node *registry.Node, cost time.Duration, success error) error {
    85         return nil
    86     }
    87     ```
    88  
    89  2. Register the custom selector
    90     ```go
    91     var exampleScheme = "example"
    92     func init() {
    93         selector.Register(exampleScheme, &exampleSelector{})
    94     }
    95     ```
    96  
    97  3. Set the service name
    98     ```go
    99     var exampleServiceName = "selector.example.trpc.test"
   100     client.WithTarget(fmt.Sprintf("%s://%s", exampleScheme, exampleServiceName))
   101     ```
   102  
   103  For more details, please refer to [selector demo](/examples/features/selector).