前言

串接第三方 API，十之八九會遇到字串狀態碼。

以大家都串過的第三方金流服務來說，訂單的付款狀態就是一串小寫字串：

created → pending → paid → refunded → (failed / expired)

一開始 domain model 我就直接用 string 存，然後就踩雷了。

把 API 的「操作狀態 success」塞進了「付款狀態」欄位，編譯器一聲都沒吭。
直到後來查資料，才發現欄位裡躺著一個根本不在狀態清單上的值。

那就改成 enum 吧。但一想到要改 enum，通常會冒出三個顧慮：

1. API 回傳的 JSON 會從 "pending" 變成數字 2，這就把既有契約給破壞了。而且數字很難讀，前端得另外拿對照表才知道 2 是什麼；要是資料庫也跟著存數字，撈出來一排 2、4，根本不知道自己在看什麼。
2. Swagger / Scalar 文件裡看到的也是數字，不是有意義的字串。
3. 資料庫欄位型別要不要跟著改？會不會需要 migration？

這篇就來把 .NET 9 新增的 [JsonStringEnumMemberName] 講清楚，一個內建 attribute 就能把這三個顧慮一次解掉。順便整理一下最容易踩雷的「兩條序列化管線」跟 query 參數的陷阱。

前言

用 [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 }，結果驗證錯誤偏偏自己長一套，前端得為它寫特例處理。

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