JSON Templates for Developers — Ready-to-Use Examples for APIs, Config & DevOps

Зачем использовать JSON-шаблоны?

Каждый разработчик неоднократно писал одни и те же структуры JSON — обертка ответа API, tsconfig.json, файл Docker Compose. Каждый раз вы либо копируете из предыдущего проекта (надеясь, что он был правильным), либо пишете с нуля (вводя тонкие ошибки).

Шаблоны устраняют этот цикл. Начало с проверенной структуры дает вам четыре конкретных преимущества:

• Экономия времени. Пропустите проблему пустого файла. Шаблон позволяет быстрее перейти к интересной части вашей работы.
• Обеспечение согласованности. Когда каждая служба в вашей организации возвращает одну и ту же обертку API, потребители могут написать один обработчик ответа вместо десяти.
• Снижение ошибок. Забыв об обязательном поле в манифесте Kubernetes, вы можете разрушить развертывание. Шаблоны включают поля, которые вы иначе могли бы забыть.
• Быстрое введение в курс дела. Новые члены команды могут прочитать шаблон и сразу понять ожидаемую структуру, вместо того чтобы восстанавливать ее из производственных данных.

Шаблоны ниже охватывают самые распространенные структуры JSON в современном разработке. Каждый из них доступен в нашей Библиотеке шаблонов, где вы можете скопировать их одним щелчком мыши.

Шаблоны ответов API

Самый важный JSON-шаблон, который вы можете использовать, — это согласованная обертка ответа API. Вместо того чтобы каждый конечный пункт возвращал произвольные формы, определите стандартную обертку с data при успехе, error при неудаче и meta для отслеживания запросов и пагинации.

Пагинированный ответ API

Вот реальный пагинированный ответ, следуя шаблону обертки:

{
  "data": [
    { "id": "usr_abc123", "name": "Алиса Джонсон", "role": "администратор" },
    { "id": "usr_def456", "name": "Боб Смит", "role": "участник" }
  ],
  "meta": {
    "total": 84,
    "page": 2,
    "per_page": 20,
    "total_pages": 5,
    "request_id": "req_9f3b7a"
  }
}

Эта структура позволяет клиентам отображать элементы управления пагинацией из meta без необходимости угадывать. request_id делает отладку служебных заявок тривиальной — просто ищите в ваших логах.

Просмотрите полные шаблоны: Успешный ответ REST API, Ошибка ответа REST API, Пагинированный ответ.

Шаблоны конфигурационных файлов

Конфигурационные файлы — это место, где большинство ошибок JSON происходит молча. Неправильный параметр компилятора в tsconfig.json не вызывает сбоя — он просто производит слегка неправильный вывод. Начало с проверенного шаблона помогает избежать этого.

Конфигурация TypeScript

Минимальный, но готовый к производству tsconfig.json для проекта Next.js:

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "jsx": "preserve",
    "paths": { "@/*": ["./src/*"] }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Ключевые выборы здесь: strict: true ловит ошибки типов на ранней стадии, moduleResolution: "bundler" соответствует современным сборщикам, а псевдоним пути @/* поддерживает чистоту импортов.

Шаблоны конфигурации: package.json, tsconfig.json, Конфигурация ESLint.

Шаблоны схемы базы данных

Будь то заполнение базы данных для разработки или определение структуры документа для MongoDB, наличие шаблона означает, что ваша команда согласовывает имена полей, типы и значения по умолчанию до первой строки кода приложения.

Документ пользователя MongoDB

{
  "_id": "ObjectId('66a1b2c3d4e5f6a7b8c9d0e1')",
  "email": "alice@example.com",
  "profile": {
    "firstName": "Алиса",
    "lastName": "Джонсон",
    "avatar": "https://cdn.example.com/avatars/alice.jpg"
  },
  "roles": ["администратор", "редактор"],
  "settings": { "theme": "dark", "locale": "ru-RU" },
  "createdAt": "2026-01-15T09:30:00Z",
  "updatedAt": "2026-03-20T14:22:00Z"
}

Эта структура группирует связанные поля под profile и settings, чтобы сохранить верхний уровень документа достаточно плоским для эффективной индексации, при этом логически группируя связанные данные.

Шаблоны баз данных: Схема MongoDB, Данные для начальной загрузки Prisma.

Шаблоны DevOps и облака

Файлы инфраструктуры как кода — это одни из самых подверженных ошибкам JSON, которые вы будете писать. Отсутствие поля в манифесте Kubernetes или шаблоне CloudFormation может вызвать молчаливые сбои, которые проявляются только в производстве. Шаблоны дают вам известную хорошую отправную точку.

Развертывание Kubernetes

Упрощенный манифест развертывания Kubernetes в формате JSON:

{
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "web-api",
    "labels": { "app": "web-api", "env": "production" }
  },
  "spec": {
    "replicas": 3,
    "selector": { "matchLabels": { "app": "web-api" } },
    "template": {
      "metadata": { "labels": { "app": "web-api" } },
      "spec": {
        "containers": [{
          "name": "web-api",
          "image": "registry.example.com/web-api:1.4.2",
          "ports": [{ "containerPort": 8080 }],
          "resources": {
            "requests": { "cpu": "250m", "memory": "256Mi" },
            "limits": { "cpu": "500m", "memory": "512Mi" }
          }
        }]
      }
    }
  }
}

Запросы и лимиты ресурсов включены по умолчанию — пропуск их является основной причиной проблем с соседями в общих кластерах. Метки следуют стандартной конвенции app / env, чтобы селекторы и сетевые политики работали сразу.

Шаблоны инфраструктуры: Docker Compose, Развертывание Kubernetes, Рабочий процесс GitHub Actions.

Шаблон полезной нагрузки JWT

JSON Web Tokens несут утверждения в виде JSON-полезной нагрузки. Правильное получение стандартных утверждений критично — отсутствие утверждения exp означает, что токены никогда не истекают, а неправильный iss нарушает проверку.

{
  "sub": "usr_abc123",
  "iss": "https://auth.example.com",
  "aud": "https://api.example.com",
  "exp": 1774648800,
  "iat": 1774645200,
  "nbf": 1774645200,
  "roles": ["администратор", "редактор"],
  "email": "alice@example.com"
}

Зарегистрированные утверждения (sub, iss, aud, exp, iat, nbf) следуют RFC 7519. Пользовательские утверждения, такие как roles и email, должны использовать короткие имена, чтобы уменьшить размер токена — JWT передаются в HTTP-заголовках, где каждый байт имеет значение.

Смотрите полный шаблон: Полезная нагрузка JWT.

Как настроить шаблоны

Шаблон — это отправная точка, а не готовый продукт. Вот практический рабочий процесс для адаптации любого шаблона к вашему проекту:

• Начните с ближайшего шаблона. Выберите тот, который наиболее близок к вашему случаю использования. Шаблон пагинированного ответа — это лучшее начало для конечной точки поиска, чем общий шаблон успешного ответа.
• Переименуйте и добавьте поля. Измените значения-заполнители на ваши фактические имена полей. Добавьте специфические для домена поля, которые нужны вашему приложению. Удалите поля, которые не применимы.
• Проверьте результат. Вставьте ваш измененный JSON в наш JSON Validator, чтобы поймать синтаксические ошибки — лишняя запятая или отсутствующая кавычка легко вводятся при редактировании вручную.
• Отформатируйте для удобочитаемости. Пропустите его через JSON Formatter, чтобы обеспечить согласованное выравнивание перед коммитом в вашу кодовую базу или делением с вашей командой.
• Закрепите его с помощью схемы. Для критических структур, таких как ответы API, определите JSON Schema, чтобы будущие изменения автоматически проверялись.

Просмотр всех шаблонов

Примеры в этом руководстве — это всего лишь образец. Наша Библиотека шаблонов включает 18 готовых к использованию шаблонов, охватывающих API, конфигурацию, базы данных, аутентификацию и облачную инфраструктуру — каждый с объяснениями полей и поддержкой копирования в буфер обмена.

Просмотрите полную коллекцию: Посетите Библиотеку шаблонов JSON, чтобы найти шаблоны для вашего стека. Скопируйте любой шаблон одним щелчком, настройте его и проверьте результат с помощью нашего JSON Formatter.