CUBA平台：TypeScript SDK和REST API

在本文中，我们将讨论已存在很长时间但尚未广为人知的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都无法解决另一个问题-如果更改了某些内容，该如何处理生成的客户端代码。直接的一次性代码生成很简单，但是支持却是另一回事。在删除实体的属性后，如何确保前端应用程序不会失败？

因此，为了加速前端开发并简化后端团队与前端团队之间的协作，我们需要：

公开特定于业务的API和通用API
根据后端数据模型和方法签名生成前端代码
以最小的努力和潜在的错误修改生成的代码

我们在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的支持将是您遇到的最小问题。