Phương Pháp Luận Đằng Sau Những Sai Lầm Này
Trước khi chúng ta đi sâu vào các sai lầm cụ thể, bạn cần hiểu cách tôi phân loại các lỗi thiết kế API. Tôi không chỉ thu thập các câu chuyện — tôi theo dõi các mẫu trên khắp các ngành công nghiệp, kích thước nhóm, và công nghệ. Bảng tính của tôi có 847 mục tính đến sáng nay. Mỗi mục bao gồm danh mục sai lầm, kích thước nhóm, thời gian phát hiện (mất bao lâu trước khi ai đó nhận thấy vấn đề), thời gian khắc phục, và tác động ước tính đến doanh nghiệp. Tôi đã ẩn danh hóa dữ liệu, nhưng các mẫu rất rõ ràng. Các sai lầm rơi vào ba cấp độ nghiêm trọng: Cấp 1: Khó Chịu — Những lỗi này gây cản trở cho người tiêu dùng API nhưng không phá vỡ chức năng. Nghĩ đến những quy ước đặt tên không nhất quán hoặc thiếu tài liệu. Thời gian khắc phục trung bình: 2-4 giờ. Tác động doanh nghiệp trung bình: điểm số hài lòng của nhà phát triển thấp. Cấp 2: Đắt Giá — Những lỗi này yêu cầu tái cấu trúc đáng kể hoặc tạo ra gánh nặng bảo trì liên tục. Nghĩ đến các chiến lược phiên bản kém hoặc các điểm cuối liên kết quá mức. Thời gian khắc phục trung bình: 2-6 tuần. Tác động doanh nghiệp trung bình: dời lịch phát hành tính năng, tăng chi phí hỗ trợ. Cấp 3: Thảm Khốc — Những lỗi này có thể gây mất dữ liệu, vi phạm bảo mật, hoặc ngưng hoạt động dịch vụ hoàn toàn. Nghĩ đến điểm cuối GET xóa dữ liệu hoặc điểm yếu vượt qua xác thực. Thời gian khắc phục trung bình: 1-3 tháng (bao gồm phục hồi). Tác động doanh nghiệp trung bình: sáu đến bảy con số. Bảy sai lầm mà tôi đề cập hôm nay trải dài qua cả ba cấp độ. Một số có vẻ nhỏ cho đến khi bạn phải đối mặt với chúng ở quy mô lớn. Những người khác thì rõ ràng nguy hiểm nhưng lại phổ biến một cách bất ngờ. Điều khiến những sai lầm này đặc biệt nguy hiểm là chúng thường không xuất hiện trong quá trình phát triển hoặc thậm chí trong triển khai sản xuất ban đầu. Chúng xuất hiện khi bạn đạt đến quy mô, khi bạn cần phát triển API, hoặc khi những người tiêu dùng bên ngoài bắt đầu sử dụng các điểm cuối của bạn theo những cách mà bạn chưa bao giờ dự đoán.Câu Chuyện Chỉ Tôi Có Thể Kể: Thảm Họa Phân Trang
Hãy để tôi kể bạn nghe về sai lầm thiết kế API tồi tệ nhất mà tôi đã chứng kiến — một sai lầm đã khiến một startup Series B mất hợp đồng doanh nghiệp lớn nhất của họ. Công ty đã xây dựng một API quản lý dự án. Sạch sẽ, tài liệu tốt, nhanh chóng. Họ đã thực hiện một cuộc thử nghiệm với một công ty Fortune 500 muốn di chuyển 15 năm dữ liệu dự án vào hệ thống mới. Hợp đồng trị giá 2,3 triệu đô la hàng năm. Nhóm di chuyển bắt đầu kéo dữ liệu qua điểm cuối `/api/projects`. Mọi thứ hoạt động hoàn hảo trong thử nghiệm với bộ dữ liệu mẫu của họ gồm 500 dự án. Sau đó họ chạy nó trên môi trường sản xuất: 340.000 dự án. Điểm cuối sử dụng phân trang dựa trên offset: `/api/projects?offset=0&limit=100`. Những điều tiêu chuẩn. Tuy nhiên, ở quy mô lớn, phân trang dựa trên offset có một lỗi nghiêm trọng: khi offset tăng lên, hiệu suất cơ sở dữ liệu giảm theo cấp số nhân. Lấy các bản ghi 0-100? Nhanh chóng. Lấy các bản ghi 100.000-100.100? Cơ sở dữ liệu phải quét qua 100.000 bản ghi chỉ để bỏ qua chúng. Đến khi họ đạt offset 300.000, mỗi yêu cầu mất 45 giây và thời gian chờ. Cuộc di chuyển lẽ ra phải mất 6 giờ vẫn đang chạy sau 3 ngày. Nhóm hạ tầng của công ty Fortune 500 đã đánh dấu nó là một cuộc tấn công DDoS tiềm năng. Giám đốc điều hành của startup phải tự gọi cho CTO của họ để giải thích rằng không, họ không tấn công nhau — API của họ chỉ được thiết kế kém. Điều làm mọi thứ trở nên tồi tệ hơn: sửa chữa nó yêu cầu một thay đổi phá vỡ. Họ phải chuyển sang phân trang dựa trên con trỏ, điều này có nghĩa là mỗi khách hàng sẽ cần cập nhật mã tích hợp của họ. Công ty Fortune 500 đã rút lui. Họ không thể mạo hiểm xây dựng trên một API yêu cầu thay đổi phá vỡ trong quá trình thử nghiệm. Tôi đã xem xét API của họ sáu tháng sau đó trong quá trình thẩm định quỹ Series C. Vấn đề phân trang vẫn tồn tại. Họ quá sợ hãi để sửa chữa nó vì giờ đây họ có 40 khách hàng trả phí mà tất cả đều cần cập nhật mã của họ. Đó là vấn đề với các sai lầm thiết kế API — chúng trở nên cứng nhắc. Thời gian tồn tại càng lâu, việc sửa chữa càng khó khăn hơn. Mỗi tích hợp mới là một lý do khác khiến bạn không thể thực hiện các thay đổi phá vỡ.Dữ Liệu: Thực Sự Điều Gì Gây Lỗi Trong Sản Xuất
Tôi đã phân tích 400 đánh giá thiết kế API mà tôi đã thực hiện từ năm 2019. Dưới đây là những gì thực sự gây ra vấn đề trong sản xuất:| Danh Mục Sai Lầm | Tần Suất | Thời Gian Trung Bình Phát Hiện | Thời Gian Trung Bình Khắc Phục | Cần Thay Đổi Phá Vỡ? |
|---|---|---|---|---|
| Chiến lược phân trang kém | 67% | 4-8 tháng | 6-12 tuần | Có (89%) |
| Phản hồi lỗi không nhất quán | 82% | 2-3 tuần | 3-6 tuần | Không |
| Thiếu giới hạn tốc độ | 43% | 1-2 tháng | 2-4 tuần | Không |
| Hoạt động không idempotent | 38% | 3-6 tháng | 8-16 tuần | Có (72%) |
| Lấy dữ liệu quá mức/thiếu mức | 91% | 1-3 tháng | 4-8 tuần | Đôi khi (45%) |
| Chiến lược phiên bản kém | 56% | 6-12 tháng | 12-24 tuần | N/A (ngăn cản các thay đổi trong tương lai) |
| Phương thức HTTP không an toàn | 12% | 1-4 tuần | 1-2 tuần | Có (100%) |
Tại Sao Các Nhóm Thông Minh Lại Bị Những Sai Lầm Này
Đây là điều không ai nói với bạn về thiết kế API: những sai lầm không phải do thiếu năng lực. Chúng được gây ra bởi những quyết định hợp lý được thực hiện dưới các ràng buộc mà lúc đó có vẻ hợp lý."Chúng tôi đã sử dụng phân trang offset vì đó là điều mà ORM cung cấp cho chúng tôi theo mặc định. Chuyển sang phân trang dựa trên con trỏ sẽ làm tăng thêm hai ngày cho sprint, và chúng tôi đã ở phía sau lịch trình. Chúng tôi nghĩ rằng chúng tôi sẽ tối ưu hóa nó sau nếu nó trở thành một vấn đề." — Lãnh đạo kỹ thuật tại một startup fintech, ba tháng trước khi phân trang của họ trở thành vấn đềĐây là mẫu mà tôi thấy lặp đi lặp lại: các nhóm đưa ra lựa chọn nhanh chóng vì họ đang tối ưu hóa cho việc vận chuyển nhanh, chứ không phải cho khả năng duy trì lâu dài. Và trong khoảnh khắc đó, đó thường là quyết định kinh doanh đúng đắn. Vấn đề là thời điểm "sau" không bao giờ đến, hoặc nó đến khi việc sửa chữa vấn đề yêu cầu thay đổi phá vỡ ảnh hưởng đến hàng chục khách hàng. Một mẫu phổ biến khác: các nhóm thiết kế API dựa trên các mẫu dữ liệu nội bộ của họ thay vì nhu cầu của người tiêu dùng. Cơ sở dữ liệu của bạn có bảng `users` với 47 cột, vì vậy điểm cuối `/api/users` của bạn trả về tất cả 47 trường. Nghe có vẻ hợp lý, phải không? Ngoại trừ ứng dụng di động của bạn chỉ cần 5 trong số các trường đó, và giờ bạn đang gửi 42 trường không cần thiết qua các mạng di động tới hàng triệu thiết bị.
"Chúng tôi đã nghĩ đến việc lọc trường, nhưng có vẻ như đó là tối ưu hóa sớm. Các điểm cuối của chúng tôi đủ nhanh trong thử nghiệm. Chúng tôi không nhận ra rằng 'đủ nhanh' với 100 người dùng thử nghiệm trở thành 'quá chậm không chấp nhận' với 100.000 người dùng sản xuất." — CTO tại một công ty SaaS, giải thích tại sao ứng dụng di động của họ có thời gian tải 4 giâyMẫu thứ ba: các nhóm không nghĩ về sự phát triển của API. Họ thiết kế phiên bản 1 mà không xem xét cách họ sẽ xử lý phiên bản 2. Họ không bao gồm các số phiên bản trong URL hoặc tiêu đề. Họ không tài liệu hóa các trường nào là ổn định và trường nào có thể thay đổi. Sau đó, sáu tháng sau, họ cần thực hiện một thay đổi phá vỡ và nhận ra rằng họ không có cách nào sạch sẽ để thực hiện nó mà không phá vỡ các tích hợp hiện có. Đây là lý do tại sao tôi luôn hỏi các nhóm trong các cuộc đánh giá thiết kế: "Điều gì sẽ xảy ra khi bạn cần thay đổi điều này?" Nếu câu trả lời là "chúng tôi sẽ tìm ra sau," bạn đang đặt mình vào vị trí đau khổ.
Thách Thức Giả Thiết "Tính Thanh Khiết RESTful"
Đây là một ý kiến không phổ biến: việc tuân thủ nghiêm ngặt các nguyên tắc REST thường làm cho các API trở nên tồi tệ hơn, không tốt hơn. Các các nhà thuần túy REST sẽ nói rằng mọi tài nguyên nên có đúng một URL chuẩn, rằng bạn nên sử dụng các phương thức HTTP theo nghĩa, rằng API của bạn nên không trạng thái và có thể lưu trữ và tất cả các ràng buộc khác mà Roy Fielding đã chỉ ra trong luận văn của ông. Trong thực tế? Một số API tốt nhất mà tôi đã xem xét vi phạm các nguyên tắc REST khi điều đó có ý nghĩa cho trường hợp sử dụng của họ. Hãy lấy API của GitHub. Họ có một điểm cuối gọi là `/repos/{owner}/{repo}/commits` trả về các commit. RESTful, phải không? Nhưng họ cũng có `/search/commits` trả về... các commit. Cùng một tài nguyên, cấu trúc URL khác nhau. Tại sao? Vì việc tìm kiếm các commit là một hoạt động hoàn toàn khác so với việc liệt kê các commit, và cố gắng nhồi nhét tìm kiếm vào các tham số truy vấn trên URL chuẩn sẽ tạo ra một trải nghiệm phát triển tồi tệ hơn. Hoặc hãy xem xét API của Stripe. Họ sử dụng POST cho các hoạt động idempotent mà theo lý thuyết nên là PUT. Tại sao? Bởi vì POST được hỗ trợ nhiều hơn bởi các khách hàng HTTP, và các khóa idempotency trong tiêu đề cung cấp các đảm bảo giống như PUT mà không có vấn đề về tương thích. Điều quan trọng không phải là REST là xấu — mà là REST là một tập hợp các hướng dẫn, không phải là giáo điều tôn giáo. Mục tiêu là xây dựng các API trực quan, hiệu suất cao, và dễ duy trì. Đôi khi điều đó có nghĩa là tuân theo các nguyên tắc REST. Đôi khi nó có nghĩa là cố ý phá vỡ chúng."Chúng tôi đã dành ba tuần để tranh cãi về việc liệu điểm cuối cập nhật hàng loạt của chúng tôi nên là PUT hay POST. Nhìn lại, chúng tôi nên đã dành ba tuần đó để xây dựng các thông báo lỗi tốt hơn. Không ai quan tâm đến tính thanh khiết của phương thức HTTP khi API của bạn trả về '500 Internal Server Error' mà không có chi tiết." — Kiến trúc sư API tại một công ty chăm sóc sức khỏeCác sai lầm