| name | static-to-api-layer |
| description | 静态页面 API 化改造工具：自动发现页面中的隐式数据接口需求，改造页面为标准 API 调用并预留 Mock/真实接口切换层。不负责 contract/mock/docs 产物生成。 |
Static to API Layer
从静态前端页面出发，聚焦 发现隐式接口需求 → 页面 API 化改造 → 统一请求层 → 切换层预留。
适用场景
- 前端先行开发，数据硬编码在
mock.js / 页面 data / useState / constants 中
- HTML Demo 转换而来的项目，需要正式化为接口驱动
- "先画页面再开发后端"的工作模式
- 作为
api-extractor-pro 的前置工程化改造
支持框架：React / Vue / 微信小程序
职责边界（强制）
本 skill 只做页面和调用层改造，不生成接口治理产物：
- ✅ 做：隐式接口发现、API 封装层生成、页面改造、Mock/真实接口切换层
- ✅ 做（小程序例外）：小程序不支持 MSW，由本 skill 提供
wx.request 拦截式 Mock 方案
- ❌ 不做：
contract.json、openapi.yaml、接口文档、一致性报告
接口治理产物（contract/OpenAPI/文档/校验）统一由 api-extractor-pro 生成。
小程序 Mock 数据由本 skill 的 mock-interceptor-wx.js 模板提供，因 MSW 在小程序中不可用。
四阶段工作流
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│1. Discover │───▶│2. Refactor │───▶│3. API Layer│───▶│4. Switch │
│隐式接口发现 │ │页面改造 │ │统一请求封装 │ │切换层预留 │
└────────────┘ └────────────┘ └────────────┘ └────────────┘
启动流程
收到用户请求后，按以下步骤启动：
- 确认项目路径：询问或确认前端项目根目录
- 识别框架类型：自动检测项目框架（React / Vue / 微信小程序）
- React：
package.json 含 react，目录结构含 src/components / src/pages
- Vue：
package.json 含 vue，目录结构含 src/views / src/components
- 微信小程序：存在
app.json + project.config.json，页面为 .wxml + .wxss + .js
- 扫描范围：默认扫描所有页面和数据文件，用户可指定范围
- 进入阶段 1
阶段 1：隐式接口发现（Discover）
目标：扫描项目中所有页面和数据文件，识别隐式数据接口需求
1.1 需要识别的 7 类接口模式
| # | 接口模式 | 识别特征 | 转化目标 |
|---|
| 1 | 列表查询 | 硬编码数组 const LIST = [...]，页面 data 中直接赋值列表 | GET /api/xxx/list |
| 2 | 详情查询 | getXxxById(id)、find(x => x.id === id)、URL 参数取 id | GET /api/xxx/:id |
| 3 | 条件筛选 | .filter()、selectedCategory、条件分支渲染 | GET /api/xxx/list?key=value |
| 4 | 分页加载 | .slice(0, n)、loadMore、page/pageSize 变量 | GET /api/xxx/list?page=1&pageSize=10 |
| 5 | 表单提交 | handleSubmit() 仅有 Toast/alert 无真实请求 | POST /api/xxx |
| 6 | 状态变更 | handleApprove()/handleReject()/handleDelete() 等操作 | PUT /api/xxx/:id/action |
| 7 | 聚合统计 | STATS_* 统计数据、图表数据源 | GET /api/stats/xxx |
1.2 各框架识别特征
| 特征 | React | Vue | 微信小程序 |
|---|
| 数据声明 | useState([...]) / const data = [...] | data() { return { list: [...] } } | Page({ data: { list: [...] } }) |
| 数据加载 | useEffect(() => {...}, []) | mounted() / onMounted() | onLoad() / onShow() |
| 表单提交 | onSubmit / handleSubmit | @submit / methods.submit | bindsubmit / handleSubmit |
| 无效请求标志 | alert('成功') / console.log | ElMessage.success / this.$message | wx.showToast({ title: '成功' }) |
| 数据文件 | mock.js / data.ts / constants.ts | mock.js / data.js | mock.js / 页面 js 内硬编码 |
1.3 附加检测
- 字典/配置数据：分类列表、枚举值、菜单配置 →
GET /api/config/xxx
- 文件上传意图：图片选择器、
wx.chooseImage、<input type="file"> → POST /api/upload
- 用户信息/鉴权意图：用户数据硬编码、登录表单 →
GET /api/user/profile / POST /api/auth/login
1.4 输出
生成 discovery_report.md（参考 templates/discovery-report.md），包含：
- 项目概览（框架、目录结构、页面数量）
- 数据源清单（文件路径 + 数据名 + 数据结构摘要）
- 数据使用映射（哪些页面使用了哪些数据，使用方式）
- 隐式接口需求列表（模式分类 + 推断 endpoint）
阶段 2：页面改造（Refactor）
目标：将页面中的硬编码数据源替换为 API 调用
2.1 页面改造规则
- 移除所有 mock 数据导入（
require('...mock') / import ... from '../mock'）
- 替换为 API 模块导入
- data 初始值改为空（
[] / null / {}）
- 添加
loading 状态（为异步加载做准备）
- 生命周期中改为 API 调用（
onLoad / useEffect / mounted）
- 添加错误处理（
catch → 错误提示 Toast）
- 表单提交改为 POST 请求
- 操作动作改为 PUT/DELETE 请求
- 确保改造后功能不变（数据展示与交互行为保持一致）
阶段 3：统一 API 封装层（API Layer）
目标：生成统一请求基础层 + 模块 API 文件
3.1 产物结构
api/ （或 src/api/）
├── request.js ← 请求封装基础层（含 Mock 切换）
├── resource.js ← 资源模块 API
├── audit.js ← 审核模块 API
├── stats.js ← 统计模块 API
└── config.js ← 配置 API
3.2 请求封装模板
- 微信小程序：
templates/request-wx.js
- React/Vue (Axios)：
templates/request-axios.js
- React (Fetch)：
templates/request-fetch.js
阶段 4：Mock ↔ 正式接口切换层（Switch）
目标：预留一键切换机制，后续联调时无需改动页面代码
4.1 切换架构
页面代码（不改动）
↓ 调用
api/resource.js（不改动）
↓ 调用
api/request.js（改这里）
↓ 根据配置
┌────────────────┐
│ IS_MOCK=true │──→ 项目现有 Mock 方案
│ IS_MOCK=false │──→ 真实 HTTP 请求
└────────────────┘
4.2 request.js 中的切换点
微信小程序：
const config = {
IS_MOCK: true,
baseURL: '',
}
React/Vue：
const IS_MOCK = import.meta.env.VITE_API_MODE === 'mock'
输出产物清单
| 产物 | 路径 | 说明 |
|---|
| 数据发现报告 | discovery_report.md | 隐式接口需求分析结果 |
| 请求封装 | api/request.js | 统一请求层，含 Mock 切换 |
| API 模块 | api/[module].js | 按模块分组的 API 函数 |
| 改造后页面 | 原页面文件 | 替换为 API 调用 |
与 api-extractor-pro 的衔接（顺序固定）
1) static-to-api-layer
- 完成页面 API 化改造
- 不生成 contract/mock/docs
2) api-extractor-pro
- 从改造后的 API 调用中扫描并生成 contract
- 统一生成 Mock、OpenAPI、文档、校验和变更报告
强制规则
- 仅做页面 API 化改造，不生成接口治理产物
- 改造后页面行为必须与改造前一致
- API 函数命名语义化（
getList / getById / create / update / delete）
- 不确定字段标记为
x-todo-confirm
- 改造前建议先提交版本，支持渐进式按模块改造
参考资料
- 请求封装模板（微信小程序）：
templates/request-wx.js
- 请求封装模板（Axios）：
templates/request-axios.js
- 请求封装模板（Fetch）：
templates/request-fetch.js
- 小程序 Mock 拦截器模板：
templates/mock-interceptor-wx.js
- 数据发现报告模板：
templates/discovery-report.md
- 改造前后对比示例：
examples/before-after.md
