Разработка API с множеством параметров

Question

Я разрабатываю API для iPhone.Каков наилучший способ разработки функций API, которые принимают много аргументов (может быть, до 20 переменных).Лучше передать пользовательский объект с определенными необходимыми полями, словарь общего значения ключа (NSDictionary в Obj-C), или просто перечислить их все?Какие еще предложения доступны?

Я стремлюсь объявлять объект для каждого API, но, поскольку мне нужно определить множество API, я опасаюсь использовать этот подход.

Answer 1

Большинство разработчиков API соглашаются с тем, что по возможности следует избегать длинных списков аргументов, например, Джошуа Блох (Эффективная Java) предлагает, чтобы 5 или больше - это слишком много. Вот несколько способов избежать этого:

1. Создать структуру для хранения аргументов и передать эту единственную структуру в функцию. Это часто называют типом простых старых данных (POD). Возможно, вы захотите добавить вспомогательную функцию для создания структуры, которая устанавливает значения по умолчанию (или, если вы используете Objective-C ++, вы можете определить конструктор для структуры, который будет делать то же самое). Если вы думаете, что список аргументов может со временем меняться и бинарная совместимость важна для вас, вы можете добавить поле версии и настроить конструктор соответствующим образом. Таким образом, ваш код может проверить номер версии, чтобы узнать, какие поля доступны.

2. Передать словарь значений. Это фактически API, управляемый данными, где аргументы и их значения передаются в структуре, которая поддерживает ключи со значениями произвольно типизированных. В C / C ++ вы должны будете создать эту структуру самостоятельно или использовать что-то вроде boost :: any или Qt QVariant. Но, как вы заметили, NSDictionary позволяет вам хранить объекты типа id, чтобы вы могли использовать это. Хорошая вещь об этом - то, что изменение списка аргументов не нарушает ваш интерфейс - это только до реализации, чтобы обнаружить новые ключи и поддержать более старые ключи. Хотя следствием этого является то, что ваш компилятор не будет ловить неправильные ключи для вас - это зависит от вашего кода. Основным недостатком является то, что просто взгляд на ваш API не говорит пользователю, какие ключи поддерживаются, поэтому этот подход должен поддерживаться хорошей документацией.

3. Создать объект и превратить аргументы в вызовы методов. Преимущество этого заключается в возможности задавать аргументы в любом порядке, по существу именовать аргументы и по-прежнему обрабатывать необязательные аргументы (просто не вызывая данный метод). Добавление новых параметров также обратно совместимо, поскольку разрешает добавление новой функции к объекту.

4. Опираясь на 3., вы можете использовать Идиому Именованных Параметров (NPI), где каждая функция возвращает указатель или ссылку на объект, что позволяет вам объединять вызовы вместе. Эта опция имеет все преимущества 3., но также допускает более краткий синтаксис, например, MyObject (). SetValue (100) .setName ("Hello"). SetEnabled (true);

Похоже, вы уже рассмотрели большинство из этих вариантов, поэтому я, вероятно, не скажу вам ничего нового. Что касается меня, я бы больше склонялся к стилю NPI, так как он избегает длинных списков параметров, строго типизирован, называет каждый аргумент, обратно совместим и все еще предлагает относительно компактный синтаксис. Он более типичен (для вас), чем подход NSDictionary, но, что важно, его легко использовать пользователям, и он делает набор поддерживаемых «аргументов» очевидным (и всегда корректным) через заголовочные файлы даже без какой-либо документации, в отличие от решения NSDictionary .

Answer 2

Если вашему API действительно нужно 20 параметров, используйте 20 параметров.Если имеет смысл объединить некоторые или все эти параметры в пользовательский объект, во что бы то ни стало, сделайте это, но не создавайте пользовательский объект только ради уменьшения списка параметров.В качестве простого примера, если метод берет координаты точки (x, y, z), вполне законно создать объект для моделирования точки и передать его в качестве единственного параметра.Вы не должны создавать объекты, единственной целью которых является моделирование списка параметров API.

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

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

Answer 3

Вам нужно 20 аргументов, чтобы просто инициализировать объект?Вам нужно несколько аргументов, чтобы привести объект в состояние по умолчанию.Затем используйте свойства, чтобы изменить его состояния.

Внутренне вы можете сохранить 20 аргументов / состояний в NSDictionary для удобства обслуживания.

Answer 4

Наиболее сложные методы, которые я могу себе представить, принимают NSDictionary в качестве аргумента.Я бы так и сделал.

Answer 5

Это зависит от типа создаваемого вами API.

Если это служба с общепринятой информационной моделью, вероятно, хорошей идеей будет наличие пользовательских объектов модели, поскольку они, как правило, облегчают понимание API в целом.

OTOH, если это скорее универсальный API, довольно много аргументов являются необязательными, или объекты модели будут уникальными для каждого метода, вам, вероятно, лучше использовать NSDictionary с четкой документацией ключей, которые вы используете. ожидание (а также правильная проверка в начале функции).

Существует также обширная информация по теме о веб-сетях, см. "Как разработать хороший API и почему это важно" для хороших идей, ProgrammableWeb для хороших примеров и «Десять лучших способов создать отличный API» для списка советов из десяти лучших.

Удачи!