如何在WSO2 API Manager 3.2.0中自定义响应错误消息及格式转换？

一、将响应错误格式从XML转换为JSON #

操作步骤： #

1. 修改全局故障序列配置
   打开路径为 <APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences/fault.xml 的配置文件，修改以下配置：
   • 找到消息类型配置行，将内容修改为：

     <property name="messageType" value="application/json" scope="axis2"/>
     <property name="ContentType" value="application/json" scope="axis2"/>
     

   • 找到默认的payloadFactory节点，将media-type属性改为json，替换原XML结构的响应模板为JSON结构，示例如下：

     <payloadFactory media-type="json">
         <format>{"error":{"code":"$1","message":"$2","description":"$3"}}</format>
         <args>
             <arg evaluator="xml" expression="$ctx:ERROR_CODE"/>
             <arg evaluator="xml" expression="$ctx:ERROR_MESSAGE"/>
             <arg evaluator="xml" expression="$ctx:ERROR_DETAIL"/>
         </args>
     </payloadFactory>
     

2. 适配自定义故障序列
   如果你为部分API单独配置了自定义故障序列，需要按照上述相同逻辑修改对应API的故障序列配置，否则这部分API的错误响应仍然会沿用原配置格式。
3. 生效验证
   配置修改后会热部署生效，不需要重启服务，直接调用API触发错误即可验证返回格式是否为JSON。

二、自定义各类错误消息配置 #

不同场景的配置方法： #

• 全局通用错误自定义
  直接修改上述fault.xml中的payloadFactory模板内容，即可调整全局所有错误响应的字段、提示文案，支持通过$ctx:前缀调用WSO2 APIM内置的上下文变量，比如错误码、错误详情、请求ID等。
• 特定错误码自定义提示
  可以在故障序列中添加条件判断逻辑，针对特定错误码返回自定义的提示内容，示例配置如下：

  <!-- 针对令牌过期错误900901返回自定义提示 -->
  <filter source="$ctx:ERROR_CODE" regex="900901">
      <then>
          <payloadFactory media-type="json">
              <format>{"error":{"code":"AUTH001","message":"访问凭证已过期","description":"请重新登录获取有效令牌后重试"}}</format>
          </payloadFactory>
          <property name="HTTP_SC" value="401" scope="axis2"/>
      </then>
  </filter>
  

• 全量API错误规则批量生效
  如果需要让所有新发布的API都遵循自定义错误规则，可以修改API生成模板：<APIM_HOME>/repository/resources/api_templates/velocity_template.xml中的故障处理部分，修改后重启APIM服务，重新发布现有API即可批量生效。
• 网关层面错误自定义
  针对连接超时、后端服务不可达等网关层面抛出的错误，同样可以在fault.xml中添加对应的错误码判断逻辑，自定义返回文案和格式。

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