@orbitsoft/json-api-store
    TypeScript icon, indicating that this package has built-in type declarations

    4.2.0 • Public • Published

    JSON API STORE

    Описание

    Данная библиотека поможет вам сделать работу с вашим JSON API легкой и удобной. Библиотека ориентирована на использования в приложениях написанных с использованием AngularJS, но при необходимости может быть достаточно легко адаптирована для использования с другими framework'ами.

    Установка

    Для установки библиотеки вам необходимо использовать наш локальный NPM резпозиторий. Для этого в домашней директории вашего пользователя или в директории проекта создайте файл .npmrc со следующим содержимым:

    registry = http://npm.orbita1.ru:4873
    always-auth=true
    

    После этого вам необходимо добавить библиотеку в зависимости вашего проекта:

    yarn add @orbit/json-api-store
    

    Работа с библиотекой

    Подключение к приложению

    Для начала нам необходимо импортировать модуль JsonApiModule в основной модуль нашего приложения. Модуль JsonApiModule использует HttpModule, поэтому модуль HttpModule должен быть импортирован первым:

    import { BrowserModule } from '@angular/platform-browser';
    import { NgModule } from '@angular/core';
    import { HttpClientModule } from '@angular/common/http';
    import { JsonApiModule } from '@orbit/json-api-store';
    
    import { AppComponent } from './app.component';
    
    @NgModule({
      declarations: [
        AppComponent
      ],
      imports: [
        BrowserModule,
        HttpClientModule,
        JsonApiModule.forRoot('http://localhost:4200/api')
      ],
      providers: [],
      bootstrap: [AppComponent]
    })
    export class AppModule { }

    Как видно из примера, при импорте JsonApiModule в основной модуль вашего приложения необходимо использовать метод JsonApiModule.forRoot() и указать базовый URL вашего JSON API.

    При необходимости, JsonApiModule может быть импортирован и в другие модули вашего приложения. Однако при этом не нужно использовать метод JsonApiModule.forRoot():

    import { NgModule } from '@angular/core';
    import { JsonApiModule } from '@orbit/json-api-store';
    
    import { ContactsComponent } from './contacts.component';
    
    @NgModule({
      declarations: [
        ContactsComponent
      ],
      imports: [
        JsonApiModule
      ],
      providers: [],
      bootstrap: [ContactsComponent]
    })
    export class ContactsModule { }

    Описание моделей

    Для работы с JsonApiStore необходимо описать модели. Модель - это plain typescript object, который представляют сущностость предметной области вашего приложения. При этом класс описывающий модель должен поддерживать интерфейс Resource, т.е. иметь свойство id, в котором будет храниться строковый уникальный идентификатор ресурса JSON API. Для удобства мы добавили класс JsonApiResource, который вы можете использовать в качестве родительского класса ваших моделей.

    Для примера опишем модель, которая представляет пользователя приложения:

    import { JsonApiResource } from '@orbit/json-api-store';
    import { Office } from './office.model';
    import { UserRole } from './user-role.model';
    
    export class User extends JsonApiResource {
      /**
      * Имя 
      */
      name: string;
    
      /**
      * Электронный адрес 
      */
      email: string;
    
      /**
      * Оффис, в котором работает пользователь 
      */
      office: Office;
    
      /**
      * Список ролей пользователя 
      */
      roles: UserRole[];
    }

    Для того чтобы JsonApiStore смог работать с нашими моделями, нам необходимо добавить специальные декораторы к классу и его свойствам.

    В первую очередь к самому классу User нам необходимо добавить декоратор @Model(). При этом мы должны указать тип ресурса JSON API, который соответствует нашей модели:

    import { JsonApiResource, Model } from '@orbit/json-api-store';
    
    @Model({type: 'users'})
    export class User extends JsonApiResource {
      
    }

    После этого нам необходимо добавить соответствующие декораторы к свойствам нашего класса.

    Для свойств, которые соответствуют атрибутам JSON API ресурса, необходимо добавить декоратор @Attribute():

    import { JsonApiResource, Model, Attribute } from '@orbit/json-api-store';
    import { Office } from './office.model';
    import { UserRole } from './user-role.model';
    
    @Model({type: 'users'})
    export class User extends JsonApiResource {
      
      @Attribute()
      name: string;
    
      @Attribute()
      email: string;
    }

    Для свойств, которые соответствуют внешним связям JSON API ресурса, необходимо добавить декоратор @Relationship() и указать модель, которая соответствует :

    import { Attribute, JsonApiResource, Model, Relationship } from '@orbit/json-api-store';
    import { Office } from './office.model';
    import { UserRole } from './user-role.model';
    
    @Model({type: 'users'})
    export class User extends JsonApiResource {
    
      @Relationship({resource: Office})
      office: Office;
    
      @Relationship({resource: UserRole, isArray: true})
      roles: UserRole[];
    }

    Для свойств, которым соответсвует связь "один-ко-многим", нам необходимо выставить значение параметра isArray в true. В нашем примере таким свойством является свойство roles, поскольку пользователь может иметь сразу несколько ролей.

    После того как мы описали модель User, нам также необходимо добавить модели Office и UserRole:

    import { Attribute, JsonApiResource, Model } from '@orbit/json-api-store';
    
    @Model({type: 'offices'})
    export class Office extends JsonApiResource {
    
      @Attribute()
      title: string;
    }
    
    @Model({type: 'user-roles'})
    export class UserRole extends JsonApiResource {
    
      @Attribute()
      role: string;
    
      @Attribute()
      status: string;
    }

    Реализация сервиса для взаимодействия с backend'ом

    После того как мы описали модели, используемые в нашем приложении, мы может использовать JsonApiStore для отправки запросов нашему backend'у. Обычно все методы работы с каким либо типом ресурсов групируются в одном сервисе и затем этот сервис используется компонентами приложения.

    Давайте реализуем UserService, который позволит нам управлять пользователями нашего приложения:

    import { JsonApiStore } from '@orbit/json-api-store';
    import { Injectable } from '@angular/core';
    
    @Injectable()
    export class UserService {
    
      constructor(private store: JsonApiStore) {};
    }

    Используя механизмы dependency injection, предоставляемые AngularJS, мы внедрили JsonApiStore в наш сервис. После этого мы может реализовывать различные методы нашего сервиса, которые позволят нам выполнять те или иные действия с нашими пользователя.

    Начнем с метода, который позволит получить список пользователей, которые соответствуют заданным критериям:

    import { JsonApiDocument, JsonApiStore } from '@orbit/json-api-store';
    import { Injectable } from '@angular/core';
    import { Observable } from 'rxjs/Observable';
    
    import { User } from '../models/user.model';
    
    @Injectable()
    export class UserService {
    
      getList(params?: any): Observable<JsonApiDocument<User[]>> {
        return this.store.getList(User, params);
      }
    
    }

    Для получения списка пользователей мы используем метод JsonApiStore.getList(). Этот метод отправит GET-запрос нашему JSON API (GET http://localhost:4200/api/users) и вернет JsonApiDocument, содержащий ответ полученный от сервера.

    Далее давайте добавим метод, который позволит нам получить информацию о заданном пользователе:

    import { JsonApiDocument, JsonApiStore } from '@orbit/json-api-store';
    import { Injectable } from '@angular/core';
    import { Observable } from 'rxjs/Observable';
    
    import { User } from '../models/user.model';
    
    @Injectable()
    export class UserService {
    
      get(id: string, params?: any): Observable<JsonApiDocument<User>> {
        return this.store.get(User, id, params);
      }
    
    }

    Для получения информации о конкретном пользователе мы используем метод JsonApiStore.get(). Этот метод отправит GET-запрос (GET http://localhost:4200/api/users/123) и вернет ответ сервера в виде объекта JsonApiDocument.

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

    import { JsonApiDocument, JsonApiStore } from '@orbit/json-api-store';
    import { Injectable } from '@angular/core';
    import { Observable } from 'rxjs/Observable';
    
    import { User } from '../models/user.model';
    
    @Injectable()
    export class UserService {
    
      save(users: User, params?: any): Observable<JsonApiDocument<User>> {
        return this.store.save(users, params);
      }
    
    }

    Здесь мы используем метод JsonApiStore.save(). Если в качестве параметра users передан новый пользователь, JsonApiStore отправит POST-запрос (POST http://localhost:4200/users). В случае если пользователь уже существует, JsonApiStore отправит PATCH-запрос (PATCH http://localhost:4200/api/users/123). В обоих случаях JsonApiStore вернет ответ сервера в виде объекта JsonApiDocument.

    Далее нам осталось реализовать метод, который позволит удалять пользователей:

    import { JsonApiDocument, JsonApiStore } from '@orbit/json-api-store';
    import { Injectable } from '@angular/core';
    import { Observable } from 'rxjs/Observable';
    
    import { User } from '../models/user.model';
    
    @Injectable()
    export class UserService {
    
      remove(user: User, params?: any): Observable<JsonApiDocument<User>> {
        return this.store.remove(user, params);
      }
      
    }

    Для удаления записей мы используем метод JsonApiStore.remove(), который отправит DELETE-запрос (DELETE http://localhost:4200/api/users/123) нашему API и вернет ответ сервера в виде JsonApiDocument

    Keywords

    none

    Install

    npm i @orbitsoft/json-api-store

    DownloadsWeekly Downloads

    2

    Version

    4.2.0

    License

    UNLICENSED

    Unpacked Size

    141 kB

    Total Files

    190

    Last publish

    Collaborators

    • maxix
    • reva2work