1.2 编码规范

编码规范是保障代码质量、提升团队协作效率与维护性的基础。良好的编码习惯不仅有助于减少 Bug，还能提升项目的长期稳定性与可扩展性。

以下是从以往项目中总结整理出来的一些编码规范，适用于 Vue/React 技术栈下的B端应用开发场景。

一、JavaScript / TypeScript 规范

1. 命名规范

• 变量命名使用有意义的英文单词，采用 camelCase，如 userName, isLoading；
• 常量命名全大写加下划线，如 MAX_RETRY_COUNT；
• 函数命名以动词开头，表达行为意图，如 fetchData(), validateForm()；
• 类或类型命名使用 PascalCase，如 UserService, UserModel；
• 布尔值命名以 is、has 或 should 开头，如 isVisible、hasPermission；

2. 代码风格

• 所有项目强制使用 const 和 let，禁止使用 var，避免作用域污染；
• 合理使用解构赋值、默认参数、箭头函数等 ES6+ 特性；
• 模块导入导出统一路径风格（推荐相对路径 + 别名 @）；
• 强制使用 TypeScript，并开启严格模式（strict: true）；
• 接口字段命名保持一致性，如后端返回 userName，前端也应使用 userName；

3. 类型安全（适用于 TypeScript）

• 所有对外暴露的函数、组件 props 必须声明类型；
• 接口定义统一存放在 types 目录；
• 推荐使用联合类型、泛型等高级特性提升灵活性；
• 不允许使用 any，确需动态类型时使用 unknown；
• 使用类型守卫进行运行时判断，避免类型错误；

二、HTML 规范

• 标签书写规范，闭合标签必须完整；
• 属性名使用小写，多个单词用 - 分隔，如 data-id, aria-label；
• 尽量避免自定义非标准属性，优先使用 data-*；
• 表单控件加上 for 与 id 关联，提升可访问性；
• 标签嵌套结构清晰，缩进统一；
• 所有 HTML 文件需验证是否符合语义结构，确保 SEO 与无障碍支持；

三、CSS / SCSS 规范

• 使用 BEM 命名法，提高组件样式隔离性；
• 类名使用小写加连字符，如 .user-card、.btn-primary；
• 避免 ID 选择器，减少样式权重冲突；
• 公共样式提取为 _common.scss 或 variables.scss；
• 移动端适配建议使用 Flexbox 或 Grid 布局；
• 使用 CSS 变量或 SCSS Mixin 实现主题定制；
• 动画统一管理，避免随意添加过渡效果；

四、目录结构建议（Vue 项目为例）

src/
├── assets/              # 图片、字体等静态资源
├── components/          # 可复用 UI 组件
├── views/               # 页面级组件
├── services/            # API 请求服务（axios 封装）
├── utils/               # 工具函数（如 date-format.js, storage.js）
├── store/               # 状态管理（Pinia/Vuex 模块）
├── router/              # 路由配置
├── styles/              # 全局样式或变量文件
├── types/               # TypeScript 类型定义
├── App.vue              # 根组件
└── main.js              # 入口文件

五、单文件组件规范（Vue）

• 每个 .vue 文件只包含一个组件；
• template、script、style 三个区块顺序固定；
• style 区块添加 scoped 或 module，避免样式污染；
• 组件名使用 PascalCase（如 UserProfile.vue）；
• 组件内逻辑复杂时拆分为子组件，保持职责单一；

六、工具与自动化

• 使用 ESLint + Prettier 统一格式化标准；
• Git 提交前自动格式化（VSCode 保存格式化 + Husky + lint-staged）；
• 所有 PR 必须经过 Code Review；
• 审查关注点包括：是否符合编码规范、是否有潜在 Bug、性能问题等；
• 推荐使用 GitHub PR 模板统一提交说明；

七、TypeScript 使用建议

• 所有对外暴露的函数、组件 props 必须声明类型；
• 接口定义统一存放在 types 目录；
• 推荐使用联合类型、泛型等高级特性提升灵活性；
• 不允许使用 any，确需动态类型时使用 unknown；
• 使用类型守卫进行运行时判断，避免类型错误；

八、API 接口封装规范

• 接口统一存放于 services 目录；
• 每个模块单独封装，如 user.service.ts、order.service.ts；
• 接口调用统一返回 Promise；
• 错误处理统一拦截，返回统一结构；
• 推荐使用 Axios 并封装请求拦截器、响应拦截器；

九、异常处理机制

• 所有异步操作必须捕获异常；
• 使用 try/catch 或 Promise.catch 处理错误；
• 错误信息统一上报至监控平台；
• 用户提示统一封装，避免直接抛出原始错误信息；

十、日志与埋点规范（便于后期运维）

• 所有关键操作添加埋点，如按钮点击、页面进入、接口失败；
• 日志记录采用统一方法，如 logger.info、logger.error；
• 日志级别清晰划分，便于排查问题；
• 上线前移除调试日志输出；