Разработка лучшего API?

Question

1. Каковы лучшие практики и шаблоны, которым необходимо следовать при разработке API?
2. Как добиться наилучшего способа сокрытия реализации (C ++ / Java)?
3. Разработка API, которые по своей природе являются общими?
4. Какие-нибудь справочники / ссылки, которые ведут с изящными примерами начинающим?

Answer 1

Я не уверен, что у меня есть отличный ответ на все ваши индивидуальные вопросы, но я думаю, что у меня есть хороший ответ на самый первый.

Попробуйте использовать его до того, как оно будет написано. Под этим я подразумеваю писать модульные тесты для кода, как если бы он действительно существовал. Напишите некоторый код, который будет использовать API, прежде чем вы даже напишите одну строку API. Когда вы попытаетесь использовать его, вы быстро увидите, что работает, а что нет, в дизайне, который вы имели в виду, и вы быстро измените его в соответствии с его фактическим использованием, потому что вы еще не написали любой актуальный код .

Нет никаких трений в том, чтобы что-то изменить, если вы не добавили что-либо в код, но в тот момент, когда вы это делаете, часто возникает некоторая степень нежелания делать это.

Answer 2

Это может быть полезно для вас.

Небольшое руководство по API Design (wayback machine)

Небольшое руководство по разработке API (оригинал; мертв)

Answer 3

4:

• Как создать хороший API и почему это важно - Отличное видео, которое стоит потраченного на него времени.

По моему мнению, у Джоша Блоха есть лучшие идеи, когда речь идет о написании хороших API, и он может объяснить их в очень простой для понимания форме. На видео выше вы найдете адрес Q1-3.

Answer 4

Я предлагаю вам проверить Как разработать хороший API и почему это важно

Хорошо написанный API может быть отличным актив для организации, которая написала это и всем, кто его использует. Учитывая важность хорошего дизайна API, на удивление мало что было написано на предмет. В этом разговоре (записано в Javapolis), дизайнер библиотеки Java Джошуа Блох учит, как проектировать хорошие API, со многими примерами того, что хорошие и плохие API выглядят так.

http://www.infoq.com/presentations/effective-api-design

Также вы можете прочитать книгу Практический дизайн API: Исповедь Java ™ Framework Architect . Я не читал его, поэтому я не уверен, может ли это быть полезным для вас.

Еще один ресурс для проверки: Как спроектировать (модуль) API

Answer 5

У меня есть совет относительно пункта 3 (общий дизайн API):

Начало использования вашего API на конкретных сценариях использования ; Сделайте свой дизайн конкретным, а не универсальным - затем обобщите позже , если , вы обнаружите, что API можно использовать повторно.

В прошлом я видел рефакторинг API-интерфейсов до такой степени, что они настолько универсальны, что одним из параметров метода является объект «Параметры» или, что еще хуже, дерево DOM, соответствующее произвольному фрагменту XML; например,

void processData(Parameters reportParams);

При таком универсальном подходе:

• Ошибки с меньшей вероятностью будут обнаружены во время компиляции или при взгляде на код, и они будут появляться во время выполнения, что затрудняет их поиск.
• Код будет менее читабельным и менее самодокументируемым, что затруднит его использование или реализацию.
• Реализация API станет уродливой, так как внутренне ей необходимо разложить этот объект «Параметры» в конкретный вариант использования и действовать в соответствии с ним.

Answer 6

Оформить заказ Подкаст

В нем рассказывается о действительно хороших концепциях, касающихся API-дизайна.

Answer 7

Чтение Эффективная Java . Автор Josh Bloch. Книга отлично подходит для любого Java-программиста, но также затрагивает множество вопросов, связанных с созданием полезного API.

Answer 8

Apress - Практический API-дизайн - Исповедь архитектора Java - 2008

Pragmatic - Дизайн, ориентированный на интерфейс - 2006

Answer 9

Вы можете реализовать следующие рекомендации:

1) использовать установленные или известные методы, примеры:

createPatientRecord();
createPatientAppointment();
createPatientCheckup();

2) возвращаемые значения:

• бросить исключение, если есть
• если объект не найден, вернуть ноль
• если несколько объектов, вернуть пустой список не нуль

3) последовательный порядок следования / последовательность

recallPatientRecord(long patientId, long hospitalId);
recallPatientRecord(long patientId);
recallPatientRecord(long patientId, long hospitalId, int disciplineCode);

Answer 10

На этот вопрос практически невозможно ответить. Это может даже не быть правильным вопросом для переполнения стека (Человек A: Как мне решить конкретную проблему? Человек B: Вот этот окончательный ответ).

1. Каковы лучшие практики и шаблоны, которым необходимо следовать при разработке API

О каком языке программирования мы говорим? О какой области проблемных областей идет речь? Потому что то, что работает для одного языка программирования / проблемной области, может не работать в другом языке программирования / проблемной области.

2.Как добиться наилучшего способа скрытия реализации (C ++ / Java)

На этот вопрос есть ответ, и писать здесь слишком долго. На самом деле, это так долго, что ссылки на сайт будет недостаточно. Существует множество веб-сайтов и книг, которые в совокупности ответят на этот вопрос. О, и я просто говорю о C ++. Повторите весь этот процесс для Java. И для C #, и для Python, и для .... (и т. Д.)

4.Любые справочники / ссылки, которые приводят наглядные примеры для начинающих

Выберите язык программирования. Тогда я могу предоставить ссылки на книги и ссылки. Как писал Фред Брукс, серебряной пули нет. Нет единого менталитета, который вы можете перенести с языка программирования на язык программирования. То, что делает хороший API на одном языке программирования, было бы ошибкой проектирования на другом языке программирования. Поверьте мне, я усвоил это с трудом, пытаясь применить идиомы C ++, Delphi и Java к этим языкам. Это приводит к плохим API и плохому коду.

Существуют также конкурирующие школы в разработке API. И, к сожалению, реальность такова, что никто не на 100% прав. На самом деле, вы становитесь отличным дизайнером API, когда знаете несколько направлений мысли и знаете, когда применять конкретную точку зрения к конкретной проблеме.