Xây Dựng Dịch Vụ Dễ Kiểm Thử với Kiến Trúc Hình Lục Giác: Hướng Dẫn về Ports và Adapters

Xây dựng các dịch vụ backend mạnh mẽ, dễ bảo trì và dễ kiểm thử là một thách thức cốt lõi đối với bất kỳ kiến trúc sư phần mềm nào. Thông thường, các ứng dụng của chúng ta trở nên gắn bó chặt chẽ với các framework, cơ sở dữ liệu hoặc API bên ngoài cụ thể, khiến chúng khó phát triển và rất khó kiểm thử. Hãy tưởng tượng bạn muốn thay thế cơ sở dữ liệu PostgreSQL bằng MongoDB, hoặc API REST bằng một endpoint gRPC – một nhiệm vụ khó khăn nếu logic nghiệp vụ của bạn bị đan xen với các chi tiết hạ tầng.

Đây chính xác là vấn đề mà Kiến trúc Hình lục giác, còn được gọi là Ports và Adapters, hướng tới giải quyết. Nó cung cấp một cách cấu trúc để giữ cho logic nghiệp vụ cốt lõi của bạn độc lập với các mối quan tâm bên ngoài, thúc đẩy khả năng kiểm thử và tính linh hoạt.

Kiến Trúc Hình Lục Giác Là Gì?

Về cơ bản, Kiến trúc Hình lục giác ủng hộ việc cô lập logic nghiệp vụ cốt lõi của ứng dụng khỏi các công nghệ và hạ tầng bên ngoài. Hãy hình dung ứng dụng của bạn như một hình lục giác (do đó có tên gọi này), với các quy tắc nghiệp vụ quan trọng nằm ở trung tâm.

Các cạnh của hình lục giác này được xác định bởi Ports (Cổng) – các giao diện độc lập với công nghệ, khai báo những gì ứng dụng cần để tương tác với thế giới bên ngoài, và những gì thế giới bên ngoài cần để tương tác với ứng dụng. Các cổng này được triển khai bởi Adapters (Bộ điều hợp), có chức năng dịch các công nghệ cụ thể (như cơ sở dữ liệu, một framework HTTP hoặc một hàng đợi thông điệp) sang định dạng mà lõi ứng dụng hiểu được, và ngược lại.

Các Khái Niệm Cốt Lõi: Ports và Adapters

• Lõi Ứng Dụng / Logic Nghiệp Vụ (Application Core / Domain Logic): Đây là trái tim của ứng dụng của bạn. Nó chứa tất cả các quy tắc nghiệp vụ, các thực thể và dịch vụ của bạn. Điều quan trọng là nó không có kiến thức về cơ sở dữ liệu, framework web hoặc hệ thống nhắn tin. Nó chỉ biết về các đối tượng miền và giao diện (ports) của riêng mình.
• Ports (Cổng): Đây là các giao diện được định nghĩa bởi lõi ứng dụng. Chúng có hai loại chính:
  • Driving Ports (Cổng Điều Khiển / Cổng Đầu Vào): Các giao diện định nghĩa cách thức các thực thể bên ngoài (ví dụ: giao diện người dùng web, API REST, CLI) có thể tương tác với ứng dụng. Một ví dụ có thể là UserServicePort với các phương thức như createUser(data: CreateUserCommand).
  • Driven Ports (Cổng Bị Điều Khiển / Cổng Đầu Ra): Các giao diện định nghĩa những gì ứng dụng cần từ các thực thể bên ngoài (ví dụ: cơ sở dữ liệu, cổng thanh toán bên ngoài). Một ví dụ có thể là UserRepositoryPort với các phương thức như save(user: User): User hoặc findById(id: string): User | undefined.
• Adapters (Bộ Điều Hợp): Đây là các triển khai cụ thể của các cổng, bắc cầu giữa lõi ứng dụng và các công nghệ bên ngoài.
  • Driving Adapters: Triển khai các driving ports. Đây là các thành phần như bộ điều khiển HTTP (HTTP controller), bộ giải quyết GraphQL (GraphQL resolver) hoặc trình xử lý lệnh CLI nhận đầu vào từ người dùng và dịch nó thành các lệnh gọi đến các driving ports của ứng dụng.
  • Driven Adapters: Triển khai các driven ports. Đây là các thành phần như PostgreSQLUserRepository, S3FileStorageAdapter hoặc StripePaymentGatewayAdapter. Chúng đóng gói các chi tiết công nghệ cụ thể và triển khai các giao diện được định nghĩa bởi lõi ứng dụng.

Nguyên tắc chính là Quy tắc Phụ thuộc (Dependency Rule): các phụ thuộc chảy vào bên trong. Lõi ứng dụng chỉ phụ thuộc vào các giao diện (ports) của riêng nó. Các cổng định nghĩa ranh giới, và các bộ điều hợp nằm bên ngoài, phụ thuộc vào các cổng. Điều này đảm bảo logic nghiệp vụ cốt lõi của bạn vẫn độc lập và có khả năng kiểm thử cao.

Một Ví Dụ Thực Tế: Dịch Vụ Quản Lý Người Dùng (TypeScript)

Hãy minh họa điều này với một dịch vụ quản lý người dùng đơn giản bằng TypeScript. Chúng ta sẽ định nghĩa một thực thể User, một UserService để quản lý người dùng, và một UserRepositoryPort để lưu trữ dữ liệu. Sau đó, chúng ta sẽ tạo một bộ điều hợp trong bộ nhớ (in-memory adapter) để kiểm thử và xem xét một bộ điều hợp PostgreSQL cho môi trường sản xuất.

1. Miền và Driven Port

Đầu tiên, thực thể miền cốt lõi của chúng ta và giao diện cho cách chúng ta sẽ duy trì người dùng. Lưu ý rằng UserRepositoryPort được định nghĩa bởi miền, không phải bởi một driver cơ sở dữ liệu.

// src/domain/user.ts
export interface User {
  id: string;
  name: string;
  email: string;
}

// src/domain/ports/user-repository.port.ts
export interface UserRepositoryPort {
  save(user: User): Promise<User>;
  findById(id: string): Promise<User | undefined>;
  findByEmail(email: string): Promise<User | undefined>;
}

2. Dịch Vụ Lõi Ứng Dụng

Dịch vụ này chứa logic nghiệp vụ của chúng ta để tạo và truy xuất người dùng. Nó chỉ phụ thuộc vào giao diện UserRepositoryPort, làm cho nó hoàn toàn độc lập với cơ chế lưu trữ thực tế.

// src/application/user.service.ts
import { User } from '../domain/user';
import { UserRepositoryPort } from '../domain/ports/user-repository.port';

interface CreateUserCommand {
  name: string;
  email: string;
}

export class UserService {
  constructor(private readonly userRepository: UserRepositoryPort) {}

  async createUser(command: CreateUserCommand): Promise<User> {
    if (await this.userRepository.findByEmail(command.email)) {
      throw new Error('User with this email already exists.');
    }
    const newUser: User = {
      id: `user-${Date.now()}`,
      name: command.name,
      email: command.email,
    };
    return this.userRepository.save(newUser);
  }

  async getUserById(id: string): Promise<User | undefined> {
    return this.userRepository.findById(id);
  }

  async getUserByEmail(email: string): Promise<User | undefined> {
    return this.userRepository.findByEmail(email);
  }
}

3. Một Driven Adapter (Bộ điều hợp trong bộ nhớ để kiểm thử)

Bộ điều hợp này triển khai UserRepositoryPort bằng cách sử dụng một bản đồ trong bộ nhớ đơn giản. Hoàn hảo cho các bài kiểm thử đơn vị và tích hợp nhanh mà không cần cơ sở dữ liệu thực.

// src/adapters/in-memory-user-repository.adapter.ts
import { User } from '../domain/user';
import { UserRepositoryPort } from '../domain/ports/user-repository.port';

export class InMemoryUserRepositoryAdapter implements UserRepositoryPort {
  private users: Map<string, User> = new Map();

  async save(user: User): Promise<User> {
    this.users.set(user.id, user);
    return { ...user }; // Trả về một bản sao để ngăn chặn sửa đổi bên ngoài
  }

  async findById(id: string): Promise<User | undefined> {
    return this.users.get(id);
  }

  async findByEmail(email: string): Promise<User | undefined> {
    return Array.from(this.users.values()).find(user => user.email === email);
  }
}

4. Kết nối (Ví dụ Driving Adapter)

Một driving adapter (như một bộ điều khiển HTTP) sẽ tương tác với UserService. Đây là cách bạn sẽ khởi tạo và sử dụng chúng, minh họa việc inject phụ thuộc tại điểm khởi đầu của ứng dụng.

// src/main.ts (đơn giản hóa để minh họa)
import { UserService } from './application/user.service';
import { InMemoryUserRepositoryAdapter } from './adapters/in-memory-user-repository.adapter';
// import { PostgresUserRepositoryAdapter } from './adapters/postgres-user-repository.adapter'; // Giả sử tồn tại

async function bootstrapApplication() {
  // Chọn bộ điều hợp của bạn dựa trên môi trường hoặc cấu hình
  const userRepository = new InMemoryUserRepositoryAdapter(); // Dùng cho môi trường dev/test
  // const userRepository = new PostgresUserRepositoryAdapter(); // Dùng cho môi trường production

  const userService = new UserService(userRepository);

  // Mô phỏng một driving adapter (ví dụ: một yêu cầu HTTP đến)
  console.log('--- Tạo Người Dùng ---');
  const user1 = await userService.createUser({
    name: 'Alice Smith',
    email: 'alice@example.com',
  });
  console.log('Đã tạo người dùng:', user1);

  console.log('--- Lấy Người Dùng theo ID ---');
  const fetchedUser = await userService.getUserById(user1.id);
  console.log('Người dùng đã lấy:', fetchedUser);

  console.log('--- Cố gắng tạo người dùng trùng lặp (sẽ thất bại) ---');
  try {
    await userService.createUser({
      name: 'Bob Johnson',
      email: 'alice@example.com',
    });
  } catch (error: any) {
    console.error('Lỗi khi tạo người dùng:', error.message);
  }
}

bootstrapApplication();

Hãy chú ý cách main.ts là nơi duy nhất biết rõ về InMemoryUserRepositoryAdapter. Bản thân UserService không biết gì về nó, chỉ biết về cổng của nó.

5. Kiểm thử Logic Cốt Lõi

Kiểm thử UserService trở nên đơn giản. Bạn có thể inject bất kỳ triển khai nào của UserRepositoryPort, phổ biến nhất là một mock hoặc InMemoryUserRepositoryAdapter.

// src/application/user.service.test.ts (sử dụng một test runner đơn giản như Jest/Vitest)
import { UserService } from './user.service';
import { InMemoryUserRepositoryAdapter } from '../adapters/in-memory-user-repository.adapter';
import { User } from '../domain/user';

describe('UserService', () => {
  let userService: UserService;
  let userRepository: InMemoryUserRepositoryAdapter; // Hoặc một mock

  beforeEach(() => {
    userRepository = new InMemoryUserRepositoryAdapter();
    userService = new UserService(userRepository);
  });

  it('nên tạo một người dùng mới', async () => {
    const user = await userService.createUser({
      name: 'Test User',
      email: 'test@example.com',
    });

    expect(user).toHaveProperty('id');
    expect(user.name).toBe('Test User');
    expect(user.email).toBe('test@example.com');

    const fetchedUser = await userService.getUserById(user.id);
    expect(fetchedUser).toEqual(user);
  });

  it('không nên tạo người dùng với email trùng lặp', async () => {
    await userService.createUser({
      name: 'Original User',
      email: 'duplicate@example.com',
    });

    await expect(
      userService.createUser({
        name: 'Another User',
        email: 'duplicate@example.com',
      })
    ).rejects.toThrow('User with this email already exists.');
  });

  it('nên trả về undefined cho người dùng không tồn tại', async () => {
    const user = await userService.getUserById('non-existent-id');
    expect(user).toBeUndefined();
  });
});

Điều này cho thấy logic nghiệp vụ (UserService) có thể được kiểm thử một cách sạch sẽ, cô lập, mà không cần khởi động một cơ sở dữ liệu thực hoặc các dịch vụ bên ngoài.

Bài Học Thực Tiễn & Đánh Đổi

Mặc dù Kiến trúc Hình lục giác mang lại những lợi ích đáng kể, nhưng nó không phải là viên đạn bạc. Hiểu rõ những đánh đổi của nó là rất quan trọng để áp dụng thành công.

Lợi ích:

• Khả năng kiểm thử cao: Lợi thế chính. Logic nghiệp vụ có thể được kiểm thử đơn vị nhanh chóng và đáng tin cậy bằng cách inject các mock hoặc các bộ điều hợp trong bộ nhớ, giúp tăng tốc đáng kể chu kỳ phát triển và tăng sự tự tin.
• Độc lập về công nghệ: Bạn có thể thay thế cơ sở dữ liệu, hàng đợi thông điệp hoặc framework web với tác động tối thiểu đến logic miền cốt lõi của bạn. Điều này giúp ứng dụng của bạn không lỗi thời trước những thay đổi của công nghệ.
• Khả năng bảo trì và phát triển: Việc tách biệt rõ ràng các mối quan tâm giúp mã nguồn dễ hiểu, dễ bảo trì và mở rộng hơn. Thay đổi trong hạ tầng không yêu cầu thay đổi trong các quy tắc nghiệp vụ, và ngược lại.
• Kiến trúc sạch: Thi hành một ranh giới được định nghĩa rõ ràng giữa logic cốt lõi và hạ tầng, dẫn đến một cơ sở mã được tổ chức tốt hơn và dễ hiểu hơn.

Thách thức & Đánh đổi:

• Khởi tạo phức tạp ban đầu: Việc định nghĩa các giao diện (ports) và các triển khai bộ điều hợp riêng biệt có thể cảm thấy như là công việc bổ sung, đặc biệt đối với các ứng dụng rất đơn giản.
• Phức tạp về mặt khái niệm: Các thành viên mới trong nhóm có thể cần thời gian để nắm bắt các khái niệm về ports, adapters và nghịch đảo phụ thuộc (dependency inversion).
• Tăng độ phức tạp cho các ứng dụng CRUD đơn giản: Đối với các ứng dụng CRUD thực sự tầm thường, chi phí kiến trúc có thể lớn hơn lợi ích. Hãy xem xét độ phức tạp của miền của bạn trước khi áp dụng nó một cách nghiêm ngặt.
• Quản lý cấu hình: Quản lý việc inject các bộ điều hợp nào (ví dụ: bộ điều hợp cơ sở dữ liệu cho môi trường phát triển so với môi trường sản xuất) yêu cầu một thiết lập dependency injection mạnh mẽ.

Kiến trúc Hình lục giác tỏa sáng trong các ứng dụng có logic nghiệp vụ phức tạp, đang phát triển và mong muốn khả năng bảo trì và linh hoạt lâu dài. Đối với các microservices đơn giản về cơ bản là các lớp bao bọc mỏng xung quanh cơ sở dữ liệu, một kiến trúc phân lớp đơn giản hơn có thể đủ. Tuy nhiên, khi các quy tắc nghiệp vụ phát triển, khoản đầu tư vào các ports và adapters sẽ mang lại lợi tức.

Điểm Cốt Lõi

• Cô lập Logic Nghiệp Vụ: Kiến trúc Hình lục giác giữ cho miền cốt lõi của bạn độc lập với các công nghệ bên ngoài.
• Ports Định Nghĩa Ranh Giới: Các giao diện (ports) thuộc về miền và định nghĩa cách nó tương tác với thế giới bên ngoài.
• Adapters Triển Khai Ports: Các bộ điều hợp bắc cầu giữa các cổng và các công nghệ cụ thể (ví dụ: cơ sở dữ liệu, framework web).
• Tăng cường Khả năng Kiểm thử: Cho phép kiểm thử đơn vị logic cốt lõi dễ dàng bằng cách hoán đổi các bộ điều hợp bằng mock hoặc triển khai trong bộ nhớ.
• Thúc đẩy Tính Linh Hoạt: Cho phép bạn thay đổi cơ sở hạ tầng cơ bản với tác động tối thiểu đến các quy tắc nghiệp vụ.