JSR-330 JAVA 依赖注入标准API说明

JSR-330 JAVA 依赖注入标准

Package javax.inject

这个包规定了一种获取对象的方法，与构造函数、工厂和服务定位器（如JNDI）等传统方法相比，它可以最大限度地提高可重用性、可测试性和可维护性。这个过程被称为依赖性注入，对大多数非琐碎的应用都是有益的。

许多类型依赖于其他类型。例如，一个Stopwatch可能依赖于一个TimeSource。一个类型所依赖的类型被称为它的依赖关系。在运行时找到一个依赖关系的实例来使用的过程被称为解析依赖关系。如果找不到这样的实例，则表示该依赖关系未被满足，并且应用程序运行失败。

在没有依赖注入的情况下，一个对象可以通过几种方式解决其依赖关系。它可以调用一个构造函数，将一个对象直接与它的依赖关系的实现和生命周期硬连接起来：

 class Stopwatch {
     final TimeSource timeSource;
     Stopwatch () {
       timeSource = new AtomicClock(...); // 通过调用构造函数新建一个依赖对象
     }
     void start() { ... }
     long stop() { ... }
   }
1
2
3
4
5
6
7
8

如果需要更多的弹性，该对象可以调用一个工厂或服务定位器：

  class Stopwatch {
     final TimeSource timeSource;
     Stopwatch () {
       timeSource = DefaultTimeSource.getInstance(); // 通过工厂方式新建一个依赖对象
     }
     void start() { ... }
     long stop() { ... }
   }
1
2
3
4
5
6
7
8

在决定这些传统的依赖解决方法时，程序员必须做出权衡。（1）构造器更简洁，但有限制性。（2）工厂在一定程度上将客户端和实现解耦，但需要模板代码。（3）服务定位器甚至可以进一步解耦，但会降低编译时的类型安全性。这三种方法都抑制了单元测试。例如，如果程序员使用工厂，那么针对依赖工厂的代码的每个测试都必须模拟出工厂，并记得自己清理，否则就会有不利影响。

   void testStopwatch() {
     TimeSource original = DefaultTimeSource.getInstance();
     DefaultTimeSource.setInstance(new MockTimeSource());
     try {
       // Now, we can actually test Stopwatch.
       Stopwatch sw = new Stopwatch();
       ...
     } finally {
       DefaultTimeSource.setInstance(original);
     }
   }
1
2
3
4
5
6
7
8
9
10
11

在实践中，模拟工厂的能力会导致更多的模板代码。对多个依赖关系进行模拟和清理的测试很快就会失去控制。更糟糕的是，程序员必须准确地预测未来需要多少灵活性，否则就会承担后果。如果程序员最初选择使用一个构造函数，但后来决定需要更多的灵活性，那么程序员必须替换对构造函数的每一次调用。如果程序员谨慎行事，预先写好工厂，可能会导致大量不必要的模板代码，增加复杂性和易错性。

依赖性注入解决了所有这些问题。程序员不需要调用构造函数或工厂，而是由一个叫做依赖注入器的工具将依赖关系传递给对象。

class Stopwatch {
     final TimeSource timeSource;
     @Inject Stopwatch(TimeSource TimeSource) {
       this.TimeSource = TimeSource;
     }
     void start() { ... }
     long stop() { ... }
   }
1
2
3
4
5
6
7
8

injector（注入器） 进一步将依赖关系传递给其他依赖关系，直到构建出整个对象图。例如，假设程序员要求注入器创建一个StopwatchWidget实例。

   /** GUI for a Stopwatch */
   class StopwatchWidget {
     @Inject StopwatchWidget(Stopwatch sw) { ... }
     ...
   }
1
2
3
4
5

injector 可能：

• 找到一个TimeSource 实例
• 用TimeSource实例构建一个Stopwatch实例
• 用Stopwatch实例构造一个StopwatchWidget

这使得程序员的代码干净、灵活，并且相对来说没有依赖性相关的基础设施。

在单元测试中，程序员现在可以直接构造对象（没有注入器），并传递模拟依赖。程序员不再需要在每个测试中建立和拆除工厂或服务定位器。这大大简化了我们的单元测试。

void testStopwatch() {
     Stopwatch sw = new Stopwatch(new MockTimeSource());
     ...
   }
1
2
3
4

单元测试复杂性的总减少量与单元测试的数量和依赖关系的数量的乘积成正比。

这个包提供了依赖注入注解，使可移植类得以实现，但它将外部依赖配置留给注入器实现。 程序员对构造函数、方法和字段进行注解，以表明其可注入性（构造函数注入在上面的例子中得到了证明）。依赖性注入器通过检查这些注释来识别一个类的依赖性，并在运行时注入依赖性。此外，injector 可以在构建时验证所有的依赖关系是否被满足。相比之下，A service locator(服务定位器)在运行时才能发现未满足的依赖关系。

注入器的实现可以采取多种形式。注入器可以使用XML、注解、DSL（特定领域语言），甚至是普通的Java代码来配置自己。一个注入器可以依靠反射或代码生成。一个使用编译时代码生成的注入器甚至可能没有自己的运行时表示。其他注入器可能根本无法生成代码，无论是在编译还是运行时。一个 “容器”，对于某些定义来说，可以是一个注入器，但这个包规范的目的是尽量减少对注入器实现的限制。

@Inject注解

@Inject注解标明可注入的构造函数、方法和字段。可以适用于静态和实例成员。一个可注入的成员可以有任何访问修饰符（private, package-private, protected, public）。构造函数首先被注入，其次是字段，然后是方法。超类中的字段和方法在子类中的字段和方法之前被注入。在同一类中的字段和方法之间的注入顺序没有被指定。

可注入的构造函数用@Inject注解，并接受零个或多个依赖作为参数。一个类中的只支持在一个构造函数上添加注解@Inject。

当没有其他构造函数时，@Inject对于公共的、无参数的构造函数是可选的。这使得注入器可以调用默认的构造函数。

什么是可注入的字段:

• 用@Inject注释的。
• not final
• may have any otherwise valid name.可以有任何其他有效的名称。

什么是可注入的方法：

• 用@Inject注释的。
• 不是abstract。
• 不声明它们自己的类型参数。
• 可以返回一个结果
• 可以有任何其他有效的名称。
• 接受零个或多个依赖作为参数。

注入器忽略注入方法的结果，但允许非void的返回类型，以支持在其他情况下使用该方法（例如，构建器式的方法链）。

Examples：

 public class Car {
     // Injectable constructor
     @Inject public Car(Engine engine) { ... }

     // Injectable field
     @Inject private Provider<Seat> seatProvider;

     // Injectable package-private method
     @Inject void install(Windshield windshield, Trunk trunk) { ... }
   }
1
2
3
4
5
6
7
8
9
10

一个用@Inject注解的方法如果覆写了另一个用@Inject注解的方法，每个实例的每个注入请求将只被注入一次。一个没有@Inject注解的方法如果覆写了一个用@Inject注解的方法，将不会被注入。

进行成员注入时必须进行@Inject注解标明。虽然一个可注入的成员可以使用任何可访问性修饰符（包括私有），但平台或注入器的限制（如安全限制或缺乏反射支持）可能会阻止非公共成员的注入。

Qualifiers

一个限定符可以注解一个可注入的字段或参数，并与类型相结合，确定要注入的实现。修饰符是可选的，当在独立于注入器的类中与 @Inject 一起使用时，一个字段或参数不能有超过一个修饰符。在下面的例子中，限定词是@Leather，@Tinted，@Big。

  public class Car {
     @Inject private @Leather Provider<Seat> seatProvider;

     @Inject void install(@Tinted Windshield windshield,
         @Big Trunk trunk) { ... }
   }
1
2
3
4
5
6

如果一个可注入方法覆盖另一个方法，覆盖方法的参数不会自动继承被覆盖方法的参数的限定词。

Injectable Values

对于一个给定的类型T和可选的限定符，一个注入器必须能够注入一个用户指定的类，该类。

1. 与T的赋值兼容，并且
2. 有一个可注入的构造函数。

例如，用户可以使用外部配置来选择T的实现。除此之外，哪些值被注入取决于注入器的实现和它的配置。

Circular Dependencies

检测和解决循环依赖是留给注入器实现的一个练习。两个构造函数之间的循环依赖是一个明显的问题，但你也可以在可注入的字段或方法之间有一个循环依赖。

  class A {
     @Inject B b;
   }
   class B {
     @Inject A a;
   }
1
2
3
4
5
6

当构造一个A的实例时，一个“天真”的注入器实现可能会进入一个无限的循环，构造一个B的实例来设置在A上，第二个A的实例来设置在B上，第二个B的实例来设置在第二个A的实例上，等等。

“保守”的注入器可能会在构建时检测到循环依赖并产生错误，此时程序员可以通过注入Provider或Provider代替A或B来打破循环依赖关系。从它被注入的构造函数或方法中直接调用get()，会破坏提供者打破循环依赖的能力。在方法或字段注入的情况下，对其中一个依赖的范围（例如，单例作用域）也可以实现有效的循环关系。

   @java.lang.annotation.Documented
   @java.lang.annotation.Retention(RUNTIME)
   @javax.inject.Qualifier
   public @interface Leather {
     Color color() default Color.TAN;
     public enum Color { RED, BLACK, TAN }
   }
1
2
3
4
5
6
7

   class Car {
     @Inject Car(Provider<Seat> seatProvider) {
       Seat driver = seatProvider.get();
       Seat passenger = seatProvider.get();
       ...
     }
   }
1
2
3
4
5
6
7

   public class Car {
     @Inject @Named("driver") Seat driverSeat;
     @Inject @Named("passenger") Seat passengerSeat;
     ...
   }
1
2
3
4
5

  @Singleton
   class Log {
     void log(String message) { ... }
   }
1
2
3
4

   @java.lang.annotation.Documented
   @java.lang.annotation.Retention(RUNTIME)
   @javax.inject.Scope
   public @interface RequestScoped {}
1
2
3
4

<dependency>
  <groupId>jakarta.injectgroupId>
  <artifactId>jakarta.inject-apiartifactId>
  <version>2.0.1.MRversion>
dependency>
1
2
3
4
5

implementation 'jakarta.inject:jakarta.inject-api:2.0.1.MR'
1