Ở 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.

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.

Zdog là một thư viện JavaScript nhỏ gọn để vẽ hình minh hoạ kiểu 3D lên <canvas> hoặc SVG. Các hình khối có vị trí thật trong không gian 3D và xoay được như vật thể 3D, nhưng lại được vẽ thành hình phẳng, nên kết quả trông giống một bức minh hoạ phẳng có thể xoay qua xoay lại hơn là một bản dựng 3D (3D render). Làm một lá cờ đơn giản thì rất hợp.

Ví dụ Zdog tối giản

#

Hai hình khối, kéo chuột để xoay, và một vòng lặp hoạt ảnh (animation loop):

<canvas class="zdog-canvas" width="240" height="240"></canvas>
<script src="https://unpkg.com/zdog@1/dist/zdog.dist.min.js"></script>
<script>
  const illo = new Zdog.Illustration({
    element: '.zdog-canvas',
    dragRotate: true, // drag to turn the scene
  });

  // a square, pushed back
  new Zdog.Rect({
    addTo: illo,
    width: 80,
    height: 80,
    translate: { z: -30 },
    stroke: 8,
    color: '#0047a0',
  });

  // a filled circle, pulled forward
  new Zdog.Ellipse({
    addTo: illo,
    diameter: 60,
    translate: { z: 30 },
    stroke: 8,
    color: '#cd2e3a',
    fill: true,
  });

  function animate() {
    illo.rotate.y += 0.02;
    illo.updateRenderGraph();
    requestAnimationFrame(animate);
  }
  animate();
</script>

Mỗi hình được gắn vào khung cảnh bằng addTo, và chính translate.z tạo ra cảm giác 3D: xoay khung cảnh thì hình tròn sẽ vòng ra phía trước hình vuông. updateRenderGraph() cập nhật và vẽ lại toàn bộ, nên nó nằm trong vòng lặp.

Tài liệu chính thức

#

https://zzz.dog/

Toàn bộ mã nguồn của ví dụ này có trên CodePen, bạn cứ vào xem.

Ví dụ của tôi

#

Dưới đây là cách tôi thiết lập.

Sao lại dùng SASS?

#

CSS thuần sẽ bắt đầu rối khi trang web lớn hơn dăm ba trang. SASS cho bạn biến, quy tắc lồng nhau, mixin và hàm, nên những thứ như màu sắc hay các đoạn bố cục dùng chung chỉ cần đặt ở một chỗ, thay vì sao chép khắp nơi. Hay nhất với người dùng Hugo là Hugo Pipes tự biên dịch SCSS giúp bạn — không cần công cụ dựng (build tool) riêng, cũng không cần script theo dõi thay đổi (watcher).

Hai trang nên mở sẵn trong lúc làm:

• Tài liệu SASS
• Tài liệu hỗ trợ SCSS/SASS của Hugo

Thiết lập

#

1. Sắp xếp lại thư mục assets

#

Hugo tìm thư mục assets ở thư mục gốc của dự án, nên bạn hãy tạo thư mục này (hoặc chuyển thư mục đang có) ra đó. Nếu muốn để nó nằm bên trong resources, hãy khai báo cho Hugo trong config.toml:

assetDir = "resources/assets"

2. Tạo thư mục sass

#

Bên trong assets, tạo một thư mục tên là sass. Các tệp SCSS của bạn sẽ nằm ở đây.

3. Thêm tệp đầu vào (entry point)

#

Tạo tệp main.scss bên trong thư mục sass. Đây là tệp mà Hugo sẽ biên dịch, nên cứ thêm vào một ít SCSS để kiểm tra xem nó đã chạy chưa:

// assets/sass/main.scss

// Variables
$primary-color: #3498db;

// Mixin
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// Styles
body {
  font-family: Arial, sans-serif;
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

4. Gắn vào mẫu giao diện (template)

#

Trong partial head.html, nạp tệp CSS đã biên dịch rồi rút gọn (minify) nó:

{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

Chỉ cần nhớ là tên tệp ở đây phải khớp với tệp đầu vào thật của bạn (main.scss).

Chia nhỏ mã định kiểu

#

Khi mọi thứ lớn dần, hãy tách SCSS thành các partial rồi import chúng từ main.scss:

// assets/sass/_variables.scss
$primary-color: #3498db;

// assets/sass/_mixins.scss
@mixin center {
  display: flex;
  justify-content: center;
  align-items: center;
}

// assets/sass/main.scss
@import "variables";
@import "mixins";

body {
  background-color: $primary-color;
}

h1 {
  @include center;
  color: white;
}

Nói thật là chỉ có vậy thôi. Bốn bước, và Hugo sẽ biên dịch lại mã định kiểu mỗi lần dựng trang. Tôi cứ tưởng sẽ phải vật lộn với quy trình xử lý tài nguyên (asset pipeline), ai ngờ mọi thứ chạy ngon luôn.