AngularJS + CoffeeScript 前端開發環境配置詳解
AngularJS 號稱 ‘第一框架’ (‘The first framework’) 確實是名不虛傳。由其從jQuery中完全轉入AngularJS后就有無法離開他的感覺了。雖然AngularJS的學習曲線很陡峭,入門的門檻相比較 高,但這些付出都是值得的相信用過的朋友都會與我有同感吧。為何我如此
地偏愛AngularJS? 或者這樣說吧,用AngularJS開發的話其實是給我了一種工業化開發的概念,我對軟件工業化的淺顯理解簡單歸結為幾點就是:
- 自動化
- 智能化
- 注重質量
- 注重工藝
前端開發比后端開發要求開發人員做更多繁雜的事,例如:js和css 的壓縮、依賴引入、更新,圖片壓縮、“糖果語言(coffeescript/less/sass)”的語法檢查與編譯、靜態圖片/靜態網頁壓縮,單元測試、E2E測試、等等。這些鎖事往往很耗時間。
再者,當引入AngularJS作為主前端框架的話,大量的js源文件管理對文件結構與模塊結構合理規劃就顯得更為之重要。所幸的是,google 是AngularJS工業化的主力推手,為了增加前端開發人員的生產力他們也不遺余力地做了很多工作,最為突出的就是[Yeoman|http://www.yeoman.io],他能快速地為我們建立各種類型項目的腳手架(項目模板),以他們的“最佳實踐”為基礎快速地為我們完成這一系列繁瑣的工作。
我在實際項目開發覺得官方提供的 angular 生成器并不是十分合用,在經歷了好幾個項目的磨合后我在 google 官方的 yeoman angular 腳手架項目上進行了一些定制與修改,也在此作一些分享,由于時間關系還沒有去將其成一個generator 所以只能在此以博文方式共享了。
如果對Yeoman不了解也不用要,本文將會獨立于yeoman 一步一步詳細地解釋如何部署一個可以用于生產AngularJS前端開發環境。
工具
以下這些可謂是前端開發必備了,如果不清楚具體用法那么就先請去他們的官網先腦補吧:
npm
Node的依賴包管理工具,可以到 [nodejs 官方下載|http://nodejs.org/download/]頁面獲取安裝包。
** bower **
bower 是由推ter開發的客戶端依賴包管理工具
npm install -g bower
** grunt **
自動化任務管理工具,是整個自動化工程的核心。
npm install -g grunt-cli
安裝此三大工具后我們就可以著手開始了。
實現的目標功能
- 基于 CoffeeScript并支持自動編譯
- 能支持 livereload(一但任何代碼、資源發生更改瀏覽器會自動刷新)
- 自動編譯 less
- 支持 ngdocs 從 CoffeeScript 自動提取注釋生成 API文檔網站
- 自動 連接、最小化靜態資源,包括:腳本、圖片、網頁
- 自動將bower引入的依賴包注入頁面
- 配備 Karma 的單元測試
- 配備基于 protractor 的e2e測試
基本目錄結構
以下是基本項目目錄的構成以及每個目錄的功能說明
項目目錄/
├── app // 應用程序目錄
│ ├── bower_components // bower 組件目錄 (由 bower 生成)
│ ├── fonts // 字體
│ ├── images // 圖片資源
│ ├── styles // 樣式目錄 可存放 .css 和 .less
│ └── scripts // 應用程序腳本
│ └── app.coffee // angularJS 應用程序文件
│ └── index.html // HTML HOME 文件
├── dist // 發布后的程序目錄
├── test // 測試程序目錄
│ ├── mocks // 存放mocks組件文件目錄
│ ├── e2e // e2e測試文件目錄
│ └── spec // 單元測試文件目錄
├── node_modules // NodeJS 的組件目錄 (由 npm 生成)
├── docs // 存放生成文檔
├── .tmp // 臨時文件目錄 (由 grunt 任務自動生成)
├── .bowerrc // bower 路徑規則指定文件
├── conffeelint.json // CoffeeScript 語法檢查規則
├── Gruntfile.js // grunt 配置文件
├── karma.conf.js // karma 配置文件
├── protractor.conf.js // protractor 配置文件
├── package.json // nodes 依賴包描述文件
└── bower.json // bower 依賴包描述文件
流程及原理
此項目環境主要提供三種主要的運行方式,分別適用于項目生命周期中的不同的時期,更準備地說應該是適用于不同的場景。
生成模式 – build
將所有的文件生成至產品交付目錄 dist 內,執行包括:
-
coffeescript/less
- 編譯
- 連結
- 壓縮
- 引用修正,包括 angular 動態注入修正
- 拷貝
-
輸出必要的靜態文件
- 網頁
- 圖片
- 字庫
- 輸出注釋文檔并生成文檔網站
指令:
grunt build
測試模式 – test
多用于開發期,進行自動化單元測試或是e2e測試,考慮到e2e測試的使用頻率相對于單元測試要低,故此 test指令只默認執行所有單元測試,
而要執行e2e測試則需加入 e2e 參數作明確指定。
指令:
grunt test
- e2e -
grunt test:e2e
如果加入 keepalive 參數的話,test 指令將直接運行于后臺,且會檢測所有的文件變化,一但文件發生更改測試將會自動被重新執行。
這種情況多適用于測試程序的編寫與調試。
grunt test:keepalive
調試模式 – debug
主要用于手工調試與HTML界面設計之用,當啟用 debug 模式后,livereload 功能將會被自動載入,也就是所有 app 目錄下的任何
變更都能被捕獲且瀏覽器能自動刷新應用更改。
指令:
grunt debug
Gruntfile.js 文件的設計
首先需要安裝 load-grunt-tasks 和 time-grunt 兩個插件
npm load-grunt-tasks --save-dev npm time-grunt --save-dev
基本的 Gruntfile.js
'use strict'; module.exports = function (grunt) { // 自動加載所有可用的grunt 任務 require('load-grunt-tasks')(grunt); // 可以顯示每個任務執行的實際時間,可以便于以我們優化任務 require('time-grunt')(grunt); // 配置主要路徑 var config = { app: require('./bower.json').appPath || 'app', dist: 'dist', tmp: '.tmp', tasks: grunt.cli.tasks }; grunt.initConfig({ // 任務配置 });
配置 CoffeeScript
首先是令CoffeeScript能支持語法檢查,需要安裝 [coffeelint|http://www.coffeelint.org] 插件:
npm install coffeelint --save-dev
此插件安裝后可以與大名鼎鼎的 jshint一樣將語法檢查規則放在一個獨立的文件內,本項目中就是項目根目錄下的 coffeelint.json,
如果需要增加更多的CoffeeScript語法檢查規則可以修改此文件 。
在Gruntfile.js內的配置如下:
coffeelint: { options: { configFile: 'coffeelint.json' }, all: ['<%= config.app %>/scripts/**/*.coffee'], //檢查應用程序目錄下的 CoffeeScript腳本 test: { files: { src: ['tests/**/*.coffee'] //檢查所有測試腳本 } } }
然后是安裝CoffeeScript編譯插件: [coffee-script|http://github.com/jashkenas/coffeescript]
npm install grunt-contrib-coffee --save-dev
由于我們編譯出來的 javascript 不會直接使用,因為還要進行連接、壓縮和拷貝過程,所以我們將所有的輸出目錄設置為 .tmp 目錄。
在即使修改時也可以通過livereload 從.tmp目錄直接將變更后的腳本直接加載到瀏覽器內,方便調試之用。
還有一點需要特別指出的是 coffee 選項中我將 sourceMap設置為true,只有這個選項打開,當生成map文件后在瀏覽器調試時才能準確地將被壓縮后的
文件正確地重新映射至未壓縮的程序源文件。關于 source map的具體用法可以參考 [javascript source map的使用|http://www.cnblogs.com/Ray-liang/p/4018162.html]
一文。
coffee: { options: { bare: false, sourceMap: true, sourceRoot: '' }, dist: { files: [ { expand: true, cwd: '<%= config.app %>/scripts', src: '{,*/}*.{coffee,litcoffee,coffee.md}', dest: '.tmp/scripts', ext: '.js' } ] }, test: { files: [ { expand: true, cwd: 'test/spec', src: '{,*/}*.coffee', dest: '.tmp/spec', ext: '.js' }, { expand: true, cwd: 'test/e2e', src: '{,*/}*.coffee', dest: '.tmp/e2e', ext: '.js' } ] } }
配置 Less
Grunt 提供了官方的less 編譯安裝包 [grunt-contrib-less|https://github.com/gruntjs/grunt-contrib-less]
npm install grunt-contrib-less --save-dev
與配置coffee 編譯器的原理一樣我們需要將 styles 目錄下的 .less文件預先編譯成為 .css并存放在 .tmp/styles下,以備后處理
和livereload 之用。
less: { all: { files: [ { expand: true, flatten: true, cwd: '<%= config.app %>/styles', src: ['{,*/}*.less'], dest: '.tmp/styles', ext: '.css' } ] } }
壓縮與連接
在這部分我并沒有直接采用 Grunt 官方的 uglify,concat 而是使用了 usemin 插件這是延續了 yo generator-angular 的做法。他是 yeoman項目的官方插件,這個插件同樣是依賴于 uglify,concat 的,然而他增加了對文件自動引用的支持,可以從頁面讀出腳本文件的引用而不是通過hardcore的方式寫在Gruntfile中。另外,他還能增加對 bower_components內的依賴進行合成而取代人工合成,這是一個很棒的功能可以省去我們從bower_components下找輸出文件的麻 煩,只需要關注bower.json文件內管理包而不是在Gurntfile.js進行硬編碼了。
usemin是一個合成包需要以下這些插件同時支持,為了節省篇幅以下的指令都是以 npm install [包] --save-dev 方式安裝
- [grunt-usemin|https://github.com/yeoman/grunt-usemin]
- [grunt-svgmin|https://github.com/sindresorhus/grunt-svgmin]
- [grunt-contrib-cssmin|https://github.com/gruntjs/grunt-contrib-cssmin]
- [grunt-contrib-htmlmin|https://github.com/gruntjs/grunt-contrib-htmlmin]
- [grunt-contrib-imagemin|https://github.com/gruntjs/grunt-contrib-imagemin]
- [grunt-contrib-uglify|https://github.com/gruntjs/grunt-contrib-uglify]
- [grunt-contrib-concat|https://github.com/gruntjs/grunt-contrib-concat]
以下配置是從 generate-angular 中拷貝過來用的:
// Reads HTML for usemin blocks to enable smart builds that automatically // concat, minify and revision files. Creates configurations in memory so // additional tasks can operate on them useminPrepare: { options: { dest: '<%= config.dist %>' }, html: [ '<%= config.app %>/index.html' ] }, // Performs rewrites based on rev and the useminPrepare configuration usemin: { options: { assetsDirs: [ '<%= config.dist %>', '<%= config.dist %>/images' ] }, html: ['<%= config.dist %>/{,*/}*.html'], css: ['<%= config.dist %>/styles/{,*/}*.css'] }, // The following *-min tasks produce minified files in the dist folder imagemin: { dist: { files: [ { expand: true, cwd: '<%= config.app %>/images', src: '{,*/}*.{gif,jpeg,jpg,png}', dest: '<%= config.dist %>/images' } ] } }, svgmin: { dist: { files: [ { expand: true, cwd: '<%= config.app %>/images', src: '{,*/}*.svg', dest: '<%= config.dist %>/images' } ] } }, htmlmin: { dist: { options: { customAttrAssign: [/\?=/], collapseBooleanAttributes: true, collapseWhitespace: true, removeAttributeQuotes: true, removeCommentsFromCDATA: true, removeEmptyAttributes: true, removeOptionalTags: true, removeRedundantAttributes: true, useShortDoctype: true }, files: [ { expand: true, cwd: '<%= config.dist %>', src: ['{,*/}*.html', 'views/{,*/}*.html', 'templates/{,*/}*.html'], dest: '<%= config.dist %>' } ] } }
這里需要說明的是 app/index.html文件,也就是在配置中:
useminPrepare: { html: [ '<%= config.app %>/index.html' ] }
這個選項是給 usemin 插件去找腳本引用的,這里默認只是設定了 index.html 文件,因為這是一個Angular SPA項目,所以只有一個index.html文件作為主入口,如果你具有多個不同的視圖模板,而且所引用的 script 都不要一樣的話,可以將這些模板頁明確地放在這個 html 數組選項中。
關于usemin的詳細用法可以參考google的官方文檔,以下只是對最常用的部分進行講解,力求不去看官方那個龐大的英文文檔也能快速地使用起來。
打開 index.html :
<!doctype html> <html ng-app="app"> <head> <meta charset="utf-8"> <title>Project Title</title> <!-- build:css styles/vendor.css --> <!-- bower:css --> <link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.css" /> <link rel="stylesheet" href="bower_components/fontawesome/css/font-awesome.css" /> <!-- endbower --> <!-- endbuild --> <!-- build:css styles/main.css --> <link rel="stylesheet" href="styles/main.css"> <!-- endbuild --> <!-- build:js scripts/vendor.js --> <!-- bower:js --> <!-- endbower --> <!-- endbuild --> <!-- build:js({.tmp,app}) scripts/index.js --> <!-- endbuild --> <base target="_blank"> </head> <body ng-strict-di> <div ui-view></div> </body> </html>
如果你足夠細心你會發現這里有一些“與眾不同的”標記,<!--build:js--><!-- endbuild --> 和 <!--build:css--><!-- endbuild -->
實際上這不是注釋,他們其實是 usemin 的專用配置標記。其中 <!-- bower:js--><!--endbower--> 是另一個插件 bowerInstall 的
配置標記,我會在下文再詳細講解。
這個標記其實很簡單將他翻譯過來就是:<!-- build:類型[js|css] 生成的目標文件>, 源文件目錄就是當前html所在的目錄,如果要指定多個
源目錄可以通過<!-- build:類型({目錄1,目錄2}) 生成的目標文件>的方式指定。
按照這個來理解的話,這里的設置就會輸出三個文件:
- vendor.js //第三方依賴的合成壓縮腳本
- index.js //項目內的的合成壓縮腳本
- vendor.css //第三方依賴的合成壓縮樣式表
- main.css //項目內的合成壓縮樣式表
好吧,先來說說 vendor.*,如果裝了 bowerInstall 這個插件在<!-- bower:類型 --><!-- endbower-->內 的引用是由 bowerInstall 自動加入的,他加入后會修改index.html源文件,我們不需要手工加入。而對于某些比較坑爹的第三包,這里指的坑爹是他的最終輸出文件放在一些古怪 的深層目錄中,而不是在他的發布目錄的根下,那么我們才需要手工加入引用。如 ace-builds 這個包,他的發布文件是在 ace-builds/src/ace.js,同時他又提供了ace-build/src-min/ace.js 文件,對于這類包我們就不得不手工將具體的引用文件加入到 <!-- bower--> 標記內,否則bowerInstall是不知道應該引用哪一個文件的。
而輸出位置就是前面我們在 usemin選項中設定的:
useminPrepare { options: { dest: '<%= config.dist %>' } }
也就是 項目目錄/dist 。
接下來是 main.css 和 index.js ,這兩個是從不同的源來生成的,main.css 沒有指定源,所以他會在當前的index.html所在位置中找 styles 目錄也就是項目目錄/app/styles,那么具體需要引用那些自定的css(之前通過 less生成的)就在此設定。
解釋得更為清楚一點就是 假設有一個 app/styles/custom.less 文件,那么在 index.html內加入這個引用應該是:
<!-- build:css styles/main.css --> <link rel="stylesheet" href="styles/main.css"> <link rel="stylesheet" href="styles/custom.css"> <!-- endbuild -->
雖然custom.css在設計期并不存在,但他會被less編譯器最終輸出,所以引用時只要名字對了就行了。
同樣的 build:js 的設置也是這理,只是這里增加了 .tmp 作源搜尋目錄,就是說在 .tmp 找不到的源文件 可以到 app/scripts下找,反之亦然。
bowerInstall
緊接上文,就是這個 bowerInstall 插件了,他就是可以從bower.json文件自動識別我們的項目引入了哪些第三方依賴,然后就將依賴的文件自動地注入到 <!--bower:js-->和<!--bower:css-->標記里面。
npm install grunt-bower-install --save-dev
配置如下:
bowerInstall: { app: { src: ['<%= config.app %>/index.html'], ignorePath: '<%= config.app %>/' } }
bowerInstall 有一個替代品,叫 wiredep ,但這個插件很笨,經常會出現引用錯誤的問題,所以這里還是推薦使用bowerInstall
Angular 的自動依賴注入
接下來就是要為 Angular 環境作專門的配置了,首先要配置的是依賴注入。先來看來來Angular官方推薦的依賴注入方法:
angular.main('myApp',[]).controller('MyCtrl',['$scope','$log','$http','$resource',($scope,$log,$http,$resource)-> #我們的代碼在此 ])
光是為依賴注入我們其實是很無趣地編寫這些對應的白癡式引用,當然只有一兩個當然沒什么問題,但如果注入得多了那么這個定義就變得
極為之難讀。如果我們將上面的代碼寫成這樣:
MyCtrl=($scope,$log,$http,$resource)-> #控制器代碼在此 @ angular.main('myApp',[]).controller 'MyCtrl',MyCtrl
這樣是否更容易讀呢?為了實現這個效果,我們可以使用 [ngAnnotate|https://www.npmjs.com/package/grunt-ng-annotate] 插件幫我們實現這
種動態式的插入,使得我們的代碼可讀性可以大大地增加。
npm install grunt-ng-annotate --save-dev
ngAnnotate: { dist: { files: [ { expand: true, cwd: '.tmp/concat/scripts', src: ['*.js', '!oldieshim.js'], dest: '.tmp/concat/scripts' } ] } }
自動生成 Angular API 文檔
這是一個我認為很 Cool 的插件,他能直接從源代碼中直接抽出注釋并生成一個API參考網站,對于開發產品項目幫助極大。這個插件叫 [ngdocs|https://www.npmjs.com/package/grunt-ngdocs]
npm install ngdocs –save-dev
這個插件配置很是簡單,但他不能支持coffeescript,那么我們只能從生成的javascript文件作為注釋文檔生成源:
ngdocs: { all: ['.tmp/scripts/**/*.js'] }
關于 ngdocs 這個主題以后我會專門花時間再詳細寫一篇文章來具體說明一下。
腳本模板
在使用Angular的 Routing、directive或是其它的插件,如 angular-ui 都可能使用到模板。如:
MyDirective=-> restrict:'E' tempalteUrl:'scripts/directives/MyDirective.tpl.html' angular.module('myApp').directive 'MyDirective',MyDirective
對于使用了 tempalteUrl 指定的模板是無法在Karma的測試中找到的,因為jasmine只能找到腳本而不能找到html文件。這樣一來就會令得 directive 成為一個不可測試的元件。可以使用 [html2js|https://github.com/karlgoldstein/grunt-html2js] 解決這一問題(angularJS官方推薦)。這個插件的最大作用是將html文件直接編譯為js文件,而無需要改動我們的源代碼,這樣一來既可在測試上 解決這個問題也可以將html模板文件封裝為可發布的腳本(如果你細心一點會發現 angular-ui 就是樣做的,angular-ui-tpl.js 就是模板文件)。
npm install grunt-html2js --save-dev
這個配置會有點點復雜
html2js: { options: { base: 'app', target: 'coffee', module: 'myApp.templates', //模板會生成至模塊內,需要明確指定模塊的名稱 singleModule: true, useStrict: true, htmlmin: { collapseBooleanAttributes: true, collapseWhitespace: true, removeComments: true, removeEmptyAttributes: true, removeRedundantAttributes: true, removeScriptTypeAttributes: true, removeStyleLinkTypeAttributes: true } }, main: { src: ['<%= config.app %>/scripts/**/*.tpl.html'], dest: '<%= config.app %>/scripts/templates.coffee' } }
有幾點在使用時需要注意:
- 這里只檢測 app 目錄下所有的以 *.tpl.html結尾的HTML文件(視為模板文件)
- 這個文件會生成至源目錄(app/scripts/)下的templates.coffee 待coffee編譯進行后處理
- 在 app.coffee 文件內需要明確地引入由 module 所指定的模板模塊,否則會引用失敗
另外考慮到本文的篇幅問題,這里就略過了 copy, watch 和 connect 三個最為常用的任務配置,具體的可以從本文內附的源代碼內參考。
karma
Karma runner 應該屬于時下最流行的測試運行器之一了。他的配置在Gurnt貌似很簡單,而然事實并非如此。他有獨立的配置文件在本項目中為 karma.conf.js,他的配置選項比較多在此就不一一地詳細解釋了,這里我是將Karma配置成能支持 coffee script并基于 [PhantomJS|http://phantomjs.org] 作為宿主瀏覽器,以 [jasmine|http://jasmine.github.io/] 作為測試運行架構的的單元測試環境。所有的單元測試文件存放在 test/spec 目錄下。
他需要的依賴插件分別有:
- karma-coffee-preprocessor
- karma-coverage
- karma-jasmine
- karma-junit-reporter
- karma-chrome-launcher
- karma-phantomjs-launcher
- karma-requirejs
- karma-story-reporter
安裝后的配置如下:
karma: { unit: { configFile: 'karma.conf.js', singleRun: true } }
這里需要注意的是,在 karma.conf.js 配置的文件的 files 和 exclude 兩個選項,files 內需要配置整個項目運行期
需要用到的 bower 依賴包,如:
files: [ 'app/bower_components/angular/angular.js', 'test/spec/{,*/}*.coffee' ]
如使用到其它的angular插件引用需要在此加入,則會可能會導致單元測試因找不到依賴包而導致注入失敗。
而 exclude 就當然是無需要加載的文件。
由于國內網絡環境問題 安裝 phantomJS 可能會偏慢,如果無法下載phantomJS可以將其刪除,而使用 chrome 代替。
protractor
對于e2e測試(白盒測試/集成測試)也可以使用Karma+angular-scenario來配置,但這個在AngularJS官方已作為過時配置而不被推薦。取而代之的當然是 [protractor|http://angular.github.io/protractor/#/] 他為jasmine所擴展的matcher很多,用起來確實是
很好用。然而 protractor 可能比較新吧(發展了才一年多的時間)他的安裝包下載是極其慢的,由其是 [selenium|http://www.seleniumhq.org]的安裝。
他的配置有點像 karma 也是通過一個外部的 protractor.conf.js文件作為額外的附加配置的,在 Gruntfile.js 內:
protractor: { options: { keepAlive: true, configFile: "protractor.conf.js" }, all: {} }
然而值得一談的是他所依賴的 Webdriver 的安裝過程。
安裝protractor包
npm install protractor --save-dev
protractor 安裝后會得到一個 webdriver-manager 的命令行工具。protractor 依賴于 selenium 服務器,且selenium是一個基于java開發的,so 在此之前則需要先安裝好JDK。
另外 protractor 只能支持 chrome 和 ie 兩種瀏覽器驅動,需要在完成 protractor安裝后手動運行:
webdriver-manager update
不知是否人品問題(我絕對不認為天朝的網絡有問題的),這個命令我是總運行不成功!這個命令會從 google的官網上下載一個chrome的模擬驅動程序至本機的/usr/local/lib/node_modules/protractor/selenium/chromedriver/ 目錄,如果你的人品與我一樣,也是無法下載的話,那么你可以直接在google上下去載 [chromedriver|https://sites.google.com/a/chromium.org/chromedriver/] 的驅動然后手工解壓到這個本地目錄下即可。(BTW 我的環境是OSX,在Linux下我不知道是什么情況,試過的朋友請給我留言作為補充吧)
由于各種的不成功,最后我是直接將 protractor 的配置指向本絕對目錄地址的,如果你有同樣的情況出現就將以下的兩個配置加入到protractor.conf.js中吧
seleniumServerJar: '/usr/local/lib/node_modules/protractor/selenium/selenium-server-standalone-2.44.0.jar', chromeDriver: '/usr/local/lib/node_modules/protractor/selenium/chromedriver/'
protractor 有一點比較好的是可以與 WebStorm 以下是具體配置的辦法:
WOO
一不小心寫了這么長一篇,光是附上文章貌似不太地道,那么如果對這個腳手架項目有興趣的朋友請到[我的 github|http://www.github.com/dotnetage/]上下載這個項目吧。項目地址是:https://github.com/DotNetAge/Angular-CoffeeScript-Seed。下載后,需要分別運行
sudo npm install
bower install
對本文所述的包進行一次性安裝。暫時還沒時間將這個包寫成 Yeoman Generator ,不過飯還是一口一口吃吧,或者你可以直接Fork這個項目噢。
來源:Ray Liang