1. 先搞清楚“Conventional”在技术语境下到底指什么“Conventional”这个词直译是“传统的”、“惯例的”。如果它单独作为一个项目标题出现而没有具体的正文、关键词或摘要那它指向的很可能不是一个具体的工具或软件而是一种约定、规范或模式。在软件开发、工程实践和团队协作中这个词出现的频率非常高。它解决的核心问题是一致性和可预测性。当项目规模变大、参与人员变多时如果没有一套大家共同遵守的“惯例”代码会变得难以阅读、维护和协作。比如一个文件应该放在哪里、变量怎么命名、提交信息怎么写、API接口如何设计这些看似琐碎的问题如果每个人都按自己的想法来很快就会变成一场灾难。所以这篇文章适合所有参与软件开发的工程师、团队负责人甚至是对工程规范感兴趣的产品经理。最关键的价值在于理解并建立一套“约定优于配置”的思维能显著降低团队的沟通成本和项目的长期维护成本。这不是教你用一个具体的工具而是分享一种经过验证的、能提升工程效率的工作方法。下面我会从最常见的几个“Conventional”实践领域入手拆解它们的具体内容、落地步骤和避坑经验。2. 最常见的“Conventional”实践提交信息与提交规范一提到“Conventional”很多开发者第一时间想到的是Conventional Commits。这是一种对 Git 提交信息的格式化约定。它的价值非常直接让每次代码提交的意图一目了然便于生成清晰的变更日志也能被工具自动化处理。2.1 提交信息的结构不止是“fix bug”一个符合 Conventional Commits 规范的提交信息结构如下type[optional scope]: description [optional body] [optional footer(s)]type(类型) 说明这次提交的性质。这是核心。feat: 新功能fix: 修复 bugdocs: 仅文档更改style: 不影响代码含义的更改空格、格式化等refactor: 既不是修复 bug 也不是添加功能的代码重构perf: 性能优化test: 添加或修改测试chore: 构建过程或辅助工具的变动[optional scope](可选范围) 说明影响范围可以是模块、文件名或功能点如(auth)、(router)。description(描述) 简短的、命令式的描述说明这次提交做了什么。body和footer 可选的详细说明和关联信息如关闭的 issue 编号。示例对比不好的提交update login logic好的提交feat(auth): add remember-me functionality to login后者一眼就能看出是“认证模块新增了‘记住我’功能”。2.2 如何落地从个人习惯到团队规范我建议分三步走不要一上来就要求全团队立刻改变。第一步个人先试用工具自动化。最直接的方式是使用commitizen这个工具。它是一个交互式的命令行工具引导你一步步填写符合规范的提交信息。安装和基本使用# 全局安装 commitizen 和适配器 npm install -g commitizen cz-conventional-changelog # 在项目根目录初始化 commitizen init cz-conventional-changelog --save-dev --save-exact之后你就可以用git cz代替git commit命令它会通过一系列问答帮你生成规范的提交信息。这一步能让你自己先熟悉格式感受其好处。第二步配置提交验证Husky commitlint。个人习惯养成后需要在团队协作中保证一致性。这时需要“卡口”工具。Husky可以让你在 Git 钩子如commit-msg中运行脚本commitlint则用来校验提交信息格式。配置示例安装依赖npm install --save-dev commitlint/cli commitlint/config-conventional husky初始化 Huskynpx husky init添加 commit-msg 钩子npx husky add .husky/commit-msg npx --no -- commitlint --edit ${1}创建commitlint.config.js文件module.exports { extends: [commitlint/config-conventional] };配置完成后如果提交信息不符合规范提交操作会被自动拒绝。这是保证规范落地的关键。第三步集成到 CI/CD 和生成 Changelog。规范提交的真正威力在于自动化。你可以配置 CI 流水线在代码合并前再次校验提交历史。更重要的是可以使用standard-version或semantic-release这类工具根据feat和fix类型的提交自动生成语义化版本号遵循 SemVer和可读的变更日志。2.3 避坑点别让规范成为负担不要过度设计 scope初期可以不用 scope或者只定义几个宽泛的模块。范围划分太细会增加心智负担。描述要简洁有力使用命令式、现在时态如“add”而不是“added”或“adds”。描述“做了什么”而不是“为什么做”为什么可以写在 body 里。处理“琐事提交”对于chore类型的提交如更新依赖如果非常频繁可以考虑定期批量提交避免污染提交历史。工具链统一确保团队所有成员的 Node.js、npm 等基础环境版本接近避免因环境差异导致 Husky 钩子执行失败。3. 代码风格与目录结构的约定让项目自己会说话提交规范管的是“历史”而代码风格和目录结构管的是“当下”。一个符合“Conventional”思维的项目新成员应该能通过浏览目录和阅读关键文件快速理解项目架构和编码风格。3.1 代码风格自动化ESLint Prettier争论空格、分号、引号是毫无意义的。解决方案是使用工具并形成团队约定。ESLint 负责代码质量捕捉潜在错误并强制执行编码规则如变量未使用、使用等。Prettier 负责代码格式专注于缩进、换行、引号等风格问题确保输出格式一致。落地步骤安装与配置在项目中安装eslint、prettier以及解决二者冲突的eslint-config-prettier。选择或创建规则集可以直接使用社区流行配置如eslint-config-airbnb、eslint-config-standard。更建议团队基于一个基础配置进行小幅调整形成自己的.eslintrc.js和.prettierrc文件。集成到编辑器在 VS Code 等编辑器中安装 ESLint 和 Prettier 插件并开启“保存时自动格式化”。这是提升体验的关键让规范在无形中生效。集成到 Git 流程同样使用 Husky在pre-commit钩子中运行 ESLint 检查和 Prettier 格式化确保提交到仓库的代码都是规范的。# 示例 pre-commit 钩子脚本 npx lint-staged在package.json中配置lint-staged{ lint-staged: { *.{js,jsx,ts,tsx}: [eslint --fix, prettier --write] } }3.2 目录结构约定可预测性高于创造性目录结构没有绝对标准但好的结构是“可预测”的。新人进入项目应该能猜到components、utils、api、stores这些文件夹里放的是什么。一个常见的 React/Vue 项目结构约定src/ ├── assets/ # 静态资源图片、字体等 ├── components/ # 通用组件 │ ├── common/ # 全局通用组件Button, Modal │ └── features/ # 业务特性组件 ├── views/ (或 pages/) # 页面级组件 ├── stores/ (或 state/) # 状态管理如 Pinia, Redux ├── utils/ # 工具函数 ├── hooks/ (或 composables/) # 自定义 Hooks ├── api/ # 所有 API 请求封装 ├── router/ # 路由配置 ├── styles/ # 全局样式 └── main.js # 应用入口关键原则按功能/特性组织优于按文件类型组织。例如将UserProfile.vue、UserProfile.module.css、useUserProfile.js放在一起的“特性文件夹”模式比把所有.vue文件放一个目录更好。保持扁平避免过深嵌套目录层级过深会降低文件查找效率。有清晰的“入口”文件如index.js用于导出模块避免在其他文件中引用深层路径。3.3 边界与经验规则不是越多越好ESLint 规则初始可以宽松一些重点抓那些会导致 bug 的规则如no-unused-vars。过于严格的风格规则如代码行数限制可能会在初期引起反感。允许合理的例外通过/* eslint-disable */注释来临时禁用某行或某文件的规则但需要在代码评审中说明理由。文档化你的约定在项目README或专门的CONTRIBUTING.md文件中用最简单的话说明你们的目录结构和命名习惯。这比口头传递有效得多。4. API 设计与命名的约定前后端协作的润滑剂“Conventional”思维同样适用于前后端接口。一套约定俗成的 API 设计规范能让前端开发者无需频繁查阅文档就能猜到接口地址和返回格式。4.1 RESTful API 约定虽然 GraphQL 等新技术兴起但 RESTful 因其简单性仍是主流约定。其核心是使用 HTTP 方法和资源名词来表达操作。资源命名使用复数名词/users而不是/user。HTTP 方法对应 CRUDGET /users 获取用户列表GET /users/{id} 获取单个用户POST /users 创建用户PUT /users/{id} 全量更新用户PATCH /users/{id} 部分更新用户DELETE /users/{id} 删除用户状态码传达结果200成功、201创建成功、400客户端错误、401未认证、403无权限、404资源不存在、500服务器错误。响应体格式统一即使是错误也返回结构化的 JSON。{ code: 40001, message: 用户名已存在, data: null }{ code: 0, message: success, data: { id: 123, name: John } }4.2 超越基础查询、分页与状态过滤实际项目中的 API 会更复杂需要额外的约定。复杂查询使用查询参数如GET /users?roleadminstatusactive。分页约定通用的参数名如page页码、limit每页条数。响应中应包含分页元数据。{ code: 0, message: success, data: [...], pagination: { page: 1, limit: 20, total: 150 } }关联数据使用expand或include参数控制是否返回关联资源如GET /users/123?expandposts。API 版本管理在 URL 路径/api/v1/users或请求头中体现版本为后续不兼容升级留出空间。4.3 前端请求层的约定后端提供了规范的 API前端也需要相应的约定来消费。请求封装使用 Axios 等库统一配置 baseURL、超时时间、请求/响应拦截器。在拦截器中统一处理错误如弹窗提示 401 跳转登录页。API 模块化在src/api/目录下按资源模块组织文件。// src/api/user.js import request from /utils/request; // 封装好的axios实例 export function getUserList(params) { return request.get(/users, { params }); } export function createUser(data) { return request.post(/users, data); }状态码与错误处理映射在前端拦截器中根据后端返回的code或 HTTP 状态码映射到具体的用户提示或业务逻辑。经验之谈前后端在项目启动初期就应该用文档如 Swagger/OpenAPI或简单的 Markdown 定义好这些约定。即使后期有变动也有迹可循。避免在聊天工具里零散地沟通接口字段那是最容易出错的方式。5. 从约定到文化在团队中推广与维护建立“Conventional”最难的不是技术而是让人接受并习惯。它本质上是一种团队文化的建设。5.1 推广策略自上而下与自下而上结合技术负责人带头Leader 首先要在自己的代码和提交中严格遵守规范并在代码评审中将其作为重要评审点。提供便捷的工具正如前文所述用git cz、Husky、编辑器自动格式化来降低遵守规范的成本。如果遵守规范比不遵守更省事大家自然会选择遵守。纳入新人入职流程在新人 onboarding 文档中明确列出项目规范并提供一个“五分钟上手”的检查清单让他们快速配置好环境并提交第一个符合规范的 commit。定期复盘与优化在团队周会或迭代回顾会上可以花少量时间讨论现有规范是否有不合理、令人困惑的地方并一致同意后进行优化。让规范是“活”的是为大家服务的。5.2 处理历史遗留项目对于已经存在的大量“不规范”代码全部一次性改造是不现实的。增量优化制定一个原则“新代码必须遵守规范旧代码在修改时逐步优化”。例如修改某个老旧文件时顺手用 ESLint 和 Prettier 格式化它。划定边界如果旧模块实在庞大且稳定可以暂时在 ESLint 配置中将其整个目录忽略ignorePatterns避免干扰新开发。工具辅助重构利用 IDE 的重构工具、代码格式化工具可以批量处理一些简单的风格问题如引号、缩进。5.3 衡量效果规范带来了什么推行一段时间后可以从这几个方面感受变化代码评审效率评审者是否更少地评论风格问题而更专注于逻辑和架构新人上手速度新人能否在一天内 clone 代码、安装依赖、并成功运行和修改项目问题定位速度通过规范的提交信息能否更快地定位引入某个 bug 的变更自动化程度Changelog 是否能够自动生成版本号能否自动更新如果答案大多是肯定的那么“Conventional”的实践就真正创造了价值。说到底“Conventional”不是一套僵化的教条而是一组经过权衡的、旨在提升集体效率的共同决策。它的最终目的是让团队能把宝贵的精力集中在解决真正的业务和技术难题上而不是浪费在无谓的格式争论和沟通误解中。从一条提交信息规范开始逐步扩展到代码、目录、API你会发现整个团队的产出会变得更加清晰、稳定和高效。