网站收藏夹功能开发的核心，是让用户能够保存网址、查看收藏、修改信息、分类整理并稳定删除，同时明确用户身份、数据字段和接口返回规则。实现前应先确定收藏夹是服务于单个用户的个人收藏，还是需要跨设备同步、多人共享；不同使用场景会直接影响数据表、权限校验、分页方式和冲突处理。
先确定收藏对象与功能边界
如果系统只保存网页地址，收藏记录可以围绕 URL、标题、备注和分类建立；如果还要保存网页快照、缩略图或正文，就已经扩展为内容采集功能，需要单独设计抓取、存储和更新机制，不能把“保存网址”接口直接当成内容收藏接口。
- 基础收藏：新增、查看、编辑、删除网址，并记录创建时间和更新时间。
- 分类整理：支持收藏夹、文件夹或标签，明确一个收藏是否只能属于一个文件夹，是否允许同时拥有多个标签。
- 检索筛选：可按标题、网址、备注、文件夹和标签筛选，关键词匹配规则应在接口文档中固定。
- 排序展示：可按最近收藏、最近修改、标题或自定义顺序排列，前端和后端要使用一致的排序字段。
- 同步需求：如果同一用户会在多个设备操作，需要保存更新时间、版本号或同步游标，不能只依赖前端本地状态。
单用户个人收藏：优先实现清晰的增删改查
适合个人导航、后台管理系统或登录后保存常用网站的场景。此时接口重点是用户隔离和数据完整性，不必一开始加入复杂的团队权限。以下为 REST 风格的建议契约，路径仅表示一种开发方案，不代表现成接口能力。
| 用途 | 建议方法与路径 | 关键参数 |
|---|---|---|
| 新增收藏 | POST /api/favorites | url、title、note、folder_id、tags |
| 收藏列表 | GET /api/favorites | folder_id、keyword、sort、page_size、cursor |
| 查看详情 | GET /api/favorites/{id} | 路径中的收藏记录 ID |
| 修改收藏 | PATCH /api/favorites/{id} | 需要修改的字段与 version |
| 删除收藏 | DELETE /api/favorites/{id} | 记录 ID，必要时支持批量删除 |
新增时，服务端应从登录凭证中取得 user_id，而不是信任客户端提交的 user_id。列表查询也必须自动附加当前用户条件，避免用户通过修改记录 ID读取他人的收藏。修改和删除同样要同时校验“记录存在”和“记录属于当前用户”。
基础数据表可以包含 id、user_id、url、title、note、folder_id、created_at、updated_at、sort_order 等字段。若启用标签，可使用独立的标签表和关联表，避免把多个标签长期拼接成难以查询的字符串。url 是否允许重复需要提前决定：允许重复时可保留多条来源不同的收藏；不允许重复时，应在同一用户范围内建立唯一规则，并返回明确的重复提示。
需要跨设备同步：增加身份、分页与冲突规则
当用户会在手机、电脑或多个浏览器中使用收藏夹，功能重点会从“能否保存”转为“数据是否一致”。接口应要求有效的登录认证，并让列表接口支持稳定分页。数据量较大时，优先采用 cursor 游标分页；如果使用 page 和 page_size，也要限制单页最大数量，防止一次返回过多记录。
- 身份校验：每次新增、查询、修改和删除都绑定认证后的用户身份，不能由前端自由指定归属用户。
- 重复提交：网络重试可能导致同一收藏被提交两次，可为新增请求增加幂等键，或依据业务规则检查相同 URL。
- 并发修改：记录中增加 version 或 updated_at，修改时携带客户端读取到的版本；版本不一致时返回 409，由前端提示刷新或重新合并。
- 删除同步：若设备需要获知删除事件，可短期保留 deleted_at，而不是立即物理删除；是否采用软删除取决于同步周期和数据保留要求。
- 排序稳定：使用 created_at 加 id，或使用 sort_order 加 id 作为辅助排序，避免时间相同时出现列表跳动。
同步接口的返回内容应固定结构，例如包含 data、meta 和 error 三个部分。data 放收藏记录，meta 放 next_cursor、has_more 等分页信息，发生错误时在 error 中返回稳定的错误码和可展示的提示。字段名称、时间格式、空值处理方式都应在接口文档中明确，前端不应根据提示文字猜测业务状态。
需要多人共享：必须单独设计权限和归属
团队书签、项目资料库或部门导航与个人收藏不同。此时不能只增加一个 is_public 字段就完成共享，因为“谁能查看、谁能新增、谁能编辑、谁能删除”通常并不相同。建议把收藏夹作为资源，配置 owner_id、成员关系或角色权限，并让每次操作经过资源级授权。
| 角色 | 可执行操作示例 | 需要确认的边界 |
|---|---|---|
| 所有者 | 管理成员、修改设置、删除收藏夹 | 所有权转移后原所有者是否保留编辑权限 |
| 编辑者 | 新增、修改、移动和删除收藏 | 是否允许删除他人创建的记录 |
| 查看者 | 查看列表和详情 | 是否允许复制、导出或查看备注 |
共享接口可在基础收藏接口上增加 folder_id 或 collection_id，但权限判断不能只放在前端。若一个用户失去共享文件夹权限，后端应立即拒绝后续读取和写入，并返回 403；资源不存在返回 404，参数格式错误返回 422，未登录或凭证失效返回 401，版本冲突返回 409。这样前端才能对不同问题采取重新登录、提示无权限或刷新数据等不同处理。
参数校验与返回结果应保持可预测
URL 校验建议只允许业务需要的协议，例如 http 和 https，并限制最大长度；是否允许端口、国际化域名、查询参数和片段标识，应根据产品规则测试后确定。title、note、tag 也应设定长度上限，避免超长输入影响数据库、列表布局或日志。服务端还要对 HTML、脚本片段和特殊字符进行合适的存储与输出处理，不能仅依赖前端校验。
新增成功可返回 HTTP 201 和完整记录；查询成功返回 HTTP 200；删除成功可返回 HTTP 204，或者返回统一的删除结果，但项目内应保持一种规则。错误响应至少应包含稳定 code、面向开发者的 message，以及可选的 field 字段。例如 url 不合法时指出 url，folder_id 不存在时指出 folder_id，便于表单准确定位问题。
开发验收应覆盖的关键流程
- 未登录用户不能访问需要身份的数据接口，登录用户不能读取其他用户的记录。
- 新增有效网址后，列表可以按文件夹、标签和关键词得到预期结果。
- 修改标题、备注或分类后，详情与列表中的 updated_at 保持一致。
- 删除记录后，普通列表不再返回；若启用同步机制，删除状态能被其他设备正确处理。
- 同一时间两次修改同一记录时，版本冲突不会静默覆盖较新的内容。
- 共享场景中分别测试所有者、编辑者和查看者，确认每个角色只拥有约定操作。
因此，网站收藏夹功能开发不只是制作一个“保存网址”按钮。先按个人、同步或共享场景确定边界，再固定数据字段、权限规则、分页方式、错误码和并发策略，才能让前端、后端及后续客户端围绕同一份接口契约稳定实现。
