第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 请求层项目骨架起来之后下一步我不会马上写页面而是先把请求层收口。原因很简单后端已经定了统一响应格式 ResultT前端如果不在这里统一处理后面每个页面、每个 API 文件都会重复写一遍错误判断、消息提示和 data 解包。后端这边返回的是这种结构{ code: 200, message: success, data: {} }如果前端不做统一封装那么后面所有业务代码都会越来越啰嗦。我给 Claude Code 的指令思路是在 hify-web/src/utils/ 下创建 request.ts封装 axios 实例。baseURL 设为 /api。响应拦截器里判断 code200 直接返回 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): PromiseT instance.get(url, { params }) export const post T(url: string, data?: object): PromiseT instance.post(url, data) export const put T(url: string, data?: object): PromiseT instance.put(url, data) export const del T(url: string): PromiseT 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 () getstring(/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 已经不是“后端骨架在前端还没影”的半成品了而是一个真正能启动、能联调、能继续往下长业务的完整空项目。