AnalogJS 项目中的 API 路由详解

概述

在 AnalogJS 项目中，API 路由是构建服务端功能的核心机制。通过 API 路由，开发者可以轻松创建后端接口，为前端应用提供数据服务。本文将全面介绍 AnalogJS 中 API 路由的各种用法和最佳实践。

基础 API 路由

创建简单 API 路由

在 AnalogJS 中，API 路由默认存放在 src/server/routes/api 目录下，系统会自动为这些路由添加 /api 前缀。

import { defineEventHandler } from 'h3';

export default defineEventHandler(() => ({ message: 'Hello World' }));

上述代码创建了一个最简单的 API 路由，访问 /api 路径时会返回 JSON 格式的 { message: 'Hello World' }。

特殊内容类型处理

创建 XML 内容

当需要提供 RSS 订阅等 XML 格式内容时，可以设置正确的 content-type 响应头：

// server/routes/api/rss.xml.ts
import { defineEventHandler, setHeader } from 'h3';

export default defineEventHandler((event) => {
  const feedString = `<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
</rss>`;
  
  setHeader(event, 'content-type', 'text/xml');
  return feedString;
});

静态生成 XML 内容

对于需要预渲染的 XML 内容，可以在配置中指定路由：

// vite.config.ts
prerender: {
  routes: async () => {
    return [
      '/api/rss.xml',
      // 其他需要预渲染的路由
    ];
  }
}

预渲染后，XML 文件会生成在 /dist/analog/public/api/rss.xml 路径。

动态路由处理

基础动态路由

动态路由使用方括号命名文件，参数可通过 event.context.params 获取：

// /server/routes/api/v1/hello/[name].ts
import { defineEventHandler } from 'h3';

export default defineEventHandler(
  (event) => `Hello ${event.context.params?.['name']}!`
);

使用 getRouterParam 获取参数

更推荐使用 getRouterParam 方法获取路由参数：

// /server/routes/api/v1/hello/[name].ts
import { defineEventHandler, getRouterParam } from 'h3';

export default defineEventHandler((event) => {
  const name = getRouterParam(event, 'name');
  return `Hello, ${name}!`;
});

HTTP 方法处理

特定 HTTP 方法路由

通过文件后缀可以指定处理特定 HTTP 方法的路由：

GET 请求处理

// /server/routes/api/v1/users/[id].get.ts
import { defineEventHandler, getRouterParam } from 'h3';

export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id');
  // 实际项目中这里通常会查询数据库
  return `User profile of ${id}!`;
});

POST 请求处理

// /server/routes/api/v1/users.post.ts
import { defineEventHandler, readBody } from 'h3';

export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  // 处理请求体并执行相应业务逻辑
  return { success: true, data: body };
});

查询参数处理

处理带有查询参数的请求：

// routes/api/v1/query.ts
import { defineEventHandler, getQuery } from 'h3';

export default defineEventHandler((event) => {
  const { param1, param2 } = getQuery(event);
  return `Received params: ${param1} and ${param2}`;
});

高级路由功能

通配路由

实现 404 处理或默认路由：

// routes/api/[...].ts
export default defineEventHandler((event) => ({
  statusCode: 404,
  message: 'API endpoint not found'
}));

错误处理

自定义错误响应：

// routes/api/v1/[id].ts
import { defineEventHandler, getRouterParam, createError } from 'h3';

export default defineEventHandler((event) => {
  const param = getRouterParam(event, 'id');
  const id = parseInt(param ?? '');
  
  if (!Number.isInteger(id)) {
    throw createError({
      statusCode: 400,
      statusMessage: 'ID must be an integer',
    });
  }
  
  return { id };
});

Cookie 操作

设置 Cookie

import { setCookie } from 'h3';
import { PageServerLoad } from '@analogjs/router';

export const load = async ({ event }: PageServerLoad) => {
  setCookie(event, 'session_id', 'abc123', {
    maxAge: 60 * 60 * 24, // 1天有效期
    httpOnly: true,
    secure: true
  });
  
  return { status: 'Cookie set' };
};

读取 Cookie

import { parseCookies } from 'h3';
import { PageServerLoad } from '@analogjs/router';

export const load = async ({ event }: PageServerLoad) => {
  const cookies = parseCookies(event);
  const sessionId = cookies['session_id'];
  
  return { sessionId };
};

总结

AnalogJS 提供了强大而灵活的 API 路由系统，开发者可以：

1. 轻松创建 RESTful API 接口
2. 处理各种 HTTP 方法和参数
3. 实现动态路由和通配路由
4. 进行完善的错误处理
5. 操作 Cookie 等 HTTP 特性

这些功能基于 Nitro 和 h3 实现，为构建全栈应用提供了坚实的基础。通过合理使用这些特性，可以创建出结构清晰、功能完善的后端 API 服务。