Ключевые моменты проектирования контрактов данных JSON API

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

В дизайне API нет стандартных ответов, но есть решения, которые «трудно отменить после выбора», и их лучше продумать до написания первой строки кода.

1. Оборачивать ответ или нет

Три стиля:

复制// Стиль A: голый ответ
{ "id": 1, "name": "张三" }

// Стиль B: оболочка data
{ "data": { "id": 1, "name": "张三" } }

// Стиль C: data + метаданные
{ "data": { "id": 1, "name": "张三" }, "meta": { "requestId": "a1b2" } }

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

2. Формат ошибок: копируйте RFC 9457

Изобретение собственной структуры ошибок — огромный источник стоимости сотрудничества. RFC 9457 (заменяет RFC 7807) определяет application/problem+json:

复制{
  "type": "https://bbdrug.com/problems/insufficient-balance",
  "title": "余额不足",
  "status": 422,
  "detail": "账户余额 12.00 元，本次扣款需要 30.00 元",
  "instance": "/accounts/A1001/payments/p-889",
  "balance": "12.00",
  "required": "30.00"
}

Поля расширения (например balance / required выше) разрешены спецификацией, и фронтенд может использовать их для точных сообщений вместо парсинга текста detail.

3. Пагинация: курсор лучше offset

复制// Пагинация по offset
{ "data": [], "page": { "offset": 40, "limit": 20, "total": 137 } }

// Пагинация по курсору
{ "data": [], "page": { "nextCursor": "eyJpZCI6MTAwfQ", "hasMore": true } }

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

4. ID и время

4.1 Всегда используйте строки для ID

Обоснование рассмотрено в статье о типах: на стороне JavaScript значения выше 2^53 молча теряют точность. Даже если текущий ID — маленькое автоинкрементное целое, использование строк оставляет место для перехода на snowflake ID позже.

复制{ "id": "1000000000000000001" }

4.2 Используйте строки RFC 3339 для времени

复制{
  "createdAt": "2026-10-30T10:41:45+08:00",
  "updatedAt": "2026-10-30T02:41:45Z"
}

• Не используйте числовые метки времени в миллисекундах: они трудночитаемы, и единицу (секунды/миллисекунды) часто путают;
• Указывайте часовой пояс явно: либо с Z, либо со смещением; никогда не используйте «локальное время без часового пояса»;
• Именуйте поля единообразно как xxxAt, чтобы с первого взгляда было очевидно, что это точка во времени.

5. null и отсутствие

Вы должны выбрать одно и записать это в документацию:

Проблема подхода A в том, что «опущено» и «отправлено как null» означают разное в PATCH, что легко неверно истолковать; проблема подхода B в том, что JSON.stringify во фронтенде отбрасывает поля со значением undefined, что случайно совпадает с семантикой.

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

• Используйте подход A для тел ответов (null ясно означает отсутствие значения, и фронтенду не нужно различать undefined);
• Используйте подход B для тел запросов (особенно PATCH), в сочетании с Merge Patch или JSON Patch, чтобы сделать семантику явной.

6. Именование и структура полей

Возврат [] вместо null для пустых массивов важен: data.items.map(...) во фронтенде не упадёт из-за null.

7. Стратегия эволюции

Три правила дисциплины:

1. Клиенты должны быть терпимы к неизвестным полям (не загоняйте себя в угол через additionalProperties: false);
2. Клиенты должны иметь запасную ветку для неизвестных значений перечислений;
3. Держите устаревшие поля как минимум одну мажорную версию и помечайте их Deprecation в заголовках ответа или документации.

8. Полный пример

复制{
  "data": [
    {
      "id": "1001",
      "name": "JSON 权威指南",
      "price": "89.50",
      "tags": ["json", "spec"],
      "publishedAt": "2026-09-01T00:00:00+08:00",
      "author": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req-7f3a", "tookMs": 12 }
}

Этот ответ отражает все соглашения выше: оболочка data, строковые ID, суммы как строки, метки времени с часовым поясом, null означает отсутствие, пустой массив, пагинация по курсору и meta для информации наблюдаемости.

9. Контрольный список

• [ ] Верхний уровень не массив; используйте оболочку data единообразно;
• [ ] Ответы об ошибках следуют RFC 9457 и включают стабильный type;
• [ ] Форма пагинации соответствует бизнес-сценарию;
• [ ] ID — строки, время использует RFC 3339;
• [ ] Семантика null и отсутствия записана в документацию;
• [ ] Стиль именования единообразен по проекту, перечисления используют строчные строки;
• [ ] Клиент имеет запасные варианты для неизвестных полей и неизвестных значений перечислений;
• [ ] Ломающие изменения проходят через версионирование или переход с двойной записью.

Вопросы и ответы

Как проектировать эволюционируемый JSON API?

Оборачивайте списки и детали единообразно в оболочку data и никогда не делайте верхний уровень массивом, чтобы пагинацию и трассировочные ID можно было добавить, не ломая контракт. Используйте строковые ID и метки времени RFC 3339 и запишите семантику null-против-отсутствия в документацию. Держите новые поля необязательными и семантически независимыми и давайте клиентам запасные варианты для неизвестных полей и значений перечислений.

Почему не изобретать собственный формат ошибок?

Изобретение собственной структуры ошибок — огромный источник стоимости сотрудничества. Копируйте application/problem+json по RFC 9457, идентифицируйте проблемы стабильным type и допускайте поля расширения вроде balance и required, чтобы фронтенд мог строить точные сообщения без парсинга текста detail.

Должна ли каждая конечная точка использовать пагинацию по курсору?

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