Справочник: инструменты, доступы, локальный запуск и разбор типичных ошибок. Возвращайтесь сюда, когда что-то не заводится.
Отметки хранятся в этом браузере и нужны только вам, на оценку они не влияют.
Справочник, а не урок. Сюда возвращаются: когда собираете машину в первый раз, когда что-то перестало работать, когда вышли на новый стенд. Проходить подряд не обязательно - пользуйтесь оглавлением.
Соберите рабочее место заранее, не откладывая до модуля 3. Пока идут теоретические модули, у вас есть время спокойно поставить инструменты и получить доступы. Если начать настройку в день, когда надо писать код, вы потеряете этот день на настройку.
Половина настройки - это не установка, а доступы. Их выдают, и запросить их надо в первый же день: часть выдаётся не мгновенно.
| Что запросить | Зачем | Без этого не получится |
|---|---|---|
| Учётная запись Nexus (логин и пароль) | скачать Maven-архетипы и библиотеки CESB SDK | сгенерировать проект - модуль 3 |
| Подгруппа в учебной группе GitLab | там вы создаёте репозиторий своего сервиса | сдать ДЗ-2 и все следующие |
| Реквизиты базы CBS: хост, SID (service name), пользователь, пароль | подключение сервиса к базе - секция CBS3DB | пройти практикум с базой - ДЗ-3 |
Права на CREATE TABLE и CREATE SEQUENCE в выданной схеме | в ДЗ-3 вы создаёте свою таблицу и последовательность | выполнить ДЗ-3 |
Драйвер ojdbc6 (файл или адрес в Nexus) | сборка сервиса с базой CBS; в публичных репозиториях его нет по лицензии | собрать cbs-проект |
| Доступ к порту Oracle с вашей машины (обычно 1521) | сервис ходит в базу с ноутбука | подключиться к базе, даже имея реквизиты |
| Адрес репозитория эталонного сервиса PayHub | смотреть, «как правильно», по ходу уроков | ничего критичного, но сильно помогает |
Отдельно уточните, одна учётная запись базы на всех или своя на каждого. Если схема
общая, договоритесь о префиксе имён объектов (например <кодсервиса>_TEMPLATE), иначе
двенадцать человек создадут таблицы с одинаковыми именами и будут мешать друг другу.
Не начинайте с установки инструментов. Сначала отправьте запрос на доступы - он будет обрабатываться, пока вы ставите JDK и Maven.
Выполните три команды. Все три должны отвечать без ошибок:
java -version # ожидаем 1.8.x - сервисы CESB собираются под JDK 8
mvn -version # ожидаем 3.6 и выше; в строке Java version - та же восьмёрка
git --version # любая современная
Проверка: три версии выведены, ошибок нет.
| Инструмент | Версия | Зачем |
|---|---|---|
| JDK | 8 | язык сервисов CESB |
| Maven | 3.6 и выше | сборка, архетипы, локальный запуск |
| Git | любая | работа с репозиторием, сдача ДЗ |
| IntelliJ IDEA | любая актуальная | разработка; все подсказки в курсе даны для неё |
Частая засада. mvn -version показывает JDK 11 или 17, потому что в системе
несколько версий Java. Сборка потом падает на невнятной ошибке компиляции. Лечится
переменной окружения JAVA_HOME, указывающей на JDK 8.
Без этого шага Maven не скачает ни архетипы, ни SDK. Это причина примерно половины всех «у меня ничего не работает».
Откройте или создайте файл ~/.m2/settings.xml - на Windows это
C:\Users\<вы>\.m2\settings.xml - и положите туда:
<?xml version="1.0"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
<localRepository>${user.home}/.m2/repository</localRepository>
<servers>
<server>
<id>cesb-nexus-repos</id>
<username>ВАШ_ЛОГИН_NEXUS</username>
<password>ВАШ_ПАРОЛЬ_NEXUS</password>
</server>
<server>
<id>archetype</id>
<username>ВАШ_ЛОГИН_NEXUS</username>
<password>ВАШ_ПАРОЛЬ_NEXUS</password>
</server>
</servers>
<profiles>
<profile>
<id>cesb-nexus</id>
<repositories>
<repository>
<id>cesb-nexus-repos</id>
<name>CESB Nexus repos</name>
<url>https://nexus.colvir.ru/repository/cesb</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</repository>
<repository>
<id>archetype</id>
<url>https://nexus.colvir.ru/repository/cesb</url>
<releases>
<enabled>true</enabled>
<checksumPolicy>fail</checksumPolicy>
</releases>
<snapshots>
<enabled>true</enabled>
<checksumPolicy>warn</checksumPolicy>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>cesb-nexus-repos</id>
<name>CESB Nexus repos</name>
<url>https://nexus.colvir.ru/repository/cesb</url>
<releases><enabled>true</enabled></releases>
<snapshots><enabled>true</enabled></snapshots>
</pluginRepository>
</pluginRepositories>
</profile>
</profiles>
<activeProfiles>
<activeProfile>cesb-nexus</activeProfile>
</activeProfiles>
</settings>
Блоки <server> - учётки к Nexus. <profile> описывает репозиторий, <activeProfiles>
его включает. Забыть <activeProfiles> - самая частая ошибка: профиль описан, но не
активен, и Maven ходит только в центральный репозиторий, где наших артефактов нет.
Проверка: mvn -U help:evaluate -Dexpression=settings.profiles отрабатывает без ошибок
доступа. Полноценно доступ проверится на шаге 4.1, при генерации проекта.
ojdbc6 не лежит в публичных репозиториях из-за лицензии - его ставят в локальный
репозиторий вручную, один раз. Файл или адрес запросите у администрации курса.
mvn install:install-file -Dfile=ojdbc6.jar \
-DgroupId=com.oracle -DartifactId=ojdbc6 \
-Dversion=11.2.0.4 -Dpackaging=jar
Проверка: BUILD SUCCESS.
Три вещи, на которых спотыкаются все, кто работает под Windows.
localhost резолвится в IPv6. Проверка авторизации SDK не распознаёт адрес ::1, и
вы получаете «Ошибка авторизации» при полностью правильном запросе. В логе это видно как
SysAuthImpl#checkAuth и ip вида 0:0:0:0:0:0:0:1. Всегда обращайтесь по
127.0.0.1.
curl в PowerShell - это не curl. Там это алиас на Invoke-WebRequest с совершенно
другим синтаксисом, и команды с -H не работают. Варианты: запускать из Git Bash или
cmd, вызывать curl.exe явно, либо просто пользоваться Postman.
JAVA_HOME. Если в системе несколько JDK, Maven возьмёт не ту. Проверяется через
mvn -version - там видно, какой именно Java он использует.
Подробный разбор - в уроке 3.1. Здесь только то, что нужно под рукой.
# сервис с БД CBS
mvn archetype:generate \
-DarchetypeGroupId=com.colvir.cesb.archetypes \
-DarchetypeArtifactId=cbs-service-archetype \
-DarchetypeVersion=LATEST
# сервис без БД
mvn archetype:generate \
-DarchetypeGroupId=com.colvir.cesb.archetypes \
-DarchetypeArtifactId=basic-service-archetype \
-DarchetypeVersion=LATEST
Проверка:
cd <ваш-artifactId>
mvn clean compile
BUILD SUCCESS означает, что архетип встал, Nexus доступен, SDK скачался и JDK
правильный. Не идите дальше, пока эта команда не отработала.
ModuleInfo-Code выбирается один раз и навсегда. Только латиница и цифры, без
подчёркиваний, регистр важен. Этот код - часть адреса каждого метода вашего сервиса.
Config.jsonФайл src/main/resources/Config.json, рядом с Module.json. Архетип его не
создаёт - сделайте сами.
Для cbs-архетипа (подставьте выданные реквизиты базы):
{
"Logging.Messages": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"],
"RequestBroker": {
"Port": "8080",
"MQ": {
"Enable": "0",
"Host": "127.0.0.1",
"Port": "",
"User": "guest",
"Pass": "guest",
"CommonQueue": "CESBCommonQueue"
},
"RequestStrategy": [
{ "Type": "HTTP", "ConnectTimeout": 5000, "ReadTimeout": 120000, "Retry": "1" },
{ "Type": "MQ", "ConnectTimeout": 5000, "ReadTimeout": 120000, "Retry": "1" }
]
},
"CBS3DB": {
"dbName": "УКАЖИТЕ_SID_БАЗЫ",
"dbServer": "УКАЖИТЕ_ХОСТ_БАЗЫ",
"dbUser": "УКАЖИТЕ_ПОЛЬЗОВАТЕЛЯ",
"dbPass": "УКАЖИТЕ_ПАРОЛЬ"
}
}
Для basic-архетипа - то же самое без секции CBS3DB.
| Секция | Кто её читает |
|---|---|
Logging.Messages | служба журналирования. На отладке держите DEBUG |
RequestBroker.MQ | параметры очереди. Enable = "0" - локально RabbitMQ не используется |
RequestBroker.RequestStrategy | таймауты и повторы транспорта. Без этого блока сервис падает при старте с «Отсутствует конфигурация для подсистемы StrategistSrvc» |
CBS3DB | подключение к базе CBS |
Запуск без шлюза доступен для сервисов, собранных с SDK версии 1.8.8.3 и выше.
Проверьте в pom.xml:
<lib-base-version>1.8.8.3</lib-base-version>
<lib-servicesbase-version>1.8.8.3</lib-servicesbase-version>
Плагин tomcat7-maven-plugin уже в pom.xml архетипа, ставить ничего не надо.
Из терминала, в корне проекта:
mvn tomcat7:run
Из IntelliJ IDEA: панель Maven справа → проект → Plugins → tomcat7 → двойной клик по tomcat7:run. Для отладки с точками останова - правой кнопкой → Debug.
Сервис поднимется на http://127.0.0.1:8081. Окно не закрывайте.
Проверка: в консоли есть сообщение о старте Tomcat.
Поднятый Tomcat ещё не значит, что сервис готов. Отправьте запрос - из Postman или curl:
curl -H "Authorization: L:P" "http://127.0.0.1:8081/sys/cmd/restart?Dbg=true&ConfFP=src/main/resources/Config.json"
Заголовок Authorization: L:P обязателен, значение ровно такое - это служебный вход SDK,
не ваши реквизиты. Тот же запрос можно слать работающему сервису, чтобы поменять
конфигурацию на лету.
Проверка: ответ получен, в консоли Tomcat нет ERROR и CRITICAL.
URL собирается из четырёх частей:
http://127.0.0.1:8081/<КодМодуля>/<префикс>/<метод>
▲ ▲ ▲
│ │ └─ name из @ServiceMethod
│ └──────────── префикс из @ServiceController
└───────────────────────── Code из Module.json
Код модуля пропускать нельзя. Адрес вида http://127.0.0.1:8081//Hello/SayHello -
два слэша подряд - означает пустой сегмент кода модуля, и метод не найдётся.
При прямом обращении передавайте объект B. Через шлюз его достраивает шлюз, а
напрямую - никто, и метод падает с NullPointerException, хотя S виден в логе:
http://127.0.0.1:8081/<КодМодуля>/Hello/SayHello?B={"Cli":{"Code":"null","D":"0","L":"RU"},"SD":{"S":"X","SA":"Y","SID":"","Auth":"L:P"},"RT":{"Type":"S"}}&S={"name":"world"}
Бизнес-параметры уезжают внутрь S, а не остаются отдельными query-параметрами. В
Postman это делать удобнее - он сам экранирует фигурные скобки; в curl закавычьте URL
целиком.
Оба способа локального запуска плохо дружат с методами, которые требуют авторизации:
полноценного контура аутентификации на вашей машине нет. На время тестирования такие
методы помечают аннотацией @AuthParam - подробнее в уроке 4.1.
Нужен, только если вы отлаживаете сам шлюз, а не свой сервис. Для обычной работы берите способ выше - он быстрее и без возни с двумя проектами.
Здесь работают два отдельных проекта: проект шлюза (берётся из хранилища) и ваш
проект сервиса. Каждый запускается своим tomcat7:run из своего окна. Конфигурация в
этом случае берётся из resources/Config.json шлюза, поэтому свой сервис надо
прописать в его конфигурацию. Дополнительно в файл hosts добавляют код вашего сервиса
и код шлюза cesbcore с адресом 127.0.0.1 - шлюз обращается к сервису по адресу вида
http://servicecode.
В проекте шлюза - mvn tomcat7:run. Шлюз поднимется на http://127.0.0.1:8080.
Из Postman - запустить шлюз: GET http://127.0.0.1:8080/Sys/cmd/Start с
заголовком Authorization: L:P.
В проекте своего сервиса, второе окно - mvn tomcat7:run (порт 8081).
Из Postman - запустить сервис. Параметры длинные, поэтому ссылка целиком:
http://127.0.0.1:8081/Sys/cmd/Start?B={"Cli":{"Code":"null","D":"0","L":"RU"},"SD":{"S":"X","SA":"Y","SID":"","Auth":"L:P"},"RT":{"Type":"S"}}&S={}
Дальше проверочные запросы идут через шлюз, на порт 8080:
http://127.0.0.1:8080/<КодМодуля>/...
Коротко: шаги 1 и 3 - это Maven в двух разных проектах, шаги 2 и 4 - HTTP-запросы из Postman. Оба процесса Tomcat должны остаться запущенными.
При смене конфигурации перезапускать нужно и шлюз, и сервис (шаги 1-4). При пересборке только сервиса достаточно шагов 3-4.
Архетип кладёт в проект боевой .gitlab-ci.yml. В курсе он не подходит по двум причинам:
main (правило workflow), поэтому на ветке ДЗ и в Merge
Request пайплайна не будет вовсе;build и deploy собирают Docker-образ, пушат его в registry и деплоят в
Kubernetes. В учебном GitLab нет ни registry, ни кластера - после мержа обе стадии
упадут.Поэтому в курсе используется учебный пайплайн. Он запускается на каждой ветке и проверяет одно - что проект собирается:
# Учебный пайплайн курса: только сборка, без образов и деплоя.
# Запускается на каждой ветке и в каждом Merge Request.
compile:
image: maven:3-jdk-8
script:
- test -s README.md
- 'if [ -f pom.xml ]; then sh worker.sh compile; else echo "pom.xml пока нет - сборка начнется с ДЗ-3"; fi'
Когда класть. В ДЗ-2 файл кладётся в корень репозитория рядом с README.md. Пока в
проекте нет pom.xml, пайплайн проверяет только, что README не пуст. В ДЗ-3 архетип
перезапишет файл боевым - верните учебный до первого пуша. worker.sh и
settings.xml оставьте те, что сгенерировал архетип: сборка идёт через них.
Учётки Nexus в пайплайне настраивает администрация курса - переменными CI/CD на
уровне учебной группы (NEXUS_USER, NEXUS_PASS и, если нужно, COLVIR_MAVEN_USER,
COLVIR_MAVEN_PASS). В свой проект их добавлять не нужно, в settings.xml и в
репозиторий пароли не пишутся.
Тесты пайплайн не запускает. worker.sh compile собирает проект с
-DskipTests=True - так устроен и боевой пайплайн. Тесты вы прогоняете сами, mvn test
перед каждым пушем.
Идите сверху вниз - таблица собрана по реальным граблям.
| Симптом | Причина | Что сделать |
|---|---|---|
401 Unauthorized при сборке | неверные логин/пароль Nexus | проверьте <username>/<password> в settings.xml; id сервера должен совпадать с id репозитория |
Could not find artifact com.colvir.cesb... | Maven не видит наш репозиторий | проверьте URL и что профиль cesb-nexus есть в <activeProfiles> |
| Maven не находит архетип | нет доступа к репозиторию архетипов | проверьте блок <repository id="archetype">; попробуйте mvn -U |
Unsupported major.minor version, странные ошибки компиляции | сборка идёт не под JDK 8 | поправьте JAVA_HOME, проверьте mvn -version |
«Ошибка авторизации» на /sys/cmd/restart | обращаетесь по localhost → IPv6 | замените на 127.0.0.1 |
«Ошибка авторизации», хотя адрес 127.0.0.1 | заголовок не дошёл | в PowerShell curl - это Invoke-WebRequest; шлите из Git Bash, curl.exe или Postman. Значение ровно L:P |
«Отсутствует конфигурация для подсистемы StrategistSrvc» | нет блока RequestStrategy | добавьте его в RequestBroker (шаг 4.2) |
| Ошибки 541 / 542 при старте | нет секции конфигурации или обязательного поля | сверьте Config.json с шагом 4.2 |
NullPointerException, в логе S={...}, B пустой | при прямом обращении не передан B | передайте B в запросе (шаг 4.5) |
| 404 на вашем методе | URL собран не из четырёх частей | код модуля на месте? нет двойного слэша? префикс и имя метода совпадают по регистру с аннотациями? |
| 404, хотя URL верный | сервис не стартовал или не получил конфигурацию | Module.json в src/main/resources? /sys/cmd/restart отработал? что в консоли Tomcat? |
| Падает при обращении к базе | нет или неверны реквизиты CBS3DB, либо закрыт порт | сверьте реквизиты; проверьте доступность порта Oracle с вашей машины |
500 при вставке, в тексте No setter found for the keyProperty 'id' in ...bas.BAS | в маппере используется <selectKey keyProperty="id"> - сессия SDK оборачивает параметр в системный объект BAS, у которого нет сеттера id | уберите <selectKey>, берите NEXTVAL прямо в INSERT, а id дочитывайте отдельным запросом через CURRVAL в той же сессии (урок 3.1, шаг 7.3) |
Запрос не находит параметр: There is no getter for property named 'clientCode' | DAO вызван через Ex-метод, а в маппере обращение к полю без префикса | в расширенных методах данные лежат в обёртке: #{sParam} для скаляра, #{sParam.поле} для объекта, #{data.поле} для данных B (урок 3.1, шаг 7.3) |
| Запрос отрабатывает, но параметры пустые | смешаны обычные и расширенные методы: selectOne с маппером под BASEx или наоборот | приведите к одному виду - везде Ex-методы и parameterType="...bas.BASEx" |
| После пуша ветки пайплайна нет | в проекте боевой .gitlab-ci.yml из архетипа - он запускается только в main | замените файл учебным (раздел 4b) |
В пайплайне упали build или deploy | то же: боевой пайплайн ищет registry и Kubernetes | замените файл учебным (раздел 4b) |
401 Unauthorized в пайплайне, хотя локально сборка проходит | у раннера нет учёток Nexus | это настройка учебной группы - напишите администрации курса |
Ничего не подошло - смотрите консоль Tomcat, где запущен tomcat7:run: там виден и
входящий запрос, и полный стектрейс. Одна строка ошибки без стектрейса почти никогда не
позволяет понять причину. При обращении за помощью прикладывайте стектрейс целиком.
Рабочее место собрано, если проходят все шесть пунктов. Этот же список - то, что подтверждают перед началом модуля 3.
java -version показывает 1.8, mvn -version использует ту же восьмёрку.mvn clean compile даёт BUILD SUCCESS..gitlab-ci.yml (раздел 4b) и зелёный пайплайн.mvn tomcat7:run поднимает сервис на 127.0.0.1:8081./sys/cmd/restart отрабатывает, в консоли нет ERROR и CRITICAL.Отдельно, когда выдадут реквизиты базы: сервис подключается к CBS и в схеме создаётся таблица. Без этого пункта пройдут только теория и первые шаги ДЗ-3.