SolidStart 项目中的 API 路由开发指南

2025-07-10 10:36:18作者：范靓好Udolf

前言

在现代 Web 开发中，API 路由是构建前后端分离应用的关键部分。SolidStart 作为一款优秀的全栈框架，提供了简洁而强大的 API 路由解决方案。本文将深入探讨 SolidStart 中的 API 路由开发，帮助开发者构建高效、灵活的后端接口。

什么是 API 路由？

API 路由是指专门处理 HTTP 请求并返回数据（而非 HTML 页面）的路由。与传统的 UI 路由不同，API 路由专注于数据交互，通常返回 JSON、XML 或其他结构化数据格式。

为什么需要 API 路由？

多客户端支持：为 Web、移动端等多个客户端提供统一的数据接口
特殊协议支持：实现 GraphQL、tRPC 等特殊协议端点
公共 API：向第三方开发者开放数据接口
Webhook 处理：处理 OAuth 认证回调等特殊请求
非 HTML 内容：提供 PDF、图片等二进制内容

基础 API 路由开发

创建基本路由

在 SolidStart 中，API 路由与 UI 路由使用相同的文件命名约定，区别在于导出内容。API 路由不导出默认的 Solid 组件，而是导出以 HTTP 方法命名的函数。

// 处理 /api/students 的 GET 请求
export function GET() {
  return new Response("学生列表数据");
}

// 处理 POST 请求
export function POST() {
  // 处理创建新学生的逻辑
}

重要注意事项

一个路由文件不能同时导出默认 UI 组件和 GET 处理器
未定义的处理方法会返回 405 Method Not Allowed 响应

高级路由功能

动态路由参数

SolidStart 支持动态路由参数，方便构建 RESTful 风格的 API：

export async function GET({ params }: APIEvent) {
  // 访问 /api/students/123 时，params.id 为 "123"
  const studentId = params.id;
  // 获取学生数据...
}

请求上下文

API 路由处理器接收 APIEvent 对象，包含丰富的信息：

request：完整的请求对象
params：动态路由参数
env：环境变量和绑定
fetch：内部 fetch 方法，用于调用其他 API 路由

会话管理实战

安全的会话管理是 Web 开发的关键。以下示例展示如何使用 HTTP-only cookie 进行用户认证：

export async function GET({ request, params }: APIEvent) {
  // 解析 cookie
  const cookie = parseCookie(request.headers.get("Cookie") ?? "");
  const userId = cookie['userId'];
  
  // 认证检查
  if (!userId) {
    return new Response("未登录", { status: 401 });
  }
  
  // 授权检查
  if (!hasPermission(userId, params.resource)) {
    return new Response("无访问权限", { status: 403 });
  }
  
  // 返回数据
  return json({ data: await getProtectedData(params.resource) });
}

特殊协议集成

GraphQL API 实现

SolidStart 可以轻松集成 GraphQL：

import { buildSchema, graphql } from "graphql";

const schema = buildSchema(`
  type Query {
    hello: String
  }
`);

const rootValue = {
  hello: () => "Hello from SolidStart!"
};

export const POST = async (event: APIEvent) => {
  const body = await new Response(event.request.body).json();
  const result = await graphql({ schema, source: body.query, rootValue });
  return json(result);
};

tRPC 集成

tRPC 是类型安全的 RPC 解决方案，与 SolidStart 完美契合：

首先定义路由器：

// lib/router.ts
import { initTRPC } from '@trpc/server';

const t = initTRPC.create();

export const appRouter = t.router({
  getUser: t.procedure.query(() => ({ id: 1, name: "张三" }))
});

export type AppRouter = typeof appRouter;

然后创建 API 路由处理器：

// routes/api/trpc/[...].ts
import { fetchRequestHandler } from '@trpc/server/adapters/fetch';

export const POST = (event: APIEvent) => 
  fetchRequestHandler({
    endpoint: '/api/trpc',
    req: event.request,
    router: appRouter,
    createContext: () => ({}),
  });