NestCloud - Feign

Description

A component of nestcloud. NestCloud is a nest framework micro-service solution.

中文文档

This is a Nest module for writing nestjs http clients easier.

Installation

$ npm i --save @nestcloud/feign @nestcloud/loadbalance @nestcloud/consul consul

Quick Start

Import Module

import { Module } from '@nestjs/common';
import { ConsulModule } from '@nestcloud/consul';
import { ServiceModule } from '@nestcloud/service';
import { LoadbalanceModule } from '@nestcloud/loadbalance';
import { BootModule } from '@nestcloud/boot';
import { FeignModule } from '@nestcloud/feign';
import { NEST_BOOT, NEST_LOADBALANCE, NEST_CONSUL } from '@nestcloud/common';

@Module({
  imports: [
      BootModule.register(__dirname, 'bootstrap.yml'),
      ConsulModule.register({dependencies: [NEST_BOOT, NEST_CONSUL]}),
      ServiceModule.register({ dependencies: [NEST_BOOT, NEST_CONSUL] }),
      LoadbalanceModule.register({ dependencies: [NEST_BOOT] }),
      FeignModule.register({ dependencies: [NEST_BOOT, NEST_LOADBALANCE] }), // or NEST_CONSUL_CONFIG
  ],
})
export class ApplicationModule {}

Configurations

feign:
  axios:
    timeout: 1000

Usage

import { Injectable } from "@nestjs/common";
import { Get, Query, Post, Body, Param, Put, Delete } from "@nestcloud/feign";

@Injectable()
export class UserClient {
    @Get('/users')
    getUsers(@Query('role') role: string) {
    }
    
    @Get('http://test.com/users')
    getRemoteUsers() {
    }
    
    @Post('/users')
    createUser(@Body('user') user: any) {
    }
    
    @Put('/users/:userId')
    updateUser(@Param('userId') userId: string, @Body('user') user: any) {
    }
    
    @Delete('/users/:userId')
    deleteUser(@Param('userId') userId: string) {
       
    }
}

Loadbalance

import { Injectable } from "@nestjs/common";
import { Loadbalanced, Get, Query } from "@nestcloud/feign";

@Injectable()
@Loadbalanced('user-service') // open loadbalance supports, need @nestcloud/loadbalance module.
export class UserClient {
    @Get('/users')
    getUsers(@Query('role') role: string) {
    }
    
    @Get('http://test.com/users')
    @Loadbalanced(false) // close loadbalance supports.
    getRemoteUsers() {
    }
}

Brakes

import { IFallback } from "@nestcloud/feign";
import { Injectable, ServiceUnavailableException } from "@nestjs/common";
import { AxiosResponse } from "axios";

@Injectable()
export class CustomFallback implements IFallback {
    fallback(): Promise<AxiosResponse | void> | AxiosResponse | void {
        throw new ServiceUnavailableException('The service is unavailable, please retry soon.');
    }
}

import { IHealthCheck } from "@nestcloud/feign";
import { Injectable } from "@nestjs/common";
import { HealthClient } from "./health.client";

@Injectable()
export class CustomCheck implements IHealthCheck {
    constructor(
        private readonly client: HealthClient
    ) {
    }

    async check(): Promise<void> {
        await this.client.checkHealth();
    }
}

import { Injectable } from "@nestjs/common";
import { UseBrakes, UseFallback, UseHealthCheck, Get, Query } from "@nestcloud/feign";
import { CustomFallback } from "./custom.fallback";
import { CustomCheck } from "./custom.check";

@Injectable()
@UseBrakes({
    statInterval: 2500,
    threshold: 0.5,
    circuitDuration: 15000,
    timeout: 250,
    healthCheck: true,
})
@UseFallback(CustomFallback)
@UseHealthCheck(CustomCheck)
export class UserClient {
}

Interceptor

import { Injectable } from '@nestjs/common';
import { IInterceptor } from "@nestcloud/feign";
import { AxiosResponse, AxiosRequestConfig } from 'axios';

@Injectable()
export class AddHeaderInterceptor implements IInterceptor {
    onRequest(request: AxiosRequestConfig): AxiosRequestConfig {
        request.headers['x-service'] = 'service-name';
        return request;
    }
    
    onResponse(response: AxiosResponse): AxiosResponse {
        return response;
    }
    
    onRequestError(error: any): any {
        return Promise.reject(error);
    }
    
    onResponseError(error: any): any {
        return Promise.reject(error);
    }
}

import { Injectable } from "@nestjs/common";
import { Get, UseInterceptor } from "@nestcloud/feign";
import { AddHeaderInterceptor } from "./middlewares/AddHeaderInterceptor";

@Injectable()
@UseInterceptor(AddHeaderInterceptor)
export class ArticleClient {
    @Get('https://api.apiopen.top/recommendPoetry')
    getArticles() {
    }
}

examples:

@UseInterceptor(Interceptor1)
@UseInterceptor(Interceptor2)
export class Client {

    @UseInterceptor(Interceptor3)
    @UseInterceptor(Interceptor4)
    getArticles() {
    }
}

result:

interceptor1 request
interceptor2 request
interceptor3 request
interceptor4 request
interceptor4 response
interceptor3 response
interceptor2 response
interceptor1 response

API

Get|Post|Put|Delete|Options|Head|Patch|Trace(uri: string, options?: AxiosRequestConfig): MethodDecorator

Route decorator.

| field | type | description | | :--- | :--- | :--- | | uri | string | the url | | options | object | axios config，see axios |

Param|Body|Query|Header(field?: string): ParameterDecorator

Parameter decorator.

| field | type | description | | :--- | :--- | :--- | | field | string | the field name |

SetHeader|SetQuery|SetParam|SetBody(field: string, value: any): MethodDecorator

constant parameter decorator

| field | type | description | | :--- | :--- | :--- | | field | string | the field name | | value | string | number | object | the field value |

Response(): MethodDecorator

If set this decorator, it will return full http response.

ResponseHeader(): MethodDecorator

If set this decorator, it will return response.headers.

ResponseBody(): MethodDecorator

It's a default decorator, it will return response.data.

ResponseType(type: string): MethodDecorator

set response data type, eg: 'arraybuffer', 'blob', 'document', 'json', 'text', 'stream', default 'json'

ResponseEncode(type: string): MethodDecorator

Set response data encode, default 'utf8'

Loadbalanced(service: string | boolean): ClassDecorator | MethodDecorator

Open or close lb support.

UseInterceptor<T extends IInterceptor>(interceptor: { new(): T })

Use interceptor, supports dynamic import and inject.

UseBrakes(config?: BrakesConfig | boolean): ClassDecorator | MethodDecorator

Open circuit supports.

UseFallback(Fall: { new(): T })

Add Custom fallback, use together with Brakes decorator, supports dynamic import and inject.

UseHealthChecker(Checker: { new(): T })

Add Health Checker for Brakes, use together with Brakes decorator, supports dynamic import and inject.

If you use health check, please set heathCheck: true, such as

@Brakes({healthCheck: true})

Stay in touch

• Author - NestCloud

License

NestCloud is MIT licensed.