1 简介

Ratpack 是一套 Java 库，用于构建快速、高效、可扩展且经过良好测试的 HTTP 应用程序。它基于高性能、高效的 Netty 事件驱动网络引擎。

Ratpack 纯粹是一个运行时。它没有可安装的包，也没有耦合的构建工具（例如 Rails、Play、Grails）。要构建 Ratpack 应用程序，您可以使用任何 JVM 构建工具。Ratpack 项目通过插件为Gradle提供了特定支持，但任何工具都可以使用。

Ratpack 发布为一组库 JAR 文件。ratpack-core 库是唯一严格要求的库。其他库，如 ratpack-groovy、ratpack-guice、ratpack-jackson、ratpack-test 等，都是可选的。

1.1 目标

Ratpack 的目标是

1. 快速、可扩展且高效
2. 允许应用程序在复杂性方面发展，而不影响性能
3. 利用非阻塞编程的优势，降低成本
4. 在集成其他工具和库方面保持灵活和无偏见
5. 允许应用程序轻松彻底地进行测试

Ratpack 的目标不是

1. 成为一个完全集成的“全栈”解决方案
2. 提供您可能需要的所有功能
3. 为“业务逻辑”提供架构或框架

2.1 关于本手册

Ratpack 的文档分散在本手册和Javadoc API 参考中。手册介绍了高级别的主题和概念，并链接到 Javadoc 以获取详细的 API 信息。大部分信息都包含在 Javadoc 中。一旦您了解了 Ratpack 的核心概念，手册就会变得不那么有用，而 Javadoc 则更加有用。

1.2.1 代码示例

文档中的所有代码示例都经过测试，大多数是完整的程序，您可以复制/粘贴并自行运行（给定正确的类路径等）。

大多数示例都作为小型嵌入式 Ratpack 应用程序给出，在测试中。以下是 Ratpack 代码示例的“Hello World”。

import ratpack.test.embed.EmbeddedApp;
import static org.junit.jupiter.api.Assertions.assertEquals;
 
public class Example {
  public static void main(String... args) throws Exception {
    EmbeddedApp.fromHandler(ctx -> 
      ctx.render("Hello World!")
    ).test(httpClient -> 
      assertEquals("Hello World!", httpClient.getText())
    );
  }
}

为了清晰起见，import 语句默认情况下被折叠。单击它们以显示/隐藏它们。

此示例是一个完整的 Ratpack 应用程序。但是，EmbeddedApp 不是通常用于实际应用程序的入口点（有关典型入口点的详细信息，请参阅启动章节）。EmbeddedApp 是面向测试的。它使在较大应用程序期间轻松启动/停止非常小的（或完整的）应用程序，并提供了一种方便的方式来对应用程序进行 HTTP 请求。它在示例中使用，以将引导过程降至最低，以便专注于正在演示的 API。

在此示例中，我们在一个短暂的端口上启动了一个 Ratpack 服务器，该服务器使用默认配置，对所有 HTTP 请求响应为纯文本字符串“Hello World”。这里使用的test() 方法为给定函数提供了一个TestHttpClient，该函数被配置为向被测服务器发出请求。此示例以及所有类似的示例都向 Ratpack 服务器发出 HTTP 请求。EmbeddedApp 和TestHttpClient 是作为 Ratpack 的测试支持的一部分提供的。

另一个在许多示例中使用的关键测试实用程序是ExecHarness.

import com.google.common.io.Files;
import ratpack.test.exec.ExecHarness;
import ratpack.exec.Blocking;

import java.io.File;
import java.nio.charset.StandardCharsets;

import static org.junit.jupiter.api.Assertions.assertEquals;

public class Example {
  public static void main(String... args) throws Exception {
    File tmpFile = File.createTempFile("ratpack", "test");
    Files.asCharSink(tmpFile, StandardCharsets.UTF_8).write("Hello World!");
    tmpFile.deleteOnExit();

    String content = ExecHarness.yieldSingle(e ->
        Blocking.get(() -> Files.asCharSource(tmpFile, StandardCharsets.UTF_8).read())
    ).getValueOrThrow();

    assertEquals("Hello World!", content);
  }
}

EmbeddedApp 支持创建整个 Ratpack 应用程序，而 ExecHarness 仅提供 Ratpack 执行模型的基础结构。它通常用于单元测试使用 Ratpack 构造（如Promise）的异步代码（有关执行模型的更多信息，请参阅“异步和非阻塞” 章节）。ExecHarness 也是作为 Ratpack 的测试支持的一部分提供的。

1.1.2.1 Java 8 风格

Ratpack 基于 Java 8 构建，并且需要 Java 8。代码示例大量使用了 Java 8 构造，例如 lambda 表达式和方法引用。如果您熟悉 Java，但不熟悉 Java 8 中的新构造，您可能会发现这些示例很“奇特”。