CodeGym /課程 /C# SELF /驗證 JSON 和 JSON Schema

驗證 JSON 和 JSON Schema

C# SELF
等級 47, 課堂 4
開放

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 裡的主要鍵的意思。

鍵 說明 範例
$schema
指向 JSON Schema 標準的版本
"https://json-schema.org/draft/2020-12/schema"
type
值的類型(object, array, string, number 等)
"type": "object"
properties
描述物件的屬性
"properties": { ... }
required
必填欄位的陣列
"required": ["id"]
items
陣列元素的描述
"items": { ... }
enum
允許值的列舉
"enum": ["A", "B"]
minimum
,
maximum
數字的限制
"minimum": 0
minLength
,
maxLength
字串長度限制
"minLength": 3
pattern
字串的正則表達式
"pattern": "^[a-zA-Z]+$"

視覺化:描述人員陣列的 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:套件的實作落後於標準。 標準在演進,但實作不一定跟上。有些檢查可能缺失或行為不同。

1
問卷/小測驗
處理 JSON-資料,等級 47,課堂 4
未開放
處理 JSON-資料
JSON 語法和結構的基礎
留言
TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION