知識庫 / REST RSS 訂閱

7. 模塊類

如前所述，RESTX 使用 J2EE 標準的依賴注入註解，例如 @Named，並在需要時自行創建，很可能受到了 Dagger 框架中 @Module 和 @Provides 的啓發。

它利用這些註解來創建應用程序的主模塊，該模塊中定義了管理員密碼等。

@Module
public class AppModule {
    
    @Provides
    public SignatureKey signatureKey() {
        return new SignatureKey("restx-demo -44749418370 restx-demo 801f-4116-48f2-906b"
            .getBytes(Charsets.UTF_8));
    }

    @Provides
    @Named("restx.admin.password")
    public String restxAdminPassword() {
        return "1234";
    }

    @Provides
    public ConfigSupplier appConfigSupplier(ConfigLoader configLoader) {
        return configLoader.fromResource("restx/demo/settings");
    } 
   
    // other provider methods to create components 
}

@Module 定義了一個可以定義其他組件的類，類似於 Dagger 中的 @Module 或 Spring 中的 @Configuration。

@Provides 允許程序性地暴露組件，就像 Dagger 中的 @Provides 或 Spring 中的 @Bean。

此外，@Named 註解用於指示所產生的組件的名稱。

AppModule 也提供了一個 SignatureKey，用於對客户端發送的內容進行簽名。在為示例應用程序創建會話時，例如，它將使用配置的密鑰對 cookie 進行簽名：

HTTP/1.1 200 OK
...
Set-Cookie: RestxSessionSignature-restx-demo="ySfv8FejvizMMvruGlK3K2hwdb8="; RestxSession-restx-demo="..."
...

查閲 RESTX 的組件工廠/依賴注入文檔 以獲取更多信息。

8. Launcher 類

最後，AppServer 類用於在嵌入式 Jetty 服務器上以標準 Java 應用的形式運行應用程序：

public class AppServer {
    public static final String WEB_INF_LOCATION = "src/main/webapp/WEB-INF/web.xml";
    public static final String WEB_APP_LOCATION = "src/main/webapp";

    public static void main(String[] args) throws Exception {
        int port = Integer.valueOf(Optional.fromNullable(System.getenv("PORT")).or("8080"));
        WebServer server = 
            new Jetty8WebServer(WEB_INF_LOCATION, WEB_APP_LOCATION, port, "0.0.0.0");
        System.setProperty("restx.mode", System.getProperty("restx.mode", "dev"));
        System.setProperty("restx.app.package", "restx.demo");
        server.startAndAwait();
    }
}

在此，開發模式在開發階段用於啓用諸如自動編譯等功能，從而縮短開發反饋循環。

我們可以將應用程序打包為 WAR文件（Web存檔）以在獨立 J2EE Web 容器中部署。

在下一部分中，我們將瞭解如何測試該應用程序。

9. 使用規範進行集成測試

RESTX 的強大功能之一是其“規範”的概念。一個示例 規範 如下所示：

title: should admin say hello
given:
  - time: 2013-08-28T01:18:00.822+02:00
wts:
  - when: |
      GET hello?who=xavier
    then: |
      {"message":"hello xavier, it's 01:18:00"}

測試採用 Given-When-Then 結構，並在一個 YAML 文件中定義，該文件基本上描述了 API 應該如何響應（then）針對特定請求（when）在當前系統狀態下（given）。

位於 src/test/resources 目錄中的 HelloResourceSpecTest 類將觸發上述規範中的測試。

@RunWith(RestxSpecTestsRunner.class)
@FindSpecsIn("specs/hello")
public class HelloResourceSpecTest {}

RestxSpecTestsRunner 類是一個自定義的 JUnit 運行器。它包含自定義的 JUnit 規則，用於：

• 設置嵌入式服務器
• 準備系統狀態（根據規範中的given 部分）
• 發出指定的請求，以及
• 驗證預期的響應

@FindSpecsIn 註解指向用於運行測試的規範文件路徑。

規範有助於編寫集成測試並提供 API 文檔中的示例。規範還對模擬 HTTP 請求和記錄請求/響應對有幫助。

10. 手動測試

我們還可以通過 HTTP 進行手動測試。首先，我們需要登錄。為此，需要在 RESTX 控制枱中對管理員密碼進行哈希處理：

hash md5 <clear-text-password>

然後我們可以將它傳遞到 sessions</em/> 端點：

curl -b u1 -c u1 -X POST -H "Content-Type: application/json" 
  -d '{"principal":{"name":"admin","passwordHash":"1d528266b85cf052803a57288"}}'
  http://localhost:8080/api/sessions

(注意：Windows 用户需要先下載 curl)

現在，如果我們使用 session 作為我們的 /message 請求的一部分：

curl -b u1 "http://localhost:8080/api/message?who=restx"

然後我們會得到類似這樣的結果：

{"message" : "hello admin, it's 09:56:51"}

11. 探索管理控制枱

管理控制枱提供有用的資源，用於控制應用程序。

請瀏覽以下地址以查看關鍵功能：http://127.0.0.1:8080/admin/@/ui

11.1. API 文檔

API 文檔部分列出了所有可用的路由，包括所有選項：

我們還可以點擊單個路由並嘗試在控制枱中執行：

11.2. 監控

《JVM 指標》部分顯示了具有活動會話、內存使用情況和線程轉儲的應用程序指標：

在《應用程序指標》下，我們默認監控了兩種主要類別：

• BUILD 對應於應用程序組件的實例化
• HTTP 對應於 RESTX 處理的 HTTP 請求

11.3. 統計數據

RESTX 允許用户選擇收集和分享應用程序的匿名統計數據，以便向 RESTX 社區提供信息。 我們可以輕鬆地通過排除 restx-stats-admin 模塊來取消收集統計數據。

統計數據報告包括底層操作系統和 JVM 版本：

由於此頁面顯示敏感信息，請務必 查看其配置選項 。

除了這些之外，管理控制枱還可以幫助我們：

• 查看服務器日誌（Logs）
• 查看遇到的錯誤（Errors）
• 檢查環境變量（Config）

12. 授權

RESTX 端點默認已啓用安全保護。這意味着對於任何端點：

@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}

當不進行身份驗證時，將默認返回一個 401  錯誤。

為了使某個端點公開，我們需要在方法或類級別使用 @PermitAll 註解：

@PermitAll 
@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}

請注意，在類級別上，所有方法都是公開的。

此外，框架還允許使用@RolesAllowed註解指定用户角色：

@RolesAllowed("admin")
@GET("/greetings/{who}")
public Message sayHello(String who) {
    return new Message(who);
}

通過此註解，RESTX 將驗證已認證的用户是否也擁有 admin 角色。如果未擁有 admin 角色且已認證的用户嘗試訪問該端點，應用程序將返回 403 而不是 401。

默認情況下，用户角色和憑據存儲在文件系統中，通過單獨的文件進行管理。

因此，包含加密密碼的用户 ID 存儲在 /data/credentials.json 文件下：

{
    "user1": "$2a$10$iZluUbCseDOvKnoe",
    "user2": "$2a$10$oym3Swr7pScdiCXu"
}

並且，用户角色定義在 /data/users.json 文件中：

[
    {"name":"user1", "roles": ["hello"]},
    {"name":"user2", "roles": []}
]

在示例應用中，文件通過 AppModule 並在 FileBasedUserRepository 類中加載：

new FileBasedUserRepository<>(StdUser.class, mapper, 
  new StdUser("admin", ImmutableSet.<String> of("*")), 
  Paths.get("data/users.json"), Paths.get("data/credentials.json"), true)

StdUser 類用於存儲用户對象。它可以是自定義的用户類，但必須可序列化為 JSON。

當然，我們也可以使用不同的 UserRepository 實現，例如一個連接數據庫的實現。

13. 結論

本教程概述了基於 Java 的輕量級 RESTX 框架。

該框架仍在開發中，使用時可能存在一些不完善之處。請訪問 官方文檔 以獲取更多詳細信息。