插件中的对象管理

在插件中你可以使用 Spring Framework 提供的常用 Bean 注解来标注一个类，然后就能使用依赖注入功能注入其他类的对象。这省去了使用工厂创建类和维护的过程，你可以像开发一个常规的 Spring 项目一样来开发插件，目前支持以下 Spring Framework 的特性：

1. Core Technologies
2. Web on Reactive
3. Testing

通过模板插件创建的项目中你会看到 StarterPlugin 标注了 @Component 注解：

@Component
public class StarterPlugin extends BasePlugin {
}

假设项目中有一个 FruitService，并将其声明了为了 Bean：

@Service
public class FruitService {

}

你可以在任何同样声明为 Bean 的类中使用依赖注入来使用它：

@Component
public class Demo {
  private final FruitService fruitService;

  public Demo(FruitService fruitService) {
    this.fruitService = fruitService;
  }
  // use it...
}

依赖注入 Halo 共享的 Bean

Halo 提供了一些共享的 Bean，任何插件都可以直接依赖注入这些 Bean。

ReactiveExtensionClient

ReactiveExtensionClient 是一个用于管理自定义模型对象的增删改查的 Bean，它是反应式的。

参考 与自定义模型交互 了解更多。

ExtensionClient

ExtensionClient 作用和方法与 ReactiveExtensionClient 一样，但它是阻塞的，只能用在非 NIO 线程中，如后台任务。

SchemeManager

SchemeManager 是一个用于管理自定义模型定义的注册和销毁的 Bean。

API 参考：SchemeManager

UserService

用于操作 Halo 用户的 Bean，包括获取用户信息、更新密码、创建用户等函数。

API 参考 UserService

ReactiveUserDetailsService

用于获取用户信息的 Bean，它只有一个方法 Mono<UserDetails> findByUsername(String username)。

RoleService

用于操作 Halo 角色的 Bean，包括查询角色绑定、角色及依赖等函数。

API 参考 RoleService

AttachmentService

用于操作 Halo 附件的 Bean，包括上传、删除附件以及获取附件访问链接等函数。

API 参考 AttachmentService。

PostContentService

在 Halo 中，文章内容具有版本管理的概念。第一个版本是完整的文章内容，称为 baseSnapshot。从第二个版本开始，每个版本都是基于 baseSnapshot 的增量内容。因此，要查询完整的文章内容，需要获取 baseSnapshot 以及对应的版本增量内容并合并。

为了方便插件开发者获取文章内容，Halo 提供了 PostContentService，以简化这一过程的复杂性。

• getHeadContent：获取文章的最新版本内容（包括正在编辑的草稿）。
• getReleaseContent：获取最新发布的文章内容。
• getSpecifiedContent：获取指定 snapshotName 对应的文章内容。
• listSnapshots：获取指定文章的所有版本的 Snapshot 对象的名称列表。

API 参考：PostContentService 文章自定义模型定义参考 Post

NotificationReasonEmitter

用于发送通知事件的 Bean。

使用示例

假如有一个 NEW_COMMENT_ON_POST 文章有新评论的通知事件，你可以这样发送通知：

Mono<Void> emitNewCommentOnPostReason(/* 此示例省略参数 */) {
  return notificationReasonEmitter.emit(NotificationReasonConst.NEW_COMMENT_ON_POST,
  builder -> {
    // 填充事件的数据
    var attributes = CommentOnPostReasonData.builder()
      .postName(subjectRef.getName())
      .postOwner(post.getSpec().getOwner())
      .postTitle(post.getSpec().getTitle())
      .postUrl(postUrl)
      .commenter(owner.getDisplayName())
      .content(comment.getSpec().getContent())
      .commentName(comment.getMetadata().getName())
      .build();
    builder.attributes(ReasonDataConverter.toAttributeMap(attributes))
      .author(identityFrom(owner))
      .subject(reasonSubject);
  })
}

API 参考：NotificationReasonEmitter

NotificationCenter

用于管理通知的订阅和取消订阅。

API 参考：NotificationCenter

ExternalLinkProcessor

用于将一个站内相对链接转换为绝对链接。

如配置了外部访问地址为 https://example.com，那么将 /post/1 转换为 https://example.com/post/1。

API 参考：ExternalLinkProcessor;

LoginHandlerEnhancer

Halo 提供了登录增强机制，插件可以在登录成功或失败时调用登录增强器，使 Halo 可以执行额外的处理逻辑。

参考 登录增强器 了解更多。

使用示例参考 用户名密码登陆成功和失败的增强切入示例

BackupRootGetter

用于获取 Halo 备份文件的根目录。它是 Supplier<Path> 的子类。

PluginsRootGetter

用于获取 Halo 插件的根目录。它是 Supplier<Path> 的子类。

ExtensionGetter

用于获取扩展点实例（扩展）的 Bean。

例如，Halo 定义了 AttachmentHandler 这个扩展点，你可以通过 ExtensionGetter 获取到所有实现了 AttachmentHandler 接口的扩展。

有了它，插件中便可以定义自己的扩展点，然后由其他插件实现以达到插件扩展插件的目的。

API 参考 ExtensionGetter

ServerSecurityContextRepository

用于获取操作用户的认证上下文信息，如登录成功后保存认证信息。

ServerSecurityContextRepository 被 ReactorContextWebFilter 使用来获取操作用户的认证上下文信息并填充到 ReactiveSecurityContextHolder 中。 此过滤器的执行顺序在 SecurityWebFiltersOrder 中定义。因此如果你的过滤器在此过滤器之前执行，那么你将无法从 ReactiveSecurityContextHolder 中获取到操作用户的认证上下文信息只能通过注入 ServerSecurityContextRepository 来获取。

API 参考：ServerSecurityContextRepository

CryptoService

Halo 根据用户名密码登录时，会先使用 CryptoService 的 readPublicKey 方法读取公钥，然后使用公钥加密密码，再发送给服务器。

当插件需要添加一些拦截器处理登录请求时可能需要获取原始密码，此时可以使用 CryptoService 的 decrypt 方法解密密码。

也可以复用它的公钥来作为一些加密算法的密钥。

API 参考 CryptoService

ExternalUrlSupplier

ExternalUrlSupplier 是一个用于获取用户配置的 Halo 外部访问地址的 Bean。

API 参考：ExternalUrlSupplier

RateLimiterRegistry

RateLimiterRegistry 是一个用于管理限流器的 Bean。

如果插件定义的某些 API 需要限流，可以使用 RateLimiterRegistry 来创建一个限流器，但是需要注意的是，必须要在插件停止的生命周期方法里销毁你所创建的限流器，否则会导致内存泄漏。

使用示例

以下示例展示了如何使用 RateLimiterRegistry 创建一个限流器：

final Set<String> limiterNames = new HashSet<>();

Mono<Void> sendEmailVerificationCode(String username, String email) {
  return buildSendEmailRateLimiter(username, email) // step 1: 构建一个限流器
      .transformDeferred(rateLimiter -> rateLimiter.map(RateLimiterOperator::of)) // step 2: 返回一个经过变换的新 Mono
      // step 3: 从这里开始的操作符都会受到限流的影响
      .flatMap(rateLimiter -> emailVerificationService.sendVerificationCode(username, email))
      // 转换 RequestNotPermitted 为 RateLimitExceededException 以使全局异常处理器能够处理
      .onErrorMap(RequestNotPermitted.class, RateLimitExceededException::new);
}

RateLimiter buildSendEmailRateLimiter(String username, String email) {
  var rateLimiterKey = "send-email-verification-code-" + username + ":" + email;
  var rateLimiter = rateLimiterRegistry.rateLimiter(rateLimiterKey, new RateLimiterConfig.Builder()
    // 频次限制为 1 次
    .limitForPeriod(1)
    // 限制刷新周期为 60 秒, 即 60 秒内只能执行 1 次
    .limitRefreshPeriod(Duration.ofSeconds(60))
    .build());
  // 添加 limiter 到自己实现的 Registry 中保存起来以便在插件停止时清理
  limiters.add(rateLimiterKey);
  return limiter;
}

在插件停止的生命周期方法里销毁你所创建的限流器：

@Override
public void stop() {
  limiters.forEach(rateLimiterRegistry::remove);
}

transformDeferred 的作用是将 Mono 传入你提供的变换器中，返回一个经过变换的新 Mono。由于 RateLimiterOperator 是基于 Publisher 的装饰器（decorator），它会监视这个 Mono 的订阅和执行情况，从而对整个 Mono 的操作链进行限流。

换句话说，因为 RateLimiterOperator 装饰了这个 Mono，所以任何接在 transformDeferred() 之后的操作符都会受到限流的影响，直到整个流结束。