Jackson注解(官方文档翻译)

目前国内使用Jersey框架的人非常少，对于其注解的分析也不多，本人尝试着把官方文档翻译一遍，把所有的注解的了解一遍，有时候一个注解能够free掉一大块的代码呢。

翻译之后，你会发现几个重要点，官方的注解会区分为属性可用的注解，实体类可用的注解或者两者都可用的注解。

中文译文

​ 本页面列出常规用途的Jacakson2.0的注解，并按照功能分类。所有的注解包含简要介绍，以后将附上详细介绍的链接地址。

属性的别名

• @JsonProperty: 属性使用的注解，用来表示外部属性名字，就是使用别名序列化，而不是对象的名字。
  • value: 指你需要指定的名字
  • index: 指的是属性的index值，暂未知用途
  • defaultValue: 指定默认值，暂未知用途

场景1：(目前对象名为storeTypeId，所以序列化出来的参数名就是storeTypeId，这里可以指定序列化为StoreTypeId这个名字，以满足需求。)
@JsonProperty("StoreTypeID")//不走驼峰命名(因为表单所限制)
private String storeTypeId;
或者
@JsonProperty(value = "StoreTypeID")//不走驼峰命名(因为表单所限制)
private String storeTypeId;

属性/实体 能否被序列化/反序列化（属性包含）

• @JsonAutoDetect: 实体类使用的注解，用于重新设置实体类中属性的自动发现机制。
  • 设置只针对属性有效，对public的getter/setter无效，没有被自动发现的属性将无法被序列化。
  • 自动发现有默认机制：先自动查询所有被 public 修饰的字段，然后再找所有被 public修饰的getter/setter。
  • 因此默认机制是不查询 private修饰的属性，如果该属性有被 public修饰的getter/setter方法，那也可以被自动发现，因为这样Jackson才有权限访问 private修饰的属性。
  • fieldVisibility=JsonAutoDetect.Visibility.ANY: 指自动发现所有修饰符的属性。
  • fieldVisibility=JsonAutoDetect.Visibility.NONE: 指禁止发现所有的属性，但是依然对getter/setter方法无效。
  • fieldVisibility=JsonAutoDetect.Visibility.NON_PRIVATE: 指自动发现除被private修饰以外的属性。
• @JsonIgnore: 属性使用的注解，用于忽略指定属性。
• @JsonIgnoreProperties: 实体类使用的注解，用于序列化的时候忽略指定的一系列属性，或者反序列化的时候忽略未知的属性(没有getter/setter的属性)。
  • 序列化的时候，@JsonIgnoreProperties({"prop1", "prop2"})，忽略列表中的属性。
  • 反序列化的时候，@JsonIgnoreProperties(ignoreUnknown=true)，忽略没有get/set的属性。
• @JsonIgnoreType: 实体类使用的注解，表示该类被忽略。
• @JsonInclude: 实体类/属性使用的注解，用于忽略NULL的属性，空的属性或者NULL的类。

场景1：(实体类中某些属性只在代码中有用，序列化不想带出来，浪费流量)
@JsonIgnoreProperties(value={"person"}) ，这里是不让person属性序列化。

场景2：(有些值为NULL不想传过去，往往还得在SQL或者代码做循环判断，损耗性能)
@JsonInclude(Include.NON_NULL)，为null的字段将不显示。

属性文档/元数据

• @JsonPropertyDescription: 并没有什么用。

反序列化/序列化的过程中操作

• @JsonFormat: 实体类/属性使用的注解，在序列化或者反序列化的时候，指定属性格式化日期/时间。
• @JsonUnwrapped: 作用在属性字段或方法上，用来将子JSON对象的属性添加到封闭的JSON对象。
  • 如果没有@JsonUnwrapped，序列化后将为{"id":111,"name":{"firstName":"张","secondName":"三"}}
  • 反之：{"id":111,"firstName":"张","secondName":"三"}
• @JsonView

反序列化的过程中操作

• @JacksonInject
• @JsonAnySetter
• @JsonCreator
• @JsonSetter
• @JsonEnumDefaultValue

序列化的过程中操作

• @JsonAnyGetter
• @JsonGetter
• @JsonPropertyOrder
• @JsonRawValue
• @JsonValue
• @JsonRootName

类型处理

• @JsonSubTypes
• @JsonTypeId
• @JsonTypeInfo
• @JsonTypeName

对象引用及标识

• @JsonManagedReference
• @JsonIdentityInfo

元注释

• @JacksonAnnotation
• @JacksonAnnotationsInside

英语原文

原文地址

This page lists all general-purpose Jackson 2.0 annotations, grouped by functionality.

For older (Jackson 1.x) annotations, refer to FasterXML Wiki.

All annotations include a brief explanation, and (in near future!) a link to full explanation with basic usage examples.

NOTE: Contributions welcome!!!

Property Naming

• @JsonProperty (also indicates that property is to be included) is used to indicate external property name, name used in data format (JSON or one of other supported data formats)
  • @JsonProperty.value: name to use
  • @JsonProperty.index: physical index to use, if dataformat (other than JSON) is index-based
  • @JsonProperty.defaultValue: textual default value defined as metadata. NOTE: core databind does NOT make any use of this value; it is currently only exposed to extension modules.

Property Inclusion

• @JsonAutoDetect: class annotation used for overriding property introspection definitions
• @JsonIgnore: simple annotation to use for ignoring specified properties:
  • Only needs to be added to one of accessors/mutators (field, getter/setter, constructor parameter), but will have effect on the "whole" property: that is, adding annotation to a "getter" will also disable "setter"
    • ... unless "setter" has @JsonProperty, in which case this is considered a "split property" with enabled "setter" but no "getter" ("read-only", so that property may be read from input, but is not written output)
• @JsonIgnoreProperties: per-class annotation to list properties to ignore, or to indicate that any unknown properties are to be ignored.
  • On serialization, @JsonIgnoreProperties({"prop1", "prop2"}) ignores listed properties
  • On deserialization, @JsonIgnoreProperties(ignoreUnknown=true) ignores properties that don't have getter/setters
• @JsonIgnoreType: per-class annotation to indicate that all properties of annotated type are to be ignored.
• @JsonInclude: annotation used to define if certain "non-values" (nulls or empty values) should not be included when serializing; can be used on per-property basis as well as default for a class (to be used for all properties of a class)

Property documentation, metadata

• @JsonPropertyDescription (added in 2.3): Annotation used to define a human readable description for a logical property.
  • Not use by core databinding, but is used by JSON Schema generator for adding description in schema.

Deserialization and Serialization details

• @JsonFormat: general annotation that has per-type behavior; can be used for example to specify format to use when serializing Date/Time values.
• @JsonUnwrapped: property annotation used to define that value should be "unwrapped" when serialized (and wrapped again when deserializing), resulting in flattening of data structure, compared to POJO structure.
• @JsonView: property annotation used for defining View(s) in which property will be included for serialization, deserialization.

Deserialization details

• @JacksonInject: annotation to indicate that property should get its value via "injection", and not from data (JSON).
• @JsonAnySetter: annotation used for defining a two-argument method as "any setter", used for deserializing values of otherwise unmapped JSON properties
• @JsonCreator: annotation used for indicating that a constructor or static factory method should be used for creating value instances during deserialization.
• @JsonSetter: alternative to @JsonProperty, for marking that specified method is a "setter-method"
• @JsonEnumDefaultValue (added in 2.8): annotation used for defining a default value when deserializing unknown Enum values. Requires config READ_UNKNOWN_ENUM_VALUES_USING_DEFAULT_VALUE feature to be enabled. See example snippet in Deserialization Features

Serialization details

• @JsonAnyGetter: annotation used to define a getter as "any getter", which returns a java.util.Map, contents of which will be serialized as additional properties for JSON Object, along with regular properties that the Object may have.
• @JsonGetter: alternative to @JsonProperty, for marking that specified method is a "getter-method"
• @JsonPropertyOrder: annotation for specifying order in which properties are serialized
• @JsonRawValue: per-property marker that can be used to specify that the value of property is to be included in serialization ''exactly'' as is, with no escaping or decoration -- useful for embedding pre-serialized JSON (or whatever data format is being used) in output
• @JsonValue: per-property marker to indicate that the POJO should serialization is to be done using value of the property, often a java.lang.String (like annotation toString() method)
• @JsonRootName: class annotation used to indicate name of "wrapper" entry used for root value, if root-wrapping is enabled

Type handling

• @JsonSubTypes: class annotation used to indicate sub-types of annotated type; necessary when deserializing polymorphic types using logical type names (and not class names)
• @JsonTypeId: property annotation used to indicate that the property value should be used as the Type Id for object, instead of using class name or external type name.
• @JsonTypeInfo: class/property annotation used to indicate details of what type information is included in serialization, as well as how.
• @JsonTypeName: class annotation used to define logical type name to use for annotated class; type name can be used as Type Id (depending on settings of @JsonTypeInfo)

Object references, identity

• @JsonManagedReference, @JsonBackReference: pair of annotations used to indicate and handle parent/child relationships expressed with pair of matching properties
• @JsonIdentityInfo: class/property annotation used to indicate that Object Identity is to be used when serializing/deserializing values, such that multiple references to a single Java Object can be properly deserialized. This can be used to properly deal with cyclic object graphs and directed-acyclic graphs.

Meta-annotations

This group includes annotations used on other annotations.

• @JacksonAnnotation: marker annotation added to all Jackson-defined annotations (which includes all other annotations contained in this package)
• @JacksonAnnotationsInside: marked annotation used to indicate that a custom annotation contains Jackson annotations; used to allow "annotation bundles", custom annotations that are annotated with Jackson annotations (why? to allow adding just a single annotation to represent set of multiple Jackson annotations)

Use with JAX-RS (DropWizard, Jersey)

Although value annotations are usable anywhere Jackson itself is, without extra work, there are some additional things to consider when using Jackson on a JAX-RS container.

Such containers require use of Jackson JAX-RS provider (or equivalent implementation of bit of glue to register Jackson for converting content between external format like JSON, and POJOs).

One specific limitation is that although Jackson can introspect annotations from within values it is passed, it does not have direct access to annotations on Resource Methods. Provider is handed these definitions, however, and it can use some of the annotations.

For more information, check out JAX-RS provider wiki, but short story is that following annotations are supported to some degree:

• @JsonView: applicable for both return value (method annotation) and input argument(s) (parameter annotation)
• @JsonRootName: similar applicable to return and input value(s).
• @JacksonAnnotationsInside: fully supported so you can create and use "annotation bundles"
• @JacksonFeature: JAX-RS provider specific annotation (not included in jackson-annotations) allows enabling/disabling SerializationFeatures and DeserializationFeatures for the endpoint

also note that annotations are NOT shared (that is, deserializer is NOT passed method annotations; nor is serializer passed parameter annotations), so in some cases you may need to violate DRY principle and add duplicate annotations

Related

It is also possible to use JAXB annotations in addition to or instead of these core annotations.

参考连接

http://blog.csdn.net/mooner_guo/article/details/42079173

http://blog.csdn.net/sdyy321/article/details/40298081

https://github.com/FasterXML/jackson-annotations/wiki/Jackson-Annotations