如何在 ts-rest 项目中优雅地拆分路由和契约

在 ts-rest 项目中，随着业务逻辑的增长，将所有路由和契约定义放在单个文件中会变得难以维护。本文将介绍几种在 ts-rest 中拆分路由和契约的有效方法，帮助开发者构建更清晰、更易维护的代码结构。

基础拆分方法

最直接的方式是将每个路由处理函数单独定义，然后组合到主路由中：

import { type AppRouteImplementation } from '@ts-rest/express';

const getPost: AppRouteImplementation<typeof contract.getPost> = async ({ params: { id } }) => {
    return {
        status: 200,
        body: { id: "1", title: "my title", body: "000" }
    };
};

const createPost: AppRouteImplementation<typeof contract.createPost> = async ({ body }) => {
    return {
        status: 201,
        body: { id: "1", title: "my title", body: "000" }
    };
};

const router = s.router(contract, { getPost, createPost });

这种方法利用了 AppRouteImplementation 类型来确保每个处理函数与契约定义的类型匹配。

模块化路由组织

更推荐的方式是将相关路由分组到不同的模块文件中，然后在主路由中组合：

// userRouter.ts
const getUsersRoute = s.router(
    { getUsers: contract.getUsers },
    {
        getUsers: async () => { /* 处理逻辑 */ }
    }
);

const getUserByIdRoute = s.router(
    { getUserById: contract.getUserById },
    {
        getUserById: {
            middleware: [ /* 中间件逻辑 */ ],
            handler: async ({ params: { id } }) => { /* 处理逻辑 */ }
        }
    }
);

export const userRoutes = {
    getUserById: getUserByIdRoute.getUserById,
    getUsers: getUsersRoute.getUsers
};

然后在主路由文件中：

import { userRoutes } from './userRouter';
import { postRoutes } from './postRouter';

const mainRouter = s.router(contract, {
    ...userRoutes,
    ...postRoutes
});

契约的模块化拆分

同样地，契约定义也可以按模块拆分：

// userContract.ts
const getUsersContract = c.query({
    method: 'GET',
    path: '/users',
    responses: {
        200: { description: '用户列表' },
        404: { description: '未找到' }
    }
});

const getUserByIdContract = c.query({
    method: 'GET',
    path: '/users/:id',
    responses: {
        200: { description: '用户详情' },
        404: { description: '用户未找到' }
    }
});

export const usersContract = {
    getUsers: getUsersContract,
    getUserById: getUserByIdContract
};

在主契约文件中组合：

import { usersContract } from './userContract';
import { postsContract } from './postContract';

export const contract = c.router({
    ...usersContract,
    ...postsContract
});

最佳实践建议

1. 按业务领域划分模块：将同一业务领域的路由和契约放在同一目录下
2. 保持命名一致性：路由文件名与契约文件名对应，如 userRouter.ts 和 userContract.ts
3. 利用类型安全：始终使用 AppRouteImplementation 确保类型安全
4. 中间件处理：可以在路由定义中直接包含中间件逻辑
5. 渐进式拆分：不必一开始就完美拆分，随着项目增长逐步重构

通过这种模块化的组织方式，ts-rest 项目可以保持清晰的结构，便于团队协作和长期维护。每个模块专注于自己的业务逻辑，主文件则负责组合和配置，实现了关注点分离。