Làm sao để thiết kế API chỉn chu và chuyên nghiệp

Những dev khác sẽ phải dùng API bạn viết ra. Thế nên đừng để nó lộn xộn như đống rác. Nếu bạn không muốn nhà bạn sáng nhất đêm nay, thì bạn phải thiết kế nó một cách đúng đắn.

Một số phương thức thiết kế sau được chọn lọc từ các developer đầy kinh nghiệm qua nhiều năm. Họ đã ứng dụng các phương thức này vào mọi kiểu thiết kế API: open source libraries (thư viện mã nguồn mở), internal SDKs (lõi bộ nguồn công cụ phát triển phần mềm), một modules hoặc ngay cả 1 class đơn lẻ.

Phải tường minh.

Đây có lẽ là phần quan trọng nhất. Nếu bạn có một hàm là getUser và nó một số tác dụng phụ đi kèm, thì đó có thể gây ra rất nhiều vấn đề. Đừng bao giờ chia sẻ một trạng thái có thể thay đổi khi chưa rõ ràng về nó. Nếu tôi gọi getUser, thì tối chỉ muốn nó trả lại một user, chứ không tăng user_id lên 1 khi đó. Bạn có thể xem thêm về  immutable data structuresđể hiểu. Hạn chế việc mã hóa tên các hàm/class/modules. Đừng trông mong người dùng mò lại source để bóc tách những hành vi ẩn nếu tên của chúng không rõ ràng. Bạn có thể lưu lại rất nhiều phiền hà trong dòng code bạn viết.

Giữ cho phạm vi thiết kế API đủ nhỏ.

Không ai muốn một phần mềm cồng kềnh. Càng ít API được bạn sử dụng càng cho trải nghiệm tốt hơn với người dùng. Thực sự có ai đó cần API mà bạn muốn viết ra hay không? Bạn hoàn toàn có thể hoãn lại nó cho đến khi có người cần đến nó để giải quyết vấn đề của họ.

Trong một số môi trường lập trình như Android, số phương thức của một ứng dụng có thể khai báo bị giới hạn, vì vậy sẽ có một số bạn cần ghi nhớ khi nhắm vào những nền tảng phát triển kiểu vậy. Để tránh mệt mỏi về tổng số thời gian phát triển lãng phí, hãy trau dồi thêm về YAGNI.

Giảm thiểu phần cung cấp sẵn.

Hãy xử lí thêm chi tiết phần phát triển bên trong để giảm gánh nặng cho khánh hàng. Người dùng càng ít động tay vào, số lượng lỗi bạn phải đối mặt càng ít. Ở đây còn cả vấn đề về mặt thẩm mỹ. Khi bạn phải dùng những bản viết sẵn có thể phá hỏng cấu trúc của thiết kế API và làm xấu code. Ai cũng thích code sạch, đúng chứ? Hãy làm cho khách hàng của bạn dễ dàng hơn trong việc giữ code sạch đẹp khi dùng thiết kế API của ban.

Giảm thiểu việc phụ thuộc.

Cố gắng cho code của bạn độc lập hết sức có thể. Càng nhiều phần phụ thuộc bạn bày ra, khả năng càng cao các lỗi sẽ xuất hiện khi khách hàng sử dụng sau này. Nếu bạn thực sự muốn dùng một đoạn code chạy ổn nào đó trong code từ modules khác. Hãy cố gắng tách nó ra thành một phần mở rộng và chỉ sử dụng nó khi nào thực sự cần.

Trả lại lỗi dễ hiểu.

Tôi có thể bỏ cả ngày để nói việc giá trị null vô dụng thế nào trong rất nhiều trường hợp. Nó thực sự theo nghĩa đen là không gì cả. 

Nó không cho tôi thông tin nào về cái gì đang chạy sai và tôi có thể làm gì trong tình huống đó. Nếu chúng ta thay thế bằng lời giải thích cho lỗi đó như Error.USER_NOT_CREATED or Error.USER_DELETED thì sẽ cung cấp nhiều thông tin hưu ích hơn nhiều cho việc debug. Các mẩu thông báo lỗi cũng nên đưa ra theo một lời hướng dẫn thống nhất. “Bạn cần đăng nhập trước khi thao tác” sẽ tốt hơn nhiều “LOL! Something went wrong.”

Lưu lại lỗi cho trường hợp lỗi thực sự.

Nếu ngôn ngữ của bạn không có lỗi, hãy vui mừng lên. Cẩ loại hoặc nhóm trong ngôn ngữ hàm đó đều sẽ cung cấp trạng thái lỗi có ý nghĩa hơn nhiều. 

Exceptions có xu hướng bị lạm dụng trong ngôn ngữ Java. Exceptions được dùng để xử lí một trạng thái thực sự ngoại lệ. Bạn có thực sự không mong muốn hàm getUser sẽ không trả về một user? Đừng trả về một ngoại lệ là Không tìm thấy user. Hãy trả về một trạng thái lỗi thích hợp thay thế (Tên người dùng không tồn tại chẳng hạn).

Hãy nhớ rằng: “Thứ duy nhất tệ hơn một chương trình crash là một chương không crash mà cứ chạy tiếp trong một trạng thái không xác định.”

Tài liệu hóa mọi thứ.

Tài liệu là một thứ nhàm chán. Và như phần nhiều những thứ nhàm chán khác, nó là cần thiết. Tài liệu tốt sẽ cứu vãn sự tỉnh táo của bạn. Bạn sẽ trành được những câu hỏi liên tiếp từ khách hàng về thiết kế API của bạn, và chỉ mình điều đó thôi đã có giá trị như vàng.

Tài liệu tốt nên có:

• Một cái nhìn tổng quan về modules và việc nó hoạt động như thế nào
• Mọi thứ về những phần khả dụng.
• Code ví dụ đơn giản về việc sử dụng nó như thế nào

Không phải mọi thứ trừu tượng đều cần tài liệu đồng cấp cho nó. Một class nhỏ chẳng hạn, chẳng cần một đoạn code ví dụ cho nó đâu. Tài liệu cũng phải được phát triển và cập nhật. Nếu bạn liên tục được hỏi về cùng một vấn đề, hãy cho nó vào tài liệu cho khách hàng tương lai của bạn. Quá nhiều tài liệu cũng sẽ làm tốn thời gian, nếu bạn phải liên tục cập nhật cho nó. Nó sẽ chẳng có giá trị gì cả nếu không ai dùng. Dù sao thì tài liệu đầy đủ và tập trung vào một vấn đề luôn có ích.

Viết test cho code của mình.

Tests là minh chứng cho sự việc code chạy đúng, cho tài liệu và cả đống ví dụ. Nó sẽ mang giá trị cực lớn khi bạn sắp xếp lại code và cho bạn tự tin hơn khi chuyển dịch một phần nào đó. Khách hàng của bạn nếu muốn tìm hiểu sâu về những gì bạn làm luôn có thể đọc test để hiểu hơn những ý định và hành vi bên trong code của bạn. Tài liệu không thể đảm đương mọi thứ, và đây là chỗ mà test có thể bù đắp.

Bạn có thể thắc mắc “Vì sao viết tài liệu thôi là chưa đủ mà phải làm cả test?”. Nếu dùng một ví dụ cụ thể để miêu tả, thì tài liệu sẽ là Hướng dẫn sử dụng, còn tests sẽ là miêu tả cụ thể cho từng trường hợp.

Làm cho nó có thể test được

Test code là một chuyện, Viết nó cho người khác có thể test nó lại là một chuyện khác. Người lập trình quan tâm đến việc test sẽ làm cho API khó bị gỡ bỏ/ghi đè trong test. Bạn có thể sử dụng cấu hình tùy chọn để debug cho các sản phẩm với phiên bản phù hợp. Mọi thứ trong môi trường hội nhập liên tục / triển khai liên tục thường khác biệt hơn một chút so với môi trường sản xuất. Hãy ghi nhớ điểm này

Cho phép người dùng lựa chọn

Không phải tất cả người dùng đều muốn sử dụng API theo một cách giống nhau. Một số muốn sử dụng nó theo hướng đồng bộ. Một số khác thì lại ưu tiên sự callbacks bất đồng bộ ,  futures, promises, hoặc Rx observables. Hãy cho phép người dùng khả năng lựa chọn theo ý thích của họ nhiều nhất họ có thể. Thiết kế API của bạn càng dễ dàng  tích hợp vào môi trường lập trình bao nhiêu thì người dùng càng yêu thích bấy nhiêu

Không cho phép người dùng lựa chọn quá nhiều

Đừng cho người sử dụng quá nhiều sự lựa chọn khiến họ chìm sâu vào việc phân tích. Luôn cố gắng cung cấp những cài đặt mặc định hợp lý. Phần lớn API của bạn sẽ được sử dụng theo một cách nhất định. Hãy biến cách mặc định trở thành cách được sử dụng nhiều nhất. Việc thiết kế API nên khuyến khích các hành vi theo quy tắc. Không nên để người dùng tùy ý chỉnh sửa một số trạng thái ngẫu nhiên trong mô-đun nếu đó không phải là một phần của hợp đồng sử dụng API. Nếu bạn để hở một số hành vi lạ lùng không theo quy tắc , bạn có thể yên tâm là nó sẽ được người dùng sử dụng và gây một số hậu quả nhất định

Hãy có chính kiến. Đừng mất tập trung bằng việc đưa ra quá nhiều sự lựa chọn. Hãy cân bằng những lựa chọn với mức độ linh hoạt và kinh nghiệm thực tế. Khi có sự nghi ngờ , lỗi lầm thuộc về phía những lựa chọn ít hơn

Kết luận

Thiết kế API là một nghệ thuật. Hi vọng những thủ thuật được nêu trên sẽ giúp bạn viết code một cách tốt hơn! Hãy cố gắng đọc và thưởng thức nhé 

Nguồn: Medium