Конфигурации и данные — итоги
Кратко — что стоит унести из раздела "Конфигурации и данные". Если пункт кажется туманным — откройте указанную главу или оглавление.
FAQ — Часто задаваемые вопросы
Типичные ошибки при работе с конфигами и форматами данных. Здесь — что делать и где копать в главах; определения для зачёта — в чек-листе.
Вопрос. kubectl apply падает с "yaml: line 12: did not find expected key".
Ответ. Почти всегда сломан отступ или смешаны пробелы с табами. YAML чувствителен к иерархии; выровняйте блоки пробелами (2 или 4), проверьте через yamllint. Подробнее здесь — YAML.
Вопрос. В JSON после последнего поля стоит запятая — парсер в браузере OK, на сервере 500.
Ответ. Стандарт JSON запрещает trailing comma; часть парсеров терпимее. Уберите лишнюю запятую; в IDE включите JSON Schema. Подробнее здесь — JSON.
Вопрос. Пароль от БД лежит в appsettings.json в Git — что делать срочно?
Ответ. Считайте секрет скомпрометированным: смените пароль, уберите из истории Git (BFG/filter-repo), храните в vault / env / secrets manager. Подробнее здесь — Конфигурационные данные.
Вопрос. enabled: on в YAML включило флаг, хотя хотел строку "on".
Ответ. YAML 1.1 трактует on/off/yes/no как булевы значения. Заключите в кавычки: enabled: "on". Подробнее здесь — YAML.
Вопрос. XML "валидный", но парсер ругается на < внутри текста.
Ответ. Символы <, >, & в тексте нужно экранировать (< и т.д.) или обернуть в CDATA. Подробнее здесь — XML.
Вопрос. Два тега <Order> и <order> — "дубликат" или разные элементы?
Ответ. В XML имена чувствительны к регистру — это разные элементы. Договоритесь о стиле (PascalCase/camelCase) в схеме. Подробнее здесь — XML.
Вопрос. XPath не находит элемент, хотя он виден в Notepad++.
Ответ. Проверьте namespace — без префикса и xmlns выборка пустая. Используйте local-name() или зарегистрируйте префикс в XPath 2.0. Подробнее здесь — XPath.
Вопрос. Конфиг в репозитории для dev, на prod другие значения — как не путать?
Ответ. Разделите шаблон и секреты: appsettings.json + appsettings.Production.json + переменные окружения; секреты — вне Git. Подробнее здесь — Конфигурационные данные.
Вопрос. JSON с комментариями // — VS Code подсвечивает, CI падает.
Ответ. JSON не поддерживает комментарии; VS Code иногда терпит JSONC. Для человекочитаемых конфигов — YAML; комментарии в JSON — через поле "_comment". Подробнее здесь — JSON.
Вопрос. Скопировал YAML из Word — "невидимые" ошибки.
Ответ. Word подставляет "умные" кавычки и неразрывные пробелы. Редактируйте конфиги в plain-text редакторе, включите отображение whitespace. Подробнее здесь — YAML, Текстовые форматы.
Вопрос. README.md вместо config.yaml — "удобнее править".
Ответ. Markdown — для людей и документации, не для машинного парсинга настроек. Программа ожидает строгую структуру JSON/YAML. Подробнее здесь — Markdown, Конфигурационные данные.
Вопрос. XSLT "ничего не вывел" — шаблон match есть.
Ответ. Проверьте namespace в match, default template (копирует детей), порядок шаблонов и <xsl:output. Тестируйте на одном узле через XPath. Подробнее здесь — XSLT.
Вопрос. .env файл попал в Docker-образ на Docker Hub.
Ответ. Добавьте .env в .dockerignore, передавайте секреты через runtime env или orchestrator secrets. Образ считайте публичным. Подробнее здесь — Конфиги и секреты.
Вопрос. Ansible playbook на Windows с \ в путях ломает YAML.
Ответ. Обратный слэш — escape в YAML; пути Windows лучше в кавычках или с прямыми /. Подробнее здесь — YAML.
Вопрос. XML огромный — DOM съел всю память.
Ответ. DOM загружает всё дерево. Для больших файлов — SAX/StAX потоковый парсинг или XPath на streaming API. Подробнее здесь — XML DOM.
Вопрос. JSON {"id": 001} — id стал 1.
Ответ. В JSON числа без ведущих нулей; 001 — невалидно как число. ID с ведущими нулями храните строкой "001". Подробнее здесь — JSON.
Вопрос. Два разработчика мержат один YAML — silent merge conflict.
Ответ. Git может оставить оба блока без маркеров конфликта в соседних ключах. Ревью diff внимательно; для k8s — kubectl diff. Подробнее здесь — Конфигурационные данные.
Вопрос. XSD валидация OK, но интеграция с партнёром падает.
Ответ. Партнёр может использовать другую версию схемы или optional поля по-другому. Сверьте sample messages, namespace, кодировку пролога UTF-8. Подробнее здесь — XML.
Вопрос. Protobuf "сломался" после добавления поля — старые клиенты падают.
Ответ. Менять номер или тип существующего поля нельзя. Новые поля — новые tag; reserved для удалённых. Подробнее здесь — MessagePack, BSON, Protobuf.
Вопрос. Эмодзи в логе YAML превратились в "квадратики" или знаки вопроса.
Ответ. Кодировка файла или терминала не UTF-8. Сохраните конфиг в UTF-8 без BOM, проверьте locale контейнера. Подробнее здесь — Текстовые форматы, Эмодзи в тексте.
Вопрос. docker-compose.yml version: '3' — предупреждение "obsolete".
Ответ. Новые Compose V2 игнорируют поле version — это не ошибка данных, а смена спецификации. Обновите документацию под актуальный compose spec. Подробнее здесь — YAML.
Вопрос. Конфиг разросся до 2000 строк — никто не знает, что можно удалить.
Ответ. Разбейте на модули, включите defaults в коде, документируйте обязательные ключи, grep по репозиторию на использование. Подробнее здесь — Конфигурационные данные.
Вопрос. JSON из JavaScript undefined сериализовался странно.
Ответ. JSON.stringify пропускает ключи со значением undefined; массивы с undefined → null. Явно задайте null или удалите ключ в контракте API. Подробнее здесь — JSON.
Вопрос. Markdown таблица в GitHub OK, в Docusaurus "плывёт".
Ответ. MDX требует пустую строку вокруг таблицы и экранирование {. Проверьте правила MDX в энциклопедии. Подробнее здесь — Markdown.
Вопрос. Банк требует XML, команда шлёт JSON — "и так работало".
Ответ. Контракт интеграции задаёт формат и XSD — JSON без согласования отклонят. Для гос. и финтеха XML часто обязателен. Подробнее здесь — XML, Конфигурационные данные.
Вопрос. YAML anchor *defaults не подставился — ключи пустые.
Ответ. Alias ссылается на узел, объявленный выше через &; merge key <<: — особый синтаксис. Проверьте отступ alias и поддержку парсера. Подробнее здесь — YAML.
Вопрос. Локально конфиг читается, в Linux-контейнере — FileNotFound.
Ответ. Windows регистр пути не учитывает; Linux — case-sensitive. Путь ./Config/app.json vs ./config/app.json. Подробнее здесь — Конфигурационные данные.
Вопрос. Хочу один формат "на всё" — что выбрать?
Ответ. Универсального нет: JSON для API, YAML для IaC и ручных правок, XML для строгих контрактов, Markdown для docs. Выбор — проектное решение под аудиторию и инструменты. Подробнее здесь — Конфигурационные данные.
Вопрос. Валидатор JSON online говорит OK, а Python json.load падает.
Ответ. Проверьте BOM в начале файла, одинарные кавычки, NaN/Infinity (не в стандарте JSON). Откройте hex первых байт. Подробнее здесь — JSON, Текстовые форматы.
Вопрос. JSON vs YAML — в чём разница и что выбрать?
Ответ. JSON — строгий, без комментариев, стандарт API. YAML — читаем человеком, отступы, комментарии; Kubernetes, Ansible, CI. Подробнее здесь — JSON, YAML, Конфигурационные данные.
Вопрос. Что такое JSON и для чего он используется?
Ответ. Текстовый формат обмена данными: объекты {}, массивы [], строки, числа, bool, null. Основа REST API и конфигов сборки. Подробнее здесь — JSON.
Вопрос. Как проверить JSON на ошибки онлайн или в терминале?
Ответ. jq . file.json, python -m json.tool, IDE с подсветкой, jsonlint.com. Частые ошибки — trailing comma, одинарные кавычки. Подробнее здесь — JSON.
Вопрос. Что такое YAML файл и как его читать?
Ответ. Иерархия через отступы, списки с -, ключ: значение. Без табов — только пробелы. Подробнее здесь — YAML.
Вопрос. XML — для чего используется в 2025 году?
Ответ. Госуслуги, банки, SOAP, конфиги .NET, документооборот со XSD-валидацией. Для новых REST чаще JSON. Подробнее здесь — XML.
Вопрос. Что такое XPath и как выбрать элемент в XML?
Ответ. Язык путей: /catalog/book/title, //item[@id='1']. Используют в тестах, XSLT, парсерах. Подробнее здесь — XPath.
Вопрос. XSLT — что это и зачем преобразовывать XML?
Ответ. Шаблоны для XML → HTML, PDF, другой XML. Legacy интеграции и отчёты. Подробнее здесь — XSLT.
Вопрос. Markdown vs HTML — когда что использовать?
Ответ. Markdown — README, wiki, статьи (Docusaurus). HTML — точная вёрстка. Markdown не заменяет JSON/YAML для настроек. Подробнее здесь — Markdown.
Вопрос. Где хранить пароли и API-ключи в проекте?
Ответ. Не в Git: переменные окружения, Vault, Secrets Manager, .env локально + .gitignore. Подробнее здесь — Конфигурационные данные.
Вопрос. Kubernetes config yaml — с чего начать изучение?
Ответ. Сначала YAML-синтаксис, затем минимальный Pod/Deployment. Отступы критичны. Подробнее здесь — YAML, Конфигурационные данные.
Вопрос. Что такое .env файл?
Ответ. Текстовый список KEY=VALUE для локальной разработки; загружается dotenv-библиотеками. Не коммитить секреты. Подробнее здесь — Конфигурационные данные.
Вопрос. Protobuf vs JSON — когда выбрать бинарный формат?
Ответ. Protobuf компактнее и быстрее при высоком RPS и gRPC; JSON проще отлаживать. Подробнее здесь — MessagePack, BSON, Protobuf.
Вопрос. Что такое JSON Schema?
Ответ. Описание структуры JSON для валидации API-контрактов (типы, required, enum). Аналог XSD для JSON. Подробнее здесь — JSON Schema, OpenAPI и Schema.org.
Вопрос. TOML vs YAML vs JSON для конфигурации?
Ответ. TOML — явные секции, популярен в Rust (Cargo.toml). YAML — k8s/Ansible. JSON — API и автогенерация. Подробнее здесь — TOML, YAML, Конфигурационные данные.
Вопрос. Как конвертировать JSON в YAML и обратно?
Ответ. yq, онлайн-конвертеры, IDE-плагины. Проверяйте типы ("on" в YAML!). Подробнее здесь — JSON, YAML.
Вопрос. Что такое namespace в XML?
Ответ. URI-префикс, чтобы различать одноимённые теги из разных схем (xs:, soap:). Обязателен в сложных интеграциях. Подробнее здесь — XML.
Вопрос. XSD валидация XML — как проверить документ?
Ответ. xmllint --schema, IDE, CI-пipeline. XSD задаёт типы, обязательные элементы, порядок. Подробнее здесь — XML.
Вопрос. Docker Compose yaml example — где учить синтаксис?
Ответ. Сначала базовый YAML (отступы, списки), затем ключи services, ports, volumes. Подробнее здесь — YAML, готовые compose-файлы с разбором — Docker Compose — готовые стеки; образ для build: — Dockerfile — 10 типовых образов.
Вопрос. Что такое конфигурационный файл приложения?
Ответ. Данные, отделяющие поведение от кода: URL БД, feature flags, лимиты. Версионируют в Git без секретов. Подробнее здесь — Конфигурационные данные.
Вопрос. UTF-8 BOM в JSON — почему ломает парсер?
Ответ. BOM (байты EF BB BF) — не часть JSON; некоторые парсеры падают. Сохраняйте UTF-8 без BOM. Подробнее здесь — Текстовые форматы, JSON.
Вопрос. Чем конфиг отличается от данных приложения?
Ответ. Конфиг меняет как работает программа (порты, флаги); предметные данные — заказы, пользователи в БД. Подробнее здесь — Конфигурационные данные.
Вопрос. XML DOM vs SAX — что выбрать для большого файла?
Ответ. SAX/StAX — потоково, мало памяти. DOM — всё дерево в RAM, удобно для XPath на маленьких файлах. Подробнее здесь — XML DOM.
Вопрос. Как оформить README.md для GitHub?
Ответ. Заголовок, описание, установка, пример, лицензия — синтаксис Markdown. Подробнее здесь — Markdown.
Что запомнить
Конфигурационные данные — это полноценный интерфейс между программой и её окружением. Они позволяют отделить поведение от реализации, повысить переносимость, упростить тестирование и обеспечить гибкость развёртывания. Для этого используются структурированные машиночитаемые форматы, каждый из которых решает свою задачу в зависимости от контекста.
XML — формат с максимальной строгостью и самодокументируемостью. Он поддерживает пространства имён, схемы (XSD/DTD), трансформации (XSLT) и адресацию (XPath). Применяется в государственных системах, корпоративных интеграциях, документообороте и промышленных решениях, где важна верифицируемость и долгосрочная совместимость.
JSON — лаконичный, предсказуемый и универсальный. Лишён комментариев и сложных типов, что делает его идеальным для обмена данными между сервисами, конфигурации сборок и API. Его простота обеспечивает надёжность парсинга даже в ресурсоограниченных средах.
YAML — ориентирован на человека. Использует отступы вместо скобок, поддерживает комментарии, алиасы и многострочные строки. Широко применяется в описании инфраструктуры как кода (Kubernetes, Ansible, Docker Compose), CI/CD-конфигурациях и проектах, где конфигурацию часто редактируют вручную. Примеры compose.yaml с разбором — Docker Compose — готовые стеки; типовые Dockerfile — галерея Lab.
Markdown — язык разметки, предназначенный для создания читаемых текстовых документов с минимальным синтаксисом. Не является форматом данных в узком смысле, но служит основой для технической документации, README-файлов, блогов и систем знаний, таких как Docusaurus.
Независимо от выбранного формата, ключевые принципы остаются неизменными:
- Структурированность — данные должны иметь однозначную иерархию.
- Машиночитаемость — любой валидный документ должен парситься без участия ИИ.
- Семантическая ясность — имена ключей, тегов и атрибутов должны отражать назначение.
- Версионируемость — конфигурация — часть системы, и её изменения фиксируются в Git.
- Безопасность — чувствительные данные (пароли, токены) никогда не хранятся в открытом виде в файлах.
Выбор формата — это проектировочное решение, а не техническая деталь. Он определяет, насколько легко будет поддерживать, расширять и интегрировать систему в будущем.
Куда идти дальше
Полный маршрут — на странице о разделе.
Проверьте себя: Чек-лист самопроверки.