Главная · Tommy Cheese

Расширения OpenCode v2: устройство и интеграция

Sun, 13 Sep 2026 00:00:00 +0800

Дата исследования: 2026-09-13. Статья описывает общие возможности плагинов OpenCode v2: типы, загрузку, регистрацию возможностей, хуки выполнения, границы разрешений и жизненный цикл. Материал предназначен для разработки плагинов и встраиваемой интеграции.

Исследование основано на ветке v2 изученного репозитория OpenCode, коммит 2308db16387c9b59e88d732a93ec9bac54462b03. Ссылки на исходники используют пути относительно репозитория в этом фиксированном коммите. Описанные интерфейсы и поведение относятся к данной версии и не обещают совместимости с другими версиями OpenCode или прежним API плагинов.

Это исследование исходного кода и описание возможностей. Примеры поясняют интерфейсы и вызовы; независимо они не запускались и не проверялись.

Plugin: точка входа для расширений

Что такое Plugin

Расширения OpenCode подключаются к существующему выполнению через регистрацию возможностей и хуков. В текущей реализации OpenCode v2 понятие Extension в основном соответствует механизму Plugin. Плагин может предоставлять ассистентов, инструменты, навыки, модели, команды и другие возможности, а также менять поведение в заданных точках выполнения. Сеансы, запросы к моделям, результаты инструментов и записи выполнения по-прежнему обрабатывает ядро OpenCode.

Процесс Plugin: от загрузки и регистрации возможностей до выполнения сеанса

Показать исходный код диаграммы Mermaid

flowchart TD
    A[配置文件、本地插件或 SDK 注册] --> B[插件加载与生命周期管理]
    B --> C[构建助手、工具、技能等能力]
    C --> D[会话选择助手]
    D --> E[准备上下文与工具快照]
    E --> F[请求阶段钩子]
    F --> G[调用模型]
    G --> H{返回内容}
    H -->|工具调用| I[工具执行与钩子]
    I --> J[保存结果与执行事件]
    J --> G
    H -->|最终回答| K[本次执行结束]

Виды Plugin

Внутренние, внешние и SDK-плагины различаются источником подключения, но управляются единой системой выполнения. Все три вида могут регистрировать ассистентов, инструменты и хуки. Различия в основном заключаются в том, кто предоставляет определение, как оно загружается в хост и внедряет ли хост дополнительные внутренние сервисы ядра. Здесь рассматриваются серверные плагины; TUI-плагины терминального интерфейса используют другую точку расширения.

Параметр сравнения	Внутренний плагин	Внешний плагин	SDK-плагин
Поставщик	Исходный код и дистрибутив OpenCode	Сопровождающие проекта или отдельного пакета плагина	Приложение-хост, встраивающее OpenCode
Точка входа	`PluginInternal` : наборы `pre` / `post` (наборы)	Обнаружение в каталогах, файлы или пакеты в конфигурации	Во встраиваемом хосте: `opencode.plugin(definition)`
Способ загрузки	Ядро напрямую импортирует определение	Разрешение модуля и чтение экспорта по умолчанию	Передача объекта плагина непосредственно в памяти
Доступные интерфейсы	Публичный Context и внутренние сервисы, внедрённые хостом	Публичный Plugin Context	Публичный Plugin Context; через замыкание доступны зависимости, явно переданные хостом
Основной способ настройки	Нативная конфигурация, внутренние сервисы или встроенные значения по умолчанию	`plugins[].options` → `ctx.options`	Код хоста и замыкания; отдельного параметра `options` у интерфейса регистрации нет
Источник обновлений	Версия кода OpenCode; некоторые плагины самостоятельно отслеживают конфигурацию	Изменения конфигурации, поддерживаемых локальных точек входа или настроек пакета	Повторная регистрация хостом с увеличением внутренней ревизии
Область экземпляра	Независимая активация для каждого Location	Отдельная активация по конфигурации каждого Location	Общие определения в одном хосте, независимая активация в каждом Location
Применение	Реализация нативных ассистентов, инструментов, провайдеров и обработки конфигурации	Добавление проектных или бизнес-возможностей в существующий сервис OpenCode	Встраивание OpenCode в собственное приложение JS/TS и управление им

Effect и Promise — два интерфейса написания плагинов. Объект Effect-плагина с публичным интерфейсом можно экспортировать по умолчанию для загрузки через конфигурацию или напрямую зарегистрировать во встраиваемом SDK. Основные возможности переиспользуются, но порядок загрузки и способ передачи конфигурации меняются.

Внутренние плагины оформляют часть собственных функций OpenCode в виде плагинов. Это не специальные файлы, устанавливаемые пользователем в каталог. Они статически импортируются исходным кодом ядра и явно включаются в наборы PluginInternal .PluginInternal.list() получает сервисы текущего Location и через Effect.provide(context) внедряет их во внутренние плагины, после чего передаёт их единому загрузчику.

Здесь существуют два уровня Context: effect(ctx) по-прежнему принимает публичный Plugin Context, а внутренний плагин дополнительно получает через среду Effect сервисы Config.Service, Permission.Service, Shell.Service, Location.Service и другие. Дополнительные возможности обусловлены явно внедрёнными зависимостями, а не тем, что ID плагина начинается с opencode. .

Пример внутреннего плагина	Набор	Фактическая ответственность
`opencode.agent`	`pre`	Регистрация базовых определений нативных ассистентов
`opencode.tool.shell`	`pre`	Регистрация инструмента Shell с нативным выполнением, разрешениями и сервисами состояния
Нативные провайдеры, поиск и другие плагины инструментов	`pre`	Базовые возможности моделей, поиска и инструментов
`opencode.config.agent`	`post`	Чтение конфигурации ассистентов и связанных файлов Markdown с применением к списку ассистентов
Плагины конфигурации провайдеров, навыков, политик и вариантов моделей	`post`	Применение конфигурации или последующей обработки к ранее предоставленным возможностям

Это объясняет связь пользовательских ассистентов с внутренними плагинами. Пользователь редактирует конфигурацию ассистента, а чтением, отслеживанием и применением занимается opencode.config.agent. Каждый пользовательский ассистент — определение Agent; отдельный плагин для него не требуется. Внешние и SDK-плагины тоже могут регистрировать Agent, которые затем корректируются конфигурационным плагином.

Встроенные плагины также участвуют в выборе включения и отключения. Например, -opencode.config.agent исключает из активного набора плагин применения конфигурации ассистентов, затрагивая соответствующие настройки. Решение о сохранении встроенного плагина нужно принимать с учётом его фактической роли.

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

Основания: набор внутренних плагинов и внедрение сервисов (packages/core/src/plugin/internal.ts), плагин нативных ассистентов (packages/core/src/plugin/agent.ts), плагин конфигурации ассистентов (packages/core/src/config/plugin/agent.ts), плагин инструмента Shell (packages/core/src/tool/plugin/shell.ts).

Внешние плагины добавляют возможности существующему сервису OpenCode через файлы или пакеты. «Внешний» означает, что код не входит во встроенный набор. При выполнении он всё равно загружается в процесс OpenCode. Загрузчик предоставляет публичный Plugin Context, но не внедряет дополнительные сервисы Core, как для внутренних плагинов. Код может пользоваться файлами, сетью и другими возможностями среды выполнения; это не отдельный процесс и не защищённая песочница.

У внешних плагинов два пути обнаружения:

Автоматическое обнаружение: сканируются plugin/ и plugins/ в нативных каталогах конфигурации. Текущая реализация напрямую распознаёт файлы .ts, .js , а также поддерживает каталоги пакетов и подходящие символические ссылки. В каталоге пакета проверяются строковые поля файла package.json : exports, module, main, затем index.ts, index.js. Эту простую логику нельзя считать поддержкой всех сложных правил экспорта пакетов.
Явная конфигурация:plugins принимает относительные и абсолютные пути, файловые URL и разрешимые пакеты. Относительные пути разрешаются от каталога файла конфигурации. Локальные пути передаются загрузчику модулей, пакеты — механизму разрешения пакетов, который пробует подраздел server или корневую точку входа пакета.

Результаты автоматического обнаружения сначала добавляются в список операций, затем применяется явная конфигурация. Поэтому автоматически найденный плагин можно отключить в настройках. Автообнаружение напрямую не перечисляет файлы .mjs ; для такой точки входа путь задаётся явно, а загрузку выполняет среда исполнения.

{
  "plugins": [
    {
      "package": "./plugins/example.ts",
      "options": {
        "serviceUrl": "https://api.example.com"
      }
    }
  ]
}

Приведённые пути иллюстрируют формат конфигурации. Плагин через ctx.options читает serviceUrl и самостоятельно проверяет обязательные поля, диапазоны значений и ограничения адресов. Сам факт передачи объекта не означает валидацию бизнес-настроек.

Внешний модуль должен по умолчанию экспортировать объект плагина с id + effect или id + setup :

Способ написания	Точка инициализации	Подключение и очистка
Effect	`effect(ctx)`	Хост выполняет плагин внутри его Scope; ресурсы связываются со scoped-жизненным циклом или finalizer
Promise	`setup(ctx)`	Загрузчик через `fromPromise` преобразует определение в Effect-плагин; можно вернуть функцию cleanup

@opencode-ai/plugin/effect предоставляет Effect API, а корневой вход пакета @opencode-ai/plugin — Promise API текущей ветки. У прежнего API отдельная точка входа v1 ; принадлежность к плагинам OpenCode сама по себе не гарантирует совместимость интерфейсов.

Типичная цепочка загрузки внешнего плагина:

配置目录 / plugins 配置
  → ConfigPluginSource 生成有序操作与本地文件时间戳
  → PluginSupervisor 解析路径或包、导入模块、校验默认导出
  → 适配 Promise 定义，并注入该来源的 options
  → Plugin.Service 创建 Location 内的插件实例
  → 注册助手、工具、钩子及需要清理的资源

Изменения файлов или конфигурации могут запустить пересоздание набора плагинов в пределах поддерживаемого обнаружения и наблюдения. Произвольный файл зависимости не обязательно обновляется в реальном времени. В частности, при явном указании каталога в качестве точки входа текущая реализация не гарантирует перезагрузку при изменении файлов внутри него. Обновления версий пакетов также следует проводить явным развёртыванием или изменением конфигурации.

Ошибка импорта модуля или проверки экспорта записывается как предупреждение загрузки; соответствующий источник пропускается. Ошибку инициализации уже на этапе активации обрабатывает единое управление плагинами. При диагностике отдельно проверяйте обнаружение файла, разрешение модуля, активацию плагина и регистрацию возможностей. Наличие настройки само по себе не доказывает доступность инструмента.

Основания: обнаружение источников и локальное наблюдение (packages/core/src/config/plugin/source.ts), загрузка модулей и внедрение конфигурации (packages/core/src/plugin/supervisor.ts), публичные точки входа пакета (packages/plugin/package.json), адаптер Promise (packages/plugin/src/promise/adapter.ts).

SDK-плагины напрямую регистрируются встраиваемым хостом и подходят для использования OpenCode как внутреннего движка приложения. Под SDK здесь понимается именно встраиваемый хост текущей ветки @opencode-ai/sdk-next .OpenCode.create() создаёт среду выполнения и цепочку вызовов HTTP-маршрутов в памяти процесса приложения. Для этой внутренней цепочки не требуется сетевое прослушивание; инструменты, модели и бизнес-сервисы по-прежнему могут выполнять собственные сетевые запросы.

Хост через opencode.plugin(definition) напрямую передаёт объект Effect-плагина, минуя обнаружение внешних модулей, разрешение пакета и проверку экспорта по умолчанию. Это не загрузка кода в уже работающий удалённый сервис OpenCode. Обычный HTTP-клиент и ctx.plugin.list() из Plugin Context также не являются этой встраиваемой точкой регистрации.

Пример ниже показывает регистрацию и запрос плагина во встраиваемом хосте. Версии зависимостей должны соответствовать исследованной версии:

import { AbsolutePath, Location, OpenCode } from "@opencode-ai/sdk-next"
import { Effect } from "effect"

const program = Effect.gen(function* () {
  const opencode = yield* OpenCode.create()

  yield* opencode.plugin({
    id: "example.reviewer",
    effect: (ctx) =>
      ctx.agent.transform((draft) => {
        draft.update("reviewer", (agent) => {
          agent.description = "检查代码并给出修改建议"
          agent.system = "分析代码质量，并说明建议的依据。"
          agent.mode = "primary"
        })
      }).pipe(Effect.asVoid),
  })

  const location = Location.Ref.make({
    directory: AbsolutePath.make(process.cwd()),
  })
  return yield* opencode.plugin.list({ location })
})

const result = await Effect.runPromise(program.pipe(Effect.scoped))
console.log(result.data)

Ассистент в примере определяет только назначение и промпт; разрешения настраиваются отдельно. После примера закрывается Scope, владеющий хостом. В реальном встраиваемом приложении этот Scope должен охватывать весь жизненный цикл сервиса.

Область действия и обновления SDK-плагина следует рассматривать на двух уровнях:

Уровень	Управляемые данные	Область действия
Реестр хоста	`Map<plugin.id, Versioned>`: хранение определения и возрастающей ревизии	Общий для одного встраиваемого хоста; у разных хостов отдельные реестры
Активный набор Location	Экземпляры плагинов, Transform, Hook и Scope в контексте данного каталога	Отдельная активация и очистка для каждого Location

Каждая регистрация публикует sdk.plugin.updated. Уже работающие Location при обновлении пересоздают набор плагинов. Новые Location и повторно запущенные после освобождения читают текущее определение из реестра хоста. Поэтому одна регистрация хостом не означает однократную инициализацию. Изменяемые объекты в замыкании могут совместно использоваться несколькими экземплярами Location одного хоста; их нельзя автоматически считать состоянием отдельного сеанса.

Повторная передача того же ID в один SDK-реестр заменяет определение и создаёт новую ревизию. Разные хосты друг друга не перезаписывают. Возврат из регистрации означает лишь запись определения и публикацию обновления, а не завершение активации во всех Location. Для проверки нужно запросить фактические списки плагинов и возможностей целевого Location и при необходимости дождаться события активации.

Текущий SDK-реестр предоставляет только register и all; отдельного интерфейса unregister нет. Конфигурация каждого Location может отключить активацию по ID, но не удаляет определение из реестра хоста. Закрытие хоста очищает ресурсы выполнения. После его пересоздания плагины нужно регистрировать заново: прежняя регистрация в памяти не является постоянной записью об установке.

SDK принимает Effect-плагины. Автоматическая адаптация Promise-плагинов внешним загрузчиком здесь не выполняется. Для повторного использования Promise-определения нужно явно применить соответствующий адаптер fromPromise . SDK-путь не внедряет дополнительные options ; публичный Context по умолчанию предоставляет пустой объект. Собственные настройки и бизнес-клиенты хост обычно передаёт фабричной функцией или замыканием.

SDK-плагин также не получает автоматически среду сервисов Core внутренних плагинов. Хост может явно передать зависимости, но прямое использование приватных сервисов Core усиливает привязку к версии. В исследованном коде sdk-next всё ещё является переходным пакетом с private: true , поэтому пример не обещает доступности опубликованного стабильного npm API для установки.

Основания: точка входа встраиваемого хоста (packages/sdk-next/src/opencode.ts), SDK-реестр (packages/core/src/plugin/sdk.ts), состояние SDK-пакета (packages/sdk-next/package.json), публичный хост плагинов (packages/core/src/plugin/host.ts). Исходники встраиваемых тестов (packages/sdk-next/test/embedded.test.ts) содержат сценарии обновления между Location, повторной активации после освобождения Location и изоляции хостов. Эти сценарии изучены, но тесты независимо не запускались.

Три источника объединяются в один упорядоченный набор активации. После определения включённых элементов текущий порядок таков:

内部 pre → SDK 注册插件 → 外部文件 / 包插件 → 内部 post

ConfigPluginSource отвечает за внешние источники и операции конфигурации; PluginSupervisor объединяет их с внутренними и SDK-определениями; Plugin.Service выполняет окончательную проверку повторяющихся ID, управление Scope, инициализацию и замену. Три источника не следует представлять как три независимых движка.

Из-за такого порядка возможности ассистентов, предоставленные внешними и SDK-плагинами, могут быть изменены последующими конфигурационными плагинами. Для определения окончательного промпта, модели или разрешений нужно читать итоговый список возможностей, а не только начальное определение отдельного плагина.

ID плагина, имя пакета и путь точки входа выполняют разные роли. Например, если конфигурация загружает файл, экспортирующий плагин с ID example.reviewer , для отключения нужно указать -example.reviewer. Селекторы поддерживают точный ID, prefix.* и *. Операции конфигурации выполняются последовательно, и последующая операция может повторно включить существующее определение.

Важно различать два правила совпадения имён:

Повторная регистрация одного ID в одном SDK-реестре: обновляет соответствующее определение; реестр поддерживает такую замену.
Один и тот же ID из разных действующих источников: этап активации отклоняет весь текущий набор из-за дублирования ID, а не молча перезаписывает по приоритету источника. Не передавайте одно определение одновременно внешним файлом и через SDK.

Кроме того, текущий Plugin.Service пропускает активацию, если ID и версии всего упорядоченного набора полностью совпадают. При любом изменении набора он обходит новый набор, очищает и повторно инициализирует уже существующие плагины. Обновление одного источника может переинициализировать и неизменённые плагины. Все три вида должны правильно освобождать ресурсы и не считать инициализацию однократным бизнес-действием. При неудачной замене предпринимается восстановление старой версии, но уже возникшие внешние бизнес-эффекты откатить нельзя.

Основания: объединение источников и порядок включения/отключения (packages/core/src/plugin/supervisor.ts), единая активация и замена (packages/core/src/plugin.ts), исходники тестов конфигурации и порядка загрузки (packages/core/test/config/plugin.test.ts).

Первая основная часть Plugin: Transform

Transform объявляет возможности, Hook обрабатывает конкретное выполнение. Выбирая точку расширения, сначала определите, к какой области относится задача.

Задача	Нативный интерфейс расширения
Зарегистрировать, изменить или удалить ассистента	`ctx.agent.transform`
Зарегистрировать исполняемый инструмент	`ctx.tool.transform`
Предоставить описание навыка и точки доступа к ресурсам	`ctx.skill.transform`
Добавить команду	`ctx.command.transform`
Изменить каталог провайдеров и моделей и выбор по умолчанию	`ctx.catalog.transform`
Предоставить источники справочных материалов	`ctx.reference.transform`
Настроить аутентификацию и подключение	`ctx.integration.transform`
Предоставить поисковый бэкенд	`ctx.websearch.transform`
Изменить контекст и видимые инструменты текущего запроса	`ctx.session.hook("context", ...)`
Проверить вход инструмента или обработать результат	`ctx.tool.hook(...)`
Изменить SDK модели или её экземпляр	`ctx.aisdk.hook(...)`
Изменить HTTP-запрос или ответ модели	`ctx.session.hook("http.request" / "http.response", ...)`
Изменить параметры создания команды	`ctx.shell.hook("create.before", ...)`
Наблюдать события в реальном времени	`ctx.event.subscribe()`
Создавать сеанс, отправлять ему данные, ожидать или прерывать его	`ctx.session.*`

Области состояния Agent, Catalog, Command, Integration, Reference, Skill и другие сохраняют активные Transform и последовательно пересоздают состояние из базового. При выгрузке плагина его Transform удаляется, затем результат строится заново. Transform должен изменять только Draft текущего вызова, не сохраняя ссылку на него и не создавая внешних бизнес-эффектов при пересборке. Внешние данные следует сначала загрузить и сохранить, а затем вызвать у соответствующей области reload().

В основе Tool — регистрация инструментов, связанная со Scope, и снимки для запросов. Жизненный цикл имеет ту же принадлежность, что и перечисленные области, но нельзя заключать, что все transform используют полностью одинаковые контейнеры состояния или возвращаемые типы.

Вторая основная часть Plugin: Hook

Hook — точка расширения, предусмотренная хостом в процессе выполнения. Плагин регистрирует callback в точке расширения. Когда OpenCode достигает соответствующего узла, он автоматически вызывает callback и передаёт контекст узла. В рамках контракта интерфейса плагин может читать данные, менять параметры или обрабатывать результаты, участвуя в запросах модели, выполнении инструментов и других процессах.

Работа Hook делится на регистрацию и срабатывание. При инициализации плагин через ctx.session.hook(...), ctx.tool.hook(...) и другие интерфейсы объявляет нужные узлы. Хост вызывает callback только при достижении узла во время выполнения. После одной регистрации callback может срабатывать многократно при повторных прохождениях узла. Хост ждёт завершения callback и продолжает согласно контракту; например, tool.execute.before позволяет через Tool.Error отклонить выполнение инструмента.

Transform формирует доступные возможности, а Hook изменяет их поведение в конкретных узлах. Например, инструмент регистрируют через ctx.tool.transform; вход отдельного вызова проверяют через ctx.tool.hook("execute.before", ...); контекст, который отправится модели, меняют через ctx.session.hook("context", ...). Hook входит в текущую цепочку вызовов, а ctx.event.subscribe() служит для подписки на события и наблюдения выполнения.

Хуки выполнения вызываются последовательно в порядке регистрации. Поздний Hook видит изменения ранних. Если несколько плагинов меняют одно поле, проверяйте окончательный порядок загрузки. Встроенные плагины разделены на предшествующий и последующий наборы; нельзя считать, что внешние всегда перезаписывают последними.

Hook	Что можно изменять или наблюдать	Замечания
`session.context`	Системный промпт, сообщения и определения инструментов текущего запроса	ID ассистента и модели задают идентичность контекста; изменение сообщений влияет только на текущий запрос и не означает добавления в постоянную историю
`tool.execute.before`	Входные данные инструмента	Можно вернуть `Tool.Error` для запрета выполнения
`tool.execute.after`	Успешный результат или ошибка инструмента	Обработка результата и добавление информации
`session.http.request/response`	HTTP-запрос и ответ модели	Возможен доступ к учётным данным и полному вводу; содержимое журналов нужно контролировать
`aisdk.sdk/language`	SDK и фактический экземпляр модели	Подходит для адаптации провайдера
`shell.create.before`	Команда, каталог, лимит времени, Shell и переменные окружения	Строковые правила сами по себе не обеспечивают системную изоляцию

Среди текущих публичных типов Hook только tool.execute.before объявляет восстанавливаемый канал ошибки Tool.Error . Остальные Hook нельзя считать универсальным middleware для произвольного выбрасывания бизнес-ошибок.

Основания: Plugin Context (packages/plugin/src/effect/plugin.ts), пересборка состояния (packages/core/src/state.ts), регистрация и выполнение Hook (packages/core/src/plugin/hooks.ts), регистрация инструментов и снимки (packages/core/src/tool.ts).

Примеры инструментов и жизненный цикл

Пример 1: определение Tool через Plugin Transform

Инструмент содержит определение, видимое модели, и функцию, исполняемую хостом. После того как модель создаёт имя и вход инструмента, OpenCode обрабатывает вызов с возможностями, зафиксированными для текущего запроса. Функция инструмента получает предоставленные хостом sessionID, agent, messageID и данные вызова id; длительная операция может сообщать ход выполнения через context.progress() .

Ниже приведён самостоятельный пример инструмента с Effect API:

import { Plugin } from "@opencode-ai/plugin/effect"
import { Effect, Schema } from "effect"

export default Plugin.define({
  id: "example.echo",
  effect: Effect.fn(function* (ctx) {
    yield* ctx.tool.transform((tools) => {
      tools.add({
        name: "echo",
        description: "返回收到的文字",
        input: Schema.Struct({ text: Schema.String }),
        output: Schema.Struct({ text: Schema.String }),
        options: { codemode: false },
        execute: ({ text }) =>
          Effect.succeed({
            output: { text },
            content: text,
          }),
      })
    })
  }),
})

Поля результата различаются по назначению:output — структурированное значение для программного использования после объявления выходной Schema;content передаётся модели и входит в содержимое сеанса;metadata содержит ограниченное дополнительное состояние. Возврат output без объявления выходной Schema считается ошибкой в текущей реализации.

В исходниках есть два нюанса валидации, более конкретных, чем названия интерфейсов:

tool.execute.before выполняется раньше декодирования Schema внутри функции инструмента. Поэтому Hook должен считать вход неизвестной структурой. После изменений Hook вход поступает на последующее декодирование.
Effect Schema и поддерживаемые Standard Schema проверяют вход во время выполнения; ветка чистой JSON Schema передаёт вход напрямую. Выходная ветка чистой JSON Schema проверяет лишь, является ли результат JSON-значением, но не каждое объявленное ограничение. Предоставление JSON Schema модели не означает, что сервер проверил параметры бизнес-инструмента.

В текущем канале инструментов ошибка самого предварительного Hook сразу прерывает дальнейшую обработку. Нельзя предполагать, что для такого отказа всегда сработает execute.after . Аудит должен покрывать и пути отказа, а не только события после успешного выполнения.

Ожидаемую восстанавливаемую ошибку инструмента можно отобразить в Tool.Error. Отмена, неизвестный дефект программы и успешный результат должны сохранять разные значения; нельзя поглощать их все и возвращать обычный текст успеха.

Основания: типы инструментов (packages/schema/src/tool.ts), оболочка выполнения инструмента (packages/core/src/tool.ts), фактическая проверка параметров (packages/core/src/tool/runtime.ts).

Пример 2: композиция вызовов через Code Mode

Code Mode определяет представление и композицию части инструментов. Текущая ветка напрямую показывает модели инструменты с codemode: false ; остальные могут попасть в каталог Code Mode, где через execute запускается короткий код для композиции вызовов и обработки результатов. Фактические вызовы из Code Mode всё равно возвращаются в путь выполнения инструментов хоста.

Это подходит для последовательных запросов, фильтрации и агрегации. Среда Code Mode ограничивает прямой доступ к файлам, импорты и подобные операции, но это не означает, что весь сервис OpenCode или внешние плагины работают в системной песочнице. В примере echo выше задано codemode: false, что демонстрирует прямое предоставление инструмента модели.

Запрос к модели фиксирует снимок текущей регистрации инструментов. Горячее обновление не заставляет уже подготовленный запрос использовать новый список; последующие запросы заново подготавливают возможности. Функция инструмента, предоставленная плагином, также не должна зависеть от бесхозных фоновых ресурсов, которые могли быть очищены.

Основания: классификация инструментов и снимки (packages/core/src/tool.ts), Code Mode (packages/core/src/codemode/tool.ts), проверка доступности инструментов текущего запроса (packages/core/src/session/model-request.ts).

Location плагина

Экземпляры плагинов управляются по Location; постоянное бизнес-состояние нужно хранить отдельно. Location — контекст выполнения из каталога и необязательного нативного ID Workspace. Один процесс OpenCode может обслуживать несколько Location одновременно, и один плагин может отдельно активироваться в каждом.

У каждого экземпляра есть Scope, которому принадлежат Transform, Hook, регистрации инструментов и правильно привязанные ресурсы. При закрытии Scope регистрации очищаются. Таймеры плагина, сетевые подписки и наблюдение файлов тоже нужно связать с очисткой. Promise-плагин может из setup вернуть cleanup; Effect-плагин использует соответствующие scoped-ресурсы и finalizer.

首次加载 → 创建 Scope → 注册能力与钩子 → 服务会话
文件或配置变化 → 替换插件 → 清理旧 Scope → 激活新版本
新版本激活失败 → 尝试恢复旧版本 → 恢复失败则停用

Для локальных файлов точек входа и источников конфигурации предусмотрено наблюдение изменений. Если явная точка входа — каталог, изменения его внутренних файлов не имеют той же гарантии автоматического горячего обновления. Загрузка, обновление и остановка зависят и от фактического наблюдения и состояния выполнения. Поэтому заявление о поддержке горячего обновления не заменяет проверку нативного списка возможностей.

Восстановление плагина возвращает код и регистрации, но не откатывает побочные эффекты в файлах, базах данных или удалённых сервисах. Задания по расписанию, состояния согласований, числа повторных попыток и ключи идемпотентности должны храниться надёжно. Состояние сеансов в памяти нужно разделять как минимум по sessionID . Глобальные переменные модуля могут совместно использоваться разными экземплярами плагина, поэтому требуют особой осторожности.

Основания: Scope плагина и восстановление (packages/core/src/plugin.ts), наблюдение файлов плагина (packages/core/src/config/plugin/source.ts).

Практические рекомендации для Plugin

При разработке сначала используйте существующую конфигурацию и публичные интерфейсы:

Для изменения промпта, назначения или предела шагов используйте конфигурацию Agent.
Для методов работы и знаний используйте Skill.
Для новых реальных действий регистрируйте Tool.
Чтобы изменить поведение в узле выполнения, используйте соответствующий Hook.
Если плагин должен сохранять бизнес-состояние или вызывать внешние сервисы, явно спроектируйте хранение, аутентификацию, транзакции и идемпотентность. Состояние плагина в памяти не должно обеспечивать эти гарантии.

Плагин с одной ответственностью может состоять из одного TS-файла. Разделяйте его на несколько ID только тогда, когда возможности требуют независимого включения, версий или стратегии отказов. Обычные внешние плагины должны зависеть от публичных интерфейсов плагинов, клиента и schema, избегая приватных реализаций Core. При распространении явно укажите совместимые версии хоста и зависимостей, точку входа модуля и способ сборки.

При обновлении Plugin проверяйте как минимум следующее, а не только успешность импорта модуля:

Появляются ли Agent, инструменты и навыки в фактическом списке возможностей и исчезает ли их вклад после выгрузки.
Соответствует ли ожиданиям итоговое состояние при разных порядках плагинов, перекрытии конфигурации и сбоях горячего обновления.
Сохраняют ли вход, выход, отмена и отказ выполнения инструмента правильную семантику.
Действительно ли применяются выбор модели и ассистента сеанса; получают ли подчинённые ассистенты ожидаемые разрешения и контекст.
Правильно ли пользовательские инструменты и вызываемые ими сервисы проверяют принадлежность сеанса, бизнес-права, переходы состояния и повторные запросы.
Восстанавливается ли постоянное состояние после перезапуска сервиса и правильно ли обрабатывается потеря событий реального времени.
Точно ли результаты инструментов и события отражают прогресс, завершение, ошибку и отмену.

Перечитывая «Чистую архитектуру» (6): границы

Mon, 29 Jul 2024 06:13:15 +0800

Что такое границы

Проектирование архитектуры ПО само по себе является искусством проведения границ.

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

Как проводить границы? Можно опираться на следующие основные принципы:

Границы следует проводить между несвязанными вещами, например GUI и бизнес-логикой. Ввод и вывод (GUI) несущественны для бизнес-логики: с ней могут работать разные реализации GUI.
Границы следует проводить вдоль осей изменения системы. Компоненты по разные стороны должны меняться по разным причинам и с разной скоростью. Оси изменения помогают определить SRP на уровне модулей и классов и CCP на уровне компонентов.

Разобравшись с ролью границ и принципами их проведения, можно перейти к основному процессу:

Сначала разделите систему на компоненты: одни содержат основную бизнес-логику, другие являются плагинами, не относящимися к ней, но предоставляющими необходимые функции.
Измените исходный код так, чтобы неосновные компоненты зависели от компонентов основной бизнес-логики.

Проведение границ — конкретное применение принципа инверсии зависимостей и принципа устойчивых абстракций. Стрелка зависимости должна идти от низкоуровневой конкретной реализации к высокоуровневой абстракции.

Разбор границ

Архитектуру системы определяют программные компоненты и границы между ними

Границы бывают разными. В этой главе они рассматриваются на примере вызовов через границу.

Во время выполнения вызов через границу означает, что функция с одной стороны вызывает функцию с другой и передаёт ей данные. Чтобы устроить такие вызовы правильно, нужно управлять зависимостями исходного кода. Иначе изменение кода одного модуля может потребовать изменения или перекомпиляции других модулей и их повторного развёртывания. Чёткие границы помогают сократить число таких случаев.

Вызовы через границы можно разделить на уровни исходного кода, развёртывания, сервисов и физические границы.

Вызовы через границы на уровне исходного кода

Такие вызовы встречаются в монолитной архитектуре. Для управления внутренними зависимостями ей обычно требуется динамический полиморфизм в той или иной форме.

Самый простой случай — низкоуровневый клиент вызывает высокоуровневую сервисную функцию. И во время выполнения, и при компиляции зависимость направлена одинаково: от низкоуровневого компонента к высокоуровневому.

(Исходная схема пока отсутствует)

Но когда клиент высокоуровневого компонента должен вызвать службу низкоуровневого, динамический полиморфизм необходим для инверсии зависимости. Интерфейс Service на схеме представляет собой одну из форм SPI.

(Исходная схема пока отсутствует)

Вызовы через границы на уровне развёртывания

На уровне развёртывания каждая развёртываемая единица упаковывается в удобный для работы формат файла. Помимо этого, компоненты, разделённые на таком уровне, почти не отличаются от монолитной структуры.

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

Вызовы через границы на уровне сервисов

Сервисы образуют самую сильную границу в архитектуре: каждый сервис является процессом. При проведении архитектурных границ необходимо максимально ограничивать число взаимодействий. На этом уровне обмен должен выдерживать высокие задержки. В остальном применимы те же правила, что для локальных процессов: низкоуровневые сервисы должны становиться плагинами высокоуровневых.

Перечитывая «Чистую архитектуру» (5): архитектура ПО

Sun, 28 Jul 2024 19:23:23 +0800

Пора перейти к архитектуре ПО. Ранее мы рассмотрели модули, классы и компоненты; эта часть посвящена основному определению программной архитектуры.

Прежде всего

🌟 Архитектор ПО должен сам быть программистом и продолжать непосредственно писать код. Не сталкиваясь лично с трудностями, вызванными устройством системы, он не почувствует последствий плохого проектирования и постепенно утратит правильное направление.

Что такое архитектура ПО?

Суть архитектурной работы — обсуждать и планировать разделение системы на компоненты, определять их расположение, связи и способы взаимодействия, то есть устанавливать границы.

У проектирования архитектуры обычно две цели:

Упростить разработку, развёртывание, эксплуатацию и сопровождение компонентов.
Чтобы все эти виды работы продвигались легче, при проектировании нужно как можно дольше сохранять как можно больше вариантов выбора;

Качество архитектуры слабо связано с тем, работает ли система правильно, то есть с её поведением. В мире немало систем с плохой архитектурой, которые исправно работают. Настоящие проблемы чаще возникают при разработке, развёртывании и последующем расширении. Это косвенно отражает мысль автора: архитектурная ценность системы в определённой мере важнее поведенческой.

Цели архитектурного проектирования:

Основная направленность: хорошая архитектура строится вокруг вариантов использования, сосредоточивается на них и изолирует их от окружающих факторов. Для этого выборы откладывают как можно дольше, сохраняя больше возможностей.
Главная цель: поддерживать весь жизненный цикл ПО. Хорошая архитектура делает систему понятной, удобной для изменения и сопровождения, а также простой в развёртывании.
Конечная цель: максимизировать производительность программистов, освобождая их возможности, и минимизировать совокупные эксплуатационные затраты системы.

Главное в архитектурном проектировании — отделить друг от друга правила, а затем перегруппировать их по характеру изменений, проведя границы. Здесь можно опираться на SRP, CCP, CSP, SDP, SAP и другие принципы.

Обязанности архитектуры ПО

Архитектура отвечает за разработку, развёртывание, эксплуатацию и сопровождение.

В разработке архитектура должна упрощать создание системы. Поэтому разным командам нужны разные архитектурные решения. В определённой мере это отражает закон Конвея.

Почему закон Конвея связывает архитектуру со структурой команды? Подробнее — в видео:Закон Конвея: почему архитектура отражает структуру команды? — bilibili

В развёртывании архитектура должна обеспечивать простое развёртывание одним действием.

В эксплуатации:

Как уже отмечалось, влияние архитектуры на эффективность выполнения меньше, чем на остальные аспекты. Автор объясняет это тем, что дополнительные аппаратные ресурсы могут компенсировать недостаточное внимание к выполнению, тогда как архитектурная работа обычно требует более дорогих человеческих ресурсов.
Архитектура должна не только влиять на эффективность, но и отражать эксплуатационные требования системы. Хорошее устройство должно позволять разработчику сразу понимать, как система работает. Варианты использования, функции и обязательное поведение нужно сделать видимыми сущностями первого уровня, упрощая понимание. Именно об этом говорится в главе «Кричащая архитектура».

Сопровождение обычно обходится дороже всего. Его затраты делятся на исследование и риск:

Исследование (spelunking): затраты на изучение существующей системы, чтобы определить лучшее место и способ добавления функции или исправления проблемы.
Риск (risk): при таких изменениях всегда возможно появление новых проблем. Эта вероятность и составляет затраты риска.

Сохранять варианты выбора

Вспомним два вида ценности: поведенческую и архитектурную. Повысить архитектурную ценность значит сделать ПО гибче, а для этого архитектура должна сохранять как можно больше вариантов выбора.

Элементы программной системы делятся на правила и детали. Правила охватывают бизнес-правила и рабочие процессы и представляют настоящую ценность системы. Детали позволяют пользователям, другим системам и программистам взаимодействовать с правилами, не влияя на сами правила. Примеры — устройства IO и базы данных. Выбор таких деталей нужно по возможности оставлять открытым.

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

Автор объясняет важность отсрочки деталей на примере независимости от устройств. Современные ОС поддерживают множество устройств ввода-вывода. На заре вычислительной техники основным, почти единственным способом была перфолента, поэтому программисты естественным образом вплетали код её чтения и записи в системный код. С появлением магнитной ленты пришлось писать новый код, затем появились оптические диски… Чтобы избежать повторной разработки и слабой адаптируемости, устройства стали абстрагировать функциями. OS взаимодействует с ними через функции, а разработчики предоставляют конкретные реализации. Ввод-вывод становится плагином OS. Это также прообраз принципа открытости/закрытости: приветствовать 👏 добавление, сопротивляться 🥊 изменению!

Сохранять независимость

Хорошая архитектура должна обеспечивать достаточную независимость.

Разделение зависимостей помогает её сохранять.

Разделение бывает горизонтальным и вертикальным.

Горизонтальное разделение, или разделение по слоям: систему можно разделить на горизонтальные слои — UI, базу данных и так далее.
Разделение вариантов использования, или вертикальное разделение: одновременно со слоями выделяют вертикальные срезы по вариантам использования. Например, UI добавления заказа отделяют от UI удаления заказа.

Если разделять систему по разным причинам изменений, можно постоянно добавлять новые варианты использования, не затрагивая существующие.

Уровни разделения также различаются: исходный код, развёртывание и сервисы.

Уровень исходного кода: контролируются зависимости между модулями, а компоненты взаимодействуют вызовами функций. Такой режим называется монолитной структурой.
Уровень развёртывания: контролируются зависимости между единицами развёртывания, например файлами Jar. Компоненты могут взаимодействовать между потоками — обратите внимание, не по сети, — через Socket или разделяемую память.
Уровень сервисов: зависимости между компонентами сводятся к структурам данных, а взаимодействие происходит через сетевые пакеты. Например, микросервисы обмениваются данными через rpc или rest.

Строгого правила, какой уровень лучше, нет: по мере зрелости проекта лучший способ разделения может меняться. Хорошая архитектура позволяет начать с монолита, развёртываемого одним файлом, затем вырасти в набор независимых единиц развёртывания, сервисов или микросервисов, а при изменении обстоятельств постепенно вернуться к монолиту. При этом большая часть исходного кода должна оставаться защищённой от изменений. Для системы в целом способ разделения тоже должен оставаться вариантом выбора. Для крупного развёртывания можно использовать один способ, а для небольшого — другой.

Теперь рассмотрим, как разделение влияет на независимость системы.

Значение разделения для независимости выполнения

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

Значение разделения для независимости разработки

Если система правильно разделена по горизонтальным слоям и вариантам использования, архитектура поддерживает работу нескольких команд независимо от того, организованы ли они по функциям, компонентам, слоям или иным признакам.

Значение разделения для независимости развёртывания

При хорошем разделении реализации слоёв и конкретных вариантов использования можно даже заменять во время работы системы (hot-swap). Тогда для нового сценария достаточно добавить файлы jar или запустить сервисы, совершенно не затрагивая остальные части.

Что такое дублирование кода

Дублирование бывает двух видов:

Настоящее дублирование: повторения, которые нужно устранить.
Мнимое дублирование: похожий код, который в действительности развивается по разным путям, с разной скоростью и по разным причинам. Согласно CRP, код с разной частотой использования следует разделять по компонентам. Если не учитывать этого при чтении, мнимое дублирование легко принять за настоящее. Иногда такие повторы необходимы. Помните пример расчёта зарплаты?

(Конец пятой статьи)

Введение в предметно-ориентированное проектирование

Fri, 26 Jul 2024 19:49:45 +0800

Обзор предметно-ориентированного проектирования

Предметно-ориентированное проектирование (DDD, Domain-Driven Design) — подход к проектированию на основе моделей. Он фиксирует знания предметной области в модели и использует её для создания ПО, которое легче сопровождать.

Проектирование в DDD делится на стратегическое и тактическое. Стратегическое рассматривает предметные области, подобласти и ограниченные контексты; тактическое — сущности, объекты-значения, события предметной области и другие элементы. Их связь показана ниже:

Понятия стратегического проектирования

Предметная область

Предметная область — это область задач, которые должна решать система. Например, ею может быть управление информацией о товарах.

Подобласти

По различиям используемого языка предметную область можно разделить на подобласти:

Ключевая подобласть определяет основное конкурентное преимущество продукта. Это наиболее важная, центральная и специфическая часть бизнеса.
Общая подобласть предоставляет универсальные функции нескольким подобластям. Примеры — общие системы аутентификации и управления правами. Они не ограничены особенностями предприятия и не требуют большой адаптации.
Вспомогательная подобласть не содержит ни ключевых, ни универсальных функций. Она специфична для предприятия и не является общей; пример — системы справочников с кодами данных.

Ограниченный контекст

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

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

Зачем вводить ограниченные контексты? Потому что контекст усложняет написание кода. Рассмотрим пример:

В подборе персонала «платформа» может обозначать учебное заведение или организацию. В прыжках в воду это вышка, с которой прыгает спортсмен. На железной дороге это посадочная платформа. Представим, что однажды вместе оказались прыгун в воду, HR и проводник, не зная профессий друг друга. И HR спросил спортсмена: «С какой вы платформы?»…

Видите? Все трое используют слово «платформа», но без предварительной договорённости могут понимать его по-разному. Решение — разделить области прыжков в воду, найма и транспорта и определить термины внутри каждой. Обсуждение в пределах одной области максимально уменьшает неоднозначность. Это и есть договорённость. По той же причине связанные с бизнесом области лучше определить в одном ограниченном контексте: чтобы уменьшить неоднозначность.

Аналогичная проблема возникает при проектировании ПО. Допустим, большой продукт охватывает прыжки в воду, найм и поездки, но сервисы никак не разделены. В логике прыжков структура platform означает вышку, в найме — организационную платформу, в транспорте — перрон. Когда три направления неизбежно пересекутся, начнётся беда: что делать с экраном, заполненным почти одинаковыми именами переменных с разным смыслом?

Если точно ограничить смысл термина в предметной области, внутри неё его можно применять свободно. В этом и состоит важная роль ограниченного контекста.

Понятия тактического проектирования

Объекты-значения и сущности

Сначала познакомимся с объектами-значениями и сущностями.

Объект-значение определяется значениями своих свойств: два таких объекта с одинаковыми внутренними значениями считаются равными. Следовательно, свойства объекта-значения неизменяемы.
Сущность — бизнес-объект с уникальным идентификатором, состоянием и жизненным циклом. Её свойства изменяемы. Даже полностью одинаковые свойства не делают две сущности одной и той же: совпасть должны их идентификаторы, например ID.

Различим эти понятия на примере:

Предположим, у нас есть объект-значение белого цвета Color white{R:255, G:255, B:255} и сущность шины tire{Air:,Size:}:

Изменяемость: каждое свойство белого цвета неизменно, потому что после его изменения объект уже не обозначает белый цвет. Давление, размер и другие параметры шины могут меняться: она всё равно остаётся шиной.
Сравнимость: неизменяемость значений определяет правило равенства объектов-значений. Значения двух объектов белого цвета обязательно совпадают, поэтому объекты с одинаковыми внутренними значениями считаются равными. У сущностей из-за изменяемости свойств такого свойства нет.

У сущностей обычно выделяют четыре формы модели:

Модель без поведения содержит только данные и методы getter/setter. Вся бизнес-логика и прикладная логика размещается в сервисном слое. В Java такой класс называют POJO.
Анемичная модель включает часть бизнес-логики, но не ту, что зависит от слоя хранения. Логика, зависящая от хранения, находится в сервисном слое.
Богатая модель содержит всю бизнес-логику, включая зависимую от слоя хранения.
Перегруженная модель помещает в предметную модель и другую прикладную логику, не относящуюся к бизнес-логике, например авторизацию и транзакции.

Репозиторий Repo

Repo определяет операции хранения для Entity. Операции должны быть по возможности низкоуровневыми, иметь короткие имена и не быть слишком многочисленными. MyBatis Mapper в Java можно рассматривать как реализацию Repo.

Агрегаты и корни агрегатов

Агрегат — инкапсуляция большего масштаба. Он объединяет сущности и объекты-значения с общим жизненным циклом, неразделимые с точки зрения бизнеса. Внешние ссылки разрешено предоставлять только корню агрегата. Агрегат также выражает связность. Корни могут вызывать друг друга; их названия обычно являются существительными.

Корень агрегата обеспечивает инкапсуляцию следующими способами:

Работать со всем агрегатом нужно через его корень; внешний код не должен напрямую обращаться к внутренним элементам. Например, фиолетовый цвет кузова + шины + стальная рама + … = автомобиль. При вождении мы не управляем отдельно шиной, рулём или внешностью. Мы действуем через автомобиль как корень агрегата, косвенно управляя остальными сущностями и объектами-значениями.
Агрегат задаёт границу, внутри которой все компоненты должны быть корректны с точки зрения бизнес-логики.
Работа с агрегатом должна проходить в одной атомарной транзакции, иначе возможны ошибки. Агрегат — единица операции: извлечение из репозитория, изменение и возврат составляют атомарное действие. Например, если автомобиль включает колёса и стальную, алюминиевую или карбоновую раму, нельзя снять колесо для ремонта и после ремонта не установить его обратно.

События предметной области — Domain Events

Изменение свойств сущности порождает событие предметной области — происходящее в ней событие, которое эксперты считают значимым и заслуживающим внимания. Обычно оно означает изменение состояния предметного объекта.События передают сообщения, запускают другие действия и служат важным средством уменьшения зависимостей предметной модели. Для их передачи часто используют очередь сообщений, чтобы каждая подписанная подобласть выполнила собственную внутреннюю реакцию.

Шина сообщений — ещё один способ реализации 👋.

Например, изменение давления в сущности шины порождает событие утечки leaked. Оно передаёт сообщение «шина спускает», вызывая другие реакции: изменение работы силовой системы, ощущений на руле и так далее. Названия событий обычно ставят в прошедшее время, показывая, что событие уже произошло и необратимо.

Сервис предметной области — Domain Service

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

Сервис предметной области — не тот же «сервис», что в микросервисах. Сервисы и корни агрегатов отчасти похожи: оба могут работать с несколькими сущностями. Но их идеи и роли различаются. Корень агрегата объединяет сущности, а сервис синхронизирует состояния нескольких сущностей, например добавляет сущность item в сущность list — скажем, доставляет mail в inbox. Поэтому название Service обычно выражается глаголом.

Моделирование предметной области в DDD

Обычная последовательность моделирования:

На основе требований предварительно выделить подобласти, ограниченные контексты и связи между контекстами.
Подробно изучить каждый контекст, определить сущности и объекты-значения, а затем выбрать форму модели сущностей: без поведения, анемичную, богатую или перегруженную.
Связать сущности и объекты-значения в агрегаты, определить их границы и корни.
Спроектировать repo для корней агрегатов и продумать создание сущностей и объектов-значений.
Применить модель в проекте, проверить её обоснованность практикой, выявить недостатки и выполнить рефакторинг.

Это двухэтапный подход DDD: сначала стратегическое проектирование, затем тактическое.

На практике рекомендуются сущности без поведения, с одними setter/getter, или анемичные модели с простой логикой без операций базы данных, например проверкой допустимости свойств.

Это лишь один способ моделирования DDD — сверху вниз. Возможен и подход снизу вверх: сначала определить предметные модели, сущности и объекты-значения, а затем подобласти и ограниченные контексты…

(Конец раздела)

Перечитывая «Чистую архитектуру» (4): принципы компонентов

Sat, 06 Jul 2024 17:27:18 +0800

Перечитывая «Чистую архитектуру» (4): принципы построения компонентов

Третья статья была посвящена проектированию модулей и классов. Теперь пойдём дальше и рассмотрим проектирование компонентов.

Компонент — единица развёртывания ПО, наименьшая сущность системы, которую можно развернуть независимо. Компоненты можно разрабатывать отдельно; компонентная плагинная архитектура уже стала привычным способом построения ПО.

Связность компонентов

Принципы связности объясняют, какие модули и классы объединять в компоненты. Основных принципов три:

Принцип эквивалентности повторного использования и выпуска.
Принцип общей закрытости.
Принцип совместного повторного использования.

Эквивалентность повторного использования и выпуска — REP

REP утверждает: минимальная единица повторного использования ПО должна совпадать с минимальной единицей его выпуска.

REP рассматривает повторное использование кода. Он позволяет объединять код с общей темой и функциями в компонент и рекомендует повторно использовать ПО именно компонентами.

Проще говоря, упакованный выпуск компонента получает номер версии или уникальный идентификатор. Мы повторно используем код, подключая готовую библиотеку: единицей подключения служит пакет компонента, а идентификатором — версия.

Общая закрытость — CCP

CCP предписывает объединять в одном компоненте классы, которые меняются одновременно и по одной причине. Классы, которые не меняются одновременно или по одной причине, следует размещать в разных компонентах.

CCP смотрит на сопровождение кода. Объединение кода с общей причиной и целью изменений снижает нагрузку, связанную с выпуском, проверкой и развёртыванием ПО.

Как уже отмечалось, CCP — компонентная версия SRP. Оба принципа можно выразить так:

Объединяйте то, что меняется одновременно по одной причине. Разделяйте то, что меняется по разным причинам и в разное время.

В SRP речь идёт о функциях и других составляющих класса или модуля.
В CCP — о классах и модулях, составляющих компонент.

Совместное повторное использование — CRP

CRP утверждает: не заставляйте пользователей компонента зависеть от того, что им не нужно.

Код с разными сценариями и частотой использования следует разносить по компонентам. CRP направлен на предотвращение ненужного разделения и является обобщением принципа разделения интерфейсов ISP.

Как обобщённая форма разделения интерфейсов, CRP вместе с ISP выражается так:

Не зависите от того, чем не пользуетесь.

В ISP это функции или классы, содержащие ненужные методы.
В CCP это классы или модули, содержащие ненужные функции.

Размышление

Как связаны REP, CCP и CRP?

Между ними существует конкуренция.

REP и CCP — объединяющие принципы: они подсказывают, какие классы и модули собрать в компонент. CRP — исключающий принцип: он показывает, какие классы и модули не следует объединять.

Если учитывать только REP и CCP, зависимости ПО будут содержать много ненужных частей, что приведёт к лишним выпускам.
Если учитывать только CRP и CCP, повторное использование станет очень трудным.
Если учитывать только REP и CRP, изменение некоторых классов или модулей неизбежно потребует изменений множества связанных модулей.

Задача архитектора — находить компромисс между тремя принципами. Состав компонентов должен эволюционировать вместе с приоритетами проекта и балансом удобства разработки и повторного использования. Поэтому направление развития нужно оценивать динамически.

Зависимости между компонентами

Принципы зависимостей объясняют, как организовывать отношения между компонентами. Их три:

Принцип ацикличности зависимостей — ADP.
Принцип устойчивых зависимостей — SDP.
Принцип устойчивых абстракций — SAP.

Ацикличность зависимостей — ADP

ADP утверждает: в графе зависимостей компонентов не должно быть циклов.

Управление номерами версий решает проблему «синдрома следующего утра», но для этого нужно соблюдать ADP. Сначала посмотрим, как автор описывает этот синдром:

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

Обычно предлагают два решения:

Еженедельная сборка.
Управление номерами версий.

Еженедельная сборка: каждый работает в собственном репозитории, а раз в неделю, например в пятницу, проект собирают и устраняют конфликты.

Ограничения этого подхода очевидны:

По мере роста проекта интеграцию всё труднее завершать вовремя.
Сборка и тестирование усложняются, цикл обратной связи удлиняется, и качество разработки закономерно падает.

Поэтому требуется управление номерами версий.

Управление номерами версий: после выпуска новой версии компонента каждая зависимая команда самостоятельно решает, переходить ли на неё сразу.

Управление номерами версий не допускает циклов в графе зависимостей компонентов, то есть требует соблюдения ADP. Иначе синдром следующего утра неизбежен. Почему?

Цикл объединяет все входящие в него компоненты в один большой компонент. Их версии должны согласованно совпадать, чтобы остальные компоненты могли успешно подключать их. Циклы также затрудняют тестирование. Хотя mock-заглушки распространены, повторно создавать их для компонентов всего цикла весьма неэлегантно.

Как устранить циклическую зависимость? Есть два способа:

Создать интерфейсы с помощью инверсии зависимостей.
Создать новый компонент.

Применение DIP понятно. Рассмотрим рабочий случай, показывающий, как разорвать цикл созданием нового компонента.

Команда проектирует систему с помощью DDD. Сущность Entity Dog зависит от Dog Repo для операции сохранения Save, поэтому модуль Entity зависит от Repo. К несчастью, Dog PO тоже определён в Entity — неудачное решение. Функции Save в Repo нужен PO для преобразования и сохранения объекта. Возникает цикл Entity ↔ Repo. К счастью, Go запрещает взаимные зависимости модулей, и проверка сообщает о циклическом импорте. Как поступить?

Нужно создать модуль PO, перенести в него PO из Entity и отнести туда функции Repo, зависящие от PO. Это устраняет цикл. Другой вариант — внедрение зависимостей. При использовании SprintBoot проблему может решить @AutoWired, но по существу он также создаёт новый компонент — пул зависимостей, — устраняя цикл.

Подобных примеров много. Помните конфликты версий библиотек при установке пакетов Python через anaconda?

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

Но автор специально отмечает невозможность проектирования сверху вниз. Посмотрим на объяснение в книге:

[!NOTE]

Граф компонентов должен меняться и расширяться вместе с системой; идеально спроектировать его с самого начала нельзя. Он не соответствует функциям один к одному, а скорее представляет карту возможностей сборки и сопровождения приложения.

По мере появления новых спроектированных и реализованных модулей возникает потребность управлять зависимостями. Мы стремимся максимально ограничить область влияния изменений, поэтому с помощью SRP и CCP объединяем классы, которые часто меняются одновременно.

Важная цель графа компонентов — показывать, как изолировать частые изменения. Часто меняющиеся компоненты не должны влиять на те, которые обязаны оставаться устойчивыми.

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

Устойчивые зависимости — SDP

SDP утверждает: зависимости должны указывать в сторону большей устойчивости. Как правило, нижние уровни архитектуры должны быть устойчивее.

От компонента, который должен часто меняться, не должен зависеть компонент, который трудно изменить. Иначе первый тоже станет трудноизменяемым. В этом одна из трудностей разработки: тщательно спроектированный гибкий компонент может стать жёстким из-за единственной чужой зависимости. Соблюдение SDP позволяет этого избежать.

Для оценки устойчивости автор предлагает показатель: $$ I=\frac{Fan-out}{Fan-in+Fan-out} $$ Fan-in — число входящих зависимостей, Fan-out — исходящих. Чем меньше у компонента исходящих зависимостей, тем он устойчивее: при нулевом значении отсутствуют внешние факторы, заставляющие его меняться.

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

SDP не требует устойчивости всех компонентов. Граф проектируют именно для выбора, какие компоненты должны быть устойчивыми, а какие — нет. Полностью устойчивая архитектура негибка, а негибкая архитектура не обладает достаточной архитектурной ценностью.

Устойчивые абстракции — SAP

SAP утверждает: степень абстрактности компонента должна соответствовать его устойчивости.

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

Абстрактный класс — промежуточная зона между интерфейсом и классом.

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

Аналогично устойчивости, абстрактность можно измерять показателем: $$ A=\frac{N_c}{N_a} $$ Nc — число классов компонента, Na — число абстрактных классов и интерфейсов. A принимает значения от 0 до 1: 0 означает отсутствие абстрактных классов, 1 — наличие только абстрактных классов.

Размышление 🤔

Связаны ли SDP и SAP?

Во-первых, связь SDP, SAP и DIP

Фактически SDP + SAP = DIP для компонентов. SDP требует направлять зависимости к более устойчивому, а SAP говорит, что устойчивость подразумевает абстрактность. Следовательно, зависимости должны направляться к более абстрактному.

Как это понимать?

DIP обеспечивает гибкость на уровне классов. SDP + SAP обеспечивают достаточную гибкость компонентов при сохранении устойчивости. И DIP, и SDP + SAP направляют архитектурные зависимости от конкретных реализаций к абстрактным классам и интерфейсам. Поэтому по своей роли SDP + SAP равны компонентному DIP.

Но различия остаются. Для класса нет серой зоны: он либо абстрактный, либо нет. SDP и SAP применяются к компонентам, которые могут быть частично абстрактными и частично устойчивыми.

Во-вторых, общность целей SAP и SDP

SDP направляет зависимости к устойчивому, а SAP требует размещать высокоуровневые правила в абстрактных компонентах. Это позволяет отделять правила от деталей и поддерживать плагинную разработку. Их цели согласованы.

Снова встретилось выражение плагинная разработка. Где оно было раньше? В DIP, инверсии зависимостей. Это ещё раз показывает сходство SAP + SDP с DIP для компонентов.

Главная последовательность

Если совместить показатель неустойчивости I и показатель абстрактности A на графике, прямая a = -i + 1 называется линией главной последовательности.

На графике выделяют три области:

Зона боли около (0, 0): компоненты очень устойчивы и одновременно конкретны, поэтому их трудно менять. Пример — таблицы базы данных. Вспомогательные библиотеки также относятся к зоне боли: хотя их I равен 1, поскольку они зависят от множества компонентов и потому неустойчивы, изменять их нельзя без проблем в большом количестве кода.
Зона бесполезности около (1, 1): компоненты чрезмерно абстрактны, но другие от них не зависят, поэтому ими часто невозможно пользоваться. Проблемы исходного кода и классов здесь обычно имеют исторические причины, например забытый старый код.
Зона главной последовательности: оптимальные положения компонентов — концы линии (0, 1) и (1, 0). Хороший архитектор должен стремиться приблизить к ним большую часть своих компонентов.

Как оценивать компонент в целом? Рассчитать расстояние до главной последовательности, количественно выражающее соответствие проекта ей. Это показатель D: 0 означает расположение прямо на линии, 1 — максимальное удаление. $$ D=|A+I-1| $$ Степень превышения D над нулём помогает направлять рефакторинг и перепроектирование компонентов.

У D есть и другие применения. Например, среднее значение и дисперсия D всех компонентов позволяют статистически оценивать устройство системы:

У хорошо спроектированной системы среднее значение и дисперсия D должны быть близки к нулю.
Дисперсию можно использовать как порог соответствия, выявляя нетипичные компоненты.
Можно также отслеживать дисперсию D во времени, наблюдая, как меняются устойчивость и абстрактность архитектуры.

(Конец четвёртой статьи)

Перечитывая «Чистую архитектуру» (3): принципы SOLID

Fri, 05 Jul 2024 14:11:30 +0800

Перечитывая «Чистую архитектуру» (3): принципы SOLID

При построении программных модулей преследуют три основные цели:

Сделать ПО устойчивым к изменениям.
Сделать ПО более понятным.
Создавать компоненты, пригодные для повторного использования в разных программных системах.

Принципы SOLID прежде всего объясняют, как объединять данные и функции в классы, а затем связывать классы в программу. Они направляют проектирование модулей; на уровне архитектуры действуют другие принципы.

SOLID включает принцип единственной ответственности SRP, принцип открытости/закрытости OCP, принцип подстановки Лисков LSP, принцип разделения интерфейсов ISP и принцип инверсии зависимостей DIP.

Принцип единственной ответственности — SRP

SRP определяет для каждого модуля одну ответственность: должна существовать только одна причина для его изменения. Каждый программный модуль должен отвечать только перед одной категорией действующих лиц.

На уровне компонентов SRP называется принципом общей закрытости — CCP.

Что произойдёт, если проектировать модуль без соблюдения SRP? Рассмотрим пример.

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

CalculateSalary: расчёт зарплаты.
CalculateTime: расчёт рабочего времени.
Save: сохранение информации.

Три отдела спокойно пользуются программой. Однажды у финансового отдела меняется порядок расчёта зарплаты, и его специалисты изменяют функцию CalculateSalary. После этого происходит неожиданное: одновременно меняется зарплата у кадровой службы и отдела разработки…

Принцип открытости/закрытости — OCP

«Приветствовать добавление, сопротивляться изменению!»

OCP утверждает: чтобы программную систему было легче менять, её устройство должно позволять изменять поведение добавлением нового кода, а не только правкой существующего. Хорошо спроектированное ПО легко расширяется и сопротивляется изменению.

OCP относится не только к классам и модулям, но и к компонентам. Он вырос из идеи независимости от устройств. Например, инверсия зависимостей позволяет оформить устройства IO как плагины, чтобы легко добавлять новые, не изменяя прежние.

OCP реализуют, разделяя систему на компоненты и организуя их зависимости в иерархию, при которой изменения низкоуровневых компонентов не затрагивают высокоуровневые.

Принцип подстановки Лисков — LSP

LSP утверждает: чтобы строить систему из взаимозаменяемых компонентов, все эти компоненты должны соблюдать один и тот же контракт.

Суть LSP — взаимозаменяемость: если для каждого объекта o1 типа S существует объект o2 типа T, причём поведение программы P, работающей с T, не меняется при замене o2 на o1, то S можно назвать подтипом T.

LSP можно и нужно применять на архитектурном уровне: нарушение взаимозаменяемости заставляет добавлять множество сложных компенсирующих механизмов.

Принцип разделения интерфейсов — ISP

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

Инверсия зависимостей — DIP

DIP утверждает: код высокоуровневых правил не должен зависеть от кода низкоуровневых деталей. Напротив, низкоуровневая реализация должна зависеть от высокоуровневых правил.

Для простого объяснения инверсии зависимостей нужно различать поток управления и зависимости исходного кода. Пусть управление идёт от компонента A к B. В таком устройстве B должен знать реализацию A, а A должен подключать модуль B, поэтому зависимость кода тоже направлена от A к B. Поведение системы определяет поток управления, а он — зависимости кода, и у архитектуры не остаётся выбора. После введения интерфейса B лишь реализует его; связь с B проходит через интерфейс, а A подключает интерфейс. A больше не нужно подключать модуль B. Направления потока управления и зависимости исходного кода становятся противоположными — это и есть инверсия зависимостей.

Инверсия зависимостей даёт свободу архитектурному проектированию. Для гибкой системы зависимости исходного кода должны чаще ссылаться на абстракции — интерфейсы, абстрактные классы и подобные типы, — а не на конкретные реализации.

Из DIP следуют несколько правил написания кода:

Чаще используйте абстрактные интерфейсы и по возможности избегайте изменчивых конкретных классов реализации.
Не создавайте производные классы от конкретных классов реализации.
Не переопределяйте (override) функции, содержащие конкретную реализацию.
Избегайте в коде имён, привязанных к конкретной реализации, и других легко меняющихся сущностей.

(Конец третьей статьи)

Перечитывая «Чистую архитектуру» (2): парадигмы программирования

Fri, 05 Jul 2024 07:25:33 +0800

Перечитывая «Чистую архитектуру» (2)

Парадигма программирования — это модель написания программ. Она подсказывает, какую структуру кода и в каких обстоятельствах следует использовать.

К настоящему времени появились три парадигмы: структурное, объектно-ориентированное и функциональное программирование.

По мнению автора, каждая парадигма не расширяет арсенал архитектора. Напротив, у архитекторов и программистов уже достаточно средств, а эти три парадигмы вводят ограничения на их применение. Именно поэтому они и называются парадигмами.

Структурное программирование

Структурное программирование ограничивает и упорядочивает прямую передачу управления; в частности, оно ограничивает произвольное использование goto.

Декомпозиция программы

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

Он также обнаружил, что большое количество goto затрудняет декомпозицию программы, хотя все задачи оператора goto можно решать с помощью ветвлений и циклов.

Структурная парадигма показывает, что программы можно декомпозировать: большую задачу разбивают на сочетание высокоуровневых функций, каждую из которых далее делят на низкоуровневые функции, рекурсивно продолжая этот процесс. Кроме того, каждую полученную функцию также можно написать в рамках структурной парадигмы.

Однако программирование с такими формальными доказательствами не стало основным подходом. Чаще применяется научный метод проверки.

Научный метод проверки

Научные теории и законы можно опровергнуть, но нельзя окончательно доказать. Аналогично, тесты могут опровергнуть корректность программы, но не доказать её: «Тестирование может показать наличие ошибок, но не доказать их отсутствие». Применяя научный метод, структурная парадигма побуждает сначала рекурсивно разложить программу на небольшие проверяемые функции, а затем написать соответствующие тесты, пытаясь показать, что функции ошибочны. Если тесты не опровергают их корректность, функции можно считать достаточно правильными, а на этом основании — и всю программу.

Объектно-ориентированное программирование

Объектно-ориентированное программирование ограничивает и упорядочивает косвенную передачу управления.

В частности, объектно-ориентированное программирование использует полиморфизм, чтобы ограничить применение указателей на функции. Их цели можно понимать как ограниченное множество: например, полиморфизм в java обычно возникает между объектами двух классов, связанных наследованием.

Автор также считает полиморфизм главным свойством OOP. С его помощью достигается инверсия зависимостей:

Инверсия зависимостей означает введение интерфейсов, позволяющих полностью управлять зависимостями исходного кода системы независимо от потока управления.

Она позволяет разрабатывать систему как набор плагинов. Например, инвертировав зависимости между web UI, базой данных и бизнес-логикой, можно отделить основную бизнес-логику от UI и базы данных. Тогда UI и база данных становятся её плагинами.

Объектно-ориентированное программирование — это способность управлять зависимостями исходного кода посредством полиморфизма. Она позволяет архитектору создавать плагинную архитектуру, отделяя высокоуровневые правила от низкоуровневых реализаций. Низкоуровневые компоненты можно компилировать в плагины, разрабатывать и развёртывать независимо от высокоуровневых.

Функциональное программирование

Функциональное программирование ограничивает и упорядочивает присваивание в программе.

Иными словами, переменные в функциональном языке неизменяемы.

Автор высказывает следующую мысль; это цитата из оригинала:

«Все гонки, взаимные блокировки и проблемы параллельного обновления обусловлены изменяемыми переменными. Если переменные никогда не изменяются, гонки и конфликты параллельного обновления невозможны. Если состояние блокировки неизменно, взаимная блокировка никогда не возникнет».

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

Изоляция изменяемости

Распространённый способ изолировать изменяемость — разделить приложение или его внутренние службы, выделив изменяемые и неизменяемые компоненты. Неизменяемые компоненты выполняют задачи чистыми функциями, не меняя никакого состояния. Для изменения состояния переменных они взаимодействуют с одним или несколькими нефункциональными, то есть изменяемыми, компонентами.

Пример — система управления версиями GIT. Она фиксирует добавление, удаление и изменение файлов с помощью перемещения указателей. При этом сами файлы фактически не изменяются и не удаляются: остаются только добавление и поиск. Разве это не пример неизменяемости?

Эта же идея используется в управлении транзакциями mysql и в транзакционной памяти.

Итоги

Три парадигмы тесно связаны с архитектурой ПО:

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

Эти три парадигмы совпадают с тремя главными заботами архитектуры ПО: независимостью компонентов (объектно-ориентированная парадигма), управлением данными (функциональная парадигма) и функциональностью (структурная парадигма).

Ещё одно размышление

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

(Конец второй статьи)

Перечитывая «Чистую архитектуру» (1)

Wed, 03 Jul 2024 23:10:20 +0800

Предисловие

Почему я перечитываю эту книгу? Я уже читал «Чистую архитектуру», но тогда мне не хватало проектной практики, проб и ошибок, поэтому понимание казалось поверхностным. Во время работы мне наконец довелось столкнуться с реальными проектами и требованиями. Ещё удачнее оказалось то, что наша команда использовала именно чистую архитектуру — точнее, сочетание событийной разработки, DDD и чистой архитектуры. Подробнее о DDD я расскажу позже. Я перечитал книгу 📚 и многое из неё вынес. В этой серии я попробую изложить собственное понимание чистой архитектуры; точнее будет назвать её читательскими заметками для коллег.

Книгу можно найти здесь: Чистая архитектура — Роберт К. Мартин — WeChat Read (qq.com)

Серия будет следовать структуре глав книги и постепенно углубляться в тему вместе с автором. Поскольку это повторное чтение, я неизбежно буду обращаться и к другим частям книги. Если встретится что-то непонятное или незнакомое, скорее всего, эта тема рассматривается в следующих главах.

Начнём.

Что означают дизайн и архитектура

По существу, между дизайном и архитектурой нет различия: низкоуровневые детали проектирования и высокоуровневая архитектура вместе определяют программную систему.

Конечная цель архитектуры ПО — удовлетворять потребности в создании и сопровождении системы с минимальными трудозатратами. Поэтому затраты позволяют оценивать качество архитектурного решения.

Система, поспешно созданная без продуманного проектирования, может превратиться в запутанный клубок. При её развитии качеством кода и улучшением структуры долгое время пренебрегают. Внимательное проектирование архитектуры в определённой мере помогает избежать такого состояния и тем самым снизить затраты.

У разработки ПО есть две важные особенности:

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

Два измерения ценности

У программной системы есть два вида ценности:

Поведенческая ценность: заставить машину работать заданным образом и приносить или увеличивать прибыль пользователей системы.
Архитектурная ценность: ПО должно быть достаточно гибким, а стоимость его изменения — зависеть от масштаба требований, а не от их формы.

Как понимать масштаб и форму требований? На мой взгляд, масштаб — это приблизительный объём требований и соответствующая предметная область, а форма — конкретные детали этих требований.

Какое измерение ценности важнее? Автор считает архитектурную ценность более важной, чем поведенческую, потому что:

Если программа работает, но её нельзя изменить, при изменении требований она перестанет работать должным образом. Исправить её для новых условий также не получится. В результате её ценность станет нулевой.
Если программа пока не работает правильно, но её легко изменить, исправить её и затем приспосабливать к новым требованиям должно быть несложно. Такая программа будет продолжать создавать ценность.

Общая ошибка бизнеса и разработчиков — не отделять действительно срочные и важные функции от срочных, но неважных. В результате важные архитектурные вопросы уступают место неважным поведенческим функциям.

Именно разработчики отвечают за баланс между важностью архитектуры системы и срочностью функциональных требований.

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

Продолжать бороться за хорошую архитектуру ✊

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

Как загрузить параметры модели PyTorch в MindSpore

Fri, 01 Sep 2023 22:53:58 +0530

Описание задачи

При разработке и обучении моделей часто встречается следующая ситуация: в открытых проектах и воспроизведениях научных работ большинство моделей спроектированы и реализованы на Pytorch, который также используется для обучения и инференса. Если же разработку нужно вести на MindSpore, возникают две проблемы:

Код модели написан на Pytorch.
Сохранённые после обучения параметры модели Pytorch нельзя напрямую загрузить в модель MindSpore.

Первую проблему можно решить переносом модели по официальной документации MindSpore: Типичные отличия от Pytorch и Таблица соответствия API PyTorch и MindSpore.

Для преобразования параметров MindConverter в рассматриваемой актуальной версии MindSpore больше не поддерживается. Поэтому можно выполнить ручное преобразование: перевести параметры модели Pytorch в формат, распознаваемый MindSpore, и затем загрузить их.

Решение

На преобразовании кода модели подробно останавливаться не будем.

Основная схема преобразования параметров:

Загрузить модель Pytorch средствами Pytorch и получить параметры prams_torch.
Загрузить модель MindSpore средствами MindSpore и получить параметры prams_ms.
Установить взаимно однозначное соответствие между именами параметров моделей Pytorch и MindSpore, где оно существует.
Создать таблицу соответствия ключей torch_2_ms и с её помощью поместить значения параметров Pytorch в позиции, соответствующие именам параметров MindSpore.
Загрузить параметры средствами MindSpore.

Разбор примера

Модули и типы параметров у моделей различаются. На примере одной сети рассмотрим основной подход к преобразованию; для других моделей он будет аналогичным.

EfficientNet — работа Google, опубликованная в 2019 году. Подробная архитектура сети описана в статье. Здесь в качестве примера возьмём EfficientNet+FC модель с полносвязным слоем и рассмотрим преобразование параметров сети.

Загрузка модели Pytorch и получение параметров prams_torch

import torch
from test.efficientnet_pytorch.model import EfficientNet as EN_pytorch
import pandas as pd

pytorch_model = EN_pytorch.from_name(cfg['model'], override_params={'num_classes': 3})
pytorch_model.cuda()
pytorch_weights_dict = pytorch_model.state_dict()
param_torch = pytorch_weights_dict.keys()
param_torch_lst = pd.DataFrame(param_torch)
param_torch_lst.to_csv('param_torch.csv')

После этого шага параметры модели pytorch сохранены в param_torch.csv. Посмотрим на данные:

	keys
0	_conv_stem.weight
1	_bn0.weight
2	_bn0.bias
3	_bn0.running_mean
4	_bn0.running_var
5	_bn0.num_batches_tracked
6	_blocks.0._depthwise_conv.weight
7	_blocks.0._bn1.weight
8	_blocks.0._bn1.bias
9	_blocks.0._bn1.running_mean
10	_blocks.0._bn1.running_var

Загрузка модели MindSpore и получение параметров prams_ms

import mindspore as ms
from test.efficientnet_mindspore.model import EfficientNet as EN_ms
import pandas as pd

mindspore_model = EN_ms.from_name(cfg['model'], override_params={'num_classes': 3})
prams_ms = mindspore_model.parameters_dict().keys()
prams_ms_lst = pd.DataFrame(prams_ms)
prams_ms_lst.to_csv('prams_ms.csv')

После этого шага параметры модели MindSpore сохранены в prams_ms.csv. Посмотрим на данные:

	keys
0	_conv_stem.weight
1	_bn0.moving_mean
2	_bn0.moving_variance
3	_bn0.gamma
4	_bn0.beta
5	0._depthwise_conv.weight
6	0._bn1.moving_mean
7	0._bn1.moving_variance
8	0._bn1.gamma
9	0._bn1.beta
10	0._se_reduce.weight

Сопоставление имён параметров моделей Pytorch и MindSpore

Теперь у нас есть таблицы ключей параметров MindSpore и Pytorch, приложенные в разделе вложений. Сравнив их, можно обнаружить устойчивые закономерности именования. Вот несколько примеров:

Batch Normalization:
- Веса: weight|bias — gamma|beta.
- Скользящие среднее и дисперсия: running_mean|running_var — moving_mean|moving_variance.
Пользовательские blocks: у pytorch есть префикс _blocks.
Другие различия

Таблица соответствия ключей

По найденным закономерностям можно написать Python-скрипт, который преобразует имена ключей и создаст таблицу соответствия:

Pytorch	mindspore
_conv_stem.weight	_conv_stem.weight
_bn0.weight	_bn0.gamma
_bn0.bias	_bn0.beta
_bn0.running_mean	_bn0.moving_mean
_bn0.running_var	_bn0.moving_variance
_blocks.0._depthwise_conv.weight	0._depthwise_conv.weight
_blocks.0._bn1.weight	0._bn1.gamma
_blocks.0._bn1.bias	0._bn1.beta
_blocks.0._bn1.running_mean	0._bn1.moving_mean
_blocks.0._bn1.running_var	0._bn1.moving_variance
_blocks.0._se_reduce.weight	0._se_reduce.weight

Затем из словаря весов Pytorch берём значение по Pytorch_key из файла соответствия, оборачиваем его в mindspore.Parameter и добавляем в набор весов по соответствующему mindspore.key:

for i in ms_param_lst.values:
    ms_key = i
    pt_key = param_mapping[ms_key]
    pt_val = pt_values_dict[pt_key]
    if not isinstance(pt_val, np.ndarray):
        pt_val = pt_val.cpu().numpy()
    ms_val = Parameter(pt_val, ms_key)
    print(ms_val)
    ms_values_dict[ms_key] = ms_val

Загрузка параметров средствами MindSpore

load_param_into_net(mindspore_model, ms_values_dict)

Теперь MindSpore должен принять параметры.

What’s more

При сохранении значений параметров учитывайте различия точности параметров между Pytorch и MindSpore.

(Конец)

За пределами градиента: матрица Гессе

Fri, 01 Sep 2023 22:53:58 +0530

В этой статье рассматривается мощный математический инструмент для изучения градиентного спуска — матрица Гессе. Прежде чем переходить к ней, необходимо познакомиться с основными понятиями градиента и матрицы Якоби.

⭐ Предполагается, что читатель уже знаком с градиентным спуском и основами численного анализа и линейной алгебры. Ссылка на оригинал

Градиент и матрица Якоби

Алгоритму градиентного спуска нужна информация о производной функции в текущей точке. Если направлений несколько, градиент представляет собой вектор (частных) производных по всем направлениям.

Это относится к случаю одного выходного значения. Если же результат функции тоже является вектором, необходимо градиенты каждого элемента выходного вектора по нескольким входам собрать вместе. Полученная матрица называется матрицей Якоби (Jacobian Matrix).

Рассмотрим примеры:

Если функция $f$ принимает три входа $x1、x2、x3$ и выдаёт один результат $y$, её градиент имеет вид:

$$ \begin{equation} Grad = [\frac{\partial y}{\partial x_1}, \frac{\partial y}{\partial x_2}, \frac{\partial y}{\partial x_3}] \end{equation} $$

Если функция $f2$ принимает три входа $x1、x2、x3$ и выдаёт три результата $y1、y2、y3$, её матрица Якоби имеет вид:

$$ \begin{equation} Jacobian = \begin{bmatrix} \frac{\partial y_1}{\partial x_1} & \frac{\partial y_1}{\partial x_2}&\frac{\partial y_1}{\partial x_3} \ \frac{\partial y_2}{\partial x_1} & \frac{\partial y_2}{\partial x_2}&\frac{\partial y_2}{\partial x_3} \ \frac{\partial y_3}{\partial x_1} & \frac{\partial y_3}{\partial x_2}&\frac{\partial y_3}{\partial x_3} \end{bmatrix} \end{equation} $$

Вторая производная даёт информацию о выпуклости или вогнутости функции в заданном направлении $d$. Это позволяет в определённой мере предвидеть поведение градиентного спуска. В направлении $d$:

Если вторая производная положительна, первая производная в направлении $d$ растёт, а значение функции убывает медленнее.
Если вторая производная отрицательна, первая производная в направлении $d$ уменьшается, а значение функции убывает быстрее.
Если вторая производная равна нулю, первая производная в направлении $d$ не меняется, и значение функции убывает с постоянной скоростью.

⭐ В градиентном спуске уменьшают функцию потерь, поэтому изменение производной анализируют на убывающем небольшом участке функции. Для приближения часто используют убывающую часть квадратичной функции: разложение Тейлора второго порядка или метод Ньютона.

Матрица Гессе

Аналогично матрице Якоби, матрица Гессе (Hessian) содержит информацию о вторых производных функции: $$ Hessian = \begin{bmatrix} \frac{\partial^2y}{\partial x_1\partial x_1} & \frac{\partial^2y}{\partial x_1\partial x_2}&\frac{\partial^2y}{\partial x_1\partial x_3} \ \frac{\partial^2y}{\partial x_2\partial x_1} & \frac{\partial^2y}{\partial x_2\partial x_2}&\frac{\partial^2y}{\partial x_2\partial x_3} \ \frac{\partial^2y}{\partial x_3\partial x_1} & \frac{\partial^2y}{\partial x_3\partial x_2}&\frac{\partial^2y}{\partial x_3\partial x_3} \end{bmatrix} $$ Поскольку порядок вычисления смешанных вторых производных можно менять, то есть $\frac{\partial^2y}{\partial x_1\partial x_2}=\frac{\partial^2y}{\partial x_2\partial x_1}$, матрица Гессе симметрична. Для симметричной матрицы можно использовать спектральное разложение, чтобы исследовать связь собственных значений со вторыми производными и быстро получать вторую производную в выбранном направлении.

Для заданного направления d вторая производная записывается как $d^THd$. Тогда:

🔗 Вторые производные по направлению и свойства матрицы Гессе — статья в блоге CSDN

Если d — собственный вектор H, соответствующий собственному значению λ:

Поскольку d является собственным вектором, соответствующим λ (далее — собственным вектором), по определению: $$ Hd = \lambda d\ \Rightarrow d^THd=d^T\lambda d = \lambda d^Td=\lambda \ \ \ 对称矩阵d^T = d^- $$

Следовательно, собственное значение λ, соответствующее собственному вектору, является второй производной в этом направлении.
Если d имеет другое направление, пусть $e_i$ — собственный вектор $H$, соответствующий собственному значению $\lambda_i$. Из предыдущего следует: $$ \lambda_i=e_i^THe_i $$ Любое направление $d=\sum_i^mt_ie_i$ представляет собой линейную комбинацию собственных векторов, где m — число собственных значений, а $t_i$ — вес $i$-го собственного вектора. Тогда: $$ d^THd=(\sum_i^mt_ie_i)^TH(\sum_i^mt_ie_i)=\sum_i^mt_ie_i^THt_ie_i=\sum_i^mt_i^2\lambda_i $$ Таким образом, вторая производная в направлении, не совпадающем с собственным вектором, является взвешенной суммой всех собственных значений. В частности, эта взвешенная сумма образует эллипсоид. В двумерном случае собственных значений вторая производная задаёт эллипс с уравнением: $$ y=\frac{\lambda_1}{\frac{1}{t_1^2}}+\frac{\lambda_2}{\frac{1}{t_2^2}} $$

Из рисунка видно, что наибольшую вторую производную определяет максимальное собственное значение (большая полуось), а наименьшую — минимальное собственное значение (малая полуось).

Применение матрицы Гессе

Разобравшись с определением, можно применять свойства матрицы Гессе для анализа задач оптимизации: определять локальные максимумы, минимумы и седловые точки, выбирать скорость обучения и оценивать поведение градиентного спуска при плохой обусловленности. Матрица Гессе также позволяет реализовать метод Ньютона — ещё один алгоритм оптимизации.

(Конец раздела)

Обзор

Sat, 25 Jun 2022 18:35:46 +0530