编码规范相关
更新: 9/17/2025 字数: 0 字 时长: 0 分钟
序言
最近整理了一下自己在团队中实践并落地的编码规范相关内容，主要包含以下几类：
- 命名规范与项目结构规范：如何为变量、函数、文件、目录制定清晰的命名规则
- Git 提交规范：如何通过规范的提交信息提高项目可追溯性
- 代码格式化工具：如何利用 Prettier 等工具自动化统一代码风格
- 工作流相关：如何保证规范能够被正确、稳定且便捷地使用
命名规范与项目结构规范
命名规范是编程规范中最重要的一部分，它直接影响到代码的可读性和可维护性
我们常见的命名形式有：
| 命名形式 | 示例 | 说明 |
|---|---|---|
camelCase | userName | 小驼峰式命名法（首字母小写） |
PascalCase | UserName | 大驼峰式命名法（首字母大写） |
snake_case | user_name | 下划线命名法 |
kebab-case | user-name | 短横线命名法 |
UPPER_CASE | USER_NAME | 大写命名法 |
文件命名规范
- 项目名称使用短横线命名法。🌰
qianxun-notes html / css / md / js / ts / jsx / tsx文件使用短横线命名法React / Vue组件文件使用大写驼峰式命名法。🌰Dialog.vue/Dialog.tsx- 静态资源文件使用短横线命名法。🌰
logo-white.png
JavaScript 命名规范
- 常量使用大写命名法。🌰
const MAX_COUNT = 1996 - 正则常量命名使用后缀
_RE。🌰const PHONE_RE = /^1[3-9]\d{9}$/ - 变量使用小驼峰式命名法。🌰
const maxCount = 1996 class类名使用大驼峰式命名法。🌰class User {}- 构造函数使用大驼峰式命名法。🌰
function User() {} - 函数使用小驼峰式命名法。🌰
function getUserInfo() {} - 对象
key使用小驼峰式命名法。🌰const user = { userName: 'qianxun' } - 路由
path使用短横线命名法。🌰path: '/user-info'
CSS 命名规范
- 类名使用短横线命名法。🌰
.user-info ID使用小驼峰式命名法。🌰#userInfo- 自定义变量使用短横线命名法。🌰
--main-color: #fff
值得注意的是，命名规范也只是规范，也并不是说必须得强制执行，有时也得灵活变动下。比如说大家一般都很鄙视使用拼音命名，认为这种方式很low，但在某些情景下，由其是定义一些专业术语变量，我认为用汉语拼音反而比强行翻译成英文要好。
比如我们在写一个基建类项目，需要定义一个路面机构层厚度相关的变量，翻译成英文叫Pavement structure layer thickness，使用小驼峰命名法pavementStructureLayerThickness，嗯。。。属实有点反人类，写成缩写PSLT也有点抽象，定义成拼音luMianJieGouCengHouDu虽然不好看，但是矮子里面挑将军，对于熟悉项目的人来说，这种命名方式反而更能接受些。
项目结构规范
以下以一个通用的前端项目为例（目录结构可按技术栈微调）：
.
├── .vscode # VSCode 配置文件
├── public # 网站资源文件（favicon.ico index.html 等）
├── scripts # 脚本相关
├── src
│ ├── apis # api 接口
│ ├── assets # 静态资源
│ ├── components # 全局组件
│ ├── config # 项目配置文件
│ ├── constants # 常量
│ ├── hooks # 通用 hooks
│ ├── layout # 页面整体布局
│ ├── lib # 第三方或无业务依赖代码
│ ├── locales # i18n
│ ├── pages # 页面相关文件
│ │ ├── Home # 大驼峰规范 => 组件即是一个构造函数
│ │ │ ├── components # 页面相关的子组件
│ │ │ ├── index.module.scss # 根据应用的 CSS Scope 方案命名
│ │ │ └── index.tsx # index 作为默认路径，视为根节点
│ │ └── App.tsx # 页面入口
│ ├── router # 页面路由
│ ├── store # 状态管理
│ ├── styles # 全局/基础样式
│ ├── types # TypeScript 类型声明
│ ├── utils # 工具函数
│ └── main.tsx # 应用启动入口
├── README.md # 当前项目的文档
├── package.json # 项目信息
└── tsconfig.json # TypeScript 配置文件有两点需要注意：
- 上面规范也只是参考，不同语言的项目结构规范不一样，甚至
vue2与vue3都不太一样，但是核心思想都大差不差 - 项目结构规范由其适用于约定大于规范这句话，如果是维护的老项目，尽量不要随着自己心意更改整个项目结构，不要随便增加或者更改结构文件夹，
否则可能会迎来队友的痛击
Git 相关规范
分支管理规范
主要是对分支的命名与管理做约定。
命名
分支命名建议使用 feature/xxx-xxx 或 fix/xxx-xxx 的格式，单词之间用短横线 - 连接。
分支管理
项目需要根据环境的不同创建对应的分支，通常有下面五种分支：
master- 生产环境分支，只接受来自develop的合并develop- 开发环境分支，所有功能开发的基础分支test- 测试环境分支，用于部署测试版本feature/xxx- 功能分支，用于开发新功能fix/xxx- 修复分支，用于修复bug
Git 相关工作流规范
Git相关工作流规范，网上的版本其实非常多，贴一个我比较常用的 Git Flow 流程图，和主流常用的大同小异：
开发新功能时：当团队成员开发新功能时，需要从 develop 分支上拉一个 feature/功能名称 分支进行开发，例如：feature/login。开发完成后需要合并到 test 分支进行部署测试，如果测试未通过，继续在feature/功能名称上开发，如果测试通过，合并到develop，develop再合并到master
修复 Bug 时：当线上出现bug时，从master分支上拉一个fix/修复功能名称分支进行开发，例如fix/upload。开发完成后也需要合并到 test 分支进行部署测试，测试通过，合并到develop和master
值得一提的是，我这个是简化过后的，适用于我们自己项目的Git Flow。当前各个公司流行的Git Flow很多都是延伸自Vincent Driessen在2010年写的一篇文章A successful Git branching model，网上也有很多文章对此进行了详细的解读，有兴趣的也可以搜索看下。
Git 提交规范
深究的话，提交规范的要求还挺高的，它的大致结构为git commit message要求填写五项内容：
type>(<scope>): <subject>
<body>
<footer>type（必填）：commit的类型scope（选填）：commit的影响范围subject（必填）：commit信息的简短描述（50 字以内）body（选填）：commit信息的具体描述footer（选填）：重大变化（Breaking Change）和需要关闭的Issue
但是就我自己实践并结合我在团队中推行规范的情况来看，大部分人包括我自己其实能写清楚type就不错了。通常我们的项目开发周期非常快，git提交的频率很高，提交一个commit就得写真么多东西在快节奏开发中属实有点不太现实。但是规范下提交的type还是很有必要的，一个合理的type能够帮助我们大致识别出来这个提交是干嘛的。
commit 常用 type：
| type | 含义 |
|---|---|
| feat | 新功能 |
| fix | 修复 bug |
| docs | 文档类改动 |
| style | 代码格式改动，同理适用于业务样式调整 |
| refactor | 重构（即不是新增功能，也不是修复 bug） |
| perf | 性能优化相关 |
| types | TypeScript 类型相关的改动 |
| test | 单元测试、e2e 测试 |
| build | 构建工具或者依赖项的改动 |
| ci | 修改项目持续集成流程 |
| chore | 其他类型的提交 |
| revert | 恢复或还原相关提交 |
| wip | draft | 托管平台对应的草稿标识 |
代码格式化
代码格式化可以保证团队成员有一致的编码风格，最常用的格式化工具应该就属prettier了
下面是一些我自己的prettier规范
/**
* Prettier 配置项
* https://prettier.io/docs/en/options.html
*/
module.exports = {
// 一行最多 100 字符
printWidth: 100,
// 使用 2 个空格缩进
tabWidth: 2,
// 不使用缩进符，而使用空格
useTabs: false,
// 行尾需要有分号
semi: true,
// 使用双引号
singleQuote: false,
// 对象的 key 仅在必要时用引号
quoteProps: "as-needed",
// jsx 不使用单引号，而使用双引号
jsxSingleQuote: false,
// es5有效的地方保留逗号
trailingComma: "es5",
// 大括号内的首尾需要空格
bracketSpacing: true,
// jsx 标签的反尖括号需要换行
jsxBracketSameLine: false,
// 箭头函数，只有一个参数的时候，也需要括号
arrowParens: "always",
// 每个文件格式化的范围是文件的全部内容
rangeStart: 0,
rangeEnd: Infinity,
// 不需要写文件开头的 @prettier
requirePragma: false,
// 不需要自动在文件开头插入 @prettier
insertPragma: false,
// 使用默认的折行标准
proseWrap: "preserve",
// 根据显示样式决定 html 要不要折行
htmlWhitespaceSensitivity: "css",
// 换行符使用 lf
endOfLine: "lf",
};需要提醒的是，对老项目，千万不要手贱对所有文件都格式化了，要不然就会出现所有文件的最新更改记录都是自己这种尴尬情况，~反正我没干过~
代码格式化相关的还有eslint这种静态检查工具，不过我不太喜欢，这里就不展开说了。需要注意的是，如果使用了eslint，需要处理好它与prettier的检测冲突问题，网上这种文章很多，有兴趣可以搜索看下。
工作流相关
规范制定好了，还需要确保“被正确执行”。现实中常见的问题包括：
对于老项目，还需要做其他东西
代码格式化
- 某些人提交
Git的时候就是不按照定义的规范来，比如随意写个commit就提交上去了 - 团队中有人已经设置过了自己的
prettier规范，或者某些人的保存并开启格式化功能并没有开启，设置了prettier可能也不起作用
这时候我们期望有一系列的工具，可以帮助我们解决以下问题：
- 提交
Git的时候检查commit格式，不符合格式的不允许提交 - 提交时对提交文件自动进行
prettier格式化，这样做可以只对提交文件进行格式化
我们可以用以下工具实现我们想要的效果：
- husky：
Git Hooks工具，在提交、推送等时机执行脚本 - commitlint：校验
commit message是否符合规范 - lint-staged：仅对暂存文件运行
ESLint/Prettier
它们的协作流程如下图：
在执行 git commit 时，husky 会触发相应的钩子，进而：
- 调用
commitlint校验提交信息格式 - 调用
lint-staged对暂存文件运行ESLint/Prettier
当两者都通过后，提交才会被允许进入仓库。
以上工具相关的配置可以去网上搜索下，然后根据自己的项目所需进行配置，想懒省事也可以看下我开发的两个小工具： @fe-qianxun/verify-commit 和 @fe-qianxun/prettier
相关链接
💡 提示：编程规范不是限制创造力的枷锁，而是提升代码质量的工具。好的规范应该让开发者专注于业务逻辑的实现，而不是纠结于代码格式的细节。