欄位長度上限

17 個欄位各自的長度上限,以及「只檢查有送出的欄位」這條規則

View as Markdown

客戶、商品、規格(SKU)、後台使用者的每一個字串欄位,都對應資料庫裡一個固定寬度的欄位。寫入的值超過對應的長度上限會被拒絕,但驗證的時機有一個容易忽略的細節,見下方「只檢查有送出的欄位」。

完整對照表

長度以字元數計算。

資源欄位長度上限超過時的錯誤代碼
客戶outerSysCode50outer_sys_code_too_long
客戶name50name_too_long
客戶shortName20short_name_too_long
客戶cellPhone20cell_phone_too_long
客戶shippingAddress50shipping_address_too_long
商品outerSysCode50outer_sys_code_too_long
商品name100name_too_long
規格(SKU)outerSysCode50outer_sys_code_too_long
規格(SKU)name100name_too_long
規格(SKU)barcode50barcode_too_long
規格(SKU)warehouse50warehouse_too_long
規格(SKU)unit50unit_too_long
規格(SKU)spec50spec_too_long
後台使用者account(僅建立時可送)50account_too_long
後台使用者name30name_too_long
後台使用者email100email_too_long
後台使用者outerSysCode50outer_sys_code_too_long

只檢查有送出的欄位

「省略的欄位保留原值」是「Upsert 與冪等」頁講過的部分合併規則;長度驗證完全沿用同一個判斷——一個欄位只有在你這次請求真的送出值時才會被檢查,省略的欄位一律跳過驗證,因為省略的欄位根本不會被寫進資料庫,沒有值可以檢查。

實際看一次:假設客戶 id=501 目前每個欄位都是合法值,這次更新只送 cellPhone

PUT /v1/customers/501
{
"cellPhone": "02-2345-6789"
}

這個請求只會檢查 cellPhone(上限 20 字元);nameshortNameshippingAddress 完全不會被檢查,因為它們沒有出現在這次請求裡——不管它們現在的值是什麼,這次更新都不會去看,也不需要重新送一次來「通過驗證」。

這條規則也代表:新增(create)時省略一個字串欄位,永遠不會觸發長度錯誤,因為省略的欄位在新增時會被視為空字串(見「Upsert 與冪等」),空字串的長度是 0,不可能超過任何上限。

規格(SKU)的 outerSysCodeproductId 另外各自有獨立的「必填」檢查——建立時省略會回傳 400 outerSysCode is required to create a SKU400 productId is required to create a SKU(注意這兩個代碼本身不是 snake_case,是逐字的英文句子)。必填檢查與這裡的長度檢查是兩件事:省略是必填檢查的責任,長度檢查只處理「有填但太長」。

超過長度會怎樣

超過對應欄位的長度上限,會回傳 400 {field}_too_long——{field} 是欄位名稱的 snake_case 版本,例如 outerSysCode 對應 outer_sys_code_too_longshortName 對應 short_name_too_long。每個欄位對應的實際代碼已經列在上表最後一欄。

下一步