[!info] related notes

• 所属 MOC:
• 相关概念:
• 易混淆概念:
• 相关资源:

Next.js Route Handler 与 Server Component 的边界

覆盖范围

这篇笔记回答 Next.js App Router 中一个非常容易写错的边界：

同一份业务能力，什么时候由 Server Component 直接调用内部 Service，什么时候应该通过 route.ts 暴露 HTTP Endpoint？

核心不是“Server Component 和 Route Handler 都能访问数据库，所以任选一个”，而是区分：

内部服务器调用
vs
跨 HTTP 边界调用

两条不同路径

Server Component

Server Component
      ↓
Application / Service
      ↓
Repository / Owning Service

它已经运行在服务器内部，不需要为了访问同一应用的业务函数再人为制造一次 HTTP 请求。

Route Handler

HTTP Client
   ↓
Route Handler
   ↓
Application / Service
   ↓
Repository / Owning Service

它存在的意义就是建立 HTTP contract。

为什么 Server Component 不应调用自己的 Route Handler

不推荐：

Server Component
      ↓
fetch("/api/goals")
      ↓
Route Handler
      ↓
goalService
      ↓
DB

如果 Server Component 与 Route Handler 属于同一个 Next.js 应用，这相当于：

server
→ HTTP serialize
→ network/runtime boundary
→ parse HTTP
→ same server

相比直接：

Server Component
→ goalService.listForUser()

多出了：

• HTTP 编解码
• URL / Method contract
• 网络或 runtime hop
• 重复错误映射
• 额外 tracing / failure point
• 某些预渲染/构建场景的可用性问题

所以这里并不是典型的“Request Waterfall 多一个独立请求”，更准确地说是无必要地增加了一层 HTTP transport hop。

共享 Service，而不是共享 HTTP

正确复用方式：

                Server Component
                    ↓
               goalService
                    ↑
                Route Handler
                    ↑
                 Browser

代码结构：

// application/goals.ts
export async function listGoalsForUser(userId: string) {
  return goalRepository.listForUser(userId)
}

Server Component：

export default async function GoalsPage() {
  const user = await requireUser()
  const goals = await listGoalsForUser(user.id)

  return <GoalList goals={goals} />
}

Route Handler：

export async function GET() {
  const user = await requireUser()
  const goals = await listGoalsForUser(user.id)

  return Response.json({ data: goals })
}

复用的是 application/service capability，不是让内部调用绕公开 HTTP Endpoint。

Client Component 为什么不同

Client Component 运行在浏览器，需要跨越浏览器 → 服务器边界：

Client Component
      ↓ HTTP
Route Handler
      ↓
Service

例如用户点击“刷新通知”：

Browser interaction
→ GET /api/notifications
→ Route Handler
→ notificationService

这是合理的，因为浏览器无法直接：

import { notificationService } from "server-only-module"

因此：

Server-side caller
→ direct function/service call

Browser / external caller
→ HTTP Route Handler

Route Handler 的消费者是谁

Route Handler 更自然的消费者包括：

Client Component
TanStack Query / SWR
Mobile App
Desktop App
Third-party system
Webhook sender
curl / automation

Server Component 如果只是读取同一应用内部能力，通常不属于这组消费者。

与独立后端服务的区别

如果真正的数据 owner 是独立 Go Backend：

Next.js Server Component
        ↓ HTTP
BodySense Go API
        ↓
Go Service

这个 HTTP hop 是合理的，因为它跨越的是真实服务边界。

不要混淆：

Server Component → 自己的 Next Route Handler
≠
Server Component → 独立 Owning Service API

前者通常是多余 transport；后者可能是系统架构本身要求的边界。

这继续遵守 数据所有权与服务边界：先问谁拥有业务规则，再决定调用路径。

MemoFlow 场景

如果 MemoFlow 的 Goal 业务本来就在当前 Next.js 应用：

/goals 首屏
→ Server Component
→ goalService.listForUser()

如果浏览器运行期需要刷新：

Client
→ /api/goals
→ Route Handler
→ same goalService.listForUser()

两个入口可以共享 Service，却服务于不同调用环境。

与 Server Action 的初步边界

完整 Server Action 放在下一专题学习。此处只建立第一层区别：

Route Handler
→ explicit HTTP endpoint
→ URL + HTTP method
→ external client 可调用

Server Action
→ React 应用内部调用服务器函数的 mutation mechanism
→ 更贴近 UI / form interaction

因此不要看到“客户端要触发服务器逻辑”就默认一定要建 /api/*；React 应用内部 Mutation 在很多场景可以由 Server Action 承担。

决策表

调用方	目标	更自然的边界
Server Component	同应用 Service	直接函数调用
Server Component	独立 Go/Python Service	HTTP/gRPC Service API
Client Component	获取服务器数据	Route Handler / HTTP API
Mobile/Desktop	调 Next.js Backend	Route Handler
Stripe/CMS	Webhook 通知	Route Handler
React Form	内部 Mutation	Server Action 常常更自然，具体见后续专题

最短记忆

内部 server call
→ share Service
→ 不要 share HTTP

跨 runtime / 跨系统
→ HTTP boundary
→ Route Handler