TypeScript SDK 和 REST API

      在本文中,我们将讨论CUBA平台中已经存在很长时间的一个功能,但是很多人还不知道,这就是前端SDK生成器,并了解它如何与CUBA的REST API插件一起使用。

Java+JavaScript - 在 web 中喜结连理

      仅仅只是大概八年之前,我们 Java 开发者将 JavaScript(JS) 作为“二等公民”语言用在 Web 应用程序中。那时,用 JS 的目的只是为了在网页中加入一些动效,网页也是使用 JSF、Struts、Tapestry 或 Thymeleaf 等框架在服务器端生成的。如今,我们见证了 JS  作为使用React、Vue 或 Angular 等框架进行客户端开发的第一语言,甚至连 Node.js 也出现在了服务端。

      实际应用中,我们开发的 Web 应用程序可能在不同的层上使用不同的语言:JS 用于客户端UI,Java 用于业务逻辑处理,SQL 用于从数据库中获取数据,Python 用于数据分析,等等。然后再使用各种技术将所有这些语言组合到一个应用程序中。最常见的例子就是 REST API,基于平台无关的 HTTP 协议简单的 JSON 格式,现在已经成为连接客户端 JS 服务器端 Java 的默认方法。

      但是,即使是最好的裁缝也不能无缝缝制衣裳。 定义 API 始终存在一个问题:要调用的方法是哪个,数据模型是什么,还有比如说我们应该将街道地址作为结构化对象还是作为字符串传递?

      我们如何才能帮助我们的 JavaScript 同事更快地创建代码还能避免沟通的不畅?

Swagger 会是终极答案吗?

      也许你要说“Swagger”,没错。 Swagger 实际上已经是设计、构建、记录和使用 REST API 的工业标准。也有许多代码生成器可帮助生成用于不同语言的客户端 SDK

      CUBA 框架就支持 Swagger,每个带有 REST API 扩展组件的应用程序都有一个 API 端点可以用来下载 .json 或 .yaml 格式的 Swagger 文档。您可以使用这些文件来生成 JS 客户端。

      但是事实上,Swagger 只是一个 API 文档工具。那么前端开发人员希望在 API 中看到什么样的信息呢? “经典”的做法是:将业务功能映射为服务,并构建一套定义规范的 API。再将这套 API 公开为一组 REST 服务,最后添加 Swagger 文档,差不多就可以了。

      如果真的是这样的话,为什么 GraphQL 会快速崛起并在前端开发人员中引起轰动呢? 我们注意到,GraphQL 的份额一直在不断增长。到底是怎么回事?事实证明,遇到经常会变动的用例,提供更“通用”的 API 对前端人员来说更加合适,因为可以避免创建很多小的 API。比如,对于 Web UI 中的购物车情景,一个物品的价格只需要第一次调用时获取,之后对于该物品只需要知道总数即可。另外,GraphQL 可以避免过度获取数据或者数据获取不足,还能一次调用多个 API 获得复杂的返回数据结构。

      这样的话,似乎应用程序不止应该开放服务的 API,还应该提供一些通用 API。这种方式使得前端开发人员可以调用复杂的业务功能,但是也为他们提供一定程度的灵活性。因此,如果他们只是需要针对不同 UI 获取数据的不同展现形式,他们不会要求提供新的 API。

      还有一个问题是 Swagger 或 GraphQL 或 OData 都无法解决的,那就是如果更改了某些内容,针对之前已经生成的客户端代码,如何做适配呢?直接一次性生成代码很容易,但是能支持业务的变化却是另外一回事了。比如,我们删除了实体的一个属性,怎么保证前端应用程序不会出问题?

      所以,综合来看,为了加速前端开发并简化后端团队与前端团队之间的协作,我们需要:

         1.定义特定业务的 API 和通用 API

         2.根据后端数据模型和方法签名来生成前端代码

         3.如需修改生成的代码,需要保证花费最小的人力并且尽量避免 bug

      我们在 CUBA 的 REST API 扩展组件和前端 SDK 生成器中也面临着相同的所有挑战。

CUBA TypeScript SDK

      在CUBA中,REST API 扩展组件提供以下功能:

         | 数据模型实体的 CRUD 操作

         | 执行预定义的 JPQL 查询

         | 执行服务方法

         | 获取元数据(实体,视图,枚举,数据类型)

         | 获取当前用户权限(访问实体、属性以及特定权限)

         | 获取当前的用户信息(名称,语言,时区等)

         | 处理文件

      功能上说,我们提供了从任何前端客户端访问应用程序的所有功能。这些 API 都通过进行说明,对于前端开发来说,可以使用这些文档立即进行开发。

      为 REST API 用户设置安全规则也很重要,需要防止 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

内容版权声明:除非注明,否则皆为本站原创文章。

转载注明出处:https://www.heiqu.com/zzgpjx.html