该技能用于后端开发场景,在涉及 API、路由、端点、数据库、Supabase、schema、迁移、Webhook 或服务端操作时自动启用,可与前端 UI 和安全鉴权模式配合使用。
主要能力与规则:
- API 端点:每个端点需依次完成鉴权(await auth(),未登录返回 401)、输入校验(用 Schema.safeParse,失败返回 400 及错误详情)、资源归属检查(资源 userId 不匹配返回 404)、在 try/catch 中执行并返回 201,错误仅向客户端返回通用信息、详细错误写入日志。
- 服务端操作:使用 'use server',同样先鉴权、再 safeParse 校验,成功后写入数据库并调用 revalidatePath 刷新缓存,返回 { data } 或 { error }。
- 数据库模式:用 include 避免 N+1 查询;列表必须分页(skip/take/orderBy);ID 用 BIGINT、时间戳用 TIMESTAMPTZ、金额用 DECIMAL。
- Webhook:先验证签名(如 stripe.webhooks.constructEvent),再做幂等检查(按 eventId 查重),按事件类型处理,最后标记已处理。
用法参考:API 路由文件 app/api/users/route.ts 对应 GET/POST /api/users,app/api/users/[id]/route.ts 对应 GET/PATCH/DELETE /api/users/:id。表单提交与变更优先用 Server Action,需外部访问或 Webhook 用 API Route。Supabase 可依赖 RLS 自动完成授权。
安全清单:开头鉴权、Zod 校验所有输入、资源访问做归属检查、客户端只给通用错误、日志保留详情、代码中不放密钥、验证 Webhook 签名。常见问题包括缺少 await auth()、用 Schema.parse 而非 safeParse、缺少归属检查、直接返回 error.message、拼接 SQL 字符串、未分页。
限制:资料未提供安装方式、依赖版本、收费与平台支持等信息。