TypeScript 单例模式实战:class、namespace 与模块三种实现的取舍(深入理解 TypeScript)

原创2026-10-07 21:47:401,391 阅读
文章标签:文档教程

TypeScript 单例模式实战:class、namespace 与模块三种实现的取舍(深入理解 TypeScript)

本指南源于《深入理解 TypeScript》(typescript-book-chinese)的 docs/tips/singletonPatern.md 章节,结合 docs/project/namespaces.md、docs/project/modules.md 等仓库章节展开。读完你将掌握:在 TypeScript 中实现"全局唯一实例"的三种经典写法(class 静态单例、namespace、文件模块),理解各自编译产物与适用场景,并学会在真实项目中避开"为了单例而单例"的陷阱。

单例模式(Singleton)是开发中高频出现的代码组织模式:它保证某个类在进程内只有一个实例,并提供一个全局访问点。TypeScript 中实现单例有多种路径,从传统的"私有构造函数 + 静态 getInstance",到利用 namespace 关键字,再到最现代的文件模块方案。本文按《深入理解 TypeScript》中文版 docs/tips/singletonPatern.md 的脉络,逐一剖析三种写法,并给出仓库源码级的编译原理佐证与选型建议。

一、经典单例:私有构造函数 + 静态方法

原文档给出的传统实现如下:

class Singleton {
  private static instance: Singleton;
  private constructor() {
    // ..
  }

  public static getInstance() {
    if (!Singleton.instance) {
      Singleton.instance = new Singleton();
    }

    return Singleton.instance;
  }

  someMethod() {}
}

let someThing = new Singleton(); // Error: constructor of 'singleton' is private

let instance = Singleton.getInstance(); // do some thing with the instance

关键点逐一拆解:

  • private constructor():把构造函数标记为私有,阻止外部通过 new Singleton() 创建实例。编译期 TypeScript 会直接报错 Error: constructor of 'singleton' is private(原文档示例中 instacne 为拼写笔误,正确写法是 instance)。
  • private static instance: Singleton:静态属性承载唯一实例,private 保证只能被类内部访问。
  • public static getInstance():懒初始化(lazy initialization)入口——仅在首次调用时创建实例,后续调用直接复用,实现"全局唯一"。

从编译原理看,这个写法在 JavaScript 运行时层面并没有真正的"私有性"和"唯一性"魔法。把编译产物摊开(假设 module: commonjs),Singleton.instance 实际上是一个模块级闭包变量,getInstance 通过 if (!Singleton.instance) 守卫保证只 new 一次。这意味着:

  • 单例的"唯一性"依赖调用方约定只能走 getInstance(),而 private constructor 仅提供编译期的静态约束;
  • 类这种写法要求所有代码都写进 class 里(成员、初始化逻辑、工具方法),当单例承载的逻辑较多时,类的体积和耦合度都会膨胀。

正是这个"所有代码必须写到 class 中"的约束,引出了下面的 namespace 方案。

二、消除样板:用 namespace 组织全局代码

如果你不想延迟初始化,原文档推荐用 namespace 替代 class 单例:

namespace Singleton {
  // .. 其他初始化的代码

  export function someMethod() {}
}

// 使用
Singleton.someMethod();

namespace 是 TypeScript 提供的"逻辑分组"语法。仓库的 docs/project/namespaces.md 解释了它的本质:namespace 关键字编译后的 JavaScript 代码,等价于早期 JavaScript 中常见的"立即执行函数 + 合并对象"模式:

(function (Utility) {
  // 添加属性至 Utility
})(Utility || (Utility = {}));

这段 IIFE 模式里,Utility || (Utility = {}) 允许匿名函数向已有对象添加内容,或者创建新对象再添加内容——这正是 namespace 在多个文件/代码块间合并、扩展同名成员的底层机制。对照之下,namespace Singleton 编译后不过是一个全局对象 Singleton,其成员通过 export 挂载到该对象上,因此:

  • 无需 getInstance() 样板,Singleton.someMethod() 直接可达;
  • 初始化代码直接在 namespace 体内按需执行(模块加载即完成,属于急切初始化);
  • 命名空间支持嵌套,可做 Utility.Messaging 式的层级组织(见 docs/project/namespaces.md)。

从声明空间的角度看(docs/project/declarationspaces.md),namespace 同时向变量声明空间提供运行时对象、向类型声明空间提供类型合并能力,这是它能同时挂方法和类型的原因。

不过要清醒地认识到:namespace 的"唯一性"是靠整个项目只出现一次该命名空间来保证的,它本质上仍是全局对象。正因如此,原文档紧接着给出了一条重要的实践警告。

三、现代推荐:用文件模块取代单例与 namespace

对大部分使用者来说,namespace 可以用模块来替代。

这是原文档的核心结论。基于文件模块(ES Module)的写法:

// someFile.ts
// ... any one time initialization goes here ...
export function someMethod() {}

// Usage
import { someMethod } from './someFile';

文件模块即"根级别含有 import 或 export 的文件"。仓库 docs/project/modules.md 详细解释了模块化的价值:

  1. 局部作用域,杜绝全局污染:模块内声明不会泄漏到全局命名空间,与其他文件天然隔离;
  2. 显式依赖:必须通过 import { someMethod } from './someFile' 声明依赖,而非隐式依赖某个全局单例;
  3. 按需加载与 tree-shaking 友好:只有真正被导入的成员才会进入最终产物,配合 module: commonjs 或现代打包器可显著优化体积。

把三种方案的取舍对齐对比:

方案 初始化时机 全局副作用 样板代码 推荐度
class 静态单例 懒初始化 全局变量 + 类约束 多(私有构造、静态属性、getInstance) 特定场景
namespace 急切初始化 全局对象 少 快速演示 / 移植旧代码
文件模块 模块加载时 无(局部作用域) 最少 现代项目首选

仓库 docs/project/modules.md 还给出模块化实践的关键提示:使用 module: commonjs 选项配合 ES 模块语法编写导入导出;相对导入路径必须以 . 开头(./someFile),非相对路径则按 Node 模块解析策略向上逐级查找 node_modules。这保证 ./someFile 这样的相对导入在编译期和运行时都能被正确解析。

四、单例只是"全局"的别称:何时该用,何时该避

原文档给出了一个非常犀利的警示,值得全文加粗理解:

单例只是全局(global)的一个别称。

这句话道出了单例模式的本质代价:无论用 class、namespace 还是模块级 export,单例在运行时都对应一份全局可访问的状态。全局状态意味着:

  • 隐式耦合:任何代码都能读写这份状态,模块间依赖关系不再显式可见;
  • 测试困难:状态在测试用例间残留,难以隔离;
  • 并发与重入风险:多实例场景(如 SSR、多租户、Worker)下"唯一性"假设会被打破。

因此,社区普遍认同的实践边界是:

  • 适合用单例/模块级状态:配置中心、日志器、事件总线、数据库连接池等天然全局唯一的基础设施;
  • 避免用单例:业务状态、可复用但非唯一的服务(应改为依赖注入或显式传参)。

在《深入理解 TypeScript》中,模块化是更普遍推荐的路径。仓库 docs/tips/classAreUseful.md 展示了一个贴近真实的"模块级单例"形态——用类组织逻辑、把类的实例作为模块导出:

class Foo {
  public someProperty;

  constructor() {
    // 一些初始化内容
  }

  public someMethod() {
    // ..code
  }

  public someUtility() {
    // .. code
  }
}

export = new Foo();

export = new Foo() 正是"模块即单例"的优雅结合:类负责组织成员与初始化,模块系统保证全局唯一(CommonJS 的 require 缓存),且不产生任何全局变量。这与 docs/tips/statefulFunctions.md 中用 new class { ... }() 保持函数调用间状态的思路一脉相承——类实例被当作"状态容器"使用,而模块导出确保该容器全局唯一。

五、实战选型建议

综合原文档与仓库各章节,给出落地建议:

  1. 新项目一律优先文件模块:把"全局唯一"的职责交给模块系统(单文件内 export),而不是手写 class 单例。它天然解决命名冲突、依赖显式化与测试隔离问题。
  2. 仅当需要"类"的形态时用 export = new Foo():如工具类、状态容器需要方法分组、生命周期初始化时(见 docs/tips/classAreUseful.md)。
  3. namespace 用于快速演示与旧代码移植:仓库 docs/project/namespaces.md 明确指出,namespace 适合"快速演示和移植旧的 JavaScript 代码";正式大型项目仍推荐外部模块。
  4. 不要迷信单例:记住"单例只是全局的别称"。每次引入单例前,先问自己:这份状态真的需要进程内唯一吗?能否通过显式传参或依赖注入替代?能否用模块局部变量在调用处隔离?

结语

从 private constructor 的 class 单例,到 namespace 的逻辑分组,再到文件模块的 export——三种方案在《深入理解 TypeScript》中文版中构成了一条清晰的演进线:从"手写全局约束"走向"语言/模块系统天然保证"。理解它们的编译产物与作用域差异,是写出可维护 TypeScript 代码的关键一步。相关章节可继续深入阅读:docs/project/modules.md(模块解析与 ES 模块语法)、docs/project/namespaces.md(namespace 编译原理)、docs/project/declarationspaces.md(类型/变量声明空间)、docs/tips/classAreUseful.md(类组织代码的实践)。

登录后查看全文
typescript-book-chinese