注解式項目開發！詳細分析Java中各個注解的作用和使用方式

@Target

• 作用: 指明了修飾的這個注解的使用範圍, 即被描述的注解可以用在哪裡

@Target(ElementType.Type)           

• ElementType取值的類型:
  • TYPE: 類,接口或者枚舉
  • FIELD: 域,包含枚舉常量
  • METHOD: 方法
  • PARAMETER: 參數
  • CONSTRUCTOR: 構造方法
  • LOCAL_VARIABLE: 局部變量
  • ANNOTATION_TYPE: 注解類型
  • PACKAGE: 包

@Retention

• 作用: 指明修飾的注解的生存周期, 即會保留到哪個階段
• RetentionPolicy的取值類型有三種:
  • SOURCE: 源碼級别保留，編譯後即丢棄
  • CLASS: 編譯級别保留,編譯後的class檔案中存在,在jvm運作時丢棄,這是預設值
  • RUNTIME: 運作級别保留,編譯後的class檔案中存在,在jvm運作時保留,可以被反射調用

@Documented

• 作用: 指明修飾的注解,可以被例如javadoc此類的工具文檔化
  • 隻負責标記
  • 沒有成員取值

@Inherited

• 作用: 允許子類繼承父類中的注解
• @Inherited需要和@AliasFor一起使用: 在子注解對應的屬性使用@AliasFor
  • 注解是可以繼承的,但是注解是不能繼承父注解的屬性
  • 也就是說,在類掃描時的注解的屬性值依然是父注解的屬性值,而不是自定義注解的屬性值
  • 需要在注解的屬性上使用@AliasFor

@ComponentScan

• 作用: 定義掃描的路徑從中找出辨別了需要裝配的類自動裝配到spring的bean容器中
• 預設會掃描該類所在的包下所有的配置類
• @ComponentScan中的參數類型:
  • value: 用于對指定包的路徑進行掃描
  • basePackages: 用于指定包的路徑進行掃描,用法和value一樣.建議使用value
  • basePackageClasses: 用于對指定某個類的所在的包的路徑進行掃描
  • nameGenerator: 用于為Spring容器中的檢測到bean元件命名
  • useDefaultFilters: 是否開啟對 @Component,@Repository,@Service,@Controller的類進行檢測
  • excludeFilters: 按照過濾條件進行排除
    • FilterType.ANNOTATION: 按照注解
    • FilterType.ASSIGNABLE_TYPE: 按照給定的類型
    • FilterType.ASPECTJ: 使用ASPECTJ表達式
    • FilterType.REGEX: 使用正規表達式
    • FilterType.CUSTOM: 按照自定義規則
  • includeFilters: 按照過濾條件進行包含

@Filter

• 作用: 配置過濾條件的過濾器注解
• @Filter中的參數類型:
  • type
  • class

@interface

• 作用: 自定義注解
• 自動繼承java.lang.annotation.Annotation接口,由編譯程式自動完成其他細節
• 在定義注解時,不能繼承其他的注解或接口
• @interface用來聲明一個注解:
  • 其中的每一個方法實際上是聲明一個配置參數
  • 方法的名稱就是參數的名稱
  • 方法的傳回值類型就是參數的類型
  • 傳回值類型隻能是基本類型,Class,String,enum
  • 可以通過default來聲明參數的預設值
• 定義注解的格式:

public @interface 注解名 {定義體}           

• 注解參數支援的資料類型:
  • 基本資料類型: int,float,boolean,byte,double,char,long,short
  • String類型
  • Class類型
  • enum類型
  • Annotation類型
  • 以上類型組合的數組
• Annotation類型中參數設定規則:
  • 隻能用public或default預設通路權修飾:
  • 參數成員隻能用基本類型byte,short,char,int,long,float,double,boolean八種基本資料類型和String,Enum,Class,annotations等資料類型,以及這一些類型的數組
  • 如果隻有一個參數成員,最好把參數名稱設為value,後加小括号
• 注解元素的預設值:
  • 注解元素必須有确定的值
  • 要麼在定義注解的預設值中指定,要麼在使用注解時指定,非基本類型的注解元素的值不可為null
  • 是以使用空字元串或0作為預設值限制
• 這個限制使得處理器很難表現一個元素的存在或缺失的狀态:
  • 因為每個注解的聲明中,所有元素都存在,并且都具有相應的值
• 為了繞開這個限制,隻能定義一些特殊的值(比如空字元串或者負數),表示某個元素不存在

@AliasFor

• 作用: 為注解的屬性添加别名
• 在同一個注解内,對兩個不同的屬性一起使用,互為别名:
  • 無論為哪個屬性名設定屬性值,另一個屬性名也是同樣的屬性值
  • 互為别名的屬性值必須相同,否則會報錯
  • 屬性必須要有預設的屬性值

public @interface RequestMapping {
   
    @AliasFor("path")             // 此時path和value值必須是一樣的,否則會報錯
    String[] value() default {};

    @AliasFor("value")             // 此時path和value值必須是一樣的,否則會報錯
    String[] path() default {};
    
}           

• 顯式的覆寫元注解中的屬性:
  • 顯式的為元注解的屬性設定别名
  • 屬性類型,屬性預設值必須相同
  • @AliasFor隻能為作為目前注解的元注解起别名
• 示例:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = AopConfig.class)
public class AopUtilsTest {}           

要想替換 @ContextConfiguration(classes = AopConfig.class) 注解,可以這樣定義一個标簽:

@Retention(RetentionPolicy.RUNTIME)
@ContextConfiguration
public @interface Context {
    @AliasFor(value = "classes", annotation = ContextConfiguration.class)
    Class<?>[] cs() default {};
}           

1. 因為 @ContextConfiguration注解本身被定義為 @Inherited的,是以Context注解即可了解為繼承 @ContextConfiguration注解
2. cs屬性等同于 @ContextConfiguration屬性中的classes屬性.使用了 @AliasFor标簽,分别設定:
   1. value: 作為哪個屬性的别名
   2. annotation: 作為哪個注解的别名

使用Context标簽的可以達到同樣效果:

@RunWith(SpringJUnit4ClassRunner.class)
@STC(cs = AopConfig.class)
public class AopUtilsTest {}           

• 在一個注解中隐式聲明别名:

@ContextConfiguration
 public @interface MyTestConfig {

    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
    String[] value() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
    String[] groovyScripts() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
    String[] xmlFiles() default {};
 }           

這就是在統一注解中隐式聲明别名:

1. 在MyTestConfig注解中 ,value,groovyScripts,xmlFiles都定義為@AliasFor(annotation = ContextConfiguration.class, attribute = "locations")的别名
2. 在這個注解中 ,value,groovyScripts和xmlFiles也互為别名

• 别名的傳遞:
  • @AliasFor注解是允許别名之間的傳遞的:
    • 如果A是B的别名,并且B是C的别名,那麼A是C的别名

@MyTestConfig
 public @interface GroovyOrXmlTestConfig {

    @AliasFor(annotation = MyTestConfig.class, attribute = "groovyScripts")
    String[] groovy() default {};

    @AliasFor(annotation = ContextConfiguration.class, attribute = "locations")
    String[] xml() default {};
 }           

1. GroovyOrXmlTestConfig把 @MyTestConfig作為元注解
2. 定義了groovy屬性,并作為MyTestConfig中的groovyScripts屬性的别名
3. 定義了xml屬性,并作為ContextConfiguration中的locations屬性的别名
4. 因為MyTestConfig中的groovyScripts屬性本身就是ContextConfiguration中的locations屬性的别名,是以xml屬性和groovy屬性也互為别名

• @Alias中的屬性:
  • annotation: 類類型,别名屬性的類的類型,即别名的屬性屬于哪個注解類
  • attribute: 需要别名的屬性
  • value: 屬性的别名

@Import

• @Import支援導入普通的Java類,并聲明為一個Bean
• @Import使用場景:
  • @Import主要用在基于Java代碼顯式建立bean的過程中
  • @Import用于将多個分散的Java Config配置類融合成一個完整的config類
• 配置類的組合主要發生在跨子產品或者跨包的配置類引用過程中: 将多個按功能或者按業務劃分的配置檔案導入到單個配置檔案中,避免将所有配置寫在一個配置中
• @Import與@ImportResource注解的作用類似
• 使用@ImportResource和@Value可以進行資源檔案的讀取

SpringBoot

@SpringBootApplication

• 包含:
  • @Configuration
  • @EnableAutoConfiguration
• 通常用在主類上

@ConfigurationProperties

• 可以使用 @ConfigurationProperties擷取大量配置在application.properties和application.yml中參數的參數值
• @ConfigurationProperties的使用: 要為每個捕獲的外部屬性提供一個帶有字段的類
  • 字首prefix定義的相關的外部屬性要綁定到類的字段上
  • 根據SpringBoot寬松的綁定規則,類屬性的名稱必須與外部屬性名稱比對
    • 可以将類類型的bean使用@Bean注解的方法注入到另一個bean中,那麼這個bean可以以類型安全的方式通路外部配置的參數值
  • 可以簡單地用一個值初始化一個字段來定義一個預設值. 最好與配置檔案中的值相同
  • 類本身可以是包私有的
  • 類的字段必須有公共setter方法
• 激活@ConfigurationProperties:
• • 通過添加 @Component注解讓ComponentScan掃描到
  • 隻有當該類所在的包被Spring的@ComponentScan掃描到才會生效.預設情況下,該注解會掃描在主應用類下所有包結構

  @Component
  @ConfigurationProperties(prefix = "spring.logger")
  class LogProperties {
      ...
  }           

  • 通過Spring的Java Configuration特性激活@ConfigurationProperties
  • 隻要MailModuleConfiguration類被SpringBoot應用掃描到,就可以在應用上下文中通路MailModuleProperties bean

  @Configuration
  class PropertiesConfig {
      @Bean 
      public LogModuleProperties logModuleProperties() {
          return new logModuleProperties();
      }
  }           

  • 同時可以使用 @EnableConfigurationProperties注解使得SpringBoot找到這個類. 這個注解用了 @Import(EnableConfigurationPropertiesImportSelector.class) 實作

@Configuration
@EnableConfigurationProperties(LogModuleProperties.class)
class PropertiesConfig {
}           

激活一個 @ConfigurationProperties類時最好子產品化應用程式,并讓每個子產品提供自己的 @ConfigurationProperties類,隻提供子產品需要的屬性.這樣可以使得在不影響其他子產品的情況下重構一個子產品中的屬性變得更加友善.是以不建議在程式類本身上使用 @EnableConfigurationProperties, 應該在特定子產品的 @Configuration類上使用 @EnableConfigurationProperties, 該類也可以利用包私有的可見性對特定應用程式其餘部分隐藏屬性

@ConfigurationProerties中無法轉換的屬性:

• 當為 @ConfigurationProperties中的屬性配置錯誤的值時,又不希望SpringBoot應用啟動失敗.可以設定ignoreInvalidFields注解屬性為true, 預設為false

@ConfigurationProperties(prefix = "spring.logger", ignoreInvalidFields = true)
public class LogModuleProperties {
    private Boolean enabled = Boolean.True;
}           

SpringBoot将會設定enable字段為設定好的預設值. 如果沒有設定預設值 ,enabled的值将為null, 因為這裡定義的是boolean的包裝類Boolean

• @ConfigurationProperties中未知的屬性:
  • 預設情況下,SpringBoot會忽略不能綁定到 @ConfigurationProperties類字段的屬性
  • 當配置檔案中又一個屬性實際沒有綁定到 @ConfigurationProperties類時,希望SpringBoot啟動失敗
  • 或者是以前使用過這個屬性,但已經被删除了,希望被觸發告知手動從application.properties删除這個屬性
  • 這是需要設定ignoreUnknownFields注解屬性為false, 預設為true

@ConfigurationProperties(prefix = "spring.logger", ignoreUnknownFields = false)
class LogModuleProperties {
    private Boolean enabled = Boolean.TRUE;
    private String defaultSubject;
}           

對于ignoreUnkownFields, 在SpringBoot中可能有兩個帶有@ConfigurationProperties的類,同時綁定到了同一個命名空間 (namespace) 上,其中一個類可能知道某個屬性,另一個類卻不知道某個屬性,這樣會導緻啟動失敗.是以這個屬性不再使用

• 啟動時校驗@ConfigurationProperties:
  • 如果希望配置參數在傳入到應用中是有效的,可以通過在字段上添加bean validation注解,同時在類上添加 @Validated注解

@ConfigurationProperties(prefix = "spring.logger")
@Validated
@Data
class LogModuleProperties {
    @NotNull private Boolean enabled;
    @NotEmty private String defaultSubject;
}            

如果這些預設的驗證注解不能滿足驗證要求的,可以自定義注解. 如果驗證邏輯很特殊,可以實作一個方法,并用 @PostConstruct标記,如果驗證失敗,方法抛出異常即可

• 複雜屬性類型:
  • 多數情況下,傳遞給應用的參數是基本字元串或者數字,有時又需要傳遞比如List的資料類型
  • List和Set:
    • 有兩種方式讓SpringBoot自動填充List屬性:
      • 在application.properties檔案中以數組形式書寫

      spring.logger.smtpServers[0]=server1
      spring.logger.smtpServers[1]=server1           

      • application.yml本身支援List類型,可以在application.yml檔案中添加

      spring:
          mail:
              smtpServers:
                  - server1
                  - server2           

    • set集合也是使用同樣的配置方式
  • 推薦使用YML做資料配置,能夠更好的閱讀,層次分明
• Duration:
  • SpringBoot内置支援從配置參數中解析duration(持續時間):

  @Data
  @ConfigurationProperties(prefix = "spring.logger")
  class loggerModuleProperties {
      private Duration pauseBetweenLogs;
  }           

  • 既可以配置毫秒數值,也可以配置帶有機關的文本:

  spring.logger.pause-between-logs=5s           

  • 如果配置duration沒有寫機關,預設按照毫秒來指定,也可以通過 @DurationUnit來指定機關:

  @Data
  @ConfigurationProperties(prefix = "spring.logger")
  class loggerModuleProperties {
      @DurationUnit(ChronoUnit.SECONDS)
      private Duration pauseBetweenLogs;
  }           

  • 常用機關如下:
    • ns: NANOSECONDS - 納秒
    • us: MICROSECONDS - 微秒
    • ms: MILLISECONDS - 毫秒
    • s: SECONDS - 秒
    • m: MINUTES - 分
    • h: HOURS - 時
    • d: DAYS - 天
• DataSize:
  • 與Duration用法一樣,預設機關是byte(位元組) , 可以通過@DataSizeUnit機關指定

  @Data
  @ConfigurationProperties(prefix = "spring.logger")
  class loggerMailModuleProperties {
      @DataSizeUnit(DataUnit.MEGABYTES)
      private DataSize maxAttachmentSize = DataSize.ofMegebytes(2);
  }            

  • 添加配置:

  spring.logger.max-attachment-size=1MB           

  輸出的結果都是以B(bytes) 為機關顯示的
  • 常見機關如下:
    • B: BYTES
    • KB: KILOBYTES
    • MB: MEGEBYTES
    • GB: GIGABYTES
    • TB: TERABYTES
• 自定義類型:
  • 有時候,想解析配置參數到自定義的對象類型上,比如自定義物品重量:

  spring.logger.max-attachment-weight=5kg           

  • 在MailModuleProeprties中添加Weight屬性:

  @Data
  @ConfigurationProperties(prefix = "spring.logger")
  class MailModuleProperties {
      private Weight maxAttachmentWeight;
  }           

  • 建立自定義轉換器converter:

  class WeightConverter implements Convert<String, Object> {
      @Override
      public Weight convert(String source) {
          // 根據String類型的source建立并傳回一個Weight類型的對象
      }
  }           

  • 将自定義轉換器converter注冊到SpringBoot上下文中

  @Configuration
  class PropertiesConfig {
      @Bean
      @ConfigurationPropertiesBinding
      public WeightConverter weightConverter() {
          return new WeightConverter();
      }
  }           

  @ConfigurationPropertiesBinding注解是讓SpringBoot使用該轉換器做資料綁定
• 标記配置屬性為Deprecated:

@DeprecatedConfigurationProperty(reason = "change name", replacement = "none")
public String getDefaultSubject() {
    return defaultSubject;
}           

可以通過添加 @DeprecatedConfigurationProperty注解到字段的getter方法上,來标示該字段為deprecated

• SpringBoot的 @ConfigurationProperties注解在綁定類型安全的Java Bean時是非常強大的
• 可以配合其注解屬性和 @DeprecatedConfigurationProperty注解讓配置更加子產品化
• 如果使用SpEL表達式,隻能選擇 @Value注解

@Repository

• 用于标注資料通路元件,即DAO元件

@Service

• 用于标注業務層元件

@RestController

• 用于标注控制層元件
• • @Controller
  • @ResponseBody

• 需要傳回頁面時要使用 @Controller而不是 @RestController

@ControllerAdvice

• 用于定義 @ExceptionHandler, @InitBinder, @ModelAttribute, 并且應用到所有 @RequestMapping中
  • @InitBinder: 在執行之前初始化資料綁定器
  • @ModelAttribute: 把值綁定到Model中,可以擷取到該值
  • @ExceptionHandler: 全局異常捕捉處理

@Component

• 泛指元件
• 當元件無法歸類時,可以使用這個注解進行标注

• 表示該方法的傳回結果直接被寫入http response body中
  • 一般在異步擷取資料時使用
• 在使用 @RequestMapping後,傳回值通常解析為跳轉路徑
• 比如:
  • 加上 @ResponseBody後傳回結果不會被解析為跳轉路徑,而是直接寫入HTTP Response Body中
  • 異步擷取json資料,加上 @ResponseBody後,會直接傳回json資料

@RequestBody

• 參數前加上這個注解,表示該參數必填
• 表示接收json字元串轉為對象List

• 元件掃描
• 掃描到有 @Component, @Cotroller, @Service等這些注解的類,就會把這些類注冊為bean*

• 表示該類是Bean的資訊源
• 相當于XML中的,一般标注在主類上

@ConditionOnProperty

• 控制Configuration在條件成立時生效
• 屬性:
  • value: 數組,擷取對應property的名稱,與name不可以同時使用
  • prefix: property名稱的字首,可有可無
  • name: 數組 ,property完整名稱或者部分名稱(與prefix組合使用,組成完整的property名稱),不可以與value同時使用
  • havingValue: 可與name組合使用,比較擷取到的屬性值與havingValue給定的值是否相同,相同才加載配置
  • matchMissing: 缺少該property時是否可以加載. 如果為true, 沒有該property也會正常加載. 如果為false, 則沒有該property時則會報錯,預設為false
  • relaxedNames: 是否支援松散比對

@Bean

• 相當于XML中的,标注在方法上
• 表示生成一個bean, 并交給Spring管理

• 使SpringBoot根據應用所聲明的依賴來對Spring架構進行配置
• 一般加在主類上

@Autowired

• byType方式
• 使用已經配置好的Bean, 完成屬性,方法的組裝
• 可以對類成員,方法以及構造函數進行标注,完成自動裝配的工作
• 如果加上 @Autowired(required = false), 當找不到bean時也不會報錯

@Qualifier

• 當有多個同一類型的Bean時,可以使用 @Qualifier("name") 來指定
• 需要和 @Autowired一起使用

@Resource

• @Resource(name = "name", type = "type")
• 如果沒有屬性的話,預設為byName, 與 @Autowired功能類似

@RequestMapping

• @RequestMapping是一個用來處理請求位址映射的注解,可以使用在類或者方法上
• 用在類上時,表示類中所有響應請求的方法都以該位址作為父路徑
• @RequestMapping有六個屬性:
  • params: 指定request中必須包含某些參數值,才讓該方法處理請求
  • headers: 指定request中必須包含某些指定的header值,才能讓該方法處理請求
  • value: 指定請求的實際位址. 指定的位址可以是URI Template模式
  • method: 指定請求的method類型 ,GET, POST, PUT,DELETE等
  • consumes: 指定處理請求的送出内容類型 - Content-Type. 比如: application,json,text,html
  • produces: 指定傳回的内容類型,僅當request請求頭中的 (Accept) 類型中包含該指定類型才傳回

@GetMapping

• @GetMapping, @PostMapping是組合注解
• 相當于 @RequestMapping(value = "/", method = RequestMethod.Get(Post, Put, Delete))

@RequestParam

• 用在方法的參數前面
• 相當于 request.getParameter

@PathVariable

• 路徑變量: RequestMapping("user/get/mac/{macAddress}")

public String getByMacAddress(@PathVariable("macAddress") String macAddress) {}           

參數與大括号裡的名字相同的話,注解後括号裡的内容可以不填

全局異常處理

• 包含 @Component
• 可以被掃描到
• 統一異常處理

@ExceptionHandler

• @Exceptionhandler(Exception.class)
  • 用在方法上面,表示遇到這個異常就執行這個方法

SpringCloud

@EnableEurekaServer

• 用在SpringBoot啟動類上
• 表示這是一個Eureka服務注冊中心

@EnableDiscoveryClient

• 表示這是一個服務,可以被注冊中心找到

@LoadBalanced

• 開啟負載均衡能力

@EnableCircuitBreaker

• 開啟斷路器功能

HystrixCommand

• @HystrixCommand(fallbackMethod = "backMethod")
• 用在方法上,表示fallbackMethod指定斷路回調方法

@EnableConfigServer

• 表示這是一個配置中心,開啟Config Server

@EnableZuulProxy

• 表示開啟zuul路由

@SpringCloudApplication

• 微服務注解集合,包含:
  • @SpringBootApplication: SpringBoot注解
  • @EnableDiscoveryClient: 注冊服務中心Eureka注解
  • @EnableCircuitBreaker: 斷路器注解
• 這是每一個微服務必須應該有的注解