Mục lục nội dung

Đặt vấn đề: Thách thức về tính nhất quán dữ liệu trong môi trường mạng không tin cậy

Trong thiết kế hệ thống phân tán và ứng dụng web hiện đại, việc đảm bảo tính đáng tin cậy (reliability) của các yêu cầu HTTP là một bài toán vô cùng quan trọng. Mạng máy tính về bản chất là không tin cậy (unreliable network). Khi ứng dụng phía client gửi một yêu cầu HTTP POST để thực hiện hành động thanh toán hoặc khởi tạo đơn hàng, có rất nhiều kịch bản sự cố có thể xảy ra: kết nối mạng bị gián đoạn giữa chừng, server xử lý thành công nhưng response bị timeout trên đường truyền, hoặc người dùng thao tác nhấp chuột nhiều lần liên tiếp (double click).

Theo ngữ nghĩa của chuẩn RESTful API, các phương thức như GET, PUT, DELETE bắt buộc phải có tính chất Idempotent (tính idempotent: thực hiện một hay nhiều lần cùng một yêu cầu đều mang lại một kết quả cuối cùng giống nhau trên hệ thống). Tuy nhiên, phương thức POST mặc định không có tính Idempotent. Nếu client thực hiện retry một request POST /api/v1/payments do bị timeout, hệ thống có rủi ro rất cao sẽ bị xử lý trùng lặp (double-spending) hoặc khởi tạo hai bản ghi hoàn toàn giống nhau trong cơ sở dữ liệu.

Để giải quyết triệt để bài toán này, chiến lược sử dụng Idempotency Key kết hợp giữa NestJS Custom Interceptor và Redis distributed lock/cache là giải pháp chuẩn công nghiệp (industry standard) được các tập đoàn công nghệ hàng đầu như Stripe, PayPal và Adyen áp dụng.

Cơ chế hoạt động của Idempotency Key Engine

Về cơ bản, cơ chế Idempotency Key hoạt động theo các bước nghiêm ngặt sau:

  1. Client tạo ra một chuỗi định danh duy nhất (thường là UUID v4) đại diện cho tác vụ và gửi kèm trong HTTP Header với tên X-Idempotency-Key.
  2. Khi request tới NestJS Backend, một Custom Interceptor sẽ bắt lấy header này trước khi request đi vào Controller xử lý logic nghiệp vụ.
  3. Interceptor kiểm tra sự tồn tại của key trong Redis cache:
    • Trường hợp 1 (Key chưa tồn tại): Tiến hành ghi ghi nhận key vào Redis với trạng thái IN_FLIGHT (đang xử lý) cùng thời gian sống (TTL) thích hợp và cho phép request tiếp tục đi vào Controller. Khi Controller hoàn tất và trả về response, Interceptor sẽ cập nhật trạng thái key trong Redis thành COMPLETED kèm theo toàn bộ HTTP Status Code và Response Body thu được.
    • Trường hợp 2 (Key đang ở trạng thái IN_FLIGHT): Request trùng lặp đến trong khi request đầu tiên chưa xử lý xong. Interceptor sẽ từ chối ngay lập tức bằng HTTP Status Code 409 Conflict để tránh xung đột concurrent.
    • Trường hợp 3 (Key đã ở trạng thái COMPLETED): Request trùng lặp đến sau khi request đầu tiên đã hoàn thành. Interceptor lập tức chặn request, không cho ghi vào DB hay gọi xuống Service layer, mà lấy lại cached response từ Redis để trả về trực tiếp cho client với HTTP Status Code ban đầu.

Xây dựng Idempotency Module trong NestJS

Dưới đây là từng bước triển khai giải pháp Idempotency Engine hoàn chỉnh trong framework NestJS sử dụng TypeScript và Redis client (ioredis).

1. Định nghĩa Custom Decorator để đánh dấu Endpoint cần Idempotency

Không phải tất cả API POST đều cần tính năng Idempotency. Do đó, ta thiết kế một Custom Decorator @UseIdempotency() để gắn linh hoạt trên từng route handler cụ thể.

import { SetMetadata } from '@nestjs/common';

export const IDEMPOTENCY_KEY = 'IDEMPOTENCY_KEY_METADATA';

export interface IdempotencyOptions {
  ttlSeconds?: number;
  enforcePayloadMatching?: boolean;
}

export const UseIdempotency = (options: IdempotencyOptions = {}) =>
  SetMetadata(IDEMPOTENCY_KEY, options);

2. Xây dựng Service quản lý Cache và Lock trên Redis

Service này đóng vai trò giao tiếp trực tiếp với Redis để thực hiện các thao tác nguyên tử (atomic operations) nhằm tránh race condition khi có nhiều request đồng thời chạm vào hệ thống.

import { Injectable, Inject } from '@nestjs/common';
import Redis from 'ioredis';
import * as crypto from 'crypto';

export interface CachedResponse {
  status: 'IN_FLIGHT' | 'COMPLETED';
  statusCode?: number;
  body?: any;
  requestHash?: string;
}

@Injectable()
export class IdempotencyService {
  constructor(@Inject('REDIS_CLIENT') private readonly redis: Redis) {}

  public generatePayloadHash(payload: any): string {
    const serialized = JSON.stringify(payload || {});
    return crypto.createHash('sha256').update(serialized).digest('hex');
  }

  public async getRecord(key: string): Promise<CachedResponse | null> {
    const rawData = await this.redis.get(`idempotency:${key}`);
    if (!rawData) return null;
    return JSON.parse(rawData);
  }

  public async lockKey(key: string, requestHash: string, ttlSeconds: number): Promise<boolean> {
    const record: CachedResponse = {
      status: 'IN_FLIGHT',
      requestHash,
    };
    // Sử dụng tham số NX (Not Exists) để đảm bảo tính Atomic Lock
    const result = await this.redis.set(
      `idempotency:${key}`,
      JSON.stringify(record),
      'EX',
      ttlSeconds,
      'NX'
    );
    return result === 'OK';
  }

  public async saveResponse(
    key: string,
    statusCode: number,
    body: any,
    requestHash: string,
    ttlSeconds: number
  ): Promise<void> {
    const record: CachedResponse = {
      status: 'COMPLETED',
      statusCode,
      body,
      requestHash,
    };
    await this.redis.set(
      `idempotency:${key}`,
      JSON.stringify(record),
      'EX',
      ttlSeconds
    );
  }

  public async deleteKey(key: string): Promise<void> {
    await this.redis.del(`idempotency:${key}`);
  }
}

3. Phát triển Idempotency Interceptor trong NestJS

Interceptor sẽ khai thác ExecutionContext và RxJS Operators để can thiệp vào toàn bộ vòng đời của HTTP Request/Response.

import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
  BadRequestException,
  ConflictException,
} from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { Observable, of } from 'rxjs';
import { tap, catchError } from 'rxjs/operators';
import { IDEMPOTENCY_KEY, IdempotencyOptions } from './idempotency.decorator';
import { IdempotencyService } from './idempotency.service';

@Injectable()
export class IdempotencyInterceptor implements NestInterceptor {
  constructor(
    private readonly reflector: Reflector,
    private readonly idempotencyService: IdempotencyService
  ) {}

  async intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const options = this.reflector.get<IdempotencyOptions>(
      IDEMPOTENCY_KEY,
      context.getHandler()
    );

    // Nếu endpoint không đánh dấu @UseIdempotency(), cho phép đi tiếp
    if (!options) {
      return next.handle();
    }

    const request = context.switchToHttp().getRequest();
    const response = context.switchToHttp().getResponse();
    const idempotencyKey = request.headers['x-idempotency-key'];

    if (!idempotencyKey) {
      throw new BadRequestException('Header X-Idempotency-Key là bắt buộc đối với endpoint này.');
    }

    const ttlSeconds = options.ttlSeconds || 86400; // Mặc định lưu 24 giờ
    const currentPayloadHash = this.idempotencyService.generatePayloadHash(request.body);

    const existingRecord = await this.idempotencyService.getRecord(idempotencyKey);

    if (existingRecord) {
      // Kiểm tra tính toàn vẹn Payload nếu bật option enforcePayloadMatching
      if (
        options.enforcePayloadMatching &&
        existingRecord.requestHash !== currentPayloadHash
      ) {
        throw new BadRequestException('Idempotency Key đã được sử dụng với Request Payload khác.');
      }

      if (existingRecord.status === 'IN_FLIGHT') {
        throw new ConflictException('Yêu cầu tương tự đang được xử lý. Vui lòng không gửi trùng lặp.');
      }

      if (existingRecord.status === 'COMPLETED') {
        response.status(existingRecord.statusCode);
        return of(existingRecord.body);
      }
    }

    // Tiến hành Lock Key trước khi cho phép đi vào Controller
    const locked = await this.idempotencyService.lockKey(
      idempotencyKey,
      currentPayloadHash,
      ttlSeconds
    );

    if (!locked) {
      throw new ConflictException('Phát hiện thao tác ghi song song. Vui lòng thử lại sau.');
    }

    return next.handle().pipe(
      tap(async (bodyData) => {
        const statusCode = response.statusCode;
        await this.idempotencyService.saveResponse(
          idempotencyKey,
          statusCode,
          bodyData,
          currentPayloadHash,
          ttlSeconds
        );
      }),
      catchError(async (err) => {
        // Giải phóng lock trong Redis nếu logic nghiệp vụ bên dưới nảy sinh ngoại lệ
        await this.idempotencyService.deleteKey(idempotencyKey);
        throw err;
      })
    );
  }
}

Áp dụng vào Controller thực tế

Sau khi thiết lập toàn bộ hạ tầng Interceptor, việc tích hợp vào Controller trở nên cực kỳ gọn gàng và chuẩn hóa. Dưới đây là ví dụ về Controller xử lý thanh toán đơn hàng:

import { Controller, Post, Body, UseInterceptors } from '@nestjs/common';
import { IdempotencyInterceptor } from './idempotency.interceptor';
import { UseIdempotency } from './idempotency.decorator';
import { CreatePaymentDto } from './dto/create-payment.dto';
import { PaymentService } from './payment.service';

@Controller('payments')
@UseInterceptors(IdempotencyInterceptor)
export class PaymentController {
  constructor(private readonly paymentService: PaymentService) {}

  @Post()
  @UseIdempotency({ ttlSeconds: 3600, enforcePayloadMatching: true })
  async processPayment(@Body() createPaymentDto: CreatePaymentDto) {
    return await this.paymentService.executeTransaction(createPaymentDto);
  }
}

Những góc khuất kỹ thuật và Best Practices cần lưu ý

1. Cơ chế Payload Matching Hash

Một lỗ hổng phổ biến khi làm Idempotency là hacker hoặc client cố tình dùng lại X-Idempotency-Key của một giao dịch cũ nhưng thay đổi dữ liệu bên trong Request Body (ví dụ: đổi số tiền thanh toán từ 100 USD thành 10000 USD). Bằng việc hash toàn bộ Request Body bằng thuật toán SHA-256 và so sánh với hash được lưu trữ ban đầu, ta đảm bảo rằng một Idempotency Key chỉ đại diện cho duy nhất một bộ dữ liệu đầu vào.

2. Xử lý sự cố Failures và Rollback Strategy

Khi ứng dụng gặp lỗi 5xx hệ thống (ví dụ: Database timeout hoặc nghẽn kết nối Third-party Payment Gateway), ta không nên lưu caching kết quả lỗi này lại với trạng thái COMPLETED. Trong đoạn code Interceptor ở trên, toán tử catchError được dùng để xóa sạch key khỏi Redis. Việc này cho phép client có quyền thực hiện retry chính xác key đó trong lần thử tiếp theo.

3. Phân biệt Idempotency Key và Database Unique Constraint

Database Unique Constraint (như Unique Index trên cột transaction_id trong PostgreSQL/MySQL với TypeORM) là lớp bảo vệ cuối cùng (Last line of defense). Tuy nhiên, chỉ phụ thuộc vào DB Constraint sẽ làm tăng tải cho Database Engine do phải chịu các connection không cần thiết và dễ gây đứt đoạn transaction. Idempotency Key ở tầng Interceptor đóng vai trò là một lớp lá chắn sớm (Early guard) ở mức Application Gateway, chặn đứng các request thừa ngay từ khi chưa chạm vào DB Connection Pool.

Tổng kết

Việc làm chủ và triển khai giải pháp Idempotency Key chuyên sâu với NestJS và Redis giúp hệ thống của bạn nâng cao đáng kể chỉ số Availability và Data Integrity, loại bỏ hoàn toàn rủi ro trùng lặp dữ liệu trong các giao dịch tài chính quan trọng.

Để làm chủ kiến trúc backend hiện đại, nắm vững chuyên sâu các thiết kế pattern chuyên nghiệp và xây dựng ứng dụng thực tế với hiệu năng cao, bạn có thể tham khảo lộ trình đào tạo bài bản. Tham khảo khóa học "RESTful API với NestJS & TypeORM" tại đây.