Akka HTTP未认证接口访问返回401而非预期404问题排查

问题根本原因 #

这个问题是Akka HTTP的指令嵌套顺序、拒绝处理优先级共同导致的，常见原因有以下三类：

• 身份认证指令的作用范围覆盖了无需认证的接口，且认证拒绝的优先级高于空响应拒绝
  如果你把全局身份认证指令写在路由定义的最外层，就算你在内层给/foos/{fooId}配了免认证逻辑，外层认证指令先执行时就会直接抛出AuthenticationFailedRejection，这个拒绝的优先级远高于rejectEmptyResponse触发的空响应拒绝，且还没走到你内层的handleErrorsAndReport指令就已经终止了流程，直接返回401。
• handleErrorsAndReport指令的位置不对，没有包裹住rejectEmptyResponse的作用域
  Akka HTTP的指令是从外到内执行、拒绝是从内到外冒泡处理的，如果你把handleErrorsAndReport写在了rejectEmptyResponse的内层，或者只包裹了业务逻辑部分，没有包含拒绝处理的上游逻辑，空响应拒绝冒泡的时候就找不到你自定义的处理器，反而会先被外层的全局异常/拒绝处理器拦截，而你全局处理器大概率把未匹配到的拒绝都转成了401。
• 免认证路由的匹配规则写法有问题，触发了隐式的认证校验
  比如你写免认证路由的时候用了pathPrefix而不是精确的path匹配，或者路由顺序写反了：先写了需要认证的/foos/**规则，再写免认证的/foos/{fooId}规则，导致请求先匹配到了需要认证的路由分支，直接触发401。

修复方案 #

你可以按照以下步骤排查修复：

1. 调整指令嵌套顺序，把免认证路由放在全局身份认证指令的外层，示例正确结构：

// 先写免认证路由
path("foos" / Segment) { fooId =>
  get {
    handleErrorsAndReport {
      rejectEmptyResponse {
        complete(service.do(fooId))
      }
    }
  }
} ~
// 再写需要认证的全局路由
authenticateOAuth2(realm = "xxx", authenticator = xxx) { user =>
  // 其他需要认证的接口
}

2. 确保handleErrorsAndReport指令同时包含异常处理和拒绝处理的逻辑，默认的handleExceptions只会处理异常不会处理Rejection，你需要同时搭配handleRejections指令才能捕获rejectEmptyResponse抛出的空响应拒绝，转成404。
3. 核对路由匹配顺序，把路径更精确的路由规则放在更靠前的位置，避免被宽泛的前缀路由提前匹配。

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