01
Начните с ответственности, а не технологии
«Сервис написан на Go» не объясняет, зачем он нужен. Для Order API полезнее: «создаёт заказ, хранит его состояние и принимает результат оплаты». Добавьте границы: он не принимает деньги и не рассчитывает доставку.
На карте SAQA поместите сервис в нужный продукт. Создайте его документ и начните с встроенного шаблона Service Doc или используйте структуру из скачиваемой заготовки.
02
Разделите свойства сервиса и свойства связи
Описание интеграции можно вести у связи. Общие правила заказа — у продукта, а специфические детали Order API — у сервиса. Это помогает не размножать один большой документ в нескольких местах.
| У сервиса | У связи |
|---|---|
| Назначение и границы ответственности. | Источник, получатель и направление обмена. |
| Сущности, состояния и владелец данных. | Протокол, формат и передаваемые поля. |
| Операции и ошибки сервиса. | Таймауты, повторы и реакция на отказ получателя. |
03
Сделайте контракт проверяемым
Добавьте хотя бы один конкретный запрос и ответ. Если схема, таблица полей и пример расходятся, исправьте расхождение до передачи в разработку.
- Для входа укажите обязательные поля, типы и ограничения.
- Для выхода — статус, поля и условия возврата.
- Для ошибок — причину и наблюдаемый результат.
- Для повторного вызова — что считается повтором и что возвращается.
04
Дайте точку входа для расследования
Запишите, по какому идентификатору искать операцию, какие состояния нормальны, какие метрики нужны и кто отвечает за сервис. Если подключены Prometheus или Zabbix, свяжите наблюдение с соответствующим сервисом.
Согласованные ограничения записывайте отдельно от пожеланий. Если значение таймаута ещё не определено, оставьте вопрос с ответственным, а не утверждение «высокая доступность».
05
Прочитайте документ глазами нового участника
- Можно объяснить назначение сервиса без разговора с автором.
- Все зависимости видны на карте или описаны в документе.
- По примерам можно подготовить запрос в API-клиенте.
- Неизвестные условия и участники согласования перечислены.
Заготовка Markdown — структура для переноса в документ. Автоматический импорт Markdown-файла этой инструкцией не предполагается.
МАТЕРИАЛЫ ДЛЯ РАБОТЫ
Продолжите на своём примере
Спецификация заказа
Заполненный пример: границы, сценарии, API, ошибки и критерии приёмки.
Шаблон описания сервиса
Назначение, зависимости, API, данные, эксплуатация и вопросы для согласования.
Учебные правила и данные нужно адаптировать к вашей системе. Набор не является готовой реализацией магазина.
Скачать полный набор ↓