Grunt学习笔记【3】---- filter使用方式和实现原理详解

本文主要讲配置任务中的filter，包括使用默认fs.Stats方法名和自定义过滤函数，以及filter的实现原理。

通过设置filter属性可以实现一些特殊处理逻辑。例如：要清理某个文件夹下的所有空文件夹，这时使用clean任务时，需要判断该文件夹下的哪些是文件，哪些是文件夹，只对空文件执行clean任务。

具体使用方法分为如下两种：

一 使用fs.Stats方法作为过滤函数

fs.stats是NodeJS的一个类，上边提供了很多对文件判断的方法，具体可以参考这里。

如下将filter设置为'isFile'时，如果发现当前文件不是文件时，就不进行clean处理。

grunt.initConfig({
  clean: {
    foo: {
      src: ['tmp/**/*'],
      filter: 'isFile',
    },
  },
});

二 自定义过滤函数

自定义过滤函数，如果过滤函数返回true，就对当前文件进行处理；返回值是false时，就不处理当前文件。

下边示例是清理tmp下边所有的空文件夹：

grunt.initConfig({
  clean: {
    foo: {
      src: ['tmp/**/*'],
      filter: function(filepath) {
        return (grunt.file.isDir(filepath) && require('fs').readdirSync(filepath).length === 0);
      },
    },
  },
});

 三 filter实现原理

在分析filter的实现原理之前，首先给出一个使用filter时的注意事项：

filter配置属性只能用于通过grunt.task.registerMultiTask()方法注册的复合任务。

如果使用的某个Grunt插件注册任务时，没有使用grunt.task.registerMultiTask 注册任务，则配置filter是不生效的。

而大多数的contrib任务，包括 jshint task、concat task 和 uglify task 都是复合任务。

下边说明filter在Grunt的实现原理：

通过grunt.task.registerMultiTask()方法注册复合任务时，会拿到配置信息中对应任务的配置对象，对配置对象中的filter属性进行判断，如果设置了filter，就对要处理的文件进行filter过滤，根据过滤结果将新的文件列表存到files属性中，各个任务函数中拿到的files属性实际上是已经过滤后的复合filter要求的文件。

下边以上边的clean任务为例，分析几个关键点的源码：

3.1 首先分析clean的源码：

在npm安装包node_module目录下grunt-contrib-clean中找到clean.js文件，该文件实际就是一个标准的nodeJS模块文件，找到其中通过grunt.registerMultiTask()方法注册clean任务代码，在第三个参数的处理函数中，我们可以看到这里实际是对this.filesSrc进行的处理，下边是部分代码：

module.exports = function(grunt) {

    function clean(filepath, options, done) {
        // 省略的代码...
    }

    grunt.registerMultiTask('clean', 'Clean files and folders.', function() {
        // 省略的代码...

        // 要处理的文件
        var files = this.filesSrc;
        
        async.eachSeries(files, function (filepath, cb) {
            clean(filepath, options, cb);
        }, function (err) {
            grunt.log.ok(files.length + ' ' + grunt.util.pluralize(files.length, 'path/paths') + ' cleaned.');
            done(err);
        });
    });

};

3.2 接下来分析task.normalizeMultiTaskFiles()函数的源码：

在该函数源码中，我们要找到传给上边clean函数的this.filesSrc来自哪里。

在grunt的npm源码包中，找到task.js，其中定义了task.registerMultiTask函数，从该函数中我们可以发现this.filesSrc实际是对this.files.src进行处理后得到的。

而this.files又是通过task.normalizeMultiTaskFiles(this.data, target)得到的，其中this.data和target就是源自于Grunt的配置信息。

在最后fn.apply(this, this.args)可以知道，这个fn实际就是注册任务时的回调函数。

下边是部分关键代码：

task.registerMultiTask = function(name, info, fn) {
    //  省略的代码...
    
    task.registerTask(name, info, function(target) {
        // 省略的代码...
        
        this.data = grunt.config([name, target]);
        // 获取到files文件
        this.files = task.normalizeMultiTaskFiles(this.data, target);
        // 定义this.filesSrc文件
        Object.defineProperty(this, 'filesSrc', {
            enumerable: true,
            get: function() {
                return grunt.util._(this.files).chain().pluck('src').flatten().uniq().value();
            }.bind(this)
        });
        // 调用任务的回调函数，并将指定this
        return fn.apply(this, this.args);
    });

    //  省略的代码...
};

3.3 分析task.normalizeMultiTaskFiles()源码：

在这个源码中找到this.files.src是如何来的。从源码中可以发现来源于grunt.file.expand(expandOptions, src)函数。

下边是其中部分代码：

task.normalizeMultiTaskFiles = function(data, target) {
    // 省略的代码...
    
    if ('src' in result) {
        Object.defineProperty(result, 'src', {
            enumerable: true,
            get: function fn() {
                var src;
                if (!('result' in fn)) {
                    src = obj.src;
                    // If src is an array, flatten it. Otherwise, make it into an array.
                    src = Array.isArray(src) ? grunt.util._.flatten(src) : [src];
                    // Expand src files, memoizing result.
                    fn.result = grunt.file.expand(expandOptions, src);
                }
                return fn.result;
            }
        });
    }

    // 省略的代码...

    return result;
};

3.4 分析grunt.file.expand源码：

在grunt的npm包中，找到file.js文件，在里边可以找到file.expand函数的定义，在该函数的定义中我们终于可以看到对filter的判断和处理，可以看到对filter是函数和字符时不同的处理。

下边是部分关键代码：

file.expand = function() {
    // 省略的代码...
    
    if (options.filter) {
        matches = matches.filter(function(filepath) {
            filepath = path.join(options.cwd || '', filepath);
            try {
                if (typeof options.filter === 'function') {
                    return options.filter(filepath);
                } else {
                    // If the file is of the right type and exists, this should work.
                    return fs.statSync(filepath)[options.filter]();
                }
            } catch(e) {
                // Otherwise, it's probably not the right type.
                return false;
            }
        });
    }
    return matches;
};

 说明：本人实际分析源码过程是倒着来的，首先在grunt包中搜到filter判断的地方，然后一步一步查找方法的调用链。

参考资料&内容来源：

Grunt官网：https://www.gruntjs.net/configuring-tasks