Соответствие URI ссылок на контент

Для сопоставления иерархических URI с шаблонами и извлечения аргументов используйте UriDeepLinkMatcher. Для десериализации сопоставленных аргументов в классы ключей используется kotlinx.serialization.

Чтобы создать UriDeepLinkMatcher, укажите шаблон DeepLinkUri и сериализатор для соответствующего ключа:

@Serializable
data class UserProfileKey(val id: String) : NavKey

val userProfilePattern = DeepLinkUri("www.example.com/users/{id}")
val userProfileMatcher = UriDeepLinkMatcher(userProfilePattern, serializer<UserProfileKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/users/123")
val matchResult = userProfileMatcher.match(request)
val key = matchResult?.key // UserProfileKey(id = "123")
UriMatcherSnippets.kt

Если вы используете неиерархические URI или специальные схемы (например, tel:), прочитайте статью Как создавать специальные сопоставители ссылок на контент.

Поддерживаемые шаблоны сопоставления

UriDeepLinkMatcher сопоставляет URI на основе пяти компонентов: схемы, источника, пути, запроса и фрагмента. В разделах ниже описаны поддерживаемый синтаксис шаблонов, плейсхолдеры аргументов и правила сопоставления для каждого компонента.

Соответствие схемы

Если в шаблоне URI нет схемы, сопоставляются и http, и https. Чтобы сопоставить определенную схему, включите ее в шаблон. Исключение: схема http в шаблоне соответствует URI запросов http и https, а схема https – только запросам https.

Сопоставление по авторитетности

UriDeepLinkMatcher выполняет точное соответствие без учета регистра для URI authority (хост и необязательный порт). Плейсхолдеры и подстановочные знаки в URI не поддерживаются, а аргументы не извлекаются.

Сопоставление путей

Поддерживаются следующие шаблоны путей:

Сопоставление запросов

Порядок параметров запроса в URI запроса не обязательно должен совпадать с порядком в URI шаблона. Кроме того, параметры, которые есть в URI запроса, но отсутствуют в URI шаблона, игнорируются.

Поддерживаются следующие шаблоны параметров запроса:

Сопоставление фрагментов

Поддерживаются следующие типы шаблонов фрагментов:

Поддерживаемые типы данных

UriDeepLinkMatcher поддерживает десериализацию аргументов URI в примитивные типы, перечисления, коллекции и пользовательские объекты. Сериализация делится на две категории:

• Стандартная сериализация. Использует kotlinx.serialization для десериализации в:
  • Примитивы (Boolean, Int, Long, Float, Double, Char, Byte, Short) и String
  • Перечисления
  • Set, List или Array примитивов, строк или перечислений
  • Вложенные классы @Serializable (свойства которых преобразуются в отдельные плейсхолдеры URI).
• Пользовательская сериализация с помощью DeepLinkSerializer. Преобразует один объект String в пользовательские объекты, внешние типы (например, java.time.LocalDate) или коллекции с пользовательскими разделителями.

Стандартная сериализация

UriDeepLinkMatcher работает со стандартными типами и плоскими структурами без необходимости реализовывать пользовательские сериализаторы.

Примитивы и строки

UriDeepLinkMatcher автоматически декодирует примитивные типы (Boolean, Int, Long, Float, Double, Char, Byte, Short) и String:

@Serializable
data class UserProfileKey(val id: Int) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/users/{id}"),
    serializer<UserProfileKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/users/123")
val key = matcher.match(request)?.key // UserProfileKey(id = 123)
UriMatcherSnippets.kt

Перечисления

Значения перечисления сопоставляются с названиями элементов перечисления с учетом регистра:

enum class SortOrder { RELEVANCE, DATE, POPULARITY }

@Serializable
data class ProductsKey(val sort: SortOrder) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/products?sort={sort}"),
    serializer<ProductsKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/products?sort=DATE")
val key = matcher.match(request)?.key // ProductsKey(sort = SortOrder.DATE)
UriMatcherSnippets.kt

Повторяющиеся коллекции запросов

Параметры запроса с повторяющимися ключами (например, ?id=10&id=20) автоматически десериализуются в List<T>, Set<T> или Array<T>, где T – это примитивный тип, String или перечисление:

@Serializable
data class FilteredItemsKey(val ids: List<Int>) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/items?id={ids}"),
    serializer<FilteredItemsKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/items?id=10&id=20")
val key = matcher.match(request)?.key // FilteredItemsKey(ids = listOf(10, 20))
UriMatcherSnippets.kt

Вложенные классы @Serializable

Если NavKey содержит свойство, тип которого является другим классом @Serializable, UriDeepLinkMatcher преобразует его свойства так, чтобы каждое свойство вложенного класса напрямую сопоставлялось с отдельным параметром URI с тем же именем:

enum class SortOrder { RELEVANCE, DATE, POPULARITY }

@Serializable
data class SearchFilters(
    val category: String,
    val sortBy: SortOrder = SortOrder.RELEVANCE
)

@Serializable
data class SearchKey(
    val query: String,
    val page: Int = 1,
    // Flattened into {category} and {sortBy}
    val filters: SearchFilters
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/search?q={query}&page={page}&category={category}&sortBy={sortBy}"),
    serializer<SearchKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/search?q=kotlin&category=books&sortBy=DATE")
val key = matcher.match(request)?.key
// SearchKey(query = "kotlin", page = 1, filters = SearchFilters(category = "books", sortBy = SortOrder.DATE))
UriMatcherSnippets.kt

Пользовательская сериализация с помощью DeepLinkSerializer

Чтобы десериализовать пользовательские объекты (например, Filter(key = "brand", value = "pixel")), внешние типы (например, java.time.LocalDate) или строки с пользовательскими разделителями (например, значения, разделенные запятыми), расширьте DeepLinkSerializer<T>.

DeepLinkSerializer<T> – это абстрактный класс KSerializer<T>, который преобразует String в T и наоборот:

abstract class DeepLinkSerializer<T : Any> : KSerializer<T> {
    abstract val serialName: String
    abstract fun deserialize(value: String): T
    abstract fun serialize(value: T): String
}

Например, рассмотрим определения Filter и FilterSerializer, которые используются в следующих фрагментах кода:

@Serializable
data class Filter(val key: String, val value: String)

object FilterSerializer : DeepLinkSerializer<Filter>() {
    override val serialName: String = "com.example.Filter"

    override fun deserialize(value: String): Filter {
        val parts = value.split(":", limit = 2)
        if (parts.size < 2) {
            throw SerializationException("Invalid filter: $value. Expected key:value.")
        }
        return Filter(key = parts[0], value = parts[1])
    }

    override fun serialize(value: Filter): String = "${value.key}:${value.value}"
}
UriMatcherSnippets.kt

Отдельные пользовательские объекты

Чтобы декодировать объект из одной строки параметра URI (например, ?filter=brand:google), добавьте к свойству аннотацию @Serializable(with = ...):

@Serializable
data class CatalogKey(
    @Serializable(with = FilterSerializer::class)
    val filter: Filter
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/catalog?filter={filter}"),
    serializer<CatalogKey>()
)

val request = DeepLinkRequest(uri = "https://www.example.com/catalog?filter=brand:google")
val key = matcher.match(request)?.key // CatalogKey(filter = Filter("brand", "google"))
UriMatcherSnippets.kt

Пользовательские объекты в повторяющихся параметрах запроса

Чтобы десериализовать повторяющиеся параметры запроса в коллекцию пользовательских объектов (List<T>, Set<T> или Array<T>), реализуйте DeepLinkSerializer<T> для типа элемента T и добавьте аннотацию @Serializable(with = ...) к аргументу типа свойства:

@Serializable
data class SearchResultsKey(
    val query: String,
    val filters: List<@Serializable(with = FilterSerializer::class) Filter> = emptyList()
) : NavKey

val searchResultsPattern = DeepLinkUri("www.example.com/search?q={query}&filter={filters}")
val searchResultsMatcher = UriDeepLinkMatcher(searchResultsPattern, serializer<SearchResultsKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/search?q=phone&filter=brand:google&filter=color:hazel")
val matchResult = searchResultsMatcher.match(request)
val key = matchResult?.key
// SearchResultsKey(query = "phone", filters = listOf(Filter("brand", "google"), Filter("color", "hazel")))
UriMatcherSnippets.kt

Наборы значений, разделенные запятыми, в отдельных параметрах

Чтобы преобразовать значения, разделенные запятыми или другими символами (например, ?ids=1,2,3), в коллекцию, реализуйте DeepLinkSerializer для всего типа коллекции и добавьте к свойству аннотацию @Serializable(with = ...):

object IntListCsvSerializer : DeepLinkSerializer<List<Int>>() {
    override val serialName: String = "com.example.IntListCsv"

    override fun deserialize(value: String): List<Int> {
        if (value.isEmpty()) return emptyList()
        return value.split(",").map { it.trim().toInt() }
    }

    override fun serialize(value: List<Int>): String = value.joinToString(",")
}

@Serializable
data class ItemListKey(
    @Serializable(with = IntListCsvSerializer::class)
    val ids: List<Int>
) : NavKey

val itemListPattern = DeepLinkUri("www.example.com/items/{ids}")
val itemListMatcher = UriDeepLinkMatcher(itemListPattern, serializer<ItemListKey>())

val request = DeepLinkRequest(uri = "https://www.example.com/items/10,20,30")
val key = itemListMatcher.match(request)?.key // ItemListKey(ids = listOf(10, 20, 30))
UriMatcherSnippets.kt

Проверка аргументов и результаты сопоставления

UriDeepLinkMatcher различает несовпадения (возвращает null, чтобы можно было попробовать другие сопоставители) и неподдерживаемые конфигурации (выдает исключение).

Несоответствия

Несоответствие возникает, когда URI входящего запроса не соответствует требованиям к шаблону или типу:

• Отсутствуют обязательные параметры. Ключевые свойства, которые не могут иметь значение NULL и не имеют значений по умолчанию, а соответствующие им параметры URI отсутствуют в URI запроса.
• Ошибки синтаксического анализа типов. Извлеченные значения аргументов, которые не могут быть преобразованы в ожидаемый тип свойства (например, "abc" для свойства Int).

Если совпадение не найдено, UriDeepLinkMatcher.match возвращает null, что позволяет оценить последующие сопоставители.

Рассмотрим класс ключа и сопоставитель, настроенные со значениями по умолчанию, вложенными объектами и перечислениями:

enum class MapLayer { STANDARD, SATELLITE, TERRAIN }

@Serializable
data class LayerOptions(
    val style: String,
    val layer: MapLayer = MapLayer.STANDARD
)

@Serializable
data class MapKey(
    val location: String,
    val zoom: Int = 12,
    val options: LayerOptions
) : NavKey

val matcher = UriDeepLinkMatcher(
    DeepLinkUri("www.example.com/map/{location}?zoom={zoom}&style={style}&layer={layer}"),
    serializer<MapKey>()
)
UriMatcherSnippets.kt

В таблице ниже показаны результаты сопоставления для различных URI запросов.

Неподдерживаемые конфигурации

Если класс ключа содержит неподдерживаемые типы данных, то при сопоставлении UriDeepLinkMatcher выдает исключение вместо возврата null.

• Карты и многомерные коллекции. UriDeepLinkMatcher поддерживает только одномерные коллекции примитивов, строк, перечислений или пользовательских типов, аннотированных с помощью DeepLinkSerializer. Map types throw an IllegalArgumentException, while nested collections (such as List<List<String>>) throw a SerializationException.
• Неаннотированные коллекции пользовательских объектов. Коллекции пользовательских типов (например, List<Filter>) вызывают ошибку SerializationException, если тип элемента не аннотирован с помощью DeepLinkSerializer.
• Неразвернутые вложенные классы. Вложенные классы @Serializable нельзя сопоставить с одним плейсхолдером (например, ?user={user}) без DeepLinkSerializer.

// Throws IllegalArgumentException: Map decoding is not supported.
@Serializable
data class InvalidKey(val tags: Map<String, String>) : NavKey
// Throws SerializationException: Only collections of primitives are supported.
@Serializable
data class InvalidKey(val filters: List<Filter>) : NavKey
UriMatcherSnippets.kt

UriMatchResult: сравнение

Экземпляры UriMatchResult ранжируются по следующим критериям:

1. Тип MatchResult. UriMatchResult имеет более высокий приоритет, чем другие типы MatchResult.
2. Точный путь. Точные совпадения путей имеют более высокий приоритет, чем совпадения с плейсхолдерами или подстановочными знаками.
3. Количество аргументов пути. Чем больше аргументов пути, тем выше рейтинг.
4. Наличие аргументов. Совпадения, содержащие аргументы, имеют более высокий приоритет, чем совпадения без аргументов.
5. Общее количество аргументов. Общее количество аргументов (путь, запрос, фрагмент) – это последний критерий, который используется для разрешения конфликтов.

UriDeepLinkMatcher: настроить

UriDeepLinkMatcher – это класс open, подкласс которого можно создать, чтобы настроить сопоставление URI и извлечение аргументов.

• matchRequest – точка входа верхнего уровня для входящего объекта DeepLinkRequest. Переопределите этот метод, чтобы проверять дополнительные параметры запроса или применять пользовательские предварительные условия перед сопоставлением URI.
• matchUri – сопоставляет DeepLinkUri с настроенным шаблоном. Переопределите этот метод, чтобы перехватывать и нормализовать входящие URI (например, переписывать динамические субдомены или устаревшие форматы путей) перед вызовом super.matchUri.
• matchArguments десериализует извлеченные карты аргументов пути, запроса и фрагмента в экземпляр ключа навигации с помощью предоставленного serializer. Переопределите этот метод, чтобы вставить динамические значения или преобразовать аргументы перед созданием экземпляра ключа.

В примере ниже показано, как создать подкласс UriDeepLinkMatcher, чтобы нормализовать префиксы путей URL устаревшего формата перед сопоставлением.

class LegacyPrefixUriDeepLinkMatcher<T : Any>(
    uriPattern: DeepLinkUri,
    serializer: KSerializer<T>
) : UriDeepLinkMatcher<T>(uriPattern, serializer) {

    override fun matchUri(uri: DeepLinkUri): UriMatchResult<T>? {
        val path = uri.path
        val normalizedUri = if (path != null && path.startsWith("/legacy/")) {
            DeepLinkUri(uri.toString().replaceFirst("/legacy", ""))
        } else {
            uri
        }
        return super.matchUri(normalizedUri)
    }
}
UriMatcherSnippets.kt