Hướng dẫn thiết kế API thu hút nhiều người dùng hơn

Blog IT

Vì những lập trình viên khác sẽ sử dụng API bạn làm ra, và sẽ kéo đến đốt nhà bạn nếu API bạn viết ra như c*c. Nên hãy làm cho đàng hoàng nhá.

Sau đây là một số thủ thuật tôi góp nhặt được sau nhiều năm làm việc và cọ sát với đồng nghiệp. Những thủ thuật nào có thể áp dụng được với tất cả kiểu API: thư viện nguồn mở, internal SDKs, module hoặc thậm chí là class đơn nhất.

Thật rõ ràng

Đây có lẽ là thủ thuật quan trọng nhất cần nhớ. Nếu bạn có một method tên getUser mang theo một số tác dụng phụ mà không nói rõ, người dùng sẽ gặp rất nhiều vấn đề.

Dừng chỉnh sửa shared mutable state mà không nói rõ ra. Nếu tôi call getUser, tôi sẽ mong đợi kết quả user, không phải tăng user_id lên 1 kèm theo. Bạn cũng có thể xem xét sử dụng immutable data structures.

Bạn muốn encode bao nhiêu hành vi vào tên method/class/module cũng được, nhưng phải có một giới hạn hợp lý. Đừng mong đợi người dùng sẽ “lặn ngụp” trong code nguồn để “khám phá” những gì tên method/class/module không nhắc đến.

Làm sao để API càng nhỏn gọn càng tốt

Chả ai thích chương trình “phù lũng” cả, càng dùng ít API để đạt được mục tiêu, mọi người càng có trải nghiệm tốt hơn.

Nếu ai đó thực sự hỏi API mới kia bạn đang muốn viết? Bạn có thể trì hoãn cho đến khi đó thực sự là vấn đề mà nhiều người muốn được giải quyết.

Trong một số môi trường lập trình như Android, luôn có giới hạn cụ thể tổng số method một ứng dụng được có, nên bạn phải chú ý khi tập trung vào những platform này.

Thêm tính năng quá vội vàng sẽ tốn mất của bạn nhiều tiến đồng hồ ngồi code mà chả giải quyết được nhiều.

Ít dùng boilerplate

Xử lý càng nhiều chi tiết trong thao tác trước khi đến tay người dùng càng tốt. Người dùng càng ít phải thao tác phức tạp, bạn càng tránh gặp bug hơn.

Còn có nhiều nghi vấn về tính thẩm mỹ. Việc phải viết boilerplate có thể phá hỏng một API hoàn hảo (nếu không có boilerplate) và khiến người dùng code xấu hơn. Tất cả chúng ta đều thích code sạch, đúng không nào? Hãy chiều lòng người dùng, giữ code cho gọn gàng sạch sẽ trong API của mình.

Giảm lượng dependencies

Hãy đảm bảo code của bạn càng khép kín càng tốt. Bạn càng dùng nhiều dependencise, code đầu của người dùng sẽ gặp càng nhiều vấn đế tìm ẩn.

Nếu bạn muốn một tính năng rất cần thiết từ một module nào đó, hãy chịu khó extract ra trước và chỉ thêm vào những denpendencies nào bạn cần.

Bạn phải đưa ra quyết định, và cân bằng giữa code re-use và tách code. Nếu tính năng không lớn, bạn hoàn toàn có thể tự tái triển khai.

Trả error states có ý nghĩa

Tôi có thể lải nhải cả ngày null là một construct vô dụng đến thế nào. Nó đúng nghĩa là không có gì luôn.

“Này module, cho tôi một user”

“Không được rồi. Lấy không có gì tạm vậy”

Như vậy, tôi chả biết được chuyện gì đang xảy ra cả, tôi cũng không biết phải làm gì để giải quyết vấn đề. Nếu chúng ta có một phương pháp hiển thị error state khoa học khi có vấn đề nhưError.USER_NOT_CREATED hoặc Error.USER_DELETED,. Như vậy, tôi có được nhiều dữ liệu hữu ích hơn và có thể debug dễ dàng hơn.

Error message cũng nên đi theo cùng một kết cấu. Bạn cần phải login để thao tác tiếp vẫn tốt hơn là LOL! Có gì đó không ổn.

Giữ exceptions chỉ cho những trường hợp quan trọng

Nếu ngôn ngữ của bạn không có exception, quá tốt! Dù gì thì các kiểu Either và cohort của chúng trong functional language cung cấp error states ý nghĩa hơn nhiều.

Exceptions thường bị lạm dụng nặng nề trong môi trường Java. Exceptions chỉ nên được dùng để xử lý các trường hợp thật sự đặc biệt. Bạn không mong đợi rằng getUser không tìm được user? Đừng throw UserNotFoundException, mà hãy dùng error state phù hợp.

Tuy nhiên, nếu thật sự bị lỗi, thì bị lỗi cho nhanh vẫn tốt hơn.

Như Jake Wharton từng nói:

“Thứ duy nhất tệ hơn một chương trình bị crash là một chương trình không crash mà tiếp tục trong indeterminate (vô định) state.”

Document tất tần tật

Công việc document vô cùng nhàm chán, và như bao thứ nhàm chán khác, lại rất cần thiết. Một chương trình với document tốt sẽ cứu rỗi tinh thần của bạn. Bạn sẽ giảm bớt lượng câu hỏi khồng lồ của người dùng về API của bạn, vì dù gì thì “thời gian là vàng bạc” mà.

Document tốt cần có:

Tổng quan chi tiết và cách làm việc của module
Javadocs, Heredocs, Rdocs hoặc bất cứ thông tin gì về public method và protocols.
Code mẫu thể hiện cách sử dụng.

Không phải tất cả cái gì trùy tượng đều ưu cầu cùng một mức document như nhau. Ví dụ như, một class be bé cũng chả cần code mẫu làm gì.

Documentation cần được làm mới liên tục. Nếu bạn nhận được nhiều câu hỏi về cùng hỏi một thứ, bạn có thể thêm vào doc để giải thích cho người dùng mới.

Quá nhiều document cũng sẽ lãng phí thời gian. Và có nhiều phần vô dụng vì chả ai dùng đến cả. Hãy thật sự document những gì hữu ích.

Viết tests

Test có thể đảm bảo độ chính xác, document, sample, tất cả trong một. Chúng cung cấp rất nhiều giá trị khi refactor và cho phép bạn đi nhanh và mạnh khi phải thay đổi thứ gì đó.

Những ai muốn đào sâu hơn vào công cụ của bạn có thể đọc test để hiểu thêm về mục đích và hành vi bên trong của code của bạn. Doumentation không thể bao quát mọi thứ, và test sẽ phần nào giúp đỡ document.

Nhiều bạn có lẻ sẽ hỏi “Vậy đã có test rồi thì tôi viết document làm gì nữa?”. Chỉ so sánh nhẹ thôi nhé, nếu document là user manual của API, thì test sẽ là x86 opcode instruction reference.

Làm sao để dễ test

Tự test code của mình là một chuyện. Viết API để người dùng cũng có thể test code là một chuyện hoàn toàn khác. API khó mock/stub trong các trường hợp test sẽ xua đi nhiều bạn lập trình viên tiềm năng.

Bạn có thể sử dụng nhiều tùy chọn config để debug và productions versions ở những chỗ dùng được. Và nên nhớ, nhiều điều sẽ phải vận hành khác đi trong môi trường Continuous Integration/Continuous Deployment so với production.

Quyền tự do lựa chọn

Không phải người dùng nào cũng muốn sử dụng API của bạn theo cùng một cách. Một số người có thể muốn synchronous (đồng bộ). Số khác lại thích callbacks, futures, promises, or Rx observables async (không đồng bộ).

Hãy cho người dùng quyền thoải mái chọn lựa họ muốn gì. API của bạn càng dễ tích hợp và chương trình và môi trượng họ đang sử dụng, thì bạn sẽ càng thu hút được nhiều người dùng hơn.

Đừng để người dùng lựa chọn quá nhiều

Đừng quăng quá nhiều tùy chọn vào mặt người dùng nếu bạn không muốn họ tối tăm mặt mày trước quá nhiều tinh chỉnh phức tạp. Luôn luôn cố gắng để một số thứ về mặc định. Đa phần, API của bạn sẽ được sử dụng theo một hướng nhất định. Và hãy chỉnh mặc định đi theo hướng này.

APIs nên khuyển khích hành vi kiểu mẫu. Đừng để người dùng tinh chỉnh vài state ngẫu nhiên nào đó trong module nếu đó không phải là một phần của API contract. Nếu để lộ ra một vài hành vi kỳ lạ không mong muốn, bạn có thể chắc chắn rằng nó sẽ được dùng một ngày nào đó, và sinh ra hậu quả không lường được.

Hãy kiên định, đừng để lộ quá nhiều tùy chỉnh gây mất tập trung. Cân bằng vừa phải số lượng ý kiến và lượng linh hoạt không phải dễ dàng.