第9节：前端工程与一键启动

AI编程企业级实战

上一节：第8节：工程初始化-后端骨架与公共基础设施

本节：第9节：前端工程与一键启动

下一节：待更新

上一节，我们已经把 Hify 的后端骨架、公共基础设施和工程底座搭起来了。但对一个真正能继续往下开发的项目来说，只有后端能跑还远远不够。

你还需要把前端工程搭起来，把请求链路打通，把页面壳子立住，最后验证"一键启动"不是脚本看起来执行了，而是前后端真的能联通。

这也是这一节要解决的问题。

很多人做前端初始化时，容易一上来就陷进细节：UI 框架怎么选、目录怎么分、状态管理要不要上、页面先写哪个。结果看起来做了很多，真正能验证"项目已经启动起来"的关键链路反而迟迟没有闭环。

我这次还是延续前面几节的方法：不追求一口气做完，而是按依赖关系拆成几个最小可验证步骤。

对 Hify 的前端工程，我把它拆成了三步：

• 先搭项目骨架

• 再封装统一请求层

• 最后补路由和页面空壳，并做前后端联通验证

这样做的好处是，每一步都能验收，每一步都能让 Claude Code 在一个清晰边界内完成工作，而不是一条指令把所有事情搅在一起。

第一步：先把前端项目骨架搭起来

前端工程的第一步，不是直接写业务页面，而是先把运行底座搭好。包括技术栈、目录结构、开发代理和基础依赖，这些都属于"后面所有页面都要踩在上面"的部分。

我给 Claude Code 的指令思路是：

初始化 Hify 前端项目 hify-web。Vue 3 + TypeScript + Vite + Element Plus。目录结构按 CLAUDE.md 中定义的前端结构来。Vite 开发服务器配置代理：/ api 请求转发到 localhost :8080。

这个提示词看起来不长，但信息其实给得很够：

• 项目名明确

• 技术栈明确

• 目录规范来源明确

• 联调代理规则明确

这几项一旦说清楚，Claude Code 生成出来的前端初始工程通常就比较稳定，不太会跑偏。

Figure 1: Claude Code 生成前端工程骨架

Figure 2: Vite 代理与基础目录结构配置

这里最值得注意的，不是"Vue 3 + Vite"这些常规选型本身，而是代理配置。

因为只要前端开发服务器把 /api 正确转发到 localhost:8080，后面你在页面里调接口时，就不用在业务代码里写满后端地址，也不会一开始就被跨域问题打断节奏。这个小配置，决定了你后续联调是不是顺畅。

所以这一步的验收标准其实很简单：

• 前端工程能启动

• 目录结构符合项目规范

• /api 代理已经指向后端服务

做到这里，才算前端地基打稳了。

第二步：封装统一的 axios 请求层

项目骨架起来之后，下一步我不会马上写页面，而是先把请求层收口。

原因很简单：后端已经定了统一响应格式 Result<T>，前端如果不在这里统一处理，后面每个页面、每个 API 文件都会重复写一遍错误判断、消息提示和 data 解包。

后端这边返回的是这种结构：

{ "code": 200, "message": "success", "data": {} }

如果前端不做统一封装，那么后面所有业务代码都会越来越啰嗦。

我给 Claude Code 的指令思路是：

在 hify-web/src/utils/ 下创建 request.ts，封装 axios 实例。baseURL 设为 /api。响应拦截器里判断 code：200 直接返回 data 字段，非 200 用 Element Plus 的 ElMessage.error 提示 message，然后 reject。导出 get、post、put、del 四个方法。

Figure 3: 统一请求层 request.ts 生成结果

为什么我会特别要求"在拦截器里自动解包 data"？

因为如果不这么做，后面每次调接口都要多写一层：

const result = await providerApi.getList() const list = result.data

封装之后，业务层就可以直接拿到真正的数据：

const list = await providerApi.getList()

别小看这个细节。一个接口时没感觉，几十个接口之后，代码的整洁度和可读性差异会非常明显。

来看当时生成的 request.ts，核心逻辑是这样的：

import axios from 'axios' import { ElMessage } from 'element-plus' const instance = axios.create({baseURL: '/api',timeout: 60000, }) instance.interceptors.response.use((response) => {const { code, message, data } = response.data if (code !== 200) {ElMessage.error(message || '请求失败')return Promise.reject(new Error(message)) }return data },(error) => {ElMessage.error(error.message || '网络异常')return Promise.reject(error) } ) export const get = <T>(url: string, params?: object): Promise<T> => instance.get(url, { params }) export const post = <T>(url: string, data?: object): Promise<T> => instance.post(url, data) export const put = <T>(url: string, data?: object): Promise<T> => instance.put(url, data) export const del = <T>(url: string): Promise<T> => instance.delete(url)

这段代码里真正要关注的点只有三个：

• baseURL 固定为 /api，和前面的代理规则对上

• 响应拦截器统一处理 code/message/data

• 业务侧只使用封装后的 get/post/put/del

只要这三件事做对了，后面 API 层和页面层会轻很多。

接着，我让 Claude Code 基于这个封装写了一个最小 API 文件，用来验证整条链路是否成立。

提示词是：

在 hify-web/src/api/ 下创建 health.ts，用封装好的 request 调用 GET /api/v1/health。导出 getHealth 方法。

Figure 4: 健康检查 API 封装示例 health.ts

生成出来的代码很简单：

import { get } from '@/utils/request' export const getHealth = () => get<string>('/v1/health')

这个文件虽然只有几行，但它验证的是整条链路：

• axios 封装是否可用

• 接口路径规范是否统一

• Vite 代理是否能把请求转到后端

所以它不是"随手写个示例"，而是一个非常有效的早期验收点。

第三步：补上路由和页面空壳

请求层打通之后，前端工程还差最后一块最小闭环：页面骨架。

这一步我也不会让 Claude Code 一口气生成复杂业务页面，而是只让它先把"结构"搭起来。原因很简单，结构先有了，后面填业务内容才不会乱。

我给它的指令是：

在 hify-web 中配置 Vue Router，创建以下路由和对应的空壳页面组件：模型管理、Agent 管理、对话。每个空壳页面只显示页面名称，比如 ProviderList.vue 里就一行"模型提供商管理"。再创建一个 App.vue 布局：左侧 Element Plus 菜单栏，三个菜单项对应三个路由，右侧内容区用 router-view。

Figure 5: Vue Router 路由与页面空壳生成结果

Figure 6: 左侧菜单加右侧内容区的基础布局

这一步的核心，不是页面长什么样，而是先把后续业务开发会反复依赖的三个东西固定下来：

• 路由组织方式

• 页面目录落点

• 整体布局骨架

这样后面无论是模型管理、Agent 管理还是对话页面，Claude Code 都能在一个已经成型的结构里继续工作，而不是每次都从零拼页面。

对个人开发者来说，这种"先搭空壳再填内容"的方式尤其重要。因为它能让你尽快看到项目的形状，而不是一直停留在一堆零散文件上。

最关键的一步：验证前后端真的联通了

前面三步做完，前端工程其实已经具备继续往下开发的能力了。但如果要说"这一节真正完成了"，还差最后一个动作：联通验证。

因为一键启动真正要验证的，不是脚本有没有执行，也不是浏览器能不能打开，而是前端页面是否真的通过统一请求层、代理配置和 API 封装，成功打到了后端服务。

所以我给 Claude Code 的最后一个小任务是：

修改 ProviderList.vue，在页面加载时调用 getHealth()，把返回结果显示在页面上。如果调用成功显示绿色的"后端已连接：Hify is running"，失败显示红色的"后端未连接"。

Figure 7: 前后端联通状态在页面中的验证结果

这个动作看起来很小，但它把前面所有步骤都串起来了：

• 前端工程启动成功

• Vue Router 和页面壳子正常工作

• request.ts 能正常发请求

• /api 代理配置生效

• 后端 /api/v1/health 接口可访问

• 页面能把结果正确展示出来

只有这一步跑通，你才能真正说：这个项目已经从"工程初始化"进入"可以继续开发"的状态了。

这也是我很喜欢用健康检查接口做联通验证的原因。它简单、清晰、成本低，但验证链路非常完整。

总结：前端工程初始化，重点不是快，而是每一步都能验证

到这里，Hify 的工程初始化其实已经形成了一个很完整的闭环：后端能跑，前端能开，请求能通，页面能验证，一键启动不再只是一个脚本动作，而是一套真正能工作的开发底座。

如果把第 8 节和这一节连起来看，你会发现我一直在重复同一套方法论。

1. 任务拆解

工程初始化体量很大，不适合用一条大而全的提示词直接生成到底。只要满足下面任意一种情况，我就会拆任务：

• 生成量已经超出一次 review 的合理范围

• 后续步骤明显依赖前置结果

前端工程这次拆成"项目骨架、请求层、页面空壳、联通验证"几步，本质上就是在控制复杂度。

2. 基础设施先行

这次你也能明显看到顺序的重要性：

• 先有前端骨架

• 再有统一请求层

• 再有页面和路由

• 最后才做联通验证

顺序一乱，后面就会不停返工。比如你如果先写页面，再回头补请求层和代理规则，代码会很快变脏。

3. 每步验收

这套方式最重要的一点，是不是等全部做完才验证，而是每一步做完就给自己一个确定性的结果。

比如：

• 前端骨架起来了，说明工程初始化没跑偏

• request.ts 跑通了，说明请求规范立住了

• health.ts 可用，说明 API 调用链路对上了

• 页面显示健康状态，说明前后端真正联通了

每一个小验收点，都是在给后续工作减风险。

结语

这一节，我们没有去写复杂业务页面，也没有急着上状态管理、权限体系或者组件抽象，而是先把前端工程最关键的几条基础链路搭通了。

这看起来不"炫技"，但对个人开发和 AI 协作开发来说，反而是最值钱的部分。因为只有地基稳了，后面 Claude Code 才能持续稳定地产出页面、接口调用和交互逻辑。

到这一步，Hify 已经不是"后端骨架在，前端还没影"的半成品了，而是一个真正能启动、能联调、能继续往下长业务的完整空项目。