Podczas omawiania interfejsów API między systemami (na poziomie biznesowym) w naszym zespole często występują dwa różne punkty widzenia: niektórzy wolą bardziej - powiedzmy - ogólne podejście abstrakcyjne, a inne proste „konkretne” podejście.
Przykład: projekt prostego interfejsu API „wyszukiwania osoby”. konkretna wersja byłaby
searchPerson(String name, boolean soundEx,
String firstName, boolean soundEx,
String dateOfBirth)
Ludzie opowiadający się za konkretną wersją mówią:
- interfejs API jest samodokumentujący
- łatwo to zrozumieć
- łatwa do sprawdzenia (kompilator lub jako usługa internetowa: sprawdzanie poprawności schematu)
- POCAŁUNEK
Druga grupa ludzi w naszym zespole powiedziałaby „To tylko lista kryteriów wyszukiwania”
searchPerson(List<SearchCriteria> criteria)
z
SearchCritera {
String parameter,
String value,
Map<String, String> options
}
z możliwym utworzeniem „parametru” jakiegoś typu wyliczenia.
Zwolennicy mówią:
- bez zmiany (deklaracji) interfejsu API implementacja może się zmienić, np. dodając więcej kryteriów lub więcej opcji. Nawet bez synchronizacji takiej zmiany w czasie wdrażania.
- dokumentacja jest konieczna nawet w przypadku konkretnego wariantu
- sprawdzanie poprawności schematu jest przereklamowane, często trzeba dokonać dalszej weryfikacji, schemat nie obsługuje wszystkich przypadków
- mamy już podobny interfejs API z innym systemem - ponowne użycie
Kontrargumentem jest
- dużo dokumentacji na temat prawidłowych parametrów i prawidłowych kombinacji parametrów
- większy wysiłek komunikacyjny, ponieważ trudniej jest zrozumieć dla innych zespołów
Czy są jakieś najlepsze praktyki? Literatura?
3
powtórzone „String name / name, boolean soundEx” jest wyraźnym naruszeniem „ suchego” i sugeruje, że ten projekt nie uwzględnił faktu, że nazwa powinna pasować do soundEx. W obliczu takich prostych błędów projektowych trudno jest przeprowadzić bardziej wyrafinowane analizy
—
gnat
Przeciwieństwo „betonu” nie jest „ogólne”, lecz „abstrakcyjne”. Abstrakcja jest bardzo ważna dla biblioteki lub API, a ta dyskusja nie zadaje prawdziwie fundamentalnego pytania, zamiast tego skupia się na tym, co szczerze mówiąc, jest raczej trywialnym pytaniem o styl. FWIW, kontrargumenty dla opcji B brzmią jak ładunek FUD, nie powinieneś potrzebować żadnej dodatkowej dokumentacji ani komunikacji, jeśli projekt API jest nawet w połowie czysty i zgodny z zasadami SOLID.
—
Aaronaught
@Aaronaught dzięki za zwrócenie na to uwagi („streszczenie”). Może to być problem z tłumaczeniem, „generisch” w języku niemieckim nadal wydaje mi się OK. Jakie jest dla ciebie „naprawdę fundamentalne pytanie”?
—
erik
@Aaronaught: Pytanie nie dotyczy abstrakcji. Prawidłowa korekta byłaby przeciwna do „ogólnej” jest „specyficzna”, a nie „konkretna”.
—
Jan Hudec
Kolejny głos na to nie jest ogólny, a abstrakcyjny, lecz ogólny i szczegółowy. „Konkretny” powyższy przykład jest właściwie specyficzny dla nazwy, imienia i datyObrazu, drugi przykład jest ogólny dla dowolnych parametrów. Żadne z nich nie są szczególnie abstrakcyjne.
—
Zredagowałbym