前言
在團隊協作中,經常會遇到這種情境:你的功能分支已經 merge 到正式環境的 release branch,但上線前一天被通知要抽單退版。這時候如果直接在 release branch 上 git revert 那筆 merge commit,後續想把同一個功能分支重新 merge 回去時,Git 會認為「這些 commit 已經被 merge 過了」而跳過所有變更——導致程式碼根本沒有被帶回來。
本文記錄這個問題的成因,以及在不遺漏檔案的前提下,如何正確退版並繼續推進功能。
之前在正式環境遇到一個棘手的問題:使用者回報某支 API 回傳 HTTP 200,瀏覽器卻直接噴出 ERR_CONTENT_DECODING_FAILED。當下排查了很久才發現問題出在 Response Header 中多了一個不該出現的 gzip,特別記錄一下整個排查過程。
打開 DevTools 檢查異常 API 的 Response Headers,可以看到幾個關鍵資訊:
Content-Encoding: gzip — 伺服器宣稱回傳內容經過 gzip 壓縮Transfer-Encoding: chunked — 資料以分段方式傳輸X-Powered-By: ASP.NET — 請求可能直接打到後端 .NET 伺服器,或經過了某層 Proxy 轉發瀏覽器收到 Content-Encoding: gzip 後,會自動嘗試用 gzip 解碼器解壓內容。但實際上這支 API 的 Response Body 是空的(長度為 0),解碼器無法處理一個空的壓縮流,因此直接報出 ERR_CONTENT_DECODING_FAILED。
為什麼 Body 會是空的?根據 Header 中的 X-Powered-By: ASP.NET,可能有兩種原因:
進一步對比同專案中兩支 API 的 Response Headers,差異一目了然:
| 欄位 | 異常 API | 正常 API |
|---|---|---|
| Content-Encoding | gzip | (無) |
| X-Powered-By | ASP.NET | (無) |
| X-Aspnet-Version | 4.0.30319 | (無) |
正常的 API 回傳的 Headers 很乾淨,是經過 Nuxt BFF(Node.js)處理後回傳的;而異常的 API 卻直接暴露了 ASP.NET 的資訊。這代表:
後端伺服器其實沒有噴錯,它正常回傳了資料(只是內容為空陣列或空物件)。真正的問題出在 Nuxt Server(Nitro)端的 API Handler 寫法。
檢查 Server 端程式碼後,發現異常的 API Handler 是這樣寫的:
1 | const response = await api.memberGetMemberPriorityHistories(query); |
這裡 api.memberGetMemberPriorityHistories() 回傳的是一個繼承自原生 Response 的物件。當直接 return response 時,Nitro 引擎會將其視為透傳(Proxy),把後端的所有原始標頭原封不動地轉發給瀏覽器。
整個流程是這樣的:
Content-Encoding: gzip 的壓縮內容return response,Nitro 把後端的原始 Headers(包含 Content-Encoding: gzip)照搬給瀏覽器Content-Encoding: gzip 標頭,嘗試解壓 Body —— 但 Body 早就被 Node.js 解壓過了,已經不是 gzip 格式ERR_CONTENT_DECODING_FAILED簡單來說:gzip 被 Nuxt Server Side 解開了一次,但 gzip 標頭卻還在,瀏覽器又試圖解第二次,自然就失敗了。
這也解釋了為什麼對比表中異常 API 會帶有 X-Powered-By: ASP.NET 和 X-Aspnet-Version — 這些都是後端的原始標頭被透傳出來的結果。
根因找到後,修正方式很明確:不要直接回傳整個 Response 物件,改為只回傳 response.data。 這樣 Nitro 會重新封裝成乾淨的 JSON Response,由 Nuxt 統一處理壓縮,後端的 ASP.NET 標頭就不會外洩。
修改前:
1 | export default defineLogAndAuthHandler(async (event) => { |
修改後:
1 | export default defineLogAndAuthHandler(async (event) => { |
這個修正需要系統性地檢查所有 Server API Handler,只要有直接 return response 的地方都應該改為 return response.data,避免同樣的問題在其他 API 上重演。
這個問題的根因不在後端、也不在前端元件,而是 Nuxt Server(Nitro)的 API Handler 直接透傳了後端 Response 物件。Node.js 在接收後端回應時已經解開了 gzip,但透傳卻把原始的 Content-Encoding: gzip 標頭一併帶給瀏覽器,導致瀏覽器嘗試二次解壓而失敗。
排查這類問題的關鍵:對比正常與異常 API 的 Response Headers。當你發現某支 API 突然多了 X-Powered-By: ASP.NET 和 Content-Encoding: gzip,而其他 API 都沒有,很可能就是 Nitro 把後端的原始標頭透傳出來了。回去檢查 Server API Handler 的回傳值,把 return response 改成 return response.data 就能解決。
在開發後台管理系統時,我們經常會遇到一個問題:每個 API Handler 都需要處理認證驗證、日誌記錄、錯誤捕獲等重複性邏輯。如果在每個檔案中都寫一遍,不僅冗長,還容易遺漏。
本文將介紹如何在 Nuxt 3 的 Server API 中,利用 Higher-Order Function (高階函式) 的概念,打造一個統一的 defineLogAndAuthHandler,讓所有 API 自動擁有以下功能:
在 JavaScript/TypeScript 中,高階函式 (HOF) 是指「接收函式作為參數」或「回傳函式」的函式。我們的設計正是利用這個概念:
export const defineLogAndAuthHandler = <T extends EventHandlerRequest>(
handler: EventHandler<T>
): EventHandler<T> => defineEventHandler<T>(async (event) => {
// 在這裡加入認證、日誌等邏輯
const response = await handler(event); // 執行原本的 Handler
// 在這裡加入回應處理邏輯
return response;
});
這就像是在原本的 API Handler 外面「包一層糖衣」,讓它自動具備額外的能力。
功能拆解
1. Session 認證與過期檢查
// 檢查是否已認證
if (!event.context?.session?.isAuthenticated && !isPublicRoute) {
return createError({
statusCode: 401,
statusText: 'Session Expired',
});
}
// 檢查 Session 是否已過期
const currentTime = new Date().getTime();
const lastLoginTimestamp = event.context?.session?.lastLoginTime;
const maxTimeDiff = (currentTime - lastLoginTimestamp) / 1000;
if (maxTimeDiff >= parseInt(maxExpiryInSeconds, 10)) {
// 清除 Session 並回傳 401
event.context.session.isAuthenticated = false;
return createError({ statusCode: 401, statusText: 'Session Expired' });
}
設計重點:
白名單機制:登入、登出等 API 不需要認證
雙重檢查:不只檢查是否登入,還檢查 Session 是否超時
2. 請求日誌記錄與敏感資料遮蔽
const ignoreLogParams = ['password', 'newPassword', 'oldPassword'];
// 遮蔽敏感欄位
if (typeof body === 'object') {
const filterBody = Object.assign({}, body);
for (const key in filterBody) {
if (ignoreLogParams.includes(key)) {
filterBody[key] = '***mask***';
}
}
logger.log('info', `[POST] ${JSON.stringify(filterBody)}`);
}
設計重點:
自動遮蔽密碼等敏感欄位,避免日誌外洩
支援 GET/POST/PUT/DELETE 不同方法的日誌格式
3. 效能監控
const startTime = Date.now();
const response = await handler(event);
const endTime = Date.now();
const duration = endTime - startTime;
logger.performance.log('info', `[${pathWithoutQueryString}] [${duration}ms]`);
設計重點:
記錄每個 API 的執行時間
方便後續分析效能瓶頸
4. 回應日誌與大型回應處理
const byPassLogUrls = ['/api/general/settings', '/api/promotion/promotions'];
function truncateString(body: string) {
const resultSizeLimit = 1024;
const stringSize = Buffer.byteLength(body);
if (stringSize > resultSizeLimit) {
return `Result size - ${stringSize} bytes`;
}
return body;
}
設計重點:
大型回應只記錄大小,避免日誌檔案爆炸
特定 API 可跳過輸出日誌(如設定檔、大量資料查詢)
5. 統一錯誤處理
catch (error: any) {
console.error('API Error:', error);
logger.error.log('error', `URL: ${event.path}, Message: ${error.message}`);
return createError({
statusCode: error.statusCode || 500,
statusMessage: error.statusMessage || 'Internal Server Error',
message: error.message || 'An unexpected error occurred',
});
}
設計重點:
所有未捕獲的異常都會被統一處理
錯誤資訊會被記錄到日誌中,方便追蹤
使用方式
使用這個封裝後,原本的 API Handler 變得非常簡潔:
// server/api/member/summary.get.ts
import { GetMemberSummary } from '@/bospi/GetMemberSummary';
export default defineLogAndAuthHandler(async (event) => {
const query = getQuery(event);
const api = new GetMemberSummary();
const response = await api.getMemberSummary(query);
return response.data;
});
只需要專注在業務邏輯,認證、日誌、錯誤處理全部自動搞定!
架構圖
┌─────────────────────────────────────────────────────────┐
│ Frontend (Browser) │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ defineLogAndAuthHandler (Wrapper) │
│ ┌─────────────────────────────────────────────────────┐│
│ │ 1. Session 認證檢查 ││
│ │ 2. 請求日誌記錄 (含敏感資料遮蔽) ││
│ │ 3. 效能計時開始 ││
│ └─────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐│
│ │ 實際的 API Handler (業務邏輯) ││
│ └─────────────────────────────────────────────────────┘│
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐│
│ │ 4. 效能計時結束 ││
│ │ 5. 回應日誌記錄 ││
│ │ 6. 錯誤捕獲與格式化 ││
│ └─────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Backend SPI (ASP.NET) │
└─────────────────────────────────────────────────────────┘
這個設計模式其實就是 AOP (Aspect-Oriented Programming) 的體現——將「橫切關注點」(如日誌、認證、錯誤處理)從業務邏輯中抽離出來。
突然有感而發 想寫下部門之前用了很多年的 GitFlow 以及它們會遇到的問題,以及他們解決什麼問題
最主要觀念是
正常功能開發以 main branch 為主體(所有的分支都由這裡出發) ,分別 Merge 到 QAT 避免同步大家開發多個功能,
有互相的影響以及將不必要的程式碼帶到正式環境
緊急修正的情況可以直接根據 main branch 拉出分支修正 避免其他影響 然後部屬到 Pre-prod 測試
首先我們先定義好 Git Branch 以及對應的環境
我們這裡以 main 當作我們的主要分支 所有 branch 都是以 main 為主
| Branch | Env | Branch Remark |
|---|---|---|
| qat | QAT | QA Testing |
| main | Pre-Prod, Prod | 正式環境 |
| feature/xxx | 開發功能分支 | |
| hotfix/xxx | 緊急功能修正 | |
| fix/xxx | 排程功能部屬 |
我們環境實際上重要的有三種環境
| Environment | remark |
|---|---|
| QAT | 給 QA 做測試的環境(所有的 Feature 都會先進到 QAT 給 QA 測試 測試完成的才會 Deploy to Pre-prod) |
| Pre-prod | 上線前給 QA 做最後測試的環境 |
| Prod | 正式環境 |
那我們可以依照幾種情境講述會遇到的問題
開發功能 照順序進到 Prod
緊急修正問題 直接推到 Prod
開發功能 時程需要拖很長(歷時一兩個月)
以下是大致上的 Gitflow 流程圖
我們會一個一個介紹
首先我們先介紹我們有幾個 branch 以及大概的功能敘述
branch 流程順序如下:
如圖片黑框的部分 這樣有可能會發生衝突
所以這是第一個衝突點,Routing 檔案衝突
接著測試到一個段落 QA 也認為 1 跟 2. 的 branch 差不多可以進 Prod 了,我們會透過剛剛提到的 5.
fix/Week1 將大家要進的程式碼統一 Merge 到此 branch 然後 merge to main ,部屬到 Pre-Prod 環境給 QA 做最後檢查
branch 流程順序如下:
這樣好處是 Merge prod 只會有一個點 到時候要退版也會好退
如圖片黑框的部分 fix/week1 是從上方這個 main branch 開的 然後 merge 進去這樣有可能會發生衝突
這樣就完成照順序進到 Prod 的功能了
想當然 我們在開發的過程中 有可能緊急有發生 Prod 有問題 需要緊急修正的問題
branch:
hotfix/RegisterIssue : 註冊問題修正的 branch
branch 流程順序如下:
為什麼要做 3 是因為要避免 qat 以及 main branch 有一些落差,理論上 qat 會比較新 但是功能應該要跟 main 相同
因為要先知道 如果一個 feature branch 存活的週期大於一個月以上一定要定時做一件事情
**定時 sync main to feature branch **
其餘流程要照著正常 feature 推動 這樣才不會有到時候要 Merge main 一堆衝突的困擾
不管使用什麼 gitflow 都是要避免衝突,盡量要跟衝突的檔案的作者溝通 看上線時程,以及 sync main branch.
如果真有遇到 Merge 到錯誤的 branch (最好是先 force reset 到錯誤的地方開始解決 千萬不要再修改檔案避免造成更多錯誤)
先說明這個問題主要是 通常在滾動頁面的時候 會有兩個需求
往下滑動就要隱藏 Header
開始上滑就要顯示 Header
但是問題來了,iOS 有一個橡皮筋的功能叫做 Elastic Scroll ,他會造成你滑動到最上方以後 會再反彈
如果沒有寫好的話,明明就滑動到最上方還是隱藏 Header (明明 Chrome 跟其他瀏覽器不會)….
為了兼容這個問題 我們以 Vue Use 為例子做一個範例
裡面其實只有 directions 跟 y 最重要
因為我們判斷它是否為回彈事件為 判斷他 nextY ===0 代表他就在最上方
不用管他是什麼事件,這樣就可以解決了
這裡說明一下 為什麼使用這方法而不用 touchmove preventDefault 是因為 有可能舊版本的 safari 沒有這個 event…
也不想要考慮太多相容性 就先保留這個行為 但是讓結果相同
1 | import { useScroll } from '@vueuse/core'; |
這個問題主要要考慮的是 iOS 以及 safari 版本不同 有可能有不同的事件 所以最好是找一個比較符合的解決方法
touchmove prevent
使用 debounce 限制 scroll top 抓取事件 delay 50 ms 之類 然後判斷高度 可以使用 lodash.throttle 套件
此篇文章是介紹 SEO Prerender,可能很多人會大概會想說聽過 Server Side Render 以及 Client Side Render ,
Prerender 簡單來說就是預先將網頁 snap shot 起來,等到搜尋引擎來的時候 就不需要當場在渲染頁面
以下是這三種方法的介紹以及優缺點
我這裡總結一下
就是 Prerender 以及 Server Side Render 都是後端產生的 html 差異在
Prerender 是預先拿取 snapshot 的檔案回來,效能比較好但是比較不即時
Server Side Render 是當下的 Request 才開始渲染網頁,比較消耗效能 但是比較即時
所以就看大家怎麼選擇
我們這裡會稍微介紹一下 怎麼使用 Asp.net 實作一個 Prerender 檢查的 Dll ,
首先我們要先知道在 Request 的什麼階段比較適合將 Snap Shot 的檔案回傳給搜尋引擎
那以下是我們的介紹
我們先來介紹當一個 Request 進到 IIS Server 中的生命週期
簡單來說 IIS 上面有一些預先檢查 EX: URL Rerewrite . 當這些檢查如果都不符合的時候
就會開始進到 Asp.net 生命週期,所以在做 Prerender 的檢查應該使用 Application Module
在 Request 還沒有進到 Asp.net 驗證以及 Routing 之前判斷,如果根據某一些 User Agent 就應該將預設好的 html
回給 search engine
sequenceDiagram
User->> IIS: Request
alt Rewrite not Match
IIS->> Application Module: Request
else Rewrite Match
IIS->> User: Return the destination
end
alt Check User Agent
Application Module->> Route: Enter into Routing
else User Agent Match with Bot And Static File Exist
Application Module->> User: Return the static file To User
end
這是 ASP.NET 應用程式生命週期流程圖 這裡不多加詳述
剛剛說的檢查是否為 Search Engine 應該在 BeginRequest 就檢查,避免做太多不必要的檢查之類
因為看到 MapRequestHandler 代表就是已經進到 Route Config 裡面了
graph LR
A(BeginRequest) --> B(AuthenticateRequest)
B --> C(AuthorizeRequest)
C --> D(ResolveRequestCache)
D --> E(MapRequestHandler)
E --> F(.....)
1 |
|
上述的例子是直接在 global.asax 裡面直接判斷,也可以使用 modules 來達到這件事情。
下面是常見的搜尋引擎的 UserAgent
| 搜索引擎 | User-Agent |
|---|---|
| Googlebot/2.1 (+http://www.google.com/bot.html) | |
| Bing | Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm) |
| Baidu | Mozilla/5.0 (compatible; Baiduspider/2.0; +http://www.baidu.com/search/spider.html) |
| Yahoo | Mozilla/5.0 (compatible; Yahoo! Slurp; http://help.yahoo.com/help/us/ysearch/slurp) |
| Yandex | Mozilla/5.0 (compatible; YandexBot/3.0; +http://yandex.com/bots) |
| DuckDuckGo | DuckDuckBot/1.0; (+http://duckduckgo.com/duckduckbot.html) |
| Sogou | Sogou web spider/4.0(+http://www.sogou.com/docs/help/webmasters.htm#07) |
使用 Prerender 好處在於說可以自己決定要回傳什麼時候的 SnapShot 檔案給搜尋引擎使用,
但是反之也要注意更新檔案的頻率。