audit-fe-api

前端 API 审计技能

自由度：混合 — 步骤 0、1、3–6 为 [高自由度]；步骤 2 的 Sentry 查询和架构 SQL 为 [低自由度 — 必须严格执行]。

只读。展示发现；Phase 6 中的代码片段是建议采用的修复形式，不要在本次审计中修改代码。

推理方式

1. 观察 — 引用 FE 调用位置、BE 路由和响应／错误
2. 解读 — 契约是否匹配（路径、方法、参数、类型）？
3. 分类 — 路由缺失／不匹配／未类型化／缓存缺口／正确
4. 严重程度 — 生产环境中的 404／401／类型不匹配 = 严重；缓存／预取 = 改进机会

示例

观察： useUser 对 /api/users/${id} 发起 GET 请求；不存在 app/api/users/[id]/route.ts； Sentry 显示 14 天内出现 25 次 404。 解读： FE 调用了 BE 从未注册的路由。 分类： 路由缺失（严重）。 严重程度： 严重 — 必然返回 404。 发现： hooks/useUser.ts | GET /api/users/:id | 严重 | 不存在 BE 路由。

报告前自我检查 [低自由度 — 不要跳过]

1. 有证据支持 — 提供 FE 文件和 BE 路由或 Sentry 事件，而不是“可能是 500”
2. 依据契约，而非个人偏好 — staleTime 建议需要说明新鲜度方面的原因
3. 严重程度有依据 — 严重 = 生产环境中的契约已损坏
4. 责任归属正确 — 可复现的线上 4xx/5xx → debug-fe-be-integration；DB 结构 → audit-db-schema
5. 双方信息齐全 — 每处不匹配都列出 FE 文件和 BE 路径（或 NOT FOUND）

---

步骤 0：自动检测 API 层

0a. 检测前端技术栈

依赖	技术
@tanstack/react-query	TanStack Query (React Query)
swr	SWR
@reduxjs/toolkit with createApi	RTK Query
axios	Axios HTTP 客户端
ky	Ky HTTP 客户端
ofetch or $fetch	Nuxt/ofetch
@trpc/client	tRPC（类型安全 RPC）
graphql-request or @apollo/client	GraphQL
openapi-fetch or openapi-typescript	OpenAPI 类型化客户端

0b. 检测后端技术栈

Glob: **/app/api/**/route.ts → Next.js App Router API routes
Glob: **/pages/api/**/*.ts → Next.js Pages Router API routes
Glob: **/src/routes/**/*.ts → Express/Hono/Fastify routes
Glob: **/server/api/**/*.ts → Nuxt server routes
Glob: **/src/app.py → Flask/Django
Glob: **/main.go → Go backend

0c. 查找 API 服务文件

Glob: **/services/*api*.ts → API service files
Glob: **/services/*service*.ts → Service files
Glob: **/api/*.ts → API client files
Glob: **/hooks/use*.ts → Custom hooks (may contain API calls)
Glob: **/lib/api*.ts → API client config
Glob: **/features/*/api.* → Feature-specific API files

0d. 检测开发服务器端口

Grep: "dev" in package.json scripts → extract port (3000, 3001, 5173, 8080, etc.)
Grep: "PORT" in .env or .env.local

0e. 记录发现

API LAYER DISCOVERY:
- HTTP client: [axios/fetch/ky/ofetch]
- State management: [TanStack Query/SWR/RTK Query/none]
- API style: [REST/GraphQL/tRPC]
- Backend framework: [Next.js API routes/Express/Hono/etc.]
- API service files: [list paths]
- API hooks: [list paths]
- Dev server: http://localhost:[port]
- API docs: [path or URL if detected]

---

步骤 1：研究 API 最佳实践

1a. Context7 — 库文档

解析每个主要依赖（@tanstack/react-query、axios、zod），然后查询文档中的 “staleTime cacheTime retry error handling optimistic updates”。调用正文： references/research-calls.md §Context7。

1b. Firecrawl — 当前 API 模式

搜索 <FRAMEWORK> API integration best practices [current year]（限制 5 条，网页来源），然后针对下方每个主题各查询一次。调用正文：references/research-calls.md §Firecrawl。

主题	查询
缓存	<state library> caching strategy staleTime production
错误处理	<framework> API error handling patterns retry
类型安全	<framework> type-safe API client OpenAPI Zod
性能	frontend API request optimization batching deduplication

---

步骤 2：检查生产环境 API 错误（Sentry）

2a. 查找与 API 相关的生产环境错误

sentry:search_issues
{
 "organizationSlug": "<ORG_SLUG>",
 "query": "API errors 4xx 5xx fetch axios network from the last 14 days",
 "projectSlugOrId": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "limit": 25
}

2b. 查找最慢的 API 调用

sentry:search_events
{
 "organizationSlug": "<ORG_SLUG>",
 "projectSlug": "<PROJECT_SLUG>",
 "regionUrl": "<REGION_URL>",
 "dataset": "spans",
 "query": "span.op:http.client",
 "sort": "-span.duration",
 "limit": 15
}

2c. 与前端代码交叉核对

对于每个 Sentry 错误：识别端点，Grep FE 调用方，检查错误处理／重试／类型。

---

阶段 3：发现前端 API 调用

3a. 查找所有 API 调用

使用 Grep（不是 bash grep）：

Grep: pattern "fetch\(|axios\.|api\.(get|post|patch|put|delete)" glob "*.{ts,tsx,js,jsx}"
Grep: pattern "useQuery|useMutation|useInfiniteQuery|useSuspenseQuery" glob "*.{ts,tsx}"
Grep: pattern "createApi|injectEndpoints" glob "*.{ts,tsx}"

3b. 创建 API 调用清单

文件	函数／Hook	方法	端点	参数	使用方
services/user.ts	getUsers	GET	/api/users	page、limit	UserList.tsx
hooks/useUser.ts	useUser	GET	/api/users/:id	id	UserProfile.tsx

---

阶段 4：与后端进行验证

4a. 检查端点是否存在

Grep: pattern "<ENDPOINT_PATH>" glob "*.{ts,js,py,go,rb}" — in backend source

App Router：必须存在 app/api/<path>/route.ts。

4b. 检查参数是否正确

检查项	方法
是否发送必需参数	将 FE 调用参数与 BE 验证架构（Zod、Yup、Joi）进行比较
命名约定是否一致	FE 使用 camelCase，BE 使用 snake_case——检查是否存在转换
类型是否匹配	FE 发送字符串，但 BE 需要数字，反之亦然
请求体结构是否匹配	将 FE 请求体与 BE 预期架构进行比较

4c. 使用 Supabase MCP 验证架构

如果后端从 Supabase 读取数据，请验证 DB 架构是否符合前端预期：

supabase:execute_sql
{
 "query": "SELECT column_name, data_type, is_nullable FROM information_schema.columns WHERE table_name = '<TABLE>' ORDER BY ordinal_position"
}

将列和类型与 FE TypeScript 接口进行比较。

---

阶段 5：识别问题

严重问题

问题	影响	检测方法
端点不存在	404 错误	在后端中搜索路由——未找到
缺少必需参数	500/422 错误	将 FE 参数与 BE 架构进行比较
HTTP 方法错误	405 错误	FE 使用 GET，BE 需要 POST
缺少 Auth 标头	401 错误	检查 API 客户端拦截器
类型不匹配	运行时错误	对比 FE 接口与 BE 响应结构

警告

问题	影响	检测方法
参数名称不匹配	参数被静默忽略	比较 camelCase 与 snake_case
端点已弃用	未来可能失效	检查 BE 路由中的版本标记
缺少错误处理	UX 较差	useQuery 未处理错误状态
缺少加载状态	UX 较差	未检查 isLoading / isPending

优化机会

问题	影响	检测方法
重复请求	浪费带宽	多个组件使用相同的 queryKey
未配置缓存	UX 较慢	未设置 staleTime（默认为 0）
未批量处理请求	请求过多	列表中存在 N+1 查询模式
缺少预取	导航较慢	悬停/聚焦时未调用 prefetchQuery
无乐观更新	变更速度较慢	变更操作等待服务器响应

---

阶段 6：前端优化

6a. 缓存策略

• 根据数据的实际新鲜度需求设置每个查询的 staleTime（用户资料约 10 min，设置为 Infinity）；默认为 0 时，每次挂载都会重新获取数据。

const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => getUser(userId),
  staleTime: 1000 * 60 * 10, // User data: 10 minutes
});

6b. 乐观更新

• onMutate：取消正在进行的查询，使用 getQueryData 创建快照，使用 setQueryData 设置新值，并返回快照。
• onError：恢复快照；onSettled：使对应的 key 失效。

6c. 预取

• 在链接的 onMouseEnter/focus 上，使用与详情视图相同的 key 和 fn 调用 queryClient.prefetchQuery。

6d. 错误处理

• 设置 retry: 3，并使用指数递增的 retryDelay，上限为 30 s；按顺序渲染 isLoading、isError 和空状态分支。

6e. 响应验证（Zod）

• 仅定义一次架构，使用 type User = z.infer<...>，并在服务函数中调用 UserSchema.parse(response.data)。

6a–6e 的完整代码：references/fix-patterns.md。

---

输出模板

按顺序报告以下部分：标题（日期、框架、客户端、状态库）→ 生产环境错误摘要（Sentry）→ 严重问题 → 警告 → 优化机会（缓存、预取、批处理）→ API 清单（端点、方法、FE 文件、BE 路由、状态）→ 类型安全状态 → 已应用的研究结果 → 后续步骤清单。

完整模板：references/report-template.md。

---

相关内容

• debug-fe-be-integration — 根据 BE 日志实时复现 4xx/5xx
• audit-db-schema — 对比 FE 类型与 DB 列
• debug-sentry-monitor — 同一端点在生产环境中的错误量