◈09|工程初始化(下):前端工程与一键启动

09|工程初始化(下):前端工程与一键启动

你好,我是Robert。

上一讲我们搭好了后端骨架——Maven多模块结构、公共基础设施、健康检查接口, java -jar 能跑,访问 /api/v1/health 返回200。

这一讲把剩下的补齐:前端Vue工程、前后端联通、启动脚本。做完之后,你执行一个 ./start.sh,后端前端同时起来,浏览器打开就能看到Hify的页面。

从零到能跑的完整闭环,这一讲交付完成。

前端 Vue 工程搭建

和上一讲后端一样,前端初始化也要分步做。我分成三步:项目骨架、axios统一请求层、路由和页面空壳。上一讲建立的任务拆解方法论直接复用,不再解释为什么要拆——按依赖关系排序,每步验证后进入下一步。

第一步:项目骨架

给Claude Code的指令思路:

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

输出是:

这一步比较标准化,Claude Code一般不会出大问题。拿到输出后检查两件事:目录结构和CLAUDE.md里定义的是否一致;Vite代理配置是否正确,开发阶段前端跑在5173端口,通过Vite代理转发 /api 请求到后端8080端口,解决跨域问题。

是不是很快。说实话,我一点不懂前端。但是通过上面的指令就有一个前端服务了。这里需要注意的是: 提示词要完整且清晰。你可以参考一下上面的提示词。

第二步:axios 统一请求层

这一步值得多讲一下,因为它是前端和后端规范体系的接合点。

后端定了统一响应格式 Result<T>,每个接口都返回 { code: 200, message: "success", data: {...} }。前端的axios封装要和这套格式对接,让业务代码不需要每次都手动处理code判断和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四个方法。

为什么要在拦截器里自动解包data?因为如果不这么做,后面每个页面调接口都要写:

const result = await providerApi.getList()
const list = result.data  // 每次都要 .data

封装之后直接就是:

const list = await providerApi.getList()  // 直接拿到 data

看起来是个小事,但几十个接口累积下来,代码干净很多。来看生成的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)

然后让Claude Code基于这个封装写一个示例API文件:

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

文件代码是:

import { get } from '@/utils/request'

export const getHealth = () => get<string>('/v1/health')

这个文件只有几行代码,但它验证了整条链路——axios封装、代理配置、接口路径规范——是否都通。

回过头看,这就是为什么06讲要把接口规范写进CLAUDE.md,因为不只后端在用,前端axios封装也在对着同一份规范做。后端的 Result<T> 格式、接口路径规则、错误码定义,前端全部照着来。一份规范,两端对齐。

第三步:路由和页面空壳

给Claude Code的指令是:

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

这一步生成的是一个有完整导航结构的空壳应用——左边菜单、右边内容,点菜单能切换页面,每个页面都是占位文字。后面往里填内容就行。

前后端联通

前端搭好了,后端上一讲已经能跑了。现在把它们连起来。

这一步验证的是完整链路:Vite代理配置对不对、axios封装能不能用、前后端的接口格式能不能对上。

把前端的ProviderList.vue改一下,让它调用健康检查接口并显示结果:

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

启动后端、启动前端,打开浏览器 http://localhost:5173,你应该能看到左侧菜单、右侧显示绿色的“后端已连接”。但是,却是:

看了一眼,发现hify server被我关了,启动后:

看到了,说明前后端联通成功——axios封装正常、Vite代理正常、后端接口正常、Result格式前端能正确解析。如果显示红色,就把浏览器控制台的错误信息贴给Claude Code让它排查。

启动脚本

到这一步,前后端都能跑了,但每次启动要开两个终端、输两条命令。写个脚本让它一键搞定。

还记得01讲的三层分工吗?启动脚本、Makefile这些就是典型的第三层——AI全权处理,你验收结果就行。脚本逻辑不复杂,但手写容易漏细节(进程管理、日志输出、端口检查),交给Claude Code特别合适。不需要逐行review shell语法,跑一下 start.sh 能起来就过了。

start.sh

写一个start.sh脚本,放在项目根目录。功能:检查MySQL和Redis是否可用,构建后端并后台启动,轮询等待后端健康检查通过,启动前端开发服务器。加上错误处理:任何一步失败就停止并提示。

stop.sh

写一个stop.sh脚本,优雅停止后端和前端进程。按PID文件找进程,先SIGTERM再等待,超时SIGKILL。

Makefile

写一个Makefile,包含以下target:make start(启动)、make stop(停止)、make restart(重启)、make build(构建后端 + 前端)、make clean(清理构建产物)、make package(打包成可分发的 tar.gz)。

这里不展示输入和输出的细节了,实操课中会演示,直接展示结果。

这 3 个文件加起来可能就一两百行脚本,但它们让整个项目的使用体验提升了一个档次。拉下代码, make start 就跑起来了, make package 就能打包分发。

验收时刻

所有东西都就绪了。最终验收:

sh start.sh

你应该看到这样的输出:

-e [INFO]  检查 MySQL localhost:3306 ...
-e [ERROR] MySQL 不可达(localhost:3306),请先启动 MySQL

这里是因为MySQL没配置。调整配置后,打开浏览器访问 http://localhost:5173:

  • 左侧看到三个菜单:模型管理、Agent管理、对话
  • 点“模型管理”,右侧显示绿色的“后端已连接:Hify is running”
  • 点其他菜单,显示对应的占位文字

看到这些,工程初始化就完成了。你手上有了一个前后端都能跑的空项目,结构清晰、规范就绪、一键启动。后面的工作就是往这个骨架里填功能。

总结

我们用两节课完成了Hify的工程初始化——后端能跑、前端能开、一键启动、前后端联通。最终,你手上有了一个完整的“空项目。

最后我们回顾一下这两讲的方法论:

任务拆解。 工程初始化体量大,不能一条指令搞定。按依赖关系拆成有序的步骤,每步验证后再进入下一步。判断标准:生成量超出一次review范围、步骤间有依赖,满足其一就拆。

基础设施先行。 先搭Maven骨架、再搭公共模块、再搭业务空壳、再搭前端、最后写脚本。顺序不能乱,因为后面的每一步都依赖前面的结果。

每步验收。 不是搭完全部才验收,而是每一步做完就验证。每一个验收点给你信心:到这里是对的。

不过,工程初始化完成不代表可以直接写业务了。现在的空项目还缺一层东西——基础组件。数据库怎么做分页、接口入参怎么校验、调外部API的客户端怎么封装、线程池怎么配、熔断怎么搞,这些是所有业务模块都会用到的底层能力。

不过下一讲我们要换一种协作模式,不是你告诉Claude Code做什么,而是先让它告诉你该做什么。

思考题

这两讲工程初始化的过程中,Claude Code做了大量“模板性”的工作,包括项目结构、配置文件、公共组件、脚本。回想一下你自己平时做项目,有哪些类似的不难但繁琐的工作?列出3个你觉得最适合交给AI做的,以及你会怎么给它描述需求。

期待你的分享。如果今天的课程让你有所收获,也欢迎转发给有需要的朋友,邀请他来一起学习,我们下节课再见!