Skip to content

empty_fields_client_server_guide.md

Latest commit

 

History

History
174 lines (118 loc) · 24 KB

empty_fields_client_server_guide.md

File metadata and controls

174 lines (118 loc) · 24 KB

Проектирование API: Интерпретация пустых значений

В мире веб-разработки, эффективное и точное общение между клиентом и сервером через API является критически важным. Однако, одним из наиболее запутанных и недооцененных аспектов этого взаимодействия является обработка и интерпретация пустых значений.

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

В следующих разделах мы сосредоточимся на JSON формате для примеров обмена данными в API, и анализе пустых значений в его контексте. Хотя примеры ориентированы на JSON, обсуждаемые принципы универсальны и могут быть адаптированы к различным форматам

Разновидности пустых значений в JSON

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

  1. Строка (string): Пустая строка представляется как "". Это означает, что строка активно включена в структуру данных, но не содержит текстового содержимого.

  2. Число (number): Хотя числовые данные обычно не имеют "пустого" представления, иногда используется 0 или другое специфическое значение для указания на отсутствие или недействительность числовых данных.

  3. Объект (object): Пустой объект в JSON обозначается как {}. Это указывает на наличие объектной структуры, но без каких-либо вложенных пар ключ-значение.

  4. Массив (array): Пустой массив обозначается как [], что означает наличие массива, но отсутствие в нем элементов.

  5. Логический тип (boolean): Логический тип данных обычно не имеет прямого пустого значения, но false может использоваться в некоторых контекстах для указания на отсутствие положительного условия.

Кроме того, в JSON существуют специальные обозначения для представления отсутствия значения:

  • null: Этот термин используется для явного указания что значение поля не установлено.

  • Отсутствие поля (no field): В случаях, когда поле полностью отсутствует в структуре данных, это состояние можно описать как no field. Это означает, что поле не было включено в данные.

Понимание этих различий помогает в проектировании более точных и предсказуемых структур данных в API, а также в обработке и интерпретации этих данных при обмене между клиентом и сервером.

Сравнительная таблица пустых значений

Значение Описание в JSON Пример Когда использовать
null Явно указывает на отсутствие значения. "age": null Когда поле существует, но его значение неизвестно или не применимо.
no field Поле отсутствует или не упоминается. (отсутствует) Когда информация о поле не требуется или не запрашивается.
"" (для строк) Пустая строка. "name": "" Когда поле существует, но не содержит данных.
[] (для массивов) Пустой массив. "tags": [] Когда поле существует и предназначено для данных, но данные отсутствуют.
{} (для объектов) Пустой объект. "meta": {} Аналогично пустому массиву, но для объектов.

boolean и number не включены в таблицу по причине отсутствия однозначного пустого представления

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

Распространённые ошибки

Две распространённые ошибки в интерпретации пустых значений в API - это:

  1. Неправильное понимание различия между null и no field.
  2. Смешение пустых значений конкретного типа с универсальными (null и no field)

Далее мы рассмотрим каждую из этих проблем, чтобы избежать распространённых недоразумений при работе с JSON в API.

Когда использовать null, а когда no field

В контексте общения с API, особенно при работе с JSON, различие между null и no field имеет фундаментальное значение. Эти два значения представляют разные состояния и должны использоваться соответственно.

Использование null и no field в ответах API

Когда речь идет о ответах от сервера к клиенту, null используется для явного указания на то, что запрашиваемое поле существует, но его значение не установлено или оно отсутствует. Например, если пользовательский профиль имеет поле дата рождения, но эта информация не предоставлена, сервер может вернуть "дата рождения": null. Это говорит клиенту, что поле признано и обработано сервером, но конкретное значение отсутствует.

no field же в ответах API возникает в ситуации, когда клиент не запрашивал конкретное поле. Это означает, что поле либо не включено в ответ сервера, либо его присутствие неопределенно. Например, если API поддерживает выборочный запрос полей (такой как GraphQL), и клиент не запрашивает поле дата рождения, то это поле в ответе будет отсутствовать или будет no field. Таким образом, no field указывает на отсутствие данных не потому, что они не установлены, а потому, что они не были запрошены клиентом.

Различие между null и no field при отправке данных на сервер

При отправке данных с клиента на сервер, null и no field имеют различные смысловые нагрузки:

  • Отправка null: Это явное указание на то, что значение поля должно быть сброшено или очищено. Например, если пользователь обновляет свой профиль и устанавливает значение дата рождения как null, это сообщает серверу о необходимости удалить или обнулить эту информацию в базе данных.

  • Отправка no field: В этом случае клиент не предоставляет информацию о конкретном поле. При создании новой сущности, это может означать, что поле будет установлено на значение по умолчанию, определенное на стороне сервера. При обновлении сущности, опущение поля или передача no field обычно означает, что текущее значение поля не изменяется.

Важно, чтобы логика обработки no field и опущенных полей была четко определена и документирована в API, особенно в случаях, когда значения по умолчанию или существующие значения влияют на состояние и поведение приложения. Это обеспечивает ясность и согласованность данных в обработке, как при создании, так и при обновлении сущностей.

Примеры использования

Давайте рассмотрим некоторые примеры, чтобы проиллюстрировать эти различия:

  1. Ответ сервера: Пользователь запрашивает свой профиль, но не указал свой адрес электронной почты. Сервер возвращает: "email": null.
  2. Ответ сервера: Пользователь запрашивает свой профиль, но не запрашивает свой адрес электронной почты. Сервер возвращает: "email": no field.
  3. Отправка данных на сервер: Пользователь обновляет свой профиль, удаляя свой номер телефона. Клиент отправляет: "телефон": null.
  4. Отправка данных на сервер: Пользователь обновляет свой профиль, но не затрагивает поле дата рождения. Клиент не отправляет поле дата рождения ( тождественно "дата рождения": no field ).
  5. Отправка данных на сервер: Пользователь создает свой профиль, не указывает статус учетной записи, сервер может автоматически установить его как "активный" или "неактивный" в зависимости от своей внутренней логики.

Правильное использование null и no field способствует более предсказуемому и надежному общению между клиентом и сервером, что в свою очередь обеспечивает стабильность и эффективность работы веб-приложений.

Когда использовать null, а когда пустые значения конкретного типа

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

Использование пустых значений конкретного типа

Пустые значения, специфичные для типа данных (например, пустая строка "", пустой массив [], или объект {}), используются для обозначения, что поле было рассмотрено, но оно не содержит данных. В отличие от null, такие значения указывают, что поле активно и включено в структуру данных, но не имеет содержимого. Это может быть важно, например, в ситуациях, когда нужно отличить, было ли поле просто не заполнено от того, что оно не применяется или не существует.

Использование null

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

Примеры

Для лучшего понимания, как использовать null и пустые значения в различных сценариях работы с API, давайте рассмотрим пример сущности в JSON формате и соответствующие запросы. Это поможет проиллюстрировать, когда и какие значения следует использовать в зависимости от бизнес-логики.

Пример Сущности: Пользовательский Профиль Для примера возьмем сущность профиля пользователя (User), которая описывается следующим образом в JSON Schema:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "about": { "type": "string" },
    "email": { "type": ["string", "null"] },
    "address": {
      "type": ["object", "null"],
      "properties": {
        "city": { "type": "string" },
        "street": { "type": "string" },
        "building": { "type": "string" }
      },
      "required": ["city", "street", "building"]
    },
    "hobby": {
      "type": "array",
      "items": { "type": "string" }
    },
    "active": { "type": "boolean" },
    "payments": {
      "type": ["array", "null"],
      "items": { "type": "string" }
    }
  },
  "required": ["id", "name", "about", "email", "address", "hobby", "active", "payments"]
}

Сценарии использования null и пустых значений (no field):

Проектирование API с учетом пустых значений требует тщательного подхода, особенно когда речь идет о бизнес-логике. Рассмотрим пример сущности User, определенной в JSON Schema, и разберем, как и почему могут возникать пустые значения в разных полях с учетом бизнес-сценариев.

  1. Поле name: Это ключевое поле, которое не может быть null или пустой строкой "".
    По бизнес-логике, каждый пользователь должен иметь имя. Если это поле отсутствует или пустое, это указывает на неполные или некорректные данные пользователя. Поэтому единственно доступный тип у него string

  2. Поле about: Это поле описывает информацию о пользователе и может быть как null, так и пустой строкой "". Однако, для сокращения сложности и унификации данных, лучше выбрать одно представление отсутствия информации.
    В данном случае, "" более предпочтительно, так как оно помогает уменьшить неоднозначность и упрощает обработку данных. В обратном случае у нас не закреплено на уровне типов, использование null или "" для пустого значения (а неоднозначность ведет к ошибкам) Поэтому единственно доступный тип у него string

  3. Поле email: В соответствии с условиями валидности электронной почты, это поле не может быть пустой строкой "", так как это будет не соответствовать формату валидного email-адреса. Таким образом, если адрес электронной почты не предоставлен, поле email должно быть null.
    Это указывает на явное отсутствие информации об электронной почте пользователя. Важно различать ситуацию, когда пользователь не предоставил email (поле null), и когда email предоставлен, но невалиден (например, не соответствует формату email). Поэтому доступные типы у него string и null

  4. Поле address: Если пользователь не указал свой адрес, то поле address будет null. Это отличается от случая, когда адрес был предоставлен, но конкретные подполя (например, city или street) не заполнены (""), что могло бы указывать на неполные данные о адресе. Поэтому доступные типы у него object и null

  5. Поле hobby: Пустой массив [] в этом поле говорит о том, что пользователь не указал свои увлечения. Это отличается от null, которое могло бы означать, что информация о хобби не применима или не учитывается в контексте данного пользователя. Поэтому единственно доступный тип у него array

  6. Поле payments: Это поле имеет особую логику. Для неактивных пользователей ("active": false) поле payments будет null, так как по бизнес-логике неактивные пользователи не могут иметь истории платежей. В то время как у активных пользователей ("active": true) это поле будет представлять собой пустой массив [], если платежи отсутствуют, что отражает факт активности пользователя и потенциальную возможность иметь историю платежей. Поэтому в отличии от hobby доступные типы у него array или null

Каждое из этих полей и их потенциальные пустые значения имеют особое значение, основанное на бизнес-логике. Отсутствие значения (null) и его явное пустое представление (например, пустой массив [] или пустая строка "") отражают разные состояния данных и должны интерпретироваться с учетом контекста приложения и пользовательского опыта. Важно, чтобы такие различия были четко документированы и последовательно применялись при разработке API, чтобы обеспечить предсказуемость и надежность системы.

Резюме по применению null и пустых значений (no field):

  • Используйте null для явного указания на отсутствие значения или когда поле должно быть сброшено.
  • Используйте пустые значения конкретного типа ("", [], {}), когда поле активно, но не содержит данных.
  • Важно четко определить и документировать, как API интерпретирует и обрабатывает null и no field, чтобы обеспечить согласованное и предсказуемое поведение.

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