NATS

NATS est un système de messagerie open source simple, sécurisé et performant pour les applications natives du cloud, la messagerie IoT et les architectures microservices. Le serveur NATS est écrit dans le langage de programmation Go, mais des bibliothèques clientes pour interagir avec le serveur sont disponibles pour des dizaines de langages de programmation majeurs. NATS prend en charge les livraisons At Most Once (au plus une fois) et At Least Once (au moins une fois). Il peut fonctionner n'importe où, depuis les grands serveurs et les instances cloud, en passant par les gateways de périphérie et même les appareils de l'Internet des objets.

Installation#

Pour commencer à construire des microservices basés sur les NATS, il faut d'abord installer le package requis :

$ npm i --save nats

Vue d'ensemble#

Pour utiliser le transporteur NATS, passez l'objet d'options suivant à la méthode createMicroservice() :

const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
  transport: Transport.NATS,
  options: {
    servers: ['nats://localhost:4222'],
  },
});

const app = await NestFactory.createMicroservice(AppModule, {
  transport: Transport.NATS,
  options: {
    servers: ['nats://localhost:4222'],
  },
});

Astuce L'enum Transport est importé du package @nestjs/microservices.

Options#

L'objet options est spécifique au transporteur choisi. Le transporteur NATS expose les propriétés décrites ici ainsi que les propriétés suivantes :

Client#

Comme d'autres transporteurs de microservices, vous avez plusieurs options pour créer une instance NATS ClientProxy.

Une méthode pour créer une instance est d'utiliser le ClientsModule. Pour créer une instance de client avec le ClientsModule, importez-le et utilisez la méthode register() pour passer un objet options avec les mêmes propriétés que celles montrées ci-dessus dans la méthode createMicroservice(), ainsi qu'une propriété name à utiliser comme jeton d'injection. Pour en savoir plus sur ClientsModuleici.

@Module({
  imports: [
    ClientsModule.register([
      {
        name: 'MATH_SERVICE',
        transport: Transport.NATS,
        options: {
          servers: ['nats://localhost:4222'],
        }
      },
    ]),
  ]
  ...
})

D'autres options pour créer un client (soit ClientProxyFactory ou @Client()) peuvent également être utilisées. Vous pouvez en prendre connaissance ici.

Requête-réponse#

Pour le style de message requête-réponse (en lire plus), le transporteur NATS n'utilise pas le mécanisme NATS intégré Request-Reply. Au lieu de cela, une "requête" est publiée sur un sujet donné en utilisant la méthode publish() avec un nom de sujet de réponse unique, et les répondeurs écoutent sur ce sujet et envoient des réponses au sujet de réponse. Les sujets de réponse sont renvoyés dynamiquement au demandeur, indépendamment de l'emplacement de l'une ou l'autre des parties.

Basé sur les événements#

Pour le style de message basé sur les événements (lire la suite), le transporteur NATS utilise le mécanisme Publish-Subscribe intégré au NATS. Un éditeur envoie un message sur un sujet et tout abonné actif écoutant sur ce sujet reçoit le message. Les abonnés peuvent également manifester leur intérêt pour des sujets génériques qui fonctionnent un peu comme des expressions régulières. Ce modèle "un pour plusieurs" est parfois appelé "fan-out".

Groupes de files d'attente#

Le NATS fournit une fonction intégrée d'équilibrage de la charge appelée files d'attente distribuées. Pour créer un abonnement à une file d'attente, utilisez la propriété queue comme suit :

const app = await NestFactory.createMicroservice<MicroserviceOptions>(AppModule, {
  transport: Transport.NATS,
  options: {
    servers: ['nats://localhost:4222'],
    queue: 'cats_queue',
  },
});

Contexte#

Dans des scénarios plus complexes, vous pouvez avoir besoin d'accéder à des informations supplémentaires sur la requête entrante. Lorsque vous utilisez le transporteur NATS, vous pouvez accéder à l'objet NatsContext.

@MessagePattern('notifications')
getNotifications(@Payload() data: number[], @Ctx() context: NatsContext) {
  console.log(`Subject: ${context.getSubject()}`);
}

@Bind(Payload(), Ctx())
@MessagePattern('notifications')
getNotifications(data, context) {
  console.log(`Subject: ${context.getSubject()}`);
}

Astuce@Payload(), @Ctx() et NatsContext sont importés du package @nestjs/microservices.

Caractères génériques#

Un abonnement peut porter sur un sujet explicite ou inclure des caractères génériques.

@MessagePattern('time.us.*')
getDate(@Payload() data: number[], @Ctx() context: NatsContext) {
  console.log(`Subject: ${context.getSubject()}`); // par exemple "time.us.east"
  return new Date().toLocaleTimeString(...);
}

@Bind(Payload(), Ctx())
@MessagePattern('time.us.*')
getDate(data, context) {
  console.log(`Subject: ${context.getSubject()}`); // par exemple "time.us.east"
  return new Date().toLocaleTimeString(...);
}

Constructeurs d'enregistrements#

Pour configurer les options du message, vous pouvez utiliser la classe NatsRecordBuilder (note : ceci est également possible pour les flux basés sur les évènements). Par exemple, pour ajouter l'en-tête x-version, utilisez la méthode setHeaders, comme suit :

import * as nats from 'nats';

// quelque part dans votre code
const headers = nats.headers();
headers.set('x-version', '1.0.0');

const record = new NatsRecordBuilder(':cat:').setHeaders(headers).build();
this.client.send('replace-emoji', record).subscribe(...);

Astuce La classe NatsRecordBuilder est exportée du package @nestjs/microservices.

Vous pouvez également lire ces en-têtes côté serveur, en accédant au NatsContext, comme suit :

@MessagePattern('replace-emoji')
replaceEmoji(@Payload() data: string, @Ctx() context: NatsContext): string {
  const headers = context.getHeaders();
  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
}

@Bind(Payload(), Ctx())
@MessagePattern('replace-emoji')
replaceEmoji(data, context) {
  const headers = context.getHeaders();
  return headers['x-version'] === '1.0.0' ? '🐱' : '🐈';
}

Dans certains cas, vous pouvez vouloir configurer des en-têtes pour plusieurs requêtes, vous pouvez les passer en tant qu'options à la ClientProxyFactory :

import { Module } from '@nestjs/common';
import { ClientProxyFactory, Transport } from '@nestjs/microservices';

@Module({
  providers: [
    {
      provide: 'API_v1',
      useFactory: () =>
        ClientProxyFactory.create({
          transport: Transport.NATS,
          options: {
            servers: ['nats://localhost:4222'],
            headers: { 'x-version': '1.0.0' },
          },
        }),
    },
  ],
})
export class ApiModule {}

Mises à jour de l'état de l'instance#

Pour obtenir des mises à jour en temps réel sur la connexion et l'état de l'instance du pilote sous-jacent, vous pouvez vous abonner au flux status. Ce flux fournit des mises à jour d'état spécifiques au pilote choisi. Pour le pilote NATS, le flux status émet les événements connected, disconnected, et reconnecting.

this.client.status.subscribe((status: NatsStatus) => {
  console.log(status);
});

Astuce Le type NatsStatus est importé du paquet @nestjs/microservices.

De même, vous pouvez vous abonner au flux status du serveur pour recevoir des notifications sur le statut du serveur.

const server = app.connectMicroservice<MicroserviceOptions>(...);
server.status.subscribe((status: NatsStatus) => {
  console.log(status);
});

Écouter les événements Nats#

Dans certains cas, vous pouvez vouloir écouter les événements internes émis par le microservice. Par exemple, vous pourriez écouter l'événement error pour déclencher des opérations supplémentaires lorsqu'une erreur se produit. Pour ce faire, utilisez la méthode on(), comme montré ci-dessous :

this.client.on('error', (err) => {
  console.error(err);
});

De même, vous pouvez écouter les événements internes du serveur :

server.on<NatsEvents>('error', (err) => {
  console.error(err);
});

Accès au pilote sous-jacent#

Pour des cas d'utilisation plus avancés, vous pouvez avoir besoin d'accéder à l'instance du pilote sous-jacent. Cela peut être utile pour des scénarios tels que la fermeture manuelle de la connexion ou l'utilisation de méthodes spécifiques au pilote. Cependant, gardez à l'esprit que dans la plupart des cas, vous ne devriez pas avoir besoin d'accéder directement au pilote.

Pour ce faire, vous pouvez utiliser la méthode unwrap(), qui renvoie l'instance du pilote sous-jacent. Le paramètre de type générique doit spécifier le type d'instance de pilote que vous attendez.

const natsConnection = this.client.unwrap<import('nats').NatsConnection>();

De même, vous pouvez accéder à l'instance de pilote sous-jacente du serveur :

```typescript const natsConnection = server.unwrap<import('nats').NatsConnection>(); ``