前端开发命名规范

1. 前言

本文档旨在为公司前端开发团队提供一套统一、清晰的代码命名规范。

遵循统一的命名规范是保障代码可读性与可维护性的基础，是提升团队协作效率的关键。不一致的命名会显著增加项目的维护成本和新成员的理解成本。本文档将详细阐述各项命名约定，所有前端项目均应严格遵守。

2. 命名法释义

为确保理解一致，首先对文档中使用的各种命名法进行定义。

命名法	风格	示例	主要应用场景
驼峰命名法 (camelCase)	首字母小写，后续单词首字母大写	let myVariableName;	变量、函数
帕斯卡命名法 (PascalCase)	所有单词首字母均大写	class MyComponent {}	类、组件、类型、接口
连字符命名法 (kebab-case)	全部小写，单词间用连字符连接	my-component.css	文件名、URL、npm 包
下划线命名法 (snake_case)	全部小写，单词间用下划线连接	let my_variable;	数据库字段、其他语言
大写下划线命名法 (UPPER_SNAKE_CASE)	全部大写，单词间用下划线连接	const MAX_COUNT = 10;	常量、环境变量

3. 命名法使用场景速查

为便于快速记忆和查找，此处提供各命名法的使用场景汇总。

命名法	使用场景
kebab-case	目录/文件夹、非组件的JS/TS文件、样式文件
PascalCase	单文件组件 (.vue/.tsx)、类、代码内的React组件、类型 (type)、接口 (interface)、枚举 (enum)
camelCase	变量、函数
UPPER_SNAKE_CASE	全局常量、环境变量

4. 核心原则：一致性

在所有规范中，一致性是最高原则。

在项目开发过程中，必须严格保持命名风格的统一。相比于争论不同命名风格的优劣，在团队和项目范围内遵循一致的规范更为重要。

5. 文件及目录命名规范

文件及目录命名统一采用 kebab-case (连字符命名法)。

选择此规范基于以下考量：

1. URL 及 SEO 友好：在约定式路由的框架（如 Next.js, UmiJS）中，文件名直接映射为 URL。搜索引擎将连字符视为单词分隔符，有利于 SEO。例如，my-awesome-page 会被正确识别。
2. 规避大小写敏感问题：不同操作系统（Windows 大小写不敏感，Linux/macOS 大小写敏感）对文件名的处理方式不同。全部使用小写 kebab-case 可以从根源上杜绝因大小写混用导致的跨平台构建或 Git 管理问题。
3. 视觉清晰度与生态一致性：kebab-case 格式在视觉上更易于分割和阅读长文件名。同时，该风格与 NPM 生态系统中绝大多数包的命名风格保持一致。

6. 命名规范细则

6.1. 文件与目录 (File & Directory)

• 目录/文件夹: 统一使用 kebab-case。

  # ✅ 推荐
  - src
    - components
    - utils
    - api-services
  
  # ❌ 禁止
  - src
    - Components
    - apiServices

• 组件文件:
  • 单文件组件: 统一使用 PascalCase。此为社区通用规范，便于识别组件文件。

    # ✅ 推荐
    MyButton.vue
    UserInfoCard.tsx

  • 目录组件: 对于结构复杂的组件，推荐使用目录形式。目录名使用 kebab-case，核心文件命名为 index。此方法可简化引用路径，并使相关文件（如样式、状态、测试）内聚。

    # ✅ 推荐 (引用路径: '.../user-profile')
    - user-profile
      - index.tsx
      - index.module.css
      - index.store.ts
      - index.test.ts

• 非组件的 .js/.ts 文件: 统一使用 kebab-case。

  # ✅ 推荐
  # 工具函数
  format-date.ts
  # API 服务
  user-api.service.ts
  # TS 类型定义
  common.types.ts
  # React Hooks
  use-request-loading.ts

• 样式文件: 统一使用 kebab-case。

  # ✅ 推荐
  reset.css
  user-profile.module.scss

6.2. 代码内部 (In the Code)

• 变量 (Variables): 统一使用 camelCase。

  // ✅ 推荐
  let userName = 'Alex';
  const isLoading = false;

• 函数 (Functions): 统一使用 camelCase。

  // ✅ 推荐
  function getUserInfo() {
    // ...
  }

• 常量 (Constants): 统一使用 UPPER_SNAKE_CASE。用于表示程序中不应被改变的硬编码值。

  // ✅ 推荐
  const MAX_LOGIN_ATTEMPTS = 5;
  const API_BASE_URL = '[https://api.example.com](https://api.example.com)';

• 类 (Classes) / React组件: 统一使用 PascalCase。

  // ✅ 推荐
  class ApiClient {
    // ...
  }
  
  const UserProfile = () => {
    return <div>...</div>;
  };

• 类型 (Types) / 接口 (Interfaces) / 枚举 (Enums): 统一使用 PascalCase。

  // ✅ 推荐
  interface UserProfile {
    userId: string;
    displayName: string;
  }
  
  type ResponseStatus = 'success' | 'error';
  
  enum OrderStatus {
    Pending,
    Processing,
    Shipped,
  }

7. 命名决策流程图

为便于在开发中快速决策，可参考以下流程图：

8. 总结

本规范旨在通过标准化的命名实践，提升代码质量与开发效率。所有前端开发人员均需理解并严格遵守本文档所列规则。本规范将根据未来的项目实践和技术演进进行适时修订。