Краткий ответ

Хранимым свойством экземпляра становится не само прикладное значение, а экземпляр property wrapper, который это значение хранит и управляет доступом к нему. Обращение к объявленному свойству прозрачно перенаправляется к wrappedValue этого wrapper.

Исторический контекст

Property wrappers появились в Swift 5.1, чтобы вынести повторяющуюся логику хранения и проверки значений из самих типов. До этого одинаковое поведение приходилось вручную дублировать в вычисляемых свойствах, инициализаторах и вспомогательных полях.

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

Постановка проблемы

Допустим, свойство должно принимать только положительные значения. Если реализовывать это вручную для каждого свойства, появятся повторяющиеся поля, getter, setter и проверки. Ошибка в одном из таких участков может привести к разному поведению одинаковых по смыслу свойств.

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

Подробное решение

Для свойства с wrapper Swift концептуально создаёт скрытое backing-свойство, обычно обозначаемое подчёркиванием, например _age. Его типом является сам wrapper, а не тип значения Int. Публичное или обычное имя age обращается к wrappedValue wrapper.

@propertyWrapper
struct NonNegative {
    private var value: Int

    init(wrappedValue: Int) {
        value = max(0, wrappedValue)
    }

    var wrappedValue: Int {
        get { value }
        set { value = max(0, newValue) }
    }
}

struct User {
    @NonNegative var age: Int
}

var user = User(age: -2)
print(user.age)
user.age = -5
print(user.age)

В этом примере экземпляр User фактически хранит NonNegative, а user.age читает его wrappedValue. Оба присваивания нормализуются wrapper и дают значение 0.

Инициализатор User(age:) принимает значение для wrappedValue, после чего Swift создаёт wrapper через его инициализатор. Если требуется передать уже созданный wrapper, внутри самого типа можно инициализировать backing-свойство напрямую, но такое имя предназначено для реализации типа и не является обычным публичным API.

Wrapper может предоставлять projectedValue. Тогда через имя с префиксом $ наружу становится доступно дополнительное представление состояния или операции wrapper, например объект валидации или publisher. Это не меняет того, что основное хранимое состояние находится в экземпляре wrapper.

Wrapper не превращает свойство в глобальное или общее для всех экземпляров: каждый экземпляр владельца обычно получает собственный экземпляр wrapper. Для общего состояния нужен другой механизм, например статическое свойство.

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

Ситуация из практики

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

Второй вариант — сделать отдельную функцию нормализации. Это уменьшает дублирование, но не гарантирует, что каждый setter действительно её вызовет.

Выбранный вариант — общий property wrapper с нижней и верхней границей. Он централизует правило, автоматически применяется при инициализации и последующих изменениях и делает контракт модели единообразным. Компромисс заключается в том, что разработчикам нужно знать о скрытом состоянии wrapper и учитывать его при сериализации, инициализации и отладке.

Что кандидаты часто упускают

Вопрос: Может ли property wrapper быть только вычисляемым и не хранить собственное состояние?

Ответ: Да. Wrapper обязан предоставлять wrappedValue, но его реализация может вычислять значение из других источников и не иметь хранимых свойств. Однако если wrapper должен сохранять значение между обращениями, ему требуется собственное состояние или внешний источник хранения.
Вопрос: Чем отличается обращение к свойству от обращения к его projected value через $?

Ответ: Обычное имя свойства обращается к wrappedValue и представляет основное прикладное значение. $имя обращается к projectedValue, если wrapper его предоставляет; это отдельный интерфейс, предназначенный для метаданных, управления или дополнительного поведения. Наличие wrappedValue само по себе не означает наличие projectedValue.
Вопрос: Почему изменение значения свойства с wrapper может быть запрещено, даже если сам wrapper объявлен как изменяемый?

Ответ: Доступность изменения определяется сочетанием доступа к свойству-владельцу и доступности setter у wrappedValue. Если setter закрыт или владелец доступен только для чтения, присваивание запрещено на уровне внешнего API. Wrapper инкапсулирует реализацию, но не отменяет правила доступа Swift и требования к изменяемости экземпляра.