Restangular 开源项目安装与使用指南

目录结构及介绍

Restangular 是一个用于简化 Angular 应用程序中 REST API 数据交互的库. 当您克隆或下载此 GitHub 存储库时, 您会看到以下主要目录结构:

主要目录

src/

此目录包含了所有源代码文件. 这些文件被组织成多个子目录以实现良好的模块化.

    * index.js            # 入口文件
    * core/               # 包含核心功能如请求处理和响应处理
    * utils/              # 通用函数和工具类
    * interceptors/       # 自定义拦截器逻辑
    * transforms/         # 数据转换和映射函数
    * providers/          # 配置选项和注入点

test/

测试用例及相关文件存放在该目录下.

docs/

文档相关资料存储在此处.

demo/

示例应用程序展示如何集成并利用 Restangular 的功能.

.gitignore

忽略不需要上传至版本控制系统的文件列表.

扩展文件夹

node_modules/

Node.js 包管理器中的第三方依赖项存放位置.

dist/

编译后的生成物存放于此文件夹内.

coverage/

单元测试覆盖率报告将被放置在这里.

启动文件介绍

在src目录下的index.js是整个库的主要入口点. 它负责初始化所有其他部分, 并提供外部接口以便将其轻松地引入到您的 Angular 环境中去。

以下是index.js的基本内容：

import { NgModule } from '@angular/core';
import { HttpClient } from '@angular/common/http';

// 导入内部组件和服务
import { RestangularModule } from './restangular.module';
import { RestangularFactory } from './factory';
import { RestangularConfig } from './config';
import { RestangularService } from './service';
import { RestangularInterceptor } from './interceptors';

@NgModule({
  imports: [],
  exports: [RestangularModule],
  providers: [
    { provide: RestangularFactory, useClass: RestangularFactory },
    { provide: RestangularService, useFactory: () => new RestangularService(RestangularFactory), deps: [] },
    { provide: RestangularInterceptor, useClass: RestangularInterceptor },
    { provide: RestangularConfig, useClass: RestangularConfig }
  ]
})
export class Restangular {
  constructor(
    private httpClient: HttpClient,
    private restangularFactory: RestangularFactory,
    private restangularService: RestangularService,
    private restangularInterceptor: RestangularInterceptor,
    private restangularConfig: RestangularConfig
  ) {}

  /**
   * 初始化 Restangular 模块, 设置全局配置等.
   */
  public init(): void {
    this.restangularService.setGlobalInterceptors([this.restangularInterceptor]);
    this.restangularService.configureOptions(this.restangularConfig);
    this.restangularService.registerAdapters();
  }
}

请注意, 在代码中我们导入了必要的 Angular 核心库和 Http 客户端, 然后设置了我们的自定义服务、工厂类和拦截器实例.

为了确保一切正确运行并且遵循 Angular 的最佳实践, 我们还提供了 module 出口.

此外, 这个文件中的 init 方法允许我们在应用程序加载时执行一些预处理操作（例如设置全局配置）。

配置文件介绍

在 Restangular 中, 配置通过一个名为 RestangularConfig 的服务来进行. 它暴露了一些方法来调整默认行为或者添加额外的功能.

让我们更详细地看一下这个配置类中有哪些可用的选项:

基础配置属性

export interface IRestangularConfig {
  rootElementKey?: string;
  fullResponse?: boolean;
  normalizeData?: Function;
  transformErrorResponse?: Function;
  serverErrorField?: string;
  collectionSuffix?: string;
  resourceSuffix?: string;
  enableActions?: boolean;
  enableLinks?: boolean;
  ignoreUnknownActions?: boolean;
  alwaysReturnData?: boolean;
  useDefaultHttpClient?: boolean;
}

/**
 * 提供配置功能, 可以设置全局参数.
 */
@Injectable()
export class RestangularConfig implements IRestangularConfig {
  public rootElementKey: string | null;
  public fullResponse: boolean;
  public normalizeData: ((data: any) => any) | null;
  public transformErrorResponse: ((response: HttpResponse<any>) => any) | null;
  public serverErrorField: string | null;
  public collectionSuffix: string | null;
  public resourceSuffix: string | null;
  public enableActions: boolean;
  public enableLinks: boolean;
  public ignoreUnknownActions: boolean;
  public alwaysReturnData: boolean;
  public useDefaultHttpClient: boolean;

  constructor(@Optional() @Inject(RestangularConfig.TOKEN) config?: IRestangularConfig) {
    this.rootElementKey = config?.rootElementKey || null;
    this.fullResponse = !!config?.fullResponse;
    this.normalizeData = config?.normalizeData || null;
    this.transformErrorResponse = config?.transformErrorResponse || null;
    this.serverErrorField = config?.serverErrorField || null;
    this.collectionSuffix = config?.collectionSuffix || 'list';
    this.resourceSuffix = config?.resourceSuffix || '';
    this.enableActions = !!config?.enableActions;
    this.enableLinks = !!config?.enableLinks;
    this.ignoreUnknownActions = !!config?.ignoreUnknownActions;
    this.alwaysReturnData = !!config?.alwaysReturnData;
    this.useDefaultHttpClient = !!config?.useDefaultHttpClient;
  }

  /**
   * 设置或更新特定属性值.
   */
  public set(key: keyof IRestangularConfig, value: any): void {
    Reflect.set(this, key, value);
  }

  /**
   * 获取指定属性的当前值.
   */
  public get<T extends keyof IRestangularConfig>(key: T): IRestangularConfig[T] {
    return Reflect.get(this, key);
  }
}

配置示例

现在我们可以创建自定义的配置对象并将它传递给 RestangularConfig 类的构造函数:

const customConfig: IRestangularConfig = {
  rootElementKey: 'items',
  fullResponse: true,
  normalizeData: (data: any[]) => data.map(item => ({ ...item, processed: true })),
  serverErrorField: 'errors',
  collectionSuffix: '',
  resourceSuffix: '-detail',
  enableActions: false,
  enableLinks: true,
  ignoreUnknownActions: true,
  alwaysReturnData: true,
  useDefaultHttpClient: false
};

const myConfig = new RestangularConfig(customConfig);

之后可以通过访问 myConfig 实例上的相应属性来获取任何先前设定好的配置值.

此外, RestangularConfig 类还支持修改某些已存在属性的方法调用:

myConfig.set('rootElementKey', 'myRoot');
myConfig.set('fullResponse', false);

console.log(myConfig.get('rootElementKey')); // 输出: 'myRoot'
console.log(myConfig.get('fullResponse')); // 输出: false

总之, 对于配置 Restangular 的各种功能来说, 以上提供的属性和方法完全足够。 当然也推荐查阅官方文档以获取更多具体细节以及了解未来可能新增的支持。