Vue3 前端专题：把工作台前端从"能跑"做到"工程化"

先花 20 分钟把"旧肌肉记忆"和"新纪律"的差清理掉。你不是从零学 Vue，你是要把脑子里 Vue2 的组织方式换成 Vue3 的。

1.1 本模块锁定的技术栈（2026-10-14 核验）

1.2 旧 Vue2（选项式）→ 新 Vue3（组合式）差异速览

一句话转换口诀：把"在 Vue2 里 this.xxx"的思路，换成"在 setup 里 import 什么、声明什么 ref"。模板那层（插值、指令、事件）你几乎不用重学。

工作台的前端放在 workbench/web/（与 server/ 平级，见 11 模块目录契约）。下面整条命令序列照抄即可，Windows PowerShell 里执行。

2.1 照做步骤（编号执行）

1. 确认地基（应与 09 模块一致；不一致先回 09，不要在本模块纠结装环境）：

node -v      # 期望 v24.21.0（或 24.x 线）
pnpm -v      # 期望 12.11.2

2. 在 workbench/ 目录下用官方脚手架起 vue-ts 模板：

cd D:\你的代码目录\workbench
pnpm create vite web --template vue-ts
# 上面命令会创建 web/ 目录，内含 vue + ts + vite 骨架
cd web

3. 锁死核心版本（关键纪律：不手填 patch，只锁主版本区间，补丁交给 lock）：

pnpm add vue@^3.5
pnpm add vue-router pinia axios
pnpm add -D typescript@^7 vite@^8.3 @vitejs/plugin-vue
pnpm install

4. 把默认 HelloWorld 演示文件删掉，只留骨架（main.ts / App.vue），然后按 §2.3 建目录。
5. 启动开发服务器：

pnpm dev      # 默认 http://localhost:5173

2.2 目录结构（与工作台契约一致）

workbench/web/
├── src/
│   ├── types/          # 与后端契约对齐的 TS 类型（api.ts）
│   ├── api/            # request.ts(axios 实例) + auth.ts / task.ts
│   ├── stores/         # Pinia：user.ts
│   ├── router/         # index.ts（路由表 + 守卫）
│   ├── views/          # LoginView.vue / WorkbenchView.vue
│   ├── App.vue
│   └── main.ts
├── vite.config.ts      # dev proxy /api → localhost:8080
├── tsconfig.json
└── package.json / pnpm-lock.yaml   # 锁文件，入库

2.3 vite.config.ts（含 dev proxy，整文件照抄）

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { fileURLToPath, URL } from 'node:url'

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url)),
    },
  },
  server: {
    port: 5173,
    proxy: {
      // 前端代码里写 /api/xxx，开发服务器转发到 Go 后端
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
      '/healthz': {
        target: 'http://localhost:8080',
        changeOrigin: true,
      },
    },
  },
})

为什么必须走 proxy：开发时前端在 5173、后端在 8080，直接跨域会触发 CORS。让 Vite 把 /api 开头的请求代理到 8080，浏览器眼里就是同源，永远不要在前端代码里写 http://localhost:8080（见 §10 CORS 条）。

2.4 tsconfig.json 要点（整文件照抄）

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": { "@/*": ["./src/*"] },
    "types": ["vite/client"]
  },
  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
}

• strict: true 是你补 TS 纪律的关键——空值、隐式 any 全部报错，不要关。
• paths 与 vite alias 成对出现：两处都配 @，import 才不报错（漏配一处 = §10 "Cannot find module '@/...'"）。
• TS 7 原生编译器仍读这份 tsconfig，迁移无额外动作。

只讲工作台会用到的最小集。不要去背全部 API——用不到的背了也会忘。

3.1 ref / reactive / computed / watch

<script setup lang="ts">
import { ref, reactive, computed, watch } from 'vue'

// ref：基本类型或需要整体替换的对象。JS 里用 .value，模板里不用。
const count = ref(0)
count.value++            // JS 操作：必须 .value

// reactive：对象的深层响应式。访问属性不需要 .value。
const form = reactive({ username: '', password: '' })

// computed：派生状态，缓存，依赖变才重算。
const isEmpty = computed(() => form.username.trim() === '')

// watch：监听某个 ref / getter，变化时执行副作用。
watch(count, (newVal, oldVal) => {
  console.log('count 变了', oldVal, '->', newVal)
})
</script>

<template>
  <button @click="count++">点了 {{ count }} 次</button>
  <input v-model="form.username" placeholder="用户名">
  <p v-if="isEmpty">用户名为空</p>
</template>

3.2 生命周期（选项式钩子名加 on 前缀）

3.3 provide / inject（跨层传值）

// 祖先组件：提供
import { provide } from 'vue'
provide('appTitle', '我的工作台')

// 深层后代组件：注入（不知道中间传了几层）
import { inject } from 'vue'
const appTitle = inject('appTitle', '默认标题')   // 第二参数是默认值

3.4 组件通信全方案（速查）

纪律：工作台里组件通信只用三种——父子 props/emit、跨层 provide/inject、全局 Pinia。不引事件总线，不用 $root，状态来源只有 store 一条。

这是你这次闭关真正要补的东西。原则只有一条：与后端契约对齐的类型，集中定义在一处，全项目复用；组件 props/emits 一律泛型化，禁止裸 any。

4.1 先建契约类型：src/types/api.ts（整文件照抄）

这是前端与 workbench-contract.md 的唯一对齐点。后端字段改了，这里先改。禁止擅自增减字段。

// src/types/api.ts —— 与 workbench-contract.md 严格对齐

// 后端统一响应：{ code, data, msg }
export interface ApiResponse<T = unknown> {
  code: number
  data: T
  msg: string
}

// GET /api/v1/users 返回的用户（对应后端 GORM User）
export interface User {
  id: number
  username: string
  created_at: string
}

// POST /api/v1/auth/login 返回 { token, user }
export interface LoginResult {
  token: string
  user: User
}

// 任务（对应后端 GORM Task）
export interface Task {
  id: number
  title: string
  note: string
  done: boolean
  created_at: string
  updated_at: string
}

// 新建任务的请求体：POST /api/v1/tasks { title, note, done }
export interface TaskPayload {
  title: string
  note: string
  done: boolean
}

4.2 类型化 props / emits（泛型写法）

<script setup lang="ts">
import type { Task } from '../types/api'

// 父组件传进来的：一个 Task 对象 + 序号；disabled 可选
const props = defineProps<{
  task: Task
  index: number
  disabled?: boolean
}>()

// 子组件向外抛的：toggle 传 id、remove 传 id
const emit = defineEmits<{
  (e: 'toggle', id: number): void
  (e: 'remove', id: number): void
}>()

function onClickToggle() {
  emit('toggle', props.task.id)   // 传错字段/类型，TS 立刻报错
}
</script>

对比旧写法 props: ['task']——传错字段名、漏传必填项，旧写法运行时才炸；泛型写法编译期就拦下来。这就是纪律的价值。

4.3 as const 与类型安全要点

• as const：把字面量冻结成字面量类型，避免被推断成宽泛的 string。

const STATUS = ['pending', 'done'] as const
type Status = typeof STATUS[number]   // = 'pending' | 'done'

// 错误：不加 as const，STATUS 被推断成 string[]，Status 变成 string

• 禁止裸 any：实在不确定，用 unknown 再收窄，不要 any 一把梭。
• 接口复用：登录返回的 User 和任务页面用到的 User 是同一个 interface，改一处全项目生效——这就是"契约对齐"的工程含义。
• API 返回值必须标注泛型：http<Task[]>(...)，不标就是 unknown，等于没类型（见 §7）。
• 解构 reactive 对象会丢响应式：要解构就用 toRefs（见 §10 "ref 解包丢失"条）。

两个页面：/login（公开）和 /tasks（需登录）。守卫判断 token，未登录重定向回登录页，并把目标地址塞进 query，登录后回跳。

5.1 src/router/index.ts（整文件照抄）

import { createRouter, createWebHistory } from 'vue-router'
import { useUserStore } from '../stores/user'

const router = createRouter({
  history: createWebHistory(),
  routes: [
    {
      path: '/login',
      name: 'login',
      component: () => import('../views/LoginView.vue'),   // 懒加载
    },
    {
      path: '/tasks',
      name: 'tasks',
      component: () => import('../views/WorkbenchView.vue'),
      meta: { requiresAuth: true, roles: ['admin', 'user'] },  // RBAC 预留位
    },
    { path: '/', redirect: '/tasks' },
    { path: '/:pathMatch(.*)*', redirect: '/tasks' },
  ],
})

// 全局前置守卫
router.beforeEach((to) => {
  const userStore = useUserStore()

  // 1. 要登录但没登录 → 跳登录，记下目标路径
  if (to.meta.requiresAuth && !userStore.isLoggedIn) {
    return { name: 'login', query: { redirect: to.fullPath } }
  }
  // 2. 已登录还访问登录页 → 直接进任务页
  if (to.name === 'login' && userStore.isLoggedIn) {
    return { path: '/tasks' }
  }
  // 3. roles 校验（阶段三 RBAC 再启用；现在不拦）
  return true
})

export default router

• 懒加载：component 写成 () => import(...)，路由组件单独打包，首屏更快。
• meta.requiresAuth / meta.roles：当前只做 requiresAuth；roles 数组是给阶段三 RBAC 预留的位（08 §2 阶段三），后端 RBAC 落地时在守卫第 3 步接上 userStore.user 的角色判断即可，现在不改结构。
• 守卫里用 useUserStore() 必须在路由实例之后调用——上面写法正确，不要把它移到文件顶层。

全局只放"登录态"这种真正跨页面的东西：token + userinfo，刷新页面不能丢，所以手写 localStorage 持久化（不引持久化插件，少一个依赖少一个坑）。

6.1 src/stores/user.ts（组合式 store 写法，整文件照抄）

import { defineStore } from 'pinia'
import { ref, computed } from 'vue'
import type { User } from '../types/api'

const TOKEN_KEY = 'wb_token'
const USER_KEY = 'wb_user'

export const useUserStore = defineStore('user', () => {
  // 初始值从 localStorage 读，刷新不丢
  const token = ref<string>(localStorage.getItem(TOKEN_KEY) || '')
  const user = ref<User | null>(
    localStorage.getItem(USER_KEY)
      ? (JSON.parse(localStorage.getItem(USER_KEY)!) as User)
      : null,
  )

  const isLoggedIn = computed(() => !!token.value)

  function setAuth(t: string, u: User) {
    token.value = t
    user.value = u
    localStorage.setItem(TOKEN_KEY, t)
    localStorage.setItem(USER_KEY, JSON.stringify(u))
  }

  function logout() {
    token.value = ''
    user.value = null
    localStorage.removeItem(TOKEN_KEY)
    localStorage.removeItem(USER_KEY)
  }

  return { token, user, isLoggedIn, setAuth, logout }
})

在组件里用：const userStore = useUserStore()，然后 userStore.isLoggedIn / userStore.setAuth(...)。store 里的 ref 在组件中自动解包，不用 .value。

工程化的标志：全项目只建一个 axios 实例，请求自动带 token，响应自动拆 code/data/msg，401 自动清登录态跳登录。业务代码里不再写任何 headers、不再判 code。

7.1 src/api/request.ts（整文件照抄）

import axios from 'axios'
import type { AxiosRequestConfig } from 'axios'
import { useUserStore } from '../stores/user'
import type { ApiResponse } from '../types/api'

const request = axios.create({
  baseURL: '/api/v1',      // 代码里都写 /api/v1/...，dev 走 vite proxy
  timeout: 10000,
})

// 请求拦截器：自动带上 Bearer token
request.interceptors.request.use((config) => {
  const userStore = useUserStore()
  if (userStore.token) {
    config.headers.Authorization = `Bearer ${userStore.token}`
  }
  return config
})

// 响应拦截器：统一拆 { code, data, msg }
request.interceptors.response.use(
  (resp) => {
    const body = resp.data as ApiResponse
    if (body.code === 0) {
      return body.data          // 业务成功：直接把 data 交出去
    }
    // code 非 0 = 业务错误，msg 是人类可读信息
    return Promise.reject(new Error(body.msg || '业务错误'))
  },
  (error) => {
    // HTTP 层错误（401/500/网络断）
    if (error.response?.status === 401) {
      const userStore = useUserStore()
      userStore.logout()
      // 已经在登录页就不要再跳，避免循环（见 §10）
      if (!window.location.pathname.startsWith('/login')) {
        const redirect = encodeURIComponent(window.location.pathname)
        window.location.href = `/login?redirect=${redirect}`
      }
    }
    const msg = error.response?.data?.msg || error.message || '网络错误'
    return Promise.reject(new Error(msg))
  },
)

// 类型化的请求函数：业务代码一律用 http<T>，不用裸 request
export async function http<T>(config: AxiosRequestConfig): Promise<T> {
  return request.request(config) as unknown as Promise<T>
}

export default request

7.2 按业务拆分：src/api/auth.ts 与 src/api/task.ts

// src/api/auth.ts
import { http } from './request'
import type { LoginResult, User } from '../types/api'

// POST /api/v1/auth/login，body { username, password }
export function login(username: string, password: string) {
  return http<LoginResult>({
    url: '/auth/login',
    method: 'POST',
    data: { username, password },
  })
}

// GET /api/v1/users（管理功能演示，工作台预留）
export function fetchUsers() {
  return http<User[]>({ url: '/users', method: 'GET' })

// src/api/task.ts —— 端点严格按契约，不新增
import { http } from './request'
import type { Task, TaskPayload } from '../types/api'

export function fetchTasks() {                                  // GET    /tasks
  return http<Task[]>({ url: '/tasks', method: 'GET' })
}
export function createTask(payload: TaskPayload) {              // POST   /tasks
  return http<Task>({ url: '/tasks', method: 'POST', data: payload })
}
export function updateTask(id: number, payload: Partial<TaskPayload>) {  // PUT /tasks/:id
  return http<Task>({ url: `/tasks/${id}`, method: 'PUT', data: payload })
}
export function removeTask(id: number) {                        // DELETE /tasks/:id
  return http<void>({ url: `/tasks/${id}`, method: 'DELETE' })
}

这是对 11 模块"最小版前端"的工程化升级：同样两个页面，但有 TS 类型、有统一请求、有路由守卫、有 loading 与错误提示。先写入口，再写两个视图。

8.1 入口：src/main.ts 与 src/App.vue

// src/main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
import router from './router'

createApp(App).use(createPinia()).use(router).mount('#app')

<!-- src/App.vue -->
<script setup lang="ts"></script>

<template>
  <router-view />
</template>

8.2 登录页：src/views/LoginView.vue（整文件照抄）

<script setup lang="ts">
import { ref } from 'vue'
import { useRouter, useRoute } from 'vue-router'
import { login } from '../api/auth'
import { useUserStore } from '../stores/user'

const router = useRouter()
const route = useRoute()
const userStore = useUserStore()

const username = ref('')
const password = ref('')
const loading = ref(false)
const errorMsg = ref('')

async function onSubmit() {
  errorMsg.value = ''
  if (!username.value || !password.value) {
    errorMsg.value = '用户名和密码不能为空'
    return
  }
  loading.value = true
  try {
    const res = await login(username.value, password.value)
    userStore.setAuth(res.token, res.user)          // token+user 落 localStorage
    const redirect = (route.query.redirect as string) || '/tasks'
    router.push(redirect)                            // 登录后回跳原目标
  } catch (e) {
    errorMsg.value = e instanceof Error ? e.message : '登录失败'
  } finally {
    loading.value = false
  }
}
</script>

<template>
  <div style="max-width:360px;margin:80px auto;padding:0 16px">
    <h2 style="text-align:center">工作台登录</h2>
    <form @submit.prevent="onSubmit" style="display:block">
      <input v-model="username" placeholder="用户名"
        style="width:100%;padding:8px;margin:8px 0" />
      <input v-model="password" type="password" placeholder="密码"
        style="width:100%;padding:8px;margin:8px 0" />
      <button type="submit" :disabled="loading"
        style="width:100%;padding:9px;margin-top:8px">
        {{ loading ? '登录中…' : '登 录' }}
      </button>
      <p v-if="errorMsg" style="color:#C0392B;margin-top:10px">{{ errorMsg }}</p>
    </form>
  </div>
</template>

8.3 任务列表页：src/views/WorkbenchView.vue（表格 + 增删改 + 完成勾选）

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { fetchTasks, createTask, updateTask, removeTask } from '../api/task'
import { useUserStore } from '../stores/user'
import type { Task } from '../types/api'

const userStore = useUserStore()
const tasks = ref<Task[]>([])
const loading = ref(false)
const errorMsg = ref('')
const newTitle = ref('')
const newNote = ref('')

async function load() {
  loading.value = true
  errorMsg.value = ''
  try {
    tasks.value = await fetchTasks()          // GET /tasks，返回类型 Task[]
  } catch (e) {
    errorMsg.value = e instanceof Error ? e.message : '加载任务失败'
  } finally {
    loading.value = false
  }
}

async function onCreate() {
  if (!newTitle.value.trim()) return
  try {
    await createTask({
      title: newTitle.value.trim(),
      note: newNote.value.trim(),
      done: false,
    })
    newTitle.value = ''
    newNote.value = ''
    await load()
  } catch (e) {
    errorMsg.value = e instanceof Error ? e.message : '创建失败'
  }
}

async function onToggleDone(t: Task) {
  try {
    await updateTask(t.id, { done: !t.done })   // PUT /tasks/:id 标记完成
    t.done = !t.done
  } catch (e) {
    errorMsg.value = e instanceof Error ? e.message : '更新失败'
  }
}

async function onRemove(t: Task) {
  try {
    await removeTask(t.id)                      // DELETE /tasks/:id
    tasks.value = tasks.value.filter((x) => x.id !== t.id)
  } catch (e) {
    errorMsg.value = e instanceof Error ? e.message : '删除失败'
  }
}

function onLogout() {
  userStore.logout()
  window.location.href = '/login'
}

onMounted(load)      // 进页面就拉一次列表
</script>

<template>
  <div style="max-width:760px;margin:30px auto;padding:0 16px">
    <div style="display:flex;justify-content:space-between;align-items:center">
      <h2>我的工作台</h2>
      <span>
        {{ userStore.user?.username }}
        <button @click="onLogout" style="margin-left:10px">退出登录</button>
      </span>
    </div>

    <div style="margin:14px 0">
      <input v-model="newTitle" placeholder="任务标题"
        style="padding:7px;width:45%" />
      <input v-model="newNote" placeholder="备注（可空）"
        style="padding:7px;width:35%;margin-left:6px" />
      <button @click="onCreate" style="margin-left:6px">新增</button>
    </div>

    <p v-if="loading" style="color:#3d5a80">加载中…</p>
    <p v-if="errorMsg" style="color:#C0392B">{{ errorMsg }}</p>

    <table v-else style="width:100%;border-collapse:collapse">
      <thead>
        <tr style="background:#0E1B2C;color:#fff;text-align:left">
          <th style="padding:8px">完成</th>
          <th style="padding:8px">标题</th>
          <th style="padding:8px">备注</th>
          <th style="padding:8px">操作</th>
        </tr>
      </thead>
      <tbody>
        <tr v-for="t in tasks" :key="t.id"
          :style="t.done ? 'opacity:.5' : ''">
          <td style="padding:8px;border:1px solid #e2e7ec">
            <input type="checkbox" :checked="t.done"
              @change="onToggleDone(t)" />
          </td>
          <td style="padding:8px;border:1px solid #e2e7ec">
            <span :style="t.done ? 'text-decoration:line-through' : ''">
              {{ t.title }}
            </span>
          </td>
          <td style="padding:8px;border:1px solid #e2e7ec">{{ t.note }}</td>
          <td style="padding:8px;border:1px solid #e2e7ec">
            <button @click="onRemove(t)">删除</button>
          </td>
        </tr>
        <tr v-if="tasks.length === 0">
          <td colspan="4" style="padding:12px;border:1px solid #e2e7ec;color:#5d6d7e">
            还没有任务，先新增一条。
          </td>
        </tr>
      </tbody>
    </table>
  </div>
</template>

这一页包含了全部工程化要点：onMounted 拉数据、loading/errorMsg 两个 ref 管界面状态、每次增删改后 reload、勾选触发 PUT、删除后本地 filter 兜底。表格样式用内联是为了教程自包含；真实项目里把样式抽进 style 块或 CSS 文件。

本地开发跑通后，一条命令产出静态文件。生产怎么接，细节归 20 模块，这里只讲"前端这边"的动作。

9.1 构建

cd workbench/web
pnpm build        # 先做 TS 类型检查，再打包；类型不过会失败
# 产物输出到 web/dist/ ：index.html + assets/
pnpm preview      # 本地预览构建产物，模拟生产

9.2 产物接入（两种，二选一，细节见 20 模块）

生产环境没有 proxy：Vite 的 server.proxy 只在 pnpm dev 时生效。生产是浏览器直接访问同源 /api，由 Go 或 Nginx 接。所以代码里写 /api/v1 相对路径是对的——dev 被代理，prod 被同源服务接住，一套代码两头通用。

闭关期间卡壳，先查这张表。每条都是这个技术栈真会遇到的报错。

对照 08 总纲 M3 验收项（"前端（Vue3+TS+Pinia+路由守卫）完整接入"）逐条打勾。全绿才算本模块结业。

结业标志：上面 10 项全绿 = 08 总纲 W5–W6"工作台前端第一版"与 W7–W8 M3"前端完整接入"两格同时打勾。你的工作台前端从此是工程，不再是"能跑的页面"。

完整版与全部核验说明见 09 环境搭建与版本清单 与全系列 versions.md。

来源表

（编者整理：本页"最小必要理论 + 照做步骤 + 报错表"的组织方式、组件通信速查、报错条目为基于官方文档与工作台契约的教学化整理；API 端点与模型为契约原文，无外部来源。）