¬аше окно в мир —јѕ–
Ќовости —татьи јвторы —обыти€ ¬акансии Ёнциклопеди€ –екламодател€м
—татьи

20 июн€ 2022

Ќовый API геометрического €дра C3D: развитие и стабильность

“ать€на ћитина, директор C3D Labs Ќижний Ќовгород

“ать€на ћитина


ќригинал публикации в блоге C3D Labs

–азработка программного обеспечени€ зачастую ведетс€ с применением каких-либо специальных программ, которыми €вл€ютс€, например, фреймворки или программные библиотеки. ¬заимодействие между ѕќ и такими программами обычно осуществл€етс€ при помощи набора специальных команд (классов, функций). —ущность, котора€ реализует такое взаимодействие, называетс€ API (Application Programming Interface Ч Ђпрограммный интерфейс приложени€ї).

Ќовый API €дра C3D

“ак как C3D Toolkit €вл€етс€ набором инструментов дл€ создани€ программного обеспечени€ (SDK), все его компоненты также предлагают программные интерфейсы дл€ использовани€ их функционала в инженерном приложении.  ак и люба€ друга€ программа, C3D Toolkit посто€нно пополн€етс€ новым функционалом, что непосредственно сказываетс€ на API его компонентов Ч он развиваетс€ и обновл€етс€. ѕри этом важно сохран€ть его состо€ние рабочим и полностью предсказуемым дл€ пользователей.

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

ќсобенности разработки API

ѕрежде чем перейти непосредственно к теме самой заметки, необходимо подробнее остановитьс€ на том, какими особенност€ми обладает API в принципе.

ќбщеизвестным €вл€етс€ факт, что программные интерфейсы создают разработчики, а используют тоже разработчики, но примен€ющие их дл€ создани€ своих собственных программных продуктов. Ёто позвол€ет нам утверждать следующее:

  • API используетс€ дл€ решени€ различных задач при разных сценари€х и получаемых данных;
  • API используетс€ в разном окружении (операционна€ система, тип компил€тора, верси€ компил€тора);
  • продукты пользователей API имеют свои собственные жизненные циклы, планы разработки и выпуска релизов.

”читыва€ вышеизложенное, программные интерфейсы должны отвечать следующим основным требовани€м:

  • API должен быть простым, интуитивно пон€тным и согласованным;
  • API должен поддерживать различные платформы разработки;
Ќовый API €дра C3D

  • API должен обеспечивать стабильность и обратную совместимость;
  • дизайн API должен предусматривать возможность его развити€ без нарушени€ стабильности.

«десь стоит остановитьс€ подробнее на двух упом€нутых выше пон€ти€х Ч стабильности и совместимости, а именно на том, что они означают в терминах API.

ѕод стабильностью понимаетс€ неизменность программных интерфейсов на прот€жении максимально долгого периода времени. ѕри этом если по€вл€етс€ необходимость модификации API, то существует четка€ процедура по внесению изменений, направленна€, в первую очередь, на поддержание удобства применени€ API пользователем. «десь как раз на сцену выходит обратна€ совместимость, котора€ означает, что код, написанный с использованием предыдущей версии, функционально одинаково работает и со следующей версией API.

Ќовый API €дра C3D: принципы разработки

ѕри разработке API геометрического €дра C3D Modeler мы неуклонно следуем следующим важным принципам.

1. ƒобавление нового интерфейса никогда не вызывает трудностей, однако удаление уже существующего, ставшего, например, лишним, может стать причиной недовольства пользователей API. ѕоэтому при удалении такого интерфейса важно проводить целую процедуру, включающую информирование пользовател€ о необходимости его перехода на новый интерфейс. —оответственно требуетс€ обеспечить минимальный набор интерфейсов, т. е. реализовать только те функции, которые нужны дл€ работы API в данный момент.

2. –азвитие (расширение) программных интерфейсов должно осуществл€тьс€ таким образом, чтобы не возникало потребности вносить какие-либо изменени€ в существующий API. ѕри этом расширение интерфейсов не должно пагубно сказыватьс€ на их стабильности и нарушать их совместимость с прошлыми верси€ми API.

Ќовый API €дра C3D

Ќиже мы расскажем, какими правилами пользуемс€ при расширении нашего API.

3. ѕри разработке структуры параметров каждого конкретного интерфейса-функции необходимо избегать длинных списков аргументов, т. к. большое их количество сложнее контролировать; кроме того, это может привести к некорректной работе интерфейса. «десь необходимо выдел€ть смысловые блоки аргументов и упаковывать их в отдельные структуры.

Ќовый API €дра C3D

4. ¬ладение объектами, которые создает интерфейс, должно быть однозначным. ƒл€ соблюдени€ этого принципа хорошей практикой будет использование умных указателей.

5. –еализаци€ новых интерфейсов по возможности должна сопровождатьс€ использованием уже существующих. “аким образом обеспечиваетс€ так называемое Ђне€вное тестированиеї, когда функци€ нового API использует другие интерфейсы.

6. ¬ завершение стоит отметить и важность документации. Ћюбые программные интерфейсы, которые видит пользователь, должны быть хорошо задокументированы, т. к. даже в хорошо спроектированном API внешнему пользователю будет непросто разобратьс€ без подробного описани€ всех его ключевых моментов.

Ќовый API €дра C3D

Ќовый API €дра C3D: пример разработки

–ассмотрим пример соблюдени€ упом€нутых выше принципов в нашем собственном API геометрического €дра.

Ќиже приведены три устаревшие функции дл€ построени€ тела скруглени€ трем€ различными способами.

Ќовый API €дра C3D

ѕример показывает, что дл€ построени€ различными способами тела скруглени€ примен€ютс€ три интерфейса, а также множество аргументов.

“еперь продемонстрируем пример уже нового интерфейса, который пришел на смену трем предыдущим.

Ќовый API €дра C3D

ќчевидно, что в данной функции все параметры, использовавшиес€ в качестве аргументов в предыдущих функци€х, инкапсулированы в единую структуру Ч класс MbShellFilletValues.

–ассмотрим подробнее данный класс.

Ќовый API €дра C3D

ѕри его разработке мы следовали некоторым описанным выше принципам. ¬о-первых, класс предоставл€ет специальный конструктор дл€ каждого способа построени€ (принцип 1) и использует умные указатели (принцип 4). ¬о-вторых, он предоставл€ет возможность расширени€ функциональности построени€ скруглений без нарушени€ обратной совместимости данного интерфейса (принцип 2). Ќапример, можно добавить новый способ построени€, определив конструктор, или расширить функционал существующего интерфейса, добавив иные параметры построени€ и метод дл€ их инициализации. ѕри этом пользователи могут продолжать использовать этот интерфейс, так как дл€ них в плане совместимости ничего не мен€етс€.

ќбеспечение стабильности и обратной совместимости API C3D

»так, мы разобрались, что такое стабильность и обратна€ совместимость API, подчеркнули важность этих параметров дл€ хорошо спроектированного программного интерфейса, а теперь давайте вы€сним, каким образом мы в C3D обеспечиваем стабильность и совместимость API.

Ќеобходимо по€снить, что в рамках одной мажорной версии (например, C3D Toolkit 2022):

  • обновление ревизии API не нарушает компилируемость продуктов пользователей;
  • обеспечиваетс€ стабильность поведени€ интерфейсов €дра;
  • массивные изменени€ API разрешаютс€ только при выпуске следующей мажорной версии;
  • интерфейс может быть объ€влен устаревшим с указанием срока его действи€, при этом после указанного срока устаревший API удал€етс€ в любой момент времени (перестает быть стабильным).
Ќовый API €дра C3D

√овор€ о стабильности и совместимости программных интерфейсов, невозможно не сказать об их развитии и расширении. ћы в C3D придерживаемс€ следующих правил при изменении API €дра:

  • интерфейс не может перемещатьс€ или переименовыватьс€ без предоставлени€ обратно совместимых псевдонимов;
  • в интерфейсе-функции не разрешены изменени€ соглашени€ вызова, количества параметров, их типа, но в качестве исключени€ новый параметр может быть добавлен в конец списка параметров существующей функции с об€зательным указанием значени€ по умолчанию (аналогичное правило примен€етс€ дл€ методов интерфейсных классов);
  • в структурах интерфейсов не разрешено удаление, перемещение или изменение публичных полей. ќднако есть исключение: при добавлении нового пол€ в структуру оно может быть добавлено только в конец списка полей, а при добавлении нового значени€ в перечисление оно также может быть добавлено только в конец списка его значений. ”пом€нутые правила распростран€ютс€ на все виды интерфейсов (функции, классы, перечислени€, публичные константы);
  • при необходимости внесени€ изменений в метод интерфейсного класса в него должен добавл€тьс€ новый метод, а существующий Ч объ€вл€тьс€ устаревшим, при этом новый метод не должен нарушать или измен€ть значение и поведение существующего (то же касаетс€ и интерфейс-функции). «десь также существуют исключени€, ограничивающие поддержание стабильности и совместимости: обратна€ совместимость интерфейса может быть нарушена без объ€влени€ его устаревшим, если критическа€ ошибка делает его непригодным дл€ использовани€, а наход€щиес€ в разработке интерфейсы не об€заны подчин€тьс€ требовани€м стабильности.

ƒл€ удобства пользователей мы выносим информацию об изменени€х API в определенных местах:

  • описываем их в файле changes.txt соответствующего релиза C3D;
  • отмечаем в комментари€х наход€щиес€ в разработке (нестабильные) интерфейсы как экспериментальные;
  • отмечаем подлежащий удалению интерфейс как устаревший с указанием замен€ющего его интерфейса (сроки удалени€ устаревшего интерфейса указываютс€ в сообщении во врем€ компил€ции).

warning C4996: 'FilletSolid':This is a deprecated API that will be removed in version 2022! Use FilletSolid with 'MbShellFilletValues' parameter instead it.

“аким образом, мы стремимс€ предоставл€ть нашим пользователем компоненты дл€ разработки инженерных приложений, обладающие интуитивно пон€тными и удобными программными интерфейсами, в стабильности и совместимости которых пользователи могут быть уверены.



¬акансии:

јктуальное обсуждение

RSS-лента комментариев

-->

ƒавид Ћевин
ƒавид Ћевин
ќт редактора: Autodesk не впервые навсегда ушел из –оссии
ѕроект ЂЌародное —јѕ–-интервьюї

—лучайна€ стать€:

isicad Top 10

—амые попул€рные материалы

   ‘орумы isicad:

isicad-2010 isicad-2008
isicad-2006 isicad-2004

ќ проекте

ѕриглашаем публиковать на сайте isicad.ru новости и пресс-релизы о новых решени€х и продуктах, о проводимых меропри€ти€х и другую информацию. јдрес дл€ корреспонденции - info@isicad.ru

ѕроект isicad нацелен на

  • укрепление контактов между разработчиками, поставщиками и потребител€ми промышленных решений в област€х PLM и ERP...
ѕодробнее

»нформаци€ дл€ рекламодателей


¬се права защищены. © 2004-2022 √руппа компаний «Ћ≈ƒј—»

ѕерепечатка материалов сайта допускаетс€ с согласи€ редакции, ссылка на isicad.ru об€зательна.
¬ы можете обратитьс€ к нам по адресу info@isicad.ru.