企业官网建设流程全解析

• 文档
• 教程
• Vibe Coding
• 示例工程

导读：当应用从"能跑"走向"能用"，数据量和需求一起增长时，简单的 CRUD 接口会接连遇到"页面跳来跳去""500 条数据一次返回""想筛选想排序却不敢新建接口"等真实问题。本文以 vibe-vibe 教程第七章 7.1 节为核心，完整梳理接口进化的三个关键节点——嵌套 vs 扁平的数据组织、offset 与 cursor 两种分页、查询参数组合实现过滤排序，并结合仓库中demo-03-social-schema、demo-01-todo、demo-02-todo-auth的源码级实现，让你读完既能判断"这个页面到底要不要 API"，也能直接用文末 Prompt 模板让 AI 生成合格的进化版接口。

一、小明的电影详情页难题：一个页面该发几个请求？

小明"个人豆瓣"项目从第六章延续过来，数据库已经设计好——movies、directors、tags、movie_tags、ratings五张表，关系理清、约束加好，按第七章 7.0 节的 CRUD 模式跑通了增删改查。开始做页面时，第一个电影详情页就把他难住了：页面上要显示电影名、年份、海报、导演姓名、演员列表、用户评分、标签、简介，而这些信息分散在四五张表里。

最直觉的做法是前端一次发五个请求：

1. GET /api/movies/1→ 拿电影基本信息
2. GET /api/directors/5→ 拿导演信息
3. GET /api/movies/1/tags→ 拿标签列表
4. GET /api/movies/1/ratings→ 拿评分
5. GET /api/movies/1/actors→ 拿演员列表

能跑，但体验很糟糕：页面先出电影标题，过了半秒导演名字才冒出来，又过了一会儿标签才显示，评分最后才加载完——用户看到的是一个"跳来跳去"的页面。更要命的是，五个请求意味着五次网络往返，每次往返至少几十毫秒，加上服务器处理时间，用户要等好几百毫秒才能看到完整页面。如果用户网络不好（比如在地铁里），某个请求超时，页面就会缺一块——有标题没导演，有评分没标签。

先问自己：这个页面需要 API 吗？

这是一个很多新手会忽略的问题。在 Next.js 里，页面组件（page.tsx）本身就运行在服务器上，可以直接查数据库，根本不需要绕一圈走 API。如果详情页是一个 Server Component（默认就是），它可以直接在组件里调用 Drizzle 查询，把多张表的数据一次查好、渲染成 HTML 发给浏览器——整个过程没有任何"前端发请求→后端返回"的网络往返。

那 API Route 是给谁用的？两种场景：

• 前端需要动态交互时——比如用户点了"收藏"按钮，前端需要告诉后端"我要收藏这部电影"，这种用户触发的写操作需要调用后端逻辑；
• 外部消费者——比如第三方想用你的数据做小程序，需要一个可以调用的 HTTP 接口。

小明的详情页属于"打开页面就展示数据"，不需要用户交互触发，所以直接在 Server Component 里查数据库即可，不用写 API Route。

Server Action：不用写接口的写操作

你可能会发现，AI 生成的"收藏""点赞""提交表单"这类功能，代码里并没有app/api/xxx/route.ts文件，取而代之的是一个带'use server'标记的函数——这就是Server Action。它让前端可以直接调用一个运行在服务器上的函数，不需要手动定义 API 路由、不需要写fetch请求，对"用户点按钮→后端处理→返回结果"这类简单写操作比 API Route 更简洁。

你不需要指定用哪种方式。加载了next-best-practicesSkill 的 Claude Code 会自动判断——页面展示用 Server Component 直接查库，简单的写操作用 Server Action，需要给外部调用的接口用 Route Handler。看到代码里没有route.ts不用觉得奇怪，AI 可能选了更合适的方式。

不过，电影列表页的筛选、排序、翻页是用户交互触发的，前端需要根据用户操作动态请求不同数据，这种场景就需要 API。所以接下来讨论的分页、过滤、排序，都是针对需要 API 的场景。但即使是 API 场景，"一个页面发五个请求"的问题依然存在——小明后来给详情页加了"收藏""评论"功能，详情页变成了客户端交互页面，这时数据结构该怎么组织？这就引出了嵌套与扁平之争。

二、嵌套 vs 扁平：两种数据组织方式

假设前端需要电影信息和导演信息，后端可以有两种返回方式。

嵌套结构：一次请求返回所有关联信息

把关联数据"嵌"在主对象里，一次返回所有信息：

{ "id": 1, "title": "千与千寻", "year": 2001, "director": { "id": 5, "name": "宫崎骏", "nationality": "日本" }, "tags": ["动画", "奇幻", "冒险"], "rating": { "average": 9.4, "count": 2156 } }

前端直接用movie.director.name就能拿到导演名字，用movie.rating.average就能拿到评分，不用再发第二个、第三个请求，所有数据一次到位。

扁平结构：只返回 ID，前端按需再查

{ "id": 1, "title": "千与千寻", "year": 2001, "directorId": 5, "tagIds": [1, 3, 7], "averageRating": 9.4 }

前端拿到directorId: 5后，如果要显示导演名字，还得再调GET /api/directors/5；要显示标签名字，还得拿着tagIds去查标签表。

怎么选？看场景，而不是看偏好

一个实用的判断标准：前端拿到数据后，还需不需要再发请求才能渲染页面？如果需要，说明接口返回的数据不够，应该嵌套更多关联数据；如果前端拿到数据就能直接渲染，说明刚刚好。

源码佐证：多表关联的 JOIN 正是"嵌套"的地基

仓库中的社交应用示例 demo-03-social-schema/src/db/schema.ts 与电影库场景高度同构：posts（帖子）、users（用户）、comments（评论）、likes（点赞）、tags/postTags（标签及多对多关联表）五类实体，外键关系明确。要在"详情"类接口里返回嵌套数据，底层靠的就是联表查询——示例的 operations.ts 中，帖子列表用innerJoin(users, eq(posts.userId, users.id))把作者昵称"嵌"进每条帖子，advanced-queries.ts 更进一步，通过子查询把点赞数、评论数、粉丝数聚合后一并返回——这正是"嵌套结构"在 SQL 层的实现形态：在服务端把关联数据一次查齐，而不是让前端逐个请求。

跟 AI 说的时候，直接描述需求即可：

"电影详情接口需要同时返回导演信息、标签列表和平均评分，用嵌套结构，一个请求返回所有数据。电影列表接口只返回标题、年份、海报 URL 和平均评分。"

三、500 条记录一次全返回，页面卡死了：分页

详情页的问题解决了，小明开始做首页列表。一开始只有十几部电影，GET /api/movies返回一个数组，前端循环渲染，毫秒级完成，体验丝滑。然后他花了一个周末把自己看过的 500 多部电影全部录了进去——再打开首页，浏览器转了好几秒才显示出来。开发者工具显示：接口返回了一个巨大的 JSON，500 多条记录，光数据就有好几百 KB；前端要渲染 500 个电影卡片、几千个 DOM 节点，浏览器直接卡住。

这就像去图书馆借书，跟管理员说"把你们所有的书都搬出来给我看看"。正常人的做法是："先给我看科幻类的，一次看 20 本，看完了再拿下一批。"这就是分页。

偏移分页（offset/limit）：翻书模式

最常见的分页方式是偏移分页——告诉后端"跳过前面 N 条，给我接下来的 M 条"。

请求：GET /api/movies?page=3&limit=20

意思是：第 3 页，每页 20 条。后端跳过前 40 条（第 1、2 页），返回第 41-60 条。

• 优点：简单直观。前端可以直接显示页码导航："第 1 页、第 2 页、第 3 页……"，用户能点击任意页码跳转。淘宝、京东搜索商品时的底部页码栏用的就是这种分页。
• 缺点：翻到后面会变慢。数据库执行OFFSET 10000 LIMIT 20时，要先扫描前面 10000 条记录（虽然不返回）再取出你要的 20 条——每次都从头数，页数越深越慢。这个问题在第六章 6.3 节讲 OFFSET 分页陷阱时已经提过。

游标分页（cursor-based）：书签模式

另一种方式不用页码，而是用"书签"。

请求：GET /api/movies?cursor=eyJpZCI6NDB9&limit=20

意思是：从上次返回的最后一条记录之后，再给我 20 条。cursor是一个编码后的标记，指向上一页最后一条记录的位置。

• 优点：无论翻到第几页，速度都一样快——数据库直接从书签位置开始读，不需要扫描前面的记录。这也解释了为什么微博、朋友圈、抖音的 feed 都用无限滚动而不是页码分页。
• 缺点：不能跳页，只能"下一页、下一页"地往后翻，无法直接跳到第 50 页。

怎么选？

小明的电影库只有几百部，偏移分页绰绰有余。

源码佐证 1：仓库里的 offset/cursor 对比演示

仓库的 demo-03-social-schema/src/pagination.ts 用同一份数据源做了两种分页的逐页演示与对比总结：

• Offset 分页的 SQL 形态是SELECT * FROM posts ORDER BY id LIMIT 2 OFFSET 0，Drizzle 写法为.limit(PAGE_SIZE).offset(page * PAGE_SIZE)；
• Cursor 分页的 SQL 形态是SELECT * FROM posts WHERE id > cursor ORDER BY id LIMIT 2，Drizzle 写法为.limit(PAGE_SIZE + 1)配合.where(gt(posts.id, cursorVal))，通过多取 1 条判断hasMore，再以最后一条的id作为下一页游标。

对比表把两者的取舍写得很直白：Offset 实现复杂度"简单"、大数据性能"差（全表扫描）"、支持跳页、数据变动时"可能重复/遗漏"；Cursor 实现"中等"、大数据性能"好（索引查找）"、不支持跳页、数据一致性"稳定"。

源码佐证 2：生产级 cursor 分页的完整实现

demo-02-todo-auth/src/app/api/todos/route.ts 给出了一个可直接照搬的 GET 实现骨架，关键点有三：

1. limit 上限保护：Math.min(Number(searchParams.get('limit') || '20'), 50)——默认每页 20 条，且强制不超过 50，防止客户端一次拉走全表；
2. 游标条件：if (cursor) conditions.push(lt(todos.id, Number(cursor)))，配合.orderBy(desc(todos.id))保证游标单调递减、不重不漏；
3. hasMore 探测：.limit(limit + 1)多取一条，items.length > limit即还有下一页，随后items.pop()把探测用的那条弹掉，响应里返回{ items, nextCursor: hasMore ? items[items.length - 1].id : null }——nextCursor为空就是没有更多数据了。

与之对应的前端消费侧在 demo-02-todo-auth/src/lib/queries.ts 的useTodosInfinite中：useInfiniteQuery的queryFn用URLSearchParams拼limit=20和cursor，getNextPageParam: (lastPage) => lastPage.nextCursor把上一页的nextCursor自动变成下一页的请求参数——这正是无限滚动列表的完整闭环。

分页响应该带什么

光返回数据不够，前端还需要知道"一共多少条""当前第几页""还有没有下一页"，否则不知道该显示几个页码按钮，也不知道"下一页"按钮该不该灰掉。一个好的分页响应长这样：

{ "success": true, "data": [ { "id": 1, "title": "千与千寻", "year": 2001, "rating": 9.4 }, { "id": 2, "title": "龙猫", "year": 1988, "rating": 9.2 }, { "id": 3, "title": "天空之城", "year": 1986, "rating": 9.1 } ], "meta": { "total": 500, "page": 1, "limit": 20, "totalPages": 25 } }

meta让前端知道：总共 500 条，当前第 1 页，每页 20 条，一共 25 页，据此渲染页码栏并在最后一页禁用"下一页"按钮。

游标分页的响应略有不同：不返回total和totalPages（因为计算总数本身就是一次全表扫描，很慢），而是返回一个nextCursor。前端拿着 cursor 请求下一页，nextCursor为空说明没有更多数据了。

跟 AI 说：

"电影列表接口加上分页，用 offset/limit 方式，默认每页 20 条。响应里带上总数和总页数，方便前端显示页码导航。"

四、想按标签筛选、按评分排序：查询参数的组合艺术

分页搞定，小明又有了新需求。朋友问"能不能只看动画片？"另一个朋友问"能不能按评分从高到低排？"小明纠结：是给每种筛选条件都建一个新接口？GET /api/movies/animation、GET /api/movies/top-rated？那如果又要按标签筛选又要按评分排序呢？再建一个GET /api/movies/animation/top-rated？排列组合下来，接口数量会爆炸。

老师傅说：不用建新接口，一个列表接口，用查询参数组合就行。

GET /api/movies?tag=动画&sort=rating&order=desc&page=1&limit=20

这一个请求就表达了："给我标签是'动画'的电影，按评分从高到低排，第 1 页，每页 20 条。"

查询参数的好处是可以自由组合，就像乐高积木：

• 只想排序不想筛选？GET /api/movies?sort=rating&order=desc
• 只想筛选不想排序？GET /api/movies?tag=动画
• 想同时按多个标签筛选？GET /api/movies?tag=动画&tag=日本
• 什么都不传？GET /api/movies返回默认排序的全部数据（带分页）

接口只有一个，前端根据用户操作拼不同参数——用户在筛选栏选了"动画"，前端加上tag=动画；用户点了"按评分排序"，前端加上sort=rating&order=desc。接口代码不用改，所有组合都自动支持。

常见的查询参数设计

这些参数都应该是可选的。不传就用默认值——默认不筛选、默认按创建时间倒序、默认第 1 页每页 20 条。这样既灵活又不会破坏已有的调用方式。

源码佐证：仓库里"参数组合 + 可选参数"的真实写法

demo-01-todo/src/app/api/todos/route.ts 的 GET 正是这套设计的落地范例：从searchParams读出category与status，先收集条件再统一where(and(...conditions))——category有值且不等于'all'时加eq(todos.category, category)，status为'active'/'completed'时加eq(todos.completed, false/true)，都不传就返回全量默认排序。条件不匹配时直接跳过，天然实现了"所有参数可选、向后兼容"。

前端一侧的封装在 demo-01-todo/src/lib/queries.ts 的useTodos中：用URLSearchParams仅在有值时才params.set('category', category)，再拼到/api/todos?${params}——接口代码不动，筛选条件随用户操作动态追加。而 demo-02-todo-auth/src/app/api/todos/route.ts 里的priority过滤（if (priority && priority !== 'all')）则展示了如何在游标分页的conditions数组里叠加过滤条件——过滤与分页、排序在同一条链路上天然共存。

搜索和筛选是两回事

筛选（Filter）是精确匹配——"标签等于动画""年份等于 2024"，用数据库的 WHERE 条件即可；搜索（Search）是模糊匹配——"标题里包含'千与千寻'"，可能还需要全文索引。两者可以组合使用，但实现方式不同。对小明的电影库，简单的LIKE '%关键词%'搜索就够了；数据量大到几十万条才需要考虑 PostgreSQL 的全文搜索——先跑起来再优化。

跟 AI 说：

"电影列表接口支持以下可选查询参数：tag（按标签过滤）、year（按年份过滤）、q（按标题搜索）、sort（排序字段，支持 rating/year/createdAt）、order（asc 或 desc）。所有参数都是可选的，不传就返回默认排序的全部数据。"

五、小明的接口进化之路

回顾小明的电影列表接口是怎么一步步进化的：

每一次进化都是被真实需求推动的——不是提前设计好的，而是用着用着发现不够用，然后加功能。这也是 API 设计的常态：先做最简单的版本，遇到问题再迭代，不需要一开始就设计一个"完美"的接口。仓库里三个 demo 恰好印证了这条路径：demo-01-todo是 V1/V2 阶段的"分页 + 基础过滤"，demo-02-todo-auth是带鉴权、游标分页、无限滚动的进阶形态，demo-03-social-schema则是围绕多表关联做查询能力演示的"重型"样本——每一层都是在上一版基础上按需长出来的。

六、跟 AI 沟通的 Prompt 模板

把上面学到的概念组合起来，你可以用一段话描述一个完整的接口需求。

从零设计接口时：

"帮我设计电影列表和详情两个接口。列表接口支持分页（offset/limit，默认每页 20 条）、按标签过滤、按评分或年份排序，响应里带上总数和总页数。详情接口返回电影信息，嵌套导演信息、标签列表和平均评分。统一用{ success, data, error }格式返回。"

给已有接口加功能时：

"现有的GET /api/movies只返回全部数据，帮我加上分页和过滤功能。分页用 query 参数 page 和 limit，过滤支持按 tag 和 year 筛选，排序支持 sort 和 order 参数。所有新参数都是可选的——不传这些参数时行为跟之前一样，保持向后兼容。"

让 AI 自查时：

"检查一下现有的电影列表接口，有没有以下问题：1）是否支持分页？2）查询参数是否都做了类型校验（比如 page 必须是正整数）？3）排序字段是否限制了允许的值（防止用户传入任意列名）？"

需要说明的是，参数校验正是仓库接口的标准动作：例如 demo-02-todo-auth/src/app/api/todos/route.ts 用 zod 的safeParse校验请求体、对id做Number.isFinite(numId) && numId > 0的数值校验，demo-03-social-schema/src/validated-operations.ts 则演示了用drizzle-zod从数据库 schema 自动生成校验规则、再由safeParse返回结构化结果而不抛异常——把"page 必须是正整数、排序字段白名单"这类要求写进 Prompt，AI 就能产出同样健壮的代码。

七、让 AI 自动优化性能：加载 Skills

当 API 代码越来越复杂时，可能会不知不觉引入性能问题——比如数据瀑布流（一个请求等另一个请求完成）、不必要的重渲染、Bundle 过大等。推荐加载这两个 Skills，让 AI 写代码时自动遵循最佳实践：

• vercel-react-best-practices——React/Next.js 性能优化（消除瀑布流、Bundle 优化、重渲染优化）；
• next-best-practices——Next.js 文件约定、RSC 边界、异步 API、路由处理、元数据。

这两个 Skills 通常已内置在 Claude Code 中，会在使用 React 或 Next.js 时自动加载，帮你避开常见的性能陷阱。

八、小结与下一步

本文围绕 vibe-vibe 教程的接口进化主线，走完了完整链路：先判断页面是否真的需要 API（Server Component 直接查库、Server Action 写操作、Route Handler 对外）→ 用嵌套结构消灭"一页五请求"→ 用 offset/cursor 分页解决数据量膨胀 → 用查询参数组合支撑筛选与排序。每一条都配有仓库源码（pagination.ts、todos route、demo-01 GET 实现）作为可复制的落地模板，文末的 Prompt 模板则可直接拿去和 AI 对话。

接口能查能筛了，但上线后会遇到新问题——有人提交空数据、重复点击、服务器突然 500。下一步可以阅读 「当接口出了问题」 学习参数校验、幂等与错误处理；想回顾本章从零搭建 CRUD 的完整过程，可回看 「7.0 构建并运行第一个全栈应用」；本章更完整的上下文见 第七章章节目录。

• 文档
• 教程
• Vibe Coding
• 示例工程