Разработка API в Java-проекте

Интересное выступление от разработчика из JetBrains про подход к дизайну API в проекте. Всегда придерживаюсь аналогичного же подхода, но не всегда получалось аргументировать это и «донести» до коллег (особенно при наличии дедлайнов и приличного объема старого кода «на поддержке»).

Основные мысли такие:

  • хорошее API должно быть максимально простым и максимально «мощным»
    1. Простые вещи должны реализовываться просто: методы которые делают много лучше резать на простые вызовы которые нужны в 90% случаев и сложные
    2. Максимально чистое API: голые интерфейсы, или абстрактные классы там где нужно, реализацию лучше убрать из контракта чтобы упростить чтение исходников для пользователя и скрыть ненужные детали.
  • хорошее API должно предотвращать «неправильный порядок» действий с ним
    1. Валидация
      • валидация в runtime: fail fast — падаем как можно раньше и с подробной информацией о том что не так
      • валидация при компиляции: type safe / generics, enums;
      • минимизировать использование нестрогих типов данных: string, object и даже boolean
    2. Думаем о своих пользователях
      • обратная совместимость должна быть всегда, если меняем API активно используем deprecated, старые методы не удаляем.
      • не добавляем методы в API просто так, т.к. добавить метод легко, а изъять из использования сложно и черевато ошибками
    3. Запретить расширение API и по максимуму защиться в контракте классов и методов API от любых возможных действий со стороны пользователя
      • все что можно — final, private
      • immutable классы там где возможно
  • хорошее API должно иметь запас по расширяемости
    1. достаточно абстрактный и гибкий дизайн, но не сложнее чем того требует задача
    2. понимание, что сразу сделать хорошо не удастся
    3. хорошим API важно пользоваться самому, и лучше «2 раза» :-)
  • все остальные пункты я бы добавил сюда — Просто пишите качественный код

Другие записи...

1 Ответ

  1. pl:

    Многие разработчики до сих пор создают документацию своих API в Word или Excel. Я использую Apiary — http://plutov.by/post/api_how_to

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

* Please Enter the Output

Можно использовать следующие HTML-теги и атрибуты: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>