答辩文档要点记录｜青训营笔记

天何言哉
154 阅读14分钟

这是我参与「第五届青训营 」伴学笔记创作活动的第 15 天

一、项目介绍

一句话概括项目核心信息-必须

项目服务地址-必须

Github 地址，权限设置为 public- 必须

全员无项目经验小白，最终仅两人开发，一个月内完成devops并按规范控制代码质量，vue3+ts+vite构建的组件库，现包含组件6个，其中核心需求复杂组件共2个全部完成。

文档站预览地址 http://39.101.72.88:8081/

项目发布地址（未发布在npm） http://39.101.72.88/

代码地址 gitlab.com/JasonGuo1/j… 注：dev分支

二、项目分工

好的团队协作可以酌情加分哟～请组长和组员做好项目分工与监督。

项目搭建前使用飞书、飞书云文档等进行项目规划及进度管理；

项目搭建后（本想）使用gitlab issue进行任务分配，但由于跳车人数过多，issue 进行assignment反而没有必要

三、项目实现

3.1 技术选型与相关开发文档

可以补充场景分析环节，明确要解决的问题和前提假设，比如按当前选型和架构总体预计需要xxx存储空间，xxx台服务器......。

技术选型总览：

技术栈： vue3+ts+scss
规范

  1. 分支管理 Github flow

    1. dev分支下自己切分支开发，平时merge到dev上；

      1. 使用时，git clone ->git checkout dev -> git branch "新分支名称" -> 进行开发 ->开发完毕 -> git add . -> git commit -m "type(scope):subject #issuenum"
      2. 当不小心覆盖了main的commit 如在main 分支下pull dev分支时 ，请使用回退，撤销commit、暂存区 回退前一版本代码：git reset HEAD~1

  2. 代码提交 Git commit 遵循 类angular 规范 （有husky+commitlint+lint-staged强制控制，如果不符合将不予commit）

    1.   type: (scope)subject #issueNum请注意type:后面有一个空格
    2.   type见

  3. 每人负责的组件user story 应建立 #issue 及 README.md ——即组件设计

  4. CSS 类名称 遵循 BEM规范 BEM规范

  5. code style： eslint+prettier+stylelint+lint-staged+husky＋commonlint

  6. 测试用例命名及位置存放规范

    1. 根据 jest 约定：

      • 功能函数对应的测试函数放在__tests__目录中功能函数所对应的目录中；

      • 测试的函数的文件名会是 fun.spec.js。 比如 add.js => add.spec.js。

构建工具 ：vite
测试工具：单元测试 jest

集成测试：cypress，但截至本文档提交之日尚未进行集成测试

代码审查工具

使用 ts

code style： eslint+prettier+stylelint+lint-staged+husky＋commonlint

注： stylelint使用在对scss,sass等样式文件的风格检查中，但由于其对于vue文件中import样式文件的限制import-notation | Stylelint 以及在script及template中对代码风格的检查与eslint及prettier产生冲突，我们仅针对src/styles/*.module.scss 开启了stylelint的风格检查，任何vue文件均添加至stylelintignore文件中， 其不对任何vue文件发生效力。

组件开发

dropselect中，对于远程搜索，使用了@vant/area-data 的数据

关于cicd及远程仓库等的选型说明

虽然cicd上有诸如github actions ， gitlab等竞品，最终由于jenkins+ngnix开源且教程众多选择了jenkins+ngnix的cicd流程：

  • Jenkins 完成持续集成
  • Ngnix 完成持续部署

在远程仓库的选择上，首先我们想用github作为远程仓库，但由于实际github webhook填入jenkins后，无法构建完成，后来使用gitee作为远程仓库，jenkins成功构建，我们猜想可能是由于网络不稳定所导致的。但由于技术要求文档中没有gitee远程仓库的选项，我们更换为了gitlab仓库。

而又由于我们的服务器只有2G内存，无法在docker中启动私有gitlab仓库（需要4G内存），最终我们使用远程的gitlab webhook成功构建。（gitlab推荐的方法无法构建gitlab+jenkins 遇到的问题 ，仍需使用webhook方法）

需要说明的是我们组没有购买域名，服务器地址为http://39.101.72.88/ 其主页面虽然为空白页面（因为app.vue还未添加url)，但已成功部署，可以http://39.101.72.88?=btnAble查看到button组件样式，其他组件type类似，详见app.vue代码。文档站中simulator 也是像这样引入iframe进行预览的。

关于构建工具vite的选型说明

选择vite不选webpack

选型原因：

参考链接

  • vite在开发环境下，模块以原生 esm 的形式被浏览器加载。
  • 生产环境下，模块被 Rollup 以传统方式打包，而且做了很多默认优化。虽然默认是打包的格式也是 ESM，但也可以通过 plugin-legacy 输出其它格式兼容旧浏览器。
  • 开发和生产环境下共享同一套 Rollup 插件机制，所以单个模块的编译在开发和生产环境下是一致的 。

webpack与vite优缺点对比

  1. webpack启动开发服务器时必须打包所有模块，服务器启动速度慢；vite利用原生ESM提高速度，加载时间缩短——vite开发体验好

  2. webpack配置灵活但困难，配置文件复杂；vite配置语法简单，无需配置，但灵活性较差——vite对学习者友好

  3. webpack需要使用polyfill加载模块，打包大小更大；vite使用ESM打包小。

  4. webpack生态好，有大量插件和社区支持。

vite构建生产版本参考链接：

暂时无法在飞书文档外展示此内容

关于git hook的选型说明

详解如何在项目中使用git Hooks(husky、yorkie) - 掘金

根据vue-cli官方文档，以及社区issue讨论，vue-cli难以使用husky作为钩子；

后续，改为vite作为构建工具后，使用了husky作为git 钩子，同时用pnpm包管理工具解决husky与eslint的版本依赖冲突问题。（报错截图略）

关于测试工具的选型说明

单元测试：

Mocha vs. Jest: comparison of two testing tools for Node.js

表格 还在加载中，请等待加载完成后再尝试复制

关于组件库的文档站的技术选型说明

调研了TSDoc TSDoc 笔记 等文档生成工具文档生成工具调研 ，发现其与markdown文本区别在于会在注释中添加如@remark等字样的标签，

如果要引入文档生成工具，将会改变开发人员的注释习惯。

由于开发时间较短且人员不足，最终采取使用vuepress或vitepress等直接使用markdown生成文档站点的自动化工具，而markdown文档则由开发人员手动进行撰写及维护。

在vuepress和vitepress的选择上 ，与 Vuepress 的区别 | VitePress 中提到：

VitePress 的目标是为编写文档提供最基本的功能。其他特性被委托给主题。另一方面，VuePress 拥有更多的开箱即用的特性，以及支持插件生态系统。

另外也由于vitepress不支持yaml语法，官方文档也不建议在使用vuepress的同时迁移至vitepress，毕竟其仍是一个实验性的项目，故最终选择使用vuepress生成文档站。

使用vuepress生成文档站的笔记

由于我们未将项目发布至npm，在文档站中引入组件库建立simulator预览是我们首先要解决的问题， 上文笔记中记载了两种针对未发布项目的引入方法，但最终我们选择了与vant相同的iframe引入预览的方法。

文档站预览地址：http://39.101.72.88:8081/

其他

参考文档：工程化选型说明文档

服务器：1台，经济原因选择阿里云免费试用一个月的2G centos服务器（服务器和cicd部署与技术选型同时进行）

3.2 架构设计

可以补充场景分析环节，明确要解决的问题和前提假设，比如预计0.5%的用户属于大V，粉丝很多，也会经常上传视频，当前架构的解决方案是xxx。

场景分析

组件库是为开发者提供可复用的 UI 组件，帮助开发者快速搭建界面。本组件库的主要场景为 Web 应用程序的开发，适用于多种类型的应用程序，包括管理后台、电商平台、社交应用等。

在实际应用中，开发者需要使用不同类型的 UI 组件，包括表单、列表、导航、弹窗、图表等。这些组件在不同的应用场景下有不同的需求，例如表单需要支持输入校验、列表需要支持分页、导航需要支持多级菜单等。

为了满足这些需求，我们需要设计一个可扩展的组件库架构，使得开发者可以方便地使用现有组件，也可以根据需求自定义组件。

问题与前提假设

在设计组件库架构时，需要考虑以下问题：

  1. 如何设计组件间的通信机制，使得组件可以协同工作？
  2. 如何实现组件的可配置性，使得开发者可以根据需求自定义组件？
  3. 如何实现组件的可测试性，保证组件质量？
  4. 如何确保代码风格一致性，提高代码可读性和可维护性？
解决方案：
  1. 使用props与通信回显机制，使组件协同工作
  2. 尽可能将开发者的需求定义为props等属性，使得开发者能够根据需求进行一定程度的自定义
  3. 使用jest测试框架，保证单元测试覆盖率；争取增加集成测试、快照测试等
  4. 使用eslint+prettier+stylelint，并使用vs code 作为IDE，确保代码风格一致
我们的组件库可以满足以下需求
  • 在项目开发中，快速构建基础的UI组件，提高开发效率和代码复用性。
  • 支持基于Vue 3的开发，利用TypeScript和SCSS提高代码的可维护性和可扩展性。
  • 提供良好的代码风格和规范，利用工具自动化检测和修复代码问题。
  • 支持单元测试，确保组件的质量和稳定性。
  • 提供可靠的Git Hook工具，确保代码提交前的代码规范检查和单元测试。

src/目录结构如下：（组件放在views中）

暂时无法在飞书文档外展示此内容

3.3 项目代码介绍

代码地址 gitlab.com/JasonGuo1/j… 注：dev分支

由于暂时单元测试通过率尚未达到100%，并未merge到main分支，形成稳定版本。待单元测试通过率达标后再行merge request。

共完成组件如下：

  1. button

    1. 支持loading

    2. L/M/S 三种大小

    3. 主要按钮/次级按钮/回退按钮

      1. 完成其hover,click,focus等不同样式

    4. 禁用状态

    5. icon按钮

  2. Avator

    1. 支持输入数值自定义大小
    2. 支持圆形和方形
    3. 支持定义颜色
    4. 支持添加isRotate属性显示旋转动画

  3. Input

    1. 支持绑定默认输入文本
    2. 支持输入icon
    3. 支持文本域

  4. Dropselect（核心需求）

    1. 支持远程搜索（多选）
    2. 支持多选
    3. 支持联动选择
    4. 支持选项分组（单选）

  5. cascader 级联选择

    1. 支持单选下拉型的级联选择
    2. 设计样式与其他选择组件保持统一

  6. date-time-picker（核心需求）

    1. 支持设置年月日日期

    2. 支持设置时分秒时刻

    3. 出场动画

四、测试结果

建议从功能测试和性能测试两部分分析，其中功能测试补充测试用例，性能测试补充性能分析报告、可优化点等内容。

功能测试

上图截图于2023-02-22，开发人员正在按照测试结果修改

测试用例可见 gitlab.com/JasonGuo1/j…

性能测试

测试用例可见 gitlab.com/JasonGuo1/j…

由于性能测试未调试好，无法识别<template>等，仍在调试中，尚无有效性能测试覆盖报告

现报错 Jest encountered an unexpected token

暂时无法在飞书文档外展示此内容

20230223更新：性能测试更改文件名perf.spec.ts为spec.ts后可以跑

上图截图于2023-02-23，正在按照测试结果修改

快照测试

待补充（有的写在了性能测试脚本中，注释掉了）

五、Demo 演示视频 （必填）

文档站见该链接： http://39.101.72.88:8081/

暂时无法在飞书文档外展示此内容

组件库发布地址 http://39.101.72.88/

20230222更新：增加了路由设置

20230223更新视频

暂时无法在飞书文档外展示此内容

六、项目总结与反思

  1. 目前仍存在的问题
  2. 已识别出的优化项
  3. 架构演进的可能性
  4. 项目过程中的反思与总结

  1. 目前仍存在的问题

    1. 某些组件耦合性较高，接口较少，灵活性较低，需再行优化重构

    2. 组件数量过少，缺少通用组件icon

    3. 由于大部分测试用例仍为单元测试，缺少集成测试

    4. 目录结构中没有开发调试目录，设计不合理

    5. 规范有缺漏

      1. 缺少文档风格规范，未使用 remark-lint对文档风格进行检查
      2. 缺少组件模版，未使用plop.js等组件生成工具快速生成组件模版
      3. 缺少依赖管理，未使用lint-deps等检查项目依赖的版本是否符合规范
      4. 缺少目录规范，未使用enforce-directory-structure等目录约束工具来维护项目的目录结构

    6. 组件之间的状态通信未引入vuex等状态管理库

  2. 已识别出的优化项

    1. 增加通用组件icon
    2. 增加组件接口，优化重构代码
    3. 优化目录结构，学习iview的目录结构
    4. 遵照测试结果修改脚本代码，增强其健壮性，争取单元测试全部pass后进入性能测试环节
    5. 增加集成测试

  3. 架构演进的可能性

  4. 项目过程中的反思与总结

    1. 反思：

      1. 由于中途跳车的人过多，项目规划经常被打乱，无法正常分配任务并预估进度
      2. 有可能由于前期为技术选型、cicd、项目搭建留出两个星期时间，队员过了兴奋期，丧失热情，不想实际参与开发
      3. 本次项目过程中，发现很多队员都期盼队长下达具体明确的任务，但是不理解又不会直接询问
      4. 虽然已经做了很多鼓励分享的努力，但难以形成讨论的氛围，大家对于学习解构有名组件库的代码不感兴趣，这也造成了在开发过程中，代码质量不是因为语言风格或规范等，而是因为没有模块化思维，未能结构化设计导致的降低

    2. 总结：

      1. 本次项目经验让我们亲身实践，初步入门前端工程化，了解了devops流程，体会到项目规范对团队协作的重要性，初探技术选型

      2. 在项目搭建及后续开发过程中，切身体会到如husky+jest等自动化测试git 钩子的便捷

      3. 在进行组件开发时，初步接触模块化思想，尽量使代码的耦合度降低，使其能够高复用

七、其他补充资料（选填）

avatar
文章
阅读
粉丝