用 C 寫 Web 服務(wù)實(shí)戰(zhàn)二路由進(jìn)階、中間件鏈與文件上傳上一篇我們搭起了一個(gè)能跑的 Web 應(yīng)用骨架——監(jiān)聽端口、注冊(cè) JSON 路由、綁定靜態(tài)目錄、開啟多事件循環(huán)、寫了一個(gè)文件日志中間件。這篇在這個(gè)骨架之上繼續(xù)往上蓋路由參數(shù)與通配符、中間件鏈的深度使用、請(qǐng)求體流式接收與文件上傳。讀完這篇你的 C Web 應(yīng)用就能處理真實(shí)業(yè)務(wù)了。一、路由進(jìn)階不止是app.get(/hello)上篇只用了最簡(jiǎn)單的精確匹配路由。實(shí)際業(yè)務(wù)中你需要從 URL 中提取參數(shù)、匹配前綴、區(qū)分 HTTP 方法。uvcpp_web_router提供的模式路由覆蓋了這些場(chǎng)景匹配優(yōu)先級(jí)為靜態(tài) 參數(shù) 通配。1.1 路徑參數(shù)/user/:idapp.get(/user/:id,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){conststd::string*idreq.param(id);resp.text(id!nullptr?*id:std::string());resp.end();});req.param(id)返回的是const std::string*參數(shù)不存在時(shí)返回nullptr——這比返回空字符串更明確不會(huì)把“參數(shù)沒傳”和“參數(shù)是空串”混在一起[reference:0]。多個(gè)參數(shù)可以混搭app.get(/api/v:version/users/:uid/posts/:pid,handler);1.2 通配符/files/*path*path匹配一段或多段路徑捕獲的內(nèi)容同樣通過req.param(path)獲取app.get(/files/*path,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){conststd::string*preq.param(path);// 請(qǐng)求 /files/docs/readme.txt → p docs/readme.txtresp.text(你請(qǐng)求了: *p);resp.end();});通配符至少吃一段。/files/*path匹配/files/a但不匹配/files——如果連前綴本身也要處理需要單獨(dú)注冊(cè)/files的路由。serve_static內(nèi)部就是靠這個(gè)機(jī)制工作的[reference:1]。1.3 HTTP 方法app.get()、app.post()、app.put()、app.del()分別注冊(cè)對(duì)應(yīng)方法的路由。同一個(gè)路徑可以注冊(cè)多個(gè)方法uvcpp_web_router會(huì)正確區(qū)分app.get(/resource,get_handler);app.post(/resource,post_handler);當(dāng)請(qǐng)求方法不匹配已注冊(cè)的路由時(shí)框架自動(dòng)返回 405 并填充Allow頭OPTIONS請(qǐng)求自動(dòng)生成允許的方法列表。這些語義是框架保證的不需要你手寫[reference:2]。二、中間件鏈Express 風(fēng)格的next()模型上篇的日志中間件已經(jīng)展示了.use()的基本用法。這一節(jié)深入中間件鏈的執(zhí)行模型。2.1 中間件就是“會(huì)調(diào) next() 的 handler”uvcpp_web_middlewareauth_middleware(){return[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){conststd::string*tokenreq.header(Authorization);if(tokennullptr||!verify_token(*token)){resp.status(401).json_str({\error\:\unauthorized\});resp.end();return;// 不調(diào) next()鏈到此結(jié)束}next();// 放行進(jìn)入下一個(gè)中間件或路由 handler};}中間件和路由 handler 的類型完全相同uvcpp_web_handler。區(qū)別只在行為不調(diào)next()就是這一環(huán)直接結(jié)束鏈不再往下走[reference:3]。2.2 執(zhí)行順序與“前后包裹”.use()的注冊(cè)順序就是執(zhí)行順序。next()調(diào)用之前的代碼在“請(qǐng)求進(jìn)入”階段執(zhí)行之后的代碼在“響應(yīng)完成”階段執(zhí)行——這是 Express/Koa 的經(jīng)典洋蔥模型app.use([]{/* ① 請(qǐng)求進(jìn)入 */next();/* ③ 響應(yīng)完成后 */});app.use([]{/* ② 請(qǐng)求進(jìn)入 */next();/* ② 響應(yīng)完成后 */});app.get(/x,handler);// ④ 最后執(zhí)行上篇的日志中間件正是利用了這個(gè)特性next()之前記錄時(shí)間戳之后記錄狀態(tài)碼。2.3 異步中間件與hold()/release()如果中間件需要做異步操作查數(shù)據(jù)庫、調(diào)外部 API不能直接next()后返回——框架可能在這一環(huán)還沒完成時(shí)就結(jié)束了請(qǐng)求。uvcpp_web_context提供hold()和release()來顯式聲明“我還沒完成”app.use([](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){uvcpp_web_context*ctxreq.context();ctx-hold();// 告訴框架這一環(huán)還在進(jìn)行中別往下走// 異步操作比如查數(shù)據(jù)庫do_async_query(req.path(),[ctx,next](boolallowed){if(allowed){ctx-release();// 解除 holdnext();// 放行}else{// 拒絕請(qǐng)求ctx-release();// ...寫響應(yīng)...}});});hold()的本質(zhì)是給上下文加一個(gè)引用計(jì)數(shù)release()減一。計(jì)數(shù)歸零時(shí)框架才認(rèn)為這一環(huán)完成。這在異步中間件中是必須的——不 hold 直接返回框架會(huì)在異步回調(diào)執(zhí)行前就結(jié)束請(qǐng)求。2.4 內(nèi)置中間件libuvcpp 自帶了一些常用中間件app.use(web_middleware_access_log());// 訪問日志app.use(web_middleware_cors());// CORS 跨域web_middleware_access_log()會(huì)寫框架標(biāo)準(zhǔn)格式的訪問日志。但如果你需要自定義格式比如上篇那樣輸出到本地文件自己寫中間件更靈活。web_middleware_cors()處理跨域預(yù)檢請(qǐng)求和Access-Control-*頭前端調(diào)試時(shí)很省心。2.5 中間件掛載建議推薦的注冊(cè)順序// 1. 日志最先注冊(cè)記錄一切app.use(my_log_middleware());// 2. CORS在鑒權(quán)之前預(yù)檢請(qǐng)求不應(yīng)被鑒權(quán)攔截app.use(web_middleware_cors());// 3. 鑒權(quán)app.use(auth_middleware());// 4. 業(yè)務(wù)路由app.get(/api/...,handler);// 5. 靜態(tài)文件最后注冊(cè)避免攔截 API 路由app.serve_static(/assets,./public);三、請(qǐng)求體流式接收默認(rèn)情況下框架會(huì)把整個(gè)請(qǐng)求體緩沖在內(nèi)存中handler 觸發(fā)時(shí)req.body()已經(jīng)完整可用。這對(duì)于小體積 JSON 或表單請(qǐng)求完全夠用。但大文件上傳或流式數(shù)據(jù)不能走這條路——一個(gè) 1 GB 的上傳會(huì)把整個(gè)請(qǐng)求體拉進(jìn)內(nèi)存。uvcpp_web_stream提供了流式接收能力通過on_data/on_end回調(diào)逐塊處理請(qǐng)求體app.post(/upload/stream,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){auto*streamreq.stream();stream-on_data([](constchar*data,size_t len){// 逐塊到達(dá)的數(shù)據(jù)可以直接寫入磁盤或做增量處理// 注意data 只在回調(diào)期間有效需要持久化就拷貝或立刻寫入});stream-on_end([](){// 請(qǐng)求體全部接收完畢});// 流式模式下handler 返回后框架不會(huì)自動(dòng)結(jié)束請(qǐng)求// 需要在 on_end 中調(diào)用 resp.end()});stream-pause()和stream-resume()可以在消費(fèi)端忙不過來時(shí)暫停接收形成背壓。這在寫入磁盤較慢的場(chǎng)景下很有用——暫停接收比在內(nèi)存中無限堆積要安全得多。四、文件上傳multipart 流式落盤uvcpp_web_upload/uvcpp_web_multipart構(gòu)建在流式接收之上專門處理multipart/form-data請(qǐng)求。4.1 基本用法app.post(/upload,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){auto*uploadreq.upload();// 設(shè)置落盤目錄和大小上限upload-set_upload_dir(./uploads);upload-set_max_file_size(50*1024*1024);// 單文件 50 MBupload-set_max_total_size(200*1024*1024);// 總大小 200 MBupload-on_file([](constuvcpp_web_uploaded_filefile){// 每個(gè)文件落盤完成后觸發(fā)// file.field_name —— 表單字段名// file.original_name —— 原始文件名// file.saved_path —— 實(shí)際保存路徑隨機(jī)葉子名// file.size —— 文件大小});upload-on_end([resp](){resp.json_str({\status\:\ok\});resp.end();});upload-on_error([](interr){// 上傳過程中出錯(cuò)超限、磁盤寫入失敗等});});4.2 大小限制與安全策略u(píng)vcpp_web_upload內(nèi)置了六條大小上限分別覆蓋限制項(xiàng)作用單文件大小防止單個(gè)超大文件打滿磁盤總請(qǐng)求大小防止大量小文件組合成 DoS文件數(shù)量防止 multipart 邊界攻擊字段名長(zhǎng)度防止超長(zhǎng)字段名消耗內(nèi)存文件名長(zhǎng)度同上part 頭部大小防止畸形 multipart 頭落盤策略是隨機(jī)葉子名 流式寫入文件名在服務(wù)端生成隨機(jī)名不使用客戶端提供的原始文件名作為磁盤路徑——這直接封死了路徑穿越攻擊../../etc/passwd這類。原始文件名只作為元數(shù)據(jù)保留在original_name中。4.3 與流式接收的區(qū)別場(chǎng)景用uvcpp_web_stream用uvcpp_web_uploadraw body 流式處理??multipart 表單??需要解析字段名/文件名??自己控制落盤邏輯??框架落盤如果上傳的是非 multipart 格式的原始數(shù)據(jù)比如直接 PUT 一個(gè)文件用uvcpp_web_stream自己處理如果是標(biāo)準(zhǔn) HTML 表單上傳用uvcpp_web_upload更省事。五、請(qǐng)求對(duì)象操作速查uvcpp_web_request封裝了日常業(yè)務(wù)最常用的訪問方式// 方法 路徑req.method()// http_method 枚舉req.method_str()// GET / POST ...req.path()// /user/123req.query()// 查詢串不含 ?// 路徑參數(shù)req.param(id)// const std::string*// 查詢串參數(shù)req.query_param(page)// const std::string*// 請(qǐng)求頭req.header(Content-Type)// const std::string*// Cookiereq.cookie(session_id)// const std::string*// 表單字段application/x-www-form-urlencodedreq.form(username)// const std::string*// 請(qǐng)求體req.body()// uvcpp_buf完整請(qǐng)求體響應(yīng)側(cè)resp.status(200);resp.set_header(X-Custom,value);resp.json_str({\ok\:true});resp.text(plain text);resp.html(h1Hello/h1);resp.redirect(/new-location);resp.send_file(./path/to/file.pdf);resp.end();六、完整示例一個(gè)帶鑒權(quán)、上傳和路由參數(shù)的 API 服務(wù)#includewebapp/uvcpp_web_app.h#includefstream#includemutex#includectime#includeiostreamusingnamespaceuvcpp;staticstd::ofstream g_log;staticstd::mutex g_log_mutex;staticstd::stringnow_str(){std::time_t tstd::time(nullptr);charbuf[64];std::strftime(buf,sizeof(buf),%Y-%m-%d %H:%M:%S,std::localtime(t));returnbuf;}// 簡(jiǎn)單鑒權(quán)中間件uvcpp_web_middlewareauth_middleware(){return[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){conststd::string*tokenreq.header(Authorization);if(tokennullptr||token-empty()){resp.status(401).json_str({\error\:\missing token\});resp.end();return;}next();};}intmain(){g_log.open(access.log,std::ios::app);uvcpp_web_app app;app.set_host(0.0.0.0).set_port(8080);constintrcapp.set_loops(4);if(rc!0){std::cerrset_loops: rcstd::endl;return1;}// ---- 中間件鏈 ----app.use([](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next next){conststd::string tsnow_str();next();std::lock_guardstd::mutexlock(g_log_mutex);if(g_log.is_open()){g_log[ts] req.method_str() req.path() - static_castint(resp.status_code())\n;g_log.flush();}});app.use(web_middleware_cors());// ---- 公開路由 ----app.get(/hello,[](uvcpp_web_request,uvcpp_web_responseresp,uvcpp_web_next){resp.json_str({\hello\:\world\});resp.end();});// ---- 路徑參數(shù) ----app.get(/user/:id,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next){conststd::string*idreq.param(id);resp.json_str({\user_id\:\(id?*id:)\});resp.end();});// ---- 通配符 ----app.get(/files/*path,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next){conststd::string*preq.param(path);resp.text(requested: (p?*p:std::string()));resp.end();});// ---- 鑒權(quán)中間件只作用于 /api 前綴 ----// 實(shí)際項(xiàng)目中可以用路徑前綴路由組這里簡(jiǎn)化處理app.use(auth_middleware());// ---- 文件上傳 ----app.post(/api/upload,[](uvcpp_web_requestreq,uvcpp_web_responseresp,uvcpp_web_next){auto*uploadreq.upload();upload-set_upload_dir(./uploads);upload-set_max_file_size(50*1024*1024);upload-set_max_total_size(200*1024*1024);upload-on_file([](constuvcpp_web_uploaded_filef){std::cout收到文件: f.original_name (f.size bytes) - f.saved_pathstd::endl;});upload-on_end([resp](){resp.json_str({\status\:\uploaded\});resp.end();});});// ---- 異步 handler ----app.get(/api/slow,[app](uvcpp_web_request,uvcpp_web_responseresp,uvcpp_web_next next){uvcpp_web_response*rpresp;auto*wnewuvcpp_work();w-init();w-queue_work(app.loop(),[](uvcpp_work*){std::this_thread::sleep_for(std::chrono::milliseconds(20));},[next,rp](uvcpp_work*done,int){rp-json_str({\slow\:true});rp-end();next();deletedone;});});// ---- 靜態(tài)資源 ----app.serve_static(/assets,./public,true);app.start();std::coutServer on :8080, 4 loopsstd::endl;app.join();return0;}幾個(gè)關(guān)鍵點(diǎn)app.use(auth_middleware())放在公開路由之后這樣/hello、/user/:id、/files/*path不需要鑒權(quán)而后續(xù)注冊(cè)的/api/upload和/api/slow會(huì)經(jīng)過鑒權(quán)。中間件的“路徑前綴”作用域通過注冊(cè)順序來控制——先注冊(cè)的中間件作用于所有后續(xù)路由。異步 handler 中next按值捕獲?？蚣芸吹絥ext被捕獲到異步回調(diào)中就知道這一環(huán)會(huì)異步恢復(fù)不會(huì)提前結(jié)束請(qǐng)求。如果只是同步處理next可以直接調(diào)用[reference:4]。resp.end()是“我寫完了”的標(biāo)記不是發(fā)送?？蚣茉?handler 返回后統(tǒng)一收尾時(shí)才真正把響應(yīng)寫出去。七、本篇小結(jié)與下一步這篇覆蓋了從“Hello World”到真實(shí)業(yè)務(wù)的關(guān)鍵跨越路由進(jìn)階——路徑參數(shù):id、通配符*path、HTTP 方法區(qū)分匹配優(yōu)先級(jí)靜態(tài) 參數(shù) 通配。中間件鏈——next()洋蔥模型異步中間件用hold()/release()聲明生命周期web_middleware_cors()開箱即用。流式請(qǐng)求體——uvcpp_web_stream的on_data/on_end配合pause()/resume()實(shí)現(xiàn)背壓。文件上傳——uvcpp_web_upload的 multipart 流式落盤、隨機(jī)葉子名、六條大小上限。請(qǐng)求對(duì)象——param()/query_param()/header()/cookie()/form()的統(tǒng)一訪問入口。下一篇會(huì)進(jìn)入WebSocket 實(shí)時(shí)通信uvcpp_web_ws端點(diǎn)的創(chuàng)建、連接生命周期管理、廣播與房間模型以及與 HTTP 路由共存在同一個(gè)應(yīng)用中的實(shí)踐。如果你在實(shí)踐過程中遇到問題歡迎在 GitHub Issues 提出。