本文翻譯自Hackathon Starter的Github頁面。

在線demo： http://hackathonstarter.herokuapp.com

本文翻譯時Hackathon Starter的version：2.3.2

Hackathon Starter是專門為Node.JS Web開發而準備的一個樣板。

如果你以前參加過黑客馬拉松（hackathon），那么你一定會意識到項目準備階段會花費大量時間：比如決定制作什么、選擇編程語言、選擇web 框架，以及選擇css框架。一段時間過后，你好不容易在Github上建立起初始化的項目，然后其他成員才終于能夠開始工作。或者考慮一個更簡單的情景， 使用Facebook賬戶登錄。如果你不熟悉OAuth 2.0的話，這將耗費你大量的時間。

當我開始本項目時，我首要考慮的是簡單和易用。我也試著讓它盡量的兼容以及可復用，使它能夠在大多數hackathon web app上使用。在最壞的情況，比如你只對使用Google賬戶登錄感興趣，你也可以將它當做一個學習指南。

你很可能不需要使用所有的賬號登錄認證功能，不用擔心，這些在Hackathon Starter 2.1版本之后是可選擇的。

現代風格

扁平化Bootstrap主題

默認主題

Hackathon Starter生成器界面

特性

• 本地登錄認證（使用Email與密碼）
• OAuth 1.0a認證（ Twitter）
• OAuth 2.0認證（Facebook、Google、Github、Linkedin等）
• 快速提示
• MVC項目結構
• Node.JS 集群支持
• Rails 3.1風格的 Asset pipeline，由connect-assets提供
• LESS樣式表（自動編譯無需Gulp/Grunt）
• Bootstrap 3 + Flat UI + iOS 7
• 聯系表單（支持Mailgun、Sendgrid、Mandrill）
• 賬戶管理
  Gravatar頭像
  用戶詳細資料
  改密碼
  找回密碼
  重置密碼
  綁定社交賬號
  注銷賬號
• CSRF保護
• API案例（Facebook等）

環境依賴

• MongoDB
• Node.JS
• 命令行工具
  Mac OS X：Xcode
  Windows：Visual Studio
  Ubuntu：sudo apt-get install build-essential
  Fedora：sudo yum groupinstall "Development Tools"
  OpenSUSE：sudo zypper install --type pattern devel_basis

注意：如果你是Node.JS新手，建議閱讀教程Getting Started With Node.js, Express, MongoDB。

入門指南

最簡單的開始方法就是克隆Github倉庫：

# Get the latest snapshot
git clone --depth=1 https://github.com/sahat/hackathon-starter.git myproject

cd myproject

# Install NPM dependencies
npm install

node app.js

注意：強烈建議安裝Nodemon，它能監控你的Node.JS App的任何改動并自動重啟，從長遠來看著將節省你大量時間。

生成器（Generator）

Hackathon Starter生成器目前還在實驗階段，它與目前的代碼緊密相連，一旦移動或改變項目代碼，生成器將有可能不可用，因此建議在下載HS后第一時間使用。

生成器能夠選擇賬號認證、改變發送郵件的服務商。

獲得API密鑰（略過）

本部分講如何從Facebook、Google等服務提供商處獲取API密鑰。

項目結構

注意：這里沒有規定你應該如何處理你的視圖，你可以將你的視圖模板放在你喜歡的地方，只要記住更新extends ../layout并且與控制器中的res.render()路徑一致。

使用包列表

有用的工具與資源

• JSDB.io – 包含絕大多數JS庫的數據庫
• JS Recipes – 前端與后端的JS教程
• Jade Syntax Documentation by Example – 比jade官方的文檔還要好
• HTML to Jade converter – 當你需要將從網上找來的HTML片段快速的應用到項目中時特別有用
• JavascriptOO – 一個常用JS庫的示例、CDN以及教學視頻的目錄
• Favicon Generator – 生成各平臺的favicon

推薦的設計資源

• Code Guide – 開發靈活、耐用、可持續的HTML與CSS的標準
• Bootsnipp – 配合Bootstrap使用的一些代碼片段
• UIBox – HTML, CSS, JS, UI 組件
• Bootstrap Zero – 免費的Bootstrap主題
• Google Bootstrap – Google風格的Bootstrap主題
• Font Awesome Icons – 已經被包含在Hackathon Starter項目中，可以將這作為參考頁面
• Colors – 更好的web頁面配色
• Creative Button Styles – 各種各樣非常棒的按鈕
• Creative Link Effects – 漂亮的鏈接CSS效果
• Medium Scroll Effect – 像Medium一樣的頂部背景圖片漸隱效果
• GeoPattern – SVG background pattern generator.
• Trianglify – SVG low-poly background pattern generator.

推薦的Node.JS庫

• Nodemon – 代碼改動時自動重啟Node.js服務
• geoip-lite – 根據IP地址庫的地理位置定位
• Filesize.js – 格式化文件大小，如 filesize(265318); // "265.32 kB".
• Numeral.js – 格式化并操作數字的庫
• Node Inspector – 基于Chrome開發者工具的Node.js調試器
• node-taglib – 讀取常用音頻格式的meta-data的庫
• sharp – 調整圖片大小的庫，支持JPEG, PNG, WebP 和 TIFF

推薦的客戶端JS庫

• Framework7 – 包含構建iOS7風格App完整特性的HTML框架
• InstantClick – 在鼠標指上時預下載，加快頁面加載速度
• NProgress.js – 簡練的進度顯示條
• Hover – 非常棒的鼠標hover css3動畫效果
• Magnific Popup – 響應式的jQuery彈出框插件
• jQuery Raty – 星星打分插件
• Headroom.js – 隱藏你的header直到你需要它
• X-editable – 直觀的修改表單元素
• Offline.js – 探測用戶是否在線
• Alertify.js – 可愛的彈出警告與瀏覽器對話框
• selectize.js – 可調整樣式的select元素與input標簽
• drop.js – 強大的JS與CSS庫用于創建下拉菜單與其他浮動顯示層
• scrollReveal.js – 提供滾動時的動畫效果

高級Tips

1. 當安裝NPM包時，添加–save標簽，它將自動添加到package.json文件中。如：npm install –save moment
2. 當你需要多個同步工作，并當它們都完成后才渲染頁面時，使用async.parallel() 。比如你需要爬取三個頁面的數據，爬取完成后將結果填充到模板中。
3. 想要從隊列中尋找特定的對象？試試Lodash里的_.find 函數。比如，這段代碼提供了檢索Twitter token的能力：

var token = _.find(req.user.tokens, { kind: 'twitter' }); 

FAQ

為什么我在提交表單時顯示403錯誤？

你需要在表單中添加下面的隱藏元素，這是一項CSRF保護措施。

input(type='hidden', name='_csrf', value=_csrf) 

注意：CSRF現在支持白名單了，這意味著你可以提交一些URL鏈接，他們可以被CSRF忽略。

注意2：如需忽略的URL是動態的，可以用正則表達式匹配。

cluster_app.js是什么？

Node.js官方文檔的解釋：

一個Node實例在單個線程中運行。為了充分利用多內核系統的性能，用戶會希望啟動一個Node的進程簇來處理負載。cluster模塊讓你能夠簡單創建共享服務器端口的子進程。

cluster_app.js是app.js的多進程版本，它能為每個被探測到的CPU創建一個進程。為了最大化的滿足HTTP請求，這是一個很好的功能。但是，cluster模塊仍處於實驗階段，因此請小心使用，確保你正確理解了它的意圖和行為。要使用它，只需要運行node cluster_app.js，它與app.js是完全分離的，無任何依賴關系。需要提醒的是，如果你用cluster_app.js替代app.js，你需要在package.json里做出聲明。

什么是Rails 3.1風格的asset pipeline？

下面是你如何在HTML里定義靜態文件，使用Jade或其他的模板引擎：

link(href='/css/styles.css', rel='stylesheet') 
script(src='/js/lib/jquery-2.1.0.min.js') 
script(src='/js/lib/bootstrap.min.js') 
script(src='/js/main.js') 

看起來足夠簡單？在開發環境下也行是這樣。但如果當你將app部署到生產環境時，它們能夠被自動的壓縮到單個的文件呢？

link(href='/css/styles.css', rel='stylesheet') 
script(src='/js/application.js') 

當你引入的JS庫越多，自動連接并壓縮JS文件帶來的好處就越大。connect-assets庫能夠讓你簡單的完成這一操作，只需兩行代碼：

!= css('styles')      // expects public/css/styles.less 
!= js('application')  // expects public/js/application.js 

你只需要記住在public/js/application.js中定義你的JS文件。語法從Rails中借鑒而來：

//= require lib/jquery-2.1.0.min 
//= require lib/bootstrap.min 
//= require main 

使用這個方法，當在開發模式時，它會加載各個獨立的JS文件，而當部署到生產環境，它會自動形成單個JS文件。你可以看Sprockets-style concatenation 來了解更多。

我出現了MongoDB Connection Error，該如何修復它？

這是一個在app.js中自定義的錯誤信息，用來表示連接到MongoDB時出現了問題。

mongoose.connection.on('error', function() { 
  console.error('✗ MongoDB Connection Error. Please make sure MongoDB is running.'); 
}); 

它提示你應該在啟動app.js之前先啟動MongoDB，你可以在這里下載MongoDB，也可以從包管理器來安裝，如果你是Windows用戶，可以按照在Windows上安裝MongoDB的說明來做。

Tip：如果你一直連接著網絡，也可以試著使用 MongoLab 或者 MongoHQ 等在線數據庫服務，你只需要更新config/secrets.js中的db信息。

當我部署我的app時提示錯誤，為什么？

有可能是你沒有在secrets.js中正確的設置數據庫路徑。當你在本地運行你的app時，數據庫路徑是localhost，但當你部署app時，你需要在網上找到一個運行的MongoDB，并將連接地址正確的填寫在secrets.js中。你也可以申請MongoLab 或者 MongoHQ 等免費服務。

為什么采用Jade代替Handlebars模板引擎？

當我開始這個項目的時候我并不熟悉Handlebars，后來我開發了一些Ember.js apps并且熟悉了Handlebars的語法。Handlebars的確更簡單一些，因為它就像HTML一樣，但我并不后悔選擇了Jade。理由有三， 第一因為Jade是Express的默認模板引擎，所以以前開發過Express應用的人已經對它很熟悉了；第二，我發現在Handlebars里 extends和block是必不可少的，它實際上并沒有達到即開即用的程度，你仍然需要編寫一些擴展函數；第三，客觀的說，Jade看上去比 Handlebars更簡潔干凈，這點與其他非HAML風格的引擎相比也是一樣。

為什么你在app.js里定義了所有的路由(route)？

一言以蔽之，為了簡潔。也許有其他更好的方法，比如在這篇博文中 將app上下文按照概述傳給每一個控制器，但我發現這種方法對初學者來說說容易搞混的。我花了大量時間來理解exports和 module.exports的概念，保證有一個單獨的全局性app文件作為參考。這是我的背景想法。app.js對我來說是“app的心臟”，它應該成 為其他所有模型、控制器、路由等的參考。

我不需要一個絕對底部（sticky footer），我能刪除它嗎？

當然可以。不過不像一個常規footer，你還需要做一些額外的工作。首先，從styles.less里刪除#wrap和#footer，以及html, body { height: 100%; }。然后，從layout.jade中刪除#wrap和#footer所在的行（順便說下，如果Jade沒有檢測到class或id，它會默認其是一個div元素）。不要忘了調整#wrap下面的縮進，本項目使用兩個空格表示塊級縮進。

我能夠使用Sass代替LESS嗎？

Yes you can！雖然你需要手動的轉換現有的樣式表到Sass，考慮到Sass和LESS的相似程度，這不會太難。然后你只需要重命名styles.less為styles.scss，connect-assets會自動的采用Sass預處理器。

你甚至可以同時的使用Sass和LESS，在layout.jade里分別指定了LESS和Sass樣式表文件：

!= css('styles') # public/css/styles.less 
!= css('my_sass_styles') # public/css/my_sass_styles.scss 

注意：項目的package.json不包含Sass，所以你需要自己安裝它，使用以下命令：

npm install --save node-sass 

迷你指南

這一部分將提供單一特定功能的細節解釋。也許你很好奇這個項目是如何工作的，也許你已經迷失在代碼當中，我希望它能給你一些指引。

定制HTML與CSS設計入門

HTML5 UP提供許多漂亮的模板，并且可以免費下載。

當你下載了一個zip文件，里面有index.html、images、css和js文件夾。那么，如何把它拿到Hackathon Starter里面來呢？Hackathon Starter使用Bootstrap CSS框架，但那些模板沒有使用。將它們放到一起會出現很多意想不到的情況。

注意：使用定制模板的方法，你應當理解你不能重用我創建的所有視圖：layout、主頁、登錄、注冊、賬號管理、聯系頁面。這些視圖使用 Bootstrap柵格風格創建。你需要用新模板里的語法手動更新這些柵格。不過你也可以用另一種方法，在大多數界面使用Bootstrap，而在 landing page使用另一種風格的模板。

讓我們從頭開始，在這個例子里我將使用Escape Velocity 模板。

注意：為了簡潔起見我將只考慮index.html，忽略left-sidebar.html、 no-sidebar.html和 right-sidebar.html。

將所有的js文件從html5up-escape-velocity/js移動到public/js，并將所有css文件從html5up- escape-velocity/css移動到public/css，最后將所有圖片文件從html5up-escape-velocity /images移動到public/images，復制index.html里的代碼，并將它們粘貼到HTML To Jade 進行轉換。

創建一個新文件escape-velocity.jade，將轉換到的Jade代碼粘貼進去。將!!! 5修改為doctype html，這是Jade最近的一個改動之一，但是http://html2jade.aaron-powell.com 還沒有跟進這個改動。

在controllers/home.js里創建一個新的控制器escapeVelocity：

exports.escapeVelocity = function(req, res) { 
  res.render('escape-velocity', { 
    title: 'Landing Page' 
  }); 
}; 

然后在app.js里創建一個路由，我將它放在index控制器的后面:：

app.get('/escape-velocity', homeController.escapeVelocity); 

重啟服務器（如果你沒有使用nodemon），然后你就可以在http://localhost:3000/escape-velocity 來查看新模板了。

我的講解將在這里打住，如果你想在更多的頁面使用這個模板，下面是你需要關注的Jade文件：

• layout.jade – 基本模板
• index.jade – 主頁
• partials/navigation.jade – Bootstrap導航欄
• partials/footer.jade – 絕對底部（sticky footer）

你需要手動的將新模板分解為更小的部分。弄清楚模板的哪些部分你想在所有的頁面中保留——那將是你的新layout.jade，其他頁面將通過 block content來共享代碼。如果有不清楚的地方，你可以使用已有的模板作為參考。

這是一個枯燥無味的過程，如果你下載的模板有一套新的柵格系統，那么需要更加謹慎了。這是我為什么使用Bootstrap的原因。很多人已經熟悉Bootstrap了，即使沒用過學起來也很簡單。你還可以從Themeforest購買一些漂亮的Bootstrap模板。然后你可以很方便的將它放到Hackathon Starter里。如果你需要完全的定制HTML與CSS，上面這些內容將幫助你。

快速提示是如何工作的？

快速提示（Flash messages）允許你在一個請求的結尾，以及當且僅當下一個請求之前顯示一段信息。比如，當登錄失敗時，你可以輸出一些警告信息，但一旦刷新頁面或者 再次進入登錄頁面后，這個警告信息不應該再次出現，它只會被顯示一次。本項目使用express-flash模塊來顯示快速提示，這個模塊在我創建 Hackathon Starter項目時就被包含在connect-flash里面。有了express-flash你無需發送快速提示到每一個視圖，它一開始就是可用的， 感謝express-flash。

使用快速提示需要兩個步驟。使用下面的代碼在你的控制器里創建一個快速提示：

req.flash('errors', { msg: 'Error messages goes here' } 

然后在你的視圖里顯示它們：

if messages.errors 
  .alert.alert-danger.fade.in 
    for error in messages.errors 
      div= error.msg 

在第一步里，'errors'是你定義的快速提示的名稱，它應該和你的視圖里的messages里的屬性名稱相匹配。將警告信息放在if message.errors以讓它們出錯時才顯示。錯誤信息采用{ msg: 'Error messages goes here' }的形式而不是像'Error messages goes here'一樣的字符串是為了一致性。express-validator模塊會驗證用戶的輸入，當發生錯誤時返回一個數組對象，每個對象都含有一個msg屬性。下面是express-validator所返回信息的一個示例：

[ 
  { param: "name", msg: "Name is required", value: "<received input>" }, 
  { param: "email", msg: "A valid email is required", value: "<received input>" } 
] 

如果使用字符串，你會發現信息框里面是空的。上面的錯誤信息也可以應用在info或者success的場合。

partials/flash.jade是控制快速提示格式化顯示的子模板。它使用一個叫做DRY的方法，將散落在各個視圖的快速提示歸到一處。

和導航欄與footer子模板一樣，flash子模板被包含在layout.jade里。

body 
  #wrap 
    include partials/navigation 
    .container 
      include partials/flash 
      block content 
  include partials/footer 

如何創建一個新頁面？

更正確的說法應該是“如何創建一個新路由”。主文件app.js包含所有的路由，每一個路由都伴隨著一個callback函數，你會在某些路由里發 現3個以上的參數，在這種情況里，第一個參數仍然是URL字符串，中間的參數是中間件，你可以將它們想象成門禁，如果它阻止你前進，你將不能得到 callback函數。一個例子是需要認證的路由：

app.get('/account', passportConf.isAuthenticated, userController.getAccount); 

它的順序總是從左到右。當用戶訪問/account頁面，isAuthenticated中間件將檢查用戶是否認證：

exports.isAuthenticated = function(req, res, next) { 
  if (req.isAuthenticated()) { 
    return next(); 
  } 
  res.redirect('/login'); 
}; 

如果認證檢查通過，你通過呼叫return next()的方式讓用戶通過門禁。它會依次通過剩下的中間件直到最后一個參數，即callback函數，它通常在接受到GET請求時渲染頁面，或在收到 POST請求時跳轉頁面。在這個例子里，你將被跳轉到用戶賬號管理頁面，如果認證沒有通過，你將被跳轉到登錄頁面。

exports.getAccount = function(req, res) { 
  res.render('account/profile', { 
    title: 'Account Management' 
  }); 
}; 

Express.js里有app.get、app.post、app.put、app.delete四種HTTP動作。但在大多數情況你只需要前兩種，除非你想創建一個RESTful API。如果你只想顯示一個頁面，使用GET，如果你想提交表單，使用POST。

下面是一個添加路由到你的app里的典型工作流。我們的目的是創建一個頁面顯示數據庫里的書籍列表。

第一步：定義一個路由。

app.get('/books', bookController.getBooks); 

在express 4.0以上你可以這樣定義你的路由：

app.route('/books') 
  .get(bookController.getBooks) 
  .post(bookController.createBooks) 
  .put(bookController.updateBooks) 
  .delete(bookController.deleteBooks) 

而下面是一個需要認證中間件的路由：

app.route('/api/twitter') 
  .all(passportConf.isAuthenticated) 
  .all(passportConf.isAuthorized) 
  .get(apiController.getTwitter); 
  .post(apiController.postTwitter) 

上面三種方式都是可接受的，你可以使用它們中的任何一種。我認為app.route里HTTP動詞的這種鏈式寫法非常干凈優雅，不過缺點是當每個路由占一行的時候，你不能一眼看到所有的動作。

第二步：創建一個叫book.js的新控制器文件。

/** 
 * GET /books 
 * List all books. 
 */ 
 
exports.getBooks = function(req, res) { 
  Book.find(function(err, docs) { 
    res.render('books', { books: docs }); 
  }); 
}; 

第三步：將控制器加入到app.js里。

var bookController = require('./controllers/book'); 

第四步：創建book.jade模板。

extends layout 
 
block content 
  .page-header 
    h3 All Books 
 
  ul 
    for book in books 
      li= book.name 

到這里就完成了。

當然，你可以將1到3步合在一起放到app.js里：

app.get('/books', function(req, res) { 
  Book.find(function(err, docs) { 
    res.render('books', { books: docs }); 
  }); 
}); 

是的，這樣更簡單些，但當你在app.js中加入1000行代碼時，瀏覽起來會變得比較麻煩。這個項目的初衷本來就是為了分解關注點，這樣你可以與你的隊員一起工作而不是忙碌于解決沖突。

上面的內容就是一切了，Express.js非常易于使用。大部分時間其實用在處理其他API，讓它們來干真正的工作，比如查詢數據庫的Mongoose，使用websocket收發信息的socket.io，發送郵件的 Nodemailer，表單驗證的express-validator 庫，以及處理web頁面的Cheerio 等。

如何在Hackathon Starter里使用Socket.io？

Dan Stroot曾提交了一個非常棒的pull以在Hackathon Starter里添加一個實時的儀表盤。但我認為它違反了非特定化的原則，因此并未接受。但你仍然可以在Hackathon Starter里使用Socket.io。下面是一般的操作步驟。

npm install socket.io --save 

將var app = express();替換為下面的代碼：

var app = express(); 
var http = require('http'); 
var server = http.createServer(app); 
var io = require('socket.io').listen(server); 

將下面的代碼添加到app.js的末尾：

io.configure(function() { 
  io.set('transports', ['websocket']); 
}); 
 
io.sockets.on('connection', function(socket) { 
  socket.emit('greet', { hello: 'Hey, Mr.Client!' }); 
  socket.on('respond', function(data) { 
    console.log(data); 
  }); 
  socket.on('disconnect', function() { 
    console.log('Socket disconnected'); 
  }); 
}); 

最后，將

app.listen(app.get('port'), function() { 

改為

server.listen(app.get('port'), function() { 

后端的工作到這里就完成了。

你有兩種方式將前端部分的js加到app中，一種是直接加到layout.jade中，將下面的代碼加到head塊中。

script(src='/socket.io/socket.io.js') 
script. 
    var socket = io.connect(window.location.href); 
    socket.on('greet', function (data) { 
      console.log(data); 
      socket.emit('respond', { message: 'Hello to you too, Mr.Server!' }); 
    }); 

注意代碼中socket.io的路徑，你并不需要實際的在項目中包含socket.io.js，它將在運行時自動生成。

另一種方法是將js部分加入到獨立的的main.js文件中，并將它們包含在jQuery的ready函數下。

$(document).ready(function() { 
 
  // Place JavaScript code here... 
  var socket = io.connect(window.location.href); 
  socket.on('greet', function (data) { 
    console.log(data); 
    socket.emit('respond', { message: 'Hello to you too, Mr.Server!' }); 
  }); 
 
}); 

到這里所有工作就完成了。

這里有一個實時儀表盤的在線演示。你可以查看這里它是如何添加到工程里的。

Mongoose Cheatsheet

查詢所有用戶：

User.find(function(err, users) { 
  console.log(users); 
}); 

通過email查詢用戶：

var userEmail = 'example@gmail.com'; 
User.findOne({ email: userEmail }, function(err, user) { 
  console.log(user); 
}); 

查詢5個最近的用戶賬號：

User 
  .find() 
  .sort({ _id: -1 }) 
  .limit(5) 
  .exec(function(err, users) { 
    console.log(users); 
  }); 

從所有文檔中查詢指定列的總數：

假設每個用戶有一個叫做votes的列，你希望統計所有用戶的votes總數。一個笨辦法是循環查找所有的文檔并手動的將結果加起來。另一個方法是使用MongoDB Aggregation Framework 來代替：

User.aggregate({ $group: { _id: null, total: { $sum: '$votes' } } }, function(err, votesCount) { 
  console.log(votesCount.total); 
}); 

應用部署（略過）

本部分介紹了應用MongoLab、Heroku、OpenShift等在線服務來部署應用，由于網絡環境的不同，在國內可能難以用到，所以不予翻譯。

（正文完）

譯者注：翻譯完成后覺得Hackathon Starter的確是個好東西，不過就像這篇文章所說的，每個開發者都需要有自己的Project Starter，這個Hackathon Starter也不適合直接拿來用，吃透它，將它本地化才是最好的做法。