前端开发系列113-工程化篇之Yeoman脚手架generator创建

这篇文章将以实例的方式来教会如何从零开始创建属于我们自己的generator。

点击获取本文示例的generator

generator创建准备

这里我们一切从零开始，在创建自己的generator之前需要做一些准备工作，比如准备好yo命令行工具，比如对生成器生成的项目结构和目录文件有清晰的规划等。

yo命令行工具

在安装了NodeJS和npm的前提下，可以通过下面的命令来安装yo命令行工具，并检查安装是否成功。

$ npm install -g yo

$ yo --version

generator-generator的安装

创建generator可以完全从零开始，也可以使用Yeoman官方提供的generator引导，这里我们选择使用Yeoman官方推荐的方式来处理。

$ mkdir YeomanTest && cd YeomanTest/ 创建新的目录并进入

$ npm install -g generator-generator 安装Yeoman引导generator

列出具体的执行情况

wendingding$ mkdir YeomanTest
wendingding$ cd YeomanTest/
wendingding$ pwd
/Users/文顶顶/Desktop/Yeoman/YeomanTest
wendingding$ npm install -g generator-generator + generator-generator@4.0.2

updated 1 package in 117.639s

   ╭─────────────────────────────────────╮
   │                                     │
   │   Update available 5.5.1 → 6.1.0    │
   │     Run npm i -g npm to update      │
   │                                     │
   ╰─────────────────────────────────────╯

执行Yeoman官方的引导generator，并处理交互式配置部分，下面列出具体的执行情况。

wendingding$ yo generator
? Your generator name generator-wendingding
Your generator must be inside a folder named generator-wendingding
I'll automatically create this folder.
? Description 博客文章测试创建生成器
? Project homepage url http://www.wendingding.com
? Author's Name 文顶顶
? Author's Email 18681537032@163.com
? Author's Homepage http://www.wendingding.com
? Package keywords (comma to split) wendingding
? Send coverage reports to coveralls Yes
? GitHub username or organization flowerField
? Which license do you want to use? Apache 2.0
   create package.json
   create README.md
   create .editorconfig
   create .gitattributes
   create .gitignore
   create generators/app/index.js
   create generators/app/templates/dummyfile.txt
   create __tests__/app.js
   create .travis.yml
   create .eslintignore
   create LICENSE
I'm all done. Running npm install for you to install the required dependencies.
If this fails, try running the command yourself.

在执行generator-generator这个生成器的过程中，会询问项目名称、作者、使用协议、主页地址等等信息，依次选择填空即可。

注意：按照约定，Yeoman generator的名字必须以“generator-”的前缀开头，这是因为所有的generator其实都是全局安装的node模块，所以Yeoman其实是完全依靠文件系统来对这些生成器进行查找操作的。

当上面的命令执行完毕后，会发现在当前的路径下面生成了generator-wendingding目录，进入到generator-wendingding目录，使用tree命令查看当前目录结构，显示如下：

.
├── LICENSE
├── README.md
├── __tests__
├── generators
├── app
│    ├── index.js
│    └── templates
│        └── dummyfile.txt
├── node_modules
├── package-lock.json
└── package.json

上面目录结构中虽然有很多文件，但我们真正需要关注的应该是generators路径下面的app/index.js文件以及templates目录，其中index文件对应是generators的组装指令部分，templates路径用于存放项目所有的模板文件。

项目模板文件准备

上面这些准备工作完成之后，接下来我们开始着手分析目标项目的文件结构，即我们使用自己创建的这个脚手架来搭建项目，其结构目录应该是怎样的？需要包含哪些文件等等。任何时候，明确知道你的目标，知道自己正在做什么至关重要。

下面试着给出目标项目的文件结构。

.
├── Gruntfile.js
├── bower.json
├── build
├── dist
├── package.json
└── src
    ├── css
    │   └── style.css
    ├── index.html
    ├── js
    │   └── index.js
    ├── libs
    │   └── jquery
    └── template

我们可以看到该项目应该包含bulid、src以及dist三个目录，其中src目录中需要创建名为css、js、libs和template的文件夹，分别用来保存样式文件、脚本文件、依赖的框架以及模板文件等。

除了这些必要的文件外，假设目标项目需要使用bower来进行依赖管理，使用Grunt来进行自动化构建，所以自然还应该拥有Gruntfile.js、bower.json以及package.json文件。

假设目标项目中一定会使用到jQuery框架，可能会使用到bootstrap框架。

现在我们可以开始分析生成器中应该包含项目模板文件了，也就是在generators/templates路径中应该包含哪些文件。

固定文件

index.js和 style.css创建空文件即可。

Gruntfile.js文件因为内容固定不变，所以选择直接从旧项目中拷贝。

.jshintrc文件用于js文件语法检查，内容也是固定不变的。

.bowerrc文件用于重置Bower下载包的安装路径，内容为{"directory": "src/libs/"}

灵活文件

package.json文件中项目名称、作者以及开源协议等需要用户配置

bower.json文件的项目名称、作者、开源协议以及依赖框架等需要用户配置

可选文件

bootstrap框架相关的部分为可选文件，需要根据用户配置进行处理。

依赖文件

jQuery框架相关的部分为依赖文件，在组装指令部分通过在代码中调用方法来下载和安装。

根据上面的分析，我们在generators/templates准备了多个模板文件，下面列出文件结构以及主要文件的具体内容：

.
└── app
    ├── index.js
    └── templates
        ├── Gruntfile.js
        ├── bower.json
        ├── css
        │   └── style.css
        ├── index.html
        ├── js
        │   └── index.js
        └── package.json

package.json文件内容

{
  "name": "<%= appName %>",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "<%= appAuthor %>",
  "license": "<%= appLicense %>",
  "devDependencies": {
    "grunt": "^1.0.2",
    "grunt-contrib-concat": "^1.0.1",
    "grunt-contrib-cssmin": "^2.2.1",
    "grunt-contrib-jshint": "^1.1.0",
    "grunt-contrib-uglify": "^3.3.0",
    "grunt-contrib-watch": "^1.0.0"
  }
}

bower.json文件内容

{
  "name": "<%= appName %>",
  "description": "\"测试使用\"",
  "main": "js/index.js",
  "authors": [
    "<%= appAuthor %>"
  ],
  "license": "<%= appLicense %>",
  "keywords": [
    "generator-wendingding",
    "yeoman-generator"
  ],
  "homepage": "https://github.com/flowerField/generator-wen",
  "ignore": [
    "**/.*",
    "node_modules",
    "bower_components",
    "test",
    "tests"
  ],
  "dependencies": {
    "jquery": "^3.3.1"<% if(isIncludeBootstrap) { %>,
    "bootstrap": "^4.1.1" <% } %>
  }
}

index.html文件内容

<!DOCTYPE html>
<html lang="en" dir="ltr">
  <head>
    <meta charset="utf-8">
    <title><%= appName %></title>
    <link rel="stylesheet" href="css/style.css">
    <script type="text/javascript" src="js/index.js"></script>
  </head>
  <body>

  </body>
</html>

Gruntfile.js文件内容

//包装函数
module.exports = function (grunt) {
    // 项目配置信息
    grunt.config.init({
        pkg:grunt.file.readJSON("package.json"),
        //代码合并
        concat:{
            options:{
                stripBanners:true,
             banner:'/*项目名称：<%=pkg.name%> 项目版本：<%=pkg.version%> 项目的作者：<%=pkg.author%> 更新时间：<%=grunt.template.today("yyyy-mm-dd")%>*/\n'
            },
            target:{
                src:["src/js/*.js"],
                dest:'build/js/index.js'
            }
        },
        //js代码压缩
        uglify:{
            target:{
                src:"build/js/index.js",
                dest:"build/js/index.min.js"
            }
        },
        //css代码压缩
        cssmin:{
            target:{
                src:"src/css/style.css",
                dest:"build/css/style.min.css"
            }
        },
        //js语法检查
        jshint:{
            target:['Gruntfile.js',"dist/js/index.js"],
        },
        //监听 自动构建
        watch:{
            target:{
                files:["src/js/*.js","src/css/*.css"],
                //只要指定路径的文件(js和css)发生了变化，就自动执行tasks中列出的任务
                tasks:["concat","jshint","uglify","cssmin"]
            }
        }
    });
    //通过命令行安装插件（省略...）
    //从node_modules路径加载插件
    grunt.loadNpmTasks("grunt-contrib-concat");
    grunt.loadNpmTasks("grunt-contrib-uglify");
    grunt.loadNpmTasks("grunt-contrib-cssmin");
    grunt.loadNpmTasks("grunt-contrib-jshint");
    grunt.loadNpmTasks("grunt-contrib-watch");
    //注册任务：在执行$ grunt命令的时候依次执行代码的合并|检查|压缩等任务并开启监听
    grunt.registerTask("default",["concat","jshint","uglify","cssmin","watch"]);
};

注意：上面部分文件中很多地方使用模板语法来传递参数，Yeoman所用的模板语言是EJS，具体用法请参考[EJS官网](http://www.embeddedjs.com/)

组装指令

处理完上面这些工作之后，接下来就是最最核心的部分了，我们需要在app/index.js文件中编写组装指令，这部分代码控制着这个生成器应该怎么执行，包括交互式配置的具体内容、如何复制文件以及框架依赖和Node模块下载等内容。

下面列出该示例中的index.js文件内容

'use strict';
const Generator = require('yeoman-generator');
const chalk = require('chalk');
const yosay = require('yosay');
const mkdirp = require('mkdirp');

module.exports = class extends Generator {
  prompting() {
    this.log(
      // yosay(`Welcome to the transcendent ${chalk.red('generator-wen')} generator!`)
      yosay(`欢迎使用\n${chalk.red('generator-wen')} !\n Author：文顶顶`)
    );

    const prompts = [
      {
        type    : 'input',
        name    : 'appName',
        message : '请输入项目名称:',
        default : this.appname        //appname是内置对象，代表工程名，这里就是ys
     },
     {
       type    : 'input',
       name    : 'appAuthor',
       message : '请输入作者姓名:',
       default : '文顶顶'
    },
    {
        type: 'list',
        name: 'appLicense',
        message: '请选择使用的license:',
        choices: ['MIT', 'ISC', 'Apache-2.0', 'AGPL-3.0']
      },
      {
        type    : 'confirm',
        name    : 'isIncludeBootstrap',
        message : '是否需要使用bootStrap框架？',
        default : false
     },

    ];

    return this.prompt(prompts).then(props => {
      // To access props later use this.props.someAnswer;
      this.props = props;
    });
  }

  writing() {
    mkdirp("build");
    mkdirp("dist");
    mkdirp("src/template");

    this.fs.copyTpl(
      this.templatePath('index.html'),
      this.destinationPath('src/index.html'),
      {appName: this.props.appName}
    );

    this.fs.copy(
      this.templatePath('css/style.css'),
      this.destinationPath('src/css/style.css')
    );

    this.fs.copy(
      this.templatePath('js/index.js'),
      this.destinationPath('src/js/index.js')
    );

    this.fs.copy(
      this.templatePath('.bowerrc'),
      this.destinationPath('.bowerrc')
    );

    this.fs.copy(
      this.templatePath('Gruntfile.js'),
      this.destinationPath('Gruntfile.js')
    );

    this.fs.copy(
      this.templatePath('.jshintrc'),
      this.destinationPath('.jshintrc')
    );

    this.fs.copyTpl(
      this.templatePath('package.json'),
      this.destinationPath('package.json'),
       {appName: this.props.appName,appAuthor:this.props.appAuthor,appLicense:this.props.appLicense}
    );

    this.fs.copyTpl(
      this.templatePath('bower.json'),
      this.destinationPath('bower.json'),
       {appName: this.props.appName,appAuthor:this.props.appAuthor,appLicense:this.props.appLicense,isIncludeBootstrap:this.props.isIncludeBootstrap}
    );
  }

  install() {
    //this.installDependencies();
    this.bowerInstall();
  }
};

上面的代码大概由三部分组成，第一部分为prompting函数用来处理安装提示，第二部分为writing函数用来设置模板文件的复制操作，第三部分为install函数用来处理框架依赖和node包的安装。

generator的发布和测试

项目模板文件和组装指令都准备好了后，我们就可以发布自己的generator了，可以先通过$ npm link命令以软连接的方式生成一个全局的npm包，测试使用。

具体的执行细节如下

wendingding:generator-wendingding wendingding$ npm link
up to date in 3.897s
/usr/local/lib/node_modules/generator-wendingding -> /Users/文顶顶/Desktop/Yeoman/YeomanTest/generator-wendingding
wendingding:generator-wendingding wendingding$

测试·使用自己创建的generator来生成初始化项目

随便找个目录新建文件夹，使用$ yo wendingding命令即可完成项目的初始化工作。

wendingding:YeomanTest wendingding$ mkdir Demo
wendingding:YeomanTest wendingding$ cd Demo/
wendingding:Demo wendingding$ yo wendingding

     _-----_     ╭──────────────────────────╮
    |       |    │         欢迎使用           │
    |--(o)--|    │      generator-wen !      │
   `---------´   │      Author：文顶顶        │
    ( _´U`_ )    ╰──────────────────────────╯
    /___A___\   /
     |  ~  |
   __'.___.'__
 ´   `  |° ´ Y `

? 请输入项目名称: Demo
? 请输入作者姓名: 文顶顶
? 请选择使用的license: Apache-2.0
? 是否需要使用bootStrap框架？ Yes
   create bower.json
   create package.json
   create src/index.html
   create src/css/style.css
   create src/js/index.js
   create .bowerrc
   create Gruntfile.js
   create .jshintrc
bower invalid-meta  for:/Users/文顶顶/Desktop/Yeoman/YeomanTest/Demo/bower.json
bower invalid-meta  The "name" is recommended to be lowercase, can contain digits, dots, dashes
bower cached        https://github.com/jquery/jquery-dist.git#3.3.1
bower validate      3.3.1 against https://github.com/jquery/jquery-dist.git#^3.3.1
bower cached        https://github.com/twbs/bootstrap.git#4.1.1
bower validate      4.1.1 against https://github.com/twbs/bootstrap.git#^4.1.1
bower install       jquery#3.3.1
bower install       bootstrap#4.1.1

jquery#3.3.1 src/libs/jquery

bootstrap#4.1.1 src/libs/bootstrap
wendingding:Demo wendingding$ tree -L 3
.
├── Gruntfile.js
├── bower.json
├── build
├── dist
├── package.json
└── src
    ├── css
    │   └── style.css
    ├── index.html
    ├── js
    │   └── index.js
    ├── libs
    │   ├── bootstrap
    │   └── jquery
    └── template

9 directories, 6 files

如果需要把这个生成器发布到社区，可以参考官网的说明。