技术点介绍
通过这篇文章你可以学到:
前言
console 对象对前端工程师来说是必不可少的 api,开发时我们经常通过它来打印一些信息来调试。但生产环境下 console 有时会引起一些问题。
最近公司内报了一个 bug,console 对象被重写了但是没有把所有的方法都重写,导致了报错,另外考虑到 console 会影响性能,所以最后定的解决方案是把源码中所有的 console 都删掉。
生产环境下删除 console 是没问题的,但是这件事不需要手动去做。在打包过程中,我们会对代码进行压缩,而压缩的工具都提供了删除一些函数的功能,比如 terser 支持 dropconsole 来删除 console.*,也可以通过 purefuncs 来删除某几种 console 的方法。
但是这种方案对我们是不适用的,因为我们既有 react 的项目又有 react-native 的项目,react-native 并不会用 webpack 打包,也就不会用 terser 来压缩。
其实源码到最终代码过程中会经历很多次 ast 的解析,比如 eslint、babel、terser 等,除了 eslint 主要是用来检查 ast,并不会做过多修改,其余的工具都可以来完成修改 ast,删除 console 这件事情。terser 不可以用,那么我们可以考虑用 babel 来做。
而且,我们只是希望在生产环境下删除 console,在开发环境下 console 还是很有用的,如果能扩展一下 console,让它功能更强大,比如支持颜色的打印,支持文件和代码行数的提示就好了。
于是我们就开发了本文介绍的这个插件: babel-plugin-console-transform。
安装
npm install --save-dev babel-plugin-console-transform
复制代码
演示
先看下效果再讲实现。
比如源码是这样的:
生产环境下转换后的代码:
开发环境下转换后的代码:
运行效果:
生产环境删除了 console,开发环境扩展了一些方法,并且添加了代码行数和颜色等。
接下来是功能的细节还有实现思路。
功能
按照需求,这个插件需要在不同的环境做不同的处理,生产环境可以删除 console,开发环境扩展 console。
生产环境删除 console 并不是全部删除,还需要支持删除指定 name 的方法,比如 log、warn 等,因为有时 console.error 是有用的。而且有的时候根据方法名还不能确定能不能删除,要根据打印的内容来确定是不是要删。
开发环境扩展 console 要求不改变原生的 api,扩展一些方法,这些方法会被转换成原生 api,但是会额外添加一些信息,比如添加代码文件和行数的信息,添加一些颜色的样式信息等。
于是 console-transform 这个插件就有了这样的参数。
{
env: 'production',
removeMethods: ['log', '*g*', (args) => args.includes('xxxx')],
additionalStyleMethods: {
success: 'padding:10px; color:#fff;background:green;',
danger: 'padding:20px; background:red;font-size:30px; color:#fff;'
}
}
复制代码
其中 env 是指定环境的,可以通过 process.env.NODE_ENV 来设置。
removeMethods 是在生产环境下要删除的方法,可以传一个 name,支持 glob,也就是 *g*是删除所有名字包含 g 的方法;而且可以传一个函数,函数的参数是 console.xxx 的所有参数,插件会根据这个函数的返回值来决定是不是删除该 console.xxx。多个条件的时候,只要有一个生效,就会删。
additionalStyleMethods 里面可以写一些扩展的方法,比如 succes、danger,分别定义了他们的样式。其实插件本身提供了 red、green、orange、blue、bgRed、bgOrange、bgGreen、bgBlue 方法,通过这个参数可以自定义,开发环境 console 可以随意的扩展。
实现
接下来是重头戏,实现思路了。
首先介绍下用到的技术,代码是用 typescript 写的,实现功能是基于 @babel/core,@babel/types,测试代码使用 ts-mocha、chai 写的,代码的 lint 用的 eslint、prettier。
主要逻辑
babel 会把代码转成 ast,插件里可以对对 ast 做修改,然后输出的代码就是转换后的。babel 的插件需要是一个返回插件信息的函数。
如下, 参数是 babelCore 的 api,里面有很多工具,我们这里只用到了 types 来生成一些 ast 的节点。返回值是一个 PluginObj 类型的对象。
import BabelCore, { PluginObj } from '@babel/core';
export default function({
types,
}: typeof BabelCore): PluginObj<ConsoleTransformState> {
return {
name: 'console-transform',
visitor: {...}
}
}
复制代码
其中 ConsoleTransformState 里面是我们要指定的类型,这是在后面对 ast 处理时需要拿到参数和文件信息时用的。
export interface PluginOptions {
env: string;
removeMethods?: Array<string | Function>;
additionalStyleMethods?: { [key: string]: string };
}
export interface ConsoleTransformState {
opts: PluginOptions;
file: any;
}
复制代码
PluginOptions 是 options 的类型,env 是必须,其余两个可选,removeMethods 是一个值为 string 或 Function 的数组,additionalStyleMethods 是一个值为 string 的对象。这都是我们讨论需求时确定的。(其中 file 是获取代码行列数用的,我没找到它的类型,就用了 any。)
返回的插件信息对象有一个 visitor 属性,可以声明对一些节点的处理方式,我们需要处理的是 CallExpression 节点。(关于代码对应的 ast 是什么样的,可以用 astexplorer 这个工具看)。
{
CallExpression(path, { opts, file }) {
validateSchema(schema, opts);
const { env, removeMethods, additionalStyleMethods } = opts;
const callee = path.get('callee');
if (
callee.node.type === 'MemberExpression' &&
(callee.node.object as any).name === 'console'
) {
...
}
},
}
复制代码
这个方法就会在处理到 CallExpression 类型的节点时被调用,参数 path 可以拿到一些节点的信息,通过 path.get('callee')拿到调用信息,然后通过 node.type 过滤出 console.xxx() 而不是 xxx()类型的函数调用,也就是 MemberExpression 类型,再通过 callee.node.object 过滤出 console 的方法。
production 下删除 console
接下来就是实现主要功能的时候了。
const methodName = callee.node.property.name as string;
if (env === 'production') {
...
return path.remove();
} else {
const lineNum = path.node.loc.start.line;
const columnNum = path.node.loc.start.column;
...
path.node.arguments.unshift(...);
callee.node.property.name = 'log';
}
复制代码
先看主要逻辑,production 环境下,调用 path.remove(),这样 console 就会被删除,其他环境对 console 的参数(path.node.arguments.)做一些修改,在前面多加一些参数,然后把方法名(callee.node.property.name)改为 log。主要逻辑是这样。
然后细化一下。
production 环境下,当有 removeMethods 参数时,要根据其中的 name 和 funciton 来决定是否删除:
if (removeMethods) {
const args = path.node.arguments.map(
item => (item as any).value,
);
if (isMatch(removeMethods, methodName, args)) {
return path.remove();
}
return;
}
return path.remove();
复制代码
通过把 path.node.arguments 把所有的 args 放到一个数组里,然后来匹配条件。如下,匹配时根据类型是 string 还是 function 决定如何调用。
const isMatch = (
removeMethods: Array<string | Function>,
methodName: string,
args: any[],
): boolean => {
let isRemove = false;
for (let i = 0; i < removeMethods.length; i++) {
if (typeof removeMethods[i] === 'function') {
isRemove = (removeMethods[i] as Function)(args) ? true : isRemove;
} else if (mm([methodName], removeMethods[i] as string).length > 0) {
isRemove = true;
}
}
return isRemove;
};
复制代码
如果是 function 就把参数作为参数传入,根据返回值确定是否删除,如果是字符串,会用 mimimatch 做 glob 的解析,支持**、 {a,b}等语法。
非 production 下扩展 console
当在非 production 环境下,插件会提供一些内置方法。
const styles: { [key: string]: string } = {
red: 'color:red;',
blue: 'color:blue;',
green: 'color:green',
orange: 'color:orange',
bgRed: 'padding: 4px; background:red;',
bgBlue: 'padding: 4px; background:blue;',
bgGreen: 'padding: 4px; background: green',
bgOrange: 'padding: 4px; background: orange',
};
复制代码
结合用户通过 addtionalStyleMethods 扩展的方法,来对代码做转换:
const methodName = callee.node.property.name as string;
const lineNum = path.node.loc.start.line;
const columnNum = path.node.loc.start.column;
const allStyleMethods = {
...styles,
...additionalStyleMethods,
};
if (Object.keys(allStyleMethods).includes(methodName)) {
const ss = path.node.arguments.map(() => '%s').join('');
path.node.arguments.unshift(
types.stringLiteral(`%c${ss}%s`),
types.stringLiteral(allStyleMethods[methodName]),
types.stringLiteral(
`${file.opts.filename.slice(
process.cwd().length,
)} (${lineNum}:${columnNum}):`,
),
);
callee.node.property.name = 'log';
}
复制代码
通过 methodName 判断出要扩展的方法,然后在参数(path.node.arguments)中填入一些额外的信息 ,这里就用到了 @babel/core 提供的 types(其实是封装了 @babel/types 的 api)来生成文本节点了,最后把扩展的方法名都改成 log。
options 的校验
我们逻辑写完了,但是 options 还没有校验,这里可以用 schema-utils 这个工具来校验,通过一个 json 对象来描述解构,然后调用 validate 的 api 来校验。webpack 那么复杂的 options 就是通过这个工具校验的。
schema 如下,对 env、removeMethods、additionalStyleMethods 都是什么格式做了声明。
export default {
type: 'object',
additionalProperties: false,
properties: {
env: {
description:
'set the environment to decide how to handle `console.xxx()` code',
type: 'string',
},
removeMethods: {
description:
'set what method to remove in production environment, default to all',
type: 'array',
items: {
description:
'method name or function to decide whether remove the code',
oneOf: [
{
type: 'string',
},
{
instanceof: 'Function',
},
],
},
},
additionalStyleMethods: {
description:
'some method to extend the console object which can be invoked by console.xxx() in non-production environment',
type: 'object',
additionalProperties: true,
},
},
required: ['env'],
};
复制代码
测试
代码写完了,就到了测试环节,测试的完善度直接决定了这个工具是否可用。
options 的测试就是传入各种情况的 options 参数,看报错信息是否正确。这里有个知识点,因为 options 需要传错,所以肯定类型不符合,使用 as any as PluginOptions 的双重断言可以绕过类型校验。
describe('options格式测试', () => {
const inputFilePath = path.resolve(
__dirname,
'./fixtures/production/drop-all-console/actual.js',
);
it('env缺失会报错', () => {
const pluginOptions = {};
assertFileTransformThrows(
inputFilePath,
pluginOptions as PluginOptions,
new RegExp(".*configuration misses the property 'env'*"),
);
});
it('env只能传字符串', () => {
const pluginOptions = {
env: 1,
};
assertFileTransformThrows(
inputFilePath,
(pluginOptions as any) as PluginOptions,
new RegExp('.*configuration.env should be a string.*'),
);
});
it('removeMethods的元素只能是string或者function', () => {
const pluginOptions = {
env: 'production',
removeMethods: [1],
};
assertFileTransformThrows(
inputFilePath,
(pluginOptions as any) as PluginOptions,
new RegExp(
'.*configuration.removeMethods[.*] should be one of these:s[ ]{3}string | function.*',
),
);
});
it('additionalStyleMethods只能是对象', () => {
const pluginOptions: any = {
env: 'production',
additionalStyleMethods: [],
};
assertFileTransformThrows(
inputFilePath,
pluginOptions as PluginOptions,
new RegExp(
'.*configuration.additionalStyleMethods should be an object.*',
),
);
});
});
复制代码
主要的还是 plugin 逻辑的测试。
@babel/core 提供了 transformFileSync 的 api,可以对文件做处理,我封装了一个工具函数,对输入文件做处理,把结果的内容和另一个输出文件做对比。
const assertFileTransformResultEqual = (
inputFilePathRelativeToFixturesDir: string,
outputFilePath: string,
pluginOptions: PluginOptions,
): void => {
const actualFilePath = path.resolve(__dirname, './fixtures/', inputFilePathRelativeToFixturesDir,);
const expectedFilePath = path.resolve(__dirname,'./fixtures/',outputFilePath);
const res = transformFileSync(inputFilePath, {
babelrc: false,
configFile: false,
plugins: [[consoleTransformPlugin, pluginOptions]]
});
assert.equal(
res.code,
fs.readFileSync(expectedFilePath, {
encoding: 'utf-8',
}),
);
};
复制代码
fixtures 下按照 production 和其他环境的不同场景分别写了输入文件 actual 和输出文件 expected。比如 production 下测试 drop-all-console、drop-console-by-function 等 case,和下面的测试代码一一对应。
代码里面是对各种情况的测试。
describe('plugin逻辑测试', () => {
describe('production环境', () => {
it('默认会删除所有的console', () => {
const pluginOptions: PluginOptions = {
env: 'production',
};
assertFileTransformResultEqual(
'production/drop-all-console/actual.js',
'production/drop-all-console/expected.js',
pluginOptions,
);
});
it('可以通过name删除指定console,支持glob', () => {...});
it('可以通过function删除指定参数的console', () => {...}
});
describe('其他环境', () => {
it('非扩展方法不做处理', () => {...});
it('默认扩展了red 、green、blue、orange、 bgRed、bgGreen等方法,并且添加了行列数', () => {...});
it('可以通过additionalStyleMethods扩展方法,并且也会添加行列数', () => {...});
it('可以覆盖原生的log等方法', () => {...});
});
});
复制代码
总结
babel-plugin-console-transform 这个插件虽然功能只是处理 console,但细节还是蛮多的,比如删除的时候要根据 name 和 function 确定是否删除,name 支持 glob,非 production 环境要支持用户自定义扩展等等。
技术方面,用了 schema-utils 做 options 校验,用 ts-mocha 结合断言库 chai 做测试,同时设计了一个比较清晰的目录结构来组织测试代码。
麻雀虽小,五脏俱全,希望大家能有所收获。这个插件在我们组已经开始使用,大家也可以使用,有 bug 或者建议可以提 issue 和 pr。
头图:Unsplash
作者:翟旭光
原文:https://mp.weixin.qq.com/s/c9Al8k9itQp8pHqvB-pAZQ
原文:如何用 typescript 写一个处理 console 的 babel 插件
来源:Qunar 技术沙龙 - 微信公众号 [ID:QunarTL]
转载:著作权归作者所有。商业转载请联系作者获得授权,非商业转载请注明出处。
评论