文件

Adobe Commerce REST API建構函式引數插入變更 — 商家開發人員指南

Last update: Tue Sep 09 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

Adobe Commerce和Magento Open Source已變更REST API處理建構函式引數插入的方式。 此更新透過確保在API請求中僅使用適當的資料型別，強化了Web API架構。 本文也會回答與CVE-2025-54236相關的問題。

說明 description

環境

Adobe Commerce / Magento Open Source 2.4.4+， 2.4.5+， 2.4.6+， 2.4.7+， 2.4.8+， 2.4.9-alpha3 （所有部署型別）

問題

Adobe Commerce API資料型別驗證增強功能 — 商家開發人員指南

概觀

Adobe Commerce和Magento Open Source已變更REST API處理建構函式引數插入的方式。 此更新透過確保在API請求中僅使用適當的資料型別，強化了Web API架構。 本文也會回答與CVE-2025-54236相關的問題。

新增功能

Web API中的增強型型別安全性

從Adobe Commerce和Magento Open Source 2.4.4-p16、2.4.5-p15、2.4.6-p13、2.4.7-p8、2.4.8-p3和2.4.9-alpha3開始，Web API架構現在對API要求中的建構函式引數實作更嚴格的資料型別驗證。 此變更可確保：

✅簡單資料型別（字串、整數、布林值）可繼續順暢運作。
✅ API資料介面(Api\Data\*Interface)仍完全受支援。
🚫服務類別和複雜模型不再自動從API裝載具現化。

技術詳細資料

變更內容

ServiceInputProcessor 現在會在API要求處理期間更嚴格地驗證建構函式引數。 增強功能引入驗證層，在嘗試物件具現化之前先檢查引數型別。 具體而言，當系統嘗試從API裝載資料填入建構函式引數時，getConstructorData()方法中會發生此驗證。 先前已處理所有引數型別；現在只允許核准的型別通過。 

允許的資料型別

支援（不需要變更）：

簡單型別

  • string — 文字值、產品名稱、說明
  • int / integer — 數值、數量、識別碼
  • float / double — 小數、價格、重量
  • bool / boolean - True/false值，狀態標幟

API資料介面

  • 全部  *\Api\Data\*Interface個類別

可能受影響的整合

可能需要稽核的自訂整合包括：

1。 自訂擴充功能與協力廠商模組

  • 傳送非標準建構函式引數的擴充功能
  • 在API裝載中使用複雜物件插入的模組
  • 具有複雜引數結構的自訂API端點

2. 正在測試指令碼

  • 具有複雜負載的各種測試指令碼

解決方法 resolution

移轉指南

稽核您的API呼叫

詳細目錄目前的整合：

  1. API呼叫檔案： 檢閱您應用程式使用的所有已記錄API端點。
  2. 程式碼儲存庫掃描： 搜尋程式碼基底，找出具有複雜巢狀物件的API呼叫。
  3. 網路流量分析： 監視傳送至Magento的實際API裝載。
  4. 協力廠商模組檢閱： 檢查所有已安裝的API擴充功能。

識別檢查清單：

  • 建構函式引數插入： 尋找API裝載中的巢狀物件。
  • 複雜物件型別： 檢查模型類別或服務的參考。
  • 自訂屬性： 識別任何非標準API引數。
  • 擴充功能特定的API： 檢閱自訂模組API實作。

疑難排解

常見錯誤訊息

> 2.4.6 不支援的欄位名稱

{ "message": "\"{fieldName}\" is not supported. Correct the field name and try again." }

<不支援的欄位名稱=2.4.6

{ "message": "Property \"{fieldName}\" does not have accessor method \"{methodName}\" in class \"{className}\"." }

發生此狀況時：

  • 使用複雜型別的建構函式引數遭到拒絕。

偵錯步驟 

1. 在非開發人員模式下檢查API記錄(< =2.4.6)。

  • 位置： var/log/exception.log
  • 篩選器：搜尋ServiceInputProcessor個專案。
  • 分析：尋找引數處理詳細資料。

2. 使用Postman/cURL進行測試。

# Test individual API calls curl -X POST "https://your-magento-site.com/rest/V1/products" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"product":{"sku":"TEST","name":"Test Product"}}'

版本相容性

回溯相容性

  • 雖然變更維持整體回溯相容性，但複雜型別且未實作Api\Data介面的REST API引數可能會發生重大變更。

現有API

  • 所有標準Magento API保持不變。
  • 核心功能未發生重大變更。

自訂副檔名

  • 如果使用複雜的建構函式插入，可能需要更新。
  • 建議在生產部署之前進行測試。
  • 擴充功能開發人員應更新檔案。

協力廠商整合

  • 應該徹底測試。
  • 請聯絡廠商以取得相容性更新。
  • 監視升級後的整合健康狀況。

常見問題集

問：我是否需要立即更新所有的API整合？
答：只有使用複雜建構函式引數插入的整合需要更新。 大部分的標準API呼叫都能繼續運作，不會有任何變更。 排定測試和更新整合的優先順序，這些整合在API裝載中使用複雜的巢狀物件。

問：如何識別整合是否會受到影響？
答：使用新版本在開發環境中測試API呼叫。

問：是否有工具可自動移轉我的API呼叫？
答：目前沒有完全自動化的移轉工具。 大多數案例都涉及移除複雜的巢狀物件並使用適當的API資料結構。

問：使用複雜插入的現有API呼叫會發生什麼事？
答：這些API呼叫將失敗，並產生 400個錯誤請求 ​或​ 500內部伺服器錯誤 （針對< =2.4.6）。

問：此變更是否會影響GraphQL API？
答：否，此增強功能僅適用於ServiceInputProcessor的REST API要求。 GraphQL API不受影響。

問：我可以暫時停用此驗證以進行測試嗎？
答：否，此驗證內建於核心框架中，無法停用。 您可以在舊版Magento上進行測試，以驗證舊版行為。

問：如果協力廠商擴充功能受到影響，怎麼辦？
答：請聯絡供應商，以取得更新且相容的版本。 如果無法取得，請考慮其他選擇，或與開發人員合作建立相容性層。

recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f