Службы MIS3. Разработка — различия между версиями

Материал из ИбисоПедии
Перейти к: навигация, поиск
(→‎Структура файлов)
(→‎Структура файлов)
 
(не показано 57 промежуточных версий 2 участников)
Строка 1: Строка 1:
 +
Внимание все службы должны жить  в репозитории '''ibis_server'''
 +
Этот файл отстает в соответствующего документа по КИС. см [[Службы_KIS._Разработка]]
 +
 
== Общие требования ==
 
== Общие требования ==
  
−
=== Аутентификация в БД ===
 
−
* каждая служба должна работать под своим уникальным пользователем (для того чтобы можно было мониторить работу службы со стороны БД)
 
−
* имя пользователя должно быть большими буквами и начинаться с "SRV_"
 
  
 
=== Структура файлов ===
 
=== Структура файлов ===
 
* каждая служба живет в своем каталоге
 
* каждая служба живет в своем каталоге
−
* имя исполняемого файла службы должно заканчиваться на _srv
+
* имена каталогов в '''ВЕРХНЕМ''' регистре
−
* имя исполняемого файла программы должно заканчиваться на _control
+
* все имена файлов в '''нижнем''' регистре
 +
* имя исполняемого файла службы должно заканчиваться на '''_srv'''.
 +
* имя службы должно быть в '''нижнем''' регистре и начинаться с '''ibis''' без "_srv" в конце. Например "ibis_sertificate"
 +
* имя исполняемого файла по управлению службой должно заканчиваться на '''_ctl'''
 
* настройки службы должны храниться в ini файле рядом с исполнимыми файлами.
 
* настройки службы должны храниться в ini файле рядом с исполнимыми файлами.
 +
* настройки подключения берутся из файла ibis.ini
  
 
Пример расположения служб
 
Пример расположения служб
 
<pre>
 
<pre>
 
IBIS_SRV
 
IBIS_SRV
−
  ├──Ibis.ini
+
  ├─IBIS_SERTIFIATE
−
  ├─SERTIFIATE
+
│  ├──ibis_sertificate_srv.exe
−
  │  ├──SERTIFICATE_SRV.EXE
+
│  ├──ibis_sertificate_ctl.exe
−
  │  ├──SERTIFICATE_CONTROL.EXE
+
│  ├──ibis_sertificate.ini
−
  │  ├──SERTIFICATE.INI
+
│  ├──ibis_sertificate.ini.example
 +
  │  ├──ibis_sertificate_install.bat
 +
  │  ├──ibis_sertificate_uninstall.bat
 +
  │  ├──ibis_sertificate_update.bat
 +
│  ├──ibis.ini
 +
  │  ├──readme.md
 
  │  └──LOG - Папка с логами
 
  │  └──LOG - Папка с логами
−
  └─SPARM
+
  └─IBIS_SPARM
−
     ├──SPARM_SRV.EXE
+
     ├──ibis_sparm_srv.exe
−
     ├──SPARM_CONTRL.EXE
+
     ├──ibis_sparm_ctl.exe
−
     ├──SPARM.INI
+
     ├──ibis.ini
 +
    ├──ibis_sparm.ini
 +
    ├──ibis_sparm.ini.example
 +
    ├──ibis_sparm_install.bat
 +
    ├──ibis_sparm_unistall.bat
 +
    ├──ibis_sparm_update.bat
 +
    ├──readme.md
 
     └──LOG
 
     └──LOG
 
</pre>
 
</pre>
 +
 +
Именования файлов
 +
 +
* _srv.exe сервис
 +
* _ctl.exe управляющая программ
 +
* _app.exe в виде отдельного приложения (на этапе разработки)
 +
* _install.bat скрипт для уснановки службы, как правило, содержит вызов _srv.exe с праметром /install
 +
* _uninstall.bat скрипт для удаления службы, как правило, содержит вызов _srv.exe с праметром /uninstall
 +
* _update.bat содержит параметры, неопходимые ''updater_console.exe'', для обновления сервисов.
 +
 +
Все исполняемые файлы (*.exe) должны содержать актуальную информацию о версии (номер версии должен совпадать с номером ревизии SVN на котором этот exe собран)
 +
 +
== Взаимодействие с postgresql==
 +
 +
 +
 +
 +
=== Аутентификация в БД ===
 +
 +
 +
* каждая служба должна работать под своим уникальным пользователем (для того чтобы можно было мониторить работу службы со стороны БД)
 +
* имя пользователя должно быть
 +
** большими буквами
 +
** совпадать с именем службы
 +
** начинаться на '''SRV''' (тут разница с KIS)
 +
 +
логин пароль  храним в открытом виде в файле ini (<имя службы>.ini)
 +
 +
*  [Postgresql]
 +
**  user
 +
**  password
 +
**  password_crypt
 +
 +
=== Требования к работоспособности при потере соединения ===
 +
 +
* Служба должна корректно отрабатывать ошибки, связанные с потерей соединения с БД и пытаться восстановить соединение самостоятельность.
 +
 +
=== application_name в сессии postgresql ===
 +
 +
Любая сессия должна себя идентифицировать установив ''application_name'' в формате <имя файла> (версия). Например:
 +
 +
  ibis_mqtt.exe (1.0.0.1)
 +
 +
Ниже пример кода:
 +
 +
procedure TdmMain.conAfterConnect(Sender: TObject);
 +
var
 +
  S : String;
 +
begin
 +
  S := ExtractFileName(FSrvInfo.AppExe);
 +
  S :=  S+  ' (' + FSrvInfo.FileVer + ')';
 +
  con.ExecSQL('SET  application_name = ''' + S + ''''); // устанваливаем переменную application_name (pg_stat_activity)
 +
end;
 +
 +
=== Размер work_mem ===
 +
для сессии которая слушает pg_listen (и только для нее) нужно проставить
 +
 +
set session work_mem='64kB'
 +
 +
== Зависимость от другого ПО ==
 +
 +
* служба не должна зависеть от стороннего ПО, такого как
 +
** вебсерверы (IIS, Apache)
 +
** Net framework
 +
** клиент БД
 +
 +
== Диагностика работы службы ==
 +
* служба должна писать информацию о событиях, в файл лога. Рекомендуется использовать QuickLogger https://github.com/exilon/QuickLogger  или  SynLog из библиотеки Synopse mORMot framework
 +
* файлы логов должны быть легко просматриваемы сторонними программами.
 +
* логов НЕ должно быть много. Т.е. НЕ должны забивать свободное место (должен происходить Rotate) и не должны сильно влиять на производительность дисковой подсистемы
 +
 +
== WEB API ==
 +
 +
* checkstatus - возвращает 1 в теле ответа, если сервис работает правильно
 +
* info - возвращает json, в котором есть настройки, текущий статус сервера (есть подключение к БД и т.п.)
 +
* stat - возвращает json со статистикой работы
 +
* showlog - показывает лог работы программы
 +
* admin - возвращает html страницу с настройками
 +
 +
== Документация ==
 +
 +
=== Файл readme.md ===
 +
 +
В каталоге обязательно должен быть файл readme.md в формате markdown (для редактирования можно использовать Typora). Кодировка UTF-8. В нем должны быть следующие разделы:
 +
 +
* Назначение
 +
* Описание работы
 +
* Состав (список файлов с описанием)
 +
* Установка
 +
* Настройка (что можно настроить в ini файлах, что можно настроить в adj)
 +
* Обновление
 +
* Мониторинг (проверка работоспособности, где и какие логи ведутся, как посмотреть какие ошибки возникали)
 +
 +
По правильному, содержимое файла markodown нужно продублировать на wiki (в typora есть экспорт)
 +
 +
=== Файлы-примеры конфигурационных файлов (ini.example) ===
 +
 +
Для каждого из возможных ini файлов должен лежать файл пример с расширением ini.example со всеми значениями по умолчанию и комментариями. Например для kis_mqtt.ini должен быть файл kis_mqtt.ini.example
 +
 +
=== Документация разработчика (readme_dev.md) ===
 +
 +
В исходных кодах в каталоге '''DOC'''  должен быть файл readme_dev.md в формате markdown
 +
Что можно писать
 +
 +
* структуры данных
 +
* особенности сборки
 +
* структура приложения (сервиса)
 +
 +
= Публикация и распространение =
 +
 +
на WEBDAV в папку LAST''SRV''FILES/&lt;имя-службы_большими буквами&gt; необходимо выложить два файла:
 +
 +
* &lt;имя''службы''маленькими&gt;.7z
 +
* ver.ini
 +
 +
== Состав файла 7z ==
 +
 +
# все необходимые для работы файлы
 +
# ini-файлы с настройками по умолчанию (как правило это два файла)
 +
# файл readme.md (см пункт &quot;Документация&quot;)
 +
 +
== Содержимое файла ver.ini ==
 +
 +
<code>[Ver]</code>
 +
 +
<code>srv_ver=1.0.0.13</code>
 +
 +
== Автоматизация публикации ==
 +
 +
В папке CI (Continuous Integration) необходимо создать два файла:
 +
 +
* 01_pack.bat - создает архив 7z
 +
* 02_webdav.bat публикует архив в папке на WEBDAV с помощью утилиты curl
 +
 +
Примеры скриптов можно брать из kis''services\trunk\kis''pg_rest\CI
 +
 +
== Алгоритм публикации ==
 +
 +
# Изменяем в проекте номер версии, успешно компилим
 +
# Правим файл ver.ini в папке bin
 +
# Последовательно запускаем скрипты 01_pack.bat, 02_webdav.bat (смотрим в логи что все успешно)
 +
 +
== Список сервисов ==
 +
* [[KIS MQTT_connector]] брать пример отсюда
 +
* [[Учет смертности и рождаемости ХМАО]]
 +
* [[Across]]
 +
* [[ХОСТ (портал пациента)]]
 +
* Интеграция с [[ЛИНС Махаон]]
 +
* Интеграция с [[СПАРМ]]
 +
* Интеграция с [[ИСАР]]
 +
* ЛИС результаты анализаторов - больше не используется
  
  
−
[[Категория:Руководство программиста MIS3]]
+
[[Категория:Руководство программиста MIS3]][[Категория:Интеграция MIS3]]

Текущая версия на 11:02, 17 октября 2022

Внимание все службы должны жить в репозитории ibis_server Этот файл отстает в соответствующего документа по КИС. см Службы_KIS._Разработка

Общие требования

Структура файлов

  • каждая служба живет в своем каталоге
  • имена каталогов в ВЕРХНЕМ регистре
  • все имена файлов в нижнем регистре
  • имя исполняемого файла службы должно заканчиваться на _srv.
  • имя службы должно быть в нижнем регистре и начинаться с ibis без "_srv" в конце. Например "ibis_sertificate"
  • имя исполняемого файла по управлению службой должно заканчиваться на _ctl
  • настройки службы должны храниться в ini файле рядом с исполнимыми файлами.
  • настройки подключения берутся из файла ibis.ini

Пример расположения служб 

IBIS_SRV
 ├─IBIS_SERTIFIATE
 │  ├──ibis_sertificate_srv.exe
 │  ├──ibis_sertificate_ctl.exe
 │  ├──ibis_sertificate.ini
 │  ├──ibis_sertificate.ini.example
 │  ├──ibis_sertificate_install.bat
 │  ├──ibis_sertificate_uninstall.bat
 │  ├──ibis_sertificate_update.bat
 │  ├──ibis.ini
 │  ├──readme.md
 │  └──LOG - Папка с логами
 └─IBIS_SPARM
    ├──ibis_sparm_srv.exe
    ├──ibis_sparm_ctl.exe
    ├──ibis.ini
    ├──ibis_sparm.ini
    ├──ibis_sparm.ini.example
    ├──ibis_sparm_install.bat
    ├──ibis_sparm_unistall.bat
    ├──ibis_sparm_update.bat
    ├──readme.md
    └──LOG

Именования файлов

  • _srv.exe сервис
  • _ctl.exe управляющая программ
  • _app.exe в виде отдельного приложения (на этапе разработки)
  • _install.bat скрипт для уснановки службы, как правило, содержит вызов _srv.exe с праметром /install
  • _uninstall.bat скрипт для удаления службы, как правило, содержит вызов _srv.exe с праметром /uninstall
  • _update.bat содержит параметры, неопходимые updater_console.exe, для обновления сервисов.

Все исполняемые файлы (*.exe) должны содержать актуальную информацию о версии (номер версии должен совпадать с номером ревизии SVN на котором этот exe собран)

Взаимодействие с postgresql

Аутентификация в БД

  • каждая служба должна работать под своим уникальным пользователем (для того чтобы можно было мониторить работу службы со стороны БД)
  • имя пользователя должно быть
    • большими буквами
    • совпадать с именем службы
    • начинаться на SRV (тут разница с KIS)

логин пароль храним в открытом виде в файле ini (<имя службы>.ini)

  • [Postgresql]
    • user
    • password
    • password_crypt

Требования к работоспособности при потере соединения

  • Служба должна корректно отрабатывать ошибки, связанные с потерей соединения с БД и пытаться восстановить соединение самостоятельность.

application_name в сессии postgresql

Любая сессия должна себя идентифицировать установив application_name в формате <имя файла> (версия). Например: 

 ibis_mqtt.exe (1.0.0.1)

Ниже пример кода: 

procedure TdmMain.conAfterConnect(Sender: TObject);
var
  S : String;
begin
  S := ExtractFileName(FSrvInfo.AppExe);
  S :=  S+  ' (' + FSrvInfo.FileVer + ')';
  con.ExecSQL('SET  application_name =  + S + '); // устанваливаем переменную application_name (pg_stat_activity)
end;

Размер work_mem

для сессии которая слушает pg_listen (и только для нее) нужно проставить

set session work_mem='64kB'

Зависимость от другого ПО

  • служба не должна зависеть от стороннего ПО, такого как
    • вебсерверы (IIS, Apache)
    • Net framework
    • клиент БД

Диагностика работы службы

  • служба должна писать информацию о событиях, в файл лога. Рекомендуется использовать QuickLogger https://github.com/exilon/QuickLogger или SynLog из библиотеки Synopse mORMot framework
  • файлы логов должны быть легко просматриваемы сторонними программами.
  • логов НЕ должно быть много. Т.е. НЕ должны забивать свободное место (должен происходить Rotate) и не должны сильно влиять на производительность дисковой подсистемы

WEB API

  • checkstatus - возвращает 1 в теле ответа, если сервис работает правильно
  • info - возвращает json, в котором есть настройки, текущий статус сервера (есть подключение к БД и т.п.)
  • stat - возвращает json со статистикой работы
  • showlog - показывает лог работы программы
  • admin - возвращает html страницу с настройками

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

Файл readme.md

В каталоге обязательно должен быть файл readme.md в формате markdown (для редактирования можно использовать Typora). Кодировка UTF-8. В нем должны быть следующие разделы:

  • Назначение
  • Описание работы
  • Состав (список файлов с описанием)
  • Установка
  • Настройка (что можно настроить в ini файлах, что можно настроить в adj)
  • Обновление
  • Мониторинг (проверка работоспособности, где и какие логи ведутся, как посмотреть какие ошибки возникали)

По правильному, содержимое файла markodown нужно продублировать на wiki (в typora есть экспорт)

Файлы-примеры конфигурационных файлов (ini.example)

Для каждого из возможных ini файлов должен лежать файл пример с расширением ini.example со всеми значениями по умолчанию и комментариями. Например для kis_mqtt.ini должен быть файл kis_mqtt.ini.example

Документация разработчика (readme_dev.md)

В исходных кодах в каталоге DOC должен быть файл readme_dev.md в формате markdown Что можно писать

  • структуры данных
  • особенности сборки
  • структура приложения (сервиса)

Публикация и распространение

на WEBDAV в папку LASTSRVFILES/<имя-службы_большими буквами> необходимо выложить два файла:

  • <имяслужбымаленькими>.7z
  • ver.ini

Состав файла 7z

  1. все необходимые для работы файлы
  2. ini-файлы с настройками по умолчанию (как правило это два файла)
  3. файл readme.md (см пункт "Документация")

Содержимое файла ver.ini

[Ver]

srv_ver=1.0.0.13

Автоматизация публикации

В папке CI (Continuous Integration) необходимо создать два файла:

  • 01_pack.bat - создает архив 7z
  • 02_webdav.bat публикует архив в папке на WEBDAV с помощью утилиты curl

Примеры скриптов можно брать из kisservices\trunk\kispg_rest\CI

Алгоритм публикации

  1. Изменяем в проекте номер версии, успешно компилим
  2. Правим файл ver.ini в папке bin
  3. Последовательно запускаем скрипты 01_pack.bat, 02_webdav.bat (смотрим в логи что все успешно)

Список сервисов

Источник — «http://mediawiki.oblteh/mediawiki/index.php?title=Службы_MIS3._Разработка&oldid=4666»