android - Dagger2 自定义范围 : How do custom-scopes (@ActivityScope) actually work?

Question

我正在阅读 Dagger2 Component Scopes Test 的源代码在 GitHub 上，我看到了为名为 @ActivityScope 的 Activity 定义的“自定义范围”，但我在其他项目中看到了它，包括 4 模块 CleanArchitecture有它的 @PerActivity 范围。

但从字面上看，@ActivityScope 注解的代码如下:

import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;

import javax.inject.Scope;

/**
 * Created by joesteele on 2/15/15.
 */
@Scope
@Retention(RetentionPolicy.RUNTIME)
public @interface ActivityScope {
}

它在模块中“神奇地”可用:

@Module
public class ActivityModule {
  @Provides @ActivityScope Picasso providePicasso(ComponentTest app, OkHttpClient client) {
    return new Picasso.Builder(app)
        .downloader(new OkHttpDownloader(client))
        .listener(new Picasso.Listener() {
          @Override public void onImageLoadFailed(Picasso picasso, Uri uri, Exception e) {
            Log.e("Picasso", "Failed to load image: " + uri.toString(), e);
          }
        })
        .build();
  }
}

或者CleanArchitecture例子:

@Scope
@Retention(RUNTIME)
public @interface PerActivity {}

@PerActivity
@Component(dependencies = ApplicationComponent.class, modules = ActivityModule.class)
public interface ActivityComponent {
  //Exposed to sub-graphs.
  Activity activity();
}

@Module
public class ActivityModule {
  private final Activity activity;

  public ActivityModule(Activity activity) {
    this.activity = activity;
  }

  /**
  * Expose the activity to dependents in the graph.
  */
  @Provides @PerActivity Activity activity() {
    return this.activity;
  }
}

我可以清楚地看到这与 JSR-330 自定义范围有关，但我真的不明白这里到底发生了什么，以便此代码启用给定的模块和/或给定模块提供的内容取决于实际的 Activity 生命周期，并且仅存在一个实例，但前提是该给定 Activity 处于 Activity 状态。

文档是这样说的:

Scope

Dagger 1 only supported a single scope: @Singleton. 
Dagger 2 allows users to any well-formed scope annotation. 
The Component docs describe the details of 
    how to properly apply scope to a component.

它说看Component docs page ，但这给了我 404。我还看到了 this ，但是……

我是否可以请求一些帮助以澄清为什么指定此自定义范围会神奇地使 Activity 级范围 正常工作？

(答案是，子作用域可以从其超作用域接收依赖，只要组件存在，子作用域就存在。而且你需要在你的模块上指定作用域，你需要指定你的组件对子作用域的依赖关系一个 super 作用域。)

Answer 1

其实没有魔法。自定义范围注释只是注释。他们可以有任何名字。

作用域的第一个功能是告诉 Dagger 编译器在作用域组件中允许哪些作用域。这就是为什么在非@ActivityScope 组件中使用@ActivityScope 依赖会引发编译错误。

事实上组件可以声明许多作用域(例如 @ActivityScope 和 @UiScope)并且 Dagger 会将它们都视为单个作用域 - 这称为作用域别名。例如，它在多模块项目中很有用——当一个 Gradle 模块使用其 Dagger 模块定义一个范围，而另一个 Gradle 模块定义另一个范围时，它们都可以在定义 Dagger 组件的第三个 Gradle 模块中用作单个别名范围。

第二个功能是限制作用域组件内允许的实例数量。支持多种类型的范围:

Unscoped - 当没有声明注释时。无作用域的依赖将生成简单的 Provider 而没有任何缓存，并且在组件中创建的该依赖的任何实例对于每次新注入(inject)都是新的(如在构造函数中，或在模块提供方法中，或仅作为字段) .

自定义范围 例如使用 @javax.inject.Scope 注释定义的 @ActivityScope 注释 - 使用该范围声明的依赖项具有缓存 Provider 并生成双重检查锁并在具有相同范围声明的组件中，只会为其创建单个实例，并且它的创建将是线程安全的。请注意，对于组件本身的每个实例，都将创建该依赖项的新实例。

可重用范围 - 使用 @dagger.Reusable 注释声明 - 使用该范围声明的依赖项可以通过公共(public)父组件在不同组件之间共享，并且将具有缓存 提供者 生成了单检查锁。当依赖项不一定需要具有单个实例但可以共享以提高单个组件或组件之间的性能(更少分配)时，它很有用。

有关范围如何工作的更多信息，请参阅 user's guide和 Dagger 生成的代码。

如何定义实际范围是您的特权。定义范围组件的生命周期，何时创建和何时销毁 - 这是您的范围。例如。 @ActivityScope 绑定(bind)到 Activity 生命周期并定义如下:

private ActivityComponent component;

@Override
protected void onCreate(Bundle savedInstanceState) {
    component = DaggerActivityComponent.builder().build();
    component.inject(this);
}

@Override
protected void onDestroy() {
    component = null;
    super.onDestroy();
}

所以没有魔法。通过使用它们的语义来定义你的范围。您可能还会发现有用的 this answer和 these examples .

EDIT 14.10.2018 扩展了范围函数和类型，以消除先前答案中的歧义。