聊聊 Spring 的那些註解

收藏待读

聊聊 Spring 的那些註解

本文我們來梳理一下Spring的那些註解,如下圖所示,大概從幾方面列出了Spring的一些註解:

聊聊 Spring 的那些註解

如果此圖看不清楚也沒事,請運行下面的代碼輸出所有的結果。

Spring目前的趨勢是使用註解結合Java代碼而不是配置來定義行為、屬性、功能、規則和擴展點,因此梳理註解也是梳理Spring功能點的很好的方式,全面的梳理可以補足我們知識點的漏洞。

查找所有註解

首先,我們來創建一個項目,使用 SPRING INITIALIZR 生成一個引入Spring各種組件的項目模板,然後引入如下工具包:

<dependency>
<
groupId>org.reflections</groupId>
<
artifactId>reflections</artifactId>
<
version>0.9.11</version>
</
dependency>

通過這個反射工具包,我們可以創建一個Spring Boot應用程序,以一行代碼打印出所有Spring框架的註解:

import org.reflections.Reflections;
import org.springframework.boot.CommandLineRunner;
import org.springframework.stereotype.Component;

import java.lang.annotation.Annotation;

@Component
public class ScanAnnotationRunner implements CommandLineRunner {
@Override
public void run(String... args) throws Exception {
new Reflections("org.springframework")
.getSubTypesOf(Annotation.
class)
.stream()
.map(clazz->clazz.getName())
.sorted()
.forEach(System.
out::println);
}
}

輸出結果這裡就不給出了,下面我們逐一進行梳理其中的一些重要註解。

有關註解

Java的Annotation註解(類似於C#的Attribute特性),說白了就是給代碼打上標籤的能力。我們可以配置這個標籤的保留階段,僅源代碼,源代碼+位元組碼,源代碼+位元組碼+運行時。通過引入註解,我們可以簡單快速賦予代碼生命力,大大提高代碼可讀性和擴展性。註解本身不具有任何能力,只是一個標籤,但是我們可以定義各種標籤然後實現各種標籤處理器來對類、方法、屬性甚至參數等進行功能擴展、功能開啟、屬性定義、行為定義、規則定義、關聯處理、元數據定義等等。在實現各種框架的時候,我們經常會自定義標籤方便框架使用者僅僅通過在合適的地方引入合適的註解來啟用(或自定義)框架的一些能力並應用到我們的程序中。

不僅僅是框架的作者會大量使用註解,在之前的系列文章中我們也多次自定義註解,我們有通過定義@Metrics註解配合Spring AOP來為程序啟動打點、日誌、異常等功能,我們有通過定義@Sign註解配合Spring MVC的ResponseBodyAdvice進行數據簽名功能,我們還經常會定義各種自定義註解配合Spring MVC的HandlerMethodArgumentResolver進行權限的校驗等等功能。採用這種模式,我們的核心業務邏輯可以保持清晰乾淨,通過註解配合AOP賦予代碼額外的能力。

你可能會說,註解還是有侵入性,我們需要耦合框架定義的那些註解,這個問題其實是無解的,100%無侵入性也代表了可讀性的降低,代碼的功能和能力應當聚合在一起,這也就是為什麼Spring現在也不建議採用XML來做配置。Java核心類庫並沒有什麼註解,好在Spring已經有了大量註解,而Spring也變為了Java開發的標準,所以其實我們很多時候如果希望自己的框架(RPC啥的)完全沒有侵入性的話可以借用Spring的那些註解@Autowired、@Controller、@Service等註解,配合各種包的規範其實我們可以對目標元素的功能識別個八九不離十,完全有可能實現0侵入的功能增強。

有關如何實現自定義註解不贅述,這裡我們簡單回顧一下幾個元註解(註解的註解):

– @Documented:將會在被此註解註解的元素的javadoc文檔中列出註解,一般都打上這個註解沒壞處

– @Target:註解能被應用的目標元素,比如類、方法、屬性、參數等等,需要仔細思考

– @Retention:僅在源碼保留,還是保留到編譯後的位元組碼,還是到運行時也去加載,超過90%的應用會在運行時去解析註解進行額外的處理,所以大部分情況我們都會設置配置為RetentionPolicy.RUNTIME

[email protected]:如果子類沒有定義註解的話,能自動從父類獲取定義了繼承屬性的註解,比如Spring的@Service是沒有繼承特性的,但是@Transactional是有繼承特性的,在OO繼承體系中使用Spring註解的時候請特別注意這點,理所當然認為註解是能被子類繼承的話可能會引起不必要的Bug,需要仔細斟酌是否開啟繼承

– @Repeatable:Java 8引入的特性,通過關聯註解容器定義可重複註解,小小語法糖提高了代碼可讀性,對於元素有多個重複註解其實是很常見的事情,比如某方法可以是A角色可以訪問也可以是B角色可以訪問,某方法需要定時任務執行,要在A條件執行也需要在B條件執行

– @Native:是否在.h頭文件中生成被標記的字段,除非原生程序需要和Java程序交互,否則很少會用到這個元註解

現在我們來從幾個方面逐一溫習一下Spring的那些常用的值得關注的註解。

Spring核心註解

– 首先來看一下各種stereotype:按分類定義了由Spring管理的各種組件, @Controller 定義表現層組件, @Service 定義業務邏輯層組件, @Repository 定義數據訪問層資源庫組件, @Component 定義其它組件(比如訪問外部服務的組件),之前也說過了隨着這些註解功能無區別,但是對組件進行合適的分類意義重大,不僅僅增加可讀性而且方便我們通過AOP對不同類型的組件進行更多自動增強

– 再來看看IOC相關的一些註解: @Autowired 自動裝配不用多說了; @Required 用於在setter方法標記屬性值需要由Spring進行裝配,對於目前版本的Spring這個註解已經廢棄,現在Spring更推薦使用構造方法注入; @Qualifier 用於通過給Bean定義修飾語來注入相應的Bean,和@Autowired一起使用相當於@Resource的效果,當然還有一種常見用法是嵌入其它註解用於對Bean進行區分,然後配合@Autowired一起使用,參見後面提到的Spring Cloud的@LoadBalanced註解; @Value 用於注入屬性配置或SpEL表達式(前者是我們常見用法,後者可以從其它對象獲取值,功能更強大一點); @Lookup 可以實現方法注入,如果我們的類是單例的,但是又希望Spring注入的依賴的對象是Prototype生命周期(每次new一個出來)的,這個時候可以通過此註解進行方法注入

– 然後來看一下有關事務的幾個註解: @EnableTransactionManagement 用於開啟事務管理,使用Spring Boot如果引入Spring Data的話不需要手動開啟(不過建議大家在使用事務的時候還是通過日誌來驗證事務管理是否生效); @Transactional 大家都知道用於開啟事務以及設置傳播性、隔離性、回滾條件等; @TransactionalEventListener 用於配置事務的回調方法,可以在事務提交前、提交後、完成後以及回滾後幾個階段接受回調事件

@Order 註解可以設置Spring管理對象的加載順序,在之前介紹AOP的文章中我們看到有的時候我們必須通過設置合理的@Order來合理安排切面的切入順序避免一些問題,還有在一些業務場景中,我們往往會去定義一組類似於Filter的@Component,然後會從容器獲得一組Bean,這個時候業務組件的運行順序往往會比較重要,也可以通過這個方式進行排序

@AliasFor 註解可以設置一組註解屬性相互作為別名,對於有歧義的時候會使代碼更清晰,此外還有一個用途是創建複合註解,Spring MVC的@GetMapping註解就是基於@RequestMapping這個註解創建的複合註解,我們可以很方便得通過這種方式來實現註解的繼承

Spring上下文註解

– 首先來看一下配置相關的一些註解: @Configuration 用於標註配置類,啟用Java配置方式的Bean配置; @Bean 用於配置一個Bean; @ComponentScan (@ComponentScans用於配置一組@ComponentScan,Java8可以直接使用重複註解特性配置多個@ComponentScan)用於掃描包方式配置Bean; @PropertySource 以及 @PropertySources 用於導入配置文件; @Conditional 用於設置關聯的條件類,在合適的時候啟用Bean的配置(Spring Boot自動配置根基); @Import 用於導入其它配置類; @ImportResource 用於導入非Java配置方式的XML配置; @Profile 用於指定在合適的Profile下啟用配置; @Lazy 用於告知容器延遲到使用的時候實例化Bean(默認情況下容器啟動的時候實例化Bean來檢查所有的問題); @Description 用於給Bean設置描述; @Scope 用於設置Bean的生命周期; @Primary 用於在定義了多個Bean的時候指定首選的Bean

– 其它一些註解包括: @EventListener 用於設置回調方法監聽Spring制定的以及自定義的各種事件; @EnableAspectJAutoProxy 用於開啟支持AspectJ的@Aspect切面配置支持,使用Spring Boot引入了AOP啟動器的話不需要顯式開啟

Spring Web註解

Spring MVC的各種註解對應了SpringMVC各方面的功能,下面我們來了解一下:

– 首先是三個定義了Bean特殊生命周期的複合註解: @RequestScope@SessionScope@ApplicationScope 。在Web應用中,我們可能需要Bean跟隨請求、會話和應用程序的聲明周期來進行創建,這個時候可以直接使用這三個快捷的複合註解

– 接下去可以看到各種@XXXMapping的註解,分別用於配置HandlerMethod匹配到不同的Http Method,當然不使用這些快捷的註解也是可以的,直接使用 @RequestMapping 然後手動設置method

@ResponseStatus 可以用到方法上也可以用到異常上,前者會直接使請求得到指定的響應代碼或原因(可以配合 @ExceptionHandler 使用),後者可以實現遇到指定異常的時候給出指定的響應代碼或原因, @ResponseBody 我們實現Restful接口的時候(@RestController)最常用了,把返回內容(序列化後)輸出到請求體

– Spring MVC給了我們各種註解方便我們從HTTP請求各種地方獲取參數, @RequestBody 從請求體(處理複雜數據,比如JSON), @RequestHeader 從請求頭, @CookieValue 從cookie中, @SessionAttribute 從會話中, @RequestAttribute 從請求的Attribute中(比如過濾器和攔截器手動設置的一些臨時數據), @RequestParam 從請求參數(處理簡單數據,鍵值對), @PathVariable 從路徑片段, @MatrixAttribute 矩陣變量允許我們採用特殊的規則在URL路徑後加參數(分號區分不同參數,逗號為參數增加多個值)

@ControllerAdvice 是一個重要註解,允許我們在集中的地方配置控制器(有@RequestMapping的方法)相關的增強( @RestControllerAdvice 也是差不多的,只是相當於為@ExceptionHandler加上了@ResponseBody)。那麼可以應用哪些增強呢?首先是可以用 @ExceptionHandler 進行統一的全局異常處理;第二是 @InitBinder 用來設置WebDataBinder,WebDataBinder用來自動綁定前台請求參數到Model中;第三是 @ModelAttribute 讓全局的@RequestMapping都能獲得在此處設置的鍵值對。當然,這裡說的@InitBinder和@ExceptionHandler也可以不定義在@ControllerAdvice內部(作為全局開啟),定義在Controller內部應用到某個Controller也是可以的

– 其它還有一些註解比如: @CrossOrigin 可以用到Controller或Method上(需要配合@RequestMapping)設置細粒度的跨域行為

在之前的文章中我們也提到,對於Spring MVC,定義自己的註解應用到參數、方法、控制器上,配合HandlerMethodArgumentResolver、XXAdvise、以及Interceptor實現具體的功能來使用太太常見了,幾乎所有的非業務橫切關注點,我們都不應該在方法實現中重複任何一行代碼。

Spring Boot註解

– 來看一下上下文相關的註解: @ConfigurationProperties 很常用(配合 @EnableConfigurationProperties 註解來設置需要啟用的配置類),用來自定義配置類和配置文件進行關聯; @DeprecatedConfigurationProperty 用於標記廢棄的配置以及設置替代配置和告知廢棄原因; @ConfigurationPropertiesBinding 用於指定自定義的轉換器用於配置解析的時的類型轉換; @NestedConfigurationProperty 用於關聯外部的類型作為嵌套配置類

– 再看看自動配置相關的註解,自動配置是Spring Boot最重要的特性,在之前的系列文章中我有提到一個觀點,IOC是好事情,但是把組件內部的一些默認配置以及組件和組件的組裝交給外部用戶來配置其實是不合理的,組件應當可以自動進行自我配置實現開箱急用,只有需要自定義組件的時候才要求外部來進行個性化配置: @EnableAutoConfiguration 註解可以啟用自動配置,Spring Boot應用程序一般我們會直接使用複合註解 @SpringBootApplication@AutoConfigureOrder (值越小優先級越高)、 @AutoConfigureAfter@AutoConfigureBefore 用於設置自動配置類加載順序,以及精確控制加載依賴關係,有的時候我們的自動配置需要相互依賴或者會相互干擾,需要手動調節

– 最後來看一下十幾種配置條件,用好這些註解是實現完善的自動配置的關鍵: @ConditionalOnBean 用於僅當容器中已經包含指定的Bean類型或名稱時才匹配條件; @ConditionalOnClass 僅當classpath上存在指定類時條件匹配; @ConditionalOnCloudPlatform 僅當指定的雲平台處於活動狀態時條件匹配; @ConditionalOnExpression 依賴於SpEL表達式的值的條件元素的配置註解; @ConditionalOnJava 基於應用運行的JVM版本的條件匹配; @ConditionalOnJndi 基於JNDI可用和可以查找指定位置的條件匹配; @ConditionalOnMissingBean 僅當容器中不包含指定的Bean類型或名稱時條件匹配; @ConditionalOnMissingClass 僅當classpath上不存在指定類時條件匹配; @ConditionalOnNotWebApplication 僅當不是WebApplicationContext(非Web項目)時條件匹配,對應@ConditionalOnWebApplication; @ConditionalOnProperty 是檢查指定的屬性是否具有指定的值; @ConditionalOnResource 表示僅當 classpath 上存在指定資源時條件匹配; @ConditionalOnSingleCandidate 僅當容器中包含指定的Bean類並且可以判斷只有單個候選者時條件匹配。其實所有這些實現原理都是擴展SpringBootCondition抽象類(實現之前提到的Condition接口),我們完全可以實現自己的條件註解(配合@Conditional註解關聯到自己實現的SpringBootCondition)

Spring Cloud註解

在介紹本系列文章的第一篇中我們就提到了,Spring Cloud整齊劃一通過各種EnableXXX註解開啟某個功能,這裡就不對這些註解進行說明了,使用Spring Boot組件的功能非常簡單,基本就是引POM+EnableXXX+設置配置文件三部曲。

– 首先是 Netflix包下的一些註解,各種EnableXXX就不說了,參考前一篇文章,之前沒介紹過 @RibbonClient ,這個註解用來為負載均衡客戶端做一些自定義的配置,可以進一步配置或自定義從哪裡獲取服務端列表、負載均衡策略、Ping也就是服務鑒活策略等等

– client包下的 @SpringCloudApplication 之前文章中我們也沒有使用到,這是一個複合註解就是@[email protected][email protected],Spring Cloud那堆東西很多,還是自己親手定義一個一個功能的註解來的踏實; @LoadBalanced 註解用於和RestTemplate配合使用構成一個負載均衡的Http客戶端,實現原理上其實這個註解是一個@Qualifier註解,Spring會為所有@LoadBalanced的RestTemplate加入一個LoadBalancerInterceptor(實現ClientHttpRequestInterceptor)實現負載均衡

– sleuth包下面的註解和鏈路跟蹤相關,比較常用的是通過 @SpanName 手動設置span的名稱,其它註解對於業務開發並不常用

總結

好了,寫了本文我發現我看到@就眼花。本文我們通過代碼打印出了大部分Spring相關的註解,你也可以通過這個方式熟悉其它框架的註解(畢竟註解是框架賦予我們各種便捷功能的一個重要入口,對註解了解個八九成也往往可以對框架賦予我們的豐富功能了解六七成)。然後我們梳理了一下Spring相關的各種註解,其中主要需要關注的是幾方面:

1、元註解,也就是註解的註解

2、Spring容器相關的一些註解,包括@Qualifier、@AliasFor、@Order等看似不重要但其實很重要的註解

3、Spring Java配置相關的一些註解,包括條件註解

4、Spring Boot自動配置相關的一些註解

5、很多註解可以同時應用到類型、方法、參數上,有的時候應用到不同的地方作用會略微不一樣,這個需要重點關注

我們知道註解其實只是一個標識,註解如何起作用背後的實現原理還是比較多樣的,你可以進一步結合本文介紹的Spring的各種註解探尋一下背後實現的原理。

原文 :

相關閱讀

免责声明:本文内容来源于mp.weixin.qq.com,已注明原文出处和链接,文章观点不代表立场,如若侵犯到您的权益,或涉不实谣言,敬请向我们提出检举。