如何开始你的开源之路(中) --- 发布自己的第一个前端开源库 - 知乎

安宇雨 - 随手采集
2024-01-03 23:57:59
随手采集
0000-未整理-等待研究

前言

上一篇介绍了一个前端的开源库如何初始化，本篇会介绍从编码过程中到发布的一些小技巧。这些也是我在学习过程中的一些片段整理，希望对大家有用。因为是面向萌新，所以可能会有点啰嗦，大佬们点个赞就可以离开了。

--- 原创文章转载请说明出处 ---

代码格式化

编写一个开源代码，你所写的所有源代码都会暴露给大众，如果你的编码风格太过于潦草，你会发现大家“看”你的眼神怪怪的。为了让你的代码看起来更加符合规范，能够更加符合大佬们的审美～我们也是需要给代码美颜一下的。为了给代码美颜，我们需要安装一个代码美颜神器：prettier。

安装依赖

 npm install prettier -D

记得添加-D标志，这个上一篇已经介绍过原因了。安装好依赖以后，我们在package.json的script里面加入一个命令。

配置脚本

"format": "prettier --write \"src/**/*.ts\"",

上面命令中的 src 是你源代码的目录，如果你的源代码不是放在这个文件夹里请自行修改为你的源文件目录。后面的**/*.ts是递归查找该目录下的所有ts文件。

创建配置文件

在项目根目录下创建一个叫.prettierrc的文件，这是配置prettier规则的文件，如果你没有创建这个文件，prettier会按照默认的规则来个实话代码，当然默认规则也非常不错了。但是如果你有特殊要求，可以把规则写到这个文件里面来覆盖默认规则。这里举个例子，比如有些人习惯在一个对象的最后一个元素后面加上逗号，并且喜欢在字符串中使用单引号，那么可以在文件中写入下面规则：

{     
  "trailingComma": "all",     
  "singleQuote": true   
}

更多规则可以去查看prettier的文档，咱们可以先把架子搭起来，再慢慢完善。这样就算你写的代码是下面这样：

const data =   astro.astrolabeBySolarDate(
birthday, 
   birthTime, 
 gender, fixLeap  );

在执行 yarn format 或者 npm run format 格式化以后就会变成这样：

const data = astro.astrolabeByLunarDate(     
     birthday,     
     birthTime,
     gender,
     isLeapMonth,
     fixLeap   
);

当然，现在随着编辑器的进化，我们完全可以让编辑器来帮我们做这件事情，假如你使用的是vscode，那可以在设置里勾选Format on save和Fomat on paste。这样在我们按ctrl+s保存代码或者是粘贴代码的时候，只要代码没有错误，编辑器就会帮我们执行format。

编码风格检查

光有外在的代码有可能中看不中用，所以，我们除了需要注意外在的形象，更要注重内在美。接下来我们需要用到另一个神器，它就是eslint。如果preitter是修饰外表的话，那么eslint就是切实的提升内在。正所谓练武不练功，到老一场空。良好的编码风格不仅让代码更加严谨，还能减少不良习惯带来的一系列问题，比如可读性差，代码不容易维护等负面影响。

安装依赖

npm install -D \       
    eslint\       
    eslint-config-standard-with-typescript\       
    eslint-plugin-import eslint-plugin-n\       
    eslint-plugin-promise\       
    @typescript-eslint/eslint-plugin

这个等待过程通常比较漫长，你也可以换成yarn或者速度更快的bun来安装依赖，不过bun对 Windows 的支持还不太好。

配置文件

我们需要在项目根目录下配置两个文件：

.eslintignore
这个文件里面是放一些你不想让lint检查的文件或文件夹

 node_modules 
 lib coverage 
 .vscode 
 .github

.eslintrc.json
这个文件是配置eslint的规则

{   
  "env": {     
    "browser": true,     
    "es2021": true   
  },   
  "extends": [     
    "eslint:recommended",     
    "plugin:@typescript-eslint/eslint-recommended",     
    "plugin:@typescript-eslint/recommended"   
  ],  
 "parserOptions": {    
   "ecmaVersion": "latest",    
   "sourceType": "module"  
 },   
 "rules": {} 
}

具体配置可以去查看eslint的文档，如果你想偷个懒或者想先集成进来再慢慢研究，也可以像我一样直接使用extends里的默认规则，如果你有特殊的要求，写在rules里面就可以了。
注意：配置好eslint以后写代码就没办法那么放飞自我了，比如一些空的代码块，没有使用的变量，甚至嵌套的三元运算符等等有可能都会报错或者报警告。

配置脚本

以上配置好了以后我们就可以把执行脚本添加到package.json的scripts里面了

"lint": "eslint . --ext .ts",

代码注释

说起代码注释，大家肯定是对它又爱又恨，爱的是别人写好了注释，恨的是自己写注释。作为一个开源程序，注释是个非常重要的东西，它的重要性可以说和文档旗鼓相当。下面这个方法是没有注释的时候，别人在调用的时候根本不知道这个方法是干嘛的，也不知道参数是干嘛的，更不知道返回值是什么，应该怎么用等等。

1694792282870.jpg

加入我们给方法加上注释

/**
 * 传入用户的名字，返回一段问候语。
 *
 * @param {string} name 用户的名字
 * @returns {string} 一串问候语
 */
function guessWhatCanIDo(name: string) {
  return `Hello ${name}~ Have a nice day!`;
}

这个时候用户再调用的时候，就可以看到每个参数的说明，这个方法的作用以及返回值的解释。

image.png

假如我们再把注释完善一点

/**
 * 传入用户的名字，返回一段问候语。
 *
 * @version v1.2.0+
 * @param {string} name 用户的名字
 * @returns {string} 一串问候语
 *
 * @example
 *
 * guessWhatCanIDo('foo'); // Hello foo~ Have a nice day!
 */
function guessWhatCanIDo(name: string) {
  return `Hello ${name}~ Have a nice day!`;
}

我们再把鼠标移动到方法上就会看到更完善的信息，比如这个方法是哪个版本加入的，如何调用，都一目了然

image.png

还有一个非常实用的标记 @deprecated，它可以将一个方法或属性标记为废弃状态，这样别人在调用的时候就会出现一条删除线。完整的示例是这样的

/**
 * 传入用户的名字，返回一段问候语。
 *
 * @version v1.2.0+
 *
 * @deprecated v2.1.3，请使用 `greeting(name: string)` 方法代替
 *
 * @param {string} name 用户的名字
 * @returns {string} 一串问候语
 *
 * @example
 *
 * guessWhatCanIDo('foo'); // Hello foo~ Have a nice day!
 */
function guessWhatCanIDo(name: string) {
  return `Hello ${name}~ Have a nice day!`;
}

这时用户再调用的时候就会是这样的

image.png

怎么样，代码是不是瞬间变得莫名的厉害起来？赶快把注释写起来吧。

测试

一套完整的代码，测试是必不可少的，甚至测试代码会比功能代码多。这也往往是大家比较讨厌的部分，平时写代码是能省则省。但是对于开源项目来说，测试就尤为重要了。因为大家都可以贡献代码，但是别人并没有办法百分之百的理解你的代码和想法，这个时候就需要单元测试来约束大家。它保证了你原本写的吃饭方法不会去吃翔。

测试代码可以统一放在__test__文件夹下，也可以和功能代码放在一起，后者叫做同置（Collocation），两种方法各有利弊，习惯用哪种就用哪种吧。

安装依赖

npm install -D jest ts-jest @types/jest

配置文件

在根目录下创建jestconfig.json文件

{
     "transform": {
       "^.+\\.(t|j)sx?$": "ts-jest"
     },
     "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.(jsx?|tsx?)$",
     "moduleFileExtensions": ["ts", "tsx", "js", "jsx", "json", "node"]
}

配置脚本

在package.json的scripts里配置执行命令

"test": "jest --config jestconfig.json --coverage",

其中--coverage会生成代码覆盖率，下一篇会介绍到。

写单元测试

在__test__目录或者你功能代码目录下创建一个[name].test.ts的文件，其中[name]就是你要测试的目标代码文件的文件名。然后就开始写单元测试吧

   describe("测试index.ts里的各个功能是否正常", () => {
     test("guessWhatCanIDo()", () => {
       expect(guessWhatCanIDo("Sylar")).toBe("Hello Sylar~ Have a nice day!");
     });
   });

然后在控制台执行npm run test。不出意外的话你将会看到执行成功的日志

image.png

其中红色数字代表该文件的这些行没有被测试到，而黄色数字则代表该文件的这些行有条件没有被覆盖到，比如你这行代码是判断性别的，但是你只测试代码里调用的时候只传入了女，没有传男。下面的Test Suites代表你单元测试代码里describe()方法的数量，而Tests代表了你test()方法的数量。当所有测试都通过了就是绿色的，如果有某些测试没有通过会有红色的数字。