descriptor-ru.md

🇺🇸 English | 🇷🇺 Русский | 🇨🇳 中文

Различия между простым и объектным дескриптором компонента с коррекцией

Основные различия

1. Формат записи

Простой дескриптор использует строковый формат, где компонент и путь коррекции разделены точкой:

"ComponentName.path.to.property"

Объектный дескриптор использует структурированный JSON-объект:

{
    "componentName": "ComponentName",
    "correction": "path.to.property"
}

2. Примеры использования

Простой дескриптор:

// Примеры валидных значений:
"TestDto"                    // Просто имя компонента
"TestDto.foo.bar"           // Компонент с путем к свойству
"TestDto.foo.bar[].test"    // Компонент с путем к элементу массива
"TestDto.allOf[2].foo"      // Компонент с путем к элементу allOf
"TestDto.oneOf[2].foo"      // Компонент с путем к элементу oneOf
"TestDto.anyOf[2].foo"      // Компонент с путем к элементу anyOf

Объектный дескриптор:

// Примеры валидных значений:
{
    "componentName": "TestDto"
}
{
    "componentName": "TestDto",
    "correction": "properties.foo.properties.bar"
}
{
    "componentName": "TestDto",
    "correction": "items.properties.foo"
}

3. Преобразование путей

При использовании простого дескриптора происходит автоматическое преобразование путей:

• foo.bar → properties.foo.properties.bar
• foo[] → items.properties.foo
• foo[].bar → items.properties.foo.properties.bar

В объектном дескрипторе пути указываются в их финальном виде без преобразования.

4. Практическое применение

Пример 1: Модификация простого свойства

// Простой дескриптор
"User.address"

// Объектный дескриптор
{
    "componentName": "User",
    "correction": "properties.address"
}

Пример 2: Модификация элемента массива

// Простой дескриптор
"Order.items[].quantity"

// Объектный дескриптор
{
    "componentName": "Order",
    "correction": "items.properties.items.items.properties.quantity"
}

Пример 3: Модификация элемента allOf/oneOf/anyOf

// Простой дескриптор
"Product.allOf[2].price"

// Объектный дескриптор
{
    "componentName": "Product",
    "correction": "allOf[2].properties.price"
}

Рекомендации по использованию

1. Используйте простой дескриптор, когда:

   • Нужен более компактный и читаемый формат
   • Пути к свойствам не слишком сложные
   • Хотите использовать автоматическое преобразование путей

2. Используйте объектный дескриптор, когда:

   • Нужен более строгий контроль над путями
   • Требуется явное указание структуры
   • Работаете со сложными вложенными структурами
   • Нужно избежать автоматического преобразования путей

Обработка ошибок

Оба типа дескрипторов имеют встроенную валидацию:

• Простой дескриптор проверяет корректность строкового формата
• Объектный дескриптор проверяет наличие обязательных полей и их типы

При некорректном формате система выведет понятное сообщение об ошибке с примером правильного использования.