Ở bài đầu tiên trong loạt bài này, tôi đã giải thích vì sao các đội nên thống nhất một bản hợp đồng API theo chuẩn OpenAPI trước khi ai bắt tay vào viết mã. Bài này nói về công cụ giúp bản hợp đồng đó thực sự phát huy tác dụng.

Tự tay viết lớp gọi API cho frontend là một trong những việc chẳng ai dám nhận là mình thích. Bạn chép các kiểu dữ liệu (type) từ tài liệu của backend, viết đi viết lại hàm bọc (wrapper) cho yêu cầu lần thứ bốn mươi, rồi ba tuần sau có ai đó đổi tên một trường và thế là một nửa số chỗ gọi API của bạn âm thầm hỏng. Orval xóa sổ luôn công việc đó. Chỉ cần trỏ nó tới bản đặc tả (spec) OpenAPI, Orval sẽ sinh mã máy khách cho bạn: hàm có định kiểu cho từng endpoint, mô hình dữ liệu khớp chính xác với hợp đồng, và cả dữ liệu giả lập (mock) để bạn phát triển trước khi backend kịp làm xong.

Vì sao đội frontend thích Orval

#

Phần sinh dữ liệu giả lập là phần bị đánh giá thấp nhất. Một khi đặc tả đã chốt, frontend có thể dựng một máy chủ giả rồi làm toàn bộ giao diện dựa trên nó, thay vì ngồi chờ những endpoint lúc nào cũng “sắp xong rồi”. Khi backend thật được triển khai, bạn chỉ việc trỏ máy khách sang đó và gần như mọi thứ chạy được luôn, vì cả hai bên đều làm dựa trên cùng một tài liệu.

Cái lợi còn lại là phần mã nhàm chán giờ đúng ngay từ khi được sinh ra. Không còn ai gõ nhầm tên trường trong phần thân yêu cầu (request body) tự viết, vì đơn giản là chẳng còn ai phải tự viết phần đó nữa.

Vì sao đội backend cũng thích

#

Khi bản đặc tả là nguồn dữ liệu gốc duy nhất, những trao đổi hằng ngày giữa hai bên cũng thay đổi hẳn. Thay vì những chuỗi tin nhắn kiểu “endpoint này trả về gì ấy nhỉ?”, frontend chỉ việc đọc các kiểu dữ liệu đã được sinh ra. Lập trình viên backend ít bị làm phiền hơn, mà lại nhận được góp ý sớm hơn: nếu frontend làm dựa trên dữ liệu giả lập rồi thấy API có chỗ nào khó dùng, bạn sẽ biết ngay từ lúc sửa còn rẻ, chứ không phải đợi đến khi nó đã lên môi trường production.

Orval nằm ở đâu trong quy trình làm việc

#

Chẳng có gì cầu kỳ cả. Backend đề xuất bản đặc tả, hai đội cùng rà soát, frontend dùng Orval để sinh mã máy khách và dữ liệu giả lập rồi bắt đầu làm, còn backend thì hiện thực các endpoint thật theo đúng hợp đồng đó. Khi đặc tả thay đổi, cả hai bên sinh lại mã, và trình biên dịch sẽ chỉ ra chính xác chỗ nào bị hỏng. Phần cuối đó mới là mấu chốt: những chỗ lệch nhau giữa frontend và backend sẽ hiện ra thành lỗi biên dịch, thay vì thành lỗi trên production.

Cài đặt và cấu hình

#

Cài Orval dưới dạng gói phụ thuộc chỉ dùng khi phát triển (dev dependency), cùng với những thư viện mà mã được sinh ra sẽ import. Nếu muốn có hook React Query và mock thì đó là TanStack Query, MSW và Faker:

npm install --save-dev orval msw @faker-js/faker
npm install @tanstack/react-query

Sau đó thêm tệp orval.config.ts ở thư mục gốc của dự án. Cấu hình dưới đây gần giống ví dụ trong tài liệu chính thức của Orval:

import { defineConfig } from 'orval';

export default defineConfig({
  petstore: {
    input: {
      target: './openapi.yaml', // a path or a URL
    },
    output: {
      mode: 'single',
      target: './src/api/petstore.ts',
      schemas: './src/api/model',
      client: 'react-query',
      httpClient: 'fetch',
      mock: true, // MSW handlers plus Faker data
      override: {
        fetch: { includeHttpResponseReturnType: false },
      },
    },
  },
});

Tùy chọn client quyết định bạn nhận được gì: các hàm fetch hoặc axios thuần, hook cho React Query, Vue Query, Svelte Query hay SWR, service cho Angular, hoặc schema Zod. Dòng includeHttpResponseReturnType: false khiến máy khách fetch trả về thẳng phần thân phản hồi (response body) thay vì { data, status }, mà thường thì component chỉ cần đúng phần đó.

Thêm một script vào package.json để không ai phải nhớ câu lệnh:

{
  "scripts": {
    "api": "orval"
  }
}

Chạy npm run api là các hook và mô hình dữ liệu được sinh ra. Sau đó component dùng chúng như mọi hook React Query khác, với kiểu dữ liệu đã có sẵn đầy đủ:

import { useListPets } from './api/petstore';

export function PetList() {
  const { data: pets, isLoading } = useListPets();
  if (isLoading) return <p>Loading…</p>;
  return (
    <ul>
      {pets?.map((pet) => <li key={pet.id}>{pet.name}</li>)}
    </ul>
  );
}

Thử đổi tên một trường trong đặc tả rồi chạy lại npm run api, bạn sẽ thấy pet.name bị gạch đỏ ở mọi chỗ đang dùng nó. Đó chính là cách bắt chỗ lệch giữa frontend và backend mà tôi nói ở trên, và bạn chẳng tốn gì để có nó.

Phát triển dựa trên mock

#

Khi bật mock: true, Orval còn viết thêm cho mỗi endpoint một handler xử lý yêu cầu (request handler) của MSW, trả về dữ liệu do Faker tạo ra theo đúng cấu trúc (schema) của phản hồi, kèm một hàm trả về toàn bộ các handler đó. Đưa danh sách này cho setupWorker của MSW khi chạy trên trình duyệt, hoặc cho setupServer khi chạy kiểm thử, là ứng dụng sẽ chạy trên một backend giả vốn đã khớp sẵn với hợp đồng API. Mỗi handler còn nhận thêm phần ghi đè (override), nên một bài kiểm thử có thể trả về một payload cụ thể, một danh sách rỗng hay một trạng thái lỗi, mà không ai phải tự tay viết dữ liệu mẫu (fixture).

Chính phần này giúp frontend bắt tay vào làm ngay từ ngày đầu tiên. Mock không phải một thứ riêng mà ai đó phải ngồi bảo trì; chúng được sinh lại từ cùng bản đặc tả với mã máy khách, nên không thể nào bị tụt lại so với đặc tả.

So sánh Orval với openapi-generator, openapi-typescript và Hey API

#

Cả bốn công cụ đều bắt đầu từ bản đặc tả OpenAPI, nhưng mỗi công cụ sinh ra đến đâu thì khác nhau.

Nếu chỉ cần kiểu dữ liệu thì openapi-typescript là lựa chọn nhẹ nhất, khó mà chê được. openapi-generator đáng dùng khi cùng một bản đặc tả phải sinh mã cho nhiều ngôn ngữ; mã TypeScript nó sinh ra vẫn chạy được, nhưng đọc lên cứ như được viết cho Java trước rồi mới chuyển sang. Giữa Orval và Hey API thì chủ yếu là chuyện sở thích, và bạn thấy mã sinh ra của bên nào dễ đọc hơn. Tôi vẫn dùng Orval vì mock được sinh ra trong cùng một lần chạy với các hook, và chính tính năng đó đã thay đổi cách đội frontend và đội backend làm việc với nhau.

Đây không phải loại công cụ hào nhoáng gì. Nó chỉ lặng lẽ dẹp bỏ cả một kiểu tranh cãi giữa các đội, và lần nào có cơ hội đổi như vậy, tôi cũng sẵn lòng.

Nói ngắn gọn, quy trình design-first (thiết kế API trước rồi mới viết mã) này lặp lại sau mỗi sprint như sau:

1. Chọn hai người phụ trách phần API của sprint, một người bên backend và một người bên frontend.
2. Hai người cùng viết (hoặc cập nhật) bản đặc tả OpenAPI dựa trên yêu cầu của sprint, rồi rà soát cho đến khi cả hai bên đều đồng ý.
3. Commit bản đặc tả vào repo. Từ lúc này, nó chính là hợp đồng giữa hai bên.
4. CI dựng một máy chủ giả lập (mock server) từ bản đặc tả vừa commit.
5. Frontend làm việc với máy chủ giả lập, trong lúc backend viết các endpoint thật.
6. Khi dịch vụ thật đã được triển khai, bản đặc tả do chính dịch vụ đó sinh ra sẽ là điểm xuất phát cho bản đặc tả của sprint tiếp theo.

Chuyện này bắt nguồn từ đâu

#

Mọi chuyện bắt đầu từ một buổi họp nhìn lại (retrospective). Góp ý hôm đó khá thẳng thắn: gần như không ai nắm được khâu lên kế hoạch API đang diễn ra thế nào. Backend xây endpoint theo cách hiểu yêu cầu của riêng mình, frontend chỉ biết phản hồi (response) của API có cấu trúc ra sao khi mọi thứ đã xong xuôi, và những chỗ vênh nhau chỉ lộ ra lúc tích hợp, đúng thời điểm sửa tốn kém nhất. Đề xuất đưa ra là kéo cả hai bên vào ngay từ giai đoạn lên kế hoạch, và lấy bản đặc tả OpenAPI (OpenAPI schema) làm trục chính cho mọi thứ xoay quanh.

Quy trình

#

Mỗi tuần, chúng tôi chọn ra hai đại diện, một người bên backend và một người bên frontend. Nhiệm vụ của họ là nắm rõ yêu cầu của sprint và chỉnh bản đặc tả OpenAPI dùng cho khâu lên kế hoạch sao cho khớp với yêu cầu đó. Hai người cùng rà soát bản đặc tả, sửa những chỗ chưa khớp, và đến cuối buổi thì cả hai bên đều biết chính xác sẽ xây cái gì, trước khi có ai bắt tay vào làm.

Khi các chỉnh sửa đã chốt xong, bản đặc tả được commit vào kho mã (repo), và quy trình CI/CD sẽ sinh ra API giả lập (mock API) từ tệp yaml đó. Hết sprint, chúng tôi tạo một tệp yaml mới cho yêu cầu API của sprint kế tiếp, và vòng lặp cứ thế tiếp tục.

Ghi chú về công cụ

#

Muốn xem trực quan tệp yaml thì Swagger Editor là đủ: tải tệp lên là bạn sẽ thấy nó hiển thị thành một tài liệu Swagger đàng hoàng.

Quy trình CI/CD cần nhận vào một tệp yaml và dựng máy chủ giả lập từ đó. Prism của Stoplight là một lựa chọn được dùng rộng rãi, và hỗ trợ cả OpenAPI 3.1:

npm install -g @stoplight/prism-cli
prism mock openapi.yaml

Lệnh này phục vụ mọi đường dẫn (path) trong bản đặc tả tại http://127.0.0.1:4010, và trả về đúng các giá trị trong examples của bản đặc tả. Chẳng hạn, gọi GET /lists/10 sẽ nhận được danh sách mẫu trong phần phụ lục. Prism cũng bắt tuân thủ hợp đồng: vì ví dụ có khai báo API key, request nào thiếu header X-API-Key sẽ nhận về mã 401, và đó chính là hành vi mà frontend cần xây dựng theo. Nếu chạy Prism trong container, hãy thêm -h 0.0.0.0 để bên ngoài container truy cập được. openapi-mock là một lựa chọn gọn nhẹ hơn, tự điền dữ liệu ngẫu nhiên vào phản hồi.

Bạn cũng nên kiểm tra lỗi (lint) bản đặc tả trước khi dựng máy chủ giả lập. Như vậy, nếu hợp đồng bị viết sai thì bản build sẽ báo lỗi ngay, thay vì để frontend phải loay hoay không hiểu vì sao. Spectral chỉ cần một tệp quy tắc (ruleset) dài đúng một dòng là chạy được:

npm install -g @stoplight/spectral-cli
echo 'extends: ["spectral:oas"]' > .spectral.yaml
spectral lint openapi.yaml

Cuối cùng, bản đặc tả này chỉ phục vụ khâu lên kế hoạch. Khi API thật đã được triển khai, dịch vụ nên tự sinh ra openapi.json của riêng nó; bạn có thể tải tệp đó về rồi dùng lại cho vòng lên kế hoạch tiếp theo.

Sao phải mất công như vậy

#

Vì làm vậy thì các cuộc tranh cãi sẽ diễn ra ở nơi rẻ nhất có thể. Khi có một kỹ sư frontend và một kỹ sư backend cùng ngồi viết bản đặc tả, những chỗ hiểu lầm sẽ được phát hiện trước khi kịp biến thành mã. Yêu cầu API chỉ cần thống nhất một lần, thay vì phải thương lượng lại giữa sprint. Nhờ có máy chủ giả lập, frontend bắt tay vào làm được ngay chứ không phải ngồi chờ. Và số chi tiết quan trọng bị bỏ sót cũng ít hơn hẳn, vì muốn lọt được thì chúng phải qua mắt hai người, lại còn phải qua một bản hợp đồng giấy trắng mực đen.

Chẳng có gì mang tính cách mạng ở đây cả. Chỉ là kế hoạch được làm cụ thể đến mức máy có thể dựng lại nó thành bản giả lập cho bạn dùng. Và hóa ra, đó cũng chính là mức cụ thể mà một bản kế hoạch cần có.

Phụ lục A - Ví dụ yaml

#

openapi: 3.1.0
info:
  title: MyApp Sprint 3
  description: Planning schema for sprint 3. Drives the mock server only.
  version: 0.3.0
servers:
  - url: https://api-mock.example.com/v1
tags:
  - name: lists
    description: Saved lists feature (PROJ-123)
security:
  - api_key: []
paths:
  /lists:
    get:
      tags: [lists]
      summary: Return the current user's saved lists
      operationId: getLists
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/List'
  /lists/{listId}:
    get:
      tags: [lists]
      summary: Find a list by ID
      operationId: getListById
      parameters:
        - name: listId
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found
components:
  schemas:
    List:
      type: object
      required: [id, title]
      properties:
        id:
          type: integer
          format: int64
          examples: [10]
        title:
          type: string
          examples: [Weekend reading]
        itemCount:
          type: integer
          examples: [7]
  securitySchemes:
    api_key:
      type: apiKey
      name: X-API-Key
      in: header

Cái vòng chờ đợi

#

Quy trình truyền thống thì chạy tuần tự. Backend thiết kế và xây API, và chỉ khi endpoint đã chạy được thật thì frontend mới bắt đầu tích hợp. Backend chậm ngày nào thì lịch của frontend lãnh đủ ngày đó, mà ngày phát hành thường lại phụ thuộc vào lịch của frontend.

Hợp đồng trước, mã nguồn sau

#

Với quy trình đặc tả trước (schema-first), hai bên bắt đầu gần như cùng lúc. Trước khi có dòng mã nào, toàn bộ cấu trúc của API được đưa vào một bản đặc tả OpenAPI (OpenAPI schema): mọi endpoint, mô hình dữ liệu của yêu cầu và phản hồi, phương thức xác thực và mã lỗi. Tài liệu đó trở thành bản hợp đồng giữa frontend và backend.

Lợi ích thấy ngay. Trước khi tính năng được xây, ai cũng hiểu nó theo cùng một cách. Frontend có thể dựng giao diện trong lúc backend vẫn đang hiện thực các endpoint. Khi có thay đổi thì xử lý cũng nhanh hơn, vì chỉ có một nguồn thông tin chuẩn đã được thống nhất cần cập nhật. Và bạn có thể sinh máy chủ giả lập (mock server) thẳng từ bản đặc tả, nên frontend bắt đầu kiểm thử được ngay cả khi chưa có endpoint thật nào.

Áp dụng thực tế ra sao

#

1. Thu thập yêu cầu, như với bất kỳ việc gì khác.
2. Thiết kế bản đặc tả: endpoint, mô hình yêu cầu/phản hồi, xác thực, mã lỗi.
3. Cho cả frontend lẫn backend cùng rà soát. Đây là lúc bản hợp đồng thể hiện rõ giá trị của nó.
4. Sinh máy chủ giả lập (Swagger và Postman đều làm được) và để frontend tích hợp với bản giả lập đó.
5. Backend hiện thực các endpoint thật theo đúng bản đặc tả.
6. Khi endpoint thật lần lượt xong thì thay dần bản giả lập bằng endpoint thật, đồng thời kiểm thử liên tục để chắc chắn hai bên vẫn làm đúng hợp đồng.
7. Tiếp tục trao đổi với nhau. Bản đặc tả là tài liệu sống, chứ không phải thứ khắc lên bia đá.

Những điểm vướng

#

Tất nhiên cách này cũng có cái giá của nó. Viết một bản đặc tả kỹ lưỡng ngay từ đầu tốn khá nhiều thời gian. Khi yêu cầu thay đổi thì bản đặc tả phải đổi trước, và ảnh hưởng sẽ lan sang cả hai đội. Ngoài ra, ai cũng cần biết dùng OpenAPI và các công cụ đi kèm ở mức cơ bản.

Dù vậy, tôi chưa từng thấy trường hợp nào mà công sức bỏ ra lúc đầu lại tốn hơn mớ hỗn loạn lúc tích hợp mà nó giúp tránh được. Frontend bắt tay vào làm từ ngày đầu tiên, còn các cuộc tranh cãi thì diễn ra trên một bản tài liệu, chứ không phải trên những bản dựng hỏng.