可调试性

为有状态的类型提供 toString 方法

对每个包含状态的类型, 要提供一个有意义的 toString 实现. 这个实现应该对实例的当前内容, 返回一个易于理解的表达, 即使是对内部类型也是如此.

由于类型的 toString 表达经常会被写入日志, 在实现这个方法时应该考虑安全性, 不要返回敏感的使用者数据.

对你的库中的不同类型, 要确保用来描述状态的格式尽可能的保持一致. 如果这个格式是你的 API 实现的合同(contract)的一部分, 那么它应该明确的描述, 并留下全面的文档. 你的 toString 方法产生的输出可能支持解析, 例如在自动化的测试组中.

enum class SubscriptionResultReason {
    Success, InsufficientFunds, IncompatibleAccount
}

class SubscriptionResult(
    val result: Boolean,
    val reason: SubscriptionResultReason,
    val description: String
)

如果没有 toString 方法, 打印输出一个 SubscriptionResult 实例不会有什么用处:

fun main() {
    val result = SubscriptionResult(
       false,
       IncompatibleAccount,
       "Users account does not support this type of subscription"
    )

    // 输出结果为 'org.example.SubscriptionResult@13221655'
    println(result)
}

添加一个简单的 toString 实现, 对这两种情况可以显著的改善输出:

// 输出结果为 'Subscription failed (reason=IncompatibleAccount, description="Users
// account does not support this type of subscription")'
override fun toString(): String {
    val resultText = if(result) "succeeded" else "failed"
    return "Subscription $resultText (reason=$reason, description=\"$description\")"
}

尽管使用数据类来自动得到 toString 方法可能很有吸引力, 但由于向后兼容性的原因, 不推荐这样做. 关于数据类, 在不要在你的 API 中使用数据类小节中详细讨论.

注意, toString 方法中描述的状态不需要是问题域中的信息. 它可以是正在进行的请求的状态(如上面的示例所示), 与外部服务的连接的健康状况, 或者正在进行的操作的中间状态.

class Person(
    val name: String?,
    val age: Int?,
    val children: List<Person>
) {
    override fun toString(): String =
        "Person(name=$name, age=$age, children=$children)"
}

class PersonBuilder {
    var name: String? = null
    var age: Int? = null
    val children = arrayListOf<Person>()

    fun child(personBuilder: PersonBuilder.() -> Unit = {}) {
       children.add(person(personBuilder))
    }

    fun build(): Person = Person(name, age, children)
}

fun person(personBuilder: PersonBuilder.() -> Unit = {}): Person =
    PersonBuilder().apply(personBuilder).build()

添加一个简单的 toString 实现, 可以产生更加有用的输出:

override fun toString(): String =
    "PersonBuilder(name=$name, age=$age, children=$children)"

采用一种异常处理方案, 并编写文档

异常的类型应该表明错误类型, 异常中的数据应该帮助使用者确定问题的根本原因. 一种常用的模式是, 将低层的异常封装到库专有的异常中, 通过 cause 可以访问原来的异常.

可调试性﻿

为有状态的类型提供 toString 方法﻿

采用一种异常处理方案, 并编写文档﻿

下一步﻿

为有状态的类型提供 toString 方法

采用一种异常处理方案, 并编写文档

下一步