Barber 项目教程

Barber 项目教程

barber Barber 💈 A type safe Kotlin JVM library for building up localized, fillable, themed documents using Mustache templating 项目地址: https://gitcode.com/gh_mirrors/barbe/barber

1. 项目介绍

Barber 是一个类型安全的 Kotlin JVM 库，用于构建本地化的、可填充的、主题化的文档，使用 Mustache 模板引擎。该项目的主要目标是帮助开发者安全地处理用户界面中的文本内容，如 UI 通知、电子邮件等，确保模板和数据在编译时得到验证，避免运行时异常或用户可见的错误。

2. 项目快速启动

2.1 添加依赖

首先，在你的 build.gradle.kts 文件中添加 Barber 的依赖：

implementation("app.cash.barber:barber:2024.01.12-173005-933c241")

2.2 定义 DocumentData

创建一个数据类 DocumentData，用于渲染模板：

data class RecipientReceipt(
    val sender: String,
    val amount: String,
    val cancelUrl: String,
    val deposit_expected_at: Instant
) : DocumentData

2.3 定义 Document

定义最终输出的文档结构：

data class TransactionalSmsDocument(
    val sms_body: String
) : Document

2.4 创建 DocumentTemplate

创建一个 DocumentTemplate，将 DocumentData 与 Document 连接起来：

val recipientReceiptSmsDocumentTemplateEN_US = DocumentTemplate(
    fields = mapOf(
        "sms_body" to "[[sender]] sent you [[amount]]"
    ),
    source = RecipientReceipt::class,
    targets = setOf(TransactionalSmsDocument::class),
    locale = Locale.EN_US
)

2.5 构建 Barbershop

使用 BarbershopBuilder 构建一个 Barbershop：

val barbershop = BarbershopBuilder()
    .installDocumentTemplate<RecipientReceipt>(recipientReceiptSmsDocumentTemplateEN_US)
    .installDocument<TransactionalSmsDocument>()
    .build()

2.6 渲染文档

获取 Barber 并渲染最终的文档：

val recipientReceiptSms = barbershop.getBarber<RecipientReceipt, TransactionalSmsDocument>()

val sandy50Receipt = RecipientReceipt(
    sender = "Sandy",
    amount = "50",
    cancelUrl = "https://example.com/cancel",
    deposit_expected_at = Instant.now()
)

val renderedDocument = recipientReceiptSms.render(sandy50Receipt, Locale.EN_US)
println(renderedDocument.sms_body)

3. 应用案例和最佳实践

3.1 多语言支持

Barber 支持多语言模板，可以通过不同的 Locale 来渲染不同语言的文档。例如，你可以为不同的语言创建不同的 DocumentTemplate，并在渲染时选择合适的 Locale。

3.2 复杂文档处理

对于复杂的文档，如包含多个字段的电子邮件，Barber 允许你定义多个字段，并在 DocumentTemplate 中为每个字段指定模板。这样可以确保每个字段都能正确渲染。

3.3 编译时验证

Barber 的一个重要特性是编译时验证。通过定义 DocumentData 和 DocumentTemplate，Barber 可以在编译时检查模板和数据是否匹配，避免运行时错误。

4. 典型生态项目

4.1 Kotlin Mustache

Kotlin Mustache 是一个 Kotlin 实现的 Mustache 模板引擎，与 Barber 结合使用可以提供强大的模板渲染能力。

4.2 Kotlinx.serialization

Kotlinx.serialization 是一个 Kotlin 序列化库，可以与 Barber 结合使用，将渲染后的文档序列化为 JSON 或其他格式，便于存储和传输。

4.3 Ktor

Ktor 是一个 Kotlin 的 Web 框架，可以与 Barber 结合使用，构建基于模板的 Web 应用，提供动态内容生成能力。

通过这些生态项目的结合，Barber 可以更好地满足复杂应用场景的需求。

barber Barber 💈 A type safe Kotlin JVM library for building up localized, fillable, themed documents using Mustache templating 项目地址: https://gitcode.com/gh_mirrors/barbe/barber