建议:使用 `const` 对象 + `as const` 替代原生 `enum string` 定义枚举

オープン
#3,076 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
35/100
issue の種類
リファクタリング
明瞭さ
おおむね明確
活発さ
静か
技術スタック
typescript

調査の方向性

The issue recommends replacing string enums throughout the TypeScript project, but does not name specific files, tests, or a bounded module. First locate existing string enum definitions and review their usages to understand the scope and compatibility concerns. Done would mean applying the convention consistently in an agreed scope and verifying affected code still builds and tests pass.

索引モデルが issue の本文から書いたものです。

説明

背景

在 TypeScript 项目中,我们大量使用 enum 来定义一组具名常量。但原生 enum 存在几个问题:

  • 运行时开销:enum 在编译后会生成额外的 JS 代码,数字枚举还会生成「反向映射」(如 Fruit[0] === "Apple"),体积更大。
  • 不利于 tree-shaking:枚举对象作为运行时真实存在的对象,难以被打包工具完全消除。
  • opaque 类型:枚举成员是独立的「不透明」类型,传递时拿到的是 Fruit.Apple 而不是真实的 "apple",在序列化、日志、接口对接时常带来额外转换成本。

推荐写法

// 1. 用 const 对象 + as const 代替 enum
export const Fruit = {
  Apple: "apple",
  Banana: "banana",
  Orange: "orange",
} as const;

// 2. 从值对象反推类型,得到联合类型 "apple" | "banana" | "orange"
export type Fruit = (typeof Fruit)[keyof typeof Fruit];

为什么推荐

1. 零运行时开销、可完全擦除

as const 仅作用于类型层面,编译后只是普通的对象字面量,不会生成反向映射等任何额外代码,对 tree-shaking 友好。

2. 值与类型一致,使用更直观

使用处拿到的是真实字符串 "apple",而非不透明的枚举成员。序列化(JSON)、表单、API 对接时无需任何转换。

3. 命名空间分离但同名,互不冲突

常量 Fruit(值空间)与类型 Fruit(类型空间)同名,但分别处于不同空间,互不冲突,调用处既能 import { Fruit } 取值,也能 : Fruit 标注类型,阅读体验与原生 enum 一致。

4. 组合复用非常自然

通过展开运算符即可合并多个枚举,类型由 (typeof X)[keyof typeof X] 自动推导,新增子枚举时无需手动同步:

export const Item = { ...Fruit, ...Toy } as const;
export type Item = (typeof Item)[keyof typeof Item];

约束与约定

  • 枚举键(Key)使用 PascalCase(如 Apple)。
  • 枚举值(Value)使用 camelCase 字符串(如 "apple");个别场景(如需要数值的 ItemSize)可使用数字值。
  • 始终通过 (typeof X)[keyof typeof X] 从值对象推导类型,避免重复维护一份类型声明。

适用范围

  • 所有 字符串枚举 场景,应一律改用此模式。
  • 需要数值枚举的特殊场景(如位运算、紧凑存储)可保留数字值,但同样使用 const 对象 + as const 而非原生 enum。

迁移建议

  • 新代码直接采用该模式。
  • 旧代码在重构或改动相关模块时,逐步将 enum 替换为 const 对象 + as const,并配合类型推导,无需一次性全量改造。

参考实现

// 1. 用 const 对象 + as const 代替 enum:
//    - as const 把所有值收窄为字面量类型(如 "apple")且只读,
//      同时对象本身不会生成运行时枚举的额外代码(可完全擦除,零运行时开销)。
//    - 相比原生 enum,不会生成反向映射等 JS 代码,更利于 tree-shaking。
export const Fruit = {
  Apple: "apple",
  Banana: "banana",
  Orange: "orange",
} as const;

// 2. 从值对象反推类型:得到联合类型 "apple" | "banana" | "orange"
//    - 名称与上面的常量同名,但分处「值空间」和「类型空间」,互不冲突。
//    - 成员值与类型一致,使用处可直接拿到真实字符串,而不是 opaque 的枚举成员。
export type Fruit = (typeof Fruit)[keyof typeof Fruit];

export const Toy = {
  Football: "football",
  Ball: "ball",
  Car: "car",
} as const;

export type Toy = (typeof Toy)[keyof typeof Toy];

// 3. 组合复用:通过展开运算符直接合并两个枚举,无需重复声明成员。
//    - 值的合并是运行时的纯对象展开;类型的合并由 (typeof Item)[keyof typeof Item]
//      自动推导为 "apple" | "banana" | "orange" | "football" | "ball" | "car"。
//    - 新增/调整子枚举时,Item 会自动同步,避免手动维护导致的遗漏。
export const Item = {
  ...Fruit,
  ...Toy,
} as const;

export type Item = (typeof Item)[keyof typeof Item];
主要言語
TypeScript
スター
5.9k
フォーク
413
平均マージ
16時間 17分
マージ済み PR(30日)
41

環境構築

  • Dockerfile・Docker Compose ファイルなし
  • プルリクエストのテンプレートあり
  • コントリビューションガイドなし

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

galacean/engine のほかの issue

galacean/engine の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。