cuba 平台_CUBA平台：TypeScript SDK和REST API

cuba 平台

在本文中，我們将讨論已存在很長時間但尚未廣為人知的CUBA平台的功能- 前端SDK生成器 ，并了解它如何與CUBA的REST API插件一起使用 。

Java + JavaScript –網絡婚姻

僅八年前，我們Java開發人員在我們的Web應用程式中使用JavaScript作為“第二等公民”語言。 那時，它的目的是通過JSF，Struts，Tapestry或Thymeleaf等架構向伺服器端生成的網頁添加一些動态。 如今，我們見證了JavaScript的出現，它是使用React，Vue或Angular等架構進行用戶端開發的第一語言，而Node.js甚至可以将其引入伺服器端。

實際上，我們開發的Web應用程式可能在不同的層上使用不同的語言：JavaScript用于用戶端UI，Java用于業務邏輯處理，SQL用于從資料庫中擷取資料，Python用于資料分析，等等。使用各種技術将所有這些語言組合到一個應用程式中。 最常見的示例– REST API。 基于與平台無關的HTTP協定和簡單的JSON格式，現在它是拼接用戶端JS和伺服器端Java的預設方法。

但是即使是最好的針腳也不能無縫。 API定義始終存在一個問題：要調用的方法，資料模型是什麼以及我們應該将街道位址作為結構化對象還是作為字元串傳遞。

我們如何才能幫助我們JavaScript研究員更快地建立代碼并避免溝通不暢？

Swagger是最終答案嗎？

你說“ 招搖 ”，對。 Swagger實際上是用于設計，建構，記錄和使用REST API的工業标準。 有許多代碼生成器可幫助生成用于不同語言的用戶端SDK。

CUBA Framework支援Swagger，每個帶有REST API插件的應用程式都有一個端點，該端點允許下載下傳.json或.yaml格式的Swagger文檔。 您可以使用這些檔案來生成JS用戶端。

請考慮以下事實：Swagger隻是一個API文檔工具。 但是，前端開發人員希望在API中看到什麼樣的資訊？ “經典”方法是：将業務功能映射到服務并建構定義良好的API。 然後将其公開為一組REST服務，添加Swagger文檔并享受。

那麼，為什麼GraphQL趕上趨勢，在前端開發人員中引起轟動？ 并注意GraphQL在Web API世界中的份額正在增長。 到底是怎麼回事？ 事實證明，有時為前端開發人員提供更多“通用” API會更容易，進而避免為可能經常更改的用例建立很多小型API。 例如，在Web UI中，對于您的購物籃，您隻需要先訂購價格，然後再訂購總額的訂單，依此類推。GraphQL還是一個​​很好的工具，可以避免過度擷取和擷取不足，以及一次查詢多個API以獲得一個複雜的資料結構。

好的，看起來應用程式不僅應該公開服務，還應該公開一些通用API。 這種方法允許前端開發人員調用複雜的業務功能，并為他們提供一定程度的靈活性，是以，如果他們隻需要UI的不同資料表示形式，則他們不會請求更改API。

Swagger或GraphQL或OData都無法解決另一個問題-如果更改了某些内容，該如何處理生成的用戶端代碼。 直接的一次性代碼生成很簡單，但是支援卻是另一回事。 在删除實體的屬性後，如何確定前端應用程式不會失敗？

是以，為了加速前端開發并簡化後端團隊和前端團隊之間的協作，我們需要：

1. 公開特定于業務的API和通用API
2. 根據後端資料模型和方法簽名生成前端代碼
3. 以最小的努力和潛在的錯誤修改生成的代碼

我們在REST中使用REST API附加元件和前端SDK生成器來面對所有這些挑戰。

CUBA TypeScript SDK

在CUBA中，REST API附加元件提供以下功能：

• 資料模型上的CRUD操作
• 執行預定義的JPQL查詢
• 執行服務方法
• 擷取中繼資料（實體，視圖，枚舉，資料類型）
• 擷取目前使用者權限（通路實體，屬性，特定權限）
• 擷取目前的使用者資訊（名稱，語言，時區等）
• 處理檔案

是以，我們擁有從任何前端用戶端使用該應用程式所需的一切。 所有這些API都在不拘一格的YAML或JSON檔案中進行了描述，是以您可以立即開始實施該應用程式。

為REST API使用者設定安全規則對于防止意外的端點暴露給所有使用者非常重要。 首先，拒絕所有使用者的正常REST API通路，然後為需要通路所需功能的角色建立特殊權限。

但是CUBA不僅提供REST API。 您可以生成一個SDK ， 該SDK可以用作任何前端開發架構的基礎：React，Angular，Vue或其他。

使用生成器，您可以建立一組TypeScript類，該類允許您從用戶端應用程式調用CUBA API。

要生成SDK，您隻需運作

npm install -g @cuba -platform/front-generator 
           

然後

gen-cuba-front sdk:all 
           

所有課程将為您建立。 您甚至可以基于ReactJS生成一個簡單的UI，是以您的客戶将能夠立即開始使用基于CUBA的應用程式。 使用者界面非常基本，但是使用CUBA，您将立即獲得所有功能，包括身份驗證，基于角色的資料通路，實體圖檢索等。

讓我們仔細看一下SDK的功能。

資料模型

應用程式資料模型表示為TypeScript類的集合。 如果我們看一下QuickStart中使用的Session Planner應用程式，則那裡有一個實體：

@NamePattern ( "%s %s|firstName,lastName" )  @Table (name = "SESSIONPLANNER_SPEAKER" )  @Entity (name = "sessionplanner_Speaker" )  public class Speaker extends StandardEntity { 
    @NotNull 
    @Column (name = "FIRST_NAME" , nullable = false ) 
    protected String firstName; 
    @Column (name = "LAST_NAME" ) 
    protected String lastName; 
    @Email 
    @NotNull 
    @Column (name = "EMAIL" , nullable = false , unique = true ) 
    protected String email;  //Setters and getters here  } 
           

在SDK中，我們将獲得一個類：

export class Speaker extends StandardEntity { 
    static NAME = "sessionplanner_Speaker" ; 
    firstName?: string | null ; 
    lastName?: string | null ; 
    email?: string | null ;  } 
           

所有關聯群組成都将被保留，是以您将能夠擷取實體圖，而不必使用多個API調用一一擷取實體。

不再需要DTO-您将獲得與後端所述完全相同的資料。

商業服務

通過CUBA中的REST公開的所有服務将在SDK中具有TypeScript表示形式。 例如，如果我們使用REST API公開會話服務 ，您将獲得一個如下所示的TypeScript代碼：

export var restServices = { 
    sessionplanner_SessionService: { 
        rescheduleSession: (cubaApp: CubaApp, fetchOpts?: FetchOptions) => (params: sessionplanner_SessionService_rescheduleSession_params) => { 
            return cubaApp.invokeService( "sessionplanner_SessionService" , "rescheduleSession" , params, fetchOpts); 
        } 
    }  }; 
           

是以，您隻需編寫以下行就可以從UI調用它：

restServices.sessionplanner_SessionService.rescheduleSession(cubaREST)({session, newStartDate}).then( (result) => { 
    //Result handling  }); 
           

友善，不是嗎？ 所有正常工作都為您完成。

通用API

如果僅需要為前端實作自定義邏輯，則始終可以使用在核心CUBA平台REST庫中定義的一組功能，例如：

loadEntities<T>(entityName: string, options?: EntitiesLoadOptions, fetchOptions?: FetchOptions): Promise<Array<SerializedEntity<T>>>;  deleteEntity(entityName: string, id: any, fetchOptions?: FetchOptions): Promise< void >; 
           

這些功能使您可以使用應用程式中的實體對CRUD操作進行細粒度的通路。 安全性仍然存在，CUBA在伺服器端驗證所有非匿名調用，并防止擷取不符合使用者角色的實體或屬性。

cubaREST.loadEntities<Speaker>(Speaker.NAME).then( (result => { 
  //Result handling  })); 
           

使用此通用API，開發人員可以使用在通用CRUD上建立的自定義API層建立JS應用程式，并将其部署到實作“ 後端前端 ”架構模式的node.js伺服器。 而且，用這種方法可能實作了多個API層，我們可以為不同的用戶端實作一組不同的API：ReactJS，Native iOS等。實際上，生成的SDK是此用例的理想工具。

通用API的不好之處在于，當您擷取的屬性超出了所需的屬性或者API描述符中的屬性不足時，可能會導緻資料擷取不足或擷取過多的風險。 CUBA的實體視圖在後端解決了這個問題，我們為前端開發人員提供了相同的選擇！ 對于每個生成的TypeScript類，我們建立反映視圖的類型：

export type SpeakerViewName = "_minimal" | "_local" | "_base" ;  export type SpeakerView<V extends SpeakerViewName> =  V extends "_minimal" ? Pick<Speaker, ? Pick<Speaker, "id" | "firstName" | "lastName" > :  V extends "_local" ? Pick<Speaker, ? Pick<Speaker, "id" | "firstName" | "lastName" | "email" > :  V extends "_base" ? Pick<Speaker, ? Pick<Speaker, "id" | "firstName" | "lastName" | "email" > :  never; 
           

是以，您可以從後端擷取實體，并且隻會擷取指定的屬性。 是以，您無需猜測提取了哪些屬性。 IDE将幫助您自動完成代碼。

API更新

如前所述，代碼生成甚至不占開發工作的一半。 更改和支援代碼是大多數工作要做的地方。 CUBA的TypeScript SDK生成器在後續運作期間分析代碼，跟蹤更改并以增量方式對其進行更新。 如果您将TypeScript用作前端的主要開發語言，TypeScript編譯器将確定您不會忘記更新使用SDK的自定義代碼。

結論

除了通用UI之外，如果您還想為CUBA應用程式開發基于JS的用戶端UI（React / React Native或Angular或Vue），則可以使用REST API插件和TypeScript SDK。 無論您決定使用哪種技術，都可以專注于設計或性能以提供最佳的使用者體驗，而不必執行正常的編碼任務。 而且，您可以确定JS到Java的通信以及對不斷變化的API的支援将是您遇到的最小問題。

翻譯自: https://www.javacodegeeks.com/2019/11/cuba-platform-typescript-sdk-and-rest-api.html

cuba 平台