做Node.js后端的朋友遲早要跟koa打交道。如果你一直用Express寫接口大概能理解那種感覺(jué)回調(diào)地獄雖然被Promise緩解了但中間件體系還是不夠順手每個(gè)業(yè)務(wù)里都夾著一堆模板代碼。koa從2015年前后進(jìn)入大家視野喊出的口號(hào)是“小而美”——它不像Express那樣把路由、模板引擎、靜態(tài)服務(wù)都內(nèi)置進(jìn)去而是只提供一個(gè)極簡(jiǎn)的HTTP服務(wù)內(nèi)核剩下的路由、參數(shù)解析、跨域、日志全部交給社區(qū)中間件自由組合。這篇文章不是官方文檔的復(fù)讀我按自己從零上手到上線維護(hù)的真實(shí)路徑把安裝節(jié)點(diǎn)、中間件洋蔥模型、路由與參數(shù)、統(tǒng)一錯(cuò)誤處理、PM2部署這些環(huán)節(jié)串一遍順便把我在實(shí)際開發(fā)里踩過(guò)的坑和排查思路寫出來(lái)。讀完你不僅能跑起一個(gè)koa項(xiàng)目還能知道每行代碼為什么這么寫。1. koa到底解決了什么問(wèn)題Express太啰嗦異步太難受1.1 回調(diào)地獄與“中間件流水線”的舊困擾Node.js剛火那幾年Express是絕對(duì)的主流一個(gè)接口常常長(zhǎng)這樣app.get(/user/:id, function (req, res, next) { User.findById(req.params.id, function (err, user) { if (err) return next(err); res.json({ data: user }); }); });單看這一段還好但真實(shí)業(yè)務(wù)里往往要查數(shù)據(jù)庫(kù)、調(diào)遠(yuǎn)程接口、寫緩存、記日志層層嵌套之后就變成了傳說(shuō)中的“金字塔代碼”一屏都放不下改起來(lái)更是膽戰(zhàn)心驚。后來(lái)社區(qū)用Promise和async/await做了不少補(bǔ)救但Express的中間件模型還是callback那一套你在async函數(shù)里拋出的異常不一定能被框架捕獲往往要自己包一層try/catch。koa的核心思路就是把中間件函數(shù)全部統(tǒng)一成async函數(shù)形態(tài)讓異常能順著Promise鏈往上傳配合統(tǒng)一的error事件就能全局兜底。用koa寫同樣的查詢接口代碼大概長(zhǎng)這樣router.get(/user/:id, async (ctx) { const user await User.findById(ctx.params.id); ctx.body { data: user }; });沒(méi)有next(err)傳參沒(méi)有res.json手動(dòng)封裝await完了直接塞給ctx.body整個(gè)讀起來(lái)和同步代碼差不多這對(duì)長(zhǎng)期維護(hù)來(lái)說(shuō)帶來(lái)的體驗(yàn)提升是肉眼可見的。1.2 koa的設(shè)計(jì)取舍小而精把選擇還給你koa的源碼壓縮后很小核心只干了三件事封裝req/res為統(tǒng)一的ctx對(duì)象、維護(hù)中間件數(shù)組、啟動(dòng)HTTP服務(wù)。沒(méi)有路由沒(méi)有模板引擎沒(méi)有靜態(tài)文件處理。我第一次看到也愣了一下連路由都要自己裝會(huì)不會(huì)太簡(jiǎn)陋恰恰是這個(gè)“簡(jiǎn)陋”給了項(xiàng)目很強(qiáng)的自由度。Express把東西都內(nèi)置好了看似方便但上了復(fù)雜業(yè)務(wù)你會(huì)發(fā)現(xiàn)內(nèi)置的實(shí)現(xiàn)不一定符合口味想換一套卻要跟內(nèi)置模塊糾纏。koa反過(guò)來(lái)默認(rèn)給一個(gè)空殼你按項(xiàng)目需要自己拼接口項(xiàng)目裝koa/router和koa-bodyparser帶頁(yè)面的裝koa-static和koa-views要鑒權(quán)裝koa-session或自己寫JWT中間件。項(xiàng)目大的時(shí)候依賴清單本身就是一張架構(gòu)圖。當(dāng)然koa也繼承了Node.js生態(tài)的“野性”——選型你得自己負(fù)責(zé)裝錯(cuò)了中間件得自己排查。這也意味著如果你想長(zhǎng)期靠Node.js吃飯搞懂每一層是怎么拼起來(lái)的反而比用全家桶框架學(xué)到的底層原理更多。1.3 koa與Express核心差異速覽對(duì)比維度Expresskoa內(nèi)核體積較大內(nèi)置路由/靜態(tài)/視圖等極小核心只有中間件機(jī)制中間件模型線性流水線next進(jìn)入下一層洋蔥模型支持中間件“進(jìn)入—返回”的雙階段處理異步風(fēng)格兼容callback、Promise、async原生async/await異常沿Promise鏈傳遞錯(cuò)誤處理next(err)逐層傳遞容易漏app.on(error)全局兜底路由內(nèi)置需安裝koa/router適用場(chǎng)景傳統(tǒng)MVC、老項(xiàng)目、快速原型輕量API服務(wù)、中后臺(tái)、微服務(wù)中的單個(gè)服務(wù)我在實(shí)際項(xiàng)目里兩種框架都維護(hù)過(guò)體感最強(qiáng)烈的不在語(yǔ)法細(xì)節(jié)而在“想做一個(gè)全局處理時(shí)的手感”。比如統(tǒng)一接口響應(yīng)格式、統(tǒng)一記錄請(qǐng)求耗時(shí)koa的中間件因?yàn)檠笫[模型的存在能很容易地在請(qǐng)求進(jìn)來(lái)時(shí)計(jì)時(shí)、等整條鏈跑完再寫日志而Express要做到類似效果得靠中間件排列順序加上res的finish事件去配合麻煩不少。2. 環(huán)境準(zhǔn)備Node.js版本怎么選安裝時(shí)我踩過(guò)的坑2.1 版本選擇LTS優(yōu)先別碰奇數(shù)字先說(shuō)結(jié)論日常開發(fā)和部署選Node.js偶數(shù)版本里的LTS也就是長(zhǎng)期支持版。寫這篇文章時(shí)主流生產(chǎn)版本是20.x和22.x如果你是新項(xiàng)目又沒(méi)有特殊依賴直接裝20或22都不會(huì)錯(cuò)。這里有一個(gè)不少剛接觸Node.js的人會(huì)犯的迷糊官網(wǎng)上寫著Current的奇數(shù)字版本比如23.x、24.x看起來(lái)是最新的但它的定位是“當(dāng)前迭代版”每六個(gè)月就換一輪API還在變動(dòng)第三方原生模塊的兼容性也可能跟不上拿來(lái)做生產(chǎn)環(huán)境是給自己找麻煩。我在把測(cè)試服務(wù)器升級(jí)到24.x的時(shí)候就遇到過(guò)某個(gè)舊版node-sass的原生模塊編譯失敗查了半天才發(fā)現(xiàn)是Node版本太新那個(gè)庫(kù)還沒(méi)跟上。后來(lái)我給自己定了個(gè)規(guī)矩開發(fā)機(jī)可以留一份最新的Current用來(lái)嘗鮮但項(xiàng)目里的package.json寫清e(cuò)ngines字段指定只允許LTS版本運(yùn)行避免同事機(jī)器上版本五花八門。2.2 Ubuntu、Windows、macOS三條安裝路徑的記錄不同平臺(tái)的安裝方式不一樣但核心建議只有一個(gè)用版本管理器不要直接去官網(wǎng)下載二進(jìn)制包。官網(wǎng)下載解壓就能用的方式對(duì)一次性環(huán)境沒(méi)問(wèn)題缺點(diǎn)是想切版本很痛苦只能手動(dòng)改環(huán)境變量路徑。我用得最多的是nvmNode Version ManagerLinux和macOS裝好后兩條命令就能搞定curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install --ltsWindows上沒(méi)有原版nvm社區(qū)維護(hù)的nvm-windows同樣好用裝完后執(zhí)行nvm install 22再nvm use 22就切過(guò)去了。這里有個(gè)小細(xì)節(jié)安裝完nvm后如果執(zhí)行node -v找不到命令多半是終端沒(méi)有重新加載配置文件手動(dòng)source ~/.bashrc或者干脆重開一個(gè)終端窗口就行。Ubuntu用戶經(jīng)常做的第一反應(yīng)是apt install nodejs我勸你多留個(gè)心眼。Ubuntu軟件源里的nodejs版本通常比較舊安裝后node -v打出來(lái)可能是個(gè)古早版本連async/await支持都有問(wèn)題更別說(shuō)跑koa。如果你不打算用nvm也可以從Node.js官網(wǎng)下載官方編譯好的LTS包解壓后把bin目錄加進(jìn)PATH比如追加到/etc/profile.d下的腳本里。2.3 “版本號(hào)尚未發(fā)布”這類報(bào)錯(cuò)的排查思路搜索熱詞里有一條報(bào)錯(cuò)很典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。這個(gè)我之前也遇到過(guò)明明官網(wǎng)上有這個(gè)版本號(hào)nvm卻提示“尚未發(fā)布”或者“不可用”很多人第一反應(yīng)是網(wǎng)絡(luò)問(wèn)題其實(shí)大概率是nvm的遠(yuǎn)端版本列表緩存太舊本地還沒(méi)同步到最新發(fā)布信息。解決辦法也不復(fù)雜。如果版本確實(shí)已經(jīng)發(fā)布先刷新nvm的版本列表再安裝nvm ls-remote nvm install 24.21.0ls-remote會(huì)重新拉取官方版本索引拉不下來(lái)的時(shí)候再看是不是nvm本身版本太老建議先升級(jí)nvm本體。還有另一種情況是版本號(hào)本身寫錯(cuò)比如把24.21.0打成了24.210這種復(fù)制粘貼時(shí)特別容易出核對(duì)官方版本列表就好。如果你只是為了跑koa完全沒(méi)必要追最新版本號(hào)穩(wěn)定的LTS版本遠(yuǎn)比“數(shù)字最大”重要。提示在開發(fā)機(jī)上裝好node后順手執(zhí)行npm -v確認(rèn)npm也正常。有些手動(dòng)安裝方式會(huì)把npm漏掉導(dǎo)致后續(xù)裝包全都失敗。3. 核心概念拆解ctx、中間件與洋蔥模型3.1 ctx一次請(qǐng)求里的“百寶袋”koa里每個(gè)請(qǐng)求都會(huì)生成一個(gè)獨(dú)立的ctx對(duì)象你可以把它理解成快遞員手里的那臺(tái)掃描終端里面既有包裹信息也有簽收界面。ctx上常見的屬性包括屬性作用典型用法ctx.request封裝的請(qǐng)求對(duì)象比原生req更好用ctx.request.query、ctx.request.bodyctx.response封裝的響應(yīng)對(duì)象ctx.response.status、ctx.response.set()ctx.params路由路徑參數(shù)來(lái)自routerctx.params.idctx.query查詢字符串解析結(jié)果訪問(wèn) /a?x1 時(shí)得到 { x: 1 }ctx.request.body請(qǐng)求體內(nèi)容一般由bodyparser填充讀取JSON請(qǐng)求體ctx.body快捷設(shè)置響應(yīng)體賦對(duì)象會(huì)自動(dòng)JSON序列化ctx.status快捷設(shè)置響應(yīng)狀態(tài)碼ctx.status 201ctx.state中間件之間傳遞數(shù)據(jù)的小倉(cāng)庫(kù)用戶鑒權(quán)后存user信息剛開始用koa的人容易在ctx.request.body和ctx.body之間犯迷糊。前者是從客戶端“拿進(jìn)來(lái)的”后者是要“送出去的”代表了兩個(gè)完全不同的方向。中間件鏈上往前傳遞數(shù)據(jù)則用ctx.state我在后面講鑒權(quán)時(shí)還會(huì)提到。3.2 用一段代碼看懂洋蔥模型koa的中間件機(jī)制網(wǎng)上叫“洋蔥模型”名字很形象。你往app.use里塞一堆a(bǔ)sync函數(shù)請(qǐng)求從最外層中間件進(jìn)入一路await next()往里走直到最后一個(gè)中間件處理完成再一層層返回。來(lái)直接看代碼const Koa require(koa); const app new Koa(); app.use(async (ctx, next) { console.log(1-請(qǐng)求進(jìn)入); await next(); console.log(1-請(qǐng)求返回); }); app.use(async (ctx, next) { console.log(2-請(qǐng)求進(jìn)入); ctx.body Hello Koa; await next(); console.log(2-請(qǐng)求返回); }); app.use(async (ctx) { console.log(3-處理業(yè)務(wù)); }); app.listen(3000);跑起來(lái)請(qǐng)求一次控制臺(tái)輸出順序是這樣的1-請(qǐng)求進(jìn)入 2-請(qǐng)求進(jìn)入 3-處理業(yè)務(wù) 2-請(qǐng)求返回 1-請(qǐng)求返回可以看到中間件代碼在await next()前后的部分會(huì)執(zhí)行兩次像剝洋蔥一樣進(jìn)去又出來(lái)。這個(gè)特性最實(shí)用的場(chǎng)景就是計(jì)時(shí)和統(tǒng)一的響應(yīng)封裝外層中間件在進(jìn)入時(shí)記錄startTime在返回前計(jì)算總耗時(shí)或者統(tǒng)一給響應(yīng)包一層結(jié)構(gòu)。如果用Express那套線性流水線想做這種“進(jìn)去又出來(lái)”的雙階段邏輯就得繞圈子。3.3 中間件設(shè)計(jì)的幾條實(shí)用原則第一個(gè)原則是中間件順序極度敏感。比如日志中間件必須排在路由之前否則路由已經(jīng)處理完響應(yīng)了日志根本來(lái)不及記錄。bodyparser也得在路由之前不然路由里讀不到ctx.request.body。第二個(gè)原則是“一個(gè)中間件只做一件事”。我見過(guò)有人把日志、鑒權(quán)、參數(shù)校驗(yàn)、業(yè)務(wù)處理全塞進(jìn)一個(gè)app.use里幾百行中間件看起來(lái)很“集中”實(shí)際上改一個(gè)功能容易碰壞另一個(gè)。把功能拆成一個(gè)一個(gè)幾十行的中間件調(diào)試時(shí)按順序注釋排查效率高很多。第三個(gè)原則是中間件內(nèi)的代碼盡量保持“同步感”。使用async函數(shù)后await之間的邏輯是順序的但如果你在中間件里又開setTimeout、又搞eventEmitter異常就很難被koa統(tǒng)一捕獲容易變成unhandledRejection。一句話把異步邊界收緊在await表達(dá)式范圍內(nèi)別讓邏輯跑到中間件調(diào)用棧外面去。4. 路由、參數(shù)與body解析從0寫一個(gè)真實(shí)接口4.1 路由選型與常見坑koa本身不帶路由目前最主流的選擇是koa/router它是koa-router的維護(hù)版功能上沒(méi)有本質(zhì)區(qū)別包名換了但API基本兼容。裝好之后先實(shí)例化再掛載到app上順序和中間件一樣敏感const Router require(koa/router); const router new Router({ prefix: /api }); router.get(/health, (ctx) { ctx.body { status: ok }; }); app.use(router.routes()); app.use(router.allowedMethods());allowedMethods()這一行很關(guān)鍵它會(huì)讓接口對(duì)不支持的方法自動(dòng)返回405或響應(yīng)Allow頭部比如只定義了get的地址收到POST請(qǐng)求就會(huì)被正確處理而不是流落到404。沒(méi)寫這行也不影響跑但接口語(yǔ)義就不完整。另一個(gè)坑是路徑前綴重復(fù)。比如頁(yè)面路由和接口路由都想用/user注冊(cè)順序后又沒(méi)有統(tǒng)一規(guī)劃請(qǐng)求很可能被第一個(gè)匹配的路由吞掉。我給每個(gè)子路由實(shí)例化時(shí)都會(huì)顯式寫死prefix這樣一眼就能看出哪些路徑屬于哪個(gè)模塊。4.2 參數(shù)怎么拿params、query和body接口開發(fā)里最常見的三類參數(shù)分別是路徑參數(shù)、查詢參數(shù)和請(qǐng)求體。路徑參數(shù)靠路由規(guī)則里的冒號(hào)定義router.get(/user/:id, (ctx) { ctx.body { id: ctx.params.id }; });查詢參數(shù)直接掛在URL后面比如/user/list?page1size10用ctx.query拿它會(huì)自動(dòng)解析成{ page: 1, size: 10 }。注意拿到的是字符串如果要做數(shù)值計(jì)算記得先用Number轉(zhuǎn)換或校驗(yàn)工具處理一下。請(qǐng)求體要分情況看。純GET接口一般不需要body但POST/PUT/PATCH發(fā)來(lái)的JSON、表單數(shù)據(jù)必須先經(jīng)過(guò)koa-bodyparser的解析才能在路由里讀取。裝好后在路由之前全局注冊(cè)const bodyParser require(koa-bodyparser); app.use(bodyParser());之后路由里就能這樣用router.post(/user, (ctx) { const { name, email } ctx.request.body; ctx.body { received: { name, email } }; });4.3 完整示例一套內(nèi)存版用戶接口為了展示“路由參數(shù)body響應(yīng)”的全鏈路我寫一個(gè)不依賴數(shù)據(jù)庫(kù)的用戶接口數(shù)據(jù)存在內(nèi)存數(shù)組里重啟丟失但夠用來(lái)理解流程。完整代碼長(zhǎng)這樣const Koa require(koa); const Router require(koa/router); const bodyParser require(koa-bodyparser); const app new Koa(); const router new Router({ prefix: /api/users }); const users []; let nextId 1; app.use(bodyParser()); router.get(/, (ctx) { ctx.body { list: users }; }); router.get(/:id, (ctx) { const id Number(ctx.params.id); const user users.find((u) u.id id); if (!user) ctx.throw(404, 用戶不存在); ctx.body { data: user }; }); router.post(/, (ctx) { const { name, email } ctx.request.body; if (!name || !email) ctx.throw(400, name和email不能為空); const user { id: nextId, name, email }; users.push(user); ctx.status 201; ctx.body { data: user }; }); router.put(/:id, (ctx) { const id Number(ctx.params.id); const user users.find((u) u.id id); if (!user) ctx.throw(404, 用戶不存在); const { name, email } ctx.request.body; if (name) user.name name; if (email) user.email email; ctx.body { data: user }; }); router.delete(/:id, (ctx) { const id Number(ctx.params.id); const index users.findIndex((u) u.id id); if (index -1) ctx.throw(404, 用戶不存在); users.splice(index, 1); ctx.status 204; }); app.use(router.routes()); app.use(router.allowedMethods()); app.listen(3000, () { console.log(server running at http://localhost:3000); });這套接口里用到了ctx.throw(400, xxx)這是koa內(nèi)置的快速拋錯(cuò)方式錯(cuò)誤會(huì)被后續(xù)的統(tǒng)一錯(cuò)誤處理接住。如果是小項(xiàng)目這個(gè)demo已經(jīng)是一份能商用的骨架了。真實(shí)項(xiàng)目只需要把內(nèi)存數(shù)組換成數(shù)據(jù)庫(kù)模型邏輯幾乎不用動(dòng)。5. 統(tǒng)一錯(cuò)誤處理與工程化結(jié)構(gòu)5.1 全局錯(cuò)誤處理中間件try/catch別散落一地新手寫koa最容易出現(xiàn)的一副畫面是每個(gè)接口里都包一層try/catch然后return一個(gè)錯(cuò)誤響應(yīng)。代碼一多錯(cuò)誤格式五花八門前端對(duì)接的時(shí)候想罵人。正確做法是統(tǒng)一在中間件頂層攔截異常。先在路由之前注冊(cè)一個(gè)錯(cuò)誤處理中間件app.use(async (ctx, next) { try { await next(); } catch (err) { ctx.status err.status || 500; ctx.body { code: err.status || 500, message: err.message || 服務(wù)器內(nèi)部錯(cuò)誤 }; ctx.app.emit(error, err, ctx); } });中間件里await next()之后的異常不管是從路由throw出來(lái)的還是數(shù)據(jù)庫(kù)查詢拋出的都會(huì)被這里攔住。有了這個(gè)兜底業(yè)務(wù)代碼里可以放心丟異常參數(shù)不對(duì)就ctx.throw(400, 參數(shù)錯(cuò)誤)用戶找不到就ctx.throw(404, 資源不存在)除非有特殊的裁剪需求否則接口里基本不需要手寫try/catch。ctx.app.emit(error, err, ctx)這行用于把原始錯(cuò)誤發(fā)到應(yīng)用層的error事件監(jiān)聽里。建議在入口處掛一個(gè)監(jiān)聽把error記錄到日志文件或日志平臺(tái)避免生產(chǎn)環(huán)境只看得到“500”卻沒(méi)有堆棧線索app.on(error, (err, ctx) { console.error(server error:, err); });5.2 404與業(yè)務(wù)錯(cuò)誤碼的約定koa默認(rèn)對(duì)沒(méi)匹配到路由的請(qǐng)求返回404響應(yīng)體是空的。對(duì)純接口項(xiàng)目我習(xí)慣在路由之后補(bǔ)一個(gè)兜底中間件讓連路由都沒(méi)匹配上的請(qǐng)求返回統(tǒng)一格式app.use((ctx) { ctx.status 404; ctx.body { code: 404, message: 接口不存在 }; });注意這段一定要放在router.routes()之后否則所有請(qǐng)求都會(huì)先被它攔截路由就失效了。另外業(yè)務(wù)上有時(shí)需要區(qū)分“HTTP狀態(tài)碼”和“業(yè)務(wù)錯(cuò)誤碼”比如登錄過(guò)期可以返回200但code為401此時(shí)字段名和語(yǔ)義需要文檔約定清楚。我常用的約定是HTTP狀態(tài)碼表達(dá)傳輸層狀態(tài)body里的code表達(dá)業(yè)務(wù)結(jié)果前端先看code再做分支。5.3 值得參考的目錄結(jié)構(gòu)項(xiàng)目無(wú)論大小我都不建議把所有路由寫在一個(gè)入口文件里。一個(gè)可維護(hù)性還不錯(cuò)的目錄結(jié)構(gòu)大概是這樣的src/ ├── app.js # koa實(shí)例、中間件裝配 ├── index.js # 入口啟動(dòng)服務(wù) ├── config/ │ └── index.js # 端口、環(huán)境變量集中配置 ├── middleware/ │ ├── errorHandler.js # 統(tǒng)一錯(cuò)誤處理 │ ├── responseTime.js # 響應(yīng)耗時(shí)統(tǒng)計(jì) │ └── auth.js # 登錄鑒權(quán) ├── routers/ │ ├── user.js │ └── order.js ├── controllers/ # 業(yè)務(wù)控制器處理req/res語(yǔ)義 │ ├── userController.js │ └── orderController.js ├── services/ # 業(yè)務(wù)邏輯層操作數(shù)據(jù)庫(kù)、調(diào)用外部API │ ├── userService.js │ └── orderService.js └── utils/ └── response.js # 統(tǒng)一響應(yīng)包裝函數(shù)分層的主線是路由只負(fù)責(zé)路徑和參數(shù)的映射controller做參數(shù)校驗(yàn)和響應(yīng)處理service做真正的業(yè)務(wù)邏輯middleware處理橫切關(guān)注點(diǎn)。小項(xiàng)目可以砍掉controller層但service和middleware的隔離建議保留后面加單元測(cè)試、加需求時(shí)能省很多事。6. 常見問(wèn)題與排查技巧實(shí)錄6.1 “ctx.body沒(méi)生效”一類問(wèn)題你在路由里明明寫了ctx.body { code: 0 }但用Postman一請(qǐng)求返回卻是404空響應(yīng)。遇到這種情況先檢查路由有沒(méi)有真的注冊(cè)到app上最常見的原因是app.use(router.routes())寫到了中間件列表的末端被某個(gè)前置的ctx.body xx搶先兜底了。再檢查路由的prefix和請(qǐng)求路徑是否拼錯(cuò)比如prefix是/api/users請(qǐng)求打的是/api/user路徑匹配不上自然走進(jìn)404。還有一個(gè)容易被忽略的點(diǎn)ctx.body賦值后如果又寫了ctx.status 204204按協(xié)議不允許響應(yīng)體瀏覽器會(huì)自動(dòng)丟棄body內(nèi)容哪怕你代碼里賦值了也看不到數(shù)據(jù)。6.2 中間件順序引發(fā)的連鎖反應(yīng)bodyparser順序不對(duì)是高頻問(wèn)題。bodyparser要放在路由中間件之前因?yàn)槁酚衫镆xctx.request.body。如果順序反了請(qǐng)求先被路由處理路由里拿到空body然后你把空數(shù)據(jù)存進(jìn)了數(shù)據(jù)庫(kù)回頭排查半天才發(fā)現(xiàn)是解析器還沒(méi)掛上。日志中間件也是一樣放路由后面的話路由都返回了日志代碼根本不會(huì)執(zhí)行到。我排查中間件順序時(shí)常用一個(gè)小技巧在每個(gè)app.use函數(shù)的開頭加一行臨時(shí)console.log(middleware A in)然后請(qǐng)求一次接口看控制臺(tái)輸出的順序和預(yù)期一不一致。定位完再刪掉日志比對(duì)著代碼猜快得多。6.3 async異常不輸出日志的坑koa能捕獲的是中間件Promise鏈上的異常但如果在中間件里用了不帶await的異步操作比如app.use((ctx, next) { setTimeout(() { throw new Error(boom); }, 100); return next(); });setTimeout里拋出的錯(cuò)誤koa根本接不住也不會(huì)出現(xiàn)在app.on(error)里最終變成unhandledRejection在有些Node版本下進(jìn)程還會(huì)直接崩掉。排查這種問(wèn)題的方法是在進(jìn)程級(jí)別掛上兜底監(jiān)聽至少讓你知道發(fā)生了什么process.on(unhandledRejection, (err) { console.error(unhandledRejection:, err); });但根因還得靠代碼規(guī)范中間件里的異步操作一律用await或把回調(diào)Promise化絕不讓異常脫離中間件的調(diào)用鏈。6.4 其他高頻問(wèn)題速查表現(xiàn)象最常見原因處理建議端口被占用啟動(dòng)報(bào)EADDRINUSE上一個(gè)進(jìn)程沒(méi)退出lsof -i:3000找到PID并kill或改用其他端口請(qǐng)求對(duì)象返回的是字符串而不是JSON手動(dòng)設(shè)置了Content-Type或ctx.body直接賦字符串給ctx.body賦對(duì)象即可koa會(huì)自動(dòng)設(shè)置application/jsonPOST請(qǐng)求讀取不到ctx.request.body沒(méi)掛koa-bodyparser或掛載順序在路由之后在路由之前app.use(bodyParser())接口突然404路由未注冊(cè)、路由前綴拼錯(cuò)、兜底中間件放錯(cuò)位置用中間件日志定位是否有進(jìn)入router.routes()外部POST請(qǐng)求跨域被攔沒(méi)配置CORS中間件使用koa/cors并設(shè)置允許的來(lái)源日志時(shí)間比本地時(shí)間差8小時(shí)服務(wù)器默認(rèn)UTC時(shí)區(qū)在日志配置中顯式指定時(shí)區(qū)或統(tǒng)一轉(zhuǎn)換7. 上線部署與性能優(yōu)化要點(diǎn)7.1 PM2守護(hù)進(jìn)程別讓進(jìn)程自己死掉koa應(yīng)用本質(zhì)上就是一個(gè)Node進(jìn)程上線時(shí)如果直接node src/index.js掛著一旦進(jìn)程崩潰服務(wù)就完全不可用了。我平時(shí)用的是PM2做進(jìn)程守護(hù)簡(jiǎn)單配置如下npm install -g pm2 pm2 start src/index.js --name my-koa-app pm2 save pm2 startuppm2 startup會(huì)生成一條開機(jī)自啟命令讓服務(wù)器重啟后進(jìn)程自動(dòng)拉起。PM2還自帶日志和監(jiān)控面板pm2 logs看實(shí)時(shí)輸出pm2 monit看CPU和內(nèi)存。多核機(jī)器上建議開cluster模式讓進(jìn)程按CPU核心數(shù)復(fù)制起來(lái)充分利用多核性能pm2 start src/index.js -i max --name my-koa-app不過(guò)開了cluster模式后要注意session和內(nèi)存數(shù)據(jù)不再共享如果代碼里有內(nèi)存緩存或者WebSocket連接會(huì)繞出跨進(jìn)程一致性的問(wèn)題。所以我的建議是接口純無(wú)狀態(tài)才放心用cluster否則先單進(jìn)程跑瓶頸到了再去加架構(gòu)上的復(fù)雜度。7.2 環(huán)境變量與運(yùn)行模式端口號(hào)、數(shù)據(jù)庫(kù)連接串、密鑰這類配置不適合寫死在代碼里用環(huán)境變量讀取是最基本的工程習(xí)慣。代碼里這樣寫const port process.env.PORT || 3000; const env process.env.NODE_ENV || development;PM2啟動(dòng)時(shí)通過(guò)env字段或命令行傳入環(huán)境變量開發(fā)環(huán)境、測(cè)試環(huán)境、生產(chǎn)環(huán)境用不同的配置避免把本地配置帶到線上。還有個(gè)細(xì)節(jié)生產(chǎn)環(huán)境一定要設(shè)置NODE_ENVproduction很多庫(kù)的日志詳細(xì)度、內(nèi)存用量都依賴這個(gè)值koa本身雖然不直接看它但它會(huì)影響你調(diào)用的其他中間件的表現(xiàn)。7.3 Nginx反向代理下要注意的細(xì)節(jié)實(shí)際部署很少讓Node直接暴露80端口對(duì)外訪問(wèn)一般前端是Nginx做反代把接口請(qǐng)求轉(zhuǎn)發(fā)給Node進(jìn)程。配置大概長(zhǎng)這樣server { listen 80; server_name example.com; location /api/ { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }這時(shí)候如果代碼里需要獲取用戶真實(shí)IP直接用ctx.request.ip會(huì)拿到Nginx的內(nèi)網(wǎng)地址需要在koa入口設(shè)置一句app.proxy true讓框架信任X-Forwarded-For頭再去讀ctx.request.ip才是真實(shí)用戶IP。出于安全考慮這一句只在確認(rèn)只有Nginx能把請(qǐng)求打到應(yīng)用時(shí)才開否則客戶端偽造請(qǐng)求頭會(huì)導(dǎo)致IP記錄失真。8. 最后關(guān)于koa的一些真實(shí)體驗(yàn)8.1 什么時(shí)候該用koa什么時(shí)候別用做過(guò)幾個(gè)項(xiàng)目的橫向?qū)Ρ群笪椰F(xiàn)在的選型標(biāo)準(zhǔn)比較固定面向接口開發(fā)、團(tuán)隊(duì)熟悉異步編程、項(xiàng)目需要靈活定制中間件的koa是很好的選擇。如果你的項(xiàng)目本身是傳統(tǒng)的服務(wù)端渲染頁(yè)面要模板引擎、要靜態(tài)資源托管、要現(xiàn)成的MVC結(jié)構(gòu)Express能讓你更快落地。如果你要的是一個(gè)全家桶框架自帶ORM、鑒權(quán)、定時(shí)任務(wù)、微服務(wù)協(xié)同那要去看NestJS這類重框架koa這類輕量?jī)?nèi)核需要你自行拼裝的部分會(huì)太多。koa還有一個(gè)隱藏優(yōu)勢(shì)是學(xué)習(xí)成本曲線。它核心概念就那么幾個(gè)源碼也短新手啃一遍中間件機(jī)制后對(duì)Node異步理解會(huì)加深不少這種底子對(duì)后面接觸NestJS、寫AWS Lambda函數(shù)等都是保值資產(chǎn)。8.2 我從實(shí)踐中總結(jié)的幾條經(jīng)驗(yàn)第一中間件一定要保持“薄”。我在代碼審查時(shí)看到過(guò)長(zhǎng)到幾百行的app.use函數(shù)里面塞了十幾件事這種代碼看起來(lái)也能跑但以后任何人都不敢動(dòng)它。一個(gè)中間件只做一件事做完了就把控制權(quán)交給下一個(gè)這是koa最優(yōu)雅的用法。第二路由層級(jí)和模塊邊界要在項(xiàng)目最開始就定好。prefix一旦在多個(gè)模塊里用起來(lái)后續(xù)想改路徑是牽一發(fā)動(dòng)全身的事。我吃過(guò)一次虧前后端聯(lián)調(diào)時(shí)發(fā)現(xiàn)前端所有接口都寫的是/api/v1/...而后端路由是/api/...最后只能加一層路徑重定向兜底雖然解決了問(wèn)題但顯得很丑。第三遇到奇怪問(wèn)題先懷疑順序再懷疑緩存。koa的中間件順序和bodyparser掛載順序是新手翻車的第一大來(lái)源什么奇奇怪怪的“數(shù)據(jù)讀不到”“日志不打印”十有八九是順序問(wèn)題。排掉順序之后再考慮是不是舊進(jìn)程沒(méi)殺掉、端口被老服務(wù)占著、npm緩存了舊包這幾種排查路徑基本能覆蓋日常開發(fā)里近八成的幺蛾子。