0

Đừng để component gọi API: tầng dữ liệu bám theo hợp đồng API

Dashboard thống kê mình làm có sáu màn hình. Lúc đầu, backend chưa xong, nên mỗi màn import thẳng một file dữ liệu mẫu và vẽ luôn. Nhanh, đẹp, demo được ngay.

Rồi API thật lên. Mình nhìn sáu màn hình, mỗi màn tự đọc một kiểu dữ liệu, tự định dạng số theo một kiểu, và nhận ra để chuyển sang API thì phải sửa cả sáu. Tệ hơn, khi review hợp đồng API với backend, mới phát hiện mọi response đều được bọc trong một lớp vỏ { meta, data, unavailable }, trong khi code phía mình khai báo kiểu như thể response chỉ có phần bên trong. TypeScript không báo gì, vì mình đã tự nói với nó là kiểu đó đúng.

Bài này là cách mình dựng lại: một tầng dữ liệu nằm giữa API và component, bám theo hợp đồng API, để đổi từ dữ liệu mẫu sang dữ liệu thật mà không sửa màn hình nào, và để hợp đồng thay đổi thì test đỏ chứ không phải người dùng thấy sai.

Trước và sau

TRƯỚC                                   SAU
Màn hình ── import ──▶ fixture.json     Màn hình ── hook ──▶ DataSource (interface)
Màn hình ── fetch  ──▶ API                                     ├── FixtureDataSource
(mỗi màn tự đọc, tự định dạng)                                 └── ApiDataSource
                                                                       │
                                                               client.request()
                                                               gỡ lớp vỏ ở MỘT chỗ
                                                                       │
                                                               mapper thuần:
                                                               dữ liệu API → dữ liệu hiển thị

Ba lớp, mỗi lớp một việc:

Lớp Biết gì Không biết gì
Client + gỡ vỏ URL, method, lớp vỏ response Màn hình nào dùng dữ liệu
Mapper Hình dạng dữ liệu API và dữ liệu hiển thị Dữ liệu đến từ đâu
Component Dữ liệu hiển thị API, lớp vỏ, null của backend

Bước 1: viết hợp đồng thành kiểu, kể cả chỗ có thể null

Hợp đồng API của bọn mình là một thư mục: một file liệt kê các endpoint (endpoints.json) và một file ví dụ response cho mỗi endpoint. Viết nó thành kiểu TypeScript, đúng như nó là:

// Lớp vỏ chung của mọi response
interface Envelope<T> {
  meta: { asOf: string; timeZone: string };
  data: T;
  unavailable: string[]; // phần dữ liệu backend chưa tính được
}

interface UtilisationByLocation {
  items: Array<{
    locationId: string;
    name: string;
    utilisation: number | null; // null khi địa điểm chưa có lượt đặt nào
  }>;
}

Chữ | null ở dòng utilisation là chỗ đáng giá nhất. Lần đầu khai kiểu, mình viết utilisation: number vì file ví dụ đầu tiên toàn có số. Đọc kỹ các file ví dụ ở trạng thái khác thì thấy giá trị null. Khai sai thì TypeScript sẽ cho phép item.utilisation.toFixed(1), và màn hình crash đúng lúc gặp địa điểm mới.

Để không ai lỡ tay đổi number | null thành number, có thể "khoá" bằng một đoạn code chỉ để type-check:

// Biên dịch lỗi nếu ai đó bỏ "| null" khỏi utilisation
const nullableProof: UtilisationByLocation['items'][number]['utilisation'] = null;

Bước 2: gỡ lớp vỏ ở đúng một chỗ

Lỗi cũ trông thế này:

// Sai: gọi kiểu T nhưng thứ server trả về là Envelope<T>
getUtilisation = () => client.request<UtilisationByLocation>('GET', '/insights/utilisation-by-location');

client.request<T> chỉ là lời hứa với TypeScript, không kiểm tra gì lúc chạy. Sửa bằng một hàm duy nhất biết về lớp vỏ:

async function getData<T>(path: string): Promise<{ data: T; meta: Envelope<T>['meta']; unavailable: string[] }> {
  const envelope = await client.request<Envelope<T>>('GET', path);
  return { data: envelope.data, meta: envelope.meta, unavailable: envelope.unavailable };
}

Từ đây không service nào tự gọi client.request nữa. Lớp vỏ có đổi tên trường thì sửa một chỗ.

Bước 3: mapper thuần, từ dữ liệu API sang dữ liệu hiển thị

Component không nên phải biết "null nghĩa là chưa có dữ liệu" hay "làm tròn mấy chữ số". Đó là việc của mapper, một hàm thuần không gọi mạng, không đụng React:

interface LocationRow { id: string; label: string; percent: number | null; percentText: string }

export function toLocationRows(api: UtilisationByLocation): LocationRow[] {
  return api.items
    .map((item) => ({
      id: item.locationId,
      label: item.name,
      percent: item.utilisation,
      percentText: item.utilisation === null ? 'Chưa có dữ liệu' : Math.round(item.utilisation * 100) + '%',
    }))
    .sort((a, b) => (b.percent ?? -1) - (a.percent ?? -1)); // địa điểm chưa có dữ liệu xuống cuối
}

Hàm thuần thì test rất rẻ: đưa vào một object, so object ra. Không cần render, không cần mock fetch. Phần lớn bug hiển thị số liệu (làm tròn, null, sắp xếp) bị bắt ở đây.

Bước 4: một interface, hai nguồn dữ liệu

interface InsightsDataSource {
  locations(scope: Scope): Promise<{ rows: LocationRow[]; asOf: string }>;
  // ...mỗi khối dữ liệu của dashboard một hàm
}

class FixtureDataSource implements InsightsDataSource {
  async locations() {
    return { rows: toLocationRows(fixture.utilisationByLocation), asOf: fixture.meta.asOf };
  }
}

class ApiDataSource implements InsightsDataSource {
  async locations(scope: Scope) {
    const res = await getData<UtilisationByLocation>('/insights/utilisation-by-location?' + scope.toQuery());
    return { rows: toLocationRows(res.data), asOf: res.meta.asOf };
  }
}

Màn hình chỉ thấy interface, qua một hook đọc từ context:

function LocationsPanel() {
  const { rows } = useLocations(); // không biết dữ liệu mẫu hay API thật
  return <RankedList rows={rows} />;
}

Chuyển nguồn dữ liệu là đổi một dòng ở chỗ khởi tạo app. Lúc chuyển sáu màn từ dữ liệu mẫu sang tầng mới, bộ test màn hình không phải sửa dòng nào mà vẫn xanh. Đó là bằng chứng rõ nhất rằng người dùng thấy đúng những gì họ thấy trước đó.

Một chi tiết nhỏ: nguồn dữ liệu mẫu trả kết quả ngay, nhưng vẫn là Promise. Nếu để nguyên, màn hình sẽ nháy trạng thái "đang tải" một nhịp dù dữ liệu đã có sẵn. Mình cho nguồn dữ liệu mẫu trả giá trị đồng bộ ở lần render đầu để không có cái nháy đó. Còn khi chuyển sang API thật, màn hình phải xử lý đủ trạng thái đang tải, lỗi, rỗng. Đó là chuyện của bài sau.

Bước 5: contract test, để hợp đồng đổi thì test đỏ

Hợp đồng API nằm trong repo dưới dạng file, nên test có thể đọc thẳng nó:

Test Bắt được gì
Mỗi endpoint trong endpoints.json có đúng một hàm client gọi nó, đúng method Backend thêm endpoint mà frontend quên, hoặc đổi GET thành POST
Mỗi file ví dụ response khớp kiểu TypeScript: không thừa khoá, không thiếu khoá Backend đổi tên trường
Không có file ví dụ nào "mồ côi" (không thuộc endpoint nào) Hợp đồng bị sửa nửa chừng
Mapper chạy được trên mọi file ví dụ Trạng thái dữ liệu lạ (toàn null, danh sách rỗng) làm mapper crash

Ví dụ test thứ hai, viết gọn:

import endpoints from '../../contracts/insights/endpoints.json';

test.each(endpoints)('ví dụ response của $path khớp với kiểu', ({ path, example }) => {
  const sample = loadExample(example);          // đọc file ví dụ
  const expected = shapeOf(path);               // một mẫu dữ liệu viết tay, đã type-check, cho kiểu tương ứng
  expect(Object.keys(sample.data).sort()).toEqual(Object.keys(expected).sort());
});

Không cần thư viện sinh code từ OpenAPI mới làm được điều này. Chỉ cần hợp đồng nằm trong repo và một vài test đọc nó.

Khi nào chưa cần làm thế này

  • App một hai màn hình, một hai endpoint: gọi API trong một custom hook là đủ.
  • API đã có OpenAPI chuẩn và bạn dùng công cụ sinh client: phần kiểu và client có sẵn, chỉ cần thêm lớp mapper.
  • Dữ liệu chỉ hiển thị nguyên trạng, không cần định dạng hay gộp: mapper sẽ chỉ là một hàm chép lại, đừng viết.

Thử ngay: mở một màn hình đang gọi API trực tiếp trong component, tìm chỗ nó tự định dạng số hoặc tự xử lý null. Tách đúng phần đó ra một hàm thuần và viết một test cho trường hợp null. Thường là chỗ đó đang có bug chưa ai thấy.

Bài sau trong series: mock không chỉ để trả dữ liệu đẹp. Cách "phát lại" trạng thái đang tải, lỗi, rỗng để màn hình không vỡ lúc chuyển sang API thật. Team bạn đang giữ hợp đồng API ở đâu, file OpenAPI, Postman hay trong đầu backend? Comment cho mình biết với.

P.S. Tách "nguồn dữ liệu" ra sau một interface là một quyết định về ranh giới module. Mình hay hỏi skill codebase-design trong PrimeKit, bộ skill mình tự làm, trước khi tách: nên đặt ranh giới ở đâu, interface có "sâu" không hay chỉ là một lớp bọc mỏng, và cách tách để code dễ test hơn. Cài bằng npx @lovehlmmm/primekit init, rồi gõ /pk:codebase-design kèm phần code định tách. Quyết định có tách hay không vẫn tuỳ quy mô app của bạn.


Series khác của mình


All rights reserved

Viblo
Hãy đăng ký một tài khoản Viblo để nhận được nhiều bài viết thú vị hơn.
Đăng kí