Annotation 的设计与想法

Annotation 要怎麽定义会影响使用这个 library 的使用者体验，annotation 必须要好理解而且还要具有可扩充性。我们的目标是要方便使用者获取 RSS 格式里面的资料，所以我们可以就资料层面来看这件事情。在 RSS 格式里，有三个重要的元素：

1. Tag：像是 <title> 这种东西，他除了有许多不同的 tag ，也可能有自订的 tag 。
2. Attribute：Tag 内的属性 <title attr="Attribute"> ，这个也能够自定义。
3. value：被 tag 夹起来的值，像是 <title>This is a value</title> 。

透过从资料中拆解出这三个元素，我们可以设计三个 annotation 去分别定义这三个资料型态。透过 Kotlin 的 data class 和 annotation ，我们可以组合出许多自定义的资料。这三个资料型态分别又对应了...

1. @RssTag
2. @RssAttribute
3. @RssValue

假如现在使用者有个需求是不同的 tag 想要摆在 Kotlin data class 的同一个变数或是 property 底下，那这三个 annotation 可能都无法满足这个需求，因为以上这三个都是只能处理单个 tag 或是 单个值。因此，我们需要设计一个 annotation 让使用者可以把不同 tag 的资料按优先顺序放到指定的 data class 里面，那个 annotation 就是 @RssRawData 。

让我们来看看对应的资料会长怎麽样吧！假设我们有一个 RSS 的资料：

<channel customAttr="attr">
    <title>the title</title>
		<itunes:title>itunes title</itunes:title>
    <googleplay:description>google play desc</googleplay:description>
    <itunes:summary>itunes author</itunes:summary>
</channel>

使用 annotation 可以对应成一个 data class。

@RssTag(name = "channel")
data class CustomChannelData(
		@RssAttribute(name="customAttr")
		val customAttribute: String?,
    @RssTag(name="title",order = [OrderType.GOOGLE, OrderType.ITUNES, OrderType.RSS_STANDARD])
    val rssTitle: String?,
    @RssRawData(["itunes:summary", "googleplay:description", "googleplay:summary"])
    val description: String?,
)

我们可以看到在这边我们指定要爬一个叫 channel 的 tag ，然後把 customAttr 透过 @RssAttribute 放到 customAttribute 的 class property 里面。 rssTitle 里面想依序取资料的有 google 、itunes 和 RSS 标准格式，所以 google 平台格式没取到值才会往下个优先顺序去取，依此类推。这个顺序的设计可以确保使用者的 rssTitle 可以尽最大可能拿到可用的值。 @RssRawData 也有一样的设计概念，只是它不限於三大平台格式，使用者塞几个，他就会依照那个阵列的顺序去取值，取不到就会往下一个找，另外， @RssRawData 里面的字串阵列就是使用者想要取值的候选名单，这个名称可以随意自订。像是上方范例里面有 ["itunes:summary", "googleplay:description", "googleplay:summary"] ，代表依序寻找和取值放在 description 这个 property 里面。如此一来，我们可以确保使用者有多个 annotation 对应不同种的情况，也有一个 @RssRawData 专门处理特殊的客制化 tag 需求！