文件命名指南

Python项目

核心原则：小写与下划线

• 文件名应使用小写字母。

• 单词之间使用下划线 _ 分隔。

• 避免使用空格或连字符 -。

• 跨平台兼容性：Windows 系统不区分大小写，但 Linux 和 macOS 区分。使用全小写可以避免因大小写问题导致的导入错误。

  示例：

  ✅ 好的: my_module.py, data_processor.py, utils.py

  ❌ 不好的: MyModule.py, Data-Processor.py, myModule.py

项目目录命名

项目根目录的命名同样遵循小写和下划线的规则，通常与项目名保持一致。

示例：

• awesome_project/

• django_tutorial/

• my_package/

特殊文件命名

有一些文件具有特定作用和固定名称：

• 模块和包

  • __init__.py: 将一个目录标记为 Python 包（Package）。可以是空文件，也可以包含包的初始化代码。这是必须的。

  • __main__.py: 当一个包被直接使用 python -m package_name 运行时，这个文件会被作为入口点。

• 测试文件

  测试文件通常放在一个名为 tests/ 的目录下。

  测试文件本身应以 test_ 开头，后面跟上要测试的模块名。

  测试类和方法在测试文件中也应以 test_ 开头。

示例：

• 项目结构：

  my_project/
  │
  ├── my_package/
  │   ├── __init__.py
  │   └── core.py
  │
  └── tests/
      ├── __init__.py
      └── test_core.py  # 测试 core.py 的文件

• 在test_core.py中

  def test_add_function():
      assert True
  
  class TestCore:
      def test_something_important(self):
          assert True

• 配置文件

  • 常见的配置文件使用全大写，扩展名为 .ini, .cfg, .toml 或 .env。

  • setup.cfg, pyproject.toml (现代项目首选), requirements.txt, .env

• 其他重要文件（通常全大写）

  这些是项目根目录下的文档文件，使用大写和 .md 扩展名是社区标准。

  • README.md: 项目说明文档。

  • LICENSE: 项目许可证。

  • requirements.txt: 项目依赖列表（虽然全小写也很常见 requirements.txt）。

  • pyproject.toml: 现代Python项目的构建系统配置文件（PEP 518）。

脚本可执行文件

如果你有一个希望用户可以直接从命令行运行的 Python 文件（脚本），建议遵循以下方式：

1. 命名不包含扩展名：像系统命令一样命名（例如 django-admin, pytest）。

2. 在文件顶部添加 Shebang：

   #!/usr/bin/env python3

3. 设置文件为可执行权限（在 Linux/macOS 上）：chmod +x your_script

4. 在 setup.py 或 pyproject.toml中将其声明为入口点（entry point）。这是最推荐、最专业的方式，因为它会由包管理工具自动安装到系统的 PATH 中。

   示例 (pyproject.toml)：

   [project.scripts]
   my-cli-command = "my_package.cli:main"

   这样用户安装你的包后，就可以直接在终端输入 my-cli-command 来运行 my_package/cli.py 文件中的 main() 函数。

应避免的命名

• 不要使用 Python 标准库或知名第三方库的名称：例如，不要将你的文件命名为 sys.py, json.py, requests.py，这会引发难以调试的导入错误。

• 不要使用保留字：例如 class.py, import.py, for.py。

• 慎用连字符 -：在 Python 导入系统中，连字符不是有效的标识符，import my-module 会导致语法错误。

Vue项目

JavaScript / TypeScript 文件命名

1. 工具函数、工具类、辅助文件

   规则： camelCase (小驼峰命名法)。

   ✅ 正确示例：

   formatDate.ts -> 导出一个 formatDate 函数。

   httpClient.ts -> 导出一个 HttpClient 类。

   domUtils.ts -> 导出一个包含多个 DOM 工具函数的对象。

   导入方式：import { formatDate } from '@/utils/formatDate'

2. 配置文件

   规则： kebab-case 或 全小写。

   配置文件通常不是被 import 的，而是被构建工具、框架读取的，因此命名更偏向于“命令式”。

   ✅ 正确示例：

   vue.config.js (Vue CLI)

   vite.config.ts (Vite)

   nuxt.config.ts (Nuxt.js)

   jest.config.js (Jest)

   .eslintrc.js (ESLint，以点开头)

   tsconfig.json (TypeScript，全小写)

3. 组合式函数 (Composables) 文件

   规则： camelCase，并以 use 前缀开头。

   这是 Vue 3 Composition API 的约定俗成的规范，用于标识这是一个可复用的组合式函数。

   ✅ 正确示例：

   useUserStore.ts

   useMouseTracker.ts

   useApi.ts

   导入方式：import { useUserStore } from '@/composables/useUserStore'

4. Store (Pinia) 文件

   规则： camelCase。

   Pinia 是 Vue 官方推荐的状态管理库。其 Store 定义文件通常以功能命名。

   ✅ 正确示例：

   userStore.ts -> 定义 useUserStore

   cartStore.ts -> 定义 useCartStore

   productStore.ts

   导入方式：import { useUserStore } from '@/stores/userStore'

5. API 服务文件

   规则： camelCase 或 kebab-case，并以 api 或 service 作为后缀/前缀。

   ✅ 正确示例：

   userApi.ts 或 userAPI.ts

   authService.ts

   product-api.js

样式 (CSS/SCSS/Less) 文件命名

1. 全局主样式文件

   规则： 全小写，通用名称。

   ✅ 正确示例：

   main.css

   global.scss

   app.css

2. 全局样式部分文件 (Partials)

   规则： kebab-case，并以下划线 _ 开头。

   以下划线开头的文件被称为“部分文件”，它们不会被直接编译为 CSS，而是被导入到主样式文件中。这是一种通用规范。

   ✅ 正确示例：

   _variables.scss (存放 CSS 变量或 SCSS 变量)

   _mixins.scss (存放混合宏)

   _reset.scss (存放重置样式)

   _fonts.scss (存放字体声明)

   导入方式 (在 main.scss 中)：@import './variables' (注意省略 _ 和扩展名)

3. 组件级样式文件

   规则： 通常与组件名保持一致，使用 PascalCase 或 kebab-case。

   如果与组件在同一目录：

   components/
       AppHeader/
           AppHeader.vue
           AppHeader.scss // 或 app-header.scss

   使用 CSS Modules 时，常加上 .module 后缀：

   AppHeader.module.scss

目录索引文件 (Barrel File)

规则： 固定命名为 index.ts 或 index.js。

这种文件用于统一导出某个目录下的所有模块，简化导入路径。

✅ 示例：

components/base/index.ts

// index.ts 内容
export { default as BaseButton } from './BaseButton.vue';
export { default as BaseModal } from './BaseModal.vue';
export { default as BaseIcon } from './BaseIcon.vue';

导入方式：import { BaseButton, BaseModal } from '@/components/base' (无需写到最后一级)

类型定义文件 (.d.ts)

规则： kebab-case 或 camelCase。

• 全局类型定义：通常放在 src/types 目录下。

  global.d.ts (全小写，通用名称)

• 模块特定类型：

  user.types.ts

  api-types.d.ts

  product.dto.ts (常用于定义接口数据传输对象)

测试文件命名

规则： 通常与被测试文件名保持一致，并加上 .spec 或 .test 后缀。

✅ 正确示例：

• 组件测试：AppHeader.spec.ts

• 工具函数测试：formatDate.spec.ts

• 组合式函数测试：useUserStore.spec.ts

存放位置：通常与源文件放在一起，或统一放在项目根目录的 tests/unit 或 __tests__ 目录中。

最终建议

对于 JS/TS 业务逻辑文件，统一采用 camelCase 是最安全、最现代的选择。对于配置和样式文件，遵循其生态的通用规范（如 kebab-case）。最关键的是，在项目开始前与团队达成共识，并将规范写入项目的 README 或贡献指南中。

React项目

工具类/工具函数 (Utils / Helpers)

这类文件通常包含可复用的纯函数。

• 命名规范：camelCase（小驼峰）

• 最佳实践：

  • 使用描述其功能的动词或形容词开头（如：format, calculate, validate, get, is, has）。

  • 如果工具函数非常多，可以考虑按功能模块分目录，并使用 index.js 统一导出。

• ✅ 正确示例：

  formatDate.js

  calculateDiscount.js

  validateEmail.js

  apiHelpers.js (包含多个API相关 helper 函数的文件)

  constants.js (存放全局常量)

自定义 Hooks

自定义 Hook 让你可以不编写组件而复用状态逻辑。

• 命名规范：camelCase，并且必须以 use 开头。

• 最佳实践：

  名字应明确表示 Hook 的用途，通常是一个动作(如 useLocalStorage) 或返回的值（如 useUser）。

• ✅ 正确示例：

  useLocalStorage.js

  useFetch.js

  useDebounce.js

  useAuth.js

上下文 (Context)

Context 用于跨组件层级的全局状态管理。

• 命名规范：PascalCase（大驼峰/帕斯卡命名法）

• 最佳实践：

  • 文件名应清晰描述 Context 所管理的数据域。

  • 通常一个 Context 会包含 Provider 和自定义 Hook（如 useTheme），因此文件名应与功能域匹配。

• 示例：

  AppContext.js

  ThemeContext.js

  UserContext.js

  ShoppingCartContext.js

API & 服务 (API Services)

用于组织所有对外部 API 的调用。

命名规范：camelCase 或 kebab-case（短横线连接）。项目内统一即可，camelCase 更常见。

• 最佳实践：

• 可以按资源（resource）或模块划分文件。

• 使用动词表示操作（如 get, post, update, delete）。

• 通常会将 API 基础配置（如 baseURL、拦截器）放在一个单独文件里（如 apiClient.js 或 axiosInstance.js）。

• ✅ 正确示例：

  productApi.js 或 product-api.js (包含 getProducts, createProduct 等方法)

  userService.js 或 user-service.js

  authApi.js

  apiClient.js (创建的 axios 实例)

路由配置 (Routing Configuration)

使用 React Router 等库时的路由定义文件。

• 命名规范：camelCase 或 PascalCase。

• 最佳实践：

  • 名字应明确表示这是路由配置。

  • 如果路由复杂，可以拆分成多个文件按模块管理。

• ✅ 正确示例：

  routes.js

  AppRoutes.js

  adminRoutes.js / publicRoutes.js (拆分路由)

样式文件 (Stylesheets)

CSS、Sass、CSS Modules、Styled-Components 等样式文件。

• 命名规范：取决于使用的技术，但通常使用 kebab-case。

• 最佳实践：

• CSS Modules: 通常与对应的组件同名，但使用小写短横线，如 my-component.module.css。

• 全局样式：如 global.css, reset.css。

• Styled-Components: 通常直接写在组件文件内，或使用 PascalCase 作为文件名，如 Button.styles.js。

按功能或组件分类样式文件。

• ✅ 正确示例：

  global.scss

  variables.scss (Sass 变量)

  mixins.scss (Sass 混合宏)

  header.module.css (CSS Module)

  HomePage.styles.js (Styled-Components 样式文件)

资产文件 (Assets: Images, Fonts, Icons)

图片、字体、图标等静态资源。

• 命名规范：kebab-case（强烈推荐）

• 最佳实践：

  • 使用描述性名字，说明图像内容或用途。

  • 可以在名字中包含尺寸或分辨率（如 banner-@2x.png），但通常构建工具会处理。

  • 按类型分目录存放，如 images/, icons/, fonts/。

• ✅ 正确示例：

  company-logo.svg

  user-avatar-placeholder.png

  hero-background.jpg

  icon-checkmark.svg

配置文件 (Configuration Files)

如项目构建、包管理、代码格式化等配置。

• 命名规范：全小写，扩展名决定格式。

• 最佳实践：

  使用工具默认接受的标准文件名。

• ✅ 正确示例：

  .eslintrc.js (ESLint)

  .prettierrc (Prettier)

  jsconfig.json / tsconfig.json (TypeScript)

  package.json

  webpack.config.js

  .env, .env.development, .env.production (环境变量)

测试文件 (Test Files)

测试工具类、自定义 Hooks、组件等的文件。

• 命名规范：与源文件同名，但添加 .test 或 .spec 后缀。

• 最佳实践：

  • 将测试文件放在与源文件同目录下，或统一放在 tests 目录中。两种方式都可，项目内统一即可。

  • 推荐使用 **.test.js 模式。

• ✅ 正确示例：

  源文件：utils/formatDate.js

  测试文件：utils/formatDate.test.js 或 utils/__tests__/formatDate.test.js

  源文件：hooks/useFetch.js

  测试文件：hooks/useFetch.test.js