SuperAPI AI 工具集

convex-http-actions

编程与开发

查看项目

更新于 10-16 07:21

技能介绍

用途:在 Convex 部署的 .convex.site 域名上定义公开 HTTP 端点,用于接收第三方 webhook(如 Stripe、Clerk、Resend、GitHub),或为无法使用 Convex SDK 的客户端提供普通 HTTP API,也支持浏览器下载/流式传输字节和通过 HTTP 上传文件。

主要能力:httpAction 处理器可调用 ctx.runQuery、ctx.runMutation、ctx.runAction、ctx.storage、ctx.scheduler、ctx.auth,但不得直接读写 ctx.db;支持 HMAC SHA-256 签名校验、常量时间比较、按事件 id 去重、CORS 预检、Bearer 令牌读取、流式响应与文件存取。请求与响应体上限 20MB,运行于默认 Convex 运行时,Web API 无需 "use node"。

使用方式:路由器必须位于 convex/http.ts 并作为默认导出,其他文件中的路由器会被忽略。用 http.route({ path, method, handler }) 注册路由,path 精确匹配,动态段用 pathPrefix 并从 new URL(request.url).pathname 读取尾部。处理器应指向 internal.* 函数,参数仍经过目标校验器。慢任务应快速返回 200 并用 ctx.scheduler.runAfter(0, ...) 调度。

限制与常见错误:HTTP actions 没有参数校验器和自动认证;webhook 必须先 request.text() 读取原始体再校验签名,不能先解析;必须校验签名,不能因来源可信而跳过;浏览器调用的路径需配套 OPTIONS 路由;JSON 响应需设置 Content-Type: application/json;提供商在非 2xx 时会重试,需按事件 id 去重。

文档:https://docs.convex.dev/functions/http-actions