node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »

shark-automation

介绍

shark-automation是一款基于gulp打造的,拥有较强可扩展性的前端自动化构建工具。提供了前端资源编译发布、本地调试、图片聚合等功能。

安装

  • 全局安装
#安装
npm install shark-automation -g
#在项目根目录下执行需要的任务
shark server #启动本地调试
shark build test #编译
  • 本地安装
#在项目根目录下安装
npm install shark-automation --save-dev
#需要添加npm scripts脚本
#添加脚本
{
    "scripts": {
        "server": "shark server", #启动本地调试 
        "build": "shark build test" #编译
    }
}
#执行
npm run server
npm run build 

相关文档: npm scripts

automation提供的命令

# 启动本地调试
shark server
# 启动编译.target: 指定是哪个阶段的编译。test:测试机,online:线上 
shark build <target>  
# compile。主要是给后端使用,执行预处理器语言的编译处理,比如scss
shark compile
# 聚合图片
shark sprite
# 推送编译好后的代码到指定的git仓库.target:test:测试仓库,online:线上仓库;branch:代码分支;tagv:tag version;tagm:tag 说明
shark deploy <target> <branch> [-v <tagv>] [-m <tagm>]

配置文件

shark-automation在执行任务期间,需要两份配置文件:①shark-automation-config.js ②shark-config.js。在项目根目录需提供这两份文件

  • shark-automation-config.js 基本配置项,包含项目目录结构说明、deploy 仓库地址等
配置项 说明 例子
product 项目名称 shark-automation
contextPath 请求路径前缀。一般用于本地调试用。例如项目请求的前缀为/automation,则需要配置/automation /
browserPort browserSync服务所占用的端口 9309
port express服务所占用的端口 9300
hostname 域名 localhost
openurl 用于本地调试。当本地模拟服务准备好后,自动打开的url。注意:端口需要指向browsersync的端口,不然没有livereload效果 http://localhost:9309/index.html
rootPath 项目路径 __dirname
webapp 前端代码的根目录,相对于项目路径设置 src/main/webapp
scssPath scss文件所在的目录,相对于webapp目录 style/scss
cssPath scss编译后产生的css所在目录,相对于webapp目录 style/css
imgPath 图片所在目录,相对于webapp目录 style/img
spriteSrc [Array]需要做聚合图片的文件夹目录,相对于imgPath.当需要聚合图片时,需要设置。 ['sprite']
spriteImageDist 聚合后图片的存放路径,相对于imgPath目录.当需要聚合图片时,需要设置。 sprite
spriteScssDist 聚合后产生的scss文件的存放目录,相对于scssPath目录.当需要聚合图片时,需要设置。 sprite
videoPath 视频所在目录,相对于webapp目录 style/video
jsSrcPath js源码目录,相对于webapp目录。当js需要工具编译打包时,需要多加一层。
例如:js目录下放源码,如果不需要编译打包,则直接js作为源码目录,但如果需要编译打包,则需要增加一层,比如说src。 那么,js/src则是源码目录
js || js/src
jsDistPath js编译后的目标目录。相对于webapp。如果js不需要编译,则不需要提供。 js/dist
fontPath 字体文件目录,相对于webapp目录 font
htmlPath html所在目录,相对于webapp目录 views
templatePath ftl所在目录,相对于webapp目录 tmpl
build 编译后资源的存放目录,相对于rootPath build
buildWebApp 存放class、html、font等文件,相对于build目录 app
appPath 放置前端html、font等编译后的文件,相对于build目录。一般来说,这个路径和buildWebApp是一致的。但是在有些需求中,后端要求前端资源放置在他们特定的目录下,一般是buildWebApp的子目录。 app/webapp
buildStatic 放置静态资源编译后的文件,相对于build目录。 statics
mimgURLPrefix.develop 资源定位时,开发调试阶段,静态资源请求路径的前缀 /
mimgURLPrefix.test 资源定位时,测试阶段,静态资源请求路径的前缀 http://test.com
mimgURLPrefix.online 资源定位时,上线阶段,静态资源请求路径的前缀 http://online.com
deploy.gitUrl git仓库的地址,包含协议,用户名,密码和域名。 http://user:pwd@github.com
deploy.test.static 测试仓库的静态资源路径,相对于deploy.gitUrl test/test-static.git
deploy.test.staticdir 与deploy.test.static仓库地址有映射关系的目录路径(绝对路径) /home/deploy/test/static
deploy.test.app 测试仓库中,class、html、font等资源的路径,相对于deploy.gitUrl test/test.git
deploy.test.appdir 与deploy.test.app仓库地址有映射关系的目录路径(绝对路径) /home/deploy/test/app
deploy.online.static 线上仓库的静态资源路径,相对于deploy.gitUrl online/online-static.git
deploy.online.staticdir 与deploy.online.static仓库地址有映射关系的目录路径(绝对路径) /home/deploy/online/static
deploy.online.app 线上仓库中,class、html、font等资源的路径,相对于deploy.gitUrl online/online.git
deploy.online.appdir 与deploy.online.app仓库地址有映射关系的目录路径(绝对路径) /home/deploy/online/app
ftl2html [Array]ftl渲染配置项。主要是用于本地调试
[
    {
        url: '/([a-z,A-Z,0-9,/,_]*)$', 
        sourceRoot: 'src/main/webapp',
        ftl: 'tmpl/{1}.ftl', 
        outputRoot: 'src/test/mock/output', 
        data: 'src/test/mock/tdd/{1}.tdd'
    }
]
            
  • shark-config.js

automation启动的时候,会读取这份文件。automation会暴露一个shark对象到全局对象上,该对象包含automation暴露的接口。shark-config.js这份文件就是利用shark接口,来扩展插件的默认配置。最基本的配置文件:

//设置基本配置 
shark.baseconfig = require('./shark-automation-config.js');

其他接口参考: 接口说明

工作原理

shark-automation在build阶段定义了固定的工作节点。每个节点需要完成的任务是固定的,但是具体该怎么做用户根据业务需求可以自己扩展工具提供的默认处理方式。各个节点分别是:compile(编译)、combine(合并)、location(资源定位)、min(压缩)、md5(重命名)、copy(拷贝编译后的文件到制定目录)

内置的task配置如下表格:

例如compile-css,基本的配置:

{
    compile: [{
        test: '**/*.scss'
        name: 'compile-css',
        plugins: {
            lise: [{
                use: 'gulp-sass',
                option: {}
            }, {
                use: 'gulp-css-base64',
                option: {}
            }, {
                use: 'gulp-autoprefixer',
                option: {}
            }]
        }
    }]
}

最终生成的task如下:

//其中的src、base、dest分别对应表格中的源目录、基准目录和目标目录 
gulp.task('compile-css', function() {
    return gulp.src(`${src}/$test`, {
        base: `${base}`
    })
    .pipe(require('gulp-sass')({}))
    .pipe(require('gulp-css-base64')({}))
    .pipe(require('gulp-autoprefixer')({}))
    .pipe(gulp.dest(`${dest}`));
});
节点 task plugins 源目录(src) 基准目录(base) 目标目录(dest) test like priority(数字越小优先级越高) 是否开启
compile compile-css gulp-sass、gulp-css-base64、gulp-autoprefixer ${scssPath} ${scssPath} ${tempPath}/tmp/${cssPath} **/*.scss css 0
compile-js webpack-stream(如果需要使用webpack) ${jsSrcPath} ${jsSrcPath} || ${webapp}(如果js需要编译,则是前者,如果不需要编译则是后者) ${tempPath}/tmp/${jsDistPath} **/*.js js 0
combine compile-html gulp-useref ${webapp} ${webapp} ${tempPath}/tmp1 **/*.@(html|ftl) html 1
compile-js ${tempPath}/tmp ${tempPath}/tmp ${tempPath}/tmp1 **/*.js js 1 否(如果使用webpack,则打开)
compile-css ${tempPath}/tmp ${tempPath}/tmp ${tempPath}/tmp1 **/*.css css 1
location location-html gulp-rev-replace ${tempPath}/tmp1 ${tempPath}/tmp1 ${tempPath}/tmp2 '**/*.@(html|ftl) html 6
location-js gulp-rev-replace ${tempPath}/tmp1 ${tempPath}/tmp1 ${tempPath}/tmp2 **/*.js js 3
location-css gulp-rev-replace ${tempPath}/tmp1 ${tempPath}/tmp1 ${tempPath}/tmp2 **/*.css css 3
min min-image gulp-imagemin ${webapp} ${webapp} ${tempPath}/tmp3 **/*.@(jpg|jpeg|png) image 1
min-js gulp-uglify ${tempPath}/tmp2 ${tempPath}/tmp2 ${tempPath}/tmp3 **/*.js js 4
min-css gulp-clean-css ${tempPath}/tmp2 ${tempPath}/tmp2 ${tempPath}/tmp3 **/*.css css 1 4
min-html ${tempPath}/tmp2 ${tempPath}/tmp2 ${tempPath}/tmp3 **/*.@(html|ftl) html 7
md5 md5-image gulp-rev ${tempPath}/tmp3 ${tempPath}/tmp3 ${tempPath}/tmp4 **/*.@(jpg|jpeg|png) image 2
md5-js gulp-rev ${tempPath}/tmp3 ${tempPath}/tmp3 ${tempPath}/tmp4 **/*.js js 5
md5-css gulp-rev ${tempPath}/tmp3 ${tempPath}/tmp3 ${tempPath}/tmp4 **/*.css css 5
md5-html ${tempPath}/tmp3 ${tempPath}/tmp3 ${tempPath}/tmp4 **/*.@(html|ftl) html 8
md5-video gulp-rev ${webapp} ${webapp} ${tempPath}/tmp4 **/*.@(mp4|webm|mpg|wmv|avi|rmvb) video 2
copy copy-image ${tempPath}/tmp4 ${tempPath}/tmp4 ${build}/${buildStatic}/${staticVersion} **/*.@(jpg|jpeg|png) image 9
copy-html ${tempPath}/tmp4 ${tempPath}/tmp4 ${build}/${appPath} **/*.@(html|ftl) html 9
copy-js ${tempPath}/tmp4 ${tempPath}/tmp4 ${build}/${buildStatic}/${staticVersion} **/*.js js 9
copy-css ${tempPath}/tmp4 ${tempPath}/tmp4 ${build}/${buildStatic}/${staticVersion} **/*.css css 9
copy-video ${tempPath}/tmp4 ${tempPath}/tmp4 ${build}/${buildStatic}/${staticVersion} **/*.@(mp4|webm|mpg|wmv|avi|rmvb) video 9
copy-ico ${webapp} ${webapp} ${build}/${appPath} *.@(ico|txt) ico 9
copy-font ${webapp}/${fontPath} ${webapp} ${build}/${appPath} ** font 9

接口

  • 扩展task配置
shark.plugins = {
    [compile || combine || location || min || md5 || copy]/*节点*/: [{
        test: '',//glob语法。 
        name: '',//如果name和内置的task一致,则会用此配置扩展该内置task。不然无需提供 
        like: js || css || html || image || font || video, //需要处理的文件类型  
        switch: on || off, //是否启用task 
        exclude: [], //需要被过滤的glob。可以是绝对路径,也可以是相对于项目根目录的相对路径 
        pre: {
            list: [{
                use: '',//插件名 
                option: {}//插件的option参数 
            }],//gulp插件列表。这些插件会在plugins之前执行 
            merge: replace || append || preappend //使用怎样的方式进行merge 
        },
        plugins: {
            list: [{
                use: '',//插件名 
                option: {}//插件的option参数 
            }],//gulp插件列表。 
            merge: replace || append || preappend //使用怎样的方式进行merge 
        },
        post: {
            list: [{
                use: '',//插件名 
                option: {}//插件的option参数 
            }],//gulp插件列表。这些插件会在plugins之后执行 
            merge: replace || append || preappend //使用怎样的方式进行merge 
        },
    }]
};
//根据此配置,生成的task 
let name = name || 系统生成;
gulp.task(name, function() {
    //src、base、dest 是根据节点+like两个字段,获取路径。具体查阅内置task表格 
    let srcPath = `${src}/${test}`;
    let basePath = `${base}`;
    let destPath = `${dest}`
    return gulp.src(srcPath, {
        base: basePath
    })
    .pipe([pre]/*pre plugins*/)
    .pipe([plugins]/*plugins 列表*/)
    .pipe([post]/*post plugins 列表*/)
    .pipe(gulp.dest(destPath));
});
  • webpack扩展
//如果需要使用webpack,则需要配置,否则不用配置 
shark.webpack = {
    //读取入口文件的两种方式。filename: 根据文件名/\.page.js/判断;dirname: page文件夹下的所有文件做为入口文件 
    entry: 'filename' || 'dirname'  
};
  • 扩展本地调试时的路由
shark.appConfig = function(app) {
    //express app 
}