ts-rest框架中路由前缀与子契约继承问题的深度解析

引言

在构建现代API服务时，合理的路由组织和类型安全是开发者关注的重点。ts-rest作为一个强类型的REST API框架，提供了契约式开发模式，但在实际使用中，开发者可能会遇到路由前缀继承和子契约类型传递的问题。

核心问题分析

当使用ts-rest框架构建嵌套路由结构时，开发者期望父契约中设置的pathPrefix能够自动传递给子契约，但实际情况是类型系统会报错。这源于ts-rest设计上的一个重要特性：契约选项不会自动向下传递到子契约中。

技术实现原理

ts-rest的类型系统要求每个契约必须独立声明其选项，包括pathPrefix和strictStatusCodes等。这种设计确保了类型安全，但也带来了额外的开发负担。具体表现在：

1. 路径前缀不继承：父契约的pathPrefix不会自动应用到子契约的路由路径上
2. 严格状态码需重复声明：每个子契约都需要单独设置strictStatusCodes选项
3. 类型系统严格校验：运行时路径与类型声明路径必须完全匹配

最佳实践方案

基于框架维护者的建议，推荐以下组织代码的方式：

契约层组织

// 基础契约模块
export const authContract = initContract().router(
  {
    login: { /* 路由定义 */ }
  },
  {
    strictStatusCodes: true,
    pathPrefix: "/auth"
  }
);

// 聚合契约
export const apiContract = initContract().router(
  {
    auth: authContract
  },
  {
    strictStatusCodes: true,
    pathPrefix: "/api"
  }
);

路由层实现

// 子路由实现
export const authRouter = initServer().router(apiContract.auth, {
  login: async () => ({ /* 实现 */ })
});

// 聚合路由
export const apiRouter = initServer().router(apiContract, {
  auth: authRouter
});

设计考量与替代方案

虽然上述方式需要引入一些重复代码，但它确保了：

1. 类型安全贯穿整个应用
2. 客户端和服务端行为一致性
3. 清晰的模块边界

对于希望简化开发的场景，可以考虑：

1. 使用类型断言临时绕过类型检查
2. 完全分离路由注册，不使用嵌套路由结构
3. 修改框架类型定义（不推荐生产环境使用）

结论

ts-rest框架通过严格的类型系统确保了API开发的可靠性，虽然在某些场景下会显得不够灵活，但这种设计选择带来了更好的类型安全和开发体验。理解框架的设计哲学并遵循推荐的项目结构，能够帮助开发者构建更健壮的API服务。

对于新接触ts-rest的开发者，建议从简单的平面路由结构开始，逐步过渡到复杂的嵌套场景，以充分理解框架的类型系统和设计理念。