项目架构设计：从业务到能力的映射

项目架构设计：从业务到能力的映射

本章用一个贯穿性的示例应用，演示如何把前九章的能力组装成真实架构。本节先做「业务拆解」与「能力映射」——这是动手前最重要的设计环节。

示例应用：智能知识协作平台

为了覆盖尽可能多的能力，我们设想一个「智能知识协作平台」，它的核心功能包括：

• 用户注册登录、个人资料管理。
• 用户创建、编辑、分享文档（支持上传图片附件）。
• 多人实时协作编辑同一文档（看到他人光标、在线状态）。
• 文档支持语义搜索（按意思查找）。
• 智能问答助手：基于全部文档回答用户问题（RAG）。
• 定时清理过期草稿、生成数据快照。

这个应用几乎要用到 Supabase 的每一项能力，是绝佳的整合示例。

第一步：识别实体与关系

架构设计从数据建模开始（第 2 章）。识别核心实体：

• 用户：平台的使用者。
• 文档：用户创作的内容，归属某用户，可被共享。
• 协作者：文档与用户的共享关系（多对多）。
• 附件：文档关联的文件（存 Storage）。
• 文档片段：为 RAG 切分的知识片段，带向量。

关系一览：

• 用户 ↔ 文档：一对多（一个用户拥有多份文档）。
• 文档 ↔ 用户（协作者）：多对多（通过协作者关联表）。
• 文档 ↔ 附件：一对多（一份文档多个附件）。
• 文档 ↔ 片段：一对多（一份文档切成多个片段用于 RAG）。

第二步：能力映射

把每个功能映射到 Supabase 的能力：

这张映射表是架构设计的核心产出——它让你清楚「每个需求靠什么能力实现、怎么实现」。

第三步：分层架构

从工程视角，整个应用可分为三层：

• 客户端层：用客户端库直连平台层的大部分能力（受 RLS 保护）。
• 平台层：Supabase 提供的数据库、认证、实时、存储、函数。
• 外部服务层：大模型、邮件、支付等，由边缘函数代理访问。

这种分层让前端尽量直连（高效、简单），把必须保密或需编排的逻辑交给边缘函数。

第四步：划分「直连」与「走函数」

一个关键设计决策：某个操作让前端直连数据库，还是经由边缘函数？判断标准：

• 前端直连（受 RLS 保护）：标准的、按用户隔离的增删改查。如查看自己的文档、编辑自己的内容。简单高效，首选。
• 走边缘函数：涉及密钥、跨权限操作、外部调用、复杂编排。如调用大模型、发邮件、跨用户聚合统计、批量清理。

原则：能用 RLS + 直连解决的，绝不加函数。
只有需要服务端密钥或外部调用时，才经由边缘函数。
​

避免「所有请求都过函数」的反模式——那样既慢又贵，还抹杀了 Supabase 直连架构的优势。

第五步：考虑非功能需求

架构不止于功能，还要考虑：

• 安全：RLS 覆盖、密钥管理、输入校验（详见第 4 节）。
• 性能：索引、连接管理、缓存（详见第 3 节）。
• 可扩展性：表结构能否支撑未来增长，能力是否易于扩展。
• 可维护性：逻辑分层清晰、命名一致、迁移可追溯。

这些非功能需求往往决定了应用能否长期健康运行。

第六步：环境与项目规划

借鉴第 1 章的环境隔离理念：

• 为开发、预发布、生产分别建立项目。
• 用迁移工具管理数据库结构变更。
• 密钥与环境变量按环境隔离。
• 生产项目启用备份、监控、告警。

小结

架构设计的核心是「业务拆解 → 能力映射 → 分层组织 → 直连与函数取舍 → 非功能需求」。先把这套设计想清楚，再动手实现，能避免大量返工。下一节我们深入真实请求链路，看这些能力在实际运行中如何协作。