適用情境：React / Vite 前端 + 任意後端 + Azure Container Apps + nginx 反向代理

一、什麼是 CSP？

Content Security Policy（CSP）是一組 HTTP 回應標頭，讓瀏覽器知道「這個頁面可以載入哪些來源的資源」。它是防禦 Cross-Site Scripting（XSS）與資料注入攻擊的第二道防線。

一旦瀏覽器收到 CSP，即使攻擊者成功注入惡意 <script>，瀏覽器也會拒絕執行——因為注入的腳本不符合 CSP 白名單。

CSP 補足了什麼？

[沒有 CSP]
攻擊者注入 <script src="https://evil.com/steal.js"> → 瀏覽器直接執行 ✗

[有 CSP: script-src 'self']
攻擊者注入 <script src="https://evil.com/steal.js"> → 瀏覽器拒絕執行 ✓

二、Azure 環境的架構選擇

在 Azure 上，安全標頭可以加在三個層次：

Internet
   │
   ▼
Azure Application Gateway (WAF)
   │  ← 可在此加 HTTP Response Header Rewrite Rules
   ▼
Azure Container Apps (nginx)
   │  ← 可在此加 add_header
   ▼
Go 後端 (middleware)
   │  ← 可在此加 w.Header().Set(...)

各層優缺比較

建議

對 SPA 網站來說，nginx 是最合適的地方，原因：

1. SPA 的安全標頭只需要加在 HTML 頁面回應，不需要加在 API 回應
2. nginx 已作為 SPA 的靜態資源伺服器，天然邊界清晰
3. 設定檔進版控，可 review、可追蹤

如果日後 Application Gateway 有設定 Header Rewrite，要記得移除 nginx 這邊的設定，避免同一個 header 重複出現（瀏覽器會套用第一個，但會造成混淆）。

三、為 React + Vite SPA 設計 CSP

分析資源來源

在設計 CSP 之前，先盤點頁面實際載入的所有資源：

Mantine UI 的特殊考量

Mantine（React UI library）會透過 MantineProvider 在 DOM 注入一個 <style> 標籤，內容是 CSS 自訂屬性（design token）：

<style>
  :root {
    --mantine-color-blue-9: #1971c2;
    --mantine-font-size-md: 1rem;
    /* ... */
  }
</style>

這個 inline <style> 是 Mantine 的執行時行為，無法預先計算 hash（除非用 CSP nonce）。因此 style-src 需要加上 'unsafe-inline'。

這樣安全嗎？ 相對安全。

• style-src 'unsafe-inline' 的攻擊面遠小於 script-src 'unsafe-inline'
• CSS 注入最多能做到 UI 欺騙或 timing attack，無法直接竊取 cookie 或執行任意程式碼
• 重點是 script-src 'self' 嚴格設定，不允許 inline script 或外部 script

完整 CSP 設計

Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self' 'unsafe-inline';
  img-src 'self' data:;
  font-src 'self';
  connect-src 'self';
  frame-src 'none';
  frame-ancestors 'none';
  form-action 'self';
  base-uri 'self';
  object-src 'none'

其他安全標頭

除了 CSP，建議同時加上這些標頭：

四、nginx.conf.template 實作

在 nginx server block 層級（非個別 location 內）加上 add_header ... always：

server {
    listen 80;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;

    # Security headers
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-src 'none'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "DENY" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;

    # ... 其他設定
}

always 參數：確保即使後端回傳 4xx/5xx，nginx 也會加上這些 headers。沒有 always 的話，錯誤頁面會沒有安全標頭。

要注意的地方

1. 不要加在 /api/ proxy location 裡：API 回應不需要 CSP，加了反而讓前端 XHR 請求帶著多餘 header。
2. 避免重複設定：如果 Application Gateway 已設定 Header Rewrite，nginx 這邊要移除，否則 header 會出現兩次（部分瀏覽器行為不一致）。
3. HTTPS only 部署才需要 HSTS：Strict-Transport-Security 只有在全站 HTTPS 時才加；如果有任何 HTTP 存取路徑，HSTS 會造成無法回頭。

五、上線前驗證

本地驗證

部署後使用 curl 確認標頭存在：

curl -I https://your-app.example.com/ | grep -i "content-security\|x-frame\|x-content\|referrer\|permissions"

瀏覽器 DevTools

1. 開 DevTools → Network → 選 index.html 請求
2. 查看 Response Headers，確認五個安全標頭都在
3. 開 Console，確認沒有 CSP violation 錯誤（Refused to load ...）

線上掃描工具

• Mozilla Observatory — 綜合安全標頭評分
• SecurityHeaders.com — 詳細標頭分析
• CSP Evaluator（Google） — 評估 CSP 強度

六、常見陷阱與排查

問題：Mantine 樣式全部消失

原因：style-src 缺少 'unsafe-inline'，Mantine 注入的 <style> block 被拒絕。
解法：加上 'unsafe-inline'。

問題：Console 出現 Refused to connect to 'http://...'

原因：connect-src 'self' 嚴格限制，可能有程式碼直接連外部 API（非透過 nginx proxy）。
解法：找出來源並調整，或暫時在 connect-src 白名單加入該 origin。

問題：OAuth redirect 失敗

原因：OAuth 流程是瀏覽器 window.location.href 跳轉（navigation），不是 form submit 也不是 XHR，CSP 的 form-action 和 connect-src 都不管這個。
結論：OAuth redirect 不受 CSP 影響，不需要特別處理。

問題：第三方 SSO（POST 到 /auth/sso/callback）失敗

原因：第三方 SSO 是由外部伺服器 redirect 瀏覽器 POST 到我們的 callback（form submit 跨站）。
確認：這是第三方 SSO 頁面的 form-action，不是我們這邊的 CSP 設定問題。CSP 加在我們頁面的回應，不影響來自其他頁面的 form submit。

七、結論

對於 Azure 上的 React SPA：

1. 現在就可以加：資源全 self-hosted + 無 inline script，加 CSP 的風險很低
2. 加在 nginx：比 Application Gateway 更容易維護，可版控，redeploy 即生效
3. 接受 style-src 'unsafe-inline'：這是 Mantine 的現實限制，不影響最重要的 script XSS 防護
4. 配套加其他標頭：X-Content-Type-Options、X-Frame-Options、Referrer-Policy、Permissions-Policy 是低成本高效益的防護
5. 上線後立刻掃描：用 Mozilla Observatory 驗證，確認等級達到 B 或以上

場景：Azure Container Apps 上的 React SPA 安全加固

不要錢，OWASP ZAP 完全免費且開源。

它是開放網路應用程式安全計劃（OWASP）旗下的旗艦專案，不論是個人、企業內部測試還是商業用途，都可以自由下載並免費使用完整功能，沒有任何隱藏付費牆。

自架弱點掃描工具主要分為「主機/網路層」與「網站/應用程式層」兩種需求。推薦以下幾款業界最主流、成熟的免費與開源自架方案： [1]

1. 主機與網路層弱點掃描

• OpenVAS：企業級開源弱點評估工具，是目前功能最強大的免費主機掃描器之一，具備完整的漏洞資料庫與排程掃描功能。
• Nmap：網路探測與安全性稽核的基石，主要用於主機存活性與連接埠掃描，可搭配 NSE（Nmap Scripting Engine）執行基礎弱點檢測。 [1, 2]

2. 網站應用程式弱點掃描 (Web)

• OWASP ZAP：由國際權威組織維護的最佳免費網頁應用程式弱點掃描器。非常適合整合在開發流程（CI/CD）中，能自動檢測常見的 SQL Injection、XSS 等漏洞。
• Nikto：輕量級的命令列開源網頁伺服器掃描器，能快速找出伺服器危險檔案與過時版本。 [1, 2, 3, 4]

3. 開發原始碼掃描 (DevSecOps)

• SonarQube：針對原始碼進行靜態分析（SAST）的熱門工具，社群版（Community Build）免費且容易上手，適合在自架伺服器上檢測代碼安全缺陷。
• OWASP Dependency-Check：專注於軟體供應鏈安全，能自動掃描專案中套件（如 Maven, npm）的已知漏洞。 [2, 5]

建議策略：
若要檢測作業系統與網路設備，優先部署 OpenVAS；若是針對網頁應用程式安全，則推薦安裝 OWASP ZAP。

[1] https://www.ckmates.com

[2] https://www.cloudsecurity.com.tw

[3] https://ithelp.ithome.com.tw

[4] https://zh.wikipedia.org

[5] https://www.linktech.com.tw

要透過 Docker 快速自架 OWASP ZAP，最推薦的方式是直接使用官方維護的映像檔（Image）。依照您的使用情境，您可以選擇以下其中一行指令來執行：

方案 A：啟動「瀏覽器介面版」(Web Swing UI) — 推薦！

這會在背景啟動 ZAP，並開啟一個網頁版的圖形介面，您只需用瀏覽器連過去就能直接操作，不需要安裝任何本機軟體。

docker run -u zap -p 8080:8080 -p 8090:8090 -d ghcr.io/zaproxy/zaproxy:stable zap-webswing.sh

• 如何使用：開啟瀏覽器輸入 http://localhost:8080/zap/ 即可看到操作畫面。
• 連接埠說明：8080 是 Web 介面連線埠；8090 是 ZAP 預設的代理伺服器（Proxy）連線埠。

方案 B：直接對目標網站執行「自動化基準掃描」(Baseline Scan)

如果您不需要看畫面，只想直接對特定網站進行快速的安全性點檢（約數分鐘內完成）並在終端機看結果：

docker run -t ghcr.io/zaproxy/zaproxy:stable zap-baseline.py -t https://example.com

• 注意事項：請將 https://example.com 替換為您自己擁有權限的測試網站網址。

方案 C：直接對目標網站執行「深度全功能掃描」(Full Scan)

這會執行更深度的網頁爬蟲與主動攻擊測試（包含 XSS、SQLi 等），耗時較長：

docker run -t ghcr.io/zaproxy/zaproxy:stable zap-full.py -t https://example.com

接下來，您可以決定如何處理掃描後的資料。如果您有興趣，我們可以討論：

• 如何將掃描後的 HTML/PDF 漏洞報告 自動匯出到您的本機資料夾
• 如何設定 ZAP 的 API Key 以確保 Docker 容器的安全防護
• 如何將這行指令整合進您現有的 CI/CD 自動化流程

請告訴我您想朝哪個應用方向深入操作？

非常抱歉，前一則回覆給錯了腳本名稱。在 OWASP ZAP 的官方 Docker 映像檔中，深度全功能掃描的正確腳本名稱是 zap-full-scan.py（中間多了一個 -scan），而且它已經被設定在環境變數中，不需加上 /zap/ 前綴。 [1, 2, 3, 4]

請直接複製以下經過修正的正確指令至您的 C:\Users\your-account> 終端機執行：

docker run -t ghcr.io/zaproxy/zaproxy:stable zap-full-scan.py -t https://your-app-domain.com

進階實用建議：將報告儲存至本機

由於您的目標網址是一個 dashboard（儀表板頁面），執行 zap-full-scan.py 會耗費較長時間（進行深度爬蟲與主動漏洞攻擊）。 [1]

若您希望在掃描完成後，直接在您的 Windows 本機資料夾看到 HTML 報告，建議使用 -v 參數掛載路徑，並加上 -r 指定檔名： [2, 5]

docker run -v %cd%:/zap/wrk/:rw -t ghcr.io/zaproxy/zaproxy:stable zap-full-scan.py -r report.html -t https://your-app-domain.com

執行完成後，您就可以直接在 C:\Users\your-account> 資料夾下找到 report.html 報告檔案。 [5, 6]

當您成功啟動掃描後，接下來您可能會遇到與目標網站特性的相關調整。我們可以繼續討論：

• 如果該 Dashboard 需要 帳號密碼登入 才能看到內容，該如何代入 Cookie 或帳密進行掃描
• 如何設定 -m 參數來 限制掃描時間，避免因為網站太大而掃描過久
• 如何看懂終端機輸出顯示的 漏洞風險等級 (High/Medium/Low) [7, 8, 9, 10]

請試試看修正後的指令，並告訴我您是否需要設定 登入權限掃描 呢？

[1] https://www.zaproxy.org

[2] https://forums.docker.com

[3] https://github.com

[4] https://github.com

[5] https://www.zaproxy.org

[6] https://stackoverflow.com

[7] https://www.zaproxy.org

[8] https://groups.google.com

[9] https://www.youtube.com

[10] https://www.zaproxy.org

然而，許多開發者在系統上線、面對批次發送或高並發（High Concurrency）場景時，常會突然撞上一道高牆：ACS email API returned status 429: Too Many Requests。

本篇文章將帶您從零開始了解 ACS Email 的佈署步驟，並分享如何透過三層防禦架構徹底解決 429 超額問題！

第一部分：ACS Email 基礎佈署三步驟

要使用 ACS 發送郵件，我們需要完成以下三個核心步驟：

1. 建立資源與網域

• Azure Managed Domain（預設）：適合測試。系統會配發一組 .azurecomm.net 結尾的隨機網域。它的限制非常嚴格（5 封/分、10 封/小時），且無法申請提升。
• Custom Domain（自訂網域）：生產環境必備。您可以註冊如 notify.yourdomain.com 的子網域。
  • 小提示：建議使用子網域，避免影響學校或企業既有的 MX/SPF 設定。
  • 您需要在 DNS 管理員中設定微軟提供的四筆紀錄（包含 TXT 網域驗證、兩筆 CNAME DKIM 驗證、以及 SPF 設定）。

2. 連結 ACS 與 Email 服務

在 Azure Portal 中，將您的 Communication Services 資源與 Email Communication Services 進行連結（Connect domain），讓發信 client 端能正確調用該網域。

3. SDK 整合（以 Go 語言為例）

在程式碼中，我們可以透過 Access Key 或 Managed Identity (MSI) 來初始化 ACS Client，並調用發信 API。當有多位收件人時，ACS 支援將多個 Email 放入 To 欄位陣列中一次送出。

第二部分：為什麼會遇到 429 錯誤？

當系統有多個異步任務（例如多個 Goroutines 或背景 Worker）同時觸發發信邏輯時，瞬間發出的 HTTP 請求會遠遠超過 Azure 網域的每分鐘速率上限。

• Managed Domain：上限 5 封/分。
• Custom Domain：預設上限 30 封/分。

一旦超過，ACS 就會毫不留情地回傳 HTTP 429。如果此時程式直接報錯丟棄，就會導致使用者收不到重要通知。

第三部分：完美修復 ACS 429 的「三層防禦機制」

為了確保信件 100% 送達，且系統不會因為並發而崩潰，建議在後端架構中實作以下三層防禦：

發送郵件請求 (多個 Goroutines 並發)
       │
       ▼
 ┌───────────┐
 │  Layer 2  │ ──► Client-side Rate Limiter (主動排隊，例如限制 24 封/分)
 └───────────┘
       │
       ▼
 ┌───────────┐
 │  API 發送 │ ──► HTTP POST 到 Azure ACS
 └───────────┘
       │
       ├─ [202 Accepted] ──► ✅ 成功送出
       │
       └─ [429 Too Many Requests] 
               │
               ▼
         ┌───────────┐
         │  Layer 1  │ ──► 自動 Retry (解析 Retry-After 標頭，等待後重試)
         └───────────┘
               │
               ▼
         ┌───────────┐
         │  Layer 3  │ ──► 擴充根本 Quota (升級 Custom Domain / 調整環境變數)
         └───────────┘

Layer 1：客戶端自動重試（Client-side Retry）

當收到 429 錯誤時，不要立刻放棄！ACS 的 Response Header 中會帶有一個 Retry-After 欄位（通常為 60 秒），告知你多久後可以重試。

• 實作邏輯：在發信方法中加入一個最多 3 次的 for 迴圈。
• 行為：若遇到 429，解析 Retry-After 的秒數，讓執行緒 time.Sleep()（或搭配 context 監聽）後再次重試。如果 3 次都失敗才記 Log 報錯。

Layer 2：客戶端速率限制器（Rate Limiter）

與其等收到 429 才來重試，不如在「出門前」就先排隊。我們可以在記憶體中建立一個 Token Bucket 速率限制器（例如使用 Go 的 golang.org/x/time/rate）。

• 實作邏輯：將速率限制器封裝在 ACS Client 內，每次呼叫 Send() 前，都必須先執行 limiter.Wait(ctx)。
• 參數彈性化（拒絕 Hardcode）：建議將限制速率改為環境變數化（例如 ACS_EMAIL_RATE_PER_MINUTE）：
  • 測試環境（Managed Domain）：設為 4（低於上限 5，保留 1 封緩衝）。
  • 生產環境（Custom Domain）：設為 24（低於上限 30，保留 6 封緩衝）。
• 優點：並發的 Goroutine 會自動在本地排隊，不會佔用 HTTP 連線，更不會頻繁去撞 Azure 的 API 牆。

Layer 3：切換自訂網域與申請提升 Quota

如果業務量持續成長，本地排隊隊伍越來越長，這代表您必須提升物理上限了。

1. 全面捨棄 Managed Domain，切換至 Custom Domain，將基本盤直接從 5 封/分 擴展至 30 封/分。
2. 若 30 封/分 仍不敷使用，可以前往 Azure Portal 提交 Support Ticket，問題類型選擇 Service and subscription limits (quotas)，申請將 ACS Email 的發送速率調高（例如調整至 60 或 120 封/分）。
3. 此時，由於我們在 Layer 2 將速率做成了環境變數，我們不需要修改任何程式碼、不需要重新打包 Docker Image，只需要更改雲端環境變數（例如將 ACS_EMAIL_RATE_PER_MINUTE 改為 54），重啟服務即可完美對接新的 Quota！

總結

處理雲端服務的 Rate Limit 是後端工程師的必修課。透過 Layer 2 (本地排隊限制速率) 避免主動違規、Layer 1 (退讓重試) 處理突發流量，再配合 Layer 3 (彈性環境變數與自訂網域) 提升硬體上限，你的系統就能擁有極高韌性，再也不怕被 ACS 的 429 錯誤給擊倒！

希望這篇文章能幫助到正在與 Azure ACS 奮戰的你。歡迎在下方留言分享你們在處理第三方 API 限制時的心得！

如果你想要手動微調整備份設定、延長保留時間，或是建立一個當下的資料庫複本，可以透過以下幾種常見的方法來達成。

方法一：調整自動備份的保留時間與備份策略

如果你需要讓備份保留更久，可以到 Azure Portal 調整短期或長期保留原則。

1. 登入 Azure Portal 並且找到你的 Azure SQL Database。
2. 在左側選單的 Data management 區塊中，點選 Backups。
3. 點選畫面上方的 Configure policies。
4. 調整你的 Short-term retention（短期保留，可設定 1 到 35 天）或是設定 Long-term retention（長期保留，最長可保存 10 年）。
5. 在這個頁面中，你也可以更改 Backup storage redundancy（備份儲存體備援），選擇要使用本地備援、區域備援還是異地備援。

方法二：建立即時的資料庫複本

因為 Azure SQL 無法直接下達傳統的 BACKUP DATABASE 指令，如果你需要在進行重大更新前手動留底，最快的方式是直接複製一個新的資料庫。

透過 Azure Portal 操作

1. 在資料庫的 Overview（概觀）頁面。
2. 點選上方的 Copy（複製）按鈕。
3. 輸入新資料庫的名稱、選擇目的地伺服器，系統就會在背景開始複製。

透過 T-SQL 指令操作

你也可以直接連線到資料庫，執行以下指令來進行複製：

SQL

CREATE DATABASE 新資料庫名稱 AS COPY OF 原資料庫名稱;

方法三：匯出為 BACPAC 檔案

如果你需要將備份檔案下載到地端（On-premises）環境或是移動到其他帳號，可以將資料庫匯出成 BACPAC 檔案。

1. 在資料庫的 Overview（概觀）頁面。
2. 點選畫面上方的 Export（匯出）。
3. 輸入檔名，並選擇你要用來存放這個檔案的 Azure Storage Account（儲存體帳戶）與容器（Container）。
4. 輸入 SQL Server 的管理員帳號與密碼，點選確定後系統就會開始將資料與結構打包成 BACPAC 檔案。

how to enable to my database?

這取決於你是要啟用自動備份功能、長期備份保留（LTR），還是要啟用資料庫複本。

由於 Azure SQL Database 在建立時就已經預設自動啟用了基礎備份（每週完整備份、每天差異備份、每五分鐘日誌備份），如果你需要確認它是否正常運作，或是想要啟用更進階的備份功能，可以透過以下幾種方式來完成。

檢查並確認自動備份是否啟用

系統內建的自動備份不需要額外開關，但你可以透過 Azure Portal 確認它的保留天數與狀態。

1. 登入 Azure Portal，並進入你的 Azure SQL Database 頁面。
2. 在左側選單的 Data management 分類下，點選 Backups。
3. 切換到 Available backups 標籤頁，在這裡你就可以看到目前資料庫已經自動產生的備份列表與可還原的時間點。

啟用長期備份保留（LTR）

如果你需要將備份保留數個月或數年（預設的自動備份最多只保留 35 天），你就需要手動啟用長期保留原則。

1. 在剛才的 Backups 頁面中，將標籤頁切換到 Retention policies。
2. 勾選你需要調整的資料庫，並點選上方的 Configure policies。
3. 在右側跳出的視窗中，勾選 Long-term retention。
4. 根據需求填入你要保留的時間。例如：
   • Weekly LTR backup：每週備份要保留幾週。
   • Monthly LTR backup：每月第一個備份要保留幾個月。
   • Yearly LTR backup：每年第一個備份要保留幾年。
5. 設定完成後點選 Apply，長期備份就會開始依據排程自動執行。

透過指令直接啟用並複製一個新資料庫

如果你希望立刻啟用一個一模一樣的獨立資料庫作為測試或臨時備份，你可以直接使用 T-SQL 或是 Azure CLI 指令。

使用 T-SQL 指令

利用 SQL Server Management Studio（SSMS）或是 Azure 上的 Query editor 連線到你的主資料庫（或是 master 資料庫），執行以下指令：

SQL

CREATE DATABASE 備份資料庫名稱 AS COPY OF 原資料庫名稱;

使用 Azure CLI 指令

如果你習慣使用命令列工具，也可以直接在終端機輸入這行指令，系統就會立刻在同一個伺服器上啟用並複製一個新的資料庫：

Bash

az sql db copy --dest-name 備份資料庫名稱 --name 原資料庫名稱 --resource-group 你的資源群組名稱 --server 你的伺服器名稱

我有些資料庫可以LTR, 有些沒, 沒的database how to enable LTR?

看來你目前所在的頁面是 可用的備份 標籤頁。在這個頁面中，只有 已經成功產生長期備份 並且檔案還存在儲存體當中的資料庫，才會在 可用的 LTR 備份 欄位顯示 管理，其餘還沒有備份檔案的資料庫則會顯示 無。

如果你想要為其他顯示 無 的資料庫啟用長期保留原則（LTR），你需要切換到另一個標籤頁進行設定。請依照以下步驟操作。

啟用長期保留原則（LTR）設定步驟

1. 點選畫面上方，在 可用的備份 左邊或右邊的 保留原則（Retention policies）標籤頁。
2. 進入 保留原則 頁面後，你會看到所有的資料庫列表。
3. 勾選你想要啟用 LTR 的資料庫（例如 NYCUAUTH、portal-stg 或其他目前顯示無的資料庫）。
4. 勾選後，點選列表上方出現的 配置原則（Configure policies）按鈕。
5. 此時畫面右側會跳出一個設定視窗，請找到 長期留存（Long-term retention）的區塊。
6. 根據你的需求，自由填入以下欄位來啟用它：
   • 每週 LTR 備份：勾選並填入希望每週的備份要保留幾週或幾個月。
   • 每月 LTR 備份：勾選並指定每個月第一個備份要保留多久。
   • 每年 LTR 備份：勾選並指定每年第一個備份要保留幾年。
7. 設定完成後，點選最下方的 套用（Apply）或 儲存 按鈕。

注意事項

當你完成設定並儲存之後，因為 Azure SQL Database 是依照你設定的排程（例如每週或每月）在背景自動執行長期備份，所以它不會立刻在 可用的備份 標籤頁中從 無 變成 管理。

系統必須等到下一個排程時間點到了，並且成功將第一份 LTR 備份檔案打包存入儲存體之後，該資料庫才會在這個頁面上顯示 管理 與上一次的備份時間。

要理解它為什麼能提升效率，我們需要先來看看 React 的運作機制。

為什麼需要 useMemo？

在網頁運作時，只要元件的狀態（State）或屬性（Props）發生改變，React 就會重新渲染該元件。重新渲染意味著元件內部的所有程式碼，都會從上到下重新執行一次。

想像一下，如果你的元件內有一個需要處理上萬條資料的排序函式，每次畫面一有風吹草動，這個排序函式就要重新跑一次，這會消耗極大的瀏覽器運算資源，導致畫面出現卡頓。

useMemo 就是為了解決這個問題而誕生的。

useMemo 的運作原理

useMemo 的基本語法如下：

JavaScript

const memoizedValue = useMemo(() => computeExpensiveValue(a, b), [a, b]);

它接收兩個參數：

1. 一個帶有回傳值的函式，裡面放置你需要進行的複雜運算。
2. 一個陣列，稱為「相依陣列」（Dependency Array）。

它的工作流程非常聰明：

1. 記憶結果

當元件第一次渲染時，useMemo 會執行內部的函式，並把算好的結果存到記憶體中。

2. 比對相依陣列

當元件重新渲染時，useMemo 會去檢查相依陣列裡面的變數（例如上面的 a 和 b）有沒有發生改變。

3. 決定是否重新計算

• 如果 a 和 b 的值跟上一次一模一樣，useMemo 就會直接從記憶體拿取上一次算好的結果，完全跳過內部的運算函式。
• 只有當 a 或 b 的值改變了，它才會重新執行運算，並更新記憶體裡的暫存答案。

為什麼這樣可以提升效率？

我們用一個生活中的例子來比喻：

假設老師每天都會考你一題非常複雜的數學題。

• 沒有使用 useMemo 的情況：你每天早上拿到題目，就算題目跟昨天完全一樣，你還是老老實實地在計算紙上從第一步算到最後一步，花了 20 分鐘才寫出答案。
• 使用了 useMemo 的情況：你發現題目沒變，於是直接翻開昨天的筆記本，把寫在上面的答案抄上去，只花了 2 秒鐘。只有當老師換了新題目，你才會重新動筆計算。

在程式裡也是一樣。透過快取機制，useMemo 幫瀏覽器省去了大量重複的 CPU 計算時間，讓網頁反應變得更加流暢。

什麼時候該用 useMemo？

雖然 useMemo 很好用，但這並不代表所有地方都應該加上它。因為「把資料存進記憶體」以及「每次比對相依陣列」本身也需要消耗微小的效能。

以下是適合使用的情境：

1. 處理大量資料的運算：例如高達數千筆資料的過濾（Filter）、排序（Sort）或複雜轉換。
2. 避免不必要的子元件渲染：當你把一個物件或陣列當作 Props 傳給子元件時，因為 JavaScript 每次重新渲染都會產生新的物件記憶體位址，會導致子元件誤以為資料變了而跟著重新渲染。這時候用 useMemo 把物件固定住，就能阻止子元件浪費效能。

如果只是簡單的加減乘除或少數資料的處理，直接讓 React 重新計算即可，不需要刻意使用 useMemo。

如果你使用的是 PowerShell 視窗，請輸入以下指令：

ssh -T -i “$env:USERPROFILE.ssh\your-key_ed25519” git@github.com

如果你使用的是傳統的 CMD 視窗，請輸入以下指令：

ssh -T -i “%USERPROFILE%.ssh\your-key_ed25519” git@github.com

當你按下 Enter 鍵執行之後，系統會連線到 GitHub 並回傳訊息，請根據畫面上顯示的文字來判斷結果：

如果畫面顯示 Hi 小帳的名字! 開頭的文字，代表這把金鑰已經正確設定在 小帳底下了。

如果畫面顯示 Hi max32002! 開頭的文字，代表這把金鑰目前被綁定到了錯誤的帳號。

目前系統檢查出來的結果依然顯示為 max32002 ，這代表你還需要去登入小帳的 GitHub 帳號，並將這把金鑰重新新增進去，才能正常使用。

實際執行上面句子, 會遇到錯誤因為

在 CMD 環境中，系統無法辨識以 $ 開頭的變數符號，因為那是 PowerShell 的專屬語法。如果在 CMD 裡使用，系統會找不到路徑。

請改用以下適合 CMD 的指令：

DOS

ssh -T -i "%USERPROFILE%\.ssh\your-key_ed25519" git@github.com

或是直接填入完整的絕對路徑：

DOS

ssh -T -i "C:\Users\max32\.ssh\your-key_ed25519" git@github.com

File: C:\Users\max32\.ssh\config

# Default GitHub account: max32002
Host github.com
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_rsa
    IdentitiesOnly yes

# GitHub account: max2little (use host alias: github-max2little)
Host github-max2little
    HostName github.com
    User git
    IdentityFile ~/.ssh/max2little_ed25519
    IdentitiesOnly yes

設定已經全部完成！以下是設定內容的摘要：

使用方法：未來在複製或設定 max2little 帳號的遠端儲存庫時，請將原本的 github.com 替換為 github-max2little。

範例指令如下：

Bash

git clone git@github-max2little:your-repo-name.git

Via Azure CLI

# Add new /24 subnet
az network vnet subnet create \
–resource-group rg-spoke-paas \
–vnet-name \
–name snet-appgw-new \
–address-prefix 10.x.x.0/24

# Then update AGW to use new subnet
az network application-gateway update \
–name agw-stg-jpe-001 \
–resource-group rg-spoke-paas \
–set gatewayIPConfigurations[0].subnet.id=

Note: AGW subnet IP update via CLI may require a stop/start cycle. Plan for downtime or use blue/green deployment.

Would you like help calculating an available /24 block in your VNet, or generating the full ARM/Bicep template?

-- 確認您已設定好網路加密並有成功啟用，請執行下列 Transact-SQL 查詢：
USE [master]
GO
SELECT DISTINCT (encrypt_option)
FROM sys.dm_exec_connections;
GO

事實上，Azure SQL 為了確保雲端資料傳輸的安全，在網路層級有非常嚴格的加密規範。不論你在連線字串裡有沒有設定，所有進出 Azure SQL 的流量都必須經過 TLS (Transport Layer Security) 加密。

你執行的這段指令完全正確，它能幫你檢查目前所有對資料庫的連線是否有進行加密。

1. 執行結果分析

當你在 Azure SQL 執行上述指令後，你預期會看到唯一一個結果：

• TRUE：代表該連線目前正透過 TLS/SSL 進行加密傳輸。
• 如果你在地端（On-Premises）自建的 SQL Server 執行，可能會看到 FALSE，但在 Azure SQL 上，你只會看到 TRUE。

2. Azure SQL 的連線加密機制

Azure SQL 在連線安全上有以下幾個鐵律：

• 強制加密 (Force Encryption)：Azure SQL 伺服器端強制要求所有連線必須加密。即使客戶端（你的程式或 SSMS）在連線字串中寫了 Encrypt=False，Azure 依然會拒絕該未加密的連線請求。
• TLS 版本要求：目前 Azure SQL 預設要求 TLS 1.2 或以上。較舊、有安全性漏洞的 TLS 1.0 和 1.1 預設是被停用的（你也可以在 Azure Portal 中手動將最低要求提高到 TLS 1.2）。

3. 客戶端（你的程式或工具）該如何設定？

雖然 Azure 端強制加密，但為了防止 「中間人攻擊 (Man-in-the-Middle)」，最佳實踐是在你的應用程式連線字串（Connection String）中明確加上以下參數：

Plaintext

Server=tcp:yourserver.database.windows.net,1433;Database=yourdb;Encrypt=True;TrustServerCertificate=False;

• Encrypt=True：明確告知客戶端要啟用加密（與 Azure 端的強制政策呼應）。
• TrustServerCertificate=False：這點非常重要！ 設定為 False 代表客戶端會嚴格驗證 Azure SQL 伺服器的 SSL 憑證是否合法（由信任的憑證頒發機構簽署）。如果設為 True，雖然會加密，但客戶端會盲目信任伺服器憑證，容易遭受中間人攔截。

總結

你的 TDE（靜態資料加密）和連線加密（傳輸中資料加密）在 Azure SQL 中都是預設啟動且強制執行的，這符合現代雲端資安的「預設安全 (Secure by Default)」原則！

SQL command:

SELECT DISTINCT (encrypt_option)
FROM sys.dm_exec_connections;

先回傳 False, 第回一列 True.

你在執行結果中同時看到了 FALSE 和 TRUE，這代表目前連線到你這台 Azure SQL 伺服器的連線中，有部分連線沒有啟用加密（FALSE）。

這通常會讓原本預期「Azure SQL 會強制加密」的人感到驚訝。以下為你說明為什麼會出現 FALSE，以及如何調整：

1. 為什麼會出現 FALSE？

在 Azure SQL Managed Instance (MI) 或是某些特定設定的 Azure SQL Database 環境中，如果客戶端是透過內部虛擬網路 (VNet / Private Endpoint) 進行連線，且伺服器端的「高度安全連線重定向 (Redirect)」機制在舊版驅動程式下運作時，有些系統內部的路由連線或舊版工具可能會被判定為 FALSE。

另外，如果你使用的是地端 SQL Server (VM 或實體機)，預設確實是允許 FALSE（未加密）連線的。

2. 這是資安風險嗎？該如何稽核？

是的，出現 FALSE 代表有資料正在以明文（Plaintext）在網路間傳輸，這在生產環境（Production）或合規性要求高的環境中是不被允許的。

你可以執行以下進階指令，揪出到底是「誰」或「哪台機器」在使用未加密的連線：

SQL

SELECT 
    c.session_id,
    c.encrypt_option,
    s.login_name,
    c.client_net_address,
    s.program_name,
    s.host_name
FROM sys.dm_exec_connections c
JOIN sys.dm_exec_sessions s ON c.session_id = s.session_id;

透過這個語法，你可以對照 encrypt_option = 'FALSE' 的那一列，查看：

• client_net_address：是哪台 IP 連進來的？
• program_name：是用什麼應用程式（例如：舊版 .NET 程式、舊版 SSMS、或是某個背景服務）？
• login_name：是用哪個帳號登入的？

3. 如何強制所有人必須使用加密連線？

為了確保安全，你應該強制隔離那些未加密的連線。

方案 A：從 Azure Portal 修改（最推薦）

1. 登入 Azure Portal，找到你的 SQL Server (邏輯伺服器) 或 Managed Instance。
2. 在左側選單點選 「安全性 (Security)」 > 「網路 (Networking)」。
3. 檢查是否有 「最低 TLS 版本 (Minimum TLS Version)」 的設定，將其強制設定為 TLS 1.2。這會直接阻斷不支援現代加密協議的舊式未加密連線。

方案 B：修正應用程式連線字串（Connection String）

檢查程式碼中連線到該資料庫的字串，務必確保加上以下兩個參數：

• Encrypt=True（強制加密傳輸）
• TrustServerCertificate=False（嚴格驗證憑證，防止中間人攻擊）

只要客戶端正確啟動這兩個參數，再次執行你的 SQL 指令，FALSE 的項目就會消失，全部變成 TRUE 了！

看到這份清單，你可以完全放心了！這是一個非常健康的狀態，你的資料庫完全沒有外部的安全漏洞。

那些顯示為 FALSE 的連線，全部都有一個共同的特徵：它們是 Azure SQL 內部的「系統維護服務」，而不是來自外部或你的應用程式。

以下為你詳細拆解這份清單的結構：

1. 外部與應用程式連線：全部都是 TRUE (安全)

看這幾筆最關鍵的資料：

• 你的 Go 語言應用程式 (go-mssqldb)：來自 IP 20.48.25.146，狀態全部是 TRUE。這代表從 Kubernetes 叢集（ca-pr-backend-stg-...）連過來的業務流量都有經過 TLS 加密。

2. 為什麼那幾筆會是 FALSE？

那些顯示為 FALSE 的連線，你可以注意到它們的特徵：

• client_net_address 欄位顯示為 <named pipe>。這代表它們不是透過網路（TCP/IP）連進來的，而是「這台資料庫伺服器本機內部的行程（Processes）」在互相通訊。
• program_name 是：
  • BackupService（微軟自動備份服務）
  • MetricsDownloader、DmvCollector（微軟收集效能指標與 DMV 監控資料的服務）
  • AutomaticTuningAgent（微軟的自動索引與效能最佳化顧問）
• login_name 格式為 DB000001\WF-...。這是 Azure 後台自動指派給這台虛擬機器內部使用的本機服務帳號。

結論：

因為這些服務與 SQL Server 根本就在「同一台主機的記憶體內」通訊（透過 Named Pipe，非網路），資料完全不會流出這台機器之外，所以 Azure 為了追求最佳效能，內部通訊預設不經過網路加密層（TLS）。這在架構上是安全且極為常見的設計。

結論

你的稽核可以順利過關了！

1. 靜態資料 (Data at Rest)：已透過 TDE 100% 加密。
2. 傳輸中資料 (Data in Transit)：所有來自外部、應用程式、非本機的網路連線，全部都已強制使用 TLS 加密 (TRUE)。

-- 查詢憑證是否存在
USE master;
SELECT * FROM sys.certificates WHERE name = 'TdeServerCert';

-- (補充) 記錄備份
BACKUP LOG 資料庫名稱 
TO DISK = 'D:\DB_backup\path_to_backup_file.trn';

-- 建議創建主要金鑰與憑證，主要金鑰的密碼很重要，請記得！！！
USE master;
GO
--創建主要金鑰(密碼請更換，勿用範例的密碼)
CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'TDE@9876543210';
GO
--創建加密憑證
CREATE CERTIFICATE TdeServerCert 
WITH SUBJECT = N'DB_TDE_Certificat',
EXPIRY_DATE = '2099-12-31'; --憑證到期的日期
GO

在 azure 上執行 USE master; 就顯示錯誤訊息了.

USE statement is not supported to switch between databases. Use a new connection to connect to a different database.
Failed to execute the query

可以，Azure SQL Database（以及 Azure SQL Managed Instance）完全支援「透明資料加密」（Transparent Data Encryption，簡稱 TDE）。 事實上，在 Azure 上，所有新建立的資料庫預設都是直接開啟 TDE 的，你不需要動手去啟動它。

至於你遇到的錯誤訊息，是因為 Azure SQL Database 的架構不支援 USE [資料庫名稱] 語法來切換資料庫。在 Azure SQL 中，如果你想查詢不同的資料庫（例如 master），你必須在連線工具（如 SSMS 或 Azure Data Studio）中，直接修改連線字串或連線屬性中的資料庫名稱，重新連線進去。

以下為你整理 Azure SQL TDE 的運作方式，以及如何正確查詢它的狀態：

1. 為什麼不需要在 Azure 建立 TDE 憑證？

在傳統的 On-Premises（地端）SQL Server 中，你要做 TDE 必須自己手動建立 Master Key、憑證（Certificate），然後再針對資料庫做加密（這也就是你預期去 sys.certificates 找 TdeServerCert 的原因）。

但在 Azure SQL Database 中：

• 服務管理金鑰 (Service-Managed Key)：Azure 預設會自動幫你管理 TDE 憑證與金鑰，並定期自動輪換（Rotate）。你不需要、也沒辦法在 master 資料庫裡看到或管理這個由 Azure 託管的憑證。
• 客戶管理金鑰 (Customer-Managed Key, BYOK)：如果你有合規性需求，想要自己掌控金鑰，你可以結合 Azure Key Vault 來實作 BYOK（Bring Your Own Key）。

2. 如何正確檢查 Azure SQL 的 TDE 狀態？

你不需要切換到 master 去找憑證，直接在當前的使用者資料庫下執行以下指令，就能確認該資料庫是否有啟用 TDE 加密：

SQL

SELECT 
    db_name(database_id) AS DatabaseName,
    encryption_state,
    CASE encryption_state
        WHEN 0 THEN '無加密金鑰'
        WHEN 1 THEN '未加密 (Unencrypted)'
        WHEN 2 THEN '加密中 (Encryption in progress)'
        WHEN 3 THEN '已加密 (Encrypted)'
        WHEN 4 THEN '金鑰變更中'
        WHEN 5 THEN '解密中'
        ELSE '未知狀態'
    END AS EncryptionStateDescription
FROM sys.dm_database_encryption_keys;

預期結果： 如果你是使用 Azure SQL，通常會直接看到你的資料庫狀態為 3 (已加密 Encrypted)。

3. 如何在 Azure Portal 門戶上查看或修改？

除了用 SQL 指令，你也可以直接在網頁上點選確認：

1. 進入 Azure Portal，找到你的 SQL database。
2. 在左側選單的「安全性 (Security)」分類下，點選 資料加密 (Data encryption)。
3. 在這裡你可以看到 TDE 目前是 Enabled (已啟用)，也可以在這邊切換要使用「Azure 幫你管理的金鑰」還是「你自己的 Azure Key Vault 金鑰」。

這代表你的 tempdb 和 project-name-stg 資料庫目前都是 「3：已加密 (Encrypted)」 的狀態。

在 Azure SQL 中，這是一個非常標準且健康的預設表現：

• project-name-stg（你的業務資料庫）：正如前面提到，Azure SQL 預設會為所有使用者資料庫啟用 TDE，確保你的資料在硬碟儲存時（Data at rest）是安全的。
• tempdb（系統暫存資料庫）：只要你的實例中有任何一個使用者資料庫啟用了 TDE，Azure SQL 就會自動把 tempdb 也一起加密。這是為了防止敏感資料在運算過程中，被暫存到 tempdb 時留下未加密的軌跡。

接下來的建議

既然已經確認狀態為 3 (Encrypted)，代表透明資料加密已經在底層默默幫你守護資料了，你不需要再手動執行任何加密指令（例如 ALTER DATABASE ... SET ENCRYPTION ON）。

它的核心目的是解決以往每個開發團隊各自發明錯誤格式（例如有的叫 error_msg、有的叫 message）的亂象，提供機器與人類都好閱讀的統一規格。 [4, 5]

(註：RFC 7807 已於近年被 RFC 9457 接替更新，但基礎骨架與欄位格式完全相同。) [3, 6]

標準回應格式（範例）

當 API 發生錯誤時，必須返回特殊的 Content-Type（而非一般的 application/json），格式範例如下： [2]

HTTP Header 範例

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: zh-TW

HTTP Body (JSON) 範例

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "您的帳戶餘額不足。",
  "status": 403,
  "detail": "您當前的餘額為 30 元，但此項操作需要 50 元。",
  "instance": "/account/12345/transactions/abc",
  "balance": 30
}

5 大標準屬性說明

RFC 7807 定義了 5 個皆為選填（Optional）的標準核心欄位： [7]

• type (string)：一個 URI 網址，指向說明該錯誤類型的文件。如果沒有提供，預設視為 "about:blank"。 [2, 8]
• title (string)：該錯誤類型的簡短摘要。相同錯誤類型的 title 應該保持固定，不隨單次請求的具體細節改變（例如：固定為 “Invalid Parameter”）。 [2, 8]
• status (number)：本次錯誤對應的 HTTP 狀態碼（例如：400, 403, 404），與 HTTP Header 上的狀態碼保持一致。 [2, 9]
• detail (string)：針對這一次發生錯誤的人類可讀詳細說明，用來指出更具體的原因。 [2, 8]
• instance (string)：發生此特定錯誤的資源網址（URI），常用於紀錄該次錯誤請求的端點或交易流水號，方便客服或後台除錯。 [1, 2]

延伸擴充屬性 (Extensions)

除了上述 5 個欄位，RFC 7807 允許開發者自由增加自訂欄位（例如上方範例中的 "balance": 30）。 [2]

常見的擴充情境是 400 Bad Request（表單驗證失敗），微軟 ASP.NET Core 與 Java Spring Boot 內建支援的擴充格式如下： [2, 10]

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "invalid-params": [
    { "name": "age", "reason": "年齡必須大於 18 歲" },
    { "name": "email", "reason": "電子郵件格式不正確" }
  ]
}

如果你想在專案中導入此規格，可以告訴我：

• 你目前的後端開發語言或框架是什麼（如 Go, Node.js, Spring Boot）？
• 是否需要幫你寫一個符合 RFC 7807 規範的錯誤處理中介軟體 (Middleware)？

[1] https://datatracker.ietf.org

[2] https://matthung0807.blogspot.com

[3] https://blog.gslin.org

[4] https://medium.com

[5] https://blog.csdn.net

[6] https://blog.gslin.org

[7] https://wisely.top

[8] https://blog.restcase.com

[9] https://learn.microsoft.com

[10] https://learn.microsoft.com

毫無疑問，我們應該直接採用 RFC 9457。 [1, 2]

IETF 已於 2023 年 7 月正式發布 RFC 9457，並明確宣告廢棄（Obsoletes）舊有的 RFC 7807。不過，因為兩者「完全向下相容（Fully Backward-Compatible）」，你不需要擔心選型會帶來破壞性改變。 [3, 4, 5, 6]

以下為你梳理為什麼該選 RFC 9457 以及兩者的關鍵差異：

為什麼直接選 RFC 9457？

1. 完全向下相容：基本的 5 大欄位（type, title, status, detail, instance）完全沒有變，現有的 API 測試工具與用戶端（Client）解析邏輯也100% 通用。
2. 官方正式標準：RFC 7807 在官方狀態已是「已淘汰（Deprecated）」，未來所有的主流框架（如 Spring Boot、ASP.NET Core）和工具更新，都會以 RFC 9457 作為依據。
3. 消除模糊地帶：RFC 9457 修正了 7807 在實務應用上被反覆詢問的盲點，讓語意更精準。 [1, 2, 4, 5, 7, 8, 9, 10, 11, 12]

RFC 9457 帶來了哪些關鍵改進？ [12]

如果你直接改看 RFC 9457 的規範，它主要幫你釐清並增加了以下 3 個實務規範： [1, 13, 14]

• 建立「通用問題類型註冊表」（Problem Type Registry）
  • 過去 (7807)：大家都得自己發明 type 的網址（例如 https://example.com）。
  • 現在 (9457)：IANA 建立了一個官方註冊表，未來常見的 HTTP 錯誤可能會有官方定義好的標準 URI。 [4, 6, 13, 14, 15]
• 明確規範「如何處理多個錯誤」（Multiple Problems）
  • 過去 (7807)：當表單同時出現「Email 格式錯誤」和「密碼太短」時，舊規範沒有講明該怎麼合併呈現。
  • 現在 (9457)：明確指出不應該在最外層返回一個陣列，而是維持單一 Problem Details 物件，並將多個錯誤封裝在自訂的擴充欄位中（例如 invalid-params 陣列）。 [6, 12, 13, 14, 15]
• 允許使用「無法解析的 URI」
  • 過去 (7807)：規範強烈暗示 type 的網址應該要是能夠真正點開、看得到 HTML 文件的網址（Dereferenceable URI）。
  • 現在 (9457)：放寬限制。明確表明如果你的系統不需要網頁說明文件，type 直接寫一個純字串識別碼（例如 urn:uuid 或 tag:example.com,2024:bad-request）也是完全合法的。 [5, 6, 13, 14, 16]

結論與行動建議

在撰寫程式碼、命名類別或編寫 API 文件（如 Swagger/OpenAPI）時，請一律在文字與註解中載明遵循「RFC 9457」。 [17, 18, 19]

實作時的 JSON 格式依然維持原本設計即可： [4, 6, 10]

{
  "type": "https://yourdomain.com", 
  "title": "Invalid Input Parameter",
  "status": 400,
  "detail": "The 'age' field must be greater than 18.",
  "instance": "/users/signup"
}

如果你正準備要在現有的後端框架中實作它，可以告訴我你目前使用的是哪套程式語言或 Web 框架（例如：Go, Node.js + Express, Fastify 或是 Python + FastAPI 等），我可以提供對應最主流的 RFC 9457 套件或中介軟體寫法！ [12, 20]

[1] https://www.speakeasy.com

[2] https://www.eke.li

[3] https://datatracker.ietf.org

[4] https://www.youtube.com

[5] https://www.the-main-thread.com

[6] https://nordicapis.com

[7] https://swagger.io

[8] https://www.linkedin.com

[9] https://xantygc.medium.com

[10] https://blog.frankel.ch

[11] https://dev.to

[12] https://www.codecentric.de

[13] https://datatracker.ietf.org

[14] https://blog.gslin.org

[15] https://redocly.com

[16] https://github.com

[17] https://medium.com

[18] https://www.codecentric.de

[19] https://ithelp.ithome.com.tw

[20] https://swagger.io

在 Go 語言（Golang）中，目前各大主流 Web 框架與標準庫，都已經將以往的 RFC 7807 支援無縫銜接至 RFC 9457。

以下為您提供 2026 年在 Go 專案中實作 RFC 9457 的最佳實踐，包含標準定義、Echo/Gin 框架整合，以及自訂欄位的擴充寫法。

1. 定義 RFC 9457 核心結構體

為了完美符合 RFC 9457 規範，必須宣告標準欄位，並將 Content-Type 指定為官方規定的 application/problem+json。

package rfc9457

import (
	"encoding/json"
	"net/http"
)

// MIMEType 是 RFC 9457 指定的標準回應標頭值
const MIMEType = "application/problem+json"

// ProblemDetails 定義了 RFC 9457 的標準核心結構
type ProblemDetails struct {
	Type     string `json:"type,omitempty"`     // 錯誤類型 URI (預設 "about:blank")
	Title    string `json:"title"`              // 簡短錯誤摘要
	Status   int    `json:"status"`             // HTTP 狀態碼
	Detail   string `json:"detail,omitempty"`   // 該次錯誤的詳細人讀訊息
	Instance string `json:"instance,omitempty"` // 發生錯誤的資源路徑或交易 ID
}

// WriteTo 負責將錯誤格式正確地寫入 HTTP 回應
func (p *ProblemDetails) WriteTo(w http.ResponseWriter) error {
	if p.Type == "" {
		p.Type = "about:blank"
	}
	w.Header().Set("Content-Type", MIMEType)
	w.WriteHeader(p.Status)
	return json.NewEncoder(w).Encode(p)
}

2. 實務情境：包含多欄位錯誤（表單驗證失敗）

RFC 9457 明確規範：「當有多個欄位出錯時，不應使用陣列作為最外層，而應使用單一物件，並將細節放入自訂擴充欄位。」

我們可以用 Go 的「結構體內嵌（Embedding）」完美處理擴充屬性：

// ValidationError 針對表單驗證錯誤進行結構體擴充
type ValidationError struct {
	ProblemDetails // 內嵌標準欄位
	InvalidParams  []ParamError `json:"invalid-params"` // 自訂擴充欄位
}

type ParamError struct {
	Name   string `json:"name"`   // 欄位名稱
	Reason string `json:"reason"` // 錯誤原因
}

// 實務產生範例：
func NewValidationError(instancePath string, errs []ParamError) *ValidationError {
	return &ValidationError{
		ProblemDetails: ProblemDetails{
			Type:     "urn:example:error:validation", // RFC 9457 允許使用非網址的 URN 識別碼
			Title:    "您的輸入參數驗證失敗",
			Status:   http.StatusBadRequest,
			Detail:   "請檢查提交的欄位是否符合格式要求要求。",
			Instance: instancePath,
		},
		InvalidParams: errs,
	}
}

3. 主流框架 Middleware 整合範例

在 Go 的熱門框架（如 Gin 或 Echo）中，最佳實踐是透過中央錯誤處理（Centralized Error Handling）將所有恐慌（Panic）或未捕獲的錯誤，自動格式化為 RFC 9457 的樣式。

以 Echo 框架為例

package main

import (
	"net/http"
	"://github.com"
)

// CustomHTTPErrorHandler 覆蓋 Echo 預設的錯誤處理
func CustomHTTPErrorHandler(err error, c echo.Context) {
	code := http.StatusInternalServerError
	message := err.Error()

	// 若是 Echo 內建的 HTTP 錯誤，取出其狀態碼與訊息
	if he, ok := err.(*echo.HTTPError); ok {
		code = he.Code
		if m, ok := he.Message.(string); ok {
			message = m
		}
	}

	// 建構符合 RFC 9457 的錯誤回應
	prob := ProblemDetails{
		Type:     "about:blank",
		Title:    http.StatusText(code),
		Status:   code,
		Detail:   message,
		Instance: c.Request().RequestURI,
	}

	// 確保使用正確的 Content-Type 發送回應
	c.Response().Header().Set(echo.HeaderContentType, "application/problem+json")
	_ = c.JSON(code, prob)
}

func main() {
	e := echo.New()
	
	// 註冊全域錯誤處理器
	e.HTTPErrorHandler = CustomHTTPErrorHandler

	e.GET("/api/test", func(c echo.Context) error {
		// 觸發一個 403 錯誤測試
		return echo.NewHTTPError(http.StatusForbidden, "您沒有權限存取此資源。")
	})

	e.Logger.Fatal(e.Start(":8080"))
}

如果您希望專案程式碼看起來最頂尖，可以考慮整合目前 Go 社群中最流行且專門為 RFC 7807/9457 設計的第三方成熟套件，例如由知名開發者使用的 moogar0880/problem。

接下來，您可以告訴我：

• 您目前專案使用的是 標準庫 net/http、Gin 還是 Echo 框架？
• 是否需要我幫您串接現有的 資料庫驗證（例如 go-playground/validator），直接輸出符合 RFC 9457 規格的驗證錯誤回應？

在 Python 生態系中，實作 RFC 9457 (Problem Details) 同样非常成熟。現代 Python Web 框架（如 FastAPI、Flask 或 Django）都有非常優雅的實作方式。

以下為您提供 Python 最主流框架的實作與最佳實踐。

1. 現代 FastAPI / Pydantic 實作（首選）

FastAPI 與 Pydantic 2.x 是目前 Python 後端的最愛。我們可以使用 Pydantic 來定義 RFC 9457 結構，並透過全域異常處理器（Exception Handler）來自動轉換錯誤。

from typing import Any, Dict, List, Optional
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from pydantic import BaseModel, Field

app = FastAPI()

# 1. 定義 RFC 9457 的標準媒體類型 (MIME Type)
RFC_9457_MIME = "application/problem+json"

# 2. 定義標準核心結構
class ProblemDetails(BaseModel):
    type: str = Field(default="about:blank", description="錯誤類型 URI")
    title: str = Field(..., description="簡短錯誤摘要")
    status: int = Field(..., description="HTTP 狀態碼")
    detail: Optional[str] = Field(None, description="該次錯誤的詳細訊息")
    instance: Optional[str] = Field(None, description="發生錯誤的資源路徑")

# 3. 定義表單驗證失敗的擴充結構（符合 RFC 9457 規範：外層為單一物件）
class ParamError(BaseModel):
    name: str
    reason: str

class ValidationErrorDetails(ProblemDetails):
    invalid_params: List[ParamError] = Field(default_..., alias="invalid-params")


# 4. 覆蓋 FastAPI 預設的表單驗證錯誤 (422 Unprocessable Entity)
@app.exception_handler(status.HTTP_422_UNPROCESSABLE_ENTITY)
async def validation_exception_handler(request: Request, exc: Any):
    # 將 FastAPI 原本的錯誤格式，轉換為符合 RFC 9457 的欄位
    errors = []
    for err in exc.errors():
        # loc 通常是 ('body', 'age')，我們取最後一個元素作為欄位名
        field_name = str(err["loc"][-1])
        errors.append(ParamError(name=field_name, reason=err["msg"]))

    prob = ValidationErrorDetails(
        type="urn:error:type:validation-failed",
        title="輸入參數驗證失敗",
        status=status.HTTP_400_BAD_REQUEST,  # 實務上通常轉回更通用的 400
        detail="請檢查您提交的資料欄位格式是否正確。",
        instance=request.url.path,
        invalid_params=errors
    )

    # 回傳時必須指定特殊的 Content-Type
    return JSONResponse(
        status_code=status.HTTP_400_BAD_REQUEST,
        content=prob.model_dump(by_alias=True), # 確保輸出為 "invalid-params"
        headers={"Content-Type": RFC_9457_MIME}
    )

2. 傳統 Flask / Werkzeug 實作

如果您使用的是 Flask，可以利用 Werkzeug 內建的 HTTPException 來自訂錯誤回應。Flask 的社群甚至有開源套件 flask-rfc9457（或舊稱 flask-error-handling），但手寫其實也非常簡單：

from flask import Flask, jsonify, request
from werkzeug.exceptions import HTTPException, Forbidden

app = Flask(__name__)

class RFC9457Exception(HTTPException):
    """自訂的 RFC 9457 異常類別"""
    def __init__(self, status_code: int, title: str, detail: str = None, type_uri: str = "about:blank"):
        super().__init__()
        self.code = status_code
        self.title = title
        self.detail = detail
        self.type_uri = type_uri

# 註冊全域錯誤處理器
@app.errorhandler(HTTPException)
def handle_exception(e):
    # 預設非自訂的標準 HTTP 錯誤
    status_code = e.code or 500
    title = e.name
    detail = e.description
    type_uri = "about:blank"

    # 如果是我們自己拋出的 RFC9457Exception，讀取專有屬性
    if isinstance(e, RFC9457Exception):
        title = e.title
        detail = e.detail
        type_uri = e.type_uri

    payload = {
        "type": type_uri,
        "title": title,
        "status": status_code,
        "detail": detail,
        "instance": request.path
    }
    
    response = jsonify(payload)
    response.status_code = status_code
    response.headers["Content-Type"] = "application/problem+json"
    return response

@app.route("/api/secure-data")
def get_data():
    # 觸發錯誤示範
    raise RFC9457Exception(
        status_code=403,
        title="權限等級不足",
        detail="您的帳號未通過 VIP 身分審查，無法存取此端點。",
        type_uri="https://example.com"
    )

3. 三方成熟套件推薦

在 Python 領域中，如果您不想自己從頭刻結構體，以下是兩個非常主流、開箱即用的套件：

1. http-types-rfc9457 / problem-details：專門提供 RFC 標準的數據封裝與型別提示。
2. httpx 的衍生工具：如果您在編寫 Python Client 端（爬蟲或微服務呼叫），許多客戶端庫會整合這類套件來自動將 application/problem+json 反序列化為特定的 Exception 物件。

如果您的專案需要跟現有的系統對接，您可以告訴我：

• 您使用的是 FastAPI、Flask 還是 Django？
• 您目前的錯誤訊息是否需要做 多國語系 (i18n) 的處理（例如根據 Header 的 Accept-Language 返回繁體中文的 title 與 detail）？

我可以為您提供更深入的架構調整建議！