如何在Magento 2（2.4.4版本）中创建自定义SOAP API

Magento 2.4.4没有独立的SOAP端点开发逻辑，所有SOAP能力完全复用Service Contract层的Web API定义，只要按规范声明服务接口，系统会自动生成对应SOAP端点和WSDL结构，这也是相关公开资料少的核心原因。

一、创建基础模块结构 #

所有自定义代码放在app/code/Vendor/CustomSoap目录下（Vendor替换为你自己的厂商名，CustomSoap替换为你自己的模块名），先创建两个基础文件：

• 模块注册文件registration.php

<?php
\Magento\Framework\Component\ComponentRegistrar::register(
    \Magento\Framework\Component\ComponentRegistrar::MODULE,
    'Vendor_CustomSoap',
    __DIR__
);

• 模块声明文件etc/module.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_CustomSoap" setup_version="1.0.0"/>
</config>

二、定义Service Contract接口 #

SOAP对参数、返回值的类型校验比REST严格，所有接口方法必须明确声明参数类型和返回值类型，必须加@api注解才会被Web API组件识别。

1. 先定义返回值的数据实体接口Api/CustomDataInterface.php

<?php
namespace Vendor\CustomSoap\Api;

/**
 * @api
 */
interface CustomDataInterface
{
    /**
     * @return int
     */
    public function getEntityId(): int;

    /**
     * @param int $entityId
     * @return $this
     */
    public function setEntityId(int $entityId): self;

    /**
     * @return string
     */
    public function getContent(): string;

    /**
     * @param string $content
     * @return $this
     */
    public function setContent(string $content): self;
}

2. 再定义服务端点接口Api/CustomSoapEndpointInterface.php，这个就是SOAP服务的对外入口

<?php
namespace Vendor\CustomSoap\Api;

/**
 * @api
 */
interface CustomSoapEndpointInterface
{
    /**
     * 查询自定义数据
     * @param int $entityId
     * @return \Vendor\CustomSoap\Api\CustomDataInterface
     */
    public function getCustomData(int $entityId): \Vendor\CustomSoap\Api\CustomDataInterface;
}

三、编写接口实现代码 #

1. 数据实体实现类Model/CustomData.php，直接继承框架DataObject简化get/set逻辑

<?php
namespace Vendor\CustomSoap\Model;

use Magento\Framework\DataObject;
use Vendor\CustomSoap\Api\CustomDataInterface;

class CustomData extends DataObject implements CustomDataInterface
{
    public function getEntityId(): int
    {
        return (int)$this->getData('entity_id');
    }

    public function setEntityId(int $entityId): CustomDataInterface
    {
        return $this->setData('entity_id', $entityId);
    }

    public function getContent(): string
    {
        return (string)$this->getData('content');
    }

    public function setContent(string $content): CustomDataInterface
    {
        return $this->setData('content', $content);
    }
}

2. 服务端点实现类Model/CustomSoapEndpoint.php，在这里写具体业务逻辑

<?php
namespace Vendor\CustomSoap\Model;

use Vendor\CustomSoap\Api\CustomDataInterface;
use Vendor\CustomSoap\Api\CustomSoapEndpointInterface;

class CustomSoapEndpoint implements CustomSoapEndpointInterface
{
    private $customDataFactory;

    // 数据实体的工厂类不需要手动写，Magento会自动生成，直接依赖注入即可
    public function __construct(CustomDataFactory $customDataFactory)
    {
        $this->customDataFactory = $customDataFactory;
    }

    public function getCustomData(int $entityId): CustomDataInterface
    {
        // 示例为模拟返回，实际场景替换为自己的业务逻辑，比如查表、调第三方服务等
        $data = $this->customDataFactory->create();
        $data->setEntityId($entityId);
        $data->setContent("ID为{$entityId}的自定义SOAP返回内容");
        return $data;
    }
}

四、配置Web API与依赖绑定 #

1. 创建etc/webapi.xml配置服务路由，这个配置同时对REST和SOAP生效，不需要单独为SOAP写路由

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <route url="/V1/custom-soap/get-data/:entityId" method="GET">
        <service class="Vendor\CustomSoap\Api\CustomSoapEndpointInterface" method="getCustomData"/>
        <resources>
            <!-- anonymous代表匿名可访问，需要鉴权的话替换为自己定义的ACL资源 -->
            <resource ref="anonymous"/>
        </resources>
    </route>
</routes>

2.4.4版本踩坑：不要尝试单独给SOAP加路由配置，只要webapi.xml里声明了service，系统会自动生成对应的SOAP operation，额外配置会导致WSDL解析报错。

2. 创建etc/di.xml绑定接口和实现类的对应关系

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="Vendor\CustomSoap\Api\CustomDataInterface" type="Vendor\CustomSoap\Model\CustomData"/>
    <preference for="Vendor\CustomSoap\Api\CustomSoapEndpointInterface" type="Vendor\CustomSoap\Model\CustomSoapEndpoint"/>
</config>

五、部署验证 #

在站点根目录执行以下命令启用模块、清理缓存：

bin/magento module:enable Vendor_CustomSoap
bin/magento setup:upgrade
bin/magento cache:clean
bin/magento cache:flush

部署完成后，WSDL访问地址为https://你的站点域名/soap/default?wsdl&services=customSoapEndpointV1，其中服务名规则为接口类名的驼峰转小写开头+V1，比如CustomSoapEndpointInterface对应服务名就是customSoapEndpointV1。

PHP调用示例：

<?php
$opts = [
    'http' => [
        // 非匿名访问需要传集成模式生成的Access Token
        'header' => 'Authorization: Bearer 你的访问令牌'
    ]
];
$context = stream_context_create($opts);
$client = new SoapClient('https://你的站点域名/soap/default?wsdl&services=customSoapEndpointV1', [
    'context' => $context,
    'trace' => 1
]);
$result = $client->customSoapEndpointV1GetCustomData(['entityId' => 1]);
var_dump($result);

2.4.4版本常见问题 #

• 接口方法不能用mixed、array等无明确结构的类型声明，返回列表必须在注解中标明具体实体类数组格式，比如@return \Vendor\CustomSoap\Api\CustomDataInterface[]，否则WSDL生成会缺失节点
• 开启2FA的场景下，不能用后台登录的Cookie直接调用SOAP接口，必须用集成生成的Access Token做鉴权
• 不要修改核心框架的wsdl生成逻辑，所有自定义能力都通过Service Contract扩展

内容的提问来源于stack exchange，提问作者m3k_1