Java SOAP接口单条返回数据PHP无法识别为数组的问题求助

这个问题是SOAP/XML序列化里的经典“坑”——当集合只有单个元素时，很多SOAP客户端（包括PHP的内置SOAP扩展）会默认把它解析成单个对象而非数组，但完全可以在Java后端通过调整序列化配置来解决，不需要PHP开发者额外做类型判断。

问题根源 #

你的WSDL已经正确定义了hint元素的maxOccurs="unbounded"，但JAX-WS默认的序列化逻辑在处理单元素List时，会生成单个<hint>元素的XML结构，而PHP的SOAP扩展默认会根据XML的实际节点数量来决定解析结果（单个节点→对象，多个节点→数组），而非严格遵循WSDL的定义。

后端修复方案（二选一即可） #

方案1：将List改为数组类型

把GetSearchHintResponse中的List<Hint>替换为Hint[]数组，这样不管集合中有多少元素，JAX-WS都会按照数组结构序列化，PHP端会直接识别为数组：

修改GetSearchHintResponse类：

public class GetSearchHintResponse {
    public static class Hint {
        private String text;
        
        public String getText() {
            return text;
        }
        
        public void setText(String text) {
            this.text = text;
        }
    }

    // 将List改为数组
    private Hint[] hint;

    public Hint[] getHint() {
        return hint;
    }

    public void setHint(Hint[] hint) {
        this.hint = hint;
    }
}

然后在端点代码中，把List转换为数组：

@PayloadRoot(namespace = NAMESPACE_URI, localPart = "getSearchHintRequest")
@ResponsePayload
public GetSearchHintResponse getSearchHintRequest(@RequestPayload GetSearchHintRequest request) throws Exception {
    GetSearchHintResponse response = new GetSearchHintResponse();
    Collection<? extends String> hintsStr = searchComponent.getSearchHint(request.getBeginning(), request.getCollections(), request.getHintCount());
    
    List<GetSearchHintResponse.Hint> hintsList = new ArrayList<>();
    for (String hintStr : hintsStr) {
        GetSearchHintResponse.Hint hint = new GetSearchHintResponse.Hint();
        hint.setText(hintStr + "\t");
        hintsList.add(hint);
    }
    
    // 转换为数组并设置到response
    response.setHint(hintsList.toArray(new GetSearchHintResponse.Hint[0]));
    return response;
}

方案2：添加JAXB注解强制数组序列化

如果不想修改集合类型，也可以通过JAXB的@XmlElement注解明确指定hint元素的序列化规则，强制JAX-WS把List当作数组处理：

修改GetSearchHintResponse类的List字段：

import javax.xml.bind.annotation.XmlElement;
import java.util.List;

public class GetSearchHintResponse {
    public static class Hint {
        private String text;
        
        // 确保text元素必填
        @XmlElement(required = true)
        public String getText() {
            return text;
        }
        
        public void setText(String text) {
            this.text = text;
        }
    }

    private List<Hint> hint;

    // 明确指定该元素为 unbounded 类型，强制序列化为数组结构
    @XmlElement(name = "hint", required = true, maxOccurs = "unbounded")
    public List<Hint> getHint() {
        return hint;
    }

    public void setHint(List<Hint> hint) {
        this.hint = hint;
    }
}

这个注解会告诉JAX-WS序列化器，无论List中有多少元素，都要按照maxOccurs="unbounded"的规则生成XML，PHP端解析时会严格遵循WSDL的定义，把单个hint元素识别为数组。

为什么不推荐让PHP端处理？ #

虽然PHP端可以通过开启SOAP_SINGLE_ELEMENT_ARRAYS特性，或者手动判断类型转换，但这种做法会增加客户端的耦合性和维护成本。从接口设计的角度，后端应该保证返回的数据结构和WSDL定义完全一致，这样客户端可以不用处理特殊情况，更符合SOAP协议的规范。

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