4.1.1. Логика указания входных параметров методов API
Варианты указания входного параметра метода
Обязательность указания | Требуется значение (NOT NULL) | Цвет | Логика | |
|---|---|---|---|---|
Необязательный к указанию с возможностью пустого значения | При операции изменения (EDIT, UPDATE) означает, что поле необязательно изменять при потребности изменения объекта. Поле объекта допускает пустое значение. Часто применяется программистом для изменения объекта с целью сброса значения поля. Дело в том, что пустое значение у ряда полей в системе 1С-Коннект напрямую влияет на поведение системы. Например:
При операции чтения данных (READ, LIST) означает, что логикой системы предусмотрено одно из двух:
| |||
Необязательный к указанию, но с запретом пустого значения | При операции добавления/создания (ADD, INSERT) - основной вариант для полей объекта, необязательных к заполнению. При операции изменения (EDIT, UPDATE) - основной вариант для полей объекта, обязательных к заполнению. То есть, решил изменить объект - можешь не менять это поле (в нём тогда будет предыдущее значение); если уж решил изменить значение поля - укажи новое значение. При операции чтения данных (READ, LIST) - основной вариант для возможных параметров фильтрации результата. Хочешь фильтровать по параметру - укажи его, обязательно указав значение. | |||
Обязательный к указанию, но с возможностью указать пустое значения | не применяется. | |||
Обязательный к указанию, с запретом пустого значения | При операции чтения данных (READ, LIST) - применяется для запроса обязательных параметров фильтра. При операции добавления/создания (ADD, INSERT) - основной вариант для полей объекта, обязательных к заполнению. При операции изменения (EDIT, UPDATE) - применяется редко, только для запроса параметров, напрямую связанных с транзакцией или фиксацией состояния объекта. |
Логика восприятия входных параметров системой
При операции изменения (EDIT, UPDATE) система ожидает, что, если параметр указан - то значение соответствующего поля в объекте данных нужно изменить на указанное.
То есть, если в объекте с 5 полями нужно изменить значение только 2-х - то программисту следует указать только 2 из 5 входных параметров, предназначенных для указания значений этих полей.
При этом, если значение указанного параметра не указано (пустое значение) - система и устанавливает в поле объекта пустое значение. То есть, если бизнес-логикой поле объекта не предусматривает пустое значение, то в соответствующем входном параметре метода API будет запрет на пустое значение указываемого параметра.
При операции добавления/создания (ADD, INSERT) система требует указания значений обязательных к заполнению полей, поэтому вариант R_N не допустим. Не указать входным параметром не обязательное поле объекта - равноценно указанию параметра, но с пустым значением, поэтому вариант NR_N не практикуется. Если параметр не обязателен к указанию (вариант NR_NN) - может означать 2 сценария:
поле объекта в принципе необязательно к заполнению (аналогично пониманию NULL в реляционных СУБД).
поле самого объекта обязательно к заполнению, но если программист не указал соответствующий параметр - система при создании объекта данных, записывает в это поле значение по умолчанию.
При операции чтения данных (READ, LIST) система ожидает, что если входной параметр указан - значит, необходимо производить отбор списка записей/объектов по данному параметру. Как правило, количество параметров (по сути, фильтра), требуемых к указанию для метода, минимально. Указание нескольких параметров отбора равноценно логике предикатов "AND" (∩), т.е. приводит к отбору одновременно по всем этим значениям. Вследствие этого, вариант R_D бессмысленный, и не практикуется.