1. 介紹
所以,你已經會把物件序列化成 JSON(或反過來)。但如果傳進你程式的是些……奇怪的東西,該怎麼辦?例如,你預期會得到這樣的 JSON:
{
"id": 123,
"name": "Alice",
"email": "alice@example.com"
}
結果收到的是:
{
"name": 42,
"id": "not a number"
}
是的,C# 的序列化/反序列化器會嘗試硬著頭皮去解析這種亂七八糟,但通常會導致執行期錯誤、資料遺失,甚至業務崩潰。在把資料往下傳、存庫或透過網路發送之前,請先確認資料是有效的——否則你的程式就像沒裝安全帶的特技演員。
這就是為什麼需要驗證:自動檢查 JSON 是否符合規則——數值類型、欄位是否必須、範圍、結構等。
2. 有哪些 JSON 驗證方式?
在 C# 和 .NET 裡,主要有三種做法:
- 用自寫程式碼驗證:手動解析物件,寫檢查並在錯誤時丟例外。
- 在模型上用驗證屬性:例如來自 System.ComponentModel.DataAnnotations 的 [Required]、[Range]、[EmailAddress] 等。
- 用 JSON Schema 驗證——今天的主角!
JSON Schema 是一個標準,可以正式描述一份有效文件應該長什麼樣。Schema 本身也是 JSON。你可以指定要哪些欄位、它們的類型、允許的值等等。
用 schema 你可以描述:
- 哪些欄位必須存在。
- 期待的類型(string、array、number、object⋯⋯)。
- 哪些欄位是必填,哪些不是。
- 值的範圍(例如年齡從 0 到 150)。
- 模式、長度、允許值列表等。
最簡單的 schema 範例
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
3. JSON Schema 的主要元素
我們用範例來拆解 JSON Schema 裡的主要鍵的意思。
| 鍵 | 說明 | 範例 |
|---|---|---|
|
指向 JSON Schema 標準的版本 | |
|
值的類型(object, array, string, number 等) | |
|
描述物件的屬性 | |
|
必填欄位的陣列 | |
|
陣列元素的描述 | |
|
允許值的列舉 | |
, |
數字的限制 | |
, |
字串長度限制 | |
|
字串的正則表達式 | |
視覺化:描述人員陣列的 schema 範例
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string", "minLength": 2, "maxLength": 50 },
"email": { "type": "string", "format": "email" }
},
"required": ["id", "name"]
}
}
4. 如何在 C# 中用 schema 驗證 JSON
在 .NET 裡沒有內建全面支援 JSON Schema(截至 .NET 9)。實務上會用外部套件: NJsonSchema 或 Newtonsoft.Json.Schema(Json.NET Schema)。
安裝 Newtonsoft.Json.Schema (Json.NET Schema)
在終端機(專案資料夾)執行:
dotnet add package Newtonsoft.Json.Schema
注意: Newtonsoft.Json.Schema 是商業授權的套件(非商業用途免費)。對於個人或 pet 專案非常適合。
用範例檢查 JSON 是否符合 schema
using Newtonsoft.Json.Linq;
using Newtonsoft.Json.Schema;
string schemaJson = @"{
'type': 'object',
'properties': {
'id': { 'type': 'integer' },
'name': { 'type': 'string' },
'email': { 'type': 'string', 'format': 'email' }
},
'required': ['id', 'name']
}";
// 假設我們有這個 JSON
string json = @"{
'id': 123,
'name': 'Alice',
'email': 'alice@example.com'
}";
// 先解析 schema
JSchema schema = JSchema.Parse(schemaJson);
// 把 JSON 解析成 JToken
JToken jsonObj = JToken.Parse(json);
// 檢查 JSON 是否符合 schema
bool valid = jsonObj.IsValid(schema, out IList<string> errors);
if (valid)
{
Console.WriteLine("JSON 驗證通過!");
}
else
{
Console.WriteLine("JSON 驗證失敗!");
foreach (var error in errors)
Console.WriteLine(error);
}
在應用程式中怎麼用驗證?
通常流程是:先驗證(使用 IsValid),再反序列化(使用 JsonConvert.DeserializeObject<T>),最後才進行業務邏輯。這樣可以在早期攔截壞資料。
if (jsonObj.IsValid(schema))
{
// 一切正常,可以反序列化
var person = JsonConvert.DeserializeObject<Person>(json);
}
else
{
// 停止處理!資料不正確。
}
5. JSON Schema 在現實中的應用
什麼時候需要驗證?
- 收到 API 的資料時(特別是來自外部系統或不同客戶端)。
- 微服務或資料庫之間遷移資料時。
- 用 schema 自動生成 UI 表單或自動填充時。
- 面試題:常會被問到「如果收到錯誤的 JSON 怎麼辦?」
給好奇者的額外補充
- 格式檢查: "format":"email", "date-time"。
- 複合規則: anyOf, oneOf, allOf。
- 驗證巢狀物件和陣列。
- 根據需求擴充 schema。
6. 實務大範例
輸入資料(使用者清單):
[
{ "id": 1, "name": "Alice", "email": "alice@example.com" },
{ "id": 2, "name": "Bob" },
{ "id": "什麼這是?", "name": 123, "email": "not-an-email" }
]
Schema:
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string", "minLength": 2, "maxLength": 50 },
"email": { "type": "string", "format": "email" }
},
"required": ["id", "name"]
}
}
.NET 中的檢查:
string jsonArray = @"[ ... ]"; // 參見上方
string schemaJson = @"{ ... }"; // 參見上方
JSchema schema = JSchema.Parse(schemaJson);
JToken arrayToken = JToken.Parse(jsonArray);
bool isValid = arrayToken.IsValid(schema, out IList<string> errs);
if (!isValid)
{
foreach (var error in errs)
Console.WriteLine(error);
// 範例訊息:
// "String '什麼這是?' is not a valid integer."
// "Integer 123 is not a valid string."
// "String 'not-an-email' is not a valid email address."
}
7. 使用 JSON Schema 時常見錯誤
錯誤 #1:schema 與實際資料不同步。 修改模型後忘了更新 schema。驗證可能會錯過錯誤或拒絕正確資料。
錯誤 #2:schema 與模型類型不匹配。 模型裡某欄位改了型別(例如 id 變成字串),但 schema 還是定義成 integer——驗證器就會抱怨。
錯誤 #3:缺少對業務重要的必填欄位。 即便欄位沒被標成必填,業務邏輯可能依賴它,缺少會導致故障。
錯誤 #4:資料格式不對。 類型是 string 的 email 或日期看起來像字串,但可能不符合格式。搭配 format 或額外檢查。
錯誤 #5:套件的實作落後於標準。 標準在演進,但實作不一定跟上。有些檢查可能缺失或行為不同。
GO TO FULL VERSION