SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场convex-review

convex-review

编程与开发

查看项目

更新于 10-15 09:48

技能介绍

用途

Convex Code Review 是一份面向生产就绪（production readiness）的 Convex 代码审查清单。它适用于在部署前审计 Convex 代码库、审查拉取请求（pull requests）等场景，帮助开发者系统性地检查代码中的安全、性能、架构与代码质量问题。

主要能力

清单按四大类组织检查项，并附带快速正则搜索与修复建议。

安全清单

  1. 参数与返回值验证器：所有公开的 query、mutation、action 都应有 args 验证器；所有函数都应有 returns 验证器；敏感数据不得使用 v.any()；HTTP action 应验证请求体（推荐 Zod）。搜索方式：查找 query({、mutation({、action({，检查每个是否同时具有 args: 和 returns:。

  2. 错误处理：面向用户的错误应使用 ConvexError（而非普通 Error）；错误码应结构化，如 { code: "NOT_FOUND", message: "..." }；错误消息中不得泄露敏感信息。搜索方式：throw new Error 应改为 throw new ConvexError。

  3. 访问控制：所有公开函数在需要时应检查 ctx.auth.getUserIdentity()；使用认证辅助函数（requireAuth、requireRole）；不得使用客户端提供的 email/username 进行授权；应验证行级访问（所有权检查）。搜索方式：ctx.auth.getUserIdentity 应出现在大多数公开函数中。

  4. 内部函数：ctx.runQuery、ctx.runMutation、ctx.runAction 应使用 internal.* 而非 api.；ctx.scheduler.runAfter 应使用 internal. 而非 api.；crons.ts 中的定时任务应使用 internal. 而非 api.*。搜索方式：在 convex 目录中查找 api.，不应将其用于调度或运行。

  5. 数据库调用中的表名：所有 ctx.db.get、patch、replace、delete 都应将表名作为第一个参数。搜索方式：db.get(、db.patch( 的第一个参数应为带引号的字符串。

性能清单

  1. 数据库查询：查询中不得使用 .filter()（应使用 .withIndex() 或在代码中过滤）；.collect() 仅用于结果有界的情况（少于 1000 个文档）；大结果集应使用分页。搜索方式：.filter((?q、.collect(。

  2. 索引：不得有冗余索引（by_foo 与 by_foo_and_bar）；所有过滤查询应使用 .withIndex()；索引名称应包含所有字段。审查方式：查看 schema.ts 中的索引定义。

  3. 查询中的 Date.now()：query 函数中不得使用 Date.now()；时间过滤应使用布尔字段或客户端传入的时间戳。

  4. Promise 处理：所有 promise 都应被 await（ctx.scheduler、ctx.db.*）。ESLint：no-floating-promises。

架构清单

  1. Action 使用：若使用 Node.js API，Action 应包含 "use node"；仅在切换运行时时使用 ctx.runAction；不得顺序调用 ctx.runMutation/ctx.runQuery（应合并以保证一致性）。

  2. 代码组织：业务逻辑放在辅助函数中（convex/model/）；公开 API 处理器应为薄包装；认证辅助函数放在 convex/lib/auth.ts。

  3. 事务一致性：相关读取放在同一 query/mutation 中；批量操作放在单个 mutation 中；mutation 应幂等。

快速正则搜索

清单提供问题、正则与修复的对照表：.filter() 对应 .filter((?q，修复为使用 .withIndex()；缺失 returns 对应 handler:.async without returns:，修复为添加 returns:；普通 Error 对应 throw new Error(，修复为使用 ConvexError；缺失表名对应 db.(get|patch)([^"']，修复为添加表名；查询中的 Date.now() 对应 Date.now()，修复为从查询中移除；api. 调度对应 api.[a-z]，修复为使用 internal.*。

生产就绪总结

安全：验证器 + ConvexError + 认证检查 + 内部函数。性能：索引 + 有界查询 + 无 Date.now()。架构：辅助函数 + 正确的 Action 使用 + "use node"。代码质量：await 的 promise + 表名 + 返回值验证器。

使用方式

将本清单作为审查 Convex 代码库的检查表，逐项核对；也可使用清单中提供的正则表达式在代码库中搜索潜在问题，并按修复建议调整。

适用场景

适用于 Convex 项目的部署前审计、拉取请求审查，以及日常代码质量与安全检查。

限制

本清单为审查指南，具体项目情况可能不同；资料未提供自动化工具集成、命令行安装方式或价格信息。