Просмотр исходного текста страницы Службы KIS. Разработка

Этот файл продублирован на svn 

Для сервисов ИБИС есть похожий документ см [[Службы_MIS3._Разработка]]
= Общие требования  =

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

* каждая служба живет в своем каталоге
* имена каталогов в '''ВЕРХНЕМ''' регистре
* все имена файлов в '''нижнем''' регистре
* имя исполняемого файла службы должно заканчиваться на '''_srv'''
* имя службы должно начинаться с '''kis''' без "_srv" в конце!
* имя исполняемого файла по управлению службой должно заканчиваться на '''_ctl'''
* настройка подключения к БД должна храниться в файле kis.ini
* настройки службы должны храниться в &lt;имя''службы&gt;.ini файле рядом с исполнимыми файлами. см. [Конфигурационные файлы KIS](Конфигурационные''файлы_KIS &quot;wikilink&quot;)

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

<pre class="">KIS_SRV
 ├─KIS_MQTT
 │  ├──kis_mqtt_srv.exe
 │  ├──kis_mqtt_ctl.exe
 │  ├──kis.ini
 │  │  kis_mqtt.ini
 │  └──LOG - Папка с логами
 └─KIS_EHR_CONNECTOR
    ├──kis_ehr_connector_srv.exe
    ├──kis_ehr_connector_ctl.exe
    ├──kis.ini
    ├──kis_ehr_connector.ini
    └──LOG</pre>
Именования файлов

* _srv.exe севрис
* _ctl.exe управляющая программ
* _app.EXE в виде отдельного приложения (на этапе разработки)

== Имя службы windows  ==

Имя службы должно быть латинскими буквами в нижнем регистре (с подчеркиваниями) без "_srv" в конце. Примеры названий служб:

* kis_mqtt
* kis_ehr_connector 
* kis_pg_rest
* kis_supp
* kis_simi_epic

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

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

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

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

* [Postgresql]
** user
** password
** password_crypt

=== application_name в сессии postgresql  ===

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

  kis_mqtt.exe (1.0.0.1)

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

<source >
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;
</source>

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

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

=== Размер work_mem ===

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

set session work_mem='64kB'

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

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

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

* служба должна писать информацию о событиях в файл лога. Рекомендуется использовать SynLog из библиотеки Synopse mORMot framework
* файлы логов должны быть легко просматриваемы сторонними программами.

== WEB API  ==

Здесь описаны методы http, которые должна реализовать служба, чтобы можно было мониторить состояние службы. Эти методы будут вызвать сторонние приложения (админка kis_z, или другие сторонние программы) для отображения статуса работы службы

=== GET /checkstatus  ===

Метод возвращает 1 в теле ответа, если сервис работает правильно

=== GET /info ===

возвращает json, в котором есть настройки, текущий статус сервера (версия сервиса, есть подключение к БД и т.п.) Пример

<pre class=""> {&quot;FileVer&quot;: &quot;1.0.0.6&quot;,
    &quot;StartDT&quot;: &quot;2018-10-17T16:08:16.867+03:00&quot;,
    &quot;AppExe&quot;: &quot;C:\\KIS_SRV\\KIS_MQTT_SRV\\kis_mqtt_srv.exe&quot;,
    &quot;DBInfo&quot;: {
        &quot;ConnectStr&quot;: &quot;192.168.1.16:7432\/emiac1&quot;,
        &quot;ConnectStatus&quot;: &quot;connected&quot;,
        &quot;lastMessageRecivedDT&quot;: &quot;2019-02- 04T08:20:58.302+03:00&quot;,
        &quot;MeessageCount&quot;: 35024,
        &quot;ListenState&quot;: &quot;Active&quot;
    },
    &quot;MQTTInfo&quot;: {
        &quot;ConnectStr&quot;: &quot;192.168.1.16:1883&quot;,
        &quot;ConnectStatus&quot;: &quot;active&quot;,
        &quot;ClientID&quot;: &quot;V5nZpiOiintKZ1wgeg2K1f1&quot;,
        &quot;LastSendDT&quot;: &quot;2019-02-04T08:20:58.302+03:00&quot;,
        &quot;MessageCount&quot;: 35008   }</pre>
=== GET /stat  ===

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

Пример:

<pre class="">{
    &quot;last10hour&quot;: [{
        &quot;dt&quot;: &quot;2019-02-04T08:20:00.000+03:00&quot;,
        &quot;Count&quot;: 10
    },
    {
        &quot;dt&quot;: &quot;2019-02-04T08:21:00.000+03:00&quot;,
        &quot;Count&quot;: 12
    },
    {
        &quot;dt&quot;: &quot;2019-02-04T08:22:00.000+03:00&quot;,
        &quot;Count&quot;: 9
    }]
}</pre>
=== GET /showlog ===

Показывает лог работы программы

Обычная html страница, которая показывает файл лог, который лежит на сервере

Пример кода Delphi для вывода в ответе TIdHTTPResponseInfo файла лога в кодировке UTF8 содержащего Русскими символы:

 if AnsiUpperCase(leftStr(ARequestInfo.URI, 15)) = '/API/V1/SHOWLOG' then
  begin
    SL := TStringList.Create;
    uOTSynopseLog.TOTSynLog.Family.SynLog.Flush(True);
    // Даём команду и ожидаем закрытия LOG файла во всех потоках.
    uOTSynopseLog.TOTSynLog.Family.SynLog.CloseLogFile;
    // Считываем LOG файл. Пока он не будет считан другие потоки его не откроют
    SL.LoadFromFile(uOTSynopseLog.TOTSynLog.Family.SynLog.FileName, TEncoding.UTF8);
    AResponseInfo.ContentType := 'text/plain';
    AResponseInfo.CharSet := ''''utf-8'''';
    AResponseInfo.ContentText := SL.Text;
    SL.Free;
    exit;
  end;
 end;

=== GET /admin ===

Возвращает html страницу управления

=== GET /checkupdate  ===

Проверить наличие обновления (в БАЗЕ)

* если обновление не найдено, то возвращает пустую строку
* если обновление найдено, то возвращает версию обновления

=== GET /curversion  ===

возвращает строку, текущая версия сервиса

=== POST /update  ===

Обновиться

* проверить есть ли доставленное обнове в БД
* вызвать утилиту обновления для сервиса

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

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

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

Содержимое файла markodown нужно продублировать на wiki (в typora есть экспорт)
Также этот файл необходимо включать в состав дистрибутива

=== Документация разработчика ===

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

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

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

* &lt;имя''службы''маленькими&gt;.7z
* ver.ini

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

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

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



  [Ver]
  srv_ver=1.0.0.13

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

В папке 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]]
* [[KIS Certificate]]



[[Категория:Руководство программиста KIS]][[Категория:KIS сервисы]]