Node 开发者熟悉 Java 的建议

结合本项目 · global-flight-distribution（Next.js / TypeScript BFF）

一句话结论：本项目本体是 Node/TS，Java 重在读，不在写。守住类型边界 connectors/types.ts + 转换层 shared/*normalizer，不需要深学 Java 语法。

Java 只出现在两个地方

① HSF 调用

src/server/api/connectors/

调用 Java 后端服务。你写 TS，但对方的类型、方法名、返回值全是 Java 来的。

② 旧 Java 后端

global-flight-distributors

只作为确认业务口径的参考代码来读。严禁调用（AGENTS.md 硬性边界）。

所以几乎不用「写 Java」，主要工作是读 Java → 把类型和业务口径写到 TS 这边。

Node / TS	Java（HSF / 旧后端）	在本项目里的含义
import 的 npm 函数	HSF service 的 method	`connectors/types.ts` 每个 method 对应一个 Java 方法
REST endpoint + JSON	HSF（接口全限定名 + 版本做 RPC）	service id = `接口FQN:版本`，见 `connectors.ts`
`interface { }`	Java DTO / POJO	Java 一串 `getXxx()` = TS 的一个字段
`null` / `undefined`	Java `null`（`Integer` vs `int`）	包装类型（Integer/Long）会来 null，基本类型（int/long）不会
`number`	`int` / `long` / `BigDecimal`	long 在 JS 会丢精度，金额 / ID 一律用字符串
字符串 `enum`	Java `enum`（序号或 name）	用 `enums.ts` 锁口径；Java 给的是数字还是 name 先确认
try / catch	Java 异常 + 返回的 `ResultDO`	错误常常是返回值里的状态字段，不是抛异常
Promise	Java 同步方法	HSF 本身同步，TS 这边包成 Promise

一个类 = 一个 TS interface，getter = 字段。
private Long orderId; getOrderId() → 读成 orderId: string（long 用 string）。
包名 = 文件路径。
com.fliggy.global.flight.distributors.client.xxx 只是旧后端位置，不是新系统可调 provider。
找 ResultDO<T> 模式。
Java 后端用「成功/失败 + data」一个对象返回 → 这是本项目 result.ts / errors.ts 的来源。
确认业务口径的标准流程：
读旧 Java service 实现 → 抄到新 connector 转换层 connectors/shared/*-normalizer.ts。

route.ts薄层 dispatch→ service业务编排→ connectorrequest-builder→ HSFJava 后端(同步)→ normalizerJava 响应→TS→ ResultDO统一返回

你写代码主要在两端：request-builder（TS → Java 入参）和 normalizer（Java 出参 → TS）。中间的 Java 实现只读不碰。

long 丢精度 —— 订单 ID / 金额用 number 接会坏。在边界 mapper 里转 string。
Java Long 最大值 ≈ 9.2×10¹⁸，JS Number.MAX_SAFE_INTEGER ≈ 9×10¹⁵，差了 1000 倍。订单号一般 16~18 位，必出问题。
别凭习惯猜 HSF 元信息 —— 方法名 / 参数 / 返回类型用 mw hsf 查原文（docs/hsf-query-guide.md），不要按 Java 习惯「应该是这样」去填。
别以为旧后端能调 —— com.fliggy.global.flight.distributors.client.* 只是参考，不是可调 provider。
null 安全 —— Java 包装类型字段随时可能 null。TS 这边的 optional / 默认值收敛到 coercion.ts。

src/server/api/connectors/types.ts

看清和 Java 的边界（最稳定的一层）

docs/hsf-query-guide.md

学怎么查 Java 服务的元信息

connectors/shared/order-normalizer.ts 等

看 Java 响应 → TS 的真实转换例子

业务口径有疑问时，搜旧 Java 来读

只读不改不调