Vue+TypeScript 枚举（Enum）的使用规范

在 TypeScript 中，枚举（Enum）的命名应遵循以下规范，这些规范结合了 TypeScript 官方建议和行业最佳实践：

枚举命名规范（TypeScript/Vue 项目）

1. 基本命名规则：

   • 使用 PascalCase（大驼峰式） 命名枚举类型

   • 枚举成员使用 UPPER_SNAKE_CASE（全大写+下划线）

   • 避免使用复数形式（枚举表示一组相关常量，不是集合）

typescript

复制

下载

// ✅ 正确示例
export enum UserStatus {
  ACTIVE = "ACTIVE",
  INACTIVE = "INACTIVE",
  PENDING_VERIFICATION = "PENDING_VERIFICATION"
}

export enum HttpStatusCode {
  OK = 200,
  BAD_REQUEST = 400,
  NOT_FOUND = 404
}

1. 语义化命名原则：

   • 使用名词+状态/类型的组合

   • 包含明确的上下文信息

   • 避免通用名称（如 Status, Type）

typescript

复制

下载

// ✅ 推荐（包含上下文）
export enum OrderPaymentStatus {
  UNPAID = "UNPAID",
  PARTIALLY_PAID = "PARTIALLY_PAID",
  PAID = "PAID",
  REFUNDED = "REFUNDED"
}

// ❌ 避免（过于通用）
export enum Status {
  ACTIVE = 1,
  DISABLED = 0
}

1. 项目中的最佳实践：

   • 统一前缀（可选）：对相关枚举使用相同前缀

   • 文件组织：将枚举放在 /src/enums/ 目录

   • 导出规范：使用命名导出（非默认导出）

typescript

复制

下载

// /src/enums/user.enum.ts
export enum UserRole {
  ADMIN = "ADMIN",
  EDITOR = "EDITOR",
  VIEWER = "VIEWER"
}

export enum UserAccountType {
  STANDARD = "STANDARD",
  PREMIUM = "PREMIUM",
  ENTERPRISE = "ENTERPRISE"
}

1. Vue 组件中的使用规范：

   • 在 

     1. 字符串 vs 数字枚举：

        • 优先使用 字符串枚举（更好的可读性和调试体验）

        • 数字枚举仅用于性能关键场景或位运算

     typescript

     复制

     下载

     // ✅ 字符串枚举（推荐）
     export enum Direction {
       UP = "UP",
       DOWN = "DOWN",
       LEFT = "LEFT",
       RIGHT = "RIGHT"
     }
     
     // ⚠️ 数字枚举（特定场景使用）
     export enum FilePermission {
       READ = 1,       // 0001
       WRITE = 2,      // 0010
       EXECUTE = 4     // 0100
     }

     1. 常量枚举注意事项：

        • 使用 const enum 仅适用于性能敏感场景

        • 会完全移除运行时代码，影响调试

     typescript

     复制

     下载

     // ❌ 常规项目慎用（无法在运行时访问）
     const enum SecretCodes {
       KEY1 = 0xABC,
       KEY2 = 0xDEF
     }
     
     // ✅ 普通枚举更安全
     export enum ApiKeys {
       CLIENT_ID = "AK_123456",
       SECRET = "SK_789012"
     }

     命名禁忌

     1. 避免的行为：

        typescript

        复制

        下载

        // ❌ 混合大小写
        enum badNaming {
          mixedCase = 1  // 避免
        }
        
        // ❌ 单数形式表示集合
        enum Color {
          RED, GREEN, BLUE  // 应命名为 Colors?
        }
        
        // ❌ 动词命名
        enum ProcessData {  // 枚举应是状态描述
          START, STOP       // 而非动作
        }

     2. 不要重复前缀：

        typescript

        复制

        下载

        // ❌ 冗余前缀
        enum UserUserRole {  // User 重复
          USER_ADMIN,
          USER_EDITOR
        }
        
        // ✅ 简洁命名
        enum UserRole {
          ADMIN,
          EDITOR
        }

     项目一致性建议

     1. 在项目中建立 enums 目录集中管理

     2. 添加 ESLint 规则强制枚举命名规范：

        json

        复制

        下载

        // .eslintrc.json
        {
          "rules": {
            "@typescript-eslint/naming-convention": [
              "error",
              {
                "selector": "enum",
                "format": ["PascalCase"],
                "prefix": ["Enum"] // 可选前缀
              },
              {
                "selector": "enumMember",
                "format": ["UPPER_CASE"]
              }
            ]
          }
        }

     遵循这些规范能显著提升代码可读性和维护性，尤其在团队协作的 Vue+TypeScript 项目中。

     在 Vue 3 + TypeScript 项目中，enums 目录的常规结构通常遵循模块化和可维护性原则。以下是典型的组织结构和最佳实践：

     标准目录结构示例

     text

     复制

     下载

     src/
     ├── enums/                   # 枚举根目录
     │   ├── system/              # 系统级枚举
     │   │   ├── http.enum.ts     # HTTP 状态码枚举
     │   │   ├── error-codes.enum.ts
     │   │   └── index.ts         # 统一导出
     │   │
     │   ├── business/            # 业务相关枚举
     │   │   ├── order-status.enum.ts
     │   │   ├── payment-method.enum.ts
     │   │   └── index.ts
     │   │
     │   ├── user/                # 用户相关枚举
     │   │   ├── user-role.enum.ts
     │   │   ├── user-status.enum.ts
     │   │   └── index.ts
     │   │
     │   ├── ui/                  # UI/组件相关枚举
     │   │   ├── button-variant.enum.ts
     │   │   ├── notification-type.enum.ts
     │   │   └── index.ts
     │   │
     │   ├── shared/              # 跨模块通用枚举
     │   │   ├── date-formats.enum.ts
     │   │   ├── country-codes.enum.ts
     │   │   └── index.ts
     │   │
     │   └── index.ts             # 总入口文件（可选）

     关键实践说明

     1. 分类组织

        • 按功能域分组：系统、业务、用户、UI 等

        • 按模块分组：适合大型项目（如 auth/, order/, product/）

        • 通用共享枚举：放在 shared/ 目录

     2. 文件命名规范

        • 使用 *.enum.ts 后缀明确文件类型

        • 短横线命名：order-status.enum.ts

        • 枚举名与文件名一致（PascalCase）：

          typescript

          复制

          下载

          // order-status.enum.ts
          export enum OrderStatus {
            PENDING = "PENDING",
            PROCESSING = "PROCESSING",
            SHIPPED = "SHIPPED"
          }

     3. 索引文件（index.ts）
        每个子目录使用 index.ts 统一导出：

        typescript

        复制

        下载

        // system/index.ts
        export * from './http.enum';
        export * from './error-codes.enum';

     4. 总入口文件（可选）

        typescript

        复制

        下载

        // enums/index.ts
        export * as SystemEnums from './system';
        export * as BusinessEnums from './business';
        export * as UserEnums from './user';

     使用场景示例

     组件中使用

     vue

     复制

     下载

     统一导入方式

     typescript

     复制

     下载

     // 通过总入口导入（适合频繁使用的枚举）
     import { SystemEnums, UserEnums } from '@/enums';
     
     console.log(SystemEnums.HttpStatus.OK); // 200
     console.log(UserEnums.UserRole.ADMIN);  // "ADMIN"

     高级组织结构

     方案 1：按业务模块划分（推荐）

     text

     复制

     下载

     enums/
     ├── order/
     │   ├── status.enum.ts
     │   ├── payment-type.enum.ts
     │   └── index.ts
     ├── product/
     │   ├── category.enum.ts
     │   ├── availability.enum.ts
     │   └── index.ts
     └── auth/
         ├── permission.enum.ts
         └── index.ts

     方案 2：按枚举类型划分

     text

     复制

     下载

     enums/
     ├── numeric/
     │   ├── http-status.enum.ts
     │   └── error-codes.enum.ts
     ├── string/
     │   ├── user-roles.enum.ts
     │   └── order-status.enum.ts
     └── const/
         ├── ui-variants.enum.ts
         └── icon-types.enum.ts

     最佳实践建议

     1. 单一职责原则

        • 每个文件只包含 1 个主要枚举（相关辅助枚举可共存）

        • 避免创建包含多个无关枚举的 "global.enum.ts"

     2. 树摇优化

        typescript

        复制

        下载

        // 避免默认导出（影响 tree-shaking）
        // ❌ 不推荐
        export default enum Status { ... }
        
        // ✅ 推荐使用命名导出
        export enum OrderStatus { ... }

     3. 常量枚举处理
        对于 const enum，创建单独目录或添加注释：

        typescript

        复制

        下载

        // system/const-enums/
        // 或添加特殊后缀
        export const enum CacheKeys {
          USER_PROFILE = "user_profile",
          APP_CONFIG = "app_config"
        }

     4. 自动生成枚举
        如果使用 OpenAPI 等工具生成：

        text

        复制

        下载

        enums/
        ├── generated/  # 自动生成的枚举
        │   ├── api-models.enum.ts
        │   └── ...
        └── manual/     # 手动维护的枚举
            ├── ui.enum.ts
            └── ...

     典型文件示例

     用户角色枚举 (enums/user/user-role.enum.ts)

     typescript

     复制

     下载

     export enum UserRole {
       /** 系统管理员 */
       ADMIN = "ADMIN",
       
       /** 内容编辑者 */
       EDITOR = "EDITOR",
       
       /** 普通查看用户 */
       VIEWER = "VIEWER",
       
       /** 访客（未登录用户） */
       GUEST = "GUEST"
     }
     
     // 类型导出（方便同时作为类型使用）
     export type UserRoleType = `${UserRole}`;

     HTTP 状态枚举 (enums/system/http.enum.ts)

     typescript

     复制

     下载

     export enum HttpStatus {
       OK = 200,
       CREATED = 201,
       BAD_REQUEST = 400,
       UNAUTHORIZED = 401,
       FORBIDDEN = 403,
       NOT_FOUND = 404,
       INTERNAL_SERVER_ERROR = 500
     }
     
     // 状态码描述映射
     export const HttpStatusMessage: Record = {
       [HttpStatus.OK]: "请求成功",
       [HttpStatus.CREATED]: "资源创建成功",
       // ...其他描述
     };

     目录结构选择建议

     项目规模	推荐结构	特点
     小型项目	平铺结构 (enums/*.enum.ts)	简单直接，无需嵌套
     中型项目	功能域分组	平衡查找效率和组织结构
     大型项目	业务模块分组	与功能模块对齐，便于跨团队协作
     对接后端API	混合结构（生成+手动）	分离自动生成和自定义枚举

     这种组织方式确保：

     1. 快速定位枚举定义

     2. 避免命名冲突

     3. 支持按需加载

     4. 保持类型系统完整性

     5. 便于维护和扩展