[{"data":1,"prerenderedAt":232},["ShallowReactive",2],{"blog-\u002Fblog\u002Ftoo-many-toast\u002F":3},{"id":4,"title":5,"body":6,"category":207,"date":208,"description":209,"extension":210,"meta":211,"navigation":217,"ogImage":218,"path":219,"robots":220,"schemaOrg":221,"seo":228,"sitemap":229,"stem":230,"__hash__":231},"content\u002Fblog\u002Ftoo-many-toast.md","API 發生錯誤時該怎麼顯示提示？",{"type":7,"value":8,"toc":192},"minimark",[9,13,17,20,23,26,29,32,35,38,41,48,51,54,57,60,66,70,73,76,79,85,88,91,96,99,115,118,121,124,130,134,137,142,145,148],[10,11,12],"p",{},"討論的專案是使用 toast 做 API 錯誤提示，所以討論範圍都會聚焦在顯示多個 toast 是否是好的？如何管理 toast？暫不思考使用 toast 是不是正確的。",[14,15,16],"h2",{"id":16},"前言",[10,18,19],{},"「希望在載入畫面時，假如同時有多支 API 出現錯誤，可以只顯示一個錯誤訊息就好。」\n這是某位主管在例行會議上希望前端做到這件事情。",[10,21,22],{},"姑且先不論他的目的是什麼，主要是想藉這個機會想一想錯誤提示這件事情。",[10,24,25],{},"到目前為止，當前專案不管是 PM 還是 UI 還是其他相關人士都沒有針對這件事情設計，那麼到底該顯示什麼內容對使用者來說才是合適的呢？",[10,27,28],{},"我希望可以從目的、數量；從開發者、UX 來聊聊這件事。",[14,30,31],{"id":31},"錯誤提示的目的",[10,33,34],{},"我認為錯誤提示的觀看者可以分成：使用者、開發者。",[10,36,37],{},"使用者想透過錯誤提示知道：哪裡出了問題、可能的原因，以及接下來可以怎麼做。\n開發者想透過錯誤提示知道：哪裡錯了、錯的原因。",[10,39,40],{},"雖然看起來一樣，但是開發者想知道的訊息不見得適合揭露給使用者。",[10,42,43,44],{},"例如開發者可能需要錯誤代碼或診斷紀錄來追查問題，使用者比較需要知道受到什麼影響、接下來可以怎麼做。",[45,46,47],"mark",{},"使用者看得到的錯誤內容應足以協助處理問題，同時避免揭露敏感資訊和除錯細節。",[14,49,50],{"id":50},"錯誤提示的數量",[10,52,53],{},"一個畫面在載入時顯示多個錯誤訊息會有什麼問題嗎？",[10,55,56],{},"以 UX 角度來說，使用者可能會被一下子這麼多錯誤訊息嚇到，覺得你這網頁怎麼一堆問題。也可能來不及一口氣看完全部，知道可以怎麼因應這些錯誤。",[10,58,59],{},"以開發端來說，直接顯示每個錯誤可能是比較直覺的處理方式，不過也要考慮重複提示和使用者能否理解。",[10,61,62,63],{},"所以看起來應該",[45,64,65],{},"先討論 UX 是否合理，再來看看如何實作才是對的。",[14,67,69],{"id":68},"先決定-ux","先決定 UX",[10,71,72],{},"如果能先判斷這些錯誤是不是同個原因導致的，以及它們對使用者造成什麼影響，再決定要怎麼提示，應該能減少一次出現太多訊息的情況。",[10,74,75],{},"像這次的情境，畫面初始化時有 3 支 API 失敗，就可能一次出現 3 個錯誤提示。如果確認它們都是因為登入過期而失敗，是不是可以統一提示「登入過期，請重新登入」？如果原因不同，但都影響了初始化資料的載入，是不是也能依實際影響整合成一則提示呢？",[10,77,78],{},"又或是假設同時發生登入過期和其他資料載入失敗，以優先度來說，登入過期可能是使用者比較需要先知道的資訊。",[10,80,81,82],{},"如此一來，以工程面來說，我們需要",[45,83,84],{},"先根據錯誤原因及操作情境分類，再判斷哪些提示可以整合，以及哪些資訊應該優先顯示。",[14,86,87],{"id":87},"再決定如何開發",[10,89,90],{},"後端可以在 HTTP Status 以外，回傳一個可分類的錯誤代碼。前端收到錯誤後，可以先依代碼辨識原因，再考慮它發生在哪個操作，以及對使用者造成什麼影響，才能決定怎麼顯示提示。",[92,93,95],"h3",{"id":94},"錯誤該怎麼分組","錯誤該怎麼分組？",[10,97,98],{},"知道錯誤原因和操作情境後，就能進一步判斷哪些提示適合放在一起。回到前面提到的畫面載入情境，我認為可以從兩種情況來思考：",[100,101,102,109],"ul",{},[103,104,105,108],"li",{},[45,106,107],{},"相同原因：去除重複提示。"," 三支 API 都確認因登入過期失敗時，可以統一顯示「登入過期，請重新登入」。但收到 HTTP 401 時，仍要依認證流程判斷原因，不能直接認定登入過期。",[103,110,111,114],{},[45,112,113],{},"不同原因、共同影響：彙整提示。"," 同一次初始化中，統計和通知資料因不同原因載入失敗，而訂單資料成功。如果知道這批請求的結果，可以考慮顯示「部分資料載入失敗」。",[10,116,117],{},"如果不知道錯誤是不是屬於同一次操作、造成什麼影響，就不一定能用同一則訊息說明。例如初始化失敗和使用者按下儲存後失敗，即使發生時間接近，也應該分開判斷。提示的內容也要符合實際情況：部分資料成功載入時，不應讓使用者以為整個畫面都無法使用。",[92,119,120],{"id":120},"錯誤的優先度",[10,122,123],{},"分組之外，還要決定使用者應該先知道什麼。像登入狀態失效會影響後續操作，可以比一般資料載入失敗更優先處理；使用者主動執行的儲存操作失敗，也需要保留明確回饋。",[10,125,126,129],{},[45,127,128],{},"優先度要依錯誤對使用者的影響及操作情境決定，而不是只依 HTTP Status 排序。","優先顯示某個錯誤，也不代表其他需要使用者知道的錯誤就可以被忽略。",[92,131,133],{"id":132},"前端可以怎麼處理","前端可以怎麼處理？",[10,135,136],{},"假設 API 分散在不同 Component 呼叫，可以考慮用 Pinia 這類狀態管理工具收集錯誤與通知狀態，再根據錯誤原因、操作情境及已知影響分類，決定去重、彙整或分別顯示。各 Component 仍然負責自己的資料與畫面狀態；這些錯誤是否屬於同一次操作，以及實際造成什麼影響，也需要由相關流程提供足夠資訊判斷。",[10,138,139],{},[45,140,141],{},"錯誤代碼可以對應到集中管理的使用者文案；未知代碼則提供一般提示，診斷資訊依專案規範另行記錄，避免直接顯示未經確認的後端錯誤訊息。",[10,143,144],{},"這裡還有一個取捨：等一批請求完成後再彙整，可以取得較完整的結果，但使用者也會等比較久。像確認登入失效這類需要盡快處理的情況，可以先交由認證流程處理；其他錯誤要等待多久、晚到的結果怎麼處理，則需要依操作情境決定。",[14,146,147],{"id":147},"參考資料",[100,149,150,160,168,176,184],{},[103,151,152,159],{},[153,154,158],"a",{"href":155,"rel":156},"https:\u002F\u002Fdevguide.owasp.org\u002Fen\u002F04-design\u002F02-web-app-checklist\u002F10-handle-errors-exceptions\u002F",[157],"nofollow","OWASP：Handle all Errors and Exceptions","：錯誤訊息與診斷資訊的適當揭露。",[103,161,162,167],{},[153,163,166],{"href":164,"rel":165},"https:\u002F\u002Fgithub.com\u002FTanStack\u002Fquery\u002Fdiscussions\u002F3125",[157],"TanStack Query：Global and local onError callbacks","：集中處理錯誤，以及依額外資訊決定通知方式。",[103,169,170,175],{},[153,171,174],{"href":172,"rel":173},"https:\u002F\u002Fprometheus.io\u002Fdocs\u002Falerting\u002Flatest\u002Falertmanager\u002F",[157],"Prometheus：Alertmanager","：監控告警的分組與去重概念。",[103,177,178,183],{},[153,179,182],{"href":180,"rel":181},"https:\u002F\u002Fgrafana.com\u002Fdocs\u002Fgrafana\u002Flatest\u002Falerting\u002Ffundamentals\u002Fnotifications\u002Fgroup-alert-notifications\u002F",[157],"Grafana：Group alert notifications","：告警分組條件及通知等待時間的取捨。",[103,185,186,191],{},[153,187,190],{"href":188,"rel":189},"https:\u002F\u002Ffkhadra.github.io\u002Freact-toastify\u002Fprevent-duplicate\u002F",[157],"React-Toastify：Prevent duplicate","：避免重複顯示 Toast 的機制。",{"title":193,"searchDepth":194,"depth":194,"links":195},"",2,[196,197,198,199,200,206],{"id":16,"depth":194,"text":16},{"id":31,"depth":194,"text":31},{"id":50,"depth":194,"text":50},{"id":68,"depth":194,"text":69},{"id":87,"depth":194,"text":87,"children":201},[202,204,205],{"id":94,"depth":203,"text":95},3,{"id":120,"depth":203,"text":120},{"id":132,"depth":203,"text":133},{"id":147,"depth":194,"text":147},"UI\u002FUX","2026-11-05","思考多個 API 錯誤提示的分類、分組與優先度。","md",{"tags":212},[213,214,215,216],"API","錯誤處理","UX","Toast",true,{"url":193},"\u002Fblog\u002Ftoo-many-toast",null,[222],{"@type":223,"headline":224,"author":225,"datePublished":208},"BlogPosting","API 錯誤提示的分類與管理",{"@type":226,"name":227},"Person","Jamespig",{"title":5,"description":209},{"loc":219,"lastmod":208},"blog\u002Ftoo-many-toast","6kLJfPUH-X2RtWZwKQIPsqbM5lkPO-AJ4Zd0_TKH-KE",1793866848539]