在 TypeScript 项目中使用 Prisma ORM…

适用于 TypeScript + Prisma ORM 项目的数据库 schema 设计、迁移、客户端查询、错误处理和测试规范落地。

适用场景

解决思路

1. 为变量和函数始终声明显式类型。
2. 避免使用 'any'。
3. 为公共 API 编写并使用 JSDoc。
4. 每个文件只维护单一导出。
5. 优先编写自文档化代码。
6. 类/接口使用 PascalCase 命名。
7. 变量和方法使用 camelCase 命名。
8. 文件和目录使用 kebab-case 命名。
9. 常量使用 UPPERCASE 命名。
10. 布尔值使用基于动词的名称，如 isLoading、hasError、canDelete。
11. 每个函数尽量少于 20 行代码。
12. 每个函数只承担单一职责。
13. 使用提前返回。
14. 将复杂逻辑抽取到独立函数中。
15. 利用函数式模式（map、filter、reduce）。
16. 多个参数时使用对象参数。
17. 将数据封装到复合类型中，并优先使用不可变数据。
18. 适当使用 `readonly` 和 `as const`。
19. 在边界处校验数据。
20. 使用具体、描述性的错误类型，并附带上上下文信息的消息。
21. 模型和字段采用领域驱动命名。
22. 使用 `@relation` 显式声明关系。
23. 在合适处使用规范化结构。
24. 通过 `deletedAt` 字段实现软删除。
25. 对数据库特定类型使用原生类型装饰器。
26. 始终使用类型安全的 Prisma Client 操作。
27. 对复杂流程使用事务。
28. 为日志、软删除和审计实现 middleware。
29. 谨慎使用 `select` 和 `include`，避免过度获取数据。
30. 创建描述性强、命名清晰的迁移。
31. 绝不修改已有迁移。
32. 确保所有迁移具备幂等性。
33. 在生产前先在 staging 环境测试迁移。
34. 对约束冲突捕获 `PrismaClientKnownRequestError`。
35. 对意外数据库错误处理 `PrismaClientUnknownRequestError`。
36. 对 schema 不匹配使用 `PrismaClientValidationError` 进行校验和处理。
37. 通过适当的预加载（eager loading）避免 N+1 查询。
38. 使用内存数据库进行测试以提升速度。
39. 为单元测试隔离而 mock Prisma Client。
40. 绝不在 API 中暴露原始 Prisma Client。
41. 在数据库操作前校验所有用户输入。
42. 遵循 SOLID 原则，优先使用组合而非继承。

适用边界 · 注意事项

• 项目不使用 Prisma ORM 或 TypeScript 时，这些 Prisma/TypeScript 专属规范不直接适用。
• 使用其他 ORM 或查询构建器（如 TypeORM、Drizzle）时，应改用对应工具的 schema、迁移和客户端实践。
• 无法引入 Prisma schema/migration 流程或要求完全避免特定 ORM 依赖时，不适合直接套用。