backend-patterns

后端模式

适用于一般后端和数据工作的最佳实践。阅读以下每条模式。如果有任何一条适用于你即将构建的内容，就遵循它。 对于这里已明确规定的事项，不要征求许可——直接遵循规则，并用一行说明你已遵循。

何时查阅此技能

每当你编写或编辑的代码涉及以下情况时：

• 将 URL／链接保存、插入或持久化到数据库
• 接受来自用户、Agent、webhook、导入操作或粘贴处理器的链接
• 将链接转发到其他系统
• 将链接添加到任何用于保存知识的界面（例如看板、任务控制台、知识库、书签、笔记）
• 构建用于创建包含链接的记录的 Agent 工具
• 查询或写入数据库（读取、插入、更新、删除）
• 更改数据库架构，或运行迁移／生成／推送命令

如果以下模式都不适用于当前场景，则不作说明，返回原始任务。

模式

• 保存社交媒体链接时，必须通过我们的自动归档器处理（此迷你应用将在未来添加）。
  • 如果代码库中尚不存在自动归档器，不要悄悄存储原始链接。应将所有链接写入集中到一个辅助函数（例如 saveLink(url, context)）中，并明确标记 TODO: route through auto-archiver once available，这样未来接入时只需在一个地方进行一处更改。
• 数据库操作优先使用 ORM；尽可能避免原始 SQL。只有在确有必要时（ORM 无法表达相关操作）才使用原始 SQL，并用一行说明原因。
• 修改数据和处理表单时，优先使用服务器操作而非 API 路由。只有在确有必要时才使用 API 路由（例如 webhook 接收器、公开的／第三方 HTTP 端点，或需要 REST／JSON 接口的非表单客户端）。请参阅 next-best-practices 技能获取指导。
• 未经用户明确确认，绝不要对已连接的数据库应用架构更改。编辑架构源文件（例如 Prisma／Drizzle 架构文件）没有问题，但在运行任何会修改已连接数据库架构的操作之前——pnpm db:generate、pnpm db:migrate、pnpm db:push 或直接修改架构的 SQL——请先停下并征求用户确认。这是此技能中唯一需要先征求确认、而非直接执行的情况。

此技能适用时的行为方式

1. 确定哪些模式适用于当前工作。
2. 遵循这些模式。除非有具体原因表明该模式不适用，否则不要提出其他方案。
3. 用一行简短说明你遵循了哪条模式，以便用户在必要时提出异议。
4. 如果模式所需的某项基础设施（例如归档器本身）尚不存在，请明确说明，并解释你采取了什么替代做法。

未来模式

此技能会随着时间不断扩展。新增模式时，应将其作为项目符号添加到上方的模式部分，并写成 Agent 可以机械执行的规则。