如何用Symbol安全扩展TypeScript全局声明的Response类？

Fetch的Response类内置了几个便捷静态方法：

• error()
• redirect(url, status)
• json(data, init)

我想通过声明合并给它添加自定义静态方法，同时用Symbol避免命名冲突，但在扩展全局Response类时遇到了TypeScript语法问题。

不用Symbol的不安全版本可以正常实现：

function _html(body?: BodyInit | null, init?: ResponseInit): Response {
  const headers = new Headers(init?.headers);
  if (!headers.has("Content-Type")) {
    headers.set("Content-Type", "text/html");
  }
  return new Response(body, { ...init, headers });
}

declare global {
  namespace Response {
    const html: typeof _html;
  }
}

Object.defineProperty(Response, "html", { value: _html });

但尝试用unique symbol作为方法名时，找不到有效语法，代码会报迭代器相关错误：

export const html = Symbol();

function _html(body?: BodyInit | null, init?: ResponseInit): Response {
  const headers = new Headers(init?.headers);
  if (!headers.has("Content-Type")) {
    headers.set("Content-Type", "text/html");
  }
  return new Response(body, { ...init, headers });
}

declare global {
  namespace Response {
    const [html]: typeof _html;
       // ^^^^^^ Type '(body?: BodyInit | null | undefined, init?: ResponseInit | undefined) => Response' must have a '[Symbol.iterator]()' method that returns an iterator.(2488)
  }
}

Object.defineProperty(Response, html, { value: _html });

正确实现方案 #

要通过Symbol安全扩展Response静态属性，需要按以下步骤调整：

// 声明为unique symbol类型，确保类型唯一性
export const html: unique symbol = Symbol();

function _html(body?: BodyInit | null, init?: ResponseInit): Response {
  const headers = new Headers(init?.headers);
  if (!headers.has("Content-Type")) {
    headers.set("Content-Type", "text/html");
  }
  return new Response(body, { ...init, headers });
}

declare global {
  // 使用计算属性语法定义Symbol键的静态属性
  interface ResponseConstructor {
    [html]: typeof _html;
  }
}

// 将方法挂载到Response构造函数上
Object.defineProperty(Response, html, { value: _html });

关键说明 #

1. unique symbol类型：把Symbol声明为unique symbol，让TypeScript识别这是一个唯一的属性标识，避免类型冲突。
2. 计算属性语法：在全局接口声明中用[html]的写法，告诉TypeScript这是一个Symbol键的属性，而非数组解构语法。
3. 类型与实现对应：通过Object.defineProperty将方法挂载到Response上，确保和声明的类型完全匹配。

这样既实现了自定义静态方法的扩展，又通过Symbol避免了命名冲突，同时通过TypeScript的类型检查。

内容的提问来源于stack exchange，提问作者mfulton26