JSON 語法與結構入門 JSON

1. 回顧 JSON

JSON 是 JavaScript Object Notation 的縮寫。雖然名稱裡有個讓人警覺的 JavaScript，但這個格式其實對語言中立，對大多數（幾乎所有）程式語言都很友好，包括 C#。它的初衷是用純文字以簡單易懂的方式描述資料──objects、arrays、lists 和 maps。

在現代軟體世界，幾乎每個程式都要跟別的程式溝通，JSON 已經成為事實上的標準，用來序列化和交換結構化資料。它被用在各處：從 REST API 到存放使用者設定，甚至用在微服務間的內部通訊。原因很簡單——它對人可讀（除非那人害怕大括號）、易於解析，且被所有主流程式語言和函式庫支援。

為什麼不用 XML?

JSON 比 XML 更簡潔、閱讀起來更輕鬆。沒有多餘的標籤噪音，資料結構也更貼合大多數語言的原生型別。而且不用一直對應開閉標籤、括號或處理那些 XML 的繁文縟節。總之——JSON 講的是 更快、更簡單、更方便。

2. JSON 的基本語法元素

把 JSON 想像成一棵簡單的樹（或俄羅斯娃娃），由 objects、arrays 和基本資料組成。下面是我們常用的「積木」：

Objects (Objects)

JSON object 是一組「key: value」對，在大括號裡面，用 { } 包起來。

範例：

{
  "name": "Alice",
  "age": 23
}

在 C# 可以用 class 或字典來表示相同的結構。

Arrays (Arrays)

JSON array 是一個有順序的元素清單（可以是任意允許的型別），用方括號 [ ] 包起來。

範例：

[1, 2, 3, 42]

或者這樣：

[
  {"name": "Ivan"},
  {"name": "Olga"}
]

在 C# 裡通常對應到 List<T>、T[] 或其他集合。

Key-Value 對

key 一定是 string（要用雙引號包起來！），value 可以是 JSON 裡允許的任何資料型別。

範例：

{
  "id": 123,
  "login": "student",
  "isActive": true
}

JSON 的資料型別

10, -5, 3.14

"hello"

true, false

null

{"a":1}

[1,2,3]

範例 — 全部放在一起：

{
  "id": 1,
  "name": "Bob",
  "scores": [10, 20, 30],
  "profile": {
    "email": "bob@mail.com",
    "phone": null
  },
  "isAdmin": false
}

看吧，可以很緊湊又有邏輯地描述一個完整的使用者物件。

3. JSON 的格式規則

字串一定要用雙引號

就算你很想用單引號，JSON 不會放過你。正確寫法如下：

{ "name": "Vera" }

下面的寫法是 錯誤：

{ 'name': 'Vera' }

Key 只能是字串

跟 C# 不同（C# 的字典 key 可以是 int 或 enum），JSON 裡的 key 永遠是字串：

{ "2025": "C# 年", "favorite": true }

不要尾逗號

跟 C# 的某些語法不同，JSON 裡在關閉括號前多一個逗號會造成語法錯誤！

// 錯誤! (最後一個逗號不被允許)
{
  "id": 10,
  "name": "Oleg",
}

正確寫法：

{
  "id": 10,
  "name": "Oleg"
}

空白與換行

空白和換行可以為了可讀性加上去，解析器會忽略它們。通常給人看的會用 pretty-printed（格式化）JSON，網路傳輸則用 minified（一行、無空白）的版本。

4. C# 物件如何轉成 JSON

如果你用 System.Text.Json.JsonSerializer.Serialize() 序列化物件，物件的欄位和屬性就會變成一對對的 key-value。

C# 類別與序列化範例

public class Book
{
    public string Title { get; set; }
    public int Pages { get; set; }
}
var book = new Book { Title = "CLR via C#", Pages = 900 };
string json = JsonSerializer.Serialize(book);
Console.WriteLine(json); // {"Title":"CLR via C#","Pages":900}

集合 (Collections)

• List<int> 會變成 [1,2,3]
• string[] 會變成 ["hi", "wow"]
• List<Person> — 會變成物件陣列

字典 (Dictionary)

像是 Dictionary<string, int> 的字典會序列化成一個 object：

var dict = new Dictionary<string, int>
{
    ["apples"] = 5, ["bananas"] = 10
};
string json = JsonSerializer.Serialize(dict);
// {"apples":5,"bananas":10}

5. 視覺化結構：JSON 怎麼被構建

巢狀結構像俄羅斯娃娃

物件
│
├── 對: "name": "Alex"
├── 對: "hobbies": 陣列
│               │
│               ├── "skiing"
│               └── "programming"
└── 對: "profile": 物件
                 │
                 ├── "age": 42
                 └── "city": "巴塞爾"

最後結果：

{
  "name": "Alex",
  "hobbies": ["skiing", "programming"],
  "profile": {
    "age": 42,
    "city": "巴塞爾"
  }
}

6. 常見錯誤和語法注意事項

程式世界沒有完美──JSON 也有自己的陷阱！如果你傳了用錯引號的 JSON、尾逗號、或 key 沒用引號包起來，解析器會報錯。

另一個「坑」是帶前導零的數字。JSON 不允許像 0123 這種寫法——這是錯誤。

實用提醒： 有些解析器（像 JavaScript 的 JSON.parse）比較寬鬆，可能會「容忍」小錯誤。但大部分較嚴格的解析器（像 C# / .NET 的）會對任何語法偏差抱怨。

7. 將 C# 資料轉成 JSON 的範例

我們來把一個比較複雜的結構序列化。假設教學用的應用程式有一個學生清單，要把它存成 JSON 檔。

定義類別：

public class Student
{
    public string Name { get; set; }
    public int Age { get; set; }
}

填資料：

var students = new List<Student>
{
    new Student { Name = "安娜", Age = 20 },
    new Student { Name = "尼基塔", Age = 22 }
};

序列化：

using System.Text.Json;

// 將學生清單序列化成 JSON 字串
string json = JsonSerializer.Serialize(students, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

/*
[
  {
    "Name": "安娜",
    "Age": 20
  },
  {
    "Name": "尼基塔",
    "Age": 22
  }
]
*/

看到沒？每個學生都是 JSON 陣列裡的獨立物件，很直觀。

8. 小型產生器：如何「手動」寫 JSON

有時候你要自己手寫 JSON，例如做測試資料。下面是個檢查清單：

1. 外層用大括號表示 object，外層用方括號表示 array。
2. key 一律為雙引號包起來的字串。
3. value 可以是字串（雙引號）、數字、true、false、null、物件 ({})、或陣列 ([])。
4. 元素之間用逗號分隔，但最後一個元素後面不要加逗號！
5. 可以加縮排和空白提高可讀性（但不是必需的）。