Scala Play框架@Named注解注入SttpBackend失败原因咨询

为实现应用请求代理到图片服务器，我做了如下配置：
在ModuleDependencies中绑定命名为"sttp-backend"的SttpBackend[Future, Any]实例：

class ModuleDependencies
  extends SimpleModule((_, conf) => {

    ...
    val httpClient: HttpClient.Default = HttpClient.Default()

    Seq(
      ...
      bind[SttpBackend[Future, Any]]
        .qualifiedWith("sttp-backend")
        .toInstance(httpClient.backend)
      )
  })

在ControllerProxy中通过@Named("sttp-backend")注入该实例：

@Singleton
class ControllerProxy @Inject() (implicit
  cc: ControllerComponents,
  config: Configuration,
  ec: ExecutionContext,
  @Named("sttp-backend") backend: SttpBackend[Future, Any])
  extends AbstractController(cc) with LazyLogging {

  def proxyImageRequest: Action[AnyContent] = Action.async {
    request: Request[AnyContent] =>
      ...
      emptyRequest
        .method(Method.GET, url)
        .header("Authorization", config.authKey)
        .followRedirects(true)
        .readTimeout(Duration("10s"))
        .response(asByteArray)
        .send(backend)
        .map(returnJpeg(_))
        .recover { case e =>
          logger.error("Exception caught while proxying image request " + e.getMessage)
          InternalServerError
        }
  }
}

并在application.conf中启用自定义模块：

play {

  modules.enabled += module.ModuleDependencies
  ...
}

项目编译正常，但启动服务器访问健康检查端点时，出现Guice异常：

Internal server error, for (GET) [/api/health-check] ->
  play.api.UnexpectedException: Unexpected exception[CreationException: Unable to create injector, see the following errors:

1) [Guice/MissingImplementation]: No implementation for SttpBackend<Future, Object> annotated with @name.Named("sttp-backend") was bound.

Did you mean?
    SttpBackend annotated with @name.Named("sttp-backend") bound at module.ModuleDependencies$$anonfun$$lessinit$greater$1.apply(ModuleDependencies.scala:25):
Binding(interface SttpBackend qualified with QualifierInstance(@inject.Named(value=sttp-backend)) to ProviderTarget(BindingKey$$anon$1@118f795e))
      _ installed by: Modules$OverrideModule -> GuiceableModuleConversions$$anon$4

Requested by:
1  : controllers.ControllerProxy.<init>(ControllerProxy.scala:27)
      _ for 4th parameter backend
     at router.Routes.<init>(Routes.scala:60)
      _ for 5th parameter ControllerProxy_2
     at RoutesProvider$.bindingsFromConfiguration(BuiltinModule.scala:139):
Binding(class router.Routes to self)
      _ installed by: Modules$OverrideModule -> GuiceableModuleConversions$$anon$4

Learn more:
  https://github.com/google/guice/wiki/MISSING_IMPLEMENTATION

可以通过创建case class封装SttpBackend[Future, Any]来实现注入：

case class SttpFutureBackend(unwrap: SttpBackend[Future, Any]) {}

我想知道的不是解决方法，而是命名注入失败的原因，以及如何排查这个问题。错误信息明明显示已经存在对应的命名绑定，但Guice还是找不到实现。

原因分析 #

1. 类型擦除导致匹配失效
   Scala泛型编译后会丢失具体类型信息，Guice运行时只能识别SttpBackend裸类型，无法区分SttpBackend[Future, Any]和其他泛型变体。错误信息里的SttpBackend<Future, Object>（Java层面类型）和你绑定的SttpBackend[Future, Any]，虽然逻辑等价，但Guice的严格类型匹配会因为泛型表示差异判定不匹配。

2. 注解包不一致
   检查@Named注解的导入包：如果注入时用的是javax.inject.Named，但绑定代码中qualifiedWith对应的是Guice自带的com.google.inject.name.Named，Guice会认为这两个注解不属于同一类型，导致绑定匹配失败。

3. 模块加载顺序问题
   Play框架中模块加载顺序会影响绑定生效时机，如果ControllerProxy所在模块比ModuleDependencies先加载，Guice创建ControllerProxy实例时，你的命名绑定还未完成注册，自然找不到实现。

排查步骤 #

1. 打印所有Guice绑定信息
   在应用启动代码中添加打印逻辑，输出所有已注册的绑定，对比绑定类型和注入点类型是否完全一致：

import com.google.inject.Guice
import com.google.inject.util.Modules

val injector = Guice.createInjector(Modules.override(new ModuleDependencies()).with())
injector.getAllBindings.forEach { (key, binding) =>
  println(s"绑定条目: $key -> $binding")
}

重点关注泛型部分的显示是否与注入点的SttpBackend[Future, Any]匹配。

2. 核对注解导入包
   分别查看ControllerProxy和ModuleDependencies中@Named的导入语句，确保两边使用的是同一个包的注解（推荐统一用javax.inject.Named）。

3. 调整模块加载顺序
   在application.conf中将module.ModuleDependencies放在所有自定义模块最前面：

play {
  modules.enabled = [
    module.ModuleDependencies,
    # 其他模块依次放在后面
  ]
}

或者给ControllerProxy所在模块添加依赖声明，强制其在ModuleDependencies加载完成后再启动。

4. 用TypeLiteral绕过类型擦除
   绑定代码中使用TypeLiteral保留泛型信息，让Guice能精准识别类型：

// 修改绑定代码
bind(new TypeLiteral[SttpBackend[Future, Any]] {})
  .qualifiedWith("sttp-backend")
  .toInstance(httpClient.backend)

注入部分无需修改，即可避免类型擦除导致的匹配问题。

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