Версия 09:18, 2 июня 2021

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

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

Содержание

1 Общие требования
2 Публикация и распространение

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

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

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

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

KIS_SRV
 ├─KIS_MQTT
 │  ├──kis_mqtt_srv.exe
 │  ├──kis_mqtt_ctl.exe
 │  ├──kis.ini
 │  │  kis_mqtt.ini
 │  │  kis_mqtt.ini.example
 │  │  readme.md
 │  └──LOG - Папка с логами
 └─KIS_EHR_CONNECTOR
    ├──kis_ehr_connector_srv.exe
    ├──kis_ehr_connector_ctl.exe
    ├──kis.ini
    ├──kis_ehr_connector.ini
    ├──kis_ehr_connector.ini.example
    ├──readme.md
    └──LOG

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

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

Имя службы windows

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

kis_mqtt
kis_ehr_connector
kis_pg_rest
kis_supp
kis_simi_epic

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

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

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

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

[Postgresql]
- user
- password
- password_crypt

application_name в сессии postgresql

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

 kis_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, APACH)
- Net framework
- клиент БД

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

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

WEB API

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

GET /checkstatus

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

GET /info

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

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

GET /stat

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

Пример:

{
    "last10hour": [{
        "dt": "2019-02-04T08:20:00.000+03:00",
        "Count": 10
    },
    {
        "dt": "2019-02-04T08:21:00.000+03:00",
        "Count": 12
    },
    {
        "dt": "2019-02-04T08:22:00.000+03:00",
        "Count": 9
    }]
}

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\имя-службы_большими буквами> необходимо выложить два файла:

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

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

все необходимые для работы файлы
ini-файлы с настройками по умолчанию (как правило это два файла)
файл 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

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

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

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

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