JSPM

ngx-api-manager

0.2.8
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 2
  • Score
    100M100P100Q33400F
  • License MIT

Module for configuration http requests

Package Exports

  • ngx-api-manager

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ngx-api-manager) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ngx-api-manager

Installation

To install this library, run:

$ npm install ngx-api-manager --save

Для чего?

  1. Эмитит событие загрузки с указанием "точки вызова api". Вы имеете единый поток http ошибок.
  2. Совершает прерывание запроса по истчению таймаута.
  3. Эмит событий ошибки и обработка ошибок по умолчанию.
  4. Автоматически устанавливает токен и заголовки. Все повторяющиеся операции автоматизированы.
  5. Контролирует работу с api предотвращая обращения к несуществующим url. Проверка существования роута используя типы.

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

Один домент = один конфигурационный файл.

Подлючение

При подключении модуля Api обязательно указывается список конфигураций с которыми будет происходить работа.

@NgModule({
  imports: [
    ApiModule.forRoot({
      configs: [new ApiConfig('main'), new ApiCkcConfig('ckc')]
    }),
  ],
  declarations: [],
  exports: []
})
export class PagesModule { }

Использование

Работа с http сервером начинается с изучения документации в которой описаны все возможные роуты. Примером такой документации сервера может служить swagger документация. ApiConfig описывает список всех возможных роутов в соответсвии с сервеной документацией используя синтаксис класса.

1. Добавить в конфигурацию требуемые роуты

Допустим сервер предоставляет роуты для работы с двумя видами сущьностей -> Users и Apples и стандартные CRUD операции.

User:
  find
  create
  update
  delete
Apple:
  find
  create
  update
  delete

В таком случае конфигурация на фронтенд будет выглядеть следующим образом:

class ApiConfig {
  baseUrl: string = 'base url';

  get user {
    return {
      find: '${baseUrl}/User',
      create: '${baseUrl}/User',
      update: '${baseUrl}/User',
      delete: '${baseUrl}/User'
    };
  }

  get apple {
    return {
      find: '${baseUrl}/Apple',
      create: '${baseUrl}/Apple',
      update: '${baseUrl}/Apple',
      delete: '${baseUrl}/Apple'
    };
  }
}

Таким образом конфигурация на фронтэнд выглядит и упорядочена так же как и документация предоставленная бэкэндом, что удобно для поиска.

Url с динамическим параметром в середине url

Допустим существует url на удаление пользователя с динамическим параметром userID в середине ссылки /v1/User/${userID}/cancel. В таком случае в конфигурации используется стрелочная функция:

class ApiConfig {

  get user {
    return {
      find: '${baseUrl}/User',
      cancel: (userID: string) => {
        return `${this.baseUrl}/v1/User/${userID}/cancel`;
      }
    };
  }
}

2. Сконфигурировать http запрос

Конфигурирование запроса происходит в два шага: выбор рабочей конфигурации и установка параметров запроса.

this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'get',
    url: config.device.all,
    requestPoint: 'devices'
  }));

Передача generic типа в функцию useConfig обязательна для контролирования обращения к несуществующим url.

Фунция request принимает callback возвращающий объект с конфигурацией http запроса.

Объект конфигураци

Обязательные значения:

  1. method
  2. url
  3. requestPoint - строка в которой указано откуда был вызван http запрос и по которой можно отфильтровать нужные значения из потока ошибок и загрузок.

Остальные значения:

  1. param - подставляется в конце url. ${this.baseUrl}/User/{param}, например id пользователя.
  2. paramsArray - массив get параметров. [{key: 'value', val: 'value'}]
  3. body - тело запроса.
  4. timeout - кастомизирует значение задержки для конкретного запроса. иначе берется из конфигурации.

3. Выполнить запрос

Для выполнения запроса нужно вызвать специальный метод promise<T>() с указанием типа возвращаемых данных.

this.api
  .useConfig<ApiCkcConfig>('ckc')
  .request(config => ({
    method: 'get',
    url: config.device.all,
    requestPoint: 'devices'
  }))
  .promise<Array<Device>>();
Получение всех пользователей GET

В subject указываем сущьность к которой мы обращаемся. В just указываем тип CRUD операции.

this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'get',
    url: config.user.find,
    requestPoint: 'userComponent'
  }))
  .promise<Array<User>>();

// обратится к class ApiConfig (когда произойдет вызов запроса) у которого есть свойство user хранящее объект со ссылками
class ApiConfig {
  ...
    get user {
      return {
        find: '${baseUrl}/User',
        create: '${baseUrl}/User',
        update: '${baseUrl}/User',
        delete: '${baseUrl}/User'
      };
    }
  ...
}
Получение всех пользователей с лимитом не более 10 limit=10 GET

В subject указываем сущьность к которой мы обращаемся. В just указываем тип CRUD операции. Для передачи списка get параметров используется paramsArray

// '${baseUrl}/User?limit=10'
this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'get',
    url: config.user.find,
    requestPoint: 'userComponent',
    paramsArray: [{key: 'limit', val: '10'}]
  }))
  .promise<Array<User>>();
Получение пользователя по id GET

Для установки значение id в конце url используется специальный параметр param.

// получение пользователя с id = 2
// '${baseUrl}/User/2
this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'get',
    url: config.user.find,
    requestPoint: 'userComponent',
    param: 2
  }))
  .promise<User>();

Редактирование пользователя PUTCH

Для редактирования пользователя понадобится передать тело запроса body, id пользователя id и указать метод putch

this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'putch',
    url: config.user.update,
    requestPoint: 'userComponent',
    param: 2,
    body: {
      name: 'new Name'
    }
  }))
  .promise<User>();

Выполнение http запроса

После конфигурации запроса не происходит реального запроса по сети. Для этого есть два варианта использования.

let editUserRequest = this.api
  .useConfig<ApiConfig>('main')
  .request(config => ({
    method: 'putch',
    url: config.user.update,
    requestPoint: 'userComponent',
    param: 2,
    body: {
      name: 'new Name'
    }
  }))
  .promise<User>();

let putchUser = async () => {
  let putchedUser = await editUserRequest.promise();
};
  1. Преобразовать запрос к Promise -> editUserRequest.promise().
  2. Преобразовать запрос к потоку RxStream -> editUserRequest.stream().

После преобразования к Promise произойдет реальный http запрос.

В случае с преобразованием к потоку RxStream запрос произойдет лишь в момент когда кто либо подпишется на данный поток.

Обработка событий загрузки

Перед отправкой запроса по сети генерируется событие загрузки на потоке loading сервис LoadingService. По завершению запроса с ошибкой или без нее генерируется событие завершения загрузки.

Подключиться к потоку loading -> loadingService.loadingStream$;

class SomeClass {
  constructor(
    private loading: LoadingService // Подключаем сервис загрузок
  ) {
    this.loading.loadingStream$ // поток событий згрузки
  }
}

Для реакции (обработки) на данные события любой компонент может подписаться на события загрузки и отфитровать только нужные ему события начала и окончания загрузки. Фильтрация происходи благодаря указанию в момент конфигурирования запроса специального параметра requestPoint: "userComponent".

В типом данных отправляемых в поток является action -> {state: true, requestPoint: 'some reuest point name'}

import { Component, ViewChild } from '@angular/core';

import { LoadingService } from './loading.service';

@Component({
  selector: 'loading-component',
  templateUrl: 'loading.component.html'
})
export class LoadingComponent implements LoadingComponent {
  @ViewChild('staticModal')
  modal;

  isLoading: boolean = false;

  constructor(
    private loading: LoadingService // Подключаем сервис загрузок
  ) {
    this.loading
      .loadingStream$
      .filter(action => action.requestPoint === "userComponent")
      .subscribe((action) => {
        // обработать событие загрузки для компонента по точке запроса (requestPoint)
        // не используйте патерн с подпиской subscribe
        switch (action.state) {
          case true:
            return this.onStartLoading();
          case false:
            return this.onEndLoading();
        }
      });
  }

  onStartLoading() {
    this.isLoading = true;
    this.modal.show();
  }

  onEndLoading() {
    this.isLoading = false;
    this.modal.hide();
  }
}

Обработка потока ошибок

В случае возникновения ошибки http запроса генерируется событие на потоке error сервис ErrorsService. Предусмотрена автоматическая обработка ошибок с выводом уведомлений пользователю в случае ошибоки сервера error.status >= 500.

Подключиться к потоку error -> errorsService.errorsStream$;

В случае возникновения ошибки http запроса автоматически генерируется событие завершения загрузки для данной точки запроса.

import { Injectable } from '@angular/core';
import { Subject }    from 'rxjs/Subject';

import { enMsgs } from './errorsMessages/en';

import { LoadingService } from '../loading/loading.service';

@Injectable()
export class ErrorsService {
  private errorSource = new Subject<{error: ErrorObj, errorPoint: string}>();

  errorsStream$ = this.errorSource.asObservable();

  constructor(
    private loading: LoadingService
  ) {}

  emitError(error: ErrorObj, errorPoint) {
    this.loading.emitLoading({state: false, requestPoint: errorPoint});
    this.errorSource.next({error, errorPoint});
  }

  defaultProcessing(e, errorPoint) {
    switch (e.status) {
      case 0:
        return this.emitError(new DisconnectedError(enMsgs['0'], e), errorPoint);
      case 400:
        return this.emitError(new ClientError(enMsgs['400'], e), errorPoint);
      case 401:
      // ... и так далее
    }

    return this.emitError(new UnusualError(enMsgs['unusual'], e), errorPoint);
  }
}

Для реакции (обработки) на события ошибко любой компонент может подписаться на поток ошибок и отфильтровать только нужные ошибки используя специальный параметр указанные в момент конфигурирования запроса requestPoint: "userComponent". В поток ошибок данный параметр приходит под именем errorPoint

В типом данных отправляемых в поток является action -> {error: errorObject, errorPoint: 'some reuest point name'}

import { Component, ViewChild } from '@angular/core';

import { ErrorsService } from './errors.service';

@Component({
  selector: 'errors-component',
  templateUrl: 'errors.component.html',
})
export class ErrorsComponent {
  showLog: boolean = false;
  newError: any = {};
  cause: any = {};

  @ViewChild('staticModal')
  modal;

  constructor(
    private errorsService: ErrorsService
  ) {
    this.errorsService
      .errorsStream$
      .filter(action => action.errorPoint === "userComponent")
      .subscribe((error) => {
        // какая либо обработка ошибки
      });
  }
  ...
}

Итого

  1. Добавление новых ссылок к api происходит в api.config и любом другом конфиге
  2. Метод request().stream() из api.service возвращает только наблюдаемый объект Observable
  3. Внешний код занимается обработкой ошибок, например код сервиса для конкретного компонента.

License

MIT © Mike T.