MrleeAdmin/.windsurf/skills/frontend-web-api/SKILL.md

name, description, globs

name	description	globs
frontend-web-api	Web 前台 API 层规范（Nuxt 4），基于 $fetch 或 useFetch	frontend/web/app/api/**/*.ts frontend/web/app/apps/**/api/**/*.ts

文件位置

frontend/web/app/api/{module}/index.ts

代码模板

当前项目 Web 端统一通过 ~/utils/request 封装请求，自动处理 /api/ 基础路径、认证头、响应解包和错误提示：

import request from '~/utils/request'

export function get{Model}List(params: Record<string, any> = {}) {
  return request.get('/{module}/{model}', params)
}

export function get{Model}Detail(id: string | number) {
  return request.get(`/{module}/{model}/${id}`)
}

关键约定

• 优先使用 ~/utils/request，不要在业务 API 中直接使用 axios 或 $fetch
• 传给 request 的路径使用后端业务路径（如 /produce/process），由请求封装统一拼接 /api/
• 默认响应已解包为 data；需要完整响应时传递 { returnFullResponse: true }
• 上传使用 request.upload 并传入 FormData，不要在页面中重复实现认证和基础 URL 逻辑
• 错误由请求封装统一提示，业务层只处理状态和页面交互

检查清单

• 是否使用 $fetch/useFetch 而非 axios
• 路径是否以 /api/ 开头
• SSR 场景是否使用 useFetch
• 是否处理了请求错误