文件命名指南
约 2470 字大约 8 分钟
2025-10-03
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 文件(脚本),建议遵循以下方式:
命名不包含扩展名:像系统命令一样命名(例如 django-admin, pytest)。
在文件顶部添加 Shebang:
#!/usr/bin/env python3设置文件为可执行权限(在 Linux/macOS 上):chmod +x your_script
在
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 文件命名
工具函数、工具类、辅助文件
规则: camelCase (小驼峰命名法)。
✅ 正确示例:
formatDate.ts-> 导出一个 formatDate 函数。httpClient.ts-> 导出一个 HttpClient 类。domUtils.ts-> 导出一个包含多个 DOM 工具函数的对象。导入方式:
import { formatDate } from '@/utils/formatDate'配置文件
规则: 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,全小写)组合式函数 (Composables) 文件
规则: camelCase,并以 use 前缀开头。
这是 Vue 3 Composition API 的约定俗成的规范,用于标识这是一个可复用的组合式函数。
✅ 正确示例:
useUserStore.tsuseMouseTracker.tsuseApi.ts导入方式:
import { useUserStore } from '@/composables/useUserStore'Store (Pinia) 文件
规则: camelCase。
Pinia是 Vue 官方推荐的状态管理库。其 Store 定义文件通常以功能命名。✅ 正确示例:
userStore.ts-> 定义 useUserStorecartStore.ts-> 定义 useCartStoreproductStore.ts导入方式:
import { useUserStore } from '@/stores/userStore'API 服务文件
规则: camelCase 或 kebab-case,并以 api 或 service 作为后缀/前缀。
✅ 正确示例:
userApi.ts或userAPI.tsauthService.tsproduct-api.js
样式 (CSS/SCSS/Less) 文件命名
全局主样式文件
规则: 全小写,通用名称。
✅ 正确示例:
main.cssglobal.scssapp.css全局样式部分文件 (Partials)
规则: kebab-case,并以下划线 _ 开头。
以下划线开头的文件被称为“部分文件”,它们不会被直接编译为 CSS,而是被导入到主样式文件中。这是一种通用规范。
✅ 正确示例:
_variables.scss(存放 CSS 变量或 SCSS 变量)_mixins.scss(存放混合宏)_reset.scss(存放重置样式)_fonts.scss(存放字体声明)导入方式 (在
main.scss中):@import './variables'(注意省略_和扩展名)组件级样式文件
规则: 通常与组件名保持一致,使用 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.tsapi-types.d.tsproduct.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.jscalculateDiscount.jsvalidateEmail.jsapiHelpers.js(包含多个API相关helper函数的文件)constants.js(存放全局常量)
自定义 Hooks
自定义 Hook 让你可以不编写组件而复用状态逻辑。
命名规范:camelCase,并且必须以
use开头。最佳实践:
名字应明确表示 Hook 的用途,通常是一个动作(如
useLocalStorage) 或返回的值(如useUser)。✅ 正确示例:
useLocalStorage.jsuseFetch.jsuseDebounce.jsuseAuth.js
上下文 (Context)
Context 用于跨组件层级的全局状态管理。
命名规范:PascalCase(大驼峰/帕斯卡命名法)
最佳实践:
文件名应清晰描述 Context 所管理的数据域。
通常一个 Context 会包含 Provider 和自定义 Hook(如 useTheme),因此文件名应与功能域匹配。
示例:
AppContext.jsThemeContext.jsUserContext.jsShoppingCartContext.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.jsauthApi.jsapiClient.js(创建的 axios 实例)
路由配置 (Routing Configuration)
使用 React Router 等库时的路由定义文件。
命名规范:camelCase 或 PascalCase。
最佳实践:
名字应明确表示这是路由配置。
如果路由复杂,可以拆分成多个文件按模块管理。
✅ 正确示例:
routes.jsAppRoutes.jsadminRoutes.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.scssvariables.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.svguser-avatar-placeholder.pnghero-background.jpgicon-checkmark.svg
配置文件 (Configuration Files)
如项目构建、包管理、代码格式化等配置。
命名规范:全小写,扩展名决定格式。
最佳实践:
使用工具默认接受的标准文件名。
✅ 正确示例:
.eslintrc.js(ESLint).prettierrc(Prettier)jsconfig.json/tsconfig.json(TypeScript)package.jsonwebpack.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
