WSO2 APIM含特殊字符的URL返回404问题求助

问题原因 #

WSO2 APIM 4.2.0默认使用的Choreo Connect网关会自动对请求URL进行解码。当路径参数包含@这类特殊字符（无论是原始形式还是URL编码后的%40），解码后的字符会干扰网关的资源路径匹配逻辑——网关会错误地将@识别为路径分隔符或特殊标记，导致无法匹配到预定义的资源模板（如/code/{code}），最终返回404。

CORS预检OPTIONS请求的路径与实际GET请求完全一致，同样会触发上述路径匹配失败，因此也返回404，前端会将其识别为CORS错误。

可尝试的配置解决方案 #

1. 保留URL编码，避免提前解码 #

在APIM主配置文件deployment.toml中添加以下配置，让网关保留原始URL编码，不提前解码路径参数：

[apim.gateway]
preserve_encoding = true

添加后重启APIM服务，网关会直接使用编码后的路径进行资源匹配，避免@字符干扰匹配逻辑。

2. 启用严格路由匹配模式 #

修改deployment.toml中的网关环境配置，启用严格路由验证：

[apim.gateway.environment]
route_validation_mode = "strict"

严格模式下，网关会严格按照API定义的资源模板进行匹配，忽略解码后字符带来的解析干扰。

3. 自定义CORS序列处理OPTIONS请求 #

如果上述配置仍无法解决OPTIONS请求404问题，可给API添加自定义入站序列直接处理预检请求：

1. 登录APIM Publisher，进入目标API的「Sequences」配置页
2. 创建新的入站序列，内容如下：

<sequence xmlns="http://ws.apache.org/ns/synapse" name="Custom_CORS_Handler">
    <property name="Access-Control-Allow-Origin" value="*" scope="transport"/>
    <property name="Access-Control-Allow-Methods" value="GET, OPTIONS" scope="transport"/>
    <property name="Access-Control-Allow-Headers" value="Content-Type, Authorization" scope="transport"/>
    <property name="Access-Control-Max-Age" value="3600" scope="transport"/>
    <filter source="get-property('REQUEST_METHOD')" regex="OPTIONS">
        <then>
            <respond/>
        </then>
    </filter>
</sequence>

3. 将该序列绑定到API的入站序列中，OPTIONS请求会直接返回CORS响应头，无需触发路径匹配逻辑。

临时替代方案补充 #

如果配置调整无效，除了改用数字ID的API变体，还可将特殊字符参数从路径参数改为查询参数（如/code?code=FOO%40BAR），这种方式不会触发路径匹配问题，APIM可正常转发请求到后端。

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