Java注解 - 簡書

[[toc]]

flag

解釋注解的方式：反射！反射是jdk中提供的一種機(jī)制，通過讀取編譯后的運(yùn)行文件昼汗，反向獲取類信息的一種手段！可以通過反射獲取類鬼雀、方法顷窒、成員變量上的運(yùn)行時(shí)注解內(nèi)容！

元注解: 能注解到注解上的注解源哩，能用在其他注解上的注解

Java 注解（Annotation）

JDK

從Java源碼中提取的所有注解

注解	版本	說明
@WebParam		表示方法的參數(shù)
@Oneway		表示為只有輸入消息而沒有輸出消息的 Web Service 單向操作
@WebResult		表示方法的返回值
@HandlerChain		使 Web Service 與外部定義的處理程序鏈相關(guān)聯(lián)鞋吉。
@WebService		用于對接口，類進(jìn)行注解励烦，表示要發(fā)布的web服務(wù)
@WebMethod		該注解用于用@WebService注解的類或接口的方法上谓着，表示要發(fā)布的方法
@SOAPMessageHandlers
@SOAPMessageHandler
@SOAPBinding		SOAP綁定類型：RPC、DOCUMENT
@InitParam
@Resource
@Resources
@PreDestroy	Servlet2.5	被@PreDestroy修飾的方法會(huì)在服務(wù)器卸載Servlet之前運(yùn)行坛掠，并且只會(huì)被服務(wù)器調(diào)用一次
@Generated
@PostConstruct	Servlet2.5	被@PostConstruct修飾的方法會(huì)在服務(wù)器加載Servle且構(gòu)造函數(shù)之后執(zhí)行赊锚，并且只會(huì)被服務(wù)器執(zhí)行一次
@RespectBinding
@ResponseWrapper
@WebServiceRefs
@Action
@RequestWrapper
@WebServiceProvider
@WebServiceRef
@FaultAction
@WebFault
@ServiceMode
@WebEndpoint
@BindingType
@WebServiceClient
@Addressing
@MTOM
@WebServiceFeatureAnnotation
@XmlSeeAlso
@XmlElementDecl
@XmlIDREF
@XmlValue
@XmlAccessorType
@XmlMixed
@XmlID
@XmlRootElement
@XmlElementRef
@XmlEnum
@XmlElementWrapper
@XmlEnumValue
@XmlType
@XmlAccessorOrder
@XmlSchemaTypes
@XmlInlineBinaryData
@XmlSchema
@XmlAnyElement
@XmlSchemaType
@XmlRegistry
@XmlList
@XmlAttribute
@XmlAttachmentRef
@XmlNs
@XmlMimeType
@XmlElements
@XmlElement
@XmlElementRefs
@XmlTransient
@XmlAnyAttribute
@XmlJavaTypeAdapters
@XmlJavaTypeAdapter
@Interned
@NotNull
@Nullable
@MessageDumping
@FeatureConstructor
@FeatureListValidatorAnnotation
@InstanceResolverAnnotation
@SchemaValidation
@Serialization
@StreamingAttachment
@UsesJAXBContext
@MemberSubmissionAddressing
@XmlAccessorFactory
@OverrideAnnotationOf
@XmlIsSet
@XmlLocation
@WsgenProtocol
@InheritedAttributes
@DescriptorFields
@ParameterNames
@ManagedAttribute
@AMXMetadata
@InheritedAttribute
@IncludeSubclass
@ManagedData
@ManagedOperation
@Description
@NameValue
@ManagedObject
@DescriptorKey
@Taxonomy
@Reset
@ProbeParam
@ProbeProvider
@Probe
@ProbeListener
@EnvelopeStyle
@Property
@DatabindingMode
@Reference
@Immutable
@Ignore
@Logger
@Setter
@Constructor
@Optimistic
@SpecializedFunction
@ScriptClass
@Function
@Getter
@CallerSensitive
@Contended
@MXBean
@ProbeName
@ProviderName
@Attributes
@NameAttributes
@ProviderAttributes
@FunctionAttributes
@ModuleName
@ModuleAttributes
@ArgsAttributes
@FunctionName
@ConstructorProperties
@Transient
@Deprecated	jdk1.5	內(nèi)置注解：用于標(biāo)志過時(shí)的類、方法和成員變量
@FunctionalInterface	jdk1.8	函數(shù)式接口注解屉栓，用于定義函數(shù)式接口
@SafeVarargs	jdk1.7	參數(shù)安全類型注解舷蒲，用于提示用戶參數(shù)安全
@Override	jdk1.5	內(nèi)置注解：用于修飾重寫的方法
@SuppressWarnings	jdk1.5	內(nèi)置注解：用戶忽略@Deprecated標(biāo)志過的警告
@Repeatable	jdk1.8	表示注解的屬性可以重復(fù)！@Repeatable通俗來講友多，就是注解容器阿纤！
@Inherited	jdk1.5	元注解：子類繼承父類的注解（子類沒有任何注解修飾）
@Retention	jdk1.5	元注解：表示注解保留周期
@Documented	jdk1.5	元注解：將注解寫入文檔
@Target	jdk1.5	元注解：表示注解可以使用在什么地方
@Native	jdk1.8	生成本機(jī)頭文件的工具的提示，以確定是否需要頭文件夷陋，如果需要欠拾，它應(yīng)該包含哪些聲明。
@Validate
@RequireContainer
@Require
@Exported
@SupportedOptions
@SupportedAnnotationTypes
@SupportedSourceVersion
@Trusted

Servlet

Tomcat 7.0及以上版本的server.api才有注解

servlet.jar 是servlet 3.0版本之前的地址
javax.servlet-api.jar 是servlet 3.0版本之后的地址

https://github.com/eclipse-ee4j/servlet-api

注解	版本	說明
@WebServlet	Servlet3.0	用于聲明servlet
@WebListener	Servlet3.0	用于聲明過監(jiān)聽器骗绕，可通過控制filter的文件名來控制執(zhí)行順序
@WebFilter	Servlet3.0	用于聲明過濾器
@WebInitParam	Servlet3.0	為 Servlet 或者過濾器指定初始化參數(shù)藐窄，配置@WebServlet或@WebFilter時(shí)使用
@MultipartConfig	Servlet3.0	HttpServletRequest 提供的對上傳文件的支持，該注解標(biāo)注在 Servlet 上面
@HandlesTypes
@HttpConstraint
@HttpMethodConstraint
@ServletSecurity

Validation

JSR-303是JAVA EE 6中的一項(xiàng)子規(guī)范酬土，叫做Bean Validation荆忍，但是這只是一個(gè)接口，沒有具體實(shí)現(xiàn)。

javax.validation.Validation刹枉、hibernate-validator和Spring validtor
提供了JSR 303規(guī)范中所有內(nèi)置constraint 的實(shí)現(xiàn)叽唱，除此之外還有一些附加的 constraint

https://beanvalidation.org
這么寫參數(shù)校驗(yàn)(validator)就不會(huì)被勸退了

注解	支持Java類型	備注
@AssertFalse	Boolean, boolean	驗(yàn)證元素值必須為flase
@AssertTrue	Boolean, boolean	驗(yàn)證元素值必須為true，否則拋異常
@CreditCardNumber	CharSequence	驗(yàn)證信用卡號(hào)碼是否有效
@DecimalMax	Object	驗(yàn)證數(shù)值是否小于等于指定值
@DecimalMin	CharSequence	驗(yàn)證數(shù)值是否大于等于指定值
@Digits(integer = 3, fraction = 2)	Long, Integer, Double, Float	驗(yàn)證注解的元素值的整數(shù)位數(shù)和小數(shù)位數(shù)上限
@Email	CharSequence	驗(yàn)證元素必須是電子郵箱地址
@Future	java.util.Date, java.util.Calendar	驗(yàn)證日期為當(dāng)前時(shí)間之后
@FutureOrPresent	java.util.Date, java.util.Calendar	驗(yàn)證日期為當(dāng)前時(shí)間或之后一個(gè)時(shí)間
@Length(min=,max=)	CharSequence	驗(yàn)證元素值包含在一個(gè)區(qū)間
@Max	CharSequence	檢驗(yàn)當(dāng)前數(shù)值小于等于指定值
@Min	BigDecimal, BigInteger, byte, short,int, long,Number.	檢驗(yàn)當(dāng)前數(shù)值大于等于指定值
@NotBlank	CharSequence	驗(yàn)證元素值不為null且移除兩邊空格后長度大于0
@NotEmpty	CharSequence,Collection,Map and Arrays	驗(yàn)證元素值不為null且不為空（字符串長度不為0微宝、集合大小不為0）
@NotNull	Object	驗(yàn)證元素值不能為 null
@Null	Object	驗(yàn)證元素值為null
@Past	java.util.Date, java.util.Calendar	驗(yàn)證日期為當(dāng)前時(shí)間之前
@PastOrPresent	java.util.Date, java.util.Calendar	驗(yàn)證日期為當(dāng)前時(shí)間或之前
@Pattern(regex=,flag=)	CharSequence	驗(yàn)證元素必須符合指定的正則表達(dá)式
@Range(min=,max=,message=)	CharSequence	驗(yàn)證數(shù)值為指定值區(qū)間范圍內(nèi)
@Size(max=, min=)	String,Collection,Map,arrays,CharSequence	驗(yàn)證元素個(gè)數(shù)包含在一個(gè)區(qū)間
@UniqueElements	Collection	校驗(yàn)集合中的元素必須保持唯一否則異常
@URL	CharSequence	驗(yàn)證日期為當(dāng)前時(shí)間之前
@Valid	Object	驗(yàn)證關(guān)聯(lián)對象元素進(jìn)行遞歸校驗(yàn)檢查
@ScriptAssert	CharSequence	腳本表達(dá)式的計(jì)算結(jié)果為true
@SafeHtml	CharSequence	可能包含不安全的html內(nèi)容

JAX-RS

Jersey和CxF框架實(shí)現(xiàn)了JSR311/JSR339標(biāo)準(zhǔn)

jersey常用注解

https://github.com/eclipse-ee4j/jersey

Annotation	作用	說明
@GET	查詢請求	相當(dāng)于數(shù)據(jù)庫的查詢數(shù)據(jù)操作
@PUT	更新請求	相當(dāng)于數(shù)據(jù)庫的更新數(shù)據(jù)操作
@POST	插入請求	相當(dāng)于數(shù)據(jù)庫的插入數(shù)據(jù)操作
@DELETE	刪除請求	相當(dāng)于數(shù)據(jù)的刪除數(shù)據(jù)操作
@Path	uri路徑	定義資源的訪問路徑棺亭，client通過這個(gè)路徑訪問資源。比如：@Path("user")
@Produces	指定返回MIME格式	資源按照那種數(shù)據(jù)格式返回蟋软，可取的值有：MediaType.APPLICATION_XXX镶摘。比如：@Produces(MediaType.APPLICATION_XML)
@Consumes	接受指定的MIME格式	只有符合這個(gè)參數(shù)設(shè)置的請求再能訪問到這個(gè)資源。比如@Consumes("application/x-www-form-urlencoded")
@PathParam	uri路徑參數(shù)	寫在方法的參數(shù)中岳守，獲得請求路徑參數(shù)凄敢。比如：@PathParam("username") String userName
@QueryParam	uri路徑請求參數(shù)	寫在方法的參數(shù)中，獲得請求路徑附帶的參數(shù)湿痢。比如：@QueryParam("desc") String desc
@DefaultValue	設(shè)置@QueryParam參數(shù)的默認(rèn)值	如果@QueryParam沒有接收到值涝缝，就使用默認(rèn)值。比如：@DefaultValue("description") @QueryParam("desc") String desc
@FormParam	form傳遞的參數(shù)	接受form傳遞過來的參數(shù)譬重。比如：@FormParam("name") String userName
@BeanParam	通過Bean的形式傳遞參數(shù)	接受client傳遞的bean類型的參數(shù)拒逮，同時(shí)這個(gè)bean可以在屬性上配置@FormParam用以解決client的屬性名稱和bean的屬性名稱不一致的問題。比如：@BeanParam User user
@Context	獲得一些系統(tǒng)環(huán)境信息	通過@Context可以獲得以下信息：UriInfo害幅、ServletConfig消恍、ServletContext、HttpServletRequest以现、HttpServletResponse和HttpHeaders等
@XmlRootElement	將bean轉(zhuǎn)換為xml	如果要將bean以xml或json的格式返回狠怨，必須要這個(gè)注解。比如：@XmlRootElementpublic class User{...}
@XmlElements
@XmlElement

spring

// 手動(dòng)回滾事務(wù)
TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();

聲明bean的注解

@Component 組件邑遏，沒有明確的角色
@Service 在業(yè)務(wù)邏輯層使用（service層）
@Repository 在數(shù)據(jù)訪問層使用（dao層）
@Controller 在展現(xiàn)層使用佣赖，控制器的聲明（C）

注入bean的注解

都可以注解在set方法和屬性上，推薦注解在屬性上（一目了然记盒，少寫代碼）憎蛤。

@Autowired 由Spring提供
@Inject 由JSR-330提供
@Resource 由JSR-250提供

java配置類相關(guān)注解

@Configuration 聲明當(dāng)前類為配置類，相當(dāng)于xml形式的Spring配置（類上）
@Bean 注解在方法上纪吮，聲明當(dāng)前方法的返回值為一個(gè)bean俩檬，替代xml中的方式（方法上）
@Configuration 聲明當(dāng)前類為配置類，其中內(nèi)部組合了@Component注解碾盟，表明這個(gè)類是一個(gè)bean（類上）
@ComponentScan 用于對Component進(jìn)行掃描棚辽，相當(dāng)于xml中的（類上）
@WishlyConfiguration 為@Configuration與@ComponentScan的組合注解，可以替代這兩個(gè)注解

切面（AOP）相關(guān)注解

Spring支持AspectJ的注解式切面編程冰肴。

@Aspect 聲明一個(gè)切面（類上）

使用@After屈藐、@Before榔组、@Around定義建言（advice），可直接將攔截規(guī)則（切點(diǎn)）作為參數(shù)联逻。

@After 在方法執(zhí)行之后執(zhí)行（方法上）
@Before 在方法執(zhí)行之前執(zhí)行（方法上）
@Around 在方法執(zhí)行之前與之后執(zhí)行（方法上）
@PointCut 聲明切點(diǎn)

在java配置類中使用@EnableAspectJAutoProxy注解開啟Spring對AspectJ代理的支持（類上）

AOP配置元素	描述
`<aop:advisor>`	定義AOP通知器
`<aop:after>`	定義AOP后置通知（不管該方法是否執(zhí)行成功）
`<aop:after-returning>`	在方法成功執(zhí)行后調(diào)用通知
`<aop:after-throwing>`	在方法拋出異常后調(diào)用通知
`<aop:around>`	定義AOP環(huán)繞通知
`<aop:aspect>`	定義切面
`<aop:aspect-autoproxy>`	定義`@AspectJ`注解驅(qū)動(dòng)的切面
`<aop:before>`	定義AOP前置通知
`<aop:config>`	頂層的AOP配置元素搓扯，大多數(shù)的<aop:*>包含在<aop:config>元素內(nèi)
`<aop:declare-parent>`	為被通知的對象引入額外的接口，并透明的實(shí)現(xiàn)
`<aop:pointcut>`	定義切點(diǎn)

@Bean的屬性支持

@Scope 設(shè)置Spring容器如何新建Bean實(shí)例（方法上包归，得有@Bean） ,其設(shè)置類型包括：
- Singleton （單例,一個(gè)Spring容器中只有一個(gè)bean實(shí)例锨推，默認(rèn)模式）,
- Protetype （每次調(diào)用新建一個(gè)bean）,
- Request （web項(xiàng)目中，給每個(gè)http request新建一個(gè)bean）,
- Session （web項(xiàng)目中箫踩，給每個(gè)http session新建一個(gè)bean）,
- GlobalSession（給每一個(gè) global http session新建一個(gè)Bean實(shí)例）
@StepScope 在Spring Batch中還有涉及
@PostConstruct 由JSR-250提供爱态，在構(gòu)造函數(shù)執(zhí)行完之后執(zhí)行谭贪，等價(jià)于xml配置文件中bean的initMethod
@PreDestory 由JSR-250提供境钟，在Bean銷毀之前執(zhí)行，等價(jià)于xml配置文件中bean的destroyMethod

@Value注解

@Value 為屬性注入值（屬性上）,支持如下方式的注入

@Value("Michael Jackson") String name; 注入普通字符
@Value("#{systemProperties['os.name']}") String osName; 注入操作系統(tǒng)屬性
@Value("#{ T(java.lang.Math).random() * 100 }") String randomNumber; 注入表達(dá)式結(jié)果
@Value("#{domeClass.name}") String name; 注入其它bean屬性
@Value("classpath:com/hgs/hello/test.txt") String Resource file; 注入文件資源
@Value("http://www.cznovel.com") Resource url; 注入網(wǎng)站資源
@Value("${book.name}") String bookName; 注入配置文件

注入配置使用方法

編寫配置文件（test.properties）

book.name= test

@PropertySource 加載配置文件(類上)

@PropertySource("classpath:/test.propertie")

③ 還需配置一個(gè)PropertySourcesPlaceholderConfigurer的bean俭识。

環(huán)境切換

@Profile 通過設(shè)定Environment的ActiveProfiles來設(shè)定當(dāng)前context需要使用的配置環(huán)境慨削。（類或方法上）
@Conditional Spring4中可以使用此注解定義條件話的bean，通過實(shí)現(xiàn)Condition接口套媚，并重寫matches方法缚态，從而決定該bean是否被實(shí)例化。（方法上）

異步相關(guān)

@EnableAsync 配置類中堤瘤，通過此注解開啟對異步任務(wù)的支持玫芦，敘事性AsyncConfigurer接口（類上）

@Async 在實(shí)際執(zhí)行的bean方法使用該注解來申明其是一個(gè)異步任務(wù)（方法上或類上所有的方法都將異步，需要@EnableAsync開啟異步任務(wù)）

定時(shí)任務(wù)相關(guān)

@EnableScheduling 在配置類上使用本辐，開啟計(jì)劃任務(wù)的支持（類上）
@Scheduled 來申明這是一個(gè)任務(wù)桥帆，包括cron,fixDelay,fixRate等類型（方法上，需先開啟計(jì)劃任務(wù)的支持）

@Enable*注解說明

這些注解主要用來開啟對xxx的支持慎皱。

@EnableAspectJAutoProxy 開啟對AspectJ自動(dòng)代理的支持
@EnableAsync 開啟異步方法的支持
@EnableScheduling 開啟計(jì)劃任務(wù)的支持
@EnableWebMvc 開啟Web MVC的配置支持
@EnableConfigurationProperties 開啟對@ConfigurationProperties注解配置Bean的支持
@EnableJpaRepositories 開啟對SpringData JPA Repository的支持
@EnableTransactionManagement 開啟注解式事務(wù)的支持
@EnableTransactionManagement 開啟注解式事務(wù)的支持
@EnableCaching 開啟注解式的緩存支持

測試相關(guān)注解

@RunWith 運(yùn)行器老虫，Spring中通常用于對JUnit的支持

@RunWith(SpringJUnit4ClassRunner.class)

@ContextConfiguration 用來加載配置ApplicationContext，其中classes屬性用來加載配置類

@ContextConfiguration(classes={TestConfig.class})

SpringMVC注解

@EnableWebMvc 在配置類中開啟Web MVC的配置支持茫多，如一些ViewResolver或者M(jìn)essageConverter等，若無此句，重寫WebMvcConfigurerAdapter方法（用于對SpringMVC的配置）漂坏。
@Controller 聲明該類為SpringMVC中的Controller
@RequestMapping 用于映射Web請求诸典，包括訪問路徑和參數(shù)（類或方法上）
@ResponseBody 支持將返回值放在response內(nèi)，而不是一個(gè)頁面今膊，通常用戶返回json數(shù)據(jù)（返回值旁或方法上）
@RequestBody 允許request的參數(shù)在request體中些阅，而不是在直接連接在地址后面。（放在參數(shù)前）
@PathVariable 用于接收路徑參數(shù)万细，比如@RequestMapping(“/hello/{name}”)申明的路徑扑眉，將注解放在參數(shù)中前纸泄，即可獲取該值，通常作為Restful的接口實(shí)現(xiàn)方法腰素。
@RestController 該注解為一個(gè)組合注解聘裁，相當(dāng)于@Controller和@ResponseBody的組合，注解在類上弓千，意味著衡便，該Controller的所有方法都默認(rèn)加上了@ResponseBody。
@ControllerAdvice 通過該注解洋访，我們可以將對于控制器的全局配置放置在同一個(gè)位置镣陕，注解了@Controller的類的方法可使用@ExceptionHandler、@InitBinder姻政、@ModelAttribute注解到方法上呆抑，這對所有注解了 @RequestMapping的控制器內(nèi)的方法有效。
@ExceptionHandler 用于全局處理控制器里的異常
@InitBinder 用來設(shè)置WebDataBinder汁展，WebDataBinder用來自動(dòng)綁定前臺(tái)請求參數(shù)到Model中鹊碍。
@ModelAttribute 本來的作用是綁定鍵值對到Model里食绿，在@ControllerAdvice中是讓全局的@RequestMapping都能獲得在此處設(shè)置的鍵值對侈咕。

Swagger2

注解名稱	注解屬性	作用域	屬性作用
@Api	tags	類	說明該類的作用
	value	類	說明該類的作用
@ApiOperation()	value	方法	描述方法作用
	notes	方法	提示內(nèi)容
	tags	方法	分組
@ApiParam()	name	方法參數(shù)	參數(shù)名
	value	方法參數(shù)	參數(shù)說明
	required	方法參數(shù)	是否必填
@ApiModel()	value	類	對象名
	description	類	描述
@ApiModelProperty()	value	方法	字段說明
	name	方法	屬性名
	dataType	方法	屬性類型
	required	方法	是否必填
	example	方法	舉例
	hidden	方法	隱藏
@ApiImplicitParam()	value	方法	參數(shù)說明
	name	方法	參數(shù)名
	dataType	方法	數(shù)據(jù)類型
	paramType	方法	參數(shù)類型
	example	方法	舉例
@ApiResponse()	response	方法	返回類
	code	方法	返回碼
	message	方法	返回信息
	examples	方法	例子

注解	屬性	值	備注
@Api	value	字符串	可用在class頭上,class描述
	description	字符串
			@Api(value = "xxx", description = "xxx")
@ApiOperation	value	字符串	可用在方法頭上.參數(shù)的描述容器
	notes	字符串
			@ApiOperation(value = "xxx", notes = "xxx")
@ApiImplicitParams	{}	@ApiImplicitParam數(shù)組	可用在方法頭上.參數(shù)的描述容器
			@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})
@ApiImplicitParam	name	字符串與參數(shù)命名對應(yīng)	可用在@ApiImplicitParams里
	value	字符串	參數(shù)中文描述
	required	布爾值	true/false
	dataType	字符串	參數(shù)類型
	paramType	字符串	參數(shù)請求方式:query/path
			query:對應(yīng)@RequestParam?傳遞
			path: 對應(yīng)@PathVariable{}path傳遞
	defaultValue	字符串	在api測試中默認(rèn)值
			用例參見項(xiàng)目中的設(shè)置
@ApiResponses	{}	@ApiResponse數(shù)組	可用在方法頭上.參數(shù)的描述容器
			@ApiResponses({@ApiResponse1,@ApiResponse2,...})
@ApiResponse	code	整形	可用在@ApiResponses里
	message	字符串	錯(cuò)誤描述
			@ApiResponse(code = 200, message = "Successful")