Feature: Decorator Support

[shigma]

本 RFC 用于讨论未来将要引入的官方装饰器支持。

本 RFC 只讨论 Koishi / Satori / Cordis 相关特性。请不要讨论与 Minato / Schemastery 相关的话题。

核心思想

在 Koishi 中引入装饰器时，需要确保以下性质：

• 以减轻插件开发负担为目标，避免引入重型 DI 范式
• 仅将装饰器作为现有 API 的语法糖，不应涉及任何新概念

优势分析

引入装饰器可以带来以下好处：

• 简化类插件的开发，可以直接将方法作为事件和中间件的回调函数，而无需在构造函数中手动绑定
• 服务不再需要继承 Service 基类，从而可以继承其他库中的类
• 装饰器修饰的函数需要手动标注类型，因此可以忽略 AsyncGenerator doesn't play nicely with TNext = Promise<...> microsoft/TypeScript#44808 和 Bug: incorrect contextual typing on yield expression of generator function as discriminate of a union microsoft/TypeScript#51187 在指令回调函数中引入 yield (feat(core): support generator function as command action #819)
• 未来可以引入基于类的 Schema 或 Model (尽管它们不在本 RFC 的讨论范围)

现有方案

目前社区中已经存在 koishi-thirdeye 方案。但它基于旧版装饰器语法，不仅在接口上不兼容 Stage 3 Decorator Proposal，还大量包含了部分已经废弃的用法 (例如 Argument Decorator)，因此不能直接使用。此外，该方案存在大型依赖，也不适用于 Koishi 的轻量化需求。

计划实现的 API

对于装饰器的支持计划分为多个阶段完成，每个阶段实现一部分 API。

事件和中间件

class MyPlugin {
  @Event()
  callback1(...args) {}

  @Middleware()
  callback2(session, next) {}
}

服务与依赖

目前有两种设计方案，欢迎大家讨论。

• 方案一：使用 Service / Using。
• 优点：与 Koishi 中的命名相符。

@Service('foo')
class FooService {
  @Using('bar')
  bar: BarService

  constructor() {
    // 这里不需要继承和调用 super
  }
}

• 方案二：使用 Provide / Inject。
• 优点：与依赖注入的概念相符；不需要重载 Service 函数。

@Provide('foo')
class FooService {
  @Inject('bar')
  bar: BarService

  constructor() {
    // 这里不需要继承和调用 super
  }
}

指令开发

待定。

配置声明 / 数据库声明

不在本 RFC 的讨论范围。未来可能会有独立的 RFC。

上游进度

目前 TypeScript 已经完成了对 Decorator 的初步支持 (语法、类型检查)，尚有部分功能待完善 (类型推导)：

• Implement the Stage 3 Decorators Proposal microsoft/TypeScript#50820

esbuild 在 0.18.4 版本后无法编译含有 decorator 的源代码，但计划未来支持：

• Feature request: Decorators support evanw/esbuild#104 (comment)

对于此特性的开发需要等待上游生态完成并稳定后才会开始。

[idranme]

上游进度 (May 16, 2024)

• Feature request: Decorators support evanw/esbuild#104 (comment)