@ngrx/data 进阶之路

JiaLiPassion @ngChina2019

自我介绍

李嘉
公司: ThisDot
Zone.js: Code Owner
Angular: Collaborator
@JiaLiPassion

我经历的一个真实的项目

Step1: 传统的Angular

代码示例

// Container Service
@Injectable()
export class ContainerService {
  constructor(private http: HttpClient) {}

  getAllContainers() {
    return this.http.get('http://service/containers');
  }
}

// Container Component
export class ContainerComponent implements OnInit {
  containers$: Observable<Container[]>;

  constructor(private containerService: ContainerService) {}

  ngOnInit() {
    this.containers$ = this.containerService.getAll();
  }
}

新的需求

Text

可以编辑Image状态

新的需求

Filter可以联动URL

filter

新的需求

支持乐观更新

状态管理

状态

服务器端状态
客户端状态
- 持久状态
- URL/Routing 状态
- 客户端状态
- 临时状态
- UI状态

状态之间关系

服务器状态

持久状态

客户端状态

URL状态

临时状态

UI状态

持久状态同步

class DashboardComponent {
  starChangedInRecentUpdatedComp(starredContainer) {
    updateStarInMostStarredComp(starredContainer);
  } 
  
  starChangedInMostStarredComp(starredContainer) {
    updateStarInRecentUpdatedComp(starredContainer);
  }
}

class MostStarredComponent {
  @Output() starredComponentUpdated = new EventEmitter<Container>();
  
  starChanged(container) { this.starredComponentUpdated.emit(container); }
  
  updateStarInMostStarredComp(starredContainer) { // update local data }
}

class RecentUpdatedComponent {
  ...
}

持久状态同步+

// use a starred service as a bridge
export class StarredService {
  starredContainer$ = new BehaviorSubject(null);
  starContainer(container: Container) {
    this.starredContainer$.next(container);
  }
}

export class RecentUpdatedComponent {
  ngOnInit() {
    this.containers$ = combineLatest(
      this.starredService.starredContainer$,
      this.containerService.getLatestContainers()).
        pipe([starredContainer, latestContainers] => {...})
  }
} 

// MostStarredComponent
export class ContainerComponent {
  ngOnInit() { this.containers$ = combineLatest(...)}
}

越来越多的同步需求

Starred

Download Count

Description

Version/Tag Children

Service成了瓶颈

Starred

Service

DownloadCountService

Description

Service

Version/Tag ChildrenService

A Big

ContainerBridgeService

问题

业务逻辑和状态管理混在一起
Command和Query混在一起
各个状态之间的同步没有很好地机制,解决方案治标不治本
- 持久状态和服务器的状态
- 持久状态之间
- 客户端状态和服务器状态和URL状态
- ...
数据是Mutable 可变的
各个Component同时更新的处理变得非常复杂

状态管理库ngrx?

NgRx

唯一数据来源Store
数据只读更好的性能
Pure Function便于测试
Command和Query分开,程序便于维护

持久状态同步

RecentUpdated

Component

MostStarred

Component

Store

Selector

好多层....

试着实现一个getAll

Actions

export const GET_ALL = '[Container] query-all';
export const GET_ALL_SUCCESS = '[Container] query-all/success';
export const GET_ALL_FAILED = '[Container] query-all/failed';

export class GetAll implements Action {
  readonly type = GET_ALL;
}

export class GetAllSuccess implements Action {
  readonly type = GET_ALL_SUCCESS;
  constructor(public payload: string[]) {}
}

export class GetAllFailed implements Action {
  readonly type = GET_ALL_FAILED;
  constructor(public payload: string[]) {}
}

Reducer

export interface ContainerState {
  containers: Container[];
  filter: string;
}

export const initialState = {
  containers: [],
  filter: null
}

export function containerReducer(state: ContainerState = initialState,
                                 action: ContainerActionTypes) {
  switch(action.type) {
    case GET_ALL_SUCCESS:
      return { ...state, containers: [...action.payload] };
    default:
      return state;
  }
}

Effects

export class ContainerEffects {
    constructor(
        private store: Store<any>,
        private actions$: Actions,
        private containerDataService: ContainerDataService
    ) {}

    createEffect(() => this.actions$.pipe(
      ofType(GET_ALL),
      mergeMap(() => this.containerDataService.getAll()
        .pipe(
          map(containers => {return new GetAllSuccess(containers); }),
          catchError(() => { return new GetAllFailed(); })
        ))
     ));
  }

DataService

class ContainerDataService {
  getAll() {
    return this.httpClient.post(...);
  }
}

Selector

export const selectAllContainers = 
    (state: ContainerState) => state.containers;

ngrx 构成

10 个业务对象

5~10种Actions

好多"Boilerplate"代码

Debug对于初学者不友好

class ContainerComponent {
  ngOnInit() {
    this.store.dispatch(new GetAll());
    this.containers$ = this.store.pipe(getAllSelector);
  }
}

@ngrx/data

Zero Ngrx Boilerplate

你不需要再去实现Actions, Reduers, Effects, DataServices, Selectors.

@ngrx/data

实现了对于CRUD 操作
支持检索和排序
支持加载中和已经加载
内置错误处理
支持乐观更新(支持回滚/重试)
支持所有@ngrx/entity的功能
支持所有ngrx的功能

意识不到在使用ngrx

EntityCollectionService

export class ContainerService 
       extends EntityCollectionServiceBase {
  getAll();
  add();
  update();
  delete();
  upsert();
  
  entities$;
  filteredEntities$;
  loading$;
  loaded$;
  ...
}

entity metadata

// define metadata
export const entityMetadata: EntityMetadataMap = {
  Container: {}
};

// provide a facade service
export class ContainerService extends EntityCollectionServiceBase<Container> {
  constructor(serviceElementsFactory: EntityCollectionServiceElementsFactory) {
    super('Container', serviceElementsFactory);
  }
}

getAll

// call facade from component
export class ContainerComponent {
  ngOnInit() {
    // dispatch action
    this.containerService.getAll();
    // selector to get all entities
    this.containers$ = this.containerService.entities$;
  }
}

getAll

// dispatch action
this.containerService.getAll();
// selector to get all entities
this.containers$ = this.containerService.entities$;

ngrx/data architecture

CRUD

export class ContainersComponent implements OnInit {
  add() {
    this.containerService.add({name: 'centos'});
  }

  delete() {
    this.containerService.delete(1);
  }

  update() {
    this.containerService.update({id: 1, name: 'ubuntu:18.03'});
  }


  getById(id: number) {
    this.containerService.getByKey(id);
  }

}

CRUD

Flow: getAll

Action/HttpRequest的默认规则

Operation	action.type	http request url
getAll	[Container] @ngrx/data/query-all	GET api/containers
add	[Container] @ngrx/data/save/add-one	POST api/containers
update	[Container] @ngrx/data/save/update-one	PUT api/containers
delete	[Container] @ngrx/data/save/delete-one	DELETE api/containers
getByKey	[Container] @ngrx/data/query-by-key	GET api/containers/${key}
getWithQuery	[Container] @ngrx/data/query-many	GET api/containers?query

@ngrx/entity

{ 
  entityCache: {   
    Container: {
      ids: [
        1,
        2,
        3,
        4
      ],
      entities: {
        '1': {
          id: 1,
          name: 'ubuntu'
        },
        '2': {
          id: 2,
          name: 'alpine'
        }
      }
    }
  }
}

@ngrx/entity的好处

Containers: [
  {
    id: 1,
    name: 'ubuntu'
  },
  {
    id: 2,
    name: 'alpine'
  }
]

Containers: {
  ids: [1, 2],
  entities: {
    1: {
      id: 1,
      name: 'ubuntu' 
    },
    2: {
      id: 2,
      name: 'alpine'
    }
  }
}

@ngrx/entity提供的EntityAdpter

内建CRUD方法支持数据转换成需要的格式
提供了基础的Selectors
提供了可供定制的idSelector和sortComparer

ngrx/data -> ngrx/entity

Filter

// define a filter function and register it to entityMetadata

export function containerNameFilterFn(
  containers: ContainerUIModel[],
  pattern: string) {
  return PropsFilterFnFactory(['name'])(containers, pattern);
}

export const entityMetadata: EntityMetadataMap = {
  Container: {
    filterFn: containerNameFilterFn
  }
}

// Containers Component
export class ContainersComponent {
  this.filteredContainers$ = this.containerService.filteredEntities$;
}

Sort

// define a compare function and register it to entityMetadata

export const entityMetadata: EntityMetadataMap = {
  Container: {
    sortComparer: (c1: Container, c2: Container) => c1.id - c2.id
  }
}

// Containers Component
export class ContainersComponent {
  this.containers$ = this.containerService.entities$;
}

idSelector

// define a idSelector function and register it to entityMetadata

export const entityMetadata: EntityMetadataMap = {
  Container: {
    selectId: (c: Container) => c1.fingerprint
  }
}

Loading

// Containers Component
export class ContainersComponent {
  this.loading$ = this.containerService.loading$;
} 

// Containers Component template
<ng-container *ngIf="loading$ | async; else containers_tpl">
  Loading...
</ng-container>

Demo: Filter/Sort/Loading

乐观更新

单独的流程处理先更新客户端持久状态，再更新服务器状态
要做错误处理，当有错误的时候能够支持回滚或者重试
为了支持回滚和重试，本地还需要存储变更的内容(ChangeSet)
回滚时候也要考虑其他操作是否已经更改了数据

使用@ngrx/data实现乐观更新

export const entityMetadata: EntityMetadataMap = {
  Container: {
    entityDispatcherOptions: {
      optimisticAdd: false,
      optimisticUpdate: true,
      optimisticDelete: true
    }
  }
};

ChangeState

changeState: {
  '2': {
    changeType: 3,
    originalValue: {
      id: 2, 
      name: 'alpine'
    }
  }
}

错误处理

@Injectable({ providedIn: 'root' })
export class ErrorService {
  constructor(private actions$: Actions) {
    actions$
      .pipe(
        ofEntityOp(),
        filter(
          (ea: EntityAction) =>
          ea.payload.entityOp.endsWith(OP_ERROR)
        )
      )
      // this service never dies so no need to unsubscribe
      .subscribe(action => {
        if (action.payload.entityOp.endsWith(OP_ERROR)) {
          this.containerService.createAndDispatch(EntityOp.UNDO_ALL);
        }
      });
  }
}

Demo: Update

完美！！！

看来不需要学习太多ngrx的知识也不用写各种ngrx的bolierplate就可以得到所有ngrx的好处

但是.....

定制Http Request的规则

// create a customize http url generator
@Injectable({providedIn: 'root'})
export class CustomizeHttpUrlGenerator extends DefaultHttpUrlGenerator {
  protected getResourceUrls(
    entityName: string,
    root: string
  ): HttpResourceUrls {
    const urls = super.getResourceUrls(entityName, root);
    urls.entityResourceUrl = urls.collectionResourceUrl;
    return urls;
  }
}

// app.module.ts, then register to providers
{
  provide: HttpUrlGenerator,
  useClass: CustomizeHttpUrlGenerator
}

服务器和客户端的数据结构不一致，需要Mapping

// customize
@Injectable({ providedIn: 'root' })
export class CustomizeDataService extends DefaultDataService<Container> {
  constructor(http: HttpClient, httpUrlGenerator: HttpUrlGenerator, logger: Logger) {
    super('Container', http, httpUrlGenerator);
  }
  getAll(): Observable<Container[]> {
    return super.getAll().pipe(
      map(containers =>
        containers.map(c => ({...c, fullName: c.name + c.tag)}))
      )
    );
  }
}

分页处理

entityCache: {
  Container: {
    ids: [],
    entities: {},
    entityName: 'Container',
    filter: '',
    loaded: true,
    loading: false,
    changeState: {}
  }
}

// entity metadata.ts

export const entityMetadata: EntityMetadataMap = {
  Container: {
    additionalCollectionState: {
      page: {//...      }
    },
  }
};

不知道该如何用@ngrx/data来实现

最终

重头系统学习ngrx
学习@ngrx/data的文档和源代码

@ngrx/data扩展点

定制@ngrx/data默认提供的行为
- 定制 EntityCollectionService
- 定制 EntityAction/Dispatcher
- 增加属性到 EntityCollection
- 定制 DataService
- 定制存储时候合并的策略
- 定制 http url 规则
- 定制复数名称
- 定制存储行为
完全和普通的ngrx可以并存
- 可以脱离@ngrx/data写自己的
- Action/Reducer/Effects/Selector

分页

具体实现代码

// entity metadata
EntityMetadataMap = {
  Container: {
    additionalCollectionState: { page: {} }
  }
};
// Custom Data Service to save page from backend to data
export class CustomizeDataService extends DefaultDataService<Container> {
  getWithQuery(params: string | QueryParams): Observable<Container[]> {
    const pageIndex = params['pageIndex'] || '1';
    return this.http.get(`api/containers?pageIndex=${pageIndex}`).
      pipe(map((data: any) => {
        const containers = data.data;
        containers.page = data.page;
        return containers as any;
    }));
  }
}
// create a page$ in service
export class ContainerService extends EntityCollectionServiceBase<Container> {
  page$: Observable<{pageIndex: number, pageCount: number}>;
  constructor(serviceElementsFactory: EntityCollectionServiceElementsFactory,
    private http: HttpClient) {
    super('Container', serviceElementsFactory);

    this.page$ = this.selectors$['page$'];
  }

}

具体实现代码

// persistent handler
@Injectable({ providedIn: 'root' })
export class PagePersistenceResultHandler extends DefaultPersistenceResultHandler {
  handleSuccess(originalAction: EntityAction): (data: any) => Action {
    const actionHandler = super.handleSuccess(originalAction);
    return (data: any) => {
      const action = actionHandler(data);
      if (action && data && data.page) {
         (action as any).payload.page = data.page;
      }
      return action;
    };
   
  }
}
// reducers methods.
export class EntityCollectionPageReducerMethods<T> extends EntityCollectionReducerMethods<T> {
  constructor(public entityName: string, public definition: EntityDefinition<T>) {
    super(entityName, definition);
  }

  protected queryManySuccess(collection: EntityCollection<T>,action: EntityAction<T[]>
  ): EntityCollection<T> {
    const ec = super.queryManySuccess(collection, action);
    if ((action.payload as any).page) {
      (ec as any).page = (action.payload as any).page;
    }
    return ec;
  }
}

Demo: 分页

根据条件的错误处理

// ComponentA, want to show error dialog
this.containers$ = this.containerService.getAll().pipe(
  catchError(err => {showError(err); return of(err);})
);
// ComponentB, do not want to show error dialog
this.containers$ = this.containerService.getAll().pipe(
  catchError(err => {log.error(err); return of([])})
);
// common error service?
export class ErrorService {
  constructor(private actions$: Actions) {
    actions$
      .pipe(
        ofEntityOp(),
        filter((ea: EntityAction) =>
          ea.payload.entityOp.endsWith(OP_ERROR)
        )
      )
      .subscribe(action => {
        showError(...);
      });
  }
}

使用标签

// ComponentA, want to show error dialog
this.containers$ = this.containerService.getAll({tag: SHOW_ERROR});
// ComponentB, do not want to show error dialog
this.containers$ = this.containerService.getAll({tag: NO_ERROR});
// common error service?
export class ErrorService {
  constructor(private actions$: Actions) {
    actions$
      .pipe(
        ofEntityOp(),
        filter(
          (ea: EntityAction) =>
          ea.payload.entityOp.endsWith(OP_ERROR)
        )
      )
      .subscribe(action => {
        if (action.payload.tag === SHOW_ERROR) {
          showError(...);
        }
      });
  }
}

Demo: Tag

处理有关联关系的实体

User

Container

Version

@ngrx/data 目前还不支持自动处理有关联关系的实体

// service
export class ContainerService {
  // action to get containers with versions
  getContainerWithVersions(containerId) {
    this.getByKey(containerId).switchMap(container => {
      this.versionService.getWithQuery({containers: containers.map(con => con.id)})
        .pipe(map(versions => ({...container, versions})))
    });
  }

  // selectors
  getContainerWithVersionsSelector(containerId) {
    return this.store.pipe(
      this.selectors.selectEntities,
      this.versionService.selectors.selectEntities,
      (containers, versions) => {
         const con = containers.find(c => c.id === containerId);
         const versions = versions.filter(v => vi.cid === containerId);
         return con ? {...con, versions} : undefined;
      }
    );
  }
}

校验?

export const entityMetadata: EntityMetadataMap = {
  Container: {
    validations: {
      props: {
        name: ValidatorOptions.required
      },
      validator: (model: T) => ValidationResult
    }
  }
};

服务器和客户端数据结构的转换

// server data structure
interface Container {
  name: string;
  tag: string;
  updatedTimeStamp?: string;
}

// frontend data structure
interface Container {
  name: string;
  tag: string;
  fullName: string;
}

// entity metadata
export const entityMetadata: EntityMetadataMap = {
  Container: {
    mapTo: (backendModel) => {}
  }
};

在我深入学习并解决分页定制问题之前@ngrx/data是一个

一个有效减少ngrx boilerplate代码的库
提供了很多功能处理了应用中出现的常用场景

经历了学习之后!

一个使用ngrx并运用了ngrx的最佳实践的库
- 命名规则
- 模块划分
- 扩展设计
- 对于RxJs的运用
我们仍然需要掌握ngrx才能彻底掌握@ngrx/data

如果开发团队是ngrx的经验者

可以读一遍@ngrx/data的代码，可以从中学到很多设计的思路!!!
可以在某些管理画面使用@ngrx/data

如果开发团队是ngrx的初学者

可以把@ngrx/data作为入门库，学习使用ngrx,然后进行简单定制，最后可以完整使用ngrx

我现在的想法

@ngrx/data不光可以做简单应用，如果对于ngrx有比较深入了解后，@ngrx/data非常适合作为一个独立的解决方案

我经历的一个真实的项目

Step1: 传统的Angular

代码示例

新的需求

新的需求

新的需求

状态管理

状态

状态之间关系

持久状态同步

持久状态同步+

越来越多的同步需求

Service成了瓶颈

问题

状态管理库ngrx?

NgRx

持久状态同步

好多层....

试着实现一个getAll

Actions

Reducer

Effects

DataService

Selector

ngrx 构成

好多"Boilerplate"代码

Debug对于初学者不友好

@ngrx/data

Zero Ngrx Boilerplate

@ngrx/data

意识不到在使用ngrx

EntityCollectionService

entity metadata

getAll

getAll

ngrx/data architecture

CRUD

CRUD

Flow: getAll

Action/HttpRequest的默认规则

@ngrx/entity

@ngrx/entity的好处

@ngrx/entity提供的EntityAdpter

ngrx/data -> ngrx/entity

Filter

Sort

idSelector

Loading

Demo: Filter/Sort/Loading

乐观更新

使用@ngrx/data实现乐观更新

ChangeState

错误处理

Demo: Update

完美！！！

看来不需要学习太多ngrx的知识也不用写各种ngrx的bolierplate就可以得到所有ngrx的好处

但是.....

定制Http Request的规则

服务器和客户端的数据结构不一致，需要Mapping

分页处理

不知道该如何用@ngrx/data来实现

最终

@ngrx/data扩展点

分页

具体实现代码

具体实现代码

Demo: 分页

根据条件的错误处理

使用标签

Demo: Tag

处理有关联关系的实体

@ngrx/data 目前还不支持自动处理有关联关系的实体

校验?

服务器和客户端数据结构的转换

在我深入学习并解决分页定制问题之前@ngrx/data是一个

经历了学习之后!

如果开发团队是ngrx的经验者

如果开发团队是ngrx的初学者

我现在的想法

谢谢大家！