JSON Лучшие практики

JSON, несомненно, является гибким способом обмена данными между системами. Но это не значит, что JSON можно создать любым способом.

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

Вложите в ДВОЙНЫЕ цитаты

Всегда заключайте пару Ключ: Значение в двойные кавычки. Может быть удобно (не знаю, как) генерировать с использованием одинарных кавычек, но парсер JSON не любит анализировать JSON. объекты в одинарных кавычках.

Для числовых значений кавычки необязательны, но рекомендуется заключать их в двойные кавычки.

{'id': '1','name':File} is not right ✘
{"id": 1,"name":"File"} is okay  ✓
{"id": "1","name":"File"} is the best  ✓

Пожалуйста, без дефисов

Никогда Никогда Никогда не используйте дефисы в ключевых полях. Он нарушает работу синтаксического анализатора Python и Scala, и разработчикам приходится его избегать, чтобы использовать эти поля.

Вместо дефисов используйте символы подчеркивания (_). Но лучше всего использовать более низкий или верблюжий футляр. См. Примеры ниже.

{"first-name":"Rachel","last-name":"Green"}  is not right. ✘
{"first_name":"Rachel","last_name":"Green"} is okay ✓
{"firstname":"Rachel","lastname":"Green"} is okay ✓
{"firstName":"Rachel","lastName":"Green"} is the best. ✓

Всегда создавайте корневой элемент.

Создание корневого элемента необязательно, но это помогает при генерации сложного JSON.

JSON with root element
{
"menu": [
    {
        "id": "1",
        "name":"File",
        "value": "F",
        "popup": {
            "menuitem": [
                {"name":"New", "value": "1N", "onclick": "newDoc()"},
                {"name":"Open", "value": "1O", "onclick": "openDoc()"},
                {"name":"Close", "value": "1C", "onclick": "closeDoc()"}
                ]
            }
    },
    {
        "id": "2",
        "name":"Edit",
        "value": "E",
        "popup": {
            "menuitem": [
                {"name":"Undo", "value": "2U", "onclick": "undo()"},
                {"name":"Copy", "value": "2C", "onclick": "copy()"},
                {"name":"Cut", "value": "2T", "onclick": "cut()"}
                ]
            }
    }
    ]
}
JSON without root element
[
    {
        "id": "1",
        "name":"File",
        "value": "F",
        "popup": {
            "menuitem": [
                {"name":"New", "value": "1N", "onclick": "newDoc()"},
                {"name":"Open", "value": "1O", "onclick": "openDoc()"},
                {"name":"Close", "value": "1C", "onclick": "closeDoc()"}
                ]
            }
    },
    {
        "id": "2",
        "name":"Edit",
        "value": "E",
        "popup": {
            "menuitem": [
                {"name":"Undo", "value": "2U", "onclick": "undo()"},
                {"name":"Copy", "value": "2C", "onclick": "copy()"},
                {"name":"Cut", "value": "2T", "onclick": "cut()"}
                ]
            }
    
    
    }
]

Предоставьте образец META

Идея JSON заключается в гибкости, поэтому вам не нужно ограничивать поток данных несколькими столбцами.

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

{
"menu": [
    {
        "id": "1",
        "name":"File",
        "value": "F",
        "popup": {
            "menuitem": [
                {"name":"New", "value": "1N", "onclick": "newDoc()"},
                {"name":"Open", "value": "1O", "onclick": "openDoc()"},
                {"name":"Close", "value": "1C", "onclick": "closeDoc()"}
                ]
            }
    },
    {
        "id": "2",
        "name":"Edit",
        "value": "E",
        "popup": {
            "menuitem": [
                {"name":"Undo", "value": "2U", "onclick": "undo()"},
                {"name":"Copy", "value": "2C", "onclick": "copy()"},
                {"name":"Cut", "value": "2T", "onclick": "cut()"}
                ]
            }
    }
    ]
}

Мета-образец может быть

menu.id: integer - уникальный идентификатор
menu.name: string - имя меню
menu.value: string - внутренний идентификатор меню
menu.popup.menuitem.name: string - название подменю
menu.popup.menuitem.value: string - промежуточный идентификатор подменю
menu.popup.menuitem.onclick: string - клиентское событие подменю

Проверка вывода JSON

Использование инструментов командной строки, таких как ajv-cli / jsonlint (может быть установлено через любой менеджер пакетов), устранит проблемы для потребителей.

Похожие статьи