用途
本资料描述了一套结构化的数据获取架构，用于在服务端组件与客户端组件之间采用不同的数据获取方式。其目标是统一项目中的数据流模式，明确服务端与客户端各自的职责与调用路径。
核心原则
- 服务端组件直接调用服务端函数。
- 客户端组件使用 TanStack Query 从 API 路由获取数据。
- API 路由使用 apiRouteWrapper 包装服务端函数。
- 客户端组件的变更（mutation）直接调用服务端函数。
- TMDB API 使用从 tmdb-server-functions.ts 自动生成的服务端函数。
服务端组件
服务端组件可以直接 await 服务端函数。示例中从 @/utils/tmdb-server-functions 导入 discoverMovies，在服务端组件内直接 await discoverMovies({ page: 1, with_genres: "28" })，也可以 await 自定义的 serverFunction。要点是在服务端组件中直接使用 await，并从 @/utils/tmdb-server-functions 调用 TMDB 服务端函数。
客户端组件与 API 路由
客户端组件使用 TanStack Query 调用 API 路由，API 路由再包装服务端函数。
第一步：创建 API 路由。API 路由使用 apiRouteWrapper 包装服务端函数。例如在 src/app/api/tmdb/discover-movies/route.ts 中导入 apiRouteWrapper 与 discoverMovies，并导出 export const GET = apiRouteWrapper(discoverMovies);。对于自定义服务端函数，可写成 export const GET = apiRouteWrapper(async (params) => { return myServerFunction(params); });。
第二步：从客户端组件调用。使用 TanStack Query 配合 apiRequestWrapper。示例中在 "use client" 组件内使用 useSuspenseQuery，queryKey 形如 [{ scope: "movies", page: 1, with_genres: "28" }]，queryFn 调用 apiRequestWrapper("/api/tmdb/movie-list", { page: 1, with_genres: "28" })；另一个示例 queryKey 为 [{ scope: "someApiRoute" }]，queryFn 调用 apiRequestWrapper("/api/some-api-route", { foo: "bar" })。
客户端组件的变更（Mutations）
对于变更操作，客户端组件直接调用服务端函数，无需 API 路由。示例中在 "use client" 组件内使用 useMutation，mutationFn: updateMovie，并通过 mutation.mutate({ id: 1, title: "New Title" }) 触发更新。
TMDB API 集成
TMDB 服务端函数从 src/_generated/tmdb-server-functions.ts 自动生成。重要提示：这些函数是自动生成的，不要手动编辑；使用 pnpm codegen:tmdb 重新生成。可从 @/utils/tmdb-server-functions 导入 discoverMovies、getMovieDetails、searchMovies 等函数。服务端组件用法为 await discoverMovies({ page: 1, with_genres: "28" })；为客户端组件提供的 API 路由可写成 export const GET = apiRouteWrapper(discoverMovies);。
模式总结
- 服务端组件数据流：服务端组件 → 服务端函数 → 外部 API/数据库。
- 客户端组件数据流（查询）：客户端组件 → TanStack Query → API 路由 → 服务端函数 → 外部 API/数据库。
- 客户端组件数据流（变更）：客户端组件 → TanStack Query Mutation → 服务端函数 → 外部 API/数据库。
最佳实践
- 服务端组件：直接使用 await 调用服务端函数。
- 客户端查询：使用 TanStack Query + API 路由。
- 客户端变更：直接调用服务端函数。
- TMDB：使用自动生成的函数，绝不手动编辑。
- API 路由：使用 apiRouteWrapper。
- 客户端请求：使用 apiRequestWrapper。
常见错误
- 在服务端组件中调用 API 路由（应直接使用服务端函数）。
- 在客户端组件中直接使用 fetch（应使用 TanStack Query）。
- 手动编辑 tmdb-server-functions.ts（应使用 pnpm codegen:tmdb 重新生成）。
- 为变更操作创建 API 路由（应直接调用服务端函数）。
适用场景与限制
该模式适用于同时使用服务端组件与客户端组件、并采用 TanStack Query 与 API 路由进行数据获取的项目，尤其是需要集成 TMDB API 的场景。资料未提供具体框架版本、依赖安装步骤、错误处理细节、缓存策略或性能数据，这些内容暂未提供。