Giới thiệu

Trong bài viết này, chúng ta sẽ khám phá cách sử dụng API Extractor trong mã nguồn của dự án tldraw. Chúng ta sẽ tìm hiểu:

API Extractor là gì?
Cấu hình api-extractor.json trong mã nguồn tldraw.

API Extractor là một công cụ giúp bạn xây dựng các gói thư viện TypeScript tốt hơn. Giả sử công ty bạn đã phát hành một gói NPM có tên là awesome-widgets, chứa nhiều lớp và giao diện. Khi các nhà phát triển bắt đầu phụ thuộc vào thư viện của bạn, bạn có thể gặp phải một số vấn đề như:

Rủi ro bị hỏng không mong muốn: Người dùng báo cáo rằng mã của họ không biên dịch sau một bản cập nhật được cho là “nhỏ”. Bạn đề xuất rằng mọi yêu cầu kéo (pull request) của awesome-widgets phải được phê duyệt bởi một nhà phát triển có kinh nghiệm trong đội ngũ của bạn. Nhưng điều này không thực tế — không ai có thời gian để xem xét tất cả PR! Bạn thực sự cần một cách để phát hiện các PR thay đổi hợp đồng API và đánh dấu chúng để xem xét.
Xuất thiếu: Giả sử gói awesome-widgets xuất một hàm API AwesomeButton.draw() yêu cầu một tham số có kiểu DrawStyle, nhưng bạn quên xuất enum này. Mọi thứ có vẻ ổn lúc đầu, nhưng khi một nhà phát triển cố gắng gọi hàm đó, họ phát hiện rằng không có cách nào để chỉ định DrawStyle. Làm thế nào để tránh những sai sót này?
Xuất không mong muốn: Bạn dự định giữ lớp DrawHelper nội bộ, nhưng một ngày nọ bạn nhận ra nó đang được xuất ra. Khi bạn cố gắng xóa nó, người dùng phàn nàn rằng họ đang sử dụng nó. Làm thế nào để tránh điều này trong tương lai?
Tốt nghiệp Alpha/Beta: Bạn muốn phát hành các bản xem trước của API mới chưa sẵn sàng cho thời điểm chính. Nhưng nếu bạn thực hiện một nâng cấp SemVer lớn mỗi khi các định nghĩa này tiến triển, người dùng sẽ không hài lòng! Một cách tiếp cận tốt hơn là chỉ định một số lớp/thành viên là chất lượng alpha, sau đó nâng cấp chúng thành beta và cuối cùng thành public khi chúng trưởng thành. Nhưng làm thế nào để thông báo điều này đến người tiêu dùng của bạn? (Và làm thế nào để phát hiện các sai sót về phạm vi? Một hàm public không bao giờ nên trả về một kết quả beta.)
Tập hợp .d.ts: Bạn đã webpack thư viện của mình thành một tệp gói .js đẹp — vậy tại sao lại phát hành kiểu của bạn dưới dạng một cây lib/*.d.ts lộn xộn đầy định nghĩa nội bộ? Chúng ta không thể hợp nhất chúng thành một tệp .d.ts gọn gàng được sao? Và nếu bạn phát hành các bản nội bộ/beta/công khai, mỗi loại phát hành nên có tệp .d.ts riêng với cắt giảm phù hợp. Các nhà phát triển xây dựng một dự án sản xuất không muốn thấy nhiều thành viên nội bộ và beta trong IntelliSense của VS Code!
Tài liệu trực tuyến: Bạn đã chú thích cẩn thận mỗi thành viên TypeScript với mô tả TSDoc đẹp mắt. Giờ đây, khi thư viện của bạn đã được phát hành, đã đến lúc thiết lập một tài liệu API được định dạng đẹp. Công cụ nào sẽ được sử dụng?

API Extractor cung cấp một giải pháp tích hợp, chuyên nghiệp cho tất cả những vấn đề này. Nó được gọi khi xây dựng bởi chuỗi công cụ của bạn và tận dụng động cơ biên dịch TypeScript để:

Phát hiện bề mặt API xuất khẩu của dự án
Nắm bắt các hợp đồng trong một báo cáo ngắn gọn được thiết kế để thuận tiện cho việc xem xét
Cảnh báo về những sai lầm phổ biến (ví dụ: xuất thiếu, tính khả dụng không nhất quán, v.v.)
Tạo ra các tệp *.d.ts tổng hợp với cắt giảm theo loại phát hành
Xuất tài liệu API ở định dạng di động dễ tích hợp với quy trình nội dung của bạn

api-extractor.json trong mã nguồn tldraw

Tệp tldraw/internal/config/api-extractor.json cung cấp một giải thích chi tiết về từng tùy chọn. Bạn cũng sẽ tìm thấy api-extractor.json trong gói editor.

Thực hành tốt nhất khi sử dụng API Extractor

Đảm bảo rằng tất cả các thành phần API của bạn được tài liệu hóa đầy đủ.
Xem xét việc sử dụng các công cụ tự động hóa để kiểm tra các yêu cầu kéo.
Thường xuyên cập nhật tài liệu và cấu hình API để phản ánh chính xác tình trạng hiện tại của mã nguồn.

Những cạm bẫy phổ biến

Không chú thích đầy đủ cho các thành viên có thể dẫn đến sự hiểu lầm và khó khăn cho người dùng.
Bỏ qua việc kiểm tra tính nhất quán của các thành viên công khai và nội bộ.

Mẹo hiệu suất

Sử dụng các công cụ kiểm tra tự động để phát hiện các vấn đề về xuất khẩu và hợp đồng API.
Định kỳ xem xét và cập nhật các báo cáo API để đảm bảo chúng luôn chính xác.

Giải quyết sự cố

Nếu bạn gặp lỗi trong quá trình biên dịch, hãy kiểm tra lại cấu hình api-extractor.json và đảm bảo rằng tất cả các tham số được thiết lập đúng cách.

Kết luận

Sử dụng API Extractor trong mã nguồn của bạn không chỉ giúp bạn duy trì chất lượng mã tốt hơn mà còn cải thiện trải nghiệm của các nhà phát triển khác khi sử dụng thư viện của bạn. Hãy bắt đầu tích hợp công cụ này vào quy trình phát triển của bạn ngay hôm nay! Nếu bạn có bất kỳ câu hỏi nào, đừng ngần ngại liên hệ với chúng tôi.

FAQ

1. API Extractor có miễn phí không?
Có, API Extractor là mã nguồn mở và có thể được sử dụng miễn phí.

2. Làm thế nào để tích hợp API Extractor vào dự án của tôi?
Bạn có thể tham khảo tài liệu trên trang web chính thức của API Extractor để biết hướng dẫn chi tiết.

Sử dụng API Extractor trong mã nguồn tldraw