create-tier

新增 Tier 指南

核心原则

1. 新增 tier 优先在业务侧组合，不要为了一个新 tier 回改框架核心。
2. admin、client、public 是预置别名，不是唯一扩展入口。
3. 只有在“所有 tier 都共享的新能力”出现时，才允许修改核心文件。

当前可复用的扩展原语：

• 类型原语：BaseJwtPayload、JwtBindings、RouteHandlerWithBindings、OpenAPIWithBindings
• 运行时原语：createTierRouter、createTierFactory、defineMiddleware

默认不要修改这些核心文件：

• src/types/lib.d.ts
• src/lib/core/create-app.ts
• src/lib/core/factory.ts

先做判断

场景	是否 JWT	推荐 bindings	备注
公开 tier	否	PublicBindings 或 BaseBindings	没有 jwtPayload
认证 tier，仅需 sub	是	JwtBindings 或 ClientBindings	默认只带 sub
认证 tier，有额外 claims	是	JwtBindings<CustomJwtPayload>	例如 partnerId、tenantId
带角色的 tier	是	JwtBindings<CustomPayload & { roles: string[] }>	不要默认复用 admin 语义

如果只是“另一个业务端”，通常不需要把它加进全局核心类型，只需要在该 tier 目录下定义本地 alias。

推荐文件布局

src/routes/{tier}/
├── _middleware.ts
├── {tier}.types.ts
├── {tier}.factory.ts
└── {feature}/
    ├── {feature}.index.ts
    ├── {feature}.routes.ts
    ├── {feature}.handlers.ts
    ├── {feature}.types.ts
    └── __tests__/

约定：

• {tier}.types.ts 只放 tier 级 payload / bindings / route handler alias
• {tier}.factory.ts 只放 tier 级 router / middleware / handlers alias
• 业务模块继续放在 src/routes/{tier}/{feature}/ 或 src/routes/{tier}/{category}/{feature}/

标准步骤

1. 在 app.config.ts 注册 tier

先补文档入口和路由装配配置：

// app.config.ts
{
  name: "partner",
  title: "合作方 API 文档",
  token: "your-partner-token",
}

可选字段：

• basePath: 自定义路径前缀
• routeDir: 当目录名和 tier 名不同
• middlewares: 显式传入中间件，跳过 src/routes/{tier}/_middleware.ts

2. 如果是 JWT tier，先补环境变量

在 src/env.ts 增加对应 secret，例如：

PARTNER_JWT_SECRET: z.string().min(32, "JWT密钥长度至少32字符,建议使用强随机字符串"),

同时同步 .env / .env.test 的实际值。

3. 定义 tier 本地类型别名

优先在 src/routes/{tier}/{tier}.types.ts 定义，而不是回到 src/types/lib.d.ts 增加一个全局业务类型。

认证 tier 示例：

// src/routes/partner/partner.types.ts
import type { RouteConfig as HonoRouteConfig } from "@hono/zod-openapi";
import type {
  BaseJwtPayload,
  JwtBindings,
  RouteHandlerWithBindings,
} from "@/types/lib";

export type PartnerJwtPayload = BaseJwtPayload & {
  partnerId: string;
};

export type PartnerBindings = JwtBindings<PartnerJwtPayload>;
export type PartnerRouteHandler<R extends HonoRouteConfig>
  = RouteHandlerWithBindings<R, PartnerBindings>;