Назначение
Опиши, какой API вызывает typed client, кто владеет контрактом и какие сценарии потребляют client.
Границы
| Поле | Значение |
|---|
| Consumer service/app | <service-or-frontend-app> |
| Provider service | <service-name/external-provider> |
| OpenAPI source | <path/url> |
| Client package | <package/project> |
| Base URL config | <options class> |
| Auth scheme | <scheme> |
Операции
| OperationId | Method | Route | Request model | Response model |
|---|
<operationId> | <HTTP> | <route> | <RequestModel> | <ResponseModel> |
Модель Request <RequestModel>
| Поле | Тип | Обязательность | Источник | Валидация |
|---|
<FieldName> | <Type> | Да/Нет | <source> | <rule> |
Модель Response <ResponseModel>
| Поле | Тип | Обязательность | Правила nullable | Mapping |
|---|
<FieldName> | <Type> | Да/Нет | <when absent/null> | <internal model field> |
Политика Resilience
| Аспект | Правило |
|---|
| Timeout | <duration> |
| Retry | <retry count/backoff/retryable status> |
| Circuit breaker | <threshold/duration> |
| Bulkhead/rate limit | <rule> |
| Idempotency | <header/key source> |
Маппинг Ошибок
| HTTP status | Remote error | Local error | Повторяемость |
|---|
<status> | <remote code> | <ErrorCode> | Да/Нет |
Безопасность
| Контроль | Правило |
|---|
| Secrets | <where stored, rotation, not logged> |
| Tenant propagation | <TenantId header/claim/routing rule> |
| Correlation | X-Correlation-Id передается дальше. |
| Sensitive fields | <masked/excluded> |
Совместимость
| Тип изменения | Поведение client-а |
|---|
| Added optional field | <ignored/mapped when known> |
| Removed field | <breaking, requires version bump> |
| Unknown enum | <fallback/controlled failure> |
| New status code | <default typed remote error> |
Проверка
| Проверка | Инструмент |
|---|
| Generated client compiles | <command> |
| Contract test | <command> |
| Error mapping test | <command> |
| Resilience policy test | <command> |
Обратные ссылки
Автоссылки: где используется этот документ.