Template
58 lines
4.1 KiB
Markdown
58 lines
4.1 KiB
Markdown
# Паттерн сериализуемого контракта
|
|
|
|
Используй паттерн для полей сериализуемых request/response-контрактов.
|
|
Для HTTP endpoint таблицы находятся в разделах Request и Response блока
|
|
CONTRACT. Для асинхронного сообщения или технического лога контракт остаётся
|
|
в типизированном FR [API].
|
|
|
|
## HTTP endpoint
|
|
|
|
Каждый endpoint описывается отдельным Requirement; формат Use case выбирается
|
|
по сложности сценария. Сложные правила обработки указываются в FR, а контракт помещается в самом конце
|
|
Requirement:
|
|
|
|
```markdown
|
|
#### 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 описывает одно направление и содержит одну таблицу
|
|
по формату выше.
|