Руководство по репозиториям Maven

Мы в Appwrite недавно опубликовали наш Android SDK для Maven Central и в процессе работы узнали много нового об экосистеме Gradle и Maven.

В этой серии статей мы постараемся научить вас, как создавать и публиковать собственные библиотеки Android с помощью Gradle. Прежде чем мы погрузимся в создание и публикацию артефактов с помощью Gradle, нам нужно ознакомиться с Maven, потому что, в конце концов, Gradle – это инструмент сборки для проектов на основе Java (среди нескольких других).

Если вы работали над Java-проектом, весьма вероятно, что вы слышали о Maven, так как это самый популярный инструмент сборки для Java-проектов. Большинство из нас ассоциируют Maven с pom.xml файл. Однако в Maven гораздо больше, чем кажется на первый взгляд, и вы можете очень быстро заблудиться в море знаний. Цель этой статьи – ознакомить вас с важными концепциями Maven и познакомить с различными терминологиями в экосистеме Maven.

Коробка для картотеки Файл POM

Файл POM является краеугольным камнем любого проекта Maven. Думайте об этом как о точке входа в любой проект Maven. Файл POM содержит всю информацию, необходимую для создания проекта; своего рода книга рецептов. Если вы знакомы с файлом package.json в узловых проектах, файлом composer.json в php проектах, requirements.txt в python проектах и build.gradle в других Java/Kotlin проекты, файл POM должен показаться знакомым.

Хотя мы будем использовать Gradle для создания и публикации артефактов, неплохо бы изучить структуру файла POM, поскольку эти концепции могут быть распространены и на Gradle.

Давайте возьмем пример файла POM, чтобы понять его структуру. Вы можете использовать следующую команду для создания простого проекта Maven, если хотите протестировать его самостоятельно.

mvn -B archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4

Как только вы выполните эту команду, вы заметите, что произошло несколько вещей. Во-первых, вы заметите, что для нового проекта был создан каталог с именем my-app , и этот каталог содержит файл с именем pom.xml это должно выглядеть так:


  4.0.0

  com.mycompany.app
  my-app
  1.0-SNAPSHOT

  my-app
  
  http://www.example.com

  
    UTF-8
    1.7
    1.7
  

  
    
      junit
      junit
      4.11
      test
    
  

  
    
       ... lots of helpful plugins

pom.xml содержит Объектную модель проекта (POM) для этого проекта. POM – это самая основная единица работы в Maven. Это важно помнить, потому что Maven по своей сути ориентирован на проект в том смысле, что все вращается вокруг понятия проекта. Короче говоря, POM содержит всю важную информацию о вашем проекте и является удобным местом для поиска всего, что связано с вашим проектом.

Это очень простой помпон, но он по-прежнему отображает ключевые элементы, содержащиеся в каждом стихотворении, поэтому давайте пройдемся по каждому из них, чтобы ознакомить вас с основами помпона:

проект Это элемент верхнего уровня во всех Maven pom.xml файлы.
Модификация модели Этот элемент указывает, какую версию объектной модели использует данный POM. Версия самой модели меняется очень редко, но это обязательно для обеспечения стабильности использования, если и когда разработчики Maven сочтут необходимым изменить модель.
Идентификатор группы Этот элемент указывает уникальный идентификатор организации или группы, создавшей проект. Идентификатор группы является одним из ключевых идентификаторов проекта и обычно основывается на полном доменном имени вашей организации. Например org.apache.maven.plugins является назначенным идентификатором группы для всех плагинов Maven.
артефактИд Этот элемент указывает уникальное базовое имя первичного артефакта , создаваемого этим проектом. Основным артефактом для проекта обычно является файл JAR . Вторичные артефакты, такие как исходные пакеты, также используют идентификатор артефакта как часть своего окончательного имени. Типичный артефакт, созданный Maven, будет иметь вид -. (например, myapp-1.0.jar ).
версия Этот элемент указывает версию артефакта, созданного проектом. Maven в значительной степени помогает вам в управлении версиями, и вы часто будете видеть в версии указатель СНИМОК , который указывает, что проект находится в стадии разработки. В этом руководстве мы обсудим использование моментальных снимков и то, как они работают дальше.
имя – Этот элемент указывает отображаемое имя, используемое для проекта. Это часто используется в документации, созданной Maven.
url-адрес Этот элемент указывает, где можно найти сайт проекта. Это часто используется в документации, созданной Maven.
свойства Этот элемент содержит заполнители значений, доступные в любом месте POM.
зависимости Дочерние элементы этого элемента перечисляют зависимости. Краеугольный камень ПОМ.
сборка Этот элемент обрабатывает такие вещи, как объявление структуры каталогов вашего проекта и управление плагинами.

Для получения полной документации по всем атрибутам POM вы можете обратиться к официальным документам .

🧩 Артефакты

Артефакт – это то, что либо создается, либо используется проектом. Примеры артефактов, созданных Maven для проекта, включают: Банки (архивы Java) , источник и двоичные дистрибутивы, войны , AARs (архивы Android) и т.д. Каждый артефакт идентифицируется идентификатором группы , идентификатором артефакта , версией , расширением и классификатором .

Взгляните на Android SDK для разработчиков приложений . Вы найдете следующие артефакты (и многое другое).

sdk-for-android-0.0.1-javadoc.jar                  2021-06-29 15:13       261            
sdk-for-android-0.0.1-sources.jar                  2021-06-29 15:13     18663      
sdk-for-android-0.0.1.aar                          2021-06-29 15:13     46437      
sdk-for-android-0.0.1.pom                          2021-06-29 15:13      3277

Вы найдете много .md5 , .ша1 , .ша256 , .ша512 и .спросить файлы все они используются Maven Central и другими потребителями для проверки подписи и подлинности ваших артефактов.

Вы заметите, что эти артефакты соответствуют соглашению об именовании, как указано ниже.

--.

Примечание: классификатор является необязательным полем и отсутствует в случае первичных артефактов, которыми в случае нашего проекта Android являются файлы aar и pom.

В нашем случае основными артефактами являются следующие артефакты

В нашем случае основными артефактами являются следующие артефакты
В нашем случае основными артефактами являются следующие артефакты

Наш файл aar может содержать Ресурсы Android и файл манифеста , который позволяет объединять общие ресурсы, такие как макеты и чертежи, в дополнение ко всем классам и методам Java. Наш файл pom содержит информацию о нашей библиотеке, включая все зависимости, которые мы используем внутри компании.

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

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

Когда мы будем говорить о публикации вашего проекта в следующей статье, мы будем ссылаться на все эти артефакты.

Карта мира Координаты Мавена

Мы говорили о файле pom и первичных и вторичных артефактах. В этом разделе мы погрузимся в структуру репозитория Maven и поймем, как Maven разрешает зависимости при создании вашего проекта!

Что такое Зависимость от Maven вы спрашиваете? Зависимость Maven – это любой артефакт, от которого зависит ваш проект. Типичное объявление зависимости в проекте Maven выглядит следующим образом


  
    io.appwrite
    sdk-for-android
    0.0.1

Вместе Идентификатор группы , Идентификатор артефакта и версия составляют координаты Maven . Каждый артефакт Maven идентифицируется по этим координатам.

Возникает следующий вопрос. Учитывая координаты Maven, как maven находит артефакт? Maven использует значения координат для данной зависимости для создания URL-адреса в соответствии с макетом репозитория maven .

Давайте возьмем пример Appwrite для Android SDK со следующими координатами


  io.appwrite
  sdk-for-android
  0.0.1

Согласно официальной спецификации , URL-адрес для первичных артефактов выглядит следующим образом:

/$groupId[0]/../${groupId[n]/$artifactId/$version/$artifactId-$version.$extension

Массив groupId в URL-адресе формируется из элемента в файле pom следующим образом

$$groupId – это массив строк, созданный путем разделения идентификатора группы на “.” на каталоги.

Таким образом, для значения идентификатора группы org.example.поддомен наш массив $groupId будет [org, пример, поддомен] , который при переводе в каталоги становится org/пример/поддомен .

В нашем случае идентификатор группы io.app write преобразуется в следующий путь io/запись приложения/ .

Наш следующий шаг – создать URL-адрес для основного и вторичные артефакты.

🔧 Первичные артефакты

Одной из основных особенностей Maven является его способность обрабатывать Транзитивные зависимости . То есть найти и загрузить зависимости ваших зависимостей, их зависимости и так далее, пока все зависимости не будут удовлетворены.

Точно так же, как ваш собственный проект Maven имеет pom.xml файл со списком основных зависимостей, у этих зависимостей также есть удаленный pom файл, служащий аналогичной цели. Maven использует этот файл, чтобы определить, какие другие зависимости следует загрузить. Когда координата не содержит <классификатор> , она считается основным артефактом и, как ожидается, будет иметь доступный pom.

В нашем случае основными артефактами являются файл .pom и файл .aar .

pom – Если мы будем следовать приведенному выше соглашению об URL, файл pom для Android SDK Appwrite можно найти по адресу

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.pom

аар – Если мы будем следовать приведенному выше соглашению об URL-адресах, файл aar для Android SDK Appwrite можно найти по адресу

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar

⛏️ Вторичные артефакты

Вторичные артефакты или “прикрепленные артефакты”, с другой стороны, – это зависимости, которые вы хотите загрузить Maven и которые являются вспомогательными для вашего проекта. Чаще всего они используются для загрузки javadocs и/или источники для определенной зависимости. Однако, в отличие от первичного артефакта, ожидается, что вторичный артефакт не будет иметь удаленного pom и, следовательно, никогда не будет иметь никаких зависимостей.

Они могут быть указаны в разделе <зависимости> точно так же, как и первичные артефакты:


  io.appwrite
  sdk-for-android
  0.0.1
  sources

URL-адрес для вторичных артефактов аналогичен URL-адресу для первичных артефактов, за исключением того, что у них есть необязательная переменная $classifier .

/$groupId[0]/../$groupId[n]/$artifactId/$version/$artifactId-$version-$classifier.$extension

В нашем случае вторичными артефактами являются явадоки и источники .

javadoc – Если мы будем следовать приведенному выше соглашению об URL, файл javadoc для Android SDK Appwrite может быть расположен по адресу

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1-javadoc.jar

источники – Если мы будем следовать приведенному выше соглашению об URL, исходный файл для Android SDK Appwrite можно найти по адресу

io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1-sources.jar

🏁 Контрольные суммы

Для проверки загруженных артефактов Maven вычисляет md5 , sha1 , sha256 и sha512 контрольную сумму для этого артефакта и сравнивает ее со значениями, найденными в файлах контрольных сумм, расположенных по адресу $ARTIFACT_URL.md5 или $ARTIFACT_URL.sha1 соответственно.

Это строго предназначено для быстрой проверки загрузок и НЕ предназначено для использования в целях аутентификации или безопасности. Это также НЕ заменяет использование HTTPS, так как контрольные суммы могут быть тривиально перехвачены и изменены вместе с измененными артефактами.

sha1 – контрольная сумма sha1 для наших артефактов aar, например, будет присутствовать в

  io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.sha1

md5 – тот md5 контрольная сумма для наших артефактов aar, например, будет присутствовать в

  io/appwrite/sdk-for-android/0.0.1/sdk-for-android-0.0.1.aar.md5

Аналогично для всех других артефактов (javadoc.jar.md5, pom.md5, sources.jar.md5 и так далее).

🔐 Подписи

В репозитории Maven Central обязательно указывается подпись для всех загруженных артефактов и контрольных сумм. Это обеспечивает абсолютную уверенность в подлинности загруженных артефактов. Каждый артефакт и контрольная сумма имеет соответствующий файл .asc , содержащий подпись автора артефакта.

$артефакты.asc

Для нашего файла .aar , например, соответствующий файл .asc будет находиться по адресу
$контрольная сумма.asc

Для нашего .md5 (sha1, sha256 и т.д.) файлы, соответствующий файл .asc будет находиться по адресу

📦 Репозиторий Maven

Хранилище – это Maven, в котором хранятся артефакты и зависимости всех видов. Существует ровно два вида хранилищ

Местный локальный репозиторий – это каталог на компьютере, на котором работает Maven. Он кэширует удаленные загрузки и содержит временные артефакты сборки, которые вы еще не выпустили. Обычно он находится в репозитории $HOME/.m2/
Удаленный Удаленные репозитории относятся к любому другому типу репозиториев, доступ к которым осуществляется по различным протоколам, таким как file://и https://. Эти хранилища могут быть действительно удаленным хранилищем, созданным третьей стороной для предоставления своих артефактов для загрузки (например, repo.maven.apache.org ). Другие удаленные репозитории могут быть внутренними репозиториями, созданными на файловом или HTTP-сервере вашей компании, используемыми для обмена личными артефактами между командами разработчиков и для выпусков.

Локальные и удаленные репозитории структурированы одинаково, так что сценарии могут выполняться с обеих сторон или их можно синхронизировать для автономного использования. Однако расположение репозиториев полностью прозрачно для пользователя Maven.

Последняя тема, которую мы обсудим, – это концепция репозитория Выпуска и репозитория МОМЕНТАЛЬНОГО СНИМКА .

🏆 Репозиторий релизов

Репозиторий релизов – это место, где все опубликованные артефакты хранятся в Maven. Поскольку кэширование играет действительно важную роль в репозиториях maven, настоятельно рекомендуется сделать репозитории релизов неизменяемыми. т.е. артефакты, однажды загруженные, не могут быть изменены. Допустим, вы опубликовали 0.0.1 вашей библиотеки вы не должны изменять существующую версию, вместо этого опубликуйте следующую версию, скажем, 0.0.2 . Это выполняется по умолчанию в Maven Central.

Существует также понятие Промежуточный репозиторий в Maven, который служит промежуточной областью для проверки всех ваших артефактов, прежде чем продвигать их в репозиторий выпуска.

🧪 Хранилище МОМЕНТАЛЬНЫХ СНИМКОВ

Вариант библиотеки SNAPSHOT относится к последнему коду в ветке разработки и не гарантирует, что код стабилен или неизменен, и эти варианты публикуются в репозитории SNAPSHOT . И наоборот, код в варианте Выпуска (любое значение версии без суффикса SNAPSHOT ) остается неизменным.

Другими словами, версия МОМЕНТАЛЬНОГО СНИМКА является версией разработки до окончательной версии . СНИМОК является более старым , чем его выпуск.

В процессе выпуска версия x.y.z-МОМЕНТАЛЬНОГО СНИМКА изменяется на x.y.z.x.y.z . Процесс выпуска также увеличивает версию разработки до x.y.(z+1)-МОМЕНТАЛЬНЫЙ СНИМОК . Например, версия 1.0.0-МОМЕНТАЛЬНЫЙ СНИМОК выпущена как версия 1.0.0 , а новая версия разработки – версия 1.0.1-МОМЕНТАЛЬНЫЙ СНИМОК.

Мы уже обсуждали, что Релиз репозиторий является неизменяемым. Таким образом, идея репозитория МОМЕНТАЛЬНЫХ СНИМКОВ состоит в том, чтобы обеспечить изменчивость и простоту разработки. Вы можете постоянно вносить свои последние изменения в 1.0.0-СНИМОК , и любой, кто зависит от этого, будет получать последние изменения каждый раз, когда они создают свой проект. Затем, после нескольких итераций, и все довольны последним состоянием 1.0.0-МОМЕНТАЛЬНОГО СНИМКА , он может быть окончательно выпущен как 1.0.0 , и быстрое развитие может продолжаться на 1.0.1-МОМЕНТАЛЬНЫЙ СНИМОК .

Сервис Sonatype Хостинг репозитория программного обеспечения с открытым исходным кодом (OSSRH) позволяет проектам и отдельным лицам с открытым исходным кодом создавать центральное хранилище Maven и публиковать артефакты бесплатно! В следующей статье мы рассмотрим все этапы публикации библиотеки Android в Maven Central. Так что следите за обновлениями 😉

✨ ️ Кредиты

Надеюсь, вам понравилась эта статья! Мы любим вносить свой вклад и призываем вас ознакомиться с нашими открытыми вопросами и текущие запросы предложений .

Если вы где-нибудь застряли, не стесняйтесь обращаться к нам по нашим дружественным каналам поддержки управляемым людьми 👩 💻 .

Вот несколько удобных ссылок для получения дополнительной информации:

Оригинал: “https://dev.to/appwrite/a-guide-to-maven-repositories-1e9o”