Wasp项目中的自定义HTTP API端点开发指南

概述

在Wasp项目中，虽然默认的客户端-服务器交互机制是通过Operations实现的，但当你需要特定的URL方法/路径或特定的响应时，Operations可能就不太适用了。这时，你可以使用API功能来创建自定义HTTP端点。

API基础概念

API是Wasp中用于将JavaScript函数绑定到特定端点(如POST /something/special)的机制。与Operations不同，API没有客户端辅助工具(如useQuery)，但提供了更大的灵活性。

创建API的步骤

1. 在Wasp文件中声明API

首先需要在Wasp文件中使用api声明来定义API：

api fooBar {
  fn: import { fooBar } from "@src/apis",
  httpRoute: (GET, "/foo/bar")
}

这里：

• fooBar是API的名称
• fn指定了实现函数的导入路径
• httpRoute定义了HTTP方法和路径

2. 实现NodeJS函数

在TypeScript环境下，Wasp编译器会为API生成类型定义。实现函数需要接收三个参数：

1. req: Express的Request对象
2. res: Express的Response对象
3. context: Wasp注入的上下文对象，包含用户会话信息和实体信息

示例实现：

import type { FooBar } from "wasp/server/api";

export const fooBar: FooBar = (req, res, context) => {
  res.json({ msg: `Hello, ${context.user ? "registered user" : "stranger"}!` });
};

高级类型支持

在TypeScript中，你可以为API函数提供额外的类型信息：

import { FooBar } from "wasp/server/api";

export const fooBar: FooBar<
  { email: string },  // 参数类型
  { answer: number }  // 响应类型
> = (req, res, _context) => {
  console.log(req.params.email);
  res.json({ answer: 42 });
};

API的使用方式

外部调用

可以直接通过HTTP客户端(如浏览器、Postman、curl等)调用API端点。例如，对于GET /foo/bar端点，可以直接发送GET请求到该路径。

客户端调用

在Wasp客户端代码中，可以使用内置的Axios包装器调用API：

import { api } from "wasp/client/api";

async function fetchCustomRoute() {
  const res = await api.get("/foo/bar");
  console.log(res.data);
}

CORS配置

由于API不使用默认中间件，需要特别注意CORS配置。可以通过定义中间件配置函数来启用CORS：

apiNamespace fooBar {
  middlewareConfigFn: import { fooBarNamespaceMiddlewareFn } from "@src/apis",
  path: "/foo"
}

实现文件：

import type { MiddlewareConfigFn } from "wasp/server";
export const apiMiddleware: MiddlewareConfigFn = (config) => {
  return config;
};

在API中使用数据实体

要在API中使用数据实体，需要在声明中指定：

api fooBar {
  entities: [Task],
  // 其他配置...
}

然后在实现中通过context访问：

export const fooBar: FooBar = async (req, res, context) => {
  res.json({ count: await context.entities.Task.count() });
};

API声明参考

完整的API声明包含以下字段：

• fn: 必需，实现函数的导入语句
• httpRoute: 必需，HTTP方法和路径的元组
• entities: 可选，要在API中使用的实体列表
• auth: 可选，布尔值，默认为true，决定是否解析JWT
• middlewareConfigFn: 可选，中间件配置函数的导入语句

最佳实践

1. 对于简单的CRUD操作，优先考虑使用Operations
2. 需要特定路由或自定义响应时使用API
3. 在TypeScript项目中充分利用类型系统
4. 注意CORS配置，特别是在跨域调用时
5. 合理使用中间件来扩展API功能

通过掌握Wasp中的API开发，你可以创建高度定制化的HTTP端点，满足各种复杂的业务需求。