使用 Schema-Utils 对 Webpack Plugin 进行配置项校验的简单用例

本文介绍如何使用 webpack 官方提供的 schema-utils 库。

该库主要用于在 loader 和 plugin 实例化过程中，对传入的参数进行合法性校验。

若配置格式正确，程序正常运行；若格式有误，控制台将输出详细的错误信息，并立即终止脚本执行。

首先通过一个简单用例进行演示：

const { validate } = require("schema-utils");
const schema = {
  "type": "object",
  "properties": {
    "filename": {
      "type": "string",
    }
  },
  "additionalProperties": false
}
const options = { filename: true }
validate(
  schema, // 配置参数的结构描述
  options // 实例化插件时，传入的配置参数
)

此处定义了一个 schema 对象，用于描述配置项的结构：它必须是一个对象，且仅包含 filename 属性，该属性的值必须为字符串类型。

假设 options 为实例化插件时传入的配置项，此处故意传入错误的配置，将 filename 的值设为布尔类型。

此时 validate 方法会抛出错误，提示 filename 应当为字符串类型。

throw new _ValidationError.default(errors, schema, configuration); ^ ValidationError: Invalid configuration object. Object has been initialized using a configuration object that does not match the API schema. - configuration.filename should be a string.

接下来，我们将通过开发一个具体的插件来讲解如何编写配置格式检验代码。

假设我们要开发一个 HelloWorldPlugin 插件，其功能是在打包过程中额外生成一个文件。

该插件需要接收 filename 和 content 两个参数，其中 filename 为必填项，content 为可选参数。

schema.json

首先，我们需要创建一个 schema.json 文件，用于描述配置项的具体结构。

{
  "type": "object",
  "properties": {
    "filename": {
      "description": "生成文件的名称",
      "type": "string",
      "link": "https://cn.bing.com/"
    },
    "content": {
      "description": "文件内容",
      "type": "boolean",
      "link": "https://cn.bing.com/"
    }
  },
  "required": ["filename"],
  "additionalProperties": false
}

描述属性时常用的参数包括：

• type：指定属性的数据类型，例如 string 或 boolean。
• description：对属性的文字描述。当配置类型不匹配时，该描述会被打印出来，向开发者提供关于属性的详细信息。
• link：指向属性详细说明文档的链接，同样会在类型错误时被打印输出。

对于对象类型的属性：

• required 是一个字符串数组，用于指定当前对象中哪些属性是必填的。
• additionalProperties 表示是否允许使用未在模式中显式声明的其他属性名，其默认值为 true。

描述一个 JSON 对象的模式较为复杂，更多用法可参考 JSON Schema 官网的相关文档。

插件中的写法

接下来查看插件类的具体编写方式。

const { validate } = require("schema-utils");
const schema = require('./schema.json')
class HelloWorldPlugin {
  options;
  constructor(options) {
    validate(schema, options);
    // 如果 validate 没有报错，下面的语句就能正确执行
    this.options = options;
  }
  apply() {
    console.log('apply');
  }
}
module.exports = HelloWorldPlugin;

实现非常简单：引入 schema.json 并将其赋值给 schema 对象，然后在构造函数中将 schema 和传入的插件配置一起传入 validate 方法中。

若校验未通过，脚本将终止运行并提供错误信息；若校验通过，则继续执行后续业务逻辑，例如保存配置项。

修改报错时输出的信息

有时，我们希望自定义报错时的提示信息，使其更加详尽和友好。

此时可以使用 validate 方法的第三个可选配置参数，该参数用于定制报错时输出的信息内容。

validate(
  schema,
  options,
  {
    name: "【Hello World 插件】",
    baseDataPath: "配置项",
    postFormatter: (formattedError, error) => {
      // 做一些处理
      return formattedError;
    },
  }
);

这三个参数均为可选配置。

• name：报错信息中显示的插件名称，默认值为字符串 "Object"。
• baseDataPath：默认值为 "configuration"。

这两个参数也可以直接放置在 schema.json 中，只需在最上层的对象增加一个 "title" 属性即可。该属性会以最后一个空格符为分隔符，分别提取 name 和 baseDataPath 的值。

{
  "title": "【Hello World 插件】 配置项"
  "type": "object",
   // ...
}

如果两者同时存在，优先使用 validate 方法传入的配置参数。

• postFormatter 是一个函数，用于修改最终的报错信息。

postFormatter 可以接收即将输出的错误信息字符串 formattedError，对其进行修改后返回，即可打印出定制后的错误信息内容。

另一个 error 参数是一个描述了具体错误信息的对象，例如可以通过 error.keyword 获取当前错误的类型。

默认的输出内容示例如下：

[原图，由程序原样保留，不描述看不到的内容]

添加了上述配置后的输出结果示例如下：

[原图，由程序原样保留，不描述看不到的内容]

总结

schema-utils 是 webpack 官方提供的配置项校验库，能够帮助我们验证传入配置的正确性，并在匹配失败时打印出较为详细的报错信息。

其暴露的 validate 方法接受三个参数：对象描述结构 (schema)、插件配置 (options) 以及报错信息配置 (config)。