Ozakboy.TaiwanKit.TwIdValidator — 台灣證號驗證套件

Ozakboy.TaiwanKit 系列套件之一——一套台灣在地格式驗證的 .NET 函式庫。

相關連結

• 📦 NuGet：https://www.nuget.org/packages/Ozakboy.TaiwanKit.TwIdValidator/
• 💻 GitHub：https://github.com/ozakboy/Ozakboy.TaiwanKit.TwIdValidator
• 🌐 介紹網站：https://twid.ozakboy.life

dotnet add package Ozakboy.TaiwanKit.TwIdValidator

專案背景

台灣的身分證、統一編號、手機號碼各有一套檢核碼演算法，實務上常要在後端做格式驗證。市面上的實作往往只支援本國人身分證、或沒跟上 2021 年的統編新制與新式外來人口統一證號。本套件把三類證號的驗證整合成一致的靜態 API，並補齊容易被忽略的邊界情況。

主要功能

身分證（三種證號自動辨識）

• 本國人身分證（A123456789，第 2 碼 1/2）
• 新式外來人口統一證號（A800000014，第 2 碼 8/9，2021 年起發行）
• 舊式居留證號（AB12345678，前 2 碼英文，2031 年前仍有效）

Validate 會回傳詳細結果：證號類型、性別、戶籍縣市（含 L/R/S/Y 等已停用代碼的標注）、失敗原因；格式可辨識但檢核碼錯誤時仍回填解析資訊，方便提示「格式對但號碼錯」。

統一編號

完整支援財政部 2021 年 4 月新制（加權總和為 5 的倍數）與第 7 碼為 7 的特例雙取法。

手機號碼

嚴格模式只收 09 開頭 10 碼；另提供 TryNormalize 容忍並轉換 +886、空格、dash、括號、句點與全形數字。

測試假資料產生器

Generate 產生檢核碼合法的樣本號碼（可指定證號類型、性別、seed）；僅格式合法、不對應真實人物，供單元測試使用。

技術架構

• 多框架：netstandard2.0 / netstandard2.1 / net8.0 / net9.0 / net10.0，語法以最低 netstandard2.0 為準
• 零執行期依賴：純演算法，不需網路、不需第三方套件
• 品質保證：89 項 xUnit 測試（含官方樣本、四象限無效輸入、縣市對照、特例雙取法、產生器迴圈驗證），全五個框架建置零警告
• 發佈自動化：SourceLink、符號套件（snupkg）、中英雙語 XML 文件；GitHub Release + NuGet 全自動發佈流程
• 雙語文件：README 與線上文件（getting-started / API 參考）皆中英雙語，介紹網站以 Nuxt 4 靜態產生、部署於 GitHub Pages