Принцип создания правильного API

[mousecray]

Доброго времени суток дорогие форумчане
Я то пропадаю, то появляюсь, и веду себя словно призрак. Однако призрак - это тоже своего рода жизнь.
Не так давно передо мной встала непростая для меня задача - спроектировать стабильное апи.
Вот каковы были основные требования.

• У пользователя нет доступа к внутренней части апи, т. е. он не может изменять его поведение извне.
• У пользователя нет доступа к исходному коду. Всё, что у него есть - набор рычагов, для достижения своих целей. То-бишь такое апи можно спокойно передавать стороннему разработчику, без боязни, что приватный код отправится на просторы интернета
• Компактный размер
• Удобное представление. Минимум кода.
• Методы должны быть хорошо документированы.
• Апи должно быть устойчиво к тупости людишек различного рода непредвиденным ситуациям, например null в аргумент помеченный @Nonnull

После некоторых метаний, я с горем пополам реализовал нечто, что удовлетворяет этим требованиям, взяв за основу данные из самых разных источников, в том числе форджа, некоторых модов, и баккита, а также некоторых плагинов. Однако я до сих пор не уверен, что выбрал правильный подход. Ибо в интернете конструктивных статей на эту тему не так уж и много, или я плохо искал.
Так вот, хотелось бы услышать чужое мнение на этот вопрос, а возможно и чужой опыт. Кто-нибудь работал с такими вещами? На какой свинье вы подъезжали как вы подходили к этому вопросу? Возможно в интернете, например на том же хабре, есть некий шаблон, или руководство на эту тему?

P.S. Если я найду время, я мог бы опубликовать свой опыт, и свою стратегию, если эта тема будет интересна сообществу.

 

[GoogleTan]

Вроде как Coth делает так, но это не точно.
Ты можешь сделать градл плагин, который будет делать 2 джарник с тонной интерфейсов вместо твоих абстрактных классов. Нельзя укратсть код, который ты не сможешь иметь . Вроде как удолетворяет всем требованиями.

Спойлер: Для тех, кто не бомбит от других языков программирования

Еще есть богоподобный котлин, для которого нету декомпилятора нормального и по сей день! Получается хрень на яве, которая не понятна и не компилится и не более. обфускатор сверху и твой код недостежим практически не как. Так же у котлина работа с нулами удобная. p.s. это только дополнение - давать часть сорцев надо, а значит их надо резать.

 

[mousecray]

Я работаю с maven(

 

[GoogleTan]

у мавена нету плагинов?
-----------------------------
Гугл сказал, что есть. Так что прочитай мой текст, заменив градл на мавен.

 

[mousecray]

Есть, но ты предложила для градла. В любом случае - дело не в инструменте для создания, а в самой архитектуре кода... Какой она должна быть с точки зрения мифической правильности?

 

[GoogleTan]

Мне кажется, что мифическая правильность у каждого своя... Личто в моем видении идеального апи, если указано нонулл, то при нуле оно должно карать) Но это уже дело каждого

 

[mousecray]

нуле оно должно карать

Ну так и есть) Но если это не обработать, в какую-нибудь карту может пойти таинственное значение с нулевым ключём. А вообще я привёл это как пример. Ситуации разные например что делать, если пользователь дублирует ключ? Можно просто проигнорировать, но такое поведение я не считаю устойчивым. Где-то нужно вывести в консоль предупреждение о перезаписи значения, где-то вообще выбросить экзепшн. Правда особых сомнений именно в этой задаче у меня нет... Какой-нибудь Preconditions#checkNotNull влепить и всё, вариантов особо нет... Но некоторые другие задачи меня до сих пор смущают...

 

[Icosider]

Руководств как таковых нет, если твоё API лёгок в понимании, удобен в использовании, то считай достинг поставленной цели. Проще говоря, старайся во время разработки своего API стараться мыслить, как юзверь, что ты это он. Как только поймёшь, что тебе собственное API непонятно, неудобно - переписывай. Сразу не получится, старайся также заюзать своё API в "бою", чтобы наверняка убедиться в том, удобно ли оно или нет А вообще, разработка своего API это ад, по началау хи-хи, ха-ха, а затем придёт юзверь, вставит палку в жопу и скажет, что не работает/не удобно и вообще...

 

[mousecray]

Очень жаль, что руководств нет, приходится делать по наитию... Что я и сделал собственно.
----
Раз руководств нет - опубликовал опрос... Возможно поделиться своим опытом будет не лишним.

 

[hohserg]

Тут в соседних темах обсуждали какой у Форжи и Фабрика херовый апи... Так что будет полезно почитать о сформулированных тобой принципах построения хорошего апи

 

[mousecray]

Вообщем, приняв во внимание всё вышесказанное, я решил, что поделиться своим опытом будет не лишним по двум причинам: руководств на эту тему немного это раз. Два, как минимум один человек изьявил желание почитать об этом

 

[WantaSanchez]

Два, как минимум один человек изьявил желание почитать об этом

Тогда я третий, подумывал добавить API в свой мод как минимум для облегчения своей же работы, а как максимум может даже на мавен выпустить. Вообще меня давно интересовала тема, чтобы добавить удобное API, выложить на мавен какой-то и дать возможность желающим делать аддоны или юзать отдельно API для упрощения разработки. Только толковых, актуальных и полных туторов я не видел, да и пока нету времени разбираться.

 

[will0376]

как минимум один

Ну... Мне тоже было бы интересно такое почитать

 

[mousecray]

Всё-таки опубликовал я туториал... Возможно местами неточный, а возможно и радикально неправильный... Вообщем, это просто мой личный опыт... На ваш суд. Тык