Files
openspec-schema/openspec/schemas/use-case-driven/patterns/message-contract.md
T

4.0 KiB
Raw Blame History

Паттерн сериализуемого контракта

Используй паттерн для полей сериализуемых request/response-контрактов. Для HTTP endpoint таблицы находятся в разделах Request и Response блока CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся в типизированном FR [API].

HTTP endpoint

Каждый endpoint описывается отдельным Requirement с полным Use case. Сложные правила обработки указываются в FR, а контракт помещается в самом конце Requirement:

#### CONTRACT

##### Request

Метод: `POST`; путь: `/resource`. Для endpoint без тела явно укажи отсутствие тела.

##### Response

HTTP status: `200` при успешном выполнении.

| Поле | Тип | Обязательность | Ограничения и значение по умолчанию | Назначение | Формирование значения |
| --- | --- | --- | --- | --- | --- |
| `field_name` | `JSON type` | Обязательное | Формат и допустимые значения | Короткое назначение поля | Источник или правило вычисления значения |

Тело запроса при наличии описывай таблицей с пятью колонками:

Поле Тип Обязательность Ограничения и значение по умолчанию Назначение
field_name JSON type Обязательное или опциональное Формат, допустимые значения, nullable/default или явное отсутствие дополнительных ограничений и значений по умолчанию Короткое назначение поля

Для response используй эти же колонки и добавь последней «Формирование значения», чтобы для каждого поля указать источник значения или правило его вычисления.

Одна строка описывает одно поле. Указывай JSON-тип, а не тип языка реализации. Для вложенных полей используй путь из имён полей; для массивов указывай тип элемента. Обязательность задаёт наличие поля, а ограничения — nullability, формат, допустимые значения и default. Условие присутствия опционального поля укажи в ограничениях. Если дополнительных ограничений или значения по умолчанию нет, укажи это явно. Не оставляй ячейки пустыми и не используй тире.

Не создавай отдельные FR для HTTP request/response-контрактов. Не добавляй таблицу для отсутствующего тела запроса.

Сообщение или технический лог в FR [API]

Заголовок FR: <requirement-id>.FR-NN [API]: Контракт сообщения <имя> либо Контракт запроса / Контракт ответа. Сразу после заголовка укажи Тип контракта: request для отправляемых данных или Тип контракта: response для возвращаемых данных. Для отправляемого сообщения используй request. Один FR описывает одно направление и содержит одну таблицу по формату выше.