Khi thảo luận giữa các hệ thống API (vào mức độ kinh doanh) thường có hai quan điểm khác nhau trong đội ngũ của chúng tôi: một số người thích một nhiều hơn - chẳng hạn cho phép - generic phương pháp trừu tượng, một khác thẳng về phía trước "bê tông" cách tiếp cận.
Ví dụ: thiết kế API "tìm kiếm người" đơn giản. phiên bản cụ thể sẽ là
searchPerson(String name, boolean soundEx,
String firstName, boolean soundEx,
String dateOfBirth)
Những người ủng hộ phiên bản cụ thể nói:
- API là tài liệu tự
- thật dễ hiểu
- thật dễ dàng để xác nhận (trình biên dịch hoặc dưới dạng dịch vụ web: xác thực lược đồ)
- HÔN
Một nhóm người khác trong nhóm của chúng tôi sẽ nói "Đó chỉ là một danh sách các tiêu chí tìm kiếm"
searchPerson(List<SearchCriteria> criteria)
với
SearchCritera {
String parameter,
String value,
Map<String, String> options
}
với khả năng làm "tham số" của một số loại liệt kê.
Những người đề xuất nói:
- mà không thay đổi (khai báo) API, việc triển khai có thể thay đổi, ví dụ: thêm nhiều tiêu chí hoặc nhiều tùy chọn hơn. Ngay cả khi không đồng bộ hóa một sự thay đổi như vậy tại thời điểm triển khai.
- tài liệu là cần thiết ngay cả với các biến thể cụ thể
- xác thực lược đồ được đánh giá quá cao, thường thì bạn phải xác nhận thêm, lược đồ không thể xử lý tất cả các trường hợp
- chúng tôi đã có một API tương tự với một hệ thống khác - tái sử dụng
Đối số là
- rất nhiều tài liệu về các tham số hợp lệ và kết hợp tham số hợp lệ
- nỗ lực giao tiếp nhiều hơn bởi vì nó khó hiểu hơn đối với các đội khác
Có thực hành tốt nhất? Văn chương?
3
lặp đi lặp lại "String First / name, boolean soundEx" là một sự vi phạm rõ ràng về sự khô khan và gợi ý rằng thiết kế này không thể giải quyết được thực tế là tên đó sẽ đi cùng với soundEx. Đối mặt với những lỗi thiết kế đơn giản như vậy, thật khó để tiến hành phân tích tinh vi hơn
—
gnat
Trái ngược với "cụ thể" không phải là "chung chung", đó là "trừu tượng". Trừu tượng là rất quan trọng đối với một thư viện hoặc API và cuộc thảo luận này không thể đặt câu hỏi thực sự cơ bản, thay vào đó là một câu hỏi khá tầm thường về phong cách. FWIW, các đối số đối với tùy chọn B nghe giống như tải FUD, bạn không cần bất kỳ tài liệu hoặc giao tiếp bổ sung nào nếu thiết kế API thậm chí còn sạch sẽ và tuân theo các nguyên tắc RẮN.
—
Aaronaught
@Aaronaught cảm ơn vì đã chỉ ra điều đó ("trừu tượng"). Nó có thể là một vấn đề dịch thuật, "hào phóng" trong tiếng Đức vẫn ổn với tôi. "Câu hỏi thực sự cơ bản" đối với bạn là gì?
—
erik
@Aaronaught: Câu hỏi không phải là về trừu tượng. Sự điều chỉnh đúng sẽ là ngược lại với "chung chung" là "cụ thể", không phải "cụ thể".
—
Jan Hudec
Một phiếu khác cho điều này không phải là về chung chung so với trừu tượng, nhưng chung chung so với cụ thể. Ví dụ "cụ thể" ở trên thực sự cụ thể cho tên, FirstName và dateOfBirth, ví dụ khác là chung cho bất kỳ tham số nào. Không phải là đặc biệt trừu tượng. Tôi sẽ chỉnh sửa tiêu đề nhưng tôi không muốn bắt đầu một cuộc chiến chỉnh sửa :-)
—
matt freake