道术合一

Appearance

前端规范通则 ​

一、代码规范 ​

目标：统一代码风格，提升可读性、可维护性，减少低级错误。

  • SOP：

    1. 代码提交检查流程：所有代码在 git commit 时，必须自动触发 ESLint 和 Prettier 检查与格式化，未通过则阻止提交。
    2. 合并请求（MR/PR）检查清单：发起合并请求前，必须在本地运行并通过完整的 npm run lint 和 npm run test。
    3. 新项目初始化流程：创建新项目必须使用公司标准脚手架，自动注入统一的 .eslintrc、.prettierrc 和 lint-stage 配置。

  • 最佳实践：

    • 规则选择：采用 Airbnb JavaScript Style Guide 或 Standard 作为基础，结合 TypeScript 规则进行微调。
    • 工具固化：将格式化与检查工具（Prettier, ESLint）的配置封装为独立的 NPM 包（如 @company/eslint-config），所有项目强制继承。
    • IDE 统一：推荐并共享团队统一的 VSCode settings.json 和插件列表（如 ESLint、Prettier），确保“保存即格式化”。

参考文档：

二、Git 工作流规范 ​

目标：清晰管理代码历史，实现高效、可追溯的团队协作。

  • SOP：
    1. 分支管理流程：严格遵循 GitFlow 或 GitHub Flow。
      • feature/* 从 develop 拉取，合并回 develop。
      • hotfix/* 从 master 拉取，合并回 master 和 develop。
    2. 合并请求（MR）流程：
      • 必须有至少一位核心成员 Code Review 通过。
      • 必须关联任务管理系统（如 JIRA）的 Ticket ID。
      • 必须通过 CI 流水线的所有检查（构建、测试、Lint）。
    3. 提交信息格式：必须遵循 Conventional Commits 规范（如 feat:, fix:, docs:），便于自动生成变更日志。
  • 最佳实践：
    • 工具辅助：使用 commitizen + cz-conventional-changelog 交互式生成规范提交信息。
    • 提交前检查：配置 husky 在 commit-msg 钩子中校验提交信息格式。
    • 合并策略：采用 Squash and Merge，保持主线历史清晰。

参考文档：

三、项目结构规范 ​

目标：统一项目脚手架和目录约定，降低新人熟悉成本。

  • SOP：
    1. 项目初始化 SOP：必须使用公司内部 CLI 工具（如 create-frontend-app）创建新项目，自动生成标准目录。
    2. 目录结构模板：所有项目必须遵循以下基本结构：
      src/
├── assets/          # 静态资源
├── components/      # 公共组件
├── views/pages/    # 页面组件
├── store/          # 状态管理
├── router/         # 路由配置
├── utils/          # 工具函数
├── hooks/          # 自定义Hooks
├── services/       # API请求层
└── types/          # TypeScript类型定义
  • 最佳实践：
    • 功能切片（Feature-Sliced）：对于复杂应用，采用按业务功能组织的目录结构，而非按技术类型（如 src/features/user/ 包含组件、状态、API）。
    • 配置外置：将构建配置、环境变量等放置在项目根目录的 config/ 文件夹下，与业务代码分离。

参考文档：

四、组件开发规范 ​

目标：创建高内聚、低耦合、可复用的 UI 组件。

  • SOP：
    1. 组件创建流程：使用 plop 或内部 CLI 生成组件模板，必须包含：Component.vue/tsx、Component.test.ts、Component.stories.ts（Storybook）、index.ts（统一导出）。
    2. Props 定义规范：必须使用 TypeScript 严格定义 Props 接口，并为每个属性编写清晰的 JSDoc 注释。
    3. 组件测试要求：提交的组件必须包含覆盖核心交互和状态的单元测试。
  • 最佳实践：
    • 设计先行：组件 API 设计应与 UI/UX 设计师共同敲定，并优先在 Storybook 中实现和验证。
    • 单一职责：组件应专注于一件事。复杂组件应拆分为“容器组件”（管理逻辑）和“展示组件”（负责渲染）。
    • 样式方案：推荐使用 CSS Modules 或 Styled-Components 等具有隔离性的方案，并制定统一的样式变量（如颜色、间距）体系。

五、测试规范 ​

目标：建立可靠的质量防护网，保障代码正确性和可重构性。

  • SOP：
    1. 测试金字塔执行流程：
      • 单元测试：任何工具函数、工具类、React/Vue 组件必须有单元测试（Jest/Vitest）。
      • 集成测试：关键用户流程（如登录、下单）必须有集成测试（Cypress/Playwright）。
      • E2E 测试：核心主干流程在发布前必须通过 E2E 测试套件。
    2. 覆盖率阈值：单元测试覆盖率必须达到：语句覆盖率 > 80%，分支覆盖率 > 70%。CI 流水线会强制检查。
  • 最佳实践：
    • 测试驱动开发（TDD）：鼓励在开发复杂逻辑或工具函数时先写测试。
    • 测试数据管理：使用 factory.ts 或 fixtures 统一管理测试数据，避免在测试中硬编码。
    • 测试即文档：测试用例的名称应清晰描述业务行为（如 should display error message when login fails）。

参考文档：

六、文档规范 ​

目标：实现知识沉淀，降低团队沟通成本和新人上手门槛。

  • SOP：
    1. 项目 README 模板：每个仓库必须包含标准化的 README.md，需包含：项目简介、本地启动命令、构建部署说明、环境变量配置、常见问题。
    2. 组件文档化：提交到公共组件库的每个组件必须在 Storybook 或类似工具中有交互式示例和 API 说明。
    3. 架构决策记录（ADR）：任何重大的技术决策或架构变更必须创建 docs/adr/001-xxx.md 进行记录。
  • 最佳实践：
    • 文档即代码：文档与源码一同存放在仓库中，版本同步，修改需发起 MR。
    • 自动化文档：使用 TypeDoc 或类似工具，从代码注释中自动生成 API 文档。
    • Changelog 自动化：利用 standard-version 或 lerna-changelog 根据规范化的提交信息自动生成更新日志。

七、构建与部署规范 ​

目标：实现快速、稳定、可重复的交付流程。

  • SOP：
    1. CI/CD 流水线流程：
      • 推送代码到特定分支（如 develop, master）自动触发 CI。
      • CI 流水线必须顺序执行：安装依赖 -> Lint检查 -> 单元测试 -> 构建打包 -> 部署到测试环境。
      • 只有通过所有步骤的构建产物才能进入下一阶段。
    2. 版本发布流程：生产环境发布必须通过创建 Git Tag 触发，并自动生成版本号（遵循 SemVer）。
  • 最佳实践：
    • 容器化构建：使用 Docker 镜像作为构建环境，确保环境一致性。
    • 构建缓存优化：在 CI 中配置 npm/yarn 缓存、Vite/Webpack 构建缓存，大幅提速。
    • 渐进式部署：采用蓝绿部署、金丝雀发布等策略，结合监控告警，实现平滑、低风险的上线。

参考文档：