Posted inProgramming

Xây dựng hệ thống Feature Flag với OpenFeature trong TypeScript: Linh hoạt Toggle và Canary Deployment

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

Vấn đề thực tế: Áp lực từ những đợt deployment rủi ro cao

Bây giờ là 3 giờ 15 phút chiều thứ Năm. Đội ngũ của bạn vừa deploy bản viết lại hoàn toàn của dịch vụ thanh toán (checkout service) lên production. Mười phút sau, PagerDuty réo liên hồi. Một truy vấn thiếu đánh index trong luồng thanh toán mới đang làm nghẽn connection pool của PostgreSQL, chiếm giữ toàn bộ 60 kết nối. Độ trễ vọt lên hơn 4.500 ms. Việc kích hoạt rollback đồng nghĩa với việc phải chờ mười hai phút để hệ thống CI build lại, chạy smoke test và rollout các pod mới. Trong suốt khoảng thời gian gián đoạn (downtime) đó, mỗi lượt thanh toán thất bại làm bốc hơi khoảng 8.000 USD doanh thu mỗi phút.

Sự cố này phơi bày một cạm bẫy kiến trúc kinh điển: đánh đồng deployment với release. Khi việc đẩy mã nhị phân (binary) lên đồng thời tự động kích hoạt logic mới cho tất cả người dùng, bán kính ảnh hưởng (blast radius) của bạn lập tức là 100%. Môi trường staging hiếm khi phản ánh đúng lưu lượng thực tế trên production, dữ liệu khách hàng phức tạp hay các đợt lưu lượng truy cập đồng thời tăng đột biến.

Nguyên nhân gốc rễ: Deployment bị gắn chặt và phụ thuộc nhà cung cấp (Vendor Lock-in)

Tại sao các đội ngũ kỹ thuật lại vấp phải bức tường này? Thường xuất phát từ hai vấn đề kỹ thuật:

  • Thiếu khả năng kiểm soát tại runtime: Việc gắn liền việc kích hoạt tính năng với biến môi trường (environment variables) hoặc Helm values đòi hỏi phải khởi động lại toàn bộ pod để thay đổi thiết lập. Khởi động lại mất vài phút. Nhưng xử lý sự cố đòi hỏi phản hồi trong tích tắc (mili-giây). Khả năng điều khiển tính năng phải tồn tại độc lập bên ngoài vòng đời của container.
  • Bị khóa chặt vào SDK (SDK Lock-in): Các team thường bắt đầu bằng các câu lệnh kiểm tra if/else thô sơ truy vấn một key trong Redis hoặc một bảng Postgres nội bộ. Khi nhu cầu mở rộng, họ chuyển sang các nền tảng enterprise như LaunchDarkly, Split hoặc Unleash. Việc rải rác các lệnh gọi SDK riêng của nhà cung cấp trên khắp 50 microservices sẽ tạo ra món nợ kỹ thuật (technical debt) nặng nề. Việc thay đổi nhà cung cấp sau này trở thành một chuỗi ngày refactor kéo dài hàng tháng trời.

OpenFeature giải quyết triệt để sự phụ thuộc kiến trúc này. Được quản lý bởi Cloud Native Computing Foundation (CNCF), OpenFeature cung cấp một bộ đặc tả độc lập với nhà cung cấp (vendor-agnostic) và chuẩn hóa SDK. Nó tách biệt logic nghiệp vụ của bạn khỏi các giải pháp quản lý flag bên dưới trên nhiều runtime phổ biến, bao gồm cả TypeScript.

Các khái niệm cốt lõi: Cách thức hoạt động của OpenFeature

OpenFeature phân chia trách nhiệm qua bốn thành phần nguyên thủy (primitives):

  • Evaluation Context: Các thuộc tính runtime được truyền vào trong quá trình đánh giá flag. Bao gồm các thuộc tính ngữ cảnh như targetingKey, tenantId, domain email, mã quốc gia hoặc phiên bản ứng dụng.
  • Client: API dành cho lập trình viên để truy vấn giá trị flag (kiểu boolean, string, number hoặc JSON payload).
  • Provider: Adapter chuyển đổi giữa OpenFeature API và engine lưu trữ flag của bạn. Engine này có thể là một in-memory dictionary, một mã nguồn mở như Flipt hoặc GO Feature Flag, hoặc một nền tảng SaaS. Bạn có thể thay đổi provider linh hoạt mà không cần sửa đổi bất kỳ dòng code đánh giá nào trong ứng dụng.
  • Hooks: Các interceptor có khả năng kết hợp trong vòng đời, được thực thi trước, trong hoặc sau khi phân giải flag. Chúng rất lý tưởng để gửi dữ liệu telemetry sang OpenTelemetry, Prometheus hoặc Datadog.

Chuẩn hóa theo lớp trừu tượng này giúp đơn giản hóa việc phát hành không thời gian chết (zero-downtime release). Bạn có thể điều phối lưu lượng truy cập chi tiết mà không cần đụng tới cấu hình hạ tầng.

Thực hành: Xây dựng hệ thống Canary Rollout với TypeScript

Hãy cùng xây dựng một service TypeScript có thể chạy được, thực hiện canary rollout dựa trên tỷ lệ phần trăm mang tính xác định (deterministic) bằng OpenFeature.

1. Khởi tạo dự án

Thiết lập một workspace Node.js mới và cài đặt các package cần thiết:

mkdir ts-openfeature-canary
cd ts-openfeature-canary
npm init -y
npm install @openfeature/server-sdk murmurhash
npm install --save-dev typescript @types/node @types/murmurhash ts-node
npx tsc --init

Chúng ta sử dụng murmurhash để băm định danh người dùng thành phân phối đều từ 0 đến 99. Điều này đảm bảo tính phân nhóm cố định (sticky cohort assignment): cùng một người dùng sẽ luôn nhận được kết quả flag hoàn toàn giống nhau.

2. Tạo Custom Canary Provider

Mặc dù các hệ thống production thường dùng các provider có sẵn, việc tự viết một in-memory provider cục bộ sẽ giúp hiểu rõ cơ chế đánh giá theo ngữ cảnh hoạt động như thế nào ở tầng bên dưới.

Lưu phần triển khai này vào file canaryProvider.ts:

import {
  Provider,
  ResolutionDetails,
  EvaluationContext,
  ProviderMetadata,
  StandardResolutionReasons,
} from '@openfeature/server-sdk';
import murmurhash from 'murmurhash';

export interface FlagRule {
  defaultValue: boolean;
  canaryPercentage?: number; // Số nguyên từ 0 đến 100
  targetUsers?: string[];
}

export class CanaryFlagProvider implements Provider {
  readonly metadata: ProviderMetadata = {
    name: 'CanaryFlagProvider',
  };

  private flags: Map<string, FlagRule> = new Map();

  constructor(initialFlags: Record<string, FlagRule>) {
    for (const [key, rule] of Object.entries(initialFlags)) {
      this.flags.set(key, rule);
    }
  }

  // Cập nhật flag động tại runtime mà không cần khởi động lại tiến trình
  public updateFlag(key: string, rule: FlagRule): void {
    this.flags.set(key, rule);
  }

  async resolveBooleanEvaluation(
    flagKey: string,
    defaultValue: boolean,
    context: EvaluationContext
  ): Promise<ResolutionDetails<boolean>> {
    const rule = this.flags.get(flagKey);

    if (!rule) {
      return {
        value: defaultValue,
        reason: StandardResolutionReasons.DEFAULT,
      };
    }

    const targetingKey = context.targetingKey || (context.userId as string);

    // 1. Kiểm tra danh sách cho phép (allowlist) tường minh
    if (targetingKey && rule.targetUsers?.includes(targetingKey)) {
      return {
        value: true,
        reason: StandardResolutionReasons.TARGETING_MATCH,
      };
    }

    // 2. Tính toán bucket phần trăm mang tính xác định
    if (targetingKey && typeof rule.canaryPercentage === 'number') {
      const hash = Math.abs(murmurhash.v3(`${flagKey}:${targetingKey}`));
      const bucket = hash % 100;
      const isIncluded = bucket < rule.canaryPercentage;

      return {
        value: isIncluded,
        reason: isIncluded
          ? StandardResolutionReasons.TARGETING_MATCH
          : StandardResolutionReasons.DEFAULT,
      };
    }

    return {
      value: rule.defaultValue,
      reason: StandardResolutionReasons.STATIC,
    };
  }

  async resolveStringEvaluation(flagKey: string, defaultValue: string) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }

  async resolveNumberEvaluation(flagKey: string, defaultValue: number) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }

  async resolveObjectEvaluation<T>(flagKey: string, defaultValue: T) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }
}

3. Tích hợp OpenFeature vào logic ứng dụng

Đăng ký custom provider với OpenFeature singleton và đánh giá ngữ cảnh người dùng. Tạo file app.ts:

import { OpenFeature } from '@openfeature/server-sdk';
import { CanaryFlagProvider } from './canaryProvider';

async function main() {
  // 1. Cấu hình quy tắc rollout: 20% traffic + bypass dành riêng cho QA
  const flagConfigs = {
    'v2-checkout-engine': {
      defaultValue: false,
      canaryPercentage: 20,
      targetUsers: ['[email protected]'],
    },
  };

  const provider = new CanaryFlagProvider(flagConfigs);
  await OpenFeature.setProviderAndWait(provider);

  const client = OpenFeature.getClient('payment-service');

  const testUsers = [
    { id: '[email protected]', name: 'Kỹ sư QA nội bộ' },
    { id: 'usr_live_83910', name: 'Sarah (Tenant A)' },
    { id: 'usr_live_12049', name: 'Marcus (Tenant B)' },
    { id: 'usr_live_44921', name: 'Elena (Tenant C)' },
    { id: 'usr_live_99214', name: 'David (Tenant D)' },
  ];

  console.log('=== Giai đoạn 1: Triển khai Canary 20% ===');
  for (const user of testUsers) {
    const isEnabled = await client.getBooleanValue(
      'v2-checkout-engine',
      false,
      { targetingKey: user.id }
    );
    console.log(`[Đánh giá] ${user.name.padEnd(24)} -> Flag kích hoạt: ${isEnabled}`);
  }

  // 2. Nâng flag lên 100% sau khi chỉ số giám sát cho thấy 0% lỗi
  console.log('\n=== Giai đoạn 2: Nâng cấp lên Rollout 100% ===');
  provider.updateFlag('v2-checkout-engine', {
    defaultValue: true,
    canaryPercentage: 100,
  });

  for (const user of testUsers) {
    const isEnabled = await client.getBooleanValue(
      'v2-checkout-engine',
      false,
      { targetingKey: user.id }
    );
    console.log(`[Đánh giá] ${user.name.padEnd(24)} -> Flag kích hoạt: ${isEnabled}`);
  }
}

main().catch(console.error);

4. Thực thi và kiểm thử

Chạy script trực tiếp bằng ts-node:

npx ts-node app.ts

Trong giai đoạn một, tài khoản QA tester và chính xác 20% ID khách hàng được đánh giá là true. Những người dùng còn lại sẽ tiếp tục chạy qua luồng code cũ ổn định. Việc nâng cấp flag sẽ chuyển đổi toàn bộ lưu lượng ngay lập tức trong bộ nhớ mà không cần khởi động lại container hay làm xáo trộn các pod.

Kết luận: Tách biệt triển khai là tiêu chuẩn vận hành

Tách biệt deployment khỏi release giúp biến các đợt phát hành căng thẳng thành quy trình có thể dự đoán và ít rủi ro. Sử dụng đặc tả OpenFeature mang lại cho bạn sự linh hoạt tối đa trong vận hành mà không lo bị phụ thuộc vào một nhà cung cấp cụ thể.

Ba thực hành tốt nhất (best practices) sau sẽ giúp kiến trúc flag của bạn luôn tinh gọn khi mở rộng:

  1. Coi toggle là khoản nợ ngắn hạn: Đặt SLA hết hạn cho các release toggle. Xóa bỏ các đoạn kiểm tra flag và dọn dẹp các nhánh code thừa sau khi tính năng đã đạt 100% trong bảy ngày liên tiếp.
  2. Bắt buộc có cơ chế fallback xác định: Hệ thống flag có thể gặp sự cố chập chờn mạng. Giá trị mặc định của bạn phải luôn phân giải về đường dẫn fallback an toàn nhất (thường là false).
  3. Liên kết toggle trực tiếp với hệ thống cảnh báo: Đẩy các sự kiện đánh giá flag về hệ thống metrics. Khi tỷ lệ lỗi vượt quá 0,5% trong giai đoạn canary, hãy kích hoạt kill-switch tự động để tắt flag ngay lập tức.
Share:
Tags: