Sérialisation

La sérialisation est un processus qui intervient avant le retour des objets dans une réponse réseau. C’est un endroit approprié pour établir des règles de transformation et de désinfection des données à retourner au client. Par exemple, les données sensibles comme les mots de passe doivent toujours être exclues de la réponse. Certaines propriétés peuvent également nécessiter une transformation supplémentaire, comme l’envoi uniquement d’un sous-ensemble des propriétés d’une entité. Effectuer ces transformations manuellement peut être fastidieux et source d’erreurs, ce qui peut laisser un doute quant à la couverture de tous les cas.

Aperçu

Nest fournit une capacité intégrée pour garantir que ces opérations peuvent être effectuées de manière simple. L’intercepteur ClassSerializerInterceptor utilise le puissant package class-transformer pour fournir une méthode déclarative et extensible de transformation des objets. L’opération de base qu’il effectue est de prendre la valeur retournée par un gestionnaire de méthode et d’appliquer la fonction instanceToPlain() du package class-transformer. Ce faisant, il peut appliquer des règles exprimées par les décorateurs class-transformer sur une classe d’entité/DTO, comme décrit ci-dessous.

Exclure des propriétés

Supposons que nous souhaitions automatiquement exclure une propriété password d’une entité utilisateur. Nous annotons l’entité comme suit :

import { Exclude } from 'class-transformer';

export class UserEntity {
  id: number;
  firstName: string;
  lastName: string;

  @Exclude()
  password: string;

  constructor(partial: Partial<UserEntity>) {
    Object.assign(this, partial);
  }
}

Maintenant, considérons un contrôleur avec un gestionnaire de méthode qui retourne une instance de cette classe.

@UseInterceptors(ClassSerializerInterceptor)
@Get()
findOne(): UserEntity {
  return new UserEntity({
    id: 1,
    firstName: 'Kamil',
    lastName: 'Mysliwiec',
    password: 'password',
  });
}

Lorsque ce point de terminaison est demandé, le client reçoit la réponse suivante :

{
  "id": 1,
  "firstName": "Kamil",
  "lastName": "Mysliwiec"
}

Notez que l’intercepteur peut être appliqué à l’échelle de l’application (comme couvert ici). La combinaison de l’intercepteur et de la déclaration de classe d’entité garantit que toute méthode qui retourne un UserEntity veillera à supprimer la propriété password. Cela vous offre un moyen de mise en œuvre centralisée de cette règle métier.

Exposer des propriétés

Vous pouvez utiliser le décorateur @Expose() pour fournir des noms d’alias pour les propriétés ou pour exécuter une fonction pour calculer une valeur de propriété (analogue aux fonctions getter), comme illustré ci-dessous.

@Expose()
get fullName(): string {
  return `${this.firstName} ${this.lastName}`;
}

Transformer

Vous pouvez effectuer une transformation supplémentaire des données en utilisant le décorateur @Transform(). Par exemple, la construction suivante retourne la propriété nom de RoleEntity au lieu de retourner tout l’objet.

@Transform(({ value }) => value.name)
role: RoleEntity;

Passer des options

Vous pouvez vouloir modifier le comportement par défaut des fonctions de transformation. Pour remplacer les paramètres par défaut, passez-les dans un objet options avec le décorateur @SerializeOptions().

@SerializeOptions({
  excludePrefixes: ['_'],
})
@Get()
findOne(): UserEntity {
  return new UserEntity({});
}

Les options passant par @SerializeOptions() sont transmises comme deuxième argument de la fonction sous-jacente instanceToPlain(). Dans cet exemple, nous excluons automatiquement toutes les propriétés qui commencent par le préfixe _.

Exemple

Un exemple fonctionnel est disponible ici.

WebSockets et Microservices

Bien que ce chapitre montre des exemples utilisant des applications de style HTTP (par exemple, Express ou Fastify), le ClassSerializerInterceptor fonctionne de la même manière pour les WebSockets et les Microservices, quel que soit le mode de transport utilisé.

En savoir plus

Lisez plus sur les décorateurs et les options disponibles fournies par le package class-transformer ici.