name: api description: 在當前倉庫內處理介面請求、介面返回值消費或 API 型別定義時使用。核心要求是以後端返回欄位為準，前端直接使用返回值，不新增相容欄位、回退邏輯或格式化處理。 metadata: short-description: 專案介面約束

API 規則

規則執行方式（強制）

• 本 skill 一旦命中，本檔案中的全部規則、流程、檢查和交付條件預設全部執行，不得自行挑選或只執行部分內容。
• 僅允許跳過規則正文明確限定且當前條件不成立的條款；不得因改動小、只讀檔案、只回答問題或只執行命令而跳過已命中的規則。
• 多個 skill 同時命中時，疊加執行全部相關規則；交付前逐條確認已落實，未完成時不得宣告任務完成。

適用場景

• 在當前倉庫內新增或修改介面請求程式碼時使用。
• 在當前倉庫內新增或修改介面返回值消費邏輯時使用。
• 在當前倉庫內新增或修改 API 相關 TypeScript 型別時使用。

核心規則

• 請求服務端介面時，不額外編寫失敗兜底邏輯。
• 介面欄位名、欄位值、資料結構以後端實際返回為準。
• 頁面、元件、store 中直接使用後端返回欄位，不額外做重新命名、別名相容、欄位回退、格式化或二次封裝。
• 只要欄位來自介面返回，前端就直接沿用介面返回值和對應型別，不額外做 Number()、String() 等型別轉換後再透傳。
• 除非需求中明確要求轉換引數資料型別，使用介面返回的 id 或其他欄位繼續查詢詳情介面、或作為表單編輯提交引數時，直接使用返回欄位，不額外做型別轉換。
• 各類 id、bizId、主鍵欄位在頁面、元件、彈窗之間傳遞時，必須直接使用介面返回的原始值，不新增前端自定義轉換邏輯。
• 提交介面引數時，不新增空值“清洗”、歸一化或可選值兜底函式；不將 ''、null、undefined 相互轉換，也不借此刪除欄位，禁止新增 toOptionalId、toOptionalValue、toOptionalNumber 等同類 helper。
• 可選引數是否傳遞、以何種空值形態傳遞，嚴格以介面定義或明確需求為準；未明確時不在前端猜測並補充轉換邏輯。
• 後端已返回可直接展示的文案欄位時（如 xxxCn、statusText），前端必須直接使用，不額外封裝函式、不做兜底對映、不在 template/script 中做二次轉換。
• 不允許為了相容歷史欄位同時讀取多個同義字段，例如 a || b。
• 不根據前端猜測補欄位、改欄位或調整資料結構。
• 表格列表中如列表介面未返回某個展示欄位，前端不得再請求詳情介面或其他介面做兜底補齊；展示時按產品既定佔位文案處理，若需求未定義則明確標記為後端未返回。
• 後端返回欄位預設按必填處理，不額外判斷“是否必填”，也不因前端猜測把型別寫成可選欄位。
• 使用介面返回值時，只在確有需要時判斷結果物件是否存在，不針對空字串、空陣列、0 等值增加額外分支。

型別檔案約束

• API 介面相關的 TypeScript 型別必須單獨放置。
• 型別檔案需要建立在對應介面檔案的同級目錄下。
• 不要把介面型別內聯到頁面、元件或介面實現檔案中。
• API 型別定義按後端實際返回結構書寫。
• 介面文件中標註為 bigint 的欄位，前端 TypeScript 型別必須定義為 string，避免 JavaScript 數值精度丟失。
• 後端返回型別欄位預設定義為必填，不因為前端不確定就新增 ? 或額外可選型別。
• 後端欄位變更時，優先更新型別和直接消費程式碼，不新增相容層。

執行提醒

小蔥技能站7w4.net，專業的AI技能分享平臺。

• 除介面消費專屬規則外，其餘執行習慣繼續遵循 frontend-global。
• 不借介面調整順手擴充套件抽象層、轉換層或相容層。

這個 Skill 質量中等偏上，規則制定得很細緻，覆蓋了介面請求、返回值消費、型別定義等各個環節，核心思想明確——嚴格遵循後端介面，不做多餘的前端相容處理。優點是指令清晰、約束全面，能有效減少不必要的程式碼冗餘；不足是缺少示例和文件說明，規則較多導致理解成本偏高，部分規則在複雜場景下可能過於絕對。對於需要統一前端介面處理規範的專案來說有一定實用價值，但建議配合示例檔案完善文件。