spring-cloud__spring-cloud-config_CVE-2020-5410_2-1-8-RELEASE

//// НЕ РЕДАКТИРУЙТЕ ЭТОТ ФАЙЛ. ОН БЫЛ СГЕНЕРИРОВАН. Ручные изменения этого файла будут потеряны при следующей генерации. Изменяйте файлы в каталоге src/main/asciidoc/. ////

image::https://circleci.com/gh/spring-cloud/spring-cloud-config/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-config/tree/master"] image::https://codecov.io/gh/spring-cloud/spring-cloud-config/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-config/branch/master"] image::https://api.codacy.com/project/badge/Grade/f064024a072c477e97dca6ed5a70fccd?branch=master["Codacy code quality", link="https://www.codacy.com/app/Spring-Cloud/spring-cloud-config?branch=master&utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-config&utm_campaign=Badge_Grade"]

Spring Cloud Config обеспечивает поддержку внешней конфигурации в распределённой системе как на стороне сервера, так и на стороне клиента. Благодаря Config Server у вас есть централизованное место для управления внешними свойствами приложений во всех средах. Концепции на стороне клиента и сервера одинаково соотносятся с абстракциями Spring Environment и PropertySource, поэтому они отлично подходят для приложений Spring, но могут использоваться в любых приложениях, работающих на любом языке. Когда приложение проходит конвейер развёртывания от разработки к тестированию и затем к продакшену, вы можете управлять конфигурацией между этими средами и быть уверенными, что приложения будут иметь всё необходимое для запуска при миграции. Реализация серверного хранилища по умолчанию использует git, поэтому она легко поддерживает помеченные версии конфигураций сред, а также доступна для широкого спектра инструментов управления содержимым. Легко добавить альтернативные реализации и подключить их через конфигурацию Spring.

== Возможности

=== Spring Cloud Config Server

Spring Cloud Config Server предоставляет следующие преимущества:

• HTTP-ориентированный API на основе ресурсов для внешней конфигурации (пары «имя-значение» или эквивалентное YAML-содержимое)
• Шифрование и дешифрование значений свойств (симметричное или асимметричное)
• Лёгкая встраиваемость в приложение Spring Boot с помощью @EnableConfigServer

=== Spring Cloud Config Client

Для приложений Spring в частности Spring Cloud Config Client позволяет:

• Подключаться к Config Server и инициализировать Spring Environment удалёнными источниками свойств.
• Шифровать и дешифровать значения свойств (симметрично или асимметрично).
• Использовать @RefreshScope для Spring @Beans, которые должны быть повторно инициализированы при изменении конфигурации.
• Использовать конечные точки управления: ** /env для обновления Environment и повторной привязки @ConfigurationProperties и уровней журналирования. ** /refresh для обновления beans с @RefreshScope. ** /restart для перезапуска контекста Spring (по умолчанию отключён). ** /pause и /resume для вызова методов Lifecycle (stop() и на ).

== Быстрый старт

В этом разделе быстрого старта рассматривается использование как сервера, так и клиента Spring Cloud Config Server.

Сначала запустите сервер следующим образом:

$ cd spring-cloud-config-server $ ../mvnw spring-boot:run

Сервер — это приложение Spring Boot, поэтому при желании вы можете запустить его из своей IDE (главный класс — ConfigServerApplication).

Затем опробуйте клиент следующим образом:

$ curl localhost:8888/foo/development {"name":"foo","label":"master","propertySources":[ {"name":"https://github.com/scratches/config-repo/foo-development.properties","source":{"bar":"spam"}}, {"name":"https://github.com/scratches/config-repo/foo.properties","source":{"foo":"bar"}} ]}

Стратегия поиска источников свойств по умолчанию заключается в клонировании git-репозитория (по адресу spring.cloud.config.server.git.uri) и использовании его для инициализации мини-SpringApplication. Environment мини-приложения используется для перечисления источников свойств и публикации их в JSON-конечной точке.

HTTP-сервис предоставляет ресурсы следующего вида:

/{application}/{profile}[/{label}] /{application}-{profile}.yml /{label}/{application}-{profile}.yml /{application}-{profile}.properties /{label}/{application}-{profile}.properties

где application внедряется как spring.config.name в SpringApplication (обычно это application в стандартном приложении Spring Boot), profile — активный профиль (или список свойств, разделённых запятыми), а label — необязательная git-метка (по умолчанию master).

Spring Cloud Config Server получает конфигурацию для удалённых клиентов из различных источников. В следующем примере конфигурация берётся из git-репозитория (который должен быть предоставлен), как показано ниже:

[source,yaml]

spring: cloud: config: server: git: uri: https://github.com/spring-cloud-samples/config-repo

Другие источники — это любая совместимая с JDBC база данных, Subversion, Hashicorp Vault, Credhub и локальные файловые системы.

=== Использование на стороне клиента

Чтобы использовать эти возможности в приложении, вы можете создать его как приложение Spring Boot, зависящее от spring-cloud-config-client (пример см. в тестовых случаях для config-client или в примере приложения). Самый удобный способ добавить зависимость — использовать Spring Boot starter org.springframework.cloud:spring-cloud-starter-config. Также есть родительский pom и BOM (spring-cloud-starter-parent) для пользователей Maven, а для пользователей Gradle и Spring CLI — файл свойств управления версиями Spring IO. В следующем примере показана типовая конфигурация Maven:

[source,xml,indent=0] .pom.xml

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>{spring-boot-docs-version}</version>
    <relativePath /> <!-- lookup parent from repository -->
</parent>

<dependencyManagement>
	<dependencies>
		<dependency>
			<groupId>org.springframework.cloud</groupId>
			<artifactId>spring-cloud-dependencies</artifactId>
			<version>{spring-cloud-version}</version>
			<type>pom</type>
			<scope>import</scope>
		</dependency>
	</dependencies>
</dependencyManagement>

<dependencies>
	<dependency>
		<groupId>org.springframework.cloud</groupId>
		<artifactId>spring-cloud-starter-config</artifactId>
	</dependency>
	<dependency>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-test</artifactId>
		<scope>test</scope>
	</dependency>
</dependencies>

<build>
	<plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
	</plugins>
</build>

<!-- repositories also needed for snapshots and milestones -->

Теперь вы можете создать стандартное приложение Spring Boot, например следующий HTTP-сервер:

@SpringBootApplication @RestController public class Application {

@RequestMapping("/")
public String home() {
    return "Hello World!";
}

public static void main(String[] args) {
    SpringApplication.run(Application.class, args);
}

}

Когда этот HTTP-сервер запускается, он получает внешнюю конфигурацию с локального сервера конфигураций по умолчанию (если он запущен) на порту 8888. Чтобы изменить поведение при запуске, вы можете изменить расположение сервера конфигураций с помощью bootstrap.properties (аналогично application.properties, но для фазы bootstrap контекста приложения), как показано в следующем примере:

spring.cloud.config.uri: http://myconfigserver.com

По умолчанию, если имя приложения не задано, будет использоваться application. Чтобы изменить имя, можно добавить следующее свойство в файл bootstrap.properties:

spring.application.name: myapp

ПРИМЕЧАНИЕ: При задании свойства ${spring.application.name} не начинайте имя приложения с зарезервированного слова application-, чтобы избежать проблем с разрешением правильного источника свойств.

Свойства bootstrap отображаются в конечной точке /env как источник свойств с высоким приоритетом, как показано в следующем примере.

$ curl localhost:8080/env { "profiles":[], "configService:https://github.com/spring-cloud-samples/config-repo/bar.properties":{"foo":"bar"}, "servletContextInitParams":{}, "systemProperties":{...}, ... }

Источник свойств с именем ```configService:<URL удалённого репозитория>/<имя файла>содержит свойствоfooсо значениемbar` и имеет наивысший приоритет.

ПРИМЕЧАНИЕ: URL в имени источника свойств — это git-репозиторий, а не URL сервера конфигураций.

=== Пример приложения

Пример приложения можно найти https://github.com/spring-cloud/spring-cloud-config/tree/master/spring-cloud-config-sample[здесь]. Это приложение Spring Boot, поэтому вы можете запустить его обычными способами (например, mvn spring-boot:run). При запуске оно ищет сервер конфигураций на http://localhost:8888 (настраиваемое значение по умолчанию), поэтому вы также можете запустить сервер, чтобы увидеть, как всё работает вместе.

В примере есть тестовый случай, где сервер конфигураций также запускается в той же JVM (на другом порту), и тест проверяет, что свойство окружения из git-репозитория конфигурации присутствует. Чтобы изменить расположение сервера конфигураций, вы можете задать spring.cloud.config.uri в bootstrap.yml (или в системных свойствах и других местах).

Тестовый случай содержит метод main(), который запускает сервер точно так же (следите за логами, чтобы узнать его порт), поэтому вы можете запустить всю систему в одном процессе и поэкспериментировать с ней (например, запустить метод main() в своей IDE). Метод main() использует target/config как рабочий каталог git-репозитория, поэтому вы можете вносить локальные изменения там и видеть их отражение в работающем приложении. В следующем примере показан сеанс экспериментов с тестовым случаем:

$ curl localhost:8080/env/sample mytest $ vi target/config/mytest.properties .. change value of "sample", optionally commit $ curl localhost:8080/refresh ["sample"] $ curl localhost:8080/env/sample sampleValue

Конечная точка refresh сообщает, что свойство «sample» изменилось.

== Сборка

:jdkversion: 1.7

=== Базовая компиляция и тестирование

Для сборки исходного кода вам потребуется установить JDK {jdkversion}.

Spring Cloud использует Maven для большинства операций, связанных со сборкой, и вы сможете быстро начать работу, клонировав интересующий вас проект и выполнив команду

$ ./mvnw install

ПРИМЕЧАНИЕ: Вы также можете установить Maven (>=3.3.3) самостоятельно и выполнять команду mvn вместо ./mvnw в приведённых ниже примерах. Если вы так сделаете, вам, возможно, потребуется добавить -P spring, если ваши локальные настройки Maven не содержат объявлений репозиториев для предварительных версий артефактов spring.

ПРИМЕЧАНИЕ: Имейте в виду, что вам может потребоваться увеличить объём памяти, доступной Maven, задав переменную окружения MAVEN_OPTS со значением наподобие -Xmx512m -XX:MaxPermSize=128m. Мы стараемся учесть это в конфигурации .mvn, поэтому если вы обнаружите, что вам приходится делать это для успешной сборки, пожалуйста, создайте заявку, чтобы эти настройки были добавлены в систему контроля версий.

Подсказки по сборке проекта можно найти в файле .travis.yml, если он есть. Там должна быть команда «script» и, возможно, «install». Также посмотрите раздел «services», чтобы узнать, нужно ли запускать какие-либо службы локально (например, mongo или rabbit). Игнорируйте части, связанные с git, которые могут быть в разделе «before_install», поскольку они относятся к настройке учётных данных git, а они у вас уже есть.

Проекты, требующие промежуточного ПО, обычно включают docker-compose.yml, поэтому рассмотрите возможность использования https://docs.docker.com/compose/[Docker Compose] для запуска промежуточных серверов в контейнерах Docker. См. README в https://github.com/spring-cloud-samples/scripts[демонстрационном репозитории scripts] для получения конкретных инструкций по типовым случаям mongo, rabbit и redis.

ПРИМЕЧАНИЕ: Если ничего не помогает, соберите проект командой из .travis.yml (обычно ./mvnw install).

=== Документация

Модуль spring-cloud-build имеет профиль «docs», и если его включить, он попытается собрать asciidoc-исходники из src/main/asciidoc. В рамках этого процесса он будет искать README.adoc и обрабатывать его, загружая все includes, но не разбирая и не рендеря его, а просто копируя в ${main.basedir} (по умолчанию ${basedir}, то есть корень проекта). Если в README есть какие-либо изменения, они появятся после сборки Maven как изменённый файл в нужном месте. Просто закоммитьте их и отправьте изменение.

=== Работа с кодом

Если у вас нет предпочтений по IDE, мы рекомендуем использовать https://www.springsource.com/developer/sts[Spring Tools Suite] или https://eclipse.org[Eclipse] при работе с кодом. Мы используем плагин Eclipse https://eclipse.org/m2e/[m2eclipse] для поддержки Maven. Другие IDE и инструменты также должны работать без проблем, если они используют Maven 3.3.3 или новее.

==== Импорт в Eclipse с помощью m2eclipse

Мы рекомендуем плагин Eclipse https://eclipse.org/m2e/[m2eclipse] при работе с Eclipse. Если у вас ещё не установлен m2eclipse, его можно найти в «Eclipse Marketplace».

ПРИМЕЧАНИЕ: Старые версии m2e не поддерживают Maven 3.3, поэтому после импорта проектов в Eclipse вам также нужно будет указать m2eclipse правильный профиль для проектов. Если вы видите множество различных ошибок, связанных с POM в проектах, проверьте, что у вас установлена актуальная версия. Если вы не можете обновить m2e, добавьте профиль «spring» в ваш settings.xml. В качестве альтернативы вы можете скопировать настройки репозиториев из профиля «spring» родительского pom в ваш settings.xml.

==== Импорт в Eclipse без m2eclipse

Если вы предпочитаете не использовать m2eclipse, вы можете сгенерировать метаданные проекта Eclipse с помощью следующей команды:

[indent=0]

$ ./mvnw eclipse:eclipse

Сгенерированные проекты Eclipse можно импортировать, выбрав import existing projects в меню file.

=== JCE

Если вы получаете исключение «Illegal key size» и используете JDK от Sun, вам необходимо установить файлы политики Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction. Дополнительную информацию см. по следующим ссылкам:

https://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html[Java 6 JCE]

https://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html[Java 7 JCE]

https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Java 8 JCE]

Извлеките файлы JCE в папку JDK/jre/lib/security для той версии JRE/JDK x64/x86, которую вы используете.

== Участие в разработке

:spring-cloud-build-branch: master

Spring Cloud распространяется под неограничивающей лицензией Apache 2.0 и следует стандартному процессу разработки на Github, используя Github tracker для отслеживания проблем и слияния pull request'ов в master. Если вы хотите внести даже что-то тривиальное, не стесняйтесь, но следуйте приведённым ниже рекомендациям.

=== Подпишите лицензионное соглашение участника

Прежде чем мы примем нетривиальный патч или pull request, нам потребуется, чтобы вы подписали https://cla.pivotal.io/sign/spring[Contributor License Agreement]. Подписание соглашения участника не даёт никому прав на коммиты в основной репозиторий, но означает, что мы можем принимать ваши вклады, и вы получите указание авторства, если мы это сделаем. Активным участникам может быть предложено присоединиться к основной команде и получить возможность объединять pull request'ы.

=== Кодекс поведения

Этот проект придерживается Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[кодекса поведения]. Участвуя в проекте, вы обязаны соблюдать этот кодекс. Пожалуйста, сообщайте о неприемлемом поведении по адресу [email protected].

=== Соглашения о коде и поддержание порядка

Ни одно из этих требований не является обязательным для pull request, но все они помогут. Их также можно добавить после первоначального pull request, но до слияния.

• Соблюдайте соглашения о форматировании кода Spring Framework. Если вы используете Eclipse, вы можете импортировать настройки форматирования с помощью файла eclipse-code-formatter.xml из проекта https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring Cloud Build]. Если вы используете IntelliJ, вы можете использовать https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin] для импорта того же файла.
• Убедитесь, что все новые файлы .java содержат простой Javadoc-комментарий класса по крайней мере с тегом @author, указывающим вас, и желательно хотя бы абзац о том, для чего предназначен класс.
• Добавьте заголовочный комментарий лицензии ASF во все новые файлы .java (скопируйте из существующих файлов проекта)
• Добавьте себя как @author в файлы .java, которые вы существенно изменяете (не просто косметические правки).
• Добавьте немного Javadoc и, если вы меняете пространство имён, некоторые элементы документации XSD.
• Несколько модульных тестов тоже очень помогут — кому-то нужно это сделать.
• Если никто другой не использует вашу ветку, пожалуйста, перебазируйте её на текущий master (или другую целевую ветку в основном проекте).
• При написании сообщения коммита, пожалуйста, следуйте https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[этим соглашениям]; если вы исправляете существующую проблему, добавьте в конце сообщения коммита (где XXXX — номер проблемы).

=== Checkstyle

Spring Cloud Build поставляется с набором правил checkstyle. Вы можете найти их в модуле spring-cloud-build-tools. Наиболее примечательные файлы в этом модуле:

.spring-cloud-build-tools/

└── src    ├── checkstyle    │   └── checkstyle-suppressions.xml <3>    └── main    └── resources    ├── checkstyle-header.txt <2>    └── checkstyle.xml <1>

<1> Правила Checkstyle по умолчанию <2> Настройка заголовка файла <3> Правила подавления по умолчанию

==== Настройка Checkstyle

Правила Checkstyle по умолчанию отключены. Чтобы добавить checkstyle в ваш проект, просто определите следующие свойства и плагины.

.pom.xml

<reporting>
    <plugins>
        <plugin> <5>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-checkstyle-plugin</artifactId>
        </plugin>
    </plugins>
</reporting>

Если вам нужно отключить некоторые правила (например, требуется большая длина строки), достаточно определить файл ${project.root}/src/checkstyle/checkstyle-suppressions.xml с вашими подавлениями. Пример:.projectRoot/src/checkstyle/checkstyle-suppresions.xml

Рекомендуется скопировать ${spring-cloud-build.rootFolder}/.editorconfig и ${spring-cloud-build.rootFolder}/.springformat в ваш проект. Таким образом будут применены некоторые правила форматирования по умолчанию. Вы можете сделать это, запустив следующий скрипт:```bash $ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig $ touch .springformat

=== Настройка IDE

==== Intellij IDEA

Чтобы настроить Intellij, вы должны импортировать наши соглашения по оформлению кода, профили проверок и настроить плагин Checkstyle. Следующие файлы можно найти в проекте https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build].

.spring-cloud-build-tools/
----
└── src
    ├── checkstyle
    │   └── checkstyle-suppressions.xml <3>
    └── main
        └── resources
            ├── checkstyle-header.txt <2>
            ├── checkstyle.xml <1>
            └── intellij
                ├── Intellij_Project_Defaults.xml <4>
                └── Intellij_Spring_Boot_Java_Conventions.xml <5>
----
<1> Правила Checkstyle по умолчанию
<2> Настройка заголовка файла
<3> Правила подавления по умолчанию
<4> Параметры проекта по умолчанию для Intellij, которые применяют большинство правил Checkstyle
<5> Соглашения о стиле проекта для Intellij, которые применяют большинство правил Checkstyle

.Стиль кода

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[Стиль кода]

Перейдите в `File` -> `Settings` -> `Editor` -> `Code style`. Затем нажмите на значок рядом с разделом `Scheme`. После этого нажмите на значение `Import Scheme` и выберите опцию `Intellij IDEA code style XML`. Импортируйте файл `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml`.

.Профили проверок

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[Стиль кода]

Перейдите в `File` -> `Settings` -> `Editor` -> `Inspections`. Затем нажмите на значок рядом с разделом `Profile`. После этого нажмите на `Import Profile` и импортируйте файл `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml`.

.Checkstyle

Чтобы Intellij работал с Checkstyle, необходимо установить плагин `Checkstyle`. Также рекомендуется установить `Assertions2Assertj` для автоматического преобразования утверждений JUnit.

image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle]

Перейдите в `File` -> `Settings` -> `Other settings` -> `Checkstyle`. Затем нажмите на значок `+` в разделе `Configuration file`. Там вам нужно определить, откуда должны браться правила checkstyle. На изображении выше мы выбрали правила из клонированного репозитория Spring Cloud Build. Однако вы можете указать GitHub-репозиторий Spring Cloud Build (например, для `checkstyle.xml`: `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). Нам нужно указать следующие переменные:

- `checkstyle.header.file` - укажите его на файл `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` из репозитория Spring Cloud Build - либо в вашем клонированном репозитории, либо через URL `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt`.
- `checkstyle.suppressions.file` - подавления по умолчанию. Укажите его на файл `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` из репозитория Spring Cloud Build - либо в вашем клонированном репозитории, либо через URL `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml`.
- `checkstyle.additional.suppressions.file` - эта переменная соответствует подавлениям в вашем локальном проекте. Например, вы работаете над `spring-cloud-contract`. Тогда укажите папку `project-root/src/checkstyle/checkstyle-suppressions.xml`. Пример для `spring-cloud-contract`: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`.

ВАЖНО: Не забудьте установить `Scan Scope` в `All sources`, поскольку мы применяем правила checkstyle к производственным и тестовым исходникам.