Webpack Ruleset loader过滤器

[CommanderXL]

Ruleset loader过滤器

Ruleset 类主要作用于过滤加载 module 时符合匹配条件规则的 loader。Ruleset 在内部会有一个默认的 module.defaultRules 配置，在真正加载 module 之前会和你在 webpack config 配置文件当中的自定义 module.rules 进行合并，然后转化成对应的匹配过滤器。

webpack 文档上对于 Ruleset 的说明太过于抽象，在文档上提到的条件，结果和嵌套规则并没有做很好的说明。本文会结合示例，源码来解释下这3点具体是指哪些内容。

首先我们来看下 module.defaultRules 配置是在 WebpackOptionsDefaulter.js 当中完成的，得到的结果是：

[ { type: 'javascript/auto', resolve: {} },
  { test: /\.mjs$/i,
    type: 'javascript/esm',
    resolve: { mainFields: [Array] } },
  { test: /\.json$/i, type: 'json' },
  { test: /\.wasm$/i, type: 'webassembly/experimental' }]

这个数组最终会和你 webpack config 配置的 module.rules 进行 concat 合并成一个数组，并传入 Ruleset 的构造函数当中，得到 ruleset 实例：

// NormalModuleFactory.js
class NormalModuleFactory {
  ...
  this.ruleset = new Ruleset(options.defaultRules.concat(options.rules))
  ...
}

接下来我们来看下 Ruleset 构造函数里面到底进行了哪些处理：

class Ruleset {
  constructor(rules) {
    this.references = Object.create(null);
        this.rules = RuleSet.normalizeRules(rules, this.references, "ref-");
  }

  // 序列化 rules 配置选项
    static normalizeRules(rules, refs, ident) {
        if (Array.isArray(rules)) {
            return rules.map((rule, idx) => {
                return RuleSet.normalizeRule(rule, refs, `${ident}-${idx}`);
            });
        } else if (rules) {
            return [RuleSet.normalizeRule(rules, refs, ident)];
        } else {
            return [];
        }
  }

  static normalizeRule(rule, refs, ident) {
    ...
  }
}

我们可以看到构造函数里面定义了 normalizeRules 静态方法，它的作用实际就是对传入的 rules 配置进行序列化(格式化)的处理为统一的格式，其中就包含了对于条件的序列化。在 module.defaultRules 和 webpack.config 里面有关 rules 的配置你可以理解为最原始的条件配置，这些配置通过 Ruleset 内部提供的方法格式化收敛为统一的过滤条件，最终匹配 loaders 时就是使用格式化过后的这些过滤条件。

有关 webpack.config 里面暴露出来供开发者使用的(常用的)条件配置主要有：

• test
• include
• exclude
• resouce
• resourceQuery

test/include/exclude 这3项我们平时使用较多的配置实际上是和 resouce 配置是等价的，2者只能存在其一，不能混用。其中test/include 用以匹配满足条件的 loader，而 exclude 用以排除满足条件 loader，resouceQuery 主要是用以在路径中带 query 参数的匹配规则，例如你的模块依赖路径为 xxx/xxx?type=demo, resolveQuery 的配置为 /type=demo/，那么便会符合对应的匹配规则。这些字段支持的数据类型有：

• string
• function
• RegExp
• Array(数组内部的元素类型为前3者之一)
• Object(仅支持 or/include/test/add/not/exclude字段)

接下来我们看下 Ruleset 内部是如何将原始的配置进行格式的，以及最终格式化所输出的内容。

class RuleSet {
  ...
  static normalizeRule(rule, refs, ident) {
    ...
    if (rule.test || rule.include || rule.exclude) {
            condition = {
                test: rule.test,
                include: rule.include,
                exclude: rule.exclude
            };
            try {
                newRule.resource = RuleSet.normalizeCondition(condition);
            } catch (error) {
                throw new Error(RuleSet.buildErrorMessage(condition, error));
            }
    }

    if (rule.resource) {
            checkResourceSource("resource");
            try {
                newRule.resource = RuleSet.normalizeCondition(rule.resource);
            } catch (error) {
                throw new Error(RuleSet.buildErrorMessage(rule.resource, error));
            }
    }

    if (rule.resourceQuery) {
            try {
                newRule.resourceQuery = RuleSet.normalizeCondition(rule.resourceQuery);
            } catch (error) {
                throw new Error(RuleSet.buildErrorMessage(rule.resourceQuery, error));
            }
    }

    if (rule.issuer) {
            try {
                newRule.issuer = RuleSet.normalizeCondition(rule.issuer);
            } catch (error) {
                throw new Error(RuleSet.buildErrorMessage(rule.issuer, error));
            }
        }
    ...
  }

  static normalizeCondition(condition) {
    if (!condition) throw new Error("Expected condition but got falsy value");
    // 如果配置数据类型为 string，那么直接使用 indexOf 作为路径匹配规则
        if (typeof condition === "string") {
            return str => str.indexOf(condition) === 0;
    }
    // 如果为 function 函数，那么使用这个开发者自己定义的 function 作为路径匹配规则
        if (typeof condition === "function") {
            return condition;
    }
    // 如果为正则表达式
        if (condition instanceof RegExp) {
            return condition.test.bind(condition);
    }
    // 如果为一个数组，那么分别处理数组当中的每一个元素，最终返回一个由 orMatcher 包装的函数，就是只要其中一个元素的匹配条件，那么就返回为 true
        if (Array.isArray(condition)) {
            const items = condition.map(c => RuleSet.normalizeCondition(c));
            return orMatcher(items);
        }
        if (typeof condition !== "object") {
            throw Error(
                "Unexcepted " +
                    typeof condition +
                    " when condition was expected (" +
                    condition +
                    ")"
            );
        }

        // 匹配规则数组
    const matchers = [];
    // 如果为对象类型，那么最终会用一个 matchers 数组将这些条件收集起来
        Object.keys(condition).forEach(key => {
            const value = condition[key];
            switch (key) {
                case "or":
                case "include":
                case "test":
                    if (value) matchers.push(RuleSet.normalizeCondition(value));
                    break;
                case "and":
                    if (value) {
                        const items = value.map(c => RuleSet.normalizeCondition(c));
                        matchers.push(andMatcher(items)); // andMatcher 必须在 items 里面都匹配
                    }
                    break;
                case "not":
                case "exclude":
                    if (value) {
                        const matcher = RuleSet.normalizeCondition(value);
                        matchers.push(notMatcher(matcher)); // notMatcher 必须在 matcher 之外
                    }
                    break;
                default:
                    throw new Error("Unexcepted property " + key + " in condition");
            }
        });
        if (matchers.length === 0) {
            throw new Error("Excepted condition but got " + condition);
        }
        if (matchers.length === 1) {
            return matchers[0];
        }
        return andMatcher(matchers);
  }
  ...
}

在 normalizeCondition 函数执行后始终返回的是一个函数，这个函数的用途就是接受模块的路径，然后使用你所定义的匹配使用去看是否满足对应的要求，如果满足那么会使用这个 loader，如果不满足那么便会过滤掉。

以上是对于 rule condition 条件的解释，接下来看下 rule 结果的相关解释。简单来讲就是我们使用 condition 来匹配我们需要的 rule 结果，condition 和 rule 是一一对应的关系，rule 结果就是最终我们需要加载这个模块需要使用的所有相关 loader 数组。我们首先来看下哪些配置字段和 rule 结果有强相关性：

• loader
• loaders(Webpack 4.x 已废弃)
• use

这几个对应的配置写法有：

{
  module: {
    rules: [
      {
        test: /.vue$/,
        loader: 'vue-loader'
      },
      {
        test: /.scss$/,
        use: [
          'vue-style-loader',
          'css-loader',
          {
            loader: 'sass-loader',
            options: {
              data: '$color: red;'
            }
          }
        ]
      }
    ]
  }
}

在 RuleSet 构造函数内部使用静态方法 normalizeUse 方法来输出最终和 condition 对应的 rule 结果：

class RuleSet {
  static normalizeUse(use, ident) {
        if (typeof use === "function") {
            return data => RuleSet.normalizeUse(use(data), ident);
        }
        if (Array.isArray(use)) {
            return use
                .map((item, idx) => RuleSet.normalizeUse(item, `${ident}-${idx}`))
                .reduce((arr, items) => arr.concat(items), []);
        }
        return [RuleSet.normalizeUseItem(use, ident)];
    }

    static normalizeUseItemString(useItemString) {
        const idx = useItemString.indexOf("?");
        if (idx >= 0) {
            return {
                loader: useItemString.substr(0, idx),
                options: useItemString.substr(idx + 1)
            };
        }
        return {
            loader: useItemString,
            options: undefined
        };
  }

  static normalizeUseItem(item, ident) {
        if (typeof item === "string") {
            return RuleSet.normalizeUseItemString(item);
        }

        const newItem = {};

        if (item.options && item.query) {
            throw new Error("Provided options and query in use");
        }

        if (!item.loader) {
            throw new Error("No loader specified");
        }

        newItem.options = item.options || item.query;

        if (typeof newItem.options === "object" && newItem.options) {
            if (newItem.options.ident) {
                newItem.ident = newItem.options.ident;
            } else {
                newItem.ident = ident;
            }
        }

        const keys = Object.keys(item).filter(function(key) {
            return !["options", "query"].includes(key);
        });

        for (const key of keys) {
            newItem[key] = item[key];
        }

        return newItem;
    }
}

经过 normalizeUse 函数的格式化处理，最终的 rule 结果为一个数组，内部的 object 元素都包含 loader/options 等字段：

[{
  loader: 'xxx-loader',
  options: {
    data: '$color red'
  }
}, {
  lodaer: 'xxx-loader',
  options: 'a=b&c=d'
}]

经过 RuleSet 内部的格式化的处理，最终输出的 rules 为：

rules: [
  {
    resource: [Function],
    resourceQuery: [Function],
    use: [{
      loader: 'xxx-loader',
      options: {
        data: '$color red'
      }
    }]
  },
  {
    resource: [Function],
    resourceQuery: [Function],
    use: [{
      loader: 'xxx-loader',
      options: 'a=b&c=d'
    }]
  }
]

以上便是 RuleSet 构造函数实例化以及格式化 condition 及 rule 结果的过程。这个过程结束后，便可利用 ruleset 实例上的 exec 进行相关的匹配过滤工作。

在 webpack 正常的工作流当中，在加载对应的 module 之前首先需要知道加载这个模块具体使用哪些 loader，便是调用 ruleset 实例上的 exec 去过滤对应的 loader。

具体的使用方法为：

// NormalModuleFactory.js

this.ruleset.exec({
  resource: resourcePath,  // module 的路径
  realResource:
    matchResource !== undefined
      ? resource.replace(/\?.*/, "")
      : resourcePath,
  resourceQuery,  // module 路径上所带的 query 参数
  issuer: contextInfo.issuer,  // 这个模块的发布者
  compiler: contextInfo.compiler // 这个模块所使用的编译器选项
})

接下来我们看下 exec 方法内部具体的实现：

class RuleSet {
  ...
  exec(data) {
        const result = [];
        this._run(
            data,
            {
                rules: this.rules // 根据内置的 rules 和传入的 module.rule 合并后生成的 rules
            },
            result
        );
        return result;
  }

  _run(data, rule, result) {
        // test conditions
        // 一系列的匹配规则，只有通过这些匹配规则，才会将对应的 loaders 加入到数组中
        if (rule.resource && !data.resource) return false;
        if (rule.realResource && !data.realResource) return false;
        if (rule.resourceQuery && !data.resourceQuery) return false;
        if (rule.compiler && !data.compiler) return false;
        if (rule.issuer && !data.issuer) return false;
        if (rule.resource && !rule.resource(data.resource)) return false; // resource 匹配规则
        if (rule.realResource && !rule.realResource(data.realResource))
            return false;
        if (data.issuer && rule.issuer && !rule.issuer(data.issuer)) return false;
        if (
            data.resourceQuery &&
            rule.resourceQuery &&
            !rule.resourceQuery(data.resourceQuery) // resourceQuery 的匹配规则
        ) {
            return false;
        }
        if (data.compiler && rule.compiler && !rule.compiler(data.compiler)) {
            return false;
        }

        // apply
        const keys = Object.keys(rule).filter(key => {
            return ![
                "resource",
                "realResource",
                "resourceQuery",
                "compiler",
                "issuer",
                "rules",
                "oneOf",
                "use",
                "enforce"
            ].includes(key);
        });
        for (const key of keys) {
            result.push({
                type: key,
                value: rule[key]
            });
        }

        if (rule.use) {
            const process = use => {
                if (typeof use === "function") {
                    process(use(data));
                } else if (Array.isArray(use)) {
                    use.forEach(process);
                } else {
                    result.push({
                        type: "use",
                        value: use,
                        enforce: rule.enforce
                    });
                }
            };
            process(rule.use);
        }

        if (rule.rules) {
            for (let i = 0; i < rule.rules.length; i++) {
                this._run(data, rule.rules[i], result);
            }
        }

        if (rule.oneOf) {
            for (let i = 0; i < rule.oneOf.length; i++) {
                if (this._run(data, rule.oneOf[i], result)) break;
            }
        }

        return true;
    }
}

过滤过程的实现应该是非常清晰的，就是递归的根据 ruleset 在实例化的时候创建的各种过滤条件(对应的不同的 Function)，以及传入的不同字段(resouce/realsource/compiler/issuer/compiler)，最终输出的数据格式即 webpack 文档上所说的结果为：

[{
  type: 'use',
  value: {
    loader: 'vue-style-loader',
    options: {}
  },
  enforce: undefined // 可选值还有 pre/post  分别为 pre-loader 和 post-loader
}, {
  type: 'use',
  value: {
    loader: 'css-loader',
    options: {}
  },
  enforce: undefined
}, {
  type: 'use',
  value: {
    loader: 'sass-loader',
    options: {
      data: '$color red'
    }
  },
  enforce: undefined 
}]

总结

RuleSet 的使用主要包含了：

1. RuleSet 的实例化过程，即根据 webpack.module.rules 的配置及 webpack 内部的 rules 配置，将不同字段的不同数据类型，例如 string/RegExp/Function 等都转化为对应的过滤函数，因为 webpack 的 rules 为了满足不同的配置需求，设计的还是相对来说很灵活的，对于开发者而且可以使用灵活多样的配置形式，但是收敛到 ruleset 内部便统一转化为过滤函数的形式；

2. exec 方法过滤阶段便是根据传入的不同的配置规则来递归的进行匹配，最终输出被匹配到的 loaders 数组。

[eret9616]

感谢楼主好文！ 有个小建议就是Condition，Result，Nested rules专有名词直接用英文更好，有时候读着读着好久才反应过来