Advanced Property Wrapper in Swift

老司机技术周报与字节音乐联合主办了今年的 T 沙龙上海专场。本次沙龙邀请了 4 位国内嘉宾，特邀了 2 位国外嘉宾。黄智杰 受邀为大家分享【Advanced Property Wrapper in Swift】，杨宇歆基于这次分享视频为大家整理此文，辛苦二位！阅读原文，领取 PPT。

讲师简介：黄智杰，小特科技-移动组高级开发工程师

编辑简介：杨宇歆，字节跳动音乐团队工程师

什么是 Property Wrapper

首先来看一个很简单的例子，有一个叫 User 的 Struct ，里面有 username、objectId、mobilePhone、email 和 address 字段。

struct User {
 let username: String
 let objectld: String
 let mobilePhone: String
 let email: String
 let address: String
}

如果我们现在需要把 User 信息写到本地文件，又或者需要把相关的一些日志上传到我们的服务器进行诊断做日志分析的话，就可能会泄漏 mobilePhone 、email、address 等个人信息。有没有比较好的办法对 User 里面某些字段进行脱敏呢？

第一种方法是使用一个 Protocol，这里我们定义了一个叫 SensitiveStringData 的 Protocol，然后里边有一个 getter 是 rawValue。在扩展里对 debugdescription、custommirror（如果你使用 Reflection 的话）进行默认实现，通过重写 getter 返回 *** 来隐藏敏感信息。接着让 Phone、Address 等类型实现 SensitiveStringData 协议。

 Protocol SensitiveStringData: CustomDebugStringConvertible, CustomLeafReflectable {
 var rawalue: String { get }
 }

 extension SensitiveStringData {
 // CustomDebugStringConvertible
 var debugdescription: String return "***"

 // CustomLeafReflectable
 var custommirror: Mirror { return Mirror (reflecting: "***") }
 }

 struct Email: Sensitivestringdata {
 var raValue: String
 init (string: String) {
 rawValue = string
 }
 }

 struct Phone: SensitiveStringData {...} 
 struct Address: SensitiveStringData {...}

这种方法存在一些问题，你必须要定义诸如 Phone、Address 等 struct 去替换原有的 String 类型，这样就需要对现有代码做大量调整，并且这些类型都需要遵循 SensitiveStringData 协议。而在取值时，也需要通过 rawValue 的方式来访问，这非常不优雅。

第二种方法是用一个泛型结构，你可以把 rawValue 放在里边，这种方法比 Protocol 要好一点，你不用每一个单独的类型都声明一个新类型，只要使用 SensitiveData 包裹就可以了。

struct SensitiveData Value  {
 var value: Value

 init (value: Value) {
 self.value = value
 }
}

struct User {
 let username: String
 let objectld: String
 let mobilePhone: SensitiveData String 
 let email: SensitiveData String 
 let address: SensitiveData String 
}

第三种方法也是最常见的方法，用一个 Property Observer 进行 internal 属性 _email 的封装。通过 getter 返回 email 的值，通过 setter 把 newValue 塞到 internal _email 里面。

 struct User {
 let username: String
 let objectld: String
 let mobilePhone: Phone
 let address: Address
 var email: String {
 get { return _email.value }
 set { _email.value = newValue }
 }
 private var _email: SensitiveData String 

 init (username: String, email: String, ...) {
 self.username = username
 self._email = SensitiveData String (email)
 ...
 }
 }

你会发现，Property Observer 的确是一种简单粗暴的方法，但是依然要做很多重复的工作，比如需要单独为每一个 property 定义一个 private 变量，跟别提重复地复制拷贝来实现 getter 和 setter。

有没有一种更优雅的方法？

Property Wrapper。

这里我们对 sensitive struct 声明 Property Wrapper。除了在 struct 前面声明 @propertywrapper 外，还要实现它的 wrappedValue，现在，我们可以把前面一些 private property 相关的操作放在里面。这个部分是可以被其他 property 复用的，之后在 extension 中实现 debugdescription 的 getter，Done。

@propertywrapper
struct Sensitive {
 private var value: String
 var wrappedValue: String {
 get {
 return "***"
 }
 set {
 self.value = newValue
 }
 }
 init (wrappedValue: String) {
 self.value = wrappedvalue
 }
} 

extension Sensitive: CustomDebugStringConvertible {
 var debugdescription: String { return wrappedValue }
}

struct User {
 let username: String
 let objectld: String
 @Sensitive var mobilePhone: String
 @Sensitive var email: String
 @Sensitive var address: String
}

首先，@Sensitive 修饰的变量并不是一个新的类型，它们仍然是 String，这意味着我们不需要对现有的代码进行修改，现有的代码可以正常运行。其次，我们只需在任何脱敏的属性前来标记 @Sensitive，减少了太多重复的代码。除此之外，我们能直接访问 User 对象的属性，不需要间接通过 rawValue 来访问 internal 的值。

Property Wrapper的历史

接着聊聊 Property Wrapper 的历史。经常用 SwiftUI 的同学可能会比较熟悉这种 @ 开头的修饰，Property Wrapper 最早并不叫这个名字，而是叫做 Property Behavior，它来自于 Swift 最早期提案 SE-0030。如果看过 Apple Swift 源码的早期版本的话，可以发现里面有较多的 NSCopying 以及 lazy 等重复性的代码。核心团队为了解决这类重复代码问题就提出了 Property Behavior。可以看到这个提案的 State 是 deferred，可能当时核心团队还没有想好如何把这样一个能力做成一个Public 的 API 来对开发者开放。后来社区中有许多人发现这个能力还是很有必要的，可以解决项目中重复代码的问题，提升简洁度和可读性。于是有了 SE-0258 提案，并把提案中 Property Behavior 改名为 Property Wrapper。

Property Wrapper 的应用

如果你经常写 SwiftUI 或者用过 WidgetKit 的话，应该看过 @Environment 这个 property wrapper，@Environment 可以判断 Widget Family，判断 Widget 在桌面的尺寸大小， 其实这就是一个 Property Wrapper。

聊到 SwiftUI，我们也经常见到 struct XXX：View，有没有思考过这里为什么是一个 Struct 而不是 Class 呢？

个人的理解是结构体比类更简单，更轻量，其次在 SwiftUI 中，所有的 View 都是一个独立的视图，所见即所有，继承 UIView 中 200 多个 property 会成为一个很大的包袱。除了性能，用 struct 表示 view 还有其他重要原因：它强迫我们以一种更干净的方式隔离状态。通过在 Struct 使用 @state 和 @binding，我们实现状态隔离的目的。

struct PlayerView: View {
 var episode: Episode
 @state private var isPlaying: Bool = false

 var body: some View {
 VStack {
 Text(episode.title)
 Text(episode.showTitle)
 PlayButton(isPlaying: $isPlaying)
 }
 }
}

State 中还有一个 projectedValue, 它和 wrappedValue 不太一样, wrappedValue 是需要指定类型的，而 projectedValue 可以是任意类型。访问 projectedValue 时需要通过 $ 符号来访问。

struct User {}
struct Example {
 @State var user = User()
 func debug() {
 print(_user)
 print(user)
 print($user)
 }
}
Example().debug()

第一个 _user，类型是 state，因为我们在这个 user 前面加了一个 Property Wrapper。第二个就是一个正常的 User 类型。第三个 $ 开头的，其实访问的是 User 里面的 projectedValue，它是一个 Binding 类型。user、user.wrappedValue 两者是等价的，都是 User 类型。$user 和 user.projectedValue 也是等价的，都是 Binding 类型。之前的讲师有提到过，Property Wrapper 可以用来限制值的范围。比如说这样一个例子：

struct Example {
 struct RGBColor {
 @Clamping(0...255)
 var red: Double
 @Clamping(0...255)
 var green: Double
 @Clamping(0...255)
 var blue: Double
 }
 @Rounded(digits: 2) var number: Double = 3.14159
 @Trimmed var userName: String
 @Expirable(duration: 3600)
 var token: String?
 @DanamicColor(light: .white, dark: .black)
 var backgroundColor: UIColor
}

这里通过一个 Clamping 的 Property Wrapper 来限制了值的范围在 0-255 之间。这个相当于 kotlin 里的 annotation，它可以修饰一个变量，让它更符合预期。通过添加 Rounded 的 Property Wrapper，就可以限制范围值为 2 位小数。还有诸如对字符串做 trimmed 操作，设置 token 60 分钟内过期，设置深浅模式不同的背景色等。Property Wrapper 能做到的事情有很多。

下面是一个 Expirable 的例子，通过定义一个 Property Wrapper 来限制过期时间。利用 protecdValue，将一些需要的 API 封装在 Expirable 结构中，通过 $ 方式来访问这些API。

@propertyWrapper
struct Expirable Value  {
 var projectedValue: Expirable {
 self
 }

 var wrappedValue: Value? {
 get {
 return isValid ? storage?.value : nil
 }

 set {
 storage = newValue.map { ($0, Date().addingTimeInterval(duration))}
 }
 }

 init(duration: TimeInterval) {
 self.duration = duration
 }

 let duration: TimeInterval
 private var storage: (value: Value, expirationDate: Date)?
 var isValid: Bool {
 guard let storage = storage else {
 return false
 }
 return storage.expirationDate  = Date()
 }
}

@Expirable(duration: 3600) var apiToken: String?

接下来是一个和 Codable 结合的例子，通常我们从服务器拿到一个 JSON 数据后再序列化成对应的数据结构。那么在解析日期的时候，它可能年月日格式，也可能是 ISO8601 的日期格式，我们可以定义了一个 DateValue 的 Property Wrapper，把 encode 和 decode 的过程封装到 Formatter，让它更加优雅直观，通过 DateValueCodableStrategy protocol，你也可以自定义自己需要的 Strategy。

protocol DateValueCodableStrategy {
 associatedtype RawValue: Codable
 static func decode(_ value: RawValue) throws -  Date
 static func encode(_ date: Date) -  RawValue
}

@propertyWrapper
struct DateValue Formatter: DateValueCodableStrategy : Codable {
 private let value: Fomatter.RawValue
 var wrappedValue: Date

 init(wrappedValue: Date) {
 self.wrappedValue = wrappedValue
 self.value = Formatter.encode(wrappedValue)
 }

 init(from decoder: Decoder) throws {
 self.value = try Fomatter.RawValue(from: decoder)
 self.wrappedValue = try Formatter.decode(value)
 }

 func encode(to encoder: Encoder) throws {
 try value.encode(to: encoder)
 }
}

Property Wrapper 的限制

下面讨论一下 Property Wrapper的限制。

不可以抛出 error。假如如果你用 Property Wrapper 来进行读写文件操作，这个过程中发生了异常， error 是无法抛出的，你只能返回一个有错误标识意义的默认值。

Property Wrapper in Swift 5.5 Swift 5.5 中新增加 Extend Property Wrappers to Function and Closure parameters 的特性。

这意味着你可以把 Property Wrapper 放在一个 function 的参数之前，每次你调用这个方法，duration 都会被打印出来，非常方便！

@propertyWrapper
struct Logged Value  {
 init(wrappedValue: Value) {
 print(wrappedValue)
 self.wrappedValue = wrappedValue
 }

 var wrappedValue: Value {
 didSet {
 print(wrappedValue)
 }
 }
}

func runAnimation(@Logged withDuration duration: Double) { ... }

通过 Property Wrapper 重构我们现有的代码，让代码更加优雅简洁和 readable。但同时也需要注意不要滥用，因为滥用可能会使 Debug 过程更加困难，因为每使用一次就相当于新增了一层 Wrapper Layer。

前几天在Swift Forum 上看到 Property Wrapper 在编译器的层面上的实现细节，感兴趣的同学可以继续深入了解。从 Swift 代码到 SIL：Parse 负责构建 AST，Sema 负责对 AST 做类型检查 type-checking，并添加 annotation 信息，最后 SILGen 负责对上述的 AST 生成 raw 的 SIL。

其中 Sema 中有个 swift::buildPropertyWrapperInitCall 的方法，里面描述了 property wrapper 的分别对 wrappedValue 和 projectedValue initializers 方法的实现。顺着这个方法，我们可以一窥 property wrapper 的结构，比如 wrappedValue 的 initializers 可以隐式地接受多个 arguments, 又比如 property wrapper 嵌套 property wrapper 的实现。Enjoy！

附本文相关资源出处：

[1]

SE-0258: https://github.com/apple/swift-evolution/blob/master/proposals/0258-property-wrappers.md

[2]

SE-0293: https://github.com/apple/swift-evolution/blob/main/proposals/0293-extend-property-wrappers-to-function-and-closure-parameters.md

本文分享自微信公众号 老司机技术周报（LSJCoding）。
如有侵权，请联系 support@oschina.cn 删除。
本文参与“OSC源创计划”，欢迎正在阅读的你也加入，一起分享。