6. 模块构建之loader执行：loader-runner@2.4.0源码分析

// Compilation.js
buildModule(module, optional, origin, dependencies, thisCallback){
    module.build(..., error => {/*...*/})
}

// NormalModule.js
const { getContext, runLoaders } = require("loader-runner"); // 调用的loader-runner包

build(options, compilation, resolver, fs, callback) {
    return this.doBuild(..., fs, err => {/*...*/})
}

doBuild(options, compilation, resolver, fs, callback) {
    // 创建loader的执行上下文
    const loaderContext = this.createLoaderContext(/*...*/);

    runLoaders({
        resource: this.resource,
        loaders: this.loaders, // 传入loaders ，NomalModleFactory new NormalModule()传入的
        context: loaderContext,
        readResource: fs.readFile.bind(fs)
    }, (err, result) => { /*...*/ })
}

// read options
var resource = options.resource || ""; // 资源信息，将上面截图
var loaders = options.loaders || [];

// 来自NormalModule创建的context，所以每个module的执行loader的loaderContext是独立的
// 但是该module的所有loaders共享这个上线文
var loaderContext = options.context || {}; 
var readResource = options.readResource || readFile; // 文件读取方法

// 拆分resource为path和query单独存储
var splittedResource = resource && splitQuery(resource);
var resourcePath = splittedResource ? splittedResource[0] : undefined;
var resourceQuery = splittedResource ? splittedResource[1] : undefined;
var contextDirectory = resourcePath ? dirname(resourcePath) : null; // 资源所在目录

// execution state
var requestCacheable = true; // 是否要缓存当前模块
var fileDependencies = []; // 依赖的文件
var contextDependencies = []; // 依赖的目录

loaders = loaders.map(createLoaderObject);

loaderContext.context = contextDirectory;
loaderContext.loaderIndex = 0; // 用于记录当前执行的loader的索引，查找当前执行的loader
loaderContext.loaders = loaders; // 保存这次所有的loaders
loaderContext.resourcePath = resourcePath; 
loaderContext.resourceQuery = resourceQuery;
loaderContext.async = null; // 异步loader标识
loaderContext.callback = null; // 异步loader回调
loaderContext.cacheable = function cacheable(flag) { // 缓存
    if(flag === false) {
        requestCacheable = false;
    }
};

resourcePath: '/Users/.../src/simple/a.js'
resourceQuery: '?c=d'

// -------- 文件依赖、目录依赖 添加、获取、清理----------
// NormalModule保存了fileDependencies、contextDependencies，猜测变更时使用？
// 当前文件的processResource方法有用到
loaderContext.dependency = loaderContext.addDependency = ...
loaderContext.addContextDependency = //...
loaderContext.getDependencies = //...;
loaderContext.getContextDependencies = //...
loaderContext.clearDependencies = //...

// 下面的xxx: request、remainingRequest、currentRequest、previousRequest、query、data
Object.defineProperty(loaderContext, `${xxx}`, ...);

// finish loader context
// 冻结，不让扩展loaderContext
if(Object.preventExtensions) {
    Object.preventExtensions(loaderContext);
}

// loaderContext.request
/Users/.../src/simple/custom-loaders/custom-post-loader.js!/Users/.../src/simple/custom-loaders/custom-inline-loader.js??share-opts!/Users/.../src/simple/custom-loaders/custom-normal-loader.js??share-opts!/Users/.../src/simple/custom-loaders/custom-pre-loader.js!/Users/.../src/simple/a.js?c=d

{ a: 'b' } // options

loaders = loaders.map(createLoaderObject); 
// createLoaderObject返回一个对象包含以下属性用于记录loader执行是的一些状态
{
   path: null,  // loader路径，通过Object.defineProperty定义request属性，然后 obj.request = loader;
   query: null, // 如果loader设置了options则返回options，否则返回laoder的query即‘?’及其后面的字符串
   options: null, // 定义loader可以是字符串，也可以是对象，对象的化可以提供该选项
   ident: null,   // 标识符，可以通过该标志查找loader
   normal: null,  // normal类型的loader - 函数
   pitch: null,   // pitch类型的loader - 函数
   raw: null,     // 是否返回二进制资源
   data: null,    // loader间共享的数据
   pitchExecuted: false, // 标识pitch类型的loader是否执行过，一个loader可以提供normal,pitch
   normalExecuted: false // 标识normal类型的loader是否执行过 
};

var processOptions = {
    resourceBuffer: null,
    readResource: readResource // 静态资源读取的方法
};

// 开始遍历loader并执行，执行每个loader文件中的module.exports.pitch函数
iteratePitchingLoaders(processOptions, loaderContext, function(err, result) {
    //...
    callback(null, { //返回给 NormalModule.doBuild的回调
        result: result, // result结构: [source, sourceMap, {webpackAST}] 
        resourceBuffer: processOptions.resourceBuffer,
        cacheable: requestCacheable,
        fileDependencies: fileDependencies,
        contextDependencies: contextDependencies
    });
});

// 这里面的执行逻辑都是 pitch函数 的
function iteratePitchingLoaders(options, loaderContext, callback) {
    // 如果pichingLoader已经执行完，则走 processResource
    // processResource 读取资源，然后进入normalLoader的遍历
    if (loaderContext.loaderIndex >= loaderContext.loaders.length)
        return processResource(options, loaderContext, callback);

    // 获取当前loader的属性
    var currentLoaderObject = loaderContext.loaders[loaderContext.loaderIndex];

    // iterate
    // 当前loader的pitchingLoader是否执行过了
    // 已经执行过，索引加一，进入下一个pitchingLoader的执行
    if (currentLoaderObject.pitchExecuted) {
        loaderContext.loaderIndex++;
        return iteratePitchingLoaders(options, loaderContext, callback);
    }

    // load loader module
    // 如果当前pitchingLoader没有执行过，则执行
    // loaderLoader类似于 reuqire或者import，根据loader.path加载loader模块
    // 然后设置currentLoaderObject的pitch、normal，raw等属性
    loadLoader(currentLoaderObject, function (err) {
        //...
        var fn = currentLoaderObject.pitch; // 获取pitchingLoader
        currentLoaderObject.pitchExecuted = true; // 设置当前pitchingLoader执行过的标志
        // 如果不是函数，则进入下一个pichingLoader的执行
        if (!fn) return iteratePitchingLoaders(options, loaderContext, callback);

        // 开始执行loader（支持同步和异步方式调用）
        runSyncOrAsync(fn,
            // 参数同时传递了 remainingRequest、previousRequest，loader.data引用
            loaderContext, [loaderContext.remainingRequest, loaderContext.previousRequest, currentLoaderObject.data = {}],
            function (err) {
                //...

                // **注意**：这里的参数会被传递给normalLoader的入参
                // 应该是字符串或者数组，字符串或者数组的第一个元素当做normalLoader的入参：source
                // 即资源的内容
                // 解释了没有走 processResource 的source 该如何获取的问题
                // 如果所有的pitchLoader都没有返回参数则调用processResource读取，如果任意一个返回
                // 则从返回值获取source，传递给normalLoader
                var args = Array.prototype.slice.call(arguments, 1);

                // 如果你的pitchingLoader返回了结果，则会忽略后面所有的loader（不论是normal还是pitch)
                // 直接从从上一个loader.nomal开始执行
                if (args.length > 0) {
                    loaderContext.loaderIndex--; // 从上一个loader开始，即当前loader.normal不会被执行了
                    // 注意：有传递args给normalLoader
                    iterateNormalLoaders(options, loaderContext, args, callback);
                } else { // 否则继续执行下一个pitchingLoader
                    iteratePitchingLoaders(options, loaderContext, callback);
                }
            }
        );
    });
}

function processResource(options, loaderContext, callback) {
    // set loader index to last loader
    // 从最后一个loader掉头反向执行所有的normalLoader
    loaderContext.loaderIndex = loaderContext.loaders.length - 1;

    var resourcePath = loaderContext.resourcePath;
    if(resourcePath) {
        // 添加文件依赖
        loaderContext.addDependency(resourcePath);
        // 根据资源地址读取文件内容
        options.readResource(resourcePath, function(err, buffer) {
            //...
            options.resourceBuffer = buffer;
            // 进入normalLoader的执行，将资源内容作为参数传递进去
            iterateNormalLoaders(options, loaderContext, [buffer], callback);
        });
    } else {
        // 如果没有文件路径，直接进入loader.normal的执行
        iterateNormalLoaders(options, loaderContext, [null], callback);
    }
}

function iterateNormalLoaders(options, loaderContext, args, callback) {
    if (loaderContext.loaderIndex < 0) // 显然      
        // callback到runLoader方法调用iteratePitchingLoaders的回调
        return callback(null, args);

    var currentLoaderObject = loaderContext.loaders[loaderContext.loaderIndex];

    // iterate
    // 如果当前执行过，则执行下一个normalLoader - 递归
    if (currentLoaderObject.normalExecuted) {
        loaderContext.loaderIndex--;
        return iterateNormalLoaders(options, loaderContext, args, callback);
    }

    var fn = currentLoaderObject.normal;
    currentLoaderObject.normalExecuted = true;
    if (!fn) { // 如果没有提供normalLoader,则进入下一个normalLoader的执行    
        return iterateNormalLoaders(options, loaderContext, args, callback);
    }

    // 将上一个loader返回的source，根据raw值来决定是：string | buffer
    // 当前normalLoaderh会通过暴露一个raw属性来决定传入的source是什么类型
    // 通过图片等静态资源要求是buffer
    convertArgs(args, currentLoaderObject.raw);

    // 开始执行normalLoader
    runSyncOrAsync(fn, loaderContext, args, function (err) {
        if (err) return callback(err);

        // 将当前函数的参数的err移除，取后面所有参数传递给下一个normalLoader
        var args = Array.prototype.slice.call(arguments, 1);
        iterateNormalLoaders(options, loaderContext, args, callback);
    });
}

function runSyncOrAsync(fn, context, args, callback) {
    var isSync = true; // 当前loader是同步的还是异步的
    var isDone = false; // 当前loader是否执行完成
    var isError = false; // internal error
    var reportedError = false;
    context.async = function async() {
        if (isDone) //... 调用该函数时，如果loader已经执行完成则报错
        isSync = false; // 置为异步loader
        return innerCallback; // 返回异步loader需要的回调，可以通过该回调将异步结果返回给下一个loader
    };
    var innerCallback = context.callback = function () { // 异步回调
        if (isDone) //... 如果已经完成，则报错           
        isDone = true; // 异步loader调用函数传递结果，说明该loader执行完成
        isSync = false; // 置为异步的
        try {
            callback.apply(null, arguments); // 调用者的回调
        } catch (e) //...
    };
    try {
        // 注意：同步执行loader
        var result = (function LOADER_EXECUTION() { return fn.apply(context, args); }());
        // 在上面同步执行的过程中，如果没有发生调用 this.async()
        // 则说明这是一个同步loader
        if (isSync) {
            isDone = true; // 同步loader执行完成
            if (result === undefined) return callback();
            if (result && typeof result === "object" && typeof result.then === "function") {
                // 兼容loader返回Promise实现异步，可以提供一个案例
                return result.then(function (r) { callback(null, r); }, callback);
            }
            return callback(null, result);
        }
    } catch (e) // ...
}

// NormalModule.js 
// doBuild()
runLoaders({ /*...*/ }, (err, result) => {
      if (result) {
         this.buildInfo.cacheable = result.cacheable;
         this.buildInfo.fileDependencies = new Set(result.fileDependencies);
         this.buildInfo.contextDependencies = new Set(
            result.contextDependencies
         );
      }
      //...
})