Frontend API Client

Appearance

Разработка пакета ​

Клонирование и установка ​

bash
git clone https://gitlab.com/diealltagsfeen/frontend.npm.serviceslibrary.git
cd frontend.npm.serviceslibrary
npm install

Токены для работы с реестром уже прописаны в .npmrc репозитория — дополнительная настройка не требуется.

Структура проекта ​

Пакет полностью на TypeScript. Барель-файлов нет — src/index.ts перечисляет экспорты явно, по одному символу из своего файла.

src/
├── config.ts          # init() и доступ к зависимостям (axios, hosts, колбэки)
├── index.ts           # Главный экспорт (явный перечень re-export'ов)
├── http/              # HTTP-клиент и типы результата (http, ApiResult, ApiError, ...)
├── services/          # API-сервисы (clientService, workerService и т.д.)
└── dto/               # DTO по доменам (client/, worker/, common/, ...) — типы запросов и ответов

Git-воркфлоу ​

Ветвление ​

  • master — стабильная ветка для релизов
  • develop — основная ветка разработки
  • feature/* — фичевые ветки, создаются от develop

Внесение изменений ​

  1. Создайте ветку от develop:
    bash
    git checkout develop
git pull
git checkout -b feature/DIE-XXXX
  2. Внесите правки
  3. Закоммитьте и запушьте:
    bash
    git add .
git commit -m "DIE-XXXX - Описание изменений"
git push -u origin feature/DIE-XXXX
  4. Создайте Merge Request в develop через GitLab

Добавление нового сервиса ​

За образец берите любой существующий сервис в src/services/ (например clientService.ts). Кратко:

  1. Создайте файл src/services/myService.ts. Сервис — тонкая обёртка над http, метод возвращает ApiResult<T>:

    ts
    /** @module myService */
import type { ApiResult } from '../http/ApiResult'
import { http } from '../http/httpClient'
import type { CreateMyEntityRequestDto } from '../dto/myEntity/CreateMyEntityRequestDto'

/** @alias module:myService */
class MyService {
  /** Получает список сущностей с пагинацией и фильтрами */
  async GetTable(queryString: string): Promise<ApiResult> {
    return await http.get('business', `Api/MyEntity?${queryString}`)
  }

  /** Создаёт новую сущность */
  async Create(body: CreateMyEntityRequestDto): Promise<ApiResult> {
    return await http.post('business', 'Api/MyEntity', body)
  }
}

export const myService = new MyService()

  2. Добавьте явный реэкспорт в src/index.ts:

    ts
    export * from './services/myService'

Добавление DTO ​

  1. Создайте файл src/dto/<домен>/MyTypeDto.ts с interface / enum и JSDoc к полям.
  2. Добавьте явный реэкспорт в src/index.ts (export * from './dto/<домен>/MyTypeDto').

Сборка ​

bash
npm run build

Скрипт build последовательно запускает lint, typecheck и vite build. Vite собирает src/index.ts в единый ES-модуль dist/index.js и генерирует типы (dist/src/index.d.ts). Зависимость axios не бандлится — указана как external.

Релиз новой версии ​

После мержа изменений в develop, публикация выполняется одной командой:

bash
npm run release:patch   # баг-фиксы      (1.1.0 → 1.1.1)
npm run release:minor   # новый функционал (1.1.0 → 1.2.0)
npm run release:major   # ломающие изменения (1.0.0 → 2.0.0)

Команда автоматически:

  1. Соберёт пакет (npm run build)
  2. Обновит версию в package.json и создаст git-коммит с тегом
  3. Опубликует пакет в реестр (npm publish)
  4. Запушит коммит и тег в репозиторий

Токен для публикации

Для публикации необходим токен с правами на запись. Этот токен создаёт и выдаёт по запросу Owner репозитория. Самостоятельно создать его нельзя.

Обновление пакета в проектах-потребителях ​

После публикации новой версии:

bash
npm update @diealltagsfeen/frontend-api-client

Или конкретная версия:

bash
npm install @diealltagsfeen/frontend-api-client@1.2.0

Локальная разработка с проектом-потребителем ​

Для тестирования изменений без публикации можно использовать npm link или настроить alias в quasar.config.js проекта-потребителя (см. скилл api_service_dev).