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

     1  [English](README.md) | 中文
     2  
     3  # plugin
     4  
     5  tRPC-Go 在设计上遵循了插件化架构理念，通过插件来实现框架核心与各种生态体系的对接，提供了框架的开放性和可扩展性。
     6  `plugin` 包用于管理需要依赖配置进行加载的插件。
     7  而不需要依赖配置的插件相对简单，如 [codec 插件](/codec/README.zh_CN.md)，这里不再讨论。
     8  因此我们将先介绍 `plugin` 包的设计，然后在此基础上阐述如何开发一个需要依赖配置进行加载的插件。
     9  
    10  ## `plugin` 包的设计
    11  
    12  `plugin` 包通过“插件工厂”来管理所有插件的，每个插件都需要注册到插件工厂。
    13  插件工厂采用了两级管理模式：
    14  第一级为插件类型，例如，log 类型, conf 类型， selector 类型等。
    15  第二级为插件名称，例如，conf 的插件有本地文件配置，远程文件配置，本地数据库配置等。
    16  
    17  ```ascii
    18                         +-----------------+
    19                     +---+  Plugin Factory +----+
    20                     |   +--------+--------+    |
    21                     |            |             |
    22                 +---v--+      +--v--+     +----v-----+
    23       +---------+ conf |      | log |     | selector |
    24       |         +---+--+      +-----+     +----+-----+
    25       |             |                          |
    26  +----v-----+ +-----v-------+             +----v----+
    27  |local-file| | remote-file |    ......   | polaris |
    28  +----------+ +-------------+             +---------+
    29  ```
    30  
    31  对于插件的类型，`plugin` 包并没有做限制，你可以自行添加插件类型。
    32  
    33  
    34  ### 常见的插件类型
    35  
    36  按照功能划分，框架提供以下5种类型的常见插件：
    37  
    38  - 配置：提供获取配置的标准接口，通过从本地文件，配置中心等多种数据源获取配置数据，提供 json，yaml 等多种格式的配置解析，同时框架也提供了 watch 机制，来实现配置的动态更新。
    39  - 日志：提供了统一的日志打印和日志上报标准接口。日志插件通过实现日志上报接口来完成和远程日志系统的对接
    40  - 协议：提供协议编解码相关的标准接口，允许通过插件的方式来扩展业务协议、序列化类型、数据压缩方式等协议处理
    41  - 名字服务：提供包括服务注册，服务发现，策略路由，负载均衡，熔断等标准接口，用于实现服务路由寻址。
    42  - 拦截器：提供通用拦截器接口，用户可以在服务调用的上下文设置埋点，实现例如模调监控，横切日志，链路跟踪，过载保护等功能。
    43  
    44  
    45  ## 如何开发一个需要依赖配置进行加载的插件
    46  
    47  开发一个需要依赖配置进行加载的插件通常需要实现插件和配置插件，[可运行的具体的示例](/examples/features/plugin)
    48  
    49  ### 实现插件
    50  
    51  1. 该插件实现 `plugin.Factory` 接口。
    52  ```go
    53  // Factory 插件工厂统一抽象 外部插件需要实现该接口，通过该工厂接口生成具体的插件并注册到具体的插件类型里面
    54  type Factory interface {
    55      // Type 插件的类型 如 selector log config tracing
    56      Type() string
    57      // Setup 根据配置项节点装载插件，用户自己先定义好具体插件的配置数据结构
    58      Setup(name string, configDec Decoder) error
    59  }
    60  ```
    61  2. 该插件调用 `plugin.Register` 把自己插件注册到 `plugin` 包。
    62  
    63  ```
    64  // Register 注册插件工厂 可自己指定插件名，支持相同的实现 不同的配置注册不同的工厂实例
    65  func Register(name string, p Factory)
    66  ```
    67  
    68  ### 配置插件
    69  
    70  1. 在 `main` 包中 import 该插件对应的包。
    71  2. 在配置文件中的 `plugins` 字段下面配置该插件。
    72     配置文件格式为：
    73  ```yaml
    74  # 插件配置
    75  plugins:
    76    # 插件类型
    77    log:
    78      # 插件名
    79      logger1:
    80        # 插件详细配置，具体请参考各个插件的说明
    81        ....
    82      logger2:
    83        # 插件详细配置，具体请参考各个插件的说明
    84        ....
    85    # 插件类型
    86    config:
    87      # 插件名
    88      local-file:
    89        # 插件详细配置，具体请参考各个插件的说明
    90        ....
    91      remote-file:
    92        # 插件详细配置，具体请参考各个插件的说明
    93  ```
    94  
    95  上面定义了 2 个插件类型和 4 个插件。
    96  log 类型的插件下有 logger1 和 logger2 插件。
    97  config 类型的插件下有 local-file 和 remote-file 插件。
    98  
    99  ### 插件的初始化顺序
   100  
   101  tRPC-GO server 调用 `trpc.NewServer()` 函数之后，会读取框架配置文件中“plugins”字段下所有插件配置，然后调用每个插件的“Setup()”函数来完成插件配置的初始化。
   102  一般情况下，插件之间是相互独立的，框架会按随机顺序逐个初始化插件（比如 A 插件依赖 B 插件）。
   103  如果某个插件依赖其它插件可以实现以下方法来声明依赖关系。
   104  
   105  ```go
   106  // Depender 是 "强依赖" 的接口。 
   107  // 如果插件 a "强烈" 依赖插件 b，那么 b 必须存在， 
   108  // a 将在 b 初始化之后进行初始化。 
   109  type Depender interface { 
   110      // DependsOn 返回依赖的插件列表。 
   111      // 列表元素的格式为 "类型-名称"，例如 [ "selector-polaris" ]。 
   112      DependsOn() []string
   113  }
   114  
   115  // FlexDepender 是 "弱依赖" 的接口。 
   116  // 如果插件 a "弱" 依赖插件 b，并且 b 确实存在， 
   117  // 那么 a 将在 b 初始化之后进行初始化。 
   118  type FlexDepender interface { 
   119      FlexDependsOn() []string
   120  }
   121  ```
   122  
   123  依赖关系分为强依赖和弱依赖。
   124  强依赖要求被依赖的插件必须存在，不存在框架会 panic。
   125  弱依赖则不会 panic。
   126  框架会先确保所有强依赖都被满足，然后再检查弱依赖。
   127  
   128  例如，在下面的例子中，插件的初始化强依赖于 selector 类型的插件 a，弱依赖于 config 类型的插件 b。
   129  
   130  ```go
   131  func (p *Plugin) DependsOn() []string {
   132      return []string{"selector-a"}
   133  }
   134  func (p *Plugin) FlexDependsOn() []string {
   135      return []string{"config-b"}
   136  }
   137  ```