API Gateway V2 Http API映射指定Path时返回404 Not Found问题

核心原因 #

API Gateway V2（Http API）的自定义域名路径映射采用基础路径替换逻辑，与V1的路径追加机制完全不同：

• 若映射Path设为/foo，请求dev.myapp.com/foo/bar会被转发到后端API的/bar路径（/foo前缀被移除）
• 若映射Path为空，请求路径会原样转发到后端API

你的场景中，当映射Path填/oauth/callback/app时，请求dev.myapp.com/oauth/callback/app会被重写为空路径转发，但后端API仅配置了/oauth/callback/app路径，因此匹配失败返回404；而映射Path为空时，请求路径原样转发，正好匹配后端API路径，所以成功。

解决方案 #

针对多路径映射的需求，提供两种可行方案：

方案1：调整后端API路径适配映射逻辑 #

1. 修改Serverless配置中的API路径，移除映射前缀：

   functions:
     oauth-callback:
       handler: src/infra/oauth-app-callback-service/index.handler
       name: ${self:service}-oauth-callback-${sls:stage}
       events:
         - httpApi:
             path: /callback/app  # 去掉/oauth前缀
             method: GET
   

2. 重新部署API后，在自定义域名映射中设置Path为/oauth
3. 此时请求dev.myapp.com/oauth/callback/app会被重写为/callback/app，完美匹配后端API路径，返回200

如果要添加其他映射（比如/api前缀的接口），同理操作：

• 后端API路径设为/users
• 自定义域名映射Path设为/api
• 请求dev.myapp.com/api/users会转发到/users匹配后端API

方案2：配置路径重写规则（保留原API路径） #

如果不想修改后端API路径，可以通过AWS CLI或CloudFormation配置路径重写，让请求路径原样转发：

用AWS CLI创建映射：

aws apigatewayv2 create-api-mapping \
  --api-id 你的APIID \
  --domain-name dev.myapp.com \
  --stage $default \
  --api-mapping-key oauth/callback/app \
  --request-parameters '{"overwrite:path": "/oauth/callback/app"}'

在Serverless中添加自定义资源：

resources:
  Resources:
    CustomOAuthMapping:
      Type: AWS::ApiGatewayV2::ApiMapping
      Properties:
        ApiId: !Ref HttpApi  # 替换为你的API资源名，可通过sls deploy --verbose查看
        DomainName: dev.myapp.com
        Stage: $default
        ApiMappingKey: oauth/callback/app
        RequestParameters:
          overwrite:path: "'/oauth/callback/app'"

额外排查点 #

• 映射的Path必须以/开头（比如/oauth而非oauth），否则匹配逻辑失效
• 验证DNS解析是否正确指向APIGW的Regional端点（用nslookup dev.myapp.com检查）
• 确认API已部署到$default阶段（Serverless默认部署到此阶段）

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