Hono框架中JSON类型推断的注意事项

在Hono框架开发过程中，开发者可能会遇到一个关于JSON类型推断的特殊情况。当API接口返回any | undefined类型时，RPC客户端会将其推断为never类型，这可能会让一些开发者感到困惑。

问题现象

假设我们有一个简单的Hono路由，随机返回一个数字或undefined：

export const route = new Hono().get("/even", async (c) => {
  const num = Math.floor(Math.random() * 100);
  const res = num % 2 === 0 ? num : undefined;
  return c.json(res);
});

当使用Hono客户端调用这个API时：

const api = hc<typeof route>("/");
const budget = await (await api.even.$get()).json();

开发者可能期望budget的类型是number | undefined，但实际上TypeScript会将其推断为never类型。

技术原理

这种现象并非Hono框架的bug，而是与JSON规范直接相关。在标准的JSON规范中，undefined并不是一个有效的值。当尝试将undefined序列化为JSON时，会产生一个空字符串，而空字符串无法被正确解析为JSON。

Hono框架在类型定义中严格遵循了这一规范：

export type JSONPrimitive = string | boolean | number | null

可以看到，undefined确实不在允许的类型之列。这种设计确保了类型系统能够准确反映运行时行为。

解决方案

对于需要表示可选值的场景，开发者有以下几种处理方式：

1. 使用null代替undefined： 这是最符合JSON规范的解决方案，也是推荐的做法。

const res = num % 2 === 0 ? num : null;

2. 自定义类型扩展（不推荐）： 虽然可以扩展JSONPrimitive类型包含undefined，但这会违反JSON规范，可能导致运行时问题。

3. 使用类型断言： 在明确知道数据来源的情况下，可以使用类型断言，但这会降低类型安全性。

const budget = await (await api.even.$get()).json() as number | undefined;

最佳实践

在Hono框架开发中，处理可选返回值时应当：

1. 优先使用null而非undefined表示空值
2. 保持类型系统与运行时行为的一致性
3. 避免使用any类型，明确指定返回类型
4. 在客户端处理响应时，考虑添加适当的类型守卫

理解这些类型系统的设计决策，有助于开发者编写出更加健壮和类型安全的Hono应用代码。