4.9 基于注解的容器配置 · Java 開源項目中文文檔

## 4.9 基于注解的容器配置配置Spring時，注解要比XML更好嗎？基于注解配置的介紹就提出了這樣的問題，這種方法要比XML‘更好’嗎？簡短的回答就是具體問題具體分析。完整的答案就是每種方法都有它的利與弊，通常是讓開發人員來決定使用哪種策略更適合使用。由于定義它們的方式，注解在它們的聲明中提供了大量的上下文，使得配置更加簡短和簡潔。然而，XML更擅長裝配組件，而不需要觸碰它們源代碼或重新編譯。一些開發人員更喜歡裝配源碼而其他人認為被注解的類不再是POJO了，此外，配置變得分散并且難以控制。無論怎么去線則，Spring都可以容納兩種方式，甚至是它們的混合體。最值得指出的是通過JavaConfig（4.12節）選擇，Spring允許以非侵入式的方式來使用注解，而不需要觸碰目標組件的源代碼和工具，所有的配置方式都是[SpringSource Tool Suite](http://www.springsource.com/products/sts)所支持的。作為 XML 配置的另外一種選擇，依靠字節碼元數據的基于注解的配置來裝配組件代替了尖括號式的聲明。作為使用 XML 來表述 bean 裝配的替換，開發人員可以將配置信息移入到組件類本身中，在相關的類，方法或字段聲明上使用注解。正如在 4.8.1.2 節，“示例： RequiredAnnotationBeanPostProcessor”所提到的，使用 BeanPostProcessor 來連接注解是擴展 Spring IoC 容器的一種常用方式。比如，Spring 2.0 引入的使用@Required（4.9.1 節）注解來強制所需屬性的可能性。在 Spring 2.5 中，可以使用相同的處理方法來驅動 Spring 的依賴注入。從本質上來說，@Autowired 注解提供了在 4.4.5 節，“自動裝配協作者”中描述的相同能力，但卻有更細粒度的控制和更廣泛的適用性。Spring 2.5 也添加了對 JSR-250 注解的支持，比如@Resource，@PostConstruct 和@PreDestroy。Spring 3.0 添加了對 JSR-330（對 Java 的依賴注入）注解的支持，包含在 javax.inject 包下，比如@Inject，@Qualifier，@Named 和@Provider，當 JSR330 的 jar 包在類路徑下時就可以使用。使用這些注解也需要在 Spring 容器中注冊特定的 BeanPostProcessor。 > ![](img/note.gif) > 注意 > 注解注入會在 XML 注入之前執行，因此通過兩種方式，那么后面的配置會覆蓋前面裝配的屬性。一如往常，你可以注冊它們作為獨立的 bean，但是它們也可以通過包含下面的基于 XML的 Spring 配置代碼片段被隱式地注冊（注意要包含 context 命名空間）： ``` <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/bean[s http://www.springframework.org/schema/beans/spring -beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> <context:annotation-config/> </beans> ``` （隱式注冊的后處理器包含 AutowiredAnnotationBeanPostProcessor ， CommonAnnotationBeanPostProcessor ， PersistenceAnnotationBeanPostProcessor ，以及上述的 RequiredAnnotationBeanPostProcessor） > ![](img/note.gif) > 注意 > `<context:annotation-config/>`僅僅查找定義在同一上下文中的 bean 的注解。這就意味著，如果你為 DispatcherServlet 將`<context:annotation-config/>`放置在 WebApplicationContext 中，那么它僅僅檢查控制器中的@Autowired bean，而不是你的服務層 bean，可以參看 16.2 節，“DispatcherServlet”來查看更多信息。 ### 4.9.1 @Required @Required 注解應用于 bean 屬性的 setter 方法，就向下面這個示例： ``` public class SimpleMovieLister { private MovieFinder movieFinder; @Required public void setMovieFinder(MovieFinder movieFinder) { this.movieFinder = movieFinder; } // ... } ``` 這個注解只是表明受影響的 bean 的屬性必須在 bean 的定義中或者是自動裝配中通過明確的屬性值在配置時來填充。如果受影響的 bean 屬性沒有被填充，那么容器就會拋出異常；這就允許了急切而且明確的失敗，要避免 NullPointerException。我們推薦你放置斷言到 bean 的類中，比如，放置到初始化方法中。當你在容器外部使用類時，這么來做是強制那些所需的引用和值。 ### 4.9.2 @Autowired 和@Inject 正如預期的那樣，你可以使用@Autowired 注解到“傳統的”setter 方法中：注意在下面的示例中，JSR330 的@Inject 注解可以用于代替 Spring 的@Autowired。沒有必須的屬性，不像 Spring 的@Autowired 注解那樣，如果要注入的值是可選的話，要有一個 required 屬性來表示。如果你將 JSR330 的 JAR 包放置到類路徑下的話，這種行為就會自動開啟。 ``` public class SimpleMovieLister { private MovieFinder movieFinder; @Autowired public void setMovieFinder(MovieFinder movieFinder) { this.movieFinder = movieFinder; } // ... } ``` 你也可以將注解應用于任意名稱和/或多個參數的方法： ``` public class MovieRecommender { private MovieCatalog movieCatalog; private CustomerPreferenceDao customerPreferenceDao; @Autowired public void prepare(MovieCatalog movieCatalog, CustomerPreferenceDao customerPreferenceDao) { this.movieCatalog = movieCatalog; this.customerPreferenceDao = customerPreferenceDao; } // ... } ``` 你也可以將用于構造方法和字段： ``` public class MovieRecommender { @Autowired private MovieCatalog movieCatalog; private CustomerPreferenceDao customerPreferenceDao; @Autowired public MovieRecommender(CustomerPreferenceDao customerPreferenceDao) { this.customerPreferenceDao = customerPreferenceDao; } // ... } ``` 也可以提供 ApplicationContext 中特定類型的所有 bean，通過添加注解到期望哪種類型的數組的字段或者方法上： ``` public class MovieRecommender { @Autowired private MovieCatalog[] movieCatalogs; // ... } ``` 相同地，也可以用于特定類型的集合： ``` public class MovieRecommender { private Set<MovieCatalog> movieCatalogs; @Autowired public void setMovieCatalogs(Set<MovieCatalog> movieCatalogs) { this.movieCatalogs = movieCatalogs; } // ... } ``` 甚至特定類型的 Map 也可以自動裝配，但是期望的鍵的類型是 String 的。Map 值會包含所有期望類型的 bean，而鍵會包含對應 bean 的名字： ``` public class MovieRecommender { private Map<String, MovieCatalog> movieCatalogs; @Autowired public void setMovieCatalogs(Map<String, MovieCatalog> movieCatalogs) { this.movieCatalogs = movieCatalogs; } // ... } ``` 默認情況下，當出現零個候選 bean 的時候，自動裝配就會失敗；默認的行為是將被注解的方法，構造方法和字段作為需要的依賴關系。這種行為也可以通過下面這樣的做法來改變。 ``` public class SimpleMovieLister { private MovieFinder movieFinder; @Autowired(required=false) public void setMovieFinder(MovieFinder movieFinder) { this.movieFinder = movieFinder; } // ... } ``` > ![](img/note.gif) > 注意 > 每一個類中僅有一個被注解方法可以標記為必須的，但是多個非必須的構造方法可以被注解。在那種情況下，每個構造方法都要考慮到而且 Spring 使用依賴可以被滿足的那個構造方法，那就是參數最多的那個構造方法。 @Autowired 需要的屬性推薦使用@Required 注解。所需的表示了屬性對于自動裝配目的不是必須的，如果它不能被自動裝配，那么屬性就會忽略了。另一方面， @Required 更健壯一些，它強制了由容器支持的各種方式的屬性設置。如果沒有注入任何值，就會拋出對應的異常。你也可以針對我們熟知的解決依賴關系的接口來使用@Autowired：BeanFactory，ApplicationContext ， Environment ， ResourceLoader ，ApplicationEventPublisher 和 MessageSource。這些接口和它們的擴展接口，比如 ConfigurableApplicationContext 或 ResourcePatternResolver 也會被自動解析，而不需要特殊設置的必要。 ``` public class MovieRecommender { @Autowired private ApplicationContext context; public MovieRecommender() { } // ... } ``` > ![](img/note.gif) > 注意 > @Autowired ， @Inject ， @Resource 和 @Value 注解是由 Spring 的 BeanPostProcessor 實現類來控制的，反過來告訴你你不能在 BeanPostProcessor 或 BeanFactoryPostProcessor 類型（任意之一）應用這些注解。這些類型必須明確地通過 XML 或使用 Spring 的@Bean 方法來‘裝配’。 ### 4.9.3 使用限定符來微調基于注解的自動裝配因為通過類型的自動裝配可能導致多個候選者，那么在選擇過程中通常是需要更多的控制的。達成這個目的的一種做法就是 Spring 的@Qualifier 注解。你可以用特定的參數來關聯限定符的值，縮小類型的集合匹配，那么特定的 bean 就為每一個參數來選擇。最簡單的情形，這可以是普通描述性的值： > ![](img/note.gif) > 注意 > JSR 330 的@Qualifier 注解僅僅能作為元注解來用，而不像 Spring 的@Qualifier 可以使用字符串屬性來在多個注入的候選者之間區別，并可以放在注解，類型，字段，方法，構造方法和參數中。 ``` public class MovieRecommender { @Autowired @Qualifier("main") private MovieCatalog movieCatalog; // ... } ``` @Qualifier 注解也可以在獨立構造方法參數或方法參數中來指定： ``` public class MovieRecommender { private MovieCatalog movieCatalog; private CustomerPreferenceDao customerPreferenceDao; @Autowired public void prepare(@Qualifier("main") MovieCatalog movieCatalog,CustomerPreferenceDao customerPreferenceDao) { this.movieCatalog = movieCatalog; this.customerPreferenceDao = customerPreferenceDao; } // ... } ``` 對應的 bean 的定義可以按如下所示。限定符值是“main”的 bean 會用限定了相同值的構造方法參數來裝配。 ``` <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring -beans-3.0.xsd http://www.springframework.org/schema/contex)t http://www.springframework.org/schema/context/spring-context-3.0.xsd"> <context:annotation-config/> <bean class="example.SimpleMovieCatalog"> <qualifier value="main"/>  </bean> <bean class="example.SimpleMovieCatalog"> <qualifier value="action"/>  </bean> <bean id="movieRecommender" class="example.MovieRecommender"/> </beans> ``` 對于后備匹配，bean 名稱被認為是默認的限定符值。因此你可以使用 id 為“main”來定義 bean，來替代嵌套的限定符元素，這也會達到相同的匹配結果。然而，盡管你使用這種規約來通過名稱參照特定的 bean，@Autowired 從根本上來說就是關于類型驅動注入和可選語義限定符的。這就是說限定符的值，即便有 bean 的名稱作為后備，通常在類型匹配時也會縮小語義；它們不會在語義上表達對唯一 bean 的 id 的引用。好的限定符的值是“main” 或“EMEA”或“persistent”，特定組件的表達特性是和 bean 的 id 獨立的，在比如前面示例之一的匿名 bean 的情況下它是可能自動被創建的。限定符也可以用于類型集合，正如上面討論過的，比如 `Set<MovieCatalog>`。在這種情況下，根據聲明的限定符，所有匹配的 bean 都會被注入到集合中。這就說明了限定符不必是唯一的；它們只是構成了篩選條件。比如，你可以使用相同的限定符“action”來定義多個 MovieCatalog bean；它們全部都會通過@Qualifier("action")注解注入到 `Set<MovieCatalog>`中。 > ![](img/tip.gif) > 提示 > 如果你想通過名稱來表達注解驅動注入，主要是不使用@Autowired，即便在技術上來說能夠通過@Qualifier 值指向一個 bean 的名稱。相反，使用 JSR-250 的 @Resource 注解，在語義上定義了通過它的唯一名稱去確定一個具體的目標組件，聲明的類型和匹配過程無關。由于這種語義區別的特定后果，bean 本身被定義為集合或 map 類型，是不能通過 @Autowired 來進行注入的，因為類型匹配用于它們不太合適。對于這樣的 bean 使用 @Resource，通過唯一的名稱指向特定的集合或 map 類型的 bean。 @Autowired 可以用于字段，構造方法和多參數方法，在參數級允許通過限定符注解縮小。相比之下，@Resource 僅支持字段和僅有一個參數的 bea n 屬性的 setter 方法。因此，如果你的注入目標是構造方法或多參數的方法，那么就堅持使用限定符。你可以創建你自定義的限定符注解。只需定義一個注解并在你的定義中提供 @Qualifier 注解即可。注意你可以以下面描述的方式來使用 JSR 330 的@Qualifier 注解，用于替換 Spring 的 @Qualifier 注解。如果在類路徑中有 JSR 330 的 jar 包，那么這種行為是自動開啟的。 ``` @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Qualifier public @interface Genre { String value(); } ``` 之后你可以在自動裝配的字段和參數上提供自定義的限定符： ``` public class MovieRecommender { @Autowired @Genre("Action") private MovieCatalog actionCatalog; private MovieCatalog comedyCatalog; @Autowired public void setComedyCatalog(@Genre("Comedy") MovieCatalog comedyCatalog) { this.comedyCatalog = comedyCatalog; } // ... } ``` 之后，為候選 bean 提供信息，你可以添加`<qualifier/>`標簽來作為`<bean/>`標簽的子元素，然后指定 type 和 value 值來匹配你自定義的限定符注解。這種類型匹配是基于注解類的完全限定名。否則，作為一種簡便的形式，如果沒有名稱沖突存在的風險，你可以使用短類名。這兩種方法都會在下面的示例中來展示。 ``` <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring -beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> <context:annotation-config/> <bean class="example.SimpleMovieCatalog"> <qualifier type="Genre" value="Action"/> <!— 注入這個bean所需要的任何依賴 --> </bean> <bean class="example.SimpleMovieCatalog"> <qualifier type="example.Genre" value="Comedy"/> <!— 注入這個bean所需要的任何依賴 --> </bean> <bean id="movieRecommender" class="example.MovieRecommender"/> </beans> ``` 在 4.10 節，“類路徑掃描和管理的組件”中，你會看到基于注解的替代，在 XML 中來提供限定符元數據。特別是在 4.10.7 節，“使用注解提供限定符元數據”中。在一些示例中，使用無值的注解就足夠了。這當注解服務于多個通用目的時是很有用的，而且也可以用于集中不同類型的依賴關系。比如，當沒有因特網連接時，你可以提供脫機目錄來由于搜索。首先定義簡單的注解： ``` @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Qualifier public @interface Offline { } ``` 之后將注解添加到要被自動裝配的字段或屬性上： ``` public class MovieRecommender { @Autowired @Offline private MovieCatalog offlineCatalog; // ... } ``` 現在來定義 bean 的限定符的 type： ``` <bean class="example.SimpleMovieCatalog"> <qualifier type="Offline"/> <!— 注入這個bean所需要的任何依賴 --> </bean> ``` 你也可以定義自定義的限定符注解來接受命名屬性，除了或替代簡單的 value 屬性。如果多個屬性值之后在要不自動裝配的字段或參數上來指定，那么要考慮 bean 的定義必須匹配自動裝備候選者的所有屬性值。示例，考慮下面的注解定義： ``` @Target({ElementType.FIELD, ElementType.PARAMETER}) @Retention(RetentionPolicy.RUNTIME) @Qualifier public @interface MovieQualifier { String genre(); Format format(); } ``` 在本例中，Format 是枚舉類型： ``` public enum Format { VHS, DVD, BLURAY } ``` 要自動裝配的字段使用自定義的限定符和包含 genre 和 format 兩個屬性的值來注解。 ``` public class MovieRecommender { @Autowired @MovieQualifier(format=Format.VHS, genre="Action") private MovieCatalog actionVhsCatalog; @Autowired @MovieQualifier(format=Format.VHS, genre="Comedy") private MovieCatalog comedyVhsCatalog; @Autowired @MovieQualifier(format=Format.DVD, genre="Action") private MovieCatalog actionDvdCatalog; @Autowired @MovieQualifier(format=Format.BLURAY, genre="Comedy") private MovieCatalog comedyBluRayCatalog; // ... } ``` 最后，bean 的定義應該包含匹配的限定符值。這個示例也展示了 bean 的元屬性可能用于替代`<qualifier/>`子元素。如果可用，`<qualifier/>`和它的屬性優先，但是如果目前沒有限定符，自動裝配機制就會在`<meta/>`標簽提供的值上失效，就像下面這個示例中的最后兩個 bean。 ``` <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema -instance" xmlns:context="http://www.springframework.org/schema/context" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring -beans-3.0.xsd http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> <context:annotation-config/> <bean class="example.SimpleMovieCatalog"> <qualifier type="MovieQualifier"> <attribute key="format" value="VHS"/> <attribute key="genre" value="Action"/> </qualifier> <!— 注入這個bean所需要的任何依賴 --> </bean> <bean class="example.SimpleMovieCatalog"> <qualifier type="MovieQualifier"> <attribute key="format" value="VHS"/> <attribute key="genre" value="Comedy"/> </qualifier> <!— 注入這個bean所需要的任何依賴 --> </bean> <bean class="example.SimpleMovieCatalog"> <meta key="format" value="DVD"/> <meta key="genre" value="Action"/> <!— 注入這個bean所需要的任何依賴 --> </bean> <bean class="example.SimpleMovieCatalog"> <meta key="format" value="BLURAY"/> <meta key="genre" value="Comedy"/> <!— 注入這個bean所需要的任何依賴 --> </bean> </beans> ``` ### 4.9.4 CustomAutowireConfigurer [CustomAutowireConfigurer](http://static.springframework.org/spring/docs/3.0.x/javadoc-api/org/springframework/beans/factory/annotation/CustomAutowireConfigurer.html) 是 BeanFactoryPostProcessor 的一種，它使得你可以注冊你自己定義的限定符注解類型，即便它們沒有使用 Spring 的@Qualifier 注解也是可以的。 ``` <bean id="customAutowireConfigurer" class="org.springframework.beans.factory.annotation.CustomAu towireConfigurer"> <property name="customQualifierTypes"> <set> <value>example.CustomQualifier</value> </set> </property> </bean> ``` AutowireCandidateResolver 的特別實現類對基于 Java 版本的應用程序上下文激活。在 Java 5 之前的版本中，限定符注解是不支持的，因此自動裝配候選者僅由每個 bean 定義中的 autowire-candidate 值來決定，還有在`<beans/>`元素中的任何可用的 default-autowire-candidates 模式也是可以的。在 Java 5 之后的版本中， @Qualifier 注解的存在還有任意使用 CustomAutowireConfigurer 注冊的自定義注解也將發揮作用。不管 Java 的版本，當多個 bean 作為自動裝配的候選者，決定“主要”候選者的方式也是相同的：如果候選者中一個 bean 的定義有 primary 屬性精確地設置為 true，那么它就會被選擇。 ### 4.9.5 @Resource Spring 也支持使用 JSR 250 的@Resource 注解在字段或 bean 屬性的 setter 方法上的注入。這在 Java EE 5 和 6 中是一個通用的模式，比如在 JSF 1.2 中管理的 bean 或 JAX-WS 2.0 端點。Spring 也為其所管理的對象支持這種模式。 @Resource 使用名稱屬性，默認情況下 Spring 解釋這個值作為要注入的 bean 的名稱。換句話說，如果遵循 by-name 語義，正如在這個示例所展示的： ``` public class SimpleMovieLister { private MovieFinder movieFinder; @Resource(name="myMovieFinder") public void setMovieFinder(MovieFinder movieFinder) { this.movieFinder = movieFinder; } } ``` 如果沒有明確地指定名稱，那么默認的名稱就從字段名稱或 setter 方法中派生出來。以字段為例，它會選用字段名稱；以 setter 方法為例，它會選用 bean 的屬性名稱。所以下面的示例中有名為“movieFinder”的 bean 通過 setter 方法來注入： ``` public class SimpleMovieLister { private MovieFinder movieFinder; @Resource public void setMovieFinder(MovieFinder movieFinder) { this.movieFinder = movieFinder; } } ``` > ![](img/note.gif) > 注意 > 使用注解提供的名稱被感知 CommonAnnotationBeanPostProcessor 的 ApplicationContext 解析成 bean 的名稱。名稱可以通過 JNDI 方式來解析，只要你明確地配置了 Spring 的 [SimpleJndiBeanFactory](http://static.springframework.org/spring/docs/3.0.x/javadoc-api/org/springframework/jndi/support/SimpleJndiBeanFactory.html)。然而，還是推薦你基于默認行為并僅使用 Spring 的 JNDI 查找能力來保存間接的水平。在使用@Resource 并沒有明確指定名稱的獨占情況下，和 @Autowired 相似， @Resource 發現主要類型匹配，而不是特定名稱 bean 并解析了熟知的可解析的依賴關系： BeanFactory ， ApplicationContext ， ResourceLoader ， ApplicationEventPublisher，MessageSource 和接口。因此，在下面的示例中， customerPreferenceDao 字段首先尋找名為 customerPreferenceDao 的 bean，之后回到匹配 CustomerPreferenceDao 的主類型。 “context”字段基于已知的可解析的依賴類型 ApplicationContext 注入。 ``` public class MovieRecommender { @Resource private CustomerPreferenceDao customerPreferenceDao; @Resource private ApplicationContext context; public MovieRecommender() { } // ... } ``` ### 4.9.6 @PostConstruct 和@PreDestroy CommonAnnotationBeanPostProcessor 不但能識別@Resource 注解，而且還能識別 JSR-250 生命周期注解。在 Spring 2.5 中引入，對這些注解的支持提供了在初始化回調（ 4.6.1.1 節）和銷毀回調（ 4.6.1.2 節）中的另一種選擇。只要 CommonAnnotationBeanPostProcessor 在 Spring 的 ApplicationContext 中注冊，一個攜帶這些注解之一的方法就同時被調用了，和 Spring 生命周期接口方法或明確地聲明回調方法相對應。在下面的示例中，在初始化后緩存會預先填充，在銷毀后會清理。 ``` public class CachingMovieLister { @PostConstruct public void populateMovieCache() { // 在初始化時填充movie cache... } @PreDestroy public void clearMovieCache() { // 在銷毀后清理movie cache... } } ``` > ![](img/note.gif) > 注意 > 關于組合多個生命周期機制影響的細節內容，請參考 4.6.1.4 節，“組合生命周期機制”。