18、自定义 API 方法：灵活与权衡

自定义 API 方法：灵活与权衡

1. 背景与概述

在 API 设计中，当标准方法无法满足需求时，可采用自定义方法来隔离功能，避免对现有标准方法造成重载。自定义方法是指超出标准方法范围的 API 调用，不受标准方法严格规则的约束。

标准方法为 API 提供了强大的构建模块，但广泛的适用范围也伴随着大量的准则、规则和限制。而自定义方法几乎没有限制，能够根据具体场景自由发挥，以实现最佳效果。不过，这也带来了一些问题，API 用户对自定义方法的预期不如标准方法明确。因此，API 设计者需要自行制定一套规则，并确保在整个 API 中保持一致性。

以下是一个自定义方法的示例，用于发射火箭：

abstract class Rocket {
  @post("/{id=rockets/*}:launch")  // #A
  LaunchRocket(LaunchRocketRequest req): Rocket;  // #B
}

interface Rocket {
  id: string;
  // ...
}

interface LaunchRocketRequest {
  id: string;
}

• A：自定义方法使用 POST HTTP 动词和特殊的 “:” 分隔符来声明操作本身。

• B：自定义方法遵循与标准方法类似的命名约定（动词 + 名词）。

2. 实现细节

2.1 HTTP 请求格式