開發自己的工具庫(一)：專案搭建

後排的風過發表於2018-07-29

前言

本系列文章將通過自己的一個開發工具庫的實戰經驗(踩過的坑)教大家如何開發屬於自己的一個工具庫，在這裡你可以學到Git的使用規範，基礎專案的搭建，程式碼編寫的規範，函數語言程式設計思想，TypeScript實戰，單元測試，編寫文件和釋出NPM包等等知識。

閱讀文章你可能需要以下基礎知識：

專案原始碼

Windlike-Utils

Git專案

Git分支

├── master -------------------------------- 和釋出版本程式碼保持一致
│   ├── dev -------------------------------- 開發分支
│   │   ├── feature -------------------------------- 開發新特性的分支
│   │   ├── hotfix -------------------------------- 修復BUG的分支
複製程式碼

Git提交規範

程式碼有編寫規範，Git提交的資訊當然也要有規範啦。

<type>(<scope>): <subject>
// 空一行
<body>
// 空一行
<footer>
複製程式碼

type用於說明本次提交的型別：

  • feat：新功能（feature）
  • fix：修補bug
  • docs：文件（documentation）
  • style： 格式（不影響程式碼執行的變動）
  • refactor：重構（即不是新增功能，也不是修改bug的程式碼變動）
  • test：增加測試
  • chore：構建過程或輔助工具的變動

scope用於說明本次改動涉及的範圍，如資料層、控制層，選填。 subject為本次提交的簡要概述。

這裡是一個栗子：

fix(model): fix something

- fix first bug
- fix second bug

Closes #123
複製程式碼

可是有人不遵守或者無意識地不按格式填怎麼辦呢，這裡就需要工具來做驗證啦，我使用的是ghooks和validate-commit-msg，具體看下面。

想看更多Git提交規範知識點這裡：Commit message 和 Change log 編寫指南

專案結構

├── .vscode ------------------------------- vscode相關配置檔案
├── dist ---------------------------------- 構建後檔案的輸出目錄
├── docs ------------------------------ 文件
├── release ---------------------------------- Gulp合併打包後的檔案，用於CDN版本
├── packages ------------------------------ 存放獨立釋出的包的目錄
├── src ----------------------------------- 原始碼
│   ├── __test__ -------------------------- 存放入口檔案的測試用例
│   ├── <module> ------------------------------ 工具庫模組
│   │   ├── __test__ ---------------------- 測試該模組的測試用例
│   │   ├── index.d.ts ---------------------- 該模組的標頭檔案
│   │   ├── index.ts ---------------------- 該模組的實現程式碼
│   ├── utils.d.ts ---------------------------- 公共的標頭檔案
│   ├── utils.ts ------------------------- 匯出所有模組的檔案
├── package.json 
├── .eslintignore ----------------------------- eslint忽略配置檔案
├── .eslintrc.js ------------------------- eslint配置檔案
├── .gitignore --------------------------- git忽略配置檔案
├── .npmignore ------------------------------ npm忽略配置檔案，用於釋出
├── .vcmrc ----------------------------- 用於檢驗git提交資訊是否符合格式
├── CHANGELOG.md ------------------------- 版本更變日誌
├── gulpfile.js ---------------------------- gulp
├── index.js ---------------------------- 入口檔案
├── README.md ---------------------------- README
├── tsconfig.json ---------------------------- TypeScript配置檔案
複製程式碼

package.json

{
  "name": "windlike-utils",  // 要釋出包的名字
  "version": "2.0.7",  // 版本
  "description": "",  // 描述
  "main": "index.js",  // 入口檔案
  "scripts": {
    "test": "jest",  // 測試
    "dev": "tsc -w --downlevelIteration",  // 開發，檢測程式碼變化並編譯成JS
    "start": "node index",  // 執行入口檔案
    "build": "tsc -d && gulp build",  // 打包，編譯成JS並用Gulp合併壓縮
    "eslint": "eslint src --ext .ts",  // 檢查程式碼格式
    "eslint:fix": "eslint src --ext .ts --fix",// 檢查並修復程式碼格式
    "log": "conventional-changelog -p angular -i CHANGELOG.md -w -r 0"  // 生成版本日誌
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/MrWindlike/Windlike-Utils.git"
  },
  "keywords": [],
  "author": "Windlike",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/MrWindlike/Windlike-Utils/issues"
  },
  "homepage": "https://github.com/MrWindlike/Windlike-Utils#readme",
  "devDependencies": {
    "@types/jest": "^23.3.0",
    "awesome-typescript-loader": "^3.4.0",  // TS loader
    "babel-core": "^6.26.0",
    "babel-loader": "^7.1.2",
    "babel-plugin-transform-runtime": "^6.23.0",
    "babel-preset-es2015": "^6.24.1",
    "babel-runtime": "^6.26.0",
    "cz-conventional-changelog": "^2.1.0",  // 生成版本日誌的工具
    "eslint": "^5.2.0",
    "eslint-plugin-typescript": "^0.12.0",   // eslint檢測TS程式碼的工具
    "ghooks": "^2.0.4",  // git週期管理
    "gulp": "^3.9.1",
    "gulp-concat": "^2.6.1",  // gulp合併工具
    "gulp-uglify": "^3.0.0",  // gulp壓縮工具
    "jest": "^23.4.1",  // 測試程式碼的工具
    "source-map-loader": "^0.2.3",
    "ts-jest": "^23.0.1",
    "typescript": "^2.6.2",
    "typescript-eslint-parser": "^17.0.1",  // eslint檢測TS程式碼的工具
    "validate-commit-msg": "^2.14.0"  // 驗證git提交程式碼工具
  },
  "jest": {  // jest配置
    "roots": [
      "<rootDir>/src"
    ],
    "transform": {
      "^.+\\.tsx?$": "ts-jest"
    },
    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
    "moduleFileExtensions": [
      "ts",
      "tsx",
      "js",
      "jsx",
      "json",
      "node"
    ]
  },
  "config": {
    "commitizen": {
      "path": "./node_modules/cz-conventional-changelog"
    },
    "ghooks": {
      "pre-commit": "npm run eslint && npm test",  // 提交前檢查程式碼格式和執行測試用例
      "commit-msg": "validate-commit-msg"  // 提交時驗證提交資訊是否符合格式
    }
  }
}
複製程式碼

驗證Git提交資訊

使用ghooks和validate-commit-msg可以在git提交時檢查資訊。

"ghooks": {
  "pre-commit": "npm run eslint && npm test",  // 提交前檢查程式碼格式和執行測試用例
  "commit-msg": "validate-commit-msg"  // 提交時驗證提交資訊是否符合格式
}
複製程式碼

但還需要一個驗證規則的檔案.vcmrc：

{
  "types": [
    "feat",
    "fix",
    "docs",
    "style",
    "refactor",
    "perf",
    "test",
    "build",
    "ci",
    "chore",
    "revert"
  ],
  "scope": {
    "required": false,
    "allowed": [
      "*"
    ],
    "validate": false,
    "multiple": false
  },
  "warnOnFail": false,
  "maxSubjectLength": 100,
  "subjectPattern": ".+",
  "subjectPatternErrorMsg": "subject does not match subject pattern!",
  "helpMessage": "",
  "autoFix": false
}
複製程式碼

這樣就可以檢驗提交資訊是否符合格式，不符合是不能提交成功的。

TypeScript配置

tsconfig.json:

{
    "compilerOptions": {
        "outDir": "./dist/",  // 輸出目錄
        "sourceMap": true,  // 是否啟用sourceMap，用於程式碼除錯
        "noImplicitAny": true,  // 是否不能含有潛在的```any```型別
        "module": "commonjs",  // 編譯輸出的模組型別
        "target": "es5",
        "lib": [
            "es2017",
            "dom"
        ]
    },
    "include": [  // 需要編譯的程式碼
        "./src/*"
    ]
}
複製程式碼

總結

這篇文章就講到這裡啦，其他的細節就不一一講啦，想了解其他的配置檔案可以到原始碼倉庫，下篇文章將講下函數語言程式設計的一些知識。

相關文章