用途:为在 Next.js(TypeScript)中构建 API 端点提供一套规范,数据库使用 MariaDB,目标是安全、一致、现代化。
主要能力:
- 安全优先:校验会话令牌、执行前检查权限、不暴露敏感数据、校验与清洗用户输入、使用参数化查询防 SQL 注入。
- 一致性:统一命名、遵循 RESTful 原则、统一错误处理与标准 HTTP 状态码。
- 性能:合理使用索引、列表端点分页、适当缓存、实现前优化查询。
使用方式: 开发前先做检查清单。第一步用 MariaDB MCP server 核对数据库结构,例如 SHOW TABLES LIKE 'table_name';、DESCRIBE table_name;、SHOW INDEX FROM table_name;,并用 INFORMATION_SCHEMA.KEY_COLUMN_USAGE 查外键关系。第二步确认所需权限,查看 /src/constants/permissions.ts,在 withAuth、withPermission、withAnyPermission 之间选择。第三步先写 SQL 并用 MCP server 测试,用 EXPLAIN 检查性能。
端点按 src/app/api/ 目录组织,route.ts 处理列表与创建,[id]/route.ts 处理单条读取、更新与删除,子资源放在嵌套目录。模板使用 NextRequest、NextResponse、@/lib/db 的 query、@/constants/permissions 的 Permissions 与 @/lib/auth/wrappers 的 withPermission,并设置 export const dynamic = 'force-dynamic'。
鉴权包装器:withAuth 仅需认证;withPermission(Permissions.X) 需单一权限;withAnyPermission(Permissions.A, Permissions.B) 满足任一权限即可。
输入校验:校验邮箱、日期格式、数字 ID、枚举值等,非法输入返回 400。SQL 一律使用参数化查询,动态 WHERE 子句用占位符与参数数组拼接,禁止拼接用户输入。响应只返回必要字段,用 SELECT 限定列。
数据库实践:多操作使用事务(beginTransaction、commit、rollback、release);用 EXPLAIN 检查查询,为高频查询列建索引;大数据集用 LIMIT 与分页;用 COALESCE 处理 NULL;日期用 NOW() 或 CURRENT_TIMESTAMP。
错误处理:客户端错误返回 4xx,服务端错误返回 5xx,统一返回 error、details、可选 code 字段;开发环境可返回错误详情。
适用场景:在 Next.js + TypeScript + MariaDB 项目中编写或审查 API 端点。
限制:资料未提供安装命令、收费与价格、平台支持范围及具体版本要求,暂未提供。