跳至主要內容

Pamis Blog

充滿迷因與幹話的技術小本本
RazorLight 與 Razor.Templating.Core 差異

前言

用 Razor 模板（.cshtml）在後端產生 HTML（例如啟用信、密碼重設信、驗證碼信）時，
常見的兩個引擎是 RazorLight 與 Razor.Templating.Core。

模板檔案本身可以完全一樣，連 @model、@if、@Model.Xxx 都不用改，
但專案設定和驅動程式的實作差很多——而且差的點，剛好都源自同一件事：

RazorLight 是執行期（runtime）才編譯模板，Razor.Templating.Core 是建置期（build time）就預編譯好。

這一個差異，連帶解釋了三個「為什麼」：

  1. 為什麼 RazorLight 要寫一支 warmup 預熱 程式，Razor.Templating.Core 不用。
  2. 為什麼 RazorLight 的模板要設成 嵌入資源（EmbeddedResource），Razor.Templating.Core 不用。
  3. 為什麼用 Razor.Templating.Core 時，多開一個專案會比直接改 Infrastructure 好。

這篇就把這三件事講清楚，並附上兩邊的程式碼對照。

Pamis Wang2026/6/30大約 10 分鐘後端ASP.NET CoreRazorRazorLightRazor.Templating.CoreEmail專案架構
ASP.NET Core API Key 身份驗證：自訂 AuthenticationHandler 與 JWT 並存

前言

許多前後分離專案的認證一直都是 JWT：後台管理員登入後拿到 Token，之後每個請求都帶 Authorization: Bearer ...。
用久了大家很容易有個錯覺——好像 ASP.NET Core 的認證就只有 JWT 這條路。

其實不是。ASP.NET Core 的認證系統是可插拔的 Scheme 架構，JWT 只是其中一種掛上去的 Scheme 而已。
這次有個需求剛好可以拿來示範：ERP 廠商要打我們的 API，但他們不是「會登入的使用者」，給不了帳密、也不適合走 JWT 那套換 Token 的流程。
這種「機器對機器、長期有效的靜態金鑰」場景，API Key 才是對的工具。

這篇想做兩件事：

  1. 框架不是只能 JWT，要在同一個專案裡同時跑好幾種認證方式是很自然的事。
  2. 把我自己寫的這版實作記下來。網路上 API Key 的文章不少，但很多不是繞太遠，就是沒講清楚「怎麼跟既有 JWT 並存而不互相打架」，這版我盡量寫得好懂一點。
Pamis Wang2026/6/28大約 7 分鐘後端ASP.NET CoreAPI Key認證API資安
ASP.NET Core 跨域資源存取（CORS）設定

前言

前後端分離寫久了，總會遇到那個熟悉的紅字：

Access to fetch at 'https://api.example.com' from origin 'https://www.example.com'
has been blocked by CORS policy.

前端工程師看到這行，第一反應通常是轉頭問後端：「你 CORS 開了沒？」
後端工程師則是一臉無辜：「我本機明明可以啊。」

問題就在這裡——CORS 是瀏覽器的安全機制，本機用 Postman、Swagger 打都不會擋，
只有真的從另一個網域用瀏覽器發請求才會觸發。所以「我本機可以」這句話在 CORS 面前完全沒有意義。

你 CORS 開了沒？ vs 我本機明明可以

這篇就把 ASP.NET Core 的 CORS 設定一次講清楚，並把它封裝成一個擴充方法，
搭配設定檔的允許清單，讓 Program.cs 只剩乾淨的一行。

Pamis Wang2026/6/28大約 5 分鐘後端ASP.NET CoreCORSAPI資安
ASP.NET Core JWT 的兩種實作：官方 IdentityModel vs jwt-dotnet

前言

JWT 大家都在用，但「怎麼產生」這件事其實有不只一種寫法。

早期我手刻過一版——自己組 header、payload，自己做 Base64Url 編碼，自己用 HMACSHA256 算簽名。
能動是能動，但每次要加個 claim、換個演算法都得回去改一堆字串拼接，心裡總是毛毛的。

自己手刻加密，能動但心裡毛毛的

後來改用套件，又面臨一個選擇題：
要用微軟官方的 Microsoft.IdentityModel，還是社群很受歡迎的 jwt-dotnet？

這篇就把這兩套放在一起比。重點是——它們在我的專案裡實作的是同一份介面 IJsonWebTokenService，
所以可以靠 DI 一行切換引擎，呼叫端完全無感。

Pamis Wang2026/6/28大約 4 分鐘後端ASP.NET CoreJWT認證API資安
ASP.NET Core 自訂模型驗證錯誤訊息格式

前言

用 [ApiController] 寫 Web API 時，模型驗證幾乎是免費的——在 ViewModel 上掛幾個 [Required]、[StringLength]，
請求進到 Action 之前框架就會自動幫你擋下不合法的輸入，連 if (!ModelState.IsValid) 都不用寫。

public class LoginViewModel
{
    /// <summary> 帳號 </summary>
    [JsonPropertyName("id")]
    [Required(ErrorMessage = "帳號為必填")]
    public required string Id { get; set; }

    /// <summary> 密碼 </summary>
    [JsonPropertyName("password")]
    [Required(ErrorMessage = "密碼為必填")]
    public required string Password { get; set; }
}

少送一個 id，框架自動回你一包 400：

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Id": [
      "帳號為必填"
    ]
  },
  "traceId": "00-200bae18c687dfe47d1ddac560e30c51-965a2222697de138-00"
}

這格式很標準（它是 RFC 7807 / 9457 的 ProblemDetails），但實務上常常和團隊既有的 API 回應規格對不上——
前端早就講好所有回應都長 { code, message, data }，結果驗證錯誤偏偏自己長一套，前端得為它寫特例處理。

這篇就把「怎麼把模型驗證錯誤改成自己想要的格式」講清楚，提供兩種主流做法，並分析各自的優缺點與適用情境。

Pamis Wang2026/6/28大約 12 分鐘後端ASP.NET CoreWeb APIModel ValidationModelStateActionFilter
資料庫與應用程式產生主鍵的思考方向

前言

設計資料表時，有個問題其實比想像中關鍵：這張表的主鍵（PK），到底是誰負責生出來的？

最直覺的答案是「資料庫啊」——int IDENTITY 自動加一，或 SQL Server 的 NEWSEQUENTIALID()，
反正 INSERT 下去資料庫就會幫我填好。寫起來省事，大家一開始也都這樣用。

但用久了會踩到一些尷尬的狀況：

  • 我想在存檔之前就知道這筆資料的 Id（要先建關聯、要回傳給前端、要寫 log），但值在資料庫那邊，
    非得 SaveChanges() 之後才拿得到。
  • 寫單元測試想驗證物件之間的關聯，結果沒有真資料庫就生不出 Id。
  • 一張主檔搭多張明細，明細要塞外鍵，但主檔 Id 還沒生出來，整個串接卡住。

於是另一條路浮上來：讓應用程式自己產生主鍵。我們團隊的開發規範也是這樣訂的——
所有實體的主鍵一律標上 [DatabaseGenerated(DatabaseGeneratedOption.None)]，
把產生主鍵的責任從資料庫手上收回來。

這篇就把「資料庫產生 PK」與「應用程式自訂 PK」兩條路講清楚，
並用 EF Core 內建的 SequentialGuidValueGenerator 示範兩種落地寫法。

Pamis Wang2026/6/28大約 12 分鐘後端ASP.NET CoreEF CoreEntity Framework資料庫GUIDSnowflake
Mailpit 安裝與使用

前言

開發時最麻煩的事情之一，就是測試寄信功能。

填完表單按下送出，然後……什麼都沒發生。是寄出去了嗎？還是掉了？
跑去收信匣看，沒有。垃圾桶？也沒有。然後開始猜：是 SMTP 設定錯了？還是信被黑洞吸走了？

更慘的是，如果你不小心寄真的信出去……恭喜，你就變成那個「我只是在測試系統」的工程師，
然後客戶打電話進來問說：「你們剛剛寄了一封主旨是『test123』的信給我，這是什麼？」

當不該寄出去的信真的送出去了

這時候你就需要一個假郵件伺服器。

Mailpit 就是這樣的工具！它可以攔截所有寄出的信，不會真的寄給任何人，
然後用一個乾淨的 Web 介面讓你查看每封信長什麼樣子。

開發測試的好夥伴，絕對不能沒有它！

Pamis Wang2025/10/17大約 4 分鐘資料儲存MailpitSMTPemailDockerUbuntu
MinIO 安裝與使用

前言

又是檔案上傳的需求來了！

還記得那個年代嗎？
檔案直接丟進伺服器的某個角落，然後祈禱不要被駭客發現...
不然就是資料夾不小心動到後就全員失蹤了。

後來 FTP 出現，我們以為自己很專業，結果明文傳輸被抓包，
現在大家都在講物件儲存，彷彿不用 S3 就不夠潮。

但是！錢包空空怎麼辦？AWS 帳單一來就想哭，
這時候 MinIO 就是我們的救星啦！免費自架，還能假裝自己在用 S3 ，
反正 API 相容，老闆和客戶看不出來的啦 （小聲）

軟體開發日常
Pamis Wang2025/8/15大約 4 分鐘資料儲存MinIOObject StorageDockerUbuntuS3
Git Filter Branch 清理指南

前言

在開發過程中難免會犯錯，像是不小心推送了機密檔案、大型檔案，或是一些不該存在於版本控制中的檔案。

如果專案還很新，可以砍掉 .git 目錄，但過去的提交紀錄也都會不見。

這時候就需要用到 git filter-branch 來重寫 Git 歷史記錄。

Pamis Wang2025/8/9大約 4 分鐘版本控制gitGitHubGitLab
Copyright © 2026 Pamis Wang