文档

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 — 数值、数量、ID
  • 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