Khám Phá Những Cạm Bẫy Khi Sử Dụng OpenAPI Client Generator Với TypeScript

Khi bạn xây dựng các client REST API (hoặc server) bằng TypeScript, bạn mong đợi sự an toàn về kiểu dữ liệu sẽ giúp bạn tránh khỏi những rắc rối. Tuy nhiên, hầu hết các công cụ chuyển đổi OpenAPI sang TypeScript hiện có đều mang đến một cảm giác an toàn giả tạo, ẩn giấu những cạm bẫy có thể gây ra sự cố trong môi trường sản xuất. Sau khi đánh giá hơn 20 công cụ, tôi đã tìm ra những vấn đề lớn và cách khắc phục chúng.

Các Vấn Đề Chính Với OpenAPI Client Generators

1. Xử Lý Lỗi Kém

Khi gọi hàm:

typescript Copy

const ret = await api.post({ ... })

Bạn sẽ nghĩ rằng điều này là an toàn, nhưng chữ ký của phương thức thường bỏ qua các vấn đề mạng như lỗi DNS hoặc thời gian chờ. Bạn buộc phải bọc nó trong một khối try/catch, nhưng không có tài liệu rõ ràng về những lỗi nào có thể xảy ra, bạn sẽ phải đoán. Ngay cả khi có tài liệu, phương pháp này cũng rất mong manh và ngăn cản việc xử lý lỗi hiệu quả vì các lỗi xác thực (theo các thông số kỹ thuật OpenAPI) lại bị gộp vào cùng một nhóm với các lỗi mạng.

2. Xử Lý Trạng Thái HTTP Hạn Chế

Hầu hết các công cụ tạo mã chỉ phát sinh các kiểu dữ liệu cho các phản hồi 2xx, bỏ qua các lỗi 4xx/5xx với các payload cụ thể. Nếu API trả về mã 400 hoặc 500 với một ProblemJson, các kiểu TypeScript được tạo ra (và/hoặc các schema runtime) sẽ không phản ánh điều đó, để lại bạn dễ bị tổn thương với những bất ngờ trong thời gian chạy.

3. Nhiều Phản Hồi Thành Công, Khác Nhau Về Payload

Một số API trả về các payload khác nhau cho mã trạng thái 200 và 201. Nhiều client được tạo chỉ xử lý mã trạng thái thành công đầu tiên. Các client khác hoặc coi các phản hồi không phải 200 là lỗi, không xác định hoặc gộp chúng vào một union mơ hồ như SomeModel | SomeOtherModel, buộc bạn phải thực hiện các kiểm tra runtime thêm để phân biệt. Vậy thì việc sử dụng mã được tạo ra có ý nghĩa gì?

4. Xử Lý Các Phản Hồi Mặc Định Không Chính Xác

Các công cụ thông minh nhất tạo ra union phân biệt cho tất cả các loại phản hồi (200, 201, 400, 500, v.v.), nhưng các phản hồi mặc định (bao gồm các trường hợp không xác định trong OpenAPI) thường bị coi là lỗi chung và/hoặc thiếu kiểu payload và xác thực, dẫn đến các kiểu không chính xác.

5. Bỏ Qua Content-Type

Các API trả về nhiều loại nội dung cần phải phân biệt theo cả mã trạng thái và content-type. Theo kiến thức của tôi, không có công cụ TypeScript nào hiện tại hỗ trợ điều này. Lý tưởng nhất, bạn nên có thể viết:

typescript Copy

if (r.status === 200) {
 if (r.contentType === "application/json") {
    // TypeScript nên biết rằng r.data là SomeJsonModel
  } else if (r.contentType === "application/xml") {
    // TypeScript nên biết rằng r.data là SomeXmlModel
  }
}

6. Không Khớp Giữa OpenAPI Schema và TypeScript

Các schema OpenAPI có khả năng biểu đạt hơn các kiểu TypeScript. Ví dụ, một schema định nghĩa một chuỗi email hoặc mẫu regex thường trở thành một chuỗi đơn giản trong TypeScript. Ngay cả các công cụ có xác thực runtime cũng gặp khó khăn trong việc hỗ trợ các tính năng OpenAPI tiên tiến như mẫu chuỗi hoặc oneOf so với anyOf, dẫn đến các kiểu không chính xác và lỗi runtime.

Thực Hành Tốt Nhất Để Sử Dụng OpenAPI Trong TypeScript

Đọc Tài Liệu Cẩn Thận: Đảm bảo bạn hiểu các thông số kỹ thuật OpenAPI mà bạn đang làm việc.
Xác Thực Thông Tin Đầu Vào: Đảm bảo rằng bạn thực hiện xác thực cho mọi thông tin đầu vào mà API của bạn nhận được.
Kiểm Tra Lỗi Kỹ Lưỡng: Luôn luôn bọc các cuộc gọi API của bạn trong try/catch và xử lý các lỗi một cách cẩn thận.
Sử Dụng TypeScript Để Kiểm Tra Kiểu: Tận dụng tính năng kiểm tra kiểu của TypeScript để đảm bảo rằng các kiểu dữ liệu được xử lý chính xác.

Các Cạm Bẫy Thường Gặp

Kỳ Vọng Sai Lầm Về Kiểu Dữ Liệu: Đừng chỉ dựa vào các công cụ tạo mã để đảm bảo rằng các kiểu dữ liệu của bạn là chính xác.
Bỏ Qua Các Trạng Thái Lỗi: Luôn luôn xử lý các phản hồi không thành công từ API.

Mẹo Tối Ưu Hiệu Suất

Sử Dụng Lazy Loading: Nếu bạn có nhiều API, hãy xem xét việc tải chúng một cách lười biếng.
Caching Kết Quả: Sử dụng caching để giảm tải cho server và cải thiện hiệu suất.

Giải Quyết Vấn Đề

Nếu bạn gặp khó khăn trong việc xử lý các phản hồi từ API, hãy thử sử dụng các công cụ như Axios hoặc Fetch API để xử lý các cuộc gọi mạng một cách chính xác hơn.

Kết Luận

Sau khi đánh giá tình hình, tôi đã đối mặt với một tình huống khó khăn: thuyết phục các nhà phát triển của các công cụ hàng đầu áp dụng các thay đổi quan trọng cho hàng ngàn người dùng của họ hoặc xây dựng một giải pháp mới từ đầu. Tôi đã chọn phương án sau và xây dựng một công cụ tạo client TypeScript mã nguồn mở ưu tiên các kiểu dữ liệu chính xác và trải nghiệm phát triển tuyệt vời:

Apical TS

Bạn có đau đầu nhất với điều gì khi sử dụng các client/server OpenAPI được tạo ra? Hãy cho tôi biết ý kiến của bạn để hình thành dự án này, để lại một bình luận hoặc kiểm tra prototype!

Những cạm bẫy khi sử dụng OpenAPI với TypeScript