在 Convex 中构建 HTTP 端点处理…

当需要在 Convex 应用中接收第三方 Webhook、暴露自定义 API 路由、处理上传/下载、做 API Key/Bearer 鉴权、配置 CORS 和校验 Webhook 签名时使用。

适用场景

解决思路

1. 实现前先获取最新文档，不要假设：查阅 https://docs.convex.dev/functions/http-actions、https://docs.convex.dev/functions/actions、https://docs.convex.dev/auth、https://docs.convex.dev/llms.txt。
2. HTTP actions 可定义能接收第三方服务 webhook、创建自定义 API 路由、处理文件上传、集成外部服务、提供动态内容的 HTTP 端点。
3. 基础 HTTP 路由：在 `convex/http.ts` 中 `import { httpRouter } from "convex/server";` 和 `import { httpAction } from "./_generated/server";`，创建 `const http = httpRouter();`，用 `http.route({ path, method, handler: httpAction(async (ctx, request) => ... ) })` 定义路由，最后 `export default http;`。
4. 简单 GET 端点：为 `/health` 的 `GET` 返回 `new Response(JSON.stringify({ status: "ok" }), { status: 200, headers: { "Content-Type": "application/json" } })`。
5. 处理 JSON body：`const body = await request.json();`；读取 headers：`request.headers.get("Authorization")`；读取 URL 参数：`const url = new URL(request.url); url.searchParams.get("filter")`；返回 JSON 响应。
6. 处理 form data：`const formData = await request.formData();`，用 `formData.get("name")`、`formData.get("email")` 读取字段并返回 JSON。
7. 处理 raw bytes：`const bytes = await request.bytes();`，读取 `Content-Type` 默认 `application/octet-stream`，用 `new Blob([bytes], { type: contentType })` 和 `await ctx.storage.store(blob)` 存入 Convex storage，返回 `storageId`。
8. 路径参数：使用 `pathPrefix` 做动态路由，例如 `http.route({ pathPrefix: "/api/users/", method: "GET", handler: ... })`，通过 `url.pathname.replace("/api/users/", "")` 提取 `userId`。
9. CORS 配置：定义 `corsHeaders`，包含 `Access-Control-Allow-Origin: *`、`Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS`、`Access-Control-Allow-Headers: Content-Type, Authorization`、`Access-Control-Max-Age: 86400`；为同一路径的 `OPTIONS` 方法返回 `new Response(null, { status: 204, headers: corsHeaders })`；实际端点响应中展开 `...corsHeaders`。
10. Webhook 处理：读取签名相关 header，如 `stripe-signature`、`X-GitHub-Event`、`X-Hub-Signature-256`；缺失签名返回 400；用 `const body = await request.text();` 读取原始 body；调用 `await ctx.runAction(internal.stripe.verifyAndProcessWebhook, { body, signature })` 或 `internal.github.processWebhook`；成功返回 `OK` 200，失败捕获错误后返回 400。
11. Webhook 签名验证（Stripe）：在 `convex/stripe.ts` 加 `"use node";`，定义 `internalAction`，`args` 用 `v.string()` 声明 `body` 和 `signature`，`returns: v.null()`；从 `process.env.STRIPE_WEBHOOK_SECRET!` 读取 secret；用 `stripe.webhooks.constructEvent(args.body, args.signature, webhookSecret)` 验证；按 `event.type`（如 `checkout.session.completed`、`customer.subscription.updated`）调用 `ctx.runMutation(internal.payments.handleCheckoutComplete, ...)` 或 `internal.subscriptions.handleUpdate`。
12. Webhook 签名验证（Clerk/Svix）：在 `convex/clerk.ts` 加 `"use node";`，用 `internalAction` 接收 `body`、`svixId`、`svixTimestamp`、`svixSignature`；从 `process.env.CLERK_WEBHOOK_SECRET!` 读取 secret；用 `new Webhook(webhookSecret).verify(args.body, { "svix-id": args.svixId, "svix-timestamp": args.svixTimestamp, "svix-signature": args.svixSignature })` 验证；按 `user.created`、`user.updated`、`user.deleted` 调用 `internal.users.create/update/remove`。
13. HTTP action 鉴权（API key）：读取 `X-API-Key`；缺失返回 401 JSON `{ error: "Missing API key" }`；用 `await ctx.runQuery(internal.auth.validateApiKey, { apiKey })` 校验；无效返回 403 JSON `{ error: "Invalid API key" }`；通过后调用 `ctx.runQuery(internal.data.getProtectedData, {})` 并返回数据。
14. HTTP action 鉴权（Bearer token）：读取 `Authorization`；要求以 `Bearer ` 开头，否则返回 401；用 `authHeader.slice(7)` 取 token；调用 `ctx.runQuery(internal.auth.validateToken, { token })`；无效返回 403；成功返回用户 JSON。
15. 在 HTTP action 中调用 mutation/query：用 `ctx.runMutation(internal.items.create, { name, description })` 创建数据；用 `ctx.runQuery(internal.items.get, { id: itemId })` 查询单条；用 `ctx.runQuery(internal.items.list, { limit })` 查询列表，GET 的 `limit` 通过 `parseInt(url.searchParams.get("limit") ?? "10")` 解析；POST 返回 201。
16. 错误处理：定义 `jsonResponse(data, status = 200)` 和 `errorResponse(message, status)` helper；检查 `Content-Type` 必须包含 `application/json`，否则返回 415；用 try/catch 解析 `request.json()`，失败返回 400 `Invalid JSON body`；校验必填字段如 `body.data`，缺失返回 400；调用 `ctx.runMutation(internal.process.handle, { data: body.data })`；外层 catch 记录错误并返回 500。
17. 文件下载：使用 `pathPrefix: "/files/"` 和 `GET`；从 `url.pathname.replace("/files/", "") as Id<"_storage">` 取 fileId；用 `await ctx.storage.getUrl(fileId)` 获取 URL；不存在返回 404；存在时 `Response.redirect(fileUrl, 302)`。
18. 完整 Webhook 集成（Clerk）：在 `convex/http.ts` 为 `/webhooks/clerk` 的 `POST` 读取 `svix-id`、`svix-timestamp`、`svix-signature`；缺失返回 400；`const body = await request.text();`；调用 `ctx.runAction(internal.clerk.verifyAndProcess, { body, svixId, svixTimestamp, svixSignature })`；成功返回 `OK` 200，失败返回 400。
19. 为 HTTP API 定义 schema：在 `convex/schema.ts` 用 `defineSchema` 和 `defineTable` 定义 `apiKeys`（key、userId、name、createdAt、lastUsedAt、revokedAt，索引 `by_key`、`by_user`）、`webhookEvents`（source、eventType、payload、processedAt、status、error，索引 `by_source`、`by_status`）、`users`（clerkId、email、name，索引 `by_clerk_id`）。
20. 最佳实践：除非明确指示，不要运行 `npx convex deploy`；除非明确指示，不要运行任何 git 命令；始终校验和清理传入请求数据；数据库操作使用 internal functions；实现带正确状态码的错误处理；为浏览器可访问端点添加 CORS headers；处理 webhook 前验证签名；记录 webhook 事件用于调试；使用环境变量存 secrets；优雅处理超时。
21. 常见陷阱：不要漏掉 CORS 预检 OPTIONS 处理器；不要不验证 webhook 签名；不要从 HTTP actions 暴露 internal functions，应使用 internal functions；不要忘记 Content-Type headers；不要不处理请求 body 解析错误；不要长时间阻塞，重处理用 scheduled functions。
22. 参考：Convex Documentation https://docs.convex.dev/、Convex LLMs.txt https://docs.convex.dev/llms.txt、HTTP Actions https://docs.convex.dev/functions/http-actions、Actions https://docs.convex.dev/functions/actions、Authentication https://docs.convex.dev/auth。

适用边界 · 注意事项

• 项目未使用 Convex 或无法/不想依赖 Convex 平台/云服务时。
• 只需要普通 Node/Express/Next.js API 路由且没有 Convex 数据、存储或动作集成需求时。
• 无法配置 webhook secret 或无法验证第三方签名时，不应直接处理不可信 webhook 负载。