TypeScript 生成器

TypeScript 生成器生成与 Java 服务对应的 TypeScript 文件，这些服务使用 @BrowserCallable 或 @Endpoint 注解标记。

功能
生成器架构
示例
- 生成的 TypeScript 端点
附录：如何将 OpenAPI 规范转换为 TypeScript 类
- 模块／类
- 方法

TypeScript 生成器生成与使用 @BrowserCallable 或 @Endpoint 注解标记的 Java 服务对应的TypeScript文件。这些文件保留了 Java类的属性和类型，以便在前端提供类型安全性。

这些被注解的服务通常称为*端点（endpoints）*，尽管在 Hilla 中实际上只有一个 REST 端点，这个端点调用了浏览器可访问的服务。在这种情况下，“端点”一词指的是那些使用注解标记的 Java 服务。

功能

生成器[since:dev.hilla:hilla@v1.2]支持多模块项目。您可以在应用程序中使用标准的 Maven 模块，甚至外部依赖项，因为端点和实体类不需要与 Hilla 应用程序处于同一个项目中。

生成器设计灵活。生成器的所有部分均为可插拔的，这意味着您可以修改默认行为或增添新的功能。

Note	Spring Boot 启用了一个 Java 编译器选项，以在类文件中保留参数名称。如果生成的类缺少参数名，您可能需要在项目中启用该选项。使用 `javac -parameters` 选项以支持多模块项目和所有 JVM 语言。详情请参阅配置。

生成器架构

生成器包含三个部分：

Java 字节码解析器: 解析器读取 Java 字节码并生成 OpenAPI schema。
TypeScript 抽象语法树（AST）生成器: AST 生成器读取 OpenAPI schema 并生成 TypeScript 端点，这些端点可用于后续的前端开发。
运行时控制器: 运行时控制器提供服务端与客户端之间的运行时通信。

Hilla 使用 OpenAPI 规范作为端点与 TypeScript 客户端之间的中间层。实现基于 OpenAPI 规范 3.0。详情请参阅本页末尾附录部分。

示例

生成的 TypeScript 端点

UserEndpoint.ts 类由 UserEndpoint.java 类生成。

Source code

UserEndpoint.ts
/**
 * User endpoint.
 *
 * This module has been generated from UserEndpoint.java
 * @module UserEndpoint
 */
import client from './connect-client.default'; 1

/**
 * Check if a user is admin or not.
 *
 * @param id User id to be checked
 * Return Return true if the given user is an admin, otherwise false.
 */
export async function isAdmin( 2
  id?: number
) {
  return await client.call('UserEndpoint', 'isAdmin', {id});
}
UserEndpoint.java
/**
 * User endpoint.
 */
@Endpoint
public class UserEndpoint {
    /**
     * Check if a user is admin or not.
     *
     * @param id
     *            User id to be checked
     * @return Return true if the given user is an admin, otherwise false.
     */
    public boolean isAdmin(long id) {
        return id == 0;
    }
}

此行是任何生成的 TypeScript 类的固定部分。connect-client.default.ts 为另一个生成的文件，其中包含了 ConnectClient 的默认配置，并导出了名为 client 的实例。
TypeScript 生成类中的每个方法都对应于以 @Endpoint 注解标记的类中的一个 Java 方法。

有关 Java 与 TypeScript 类型映射的更多信息，请参阅类型转换。您还可能想了解一下类型可空性的相关内容。

附录：如何将 OpenAPI 规范转换为 TypeScript 类

模块／类

生成器收集 OpenAPI 文档中所有操作（operations）的所有 tags 字段。每个标签都会生成相应的 TypeScript 文件。标签名既用作 TypeScript 模块／类名，也用作文件名。

方法

模块中每个导出的方法对应于 OpenAPI 文档的 paths 对象内 path 项目对象的 POST 操作。

Note	生成器只支持 `POST` 操作。如果路径项包含除了 `POST` 之外的操作，生成器将停止处理。

路径*必须* 以 / 开头，如 Patterned Fields 所述。它被解析为 /<端点名>/<方法名> 格式，用于调用后端的 Java 端点服务。路径中的方法名也会被重复使用为生成的 TypeScript 文件中的方法名。

方法参数

方法参数来自于请求体对象的 application/json 内容。

若要得到与 UserEndpoint.ts 相应的结果，请求体内容应为：

Source code

请求体
{
 "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number"
          }
        }
      }
    }
  }
}

Note	所有请求体对象中其它类型的内容都会被 Hilla 生成器忽略。这意味着如果方法没有 `application/json` 的内容类型，则被视为无参数方法。

方法返回类型

方法返回类型来自于类型为 200 的响应对象。与请求体对象一样，生成器仅关注 application/json 内容类型。

以下是响应对象的一个示例：

Source code

响应对象
{
  "200": {
    "description": "Return true if the given user is an admin, otherwise false.",
    "content": {
      "application/json": {
        "schema": {
          "type": "boolean"
        }
      }
    }
  }
}

Note	当前，生成器仅识别 `200` 响应对象。其他响应对象均会被忽略。

Source code

Post 操作
{
  "tags": ["UserEndpoint"], 1
  "requestBody": { ...省略相同部分内容以减少篇幅... },
  "responses": { ...省略相同部分内容以减少篇幅... }
}

如 operation 对象中所述，在 Hilla 生成器中，tags 用于将操作分类到 TypeScript 文件中。这意味着每个标签有对应的生成的 TypeScript 文件。含多个标签的操作将出现在所有生成文件中。空标签的操作将放置在 Default.ts 文件中。

Note	尽管多个标签不会破坏生成器，但如果在不同的 TypeScript 文件中存在两个相同方法，可能导致开发时困惑。建议每个操作仅使用一个标签。

Docs

Docs

TypeScript 生成器

功能

生成器架构

示例

生成的 TypeScript 端点

附录：如何将 OpenAPI 规范转换为 TypeScript 类

模块／类

方法

方法参数

方法返回类型