Best practice TypeScript: 8 quy tắc kèm ví dụ trước và sau

Các quy tắc dưới đây là những quy tắc ngăn được nhiều bug nhất trong code TypeScript thực tế. Mỗi quy tắc cho thấy cách viết thường gặp trước, rồi đến cách tốt hơn, bằng code bạn chạy được. Quy tắc đầu tiên quan trọng nhất: ngừng dùng any.

Dùng unknown thay cho any

any tắt kiểm tra kiểu cho một giá trị và mọi thứ được tính từ nó. unknown cũng nhận mọi giá trị, nhưng bạn phải kiểm tra trước khi dùng, nhờ đó phép kiểm tra nằm đúng ở chỗ dữ liệu đi vào chương trình:

// Before: any switches off checking for everything it touches.
function totalAny(items: any): number {
  return items.reduce((sum: number, item: any) => sum + item.price, 0);
}
console.log(totalAny([{ price: 2 }, { cost: 3 }])); // NaN, no error anywhere

// After: take unknown, check once at the boundary, then work with real types.
interface Item {
  price: number;
}

function isItems(value: unknown): value is Item[] {
  return Array.isArray(value) && value.every((i) => typeof i?.price === "number");
}

function total(input: unknown): number {
  if (!isItems(input)) throw new Error("Expected a list of items with prices");
  return input.reduce((sum, item) => sum + item.price, 0);
}

console.log(total([{ price: 2 }, { price: 3 }])); // 5
try {
  total([{ price: 2 }, { cost: 3 }]);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Expected a list of items with prices
}

Ranh giới là những nơi kiểu không còn được bảo đảm: JSON.parse, response của fetch, localStorage, dữ liệu nhập từ form, biến môi trường và thông điệp từ tiến trình khác. Hãy kiểm tra ở đó bằng type guard hoặc thư viện schema, và phần còn lại của code có thể tin tưởng kiểu của mình.

Luôn bật strict

strict là mặc định trong TypeScript 7; đừng tắt nó. Hãy thêm những phép kiểm tra mà nó bỏ qua nhưng bắt được nhiều bug nhất:

{
    "compilerOptions": {
        "strict": true,
        "noUncheckedIndexedAccess": true,
        "noImplicitOverride": true,
        "noFallthroughCasesInSwitch": true
    }
}

noUncheckedIndexedAccess khiến arr[i] và record[key] bao gồm cả undefined, đúng với giá trị chúng trả về khi chỉ số không tồn tại. noImplicitOverride buộc phương thức của lớp con ghi rõ override, còn noFallthroughCasesInSwitch từ chối một case chạy lọt sang case tiếp theo.

Để suy luận kiểu làm việc

Chú thích kiểu cho những gì TypeScript không thể biết: tham số của hàm, và kiểu trả về của các hàm mà module khác dùng. Để biến cục bộ và tham số của callback cho suy luận kiểu. Một chú thích không cần thiết không chỉ gây rối mắt; nó còn có thể khiến kiểu rộng hơn giá trị:

type Status = "active" | "banned";

function setStatus(status: Status): string {
  return `status set to ${status}`;
}

const annotated: string = "active"; // annotation widens the type to string
// @ts-expect-error string is not assignable to Status
setStatus(annotated);

const inferred = "active"; // inferred as the literal type "active"
console.log(setStatus(inferred)); // status set to active

const users = [{ id: 1, name: "Ada" }, { id: 2, name: "Lin" }];
const ids = users.map((u) => u.id); // inferred: number[]
console.log(ids); // [ 1, 2 ]

Nếu không có chú thích @ts-expect-error, setStatus(annotated) là lỗi TS2345. const được suy luận giữ kiểu literal "active", nên được chấp nhận. Di chuột lên biến trong trình soạn thảo để xem kiểu đã được suy luận trước khi bạn thêm kiểu.

Ưu tiên union type hơn enum

Một union các chuỗi literal cho khả năng tự động gợi ý và kiểm tra đầy đủ mà không sinh ra code. Khi bạn còn cần danh sách giá trị lúc runtime, hãy suy ra kiểu từ một mảng as const:

const ROLES = ["admin", "editor", "viewer"] as const;
type Role = (typeof ROLES)[number]; // "admin" | "editor" | "viewer"

function canEdit(role: Role): boolean {
  return role !== "viewer";
}

console.log(canEdit("editor"));     // true
console.log(ROLES.filter(canEdit)); // [ 'admin', 'editor' ]

canEdit("owner"); // error TS2345: Argument of type '"owner"' is not assignable to parameter of type '"admin" | "editor" | "viewer"'.

Một enum Role { Admin, Viewer } biên dịch thành một đối tượng có ánh xạ ngược, và tham số kiểu enum số nhận bất kỳ biến number nào, kể cả biến chứa giá trị mà enum không liệt kê. Enum cũng không chạy được với type stripping của Node (TypeScript enum is not supported in strip-only mode). Các đánh đổi được so sánh ở trang enum.

Kiểm tra đối tượng config bằng satisfies

Chú thích một đối tượng bằng kiểu rộng như Record<string, Route> sẽ kiểm tra giá trị nhưng quên mất các khóa. satisfies kiểm tra cùng điều đó mà vẫn giữ kiểu chính xác:

interface Route {
  path: string;
  auth: boolean;
}

// Annotated: every string key is allowed, so typos are not caught.
const loose: Record<string, Route> = {
  home: { path: "/", auth: false },
};
console.log(loose.hmoe); // undefined, and no compile error

// satisfies: checked against Route, but the exact keys are kept.
const routes = {
  home: { path: "/", auth: false },
  admin: { path: "/admin", auth: true },
} satisfies Record<string, Route>;

console.log(routes.admin.path); // /admin
// @ts-expect-error Property 'hmoe' does not exist
routes.hmoe;

Dùng chú thích kiểu khi biến cần có đúng kiểu đã khai báo (tham số của hàm, giá trị bạn sẽ gán lại). Dùng satisfies cho bảng tra cứu, bản đồ route, theme token và các đối tượng hằng khác.

Mô hình hóa state bằng discriminated union

Một đối tượng duy nhất với các field tùy chọn cho phép những trạng thái không thể xảy ra: loading: true cùng lúc với error, hoặc thiếu data sau khi thành công. Một union các đối tượng có chung một thẻ phân biệt chỉ cho phép những trạng thái thật, và mỗi nhánh chỉ thấy field của riêng nó:

type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "error"; message: string };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", "); // data exists only here
    case "error":
      return `Error: ${state.message}`;
    default: {
      const unreachable: never = state; // fails if a case is missing
      return unreachable;
    }
  }
}

console.log(render({ status: "success", data: ["a", "b"] })); // a, b
console.log(render({ status: "error", message: "timeout" }));  // Error: timeout

Dòng never là phép kiểm tra đầy đủ. Khi ai đó thêm một trạng thái mới mà quên xử lý, quá trình build sẽ hỏng tại dòng đó:

// This does not compile: a new state was added but not handled.
type RequestState =
  | { status: "loading" }
  | { status: "success"; data: string[] }
  | { status: "cancelled" };

function render(state: RequestState): string {
  switch (state.status) {
    case "loading":
      return "Loading...";
    case "success":
      return state.data.join(", ");
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

console.log(render({ status: "loading" }));

Lỗi là index.ts(14,13): error TS2322: Type '{ status: "cancelled"; }' is not assignable to type 'never'. Nó chỉ rõ trường hợp chưa được xử lý. Thêm case "cancelled": và code sẽ biên dịch được.

Tránh ! và as

Non-null assertion x! và type assertion x as T bảo trình biên dịch ngừng kiểm tra. Cả hai đều không thay đổi giá trị lúc runtime, nên một assertion sai sẽ thành lỗi crash về sau, ở xa nguyên nhân gốc:

interface User {
  name: string;
}

const users = new Map<string, User>([["ada", { name: "Ada" }]]);

// Before: ! and as silence the compiler, and the crash moves to run time.
try {
  console.log(users.get("bob")!.name);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Cannot read properties of undefined (reading 'name')
}
const fake = {} as User;
console.log(fake.name); // undefined, typed as string

// After: handle the missing case where it can happen.
const bob = users.get("bob");
console.log(bob?.name ?? "unknown user"); // unknown user

Thay ! bằng ?., ??, một return sớm, hoặc ném lỗi kèm thông báo hữu ích. Thay as bằng một type guard thực sự kiểm tra giá trị. Assertion duy nhất luôn an toàn là as const, vì nó chỉ làm kiểu hẹp hơn và chỉ đọc. Một thiết lập lint tốt (no-non-null-assertion và no-explicit-any của typescript-eslint) sẽ đánh dấu phần còn lại.

Đặt dữ liệu là readonly

Đánh dấu thuộc tính và mảng là readonly khi code không được thay đổi chúng. Khi đó trình biên dịch từ chối push, sort và các phép gán, và các hàm trả về giá trị mới thay vì sửa đổi đầu vào:

interface Settings {
  readonly theme: "light" | "dark";
  readonly tags: readonly string[];
}

function withTag(settings: Settings, tag: string): Settings {
  // settings.tags.push(tag) would not compile
  return { ...settings, tags: [...settings.tags, tag] };
}

const before: Settings = { theme: "dark", tags: ["a"] };
const after = withTag(before, "b");
console.log(before.tags, after.tags); // [ 'a' ] [ 'a', 'b' ]

// @ts-expect-error Cannot assign to 'theme' because it is a read-only property.
before.theme = "light";

readonly chỉ được kiểm tra lúc biên dịch và chỉ ở một cấp: nó không đóng băng đối tượng lúc runtime. Như vậy vẫn đủ để bắt những lần vô tình sửa đổi state dùng chung, nguyên nhân của phần lớn các bug kiểu này.