React / 系统课时

搭建前后端项目骨架

搭建前后端项目骨架

本课搭建一个可同时启动的全栈开发骨架:React 18 前端通过 Vite 运行,Express 与 TypeScript 提供后端接口,MySQL 负责持久化。完成后,浏览器能够访问健康检查并确认数据库连接正常。

学习目标

  • 初始化前端、后端和根工作区目录
  • 用统一环境变量连接浏览器、API 与数据库
  • 建立一条可验证的本地开发启动链路

规划工作区结构

项目采用 npm workspaces 管理两个应用。apps/web 只保存浏览器代码,apps/api 只保存服务端代码;根目录负责统一脚本和环境变量示例。

text
task-manager/
├─ apps/
│  ├─ web/
│  └─ api/
├─ .env.example
├─ .gitignore
└─ package.json

运行时请求链路是:浏览器访问 Vite,Vite 把 /api 请求代理到 Express,Express 再连接 MySQL。数据库账号只由后端读取,前端只能读取带 VITE_ 前缀的公开变量。

全栈项目本地开发链路图

初始化前端与后端

在空目录中执行以下命令。命令使用 Vite 创建 React TypeScript 项目,并为 API 安装 Express、MySQL 驱动和开发期类型依赖。

bash
mkdir task-manager
cd task-manager
npm init -y
npm create vite@latest apps/web -- --template react-ts
cd apps/web
npm install react@18 react-dom@18
npm install -D @types/react@18 @types/react-dom@18
cd ../..
node -e "require('fs').mkdirSync('apps/api/src', { recursive: true })"
cd apps/api
npm init -y
npm install express cors dotenv mysql2
npm install -D typescript tsx @types/node @types/express @types/cors
cd ../..
npm install -D concurrently
node -e "const fs=require('fs'); console.log(fs.existsSync('apps/web/package.json') && fs.existsSync('apps/api/package.json') ? 'skeleton ready' : 'skeleton missing')

预期输出

text
skeleton ready

依赖安装过程中的日志会随 npm 版本和缓存状态变化,最后一行应为 skeleton ready。命令还会把前端运行时固定在 React 18,并生成 apps/web/package.json 与 apps/api/package.json。

配置工作区与启动脚本

把根目录 package.json 改为下面内容。工作区脚本会并行启动前端和后端,避免分别进入两个目录运行命令。

json
{
  "name": "task-manager",
  "private": true,
  "workspaces": [
    "apps/web",
    "apps/api"
  ],
  "scripts": {
    "dev": "concurrently -n web,api \"npm --workspace apps/web run dev\" \"npm --workspace apps/api run dev\""
  },
  "devDependencies": {
    "concurrently": "^9.0.0"
  }
}

把 apps/api/package.json 中的脚本和模块类型调整为下面内容;依赖版本保留安装命令实际写入的值。

json
{
  "name": "api",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "typecheck": "tsc --noEmit"
  }
}

片段示例:第二段只展示需要人工合并的字段,不能直接覆盖安装后完整的 apps/api/package.json。合并后执行 npm install,确保工作区锁文件与两个子项目一致。

统一环境变量边界

根目录创建 .env.example。前端公开变量必须使用 VITE_ 前缀;数据库账号不带该前缀,因此不会被 Vite 注入浏览器代码。

bash
PORT=3000
VITE_API_BASE_URL=/api
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=task_manager
DB_USER=task_app
DB_PASSWORD=change_me

这是配置文件示例,不直接执行。将其复制为 .env 后填写本机数据库信息,并把 .env 加入 .gitignore,只提交 .env.example。

配置 apps/web/vite.config.ts,让 Vite 从根目录读取公开变量,并代理 API 请求。

ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  envDir: '../../',
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true
      }
    }
  }
});

生效后,浏览器请求 /api/health 时不会发生跨域跳转,而是由 Vite 开发服务器转发给后端。生产环境仍应由反向代理或同域部署接管该路径。

实现后端健康检查

创建 apps/api/tsconfig.json。

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": [
    "src"
  ]
}

创建 apps/api/src/server.ts。启动时加载根目录 .env,健康检查通过 SELECT 1 验证数据库,而不是只返回固定字符串。

ts
import cors from 'cors';
import dotenv from 'dotenv';
import express from 'express';
import mysql from 'mysql2/promise';
import { resolve } from 'node:path';

dotenv.config({ path: resolve(process.cwd(), '../../.env') });

const app = express();
const port = Number(process.env.PORT ?? 3000);

const pool = mysql.createPool({
  host: process.env.DB_HOST,
  port: Number(process.env.DB_PORT ?? 3306),
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  connectionLimit: 5
});

app.use(cors());
app.use(express.json());

app.get('/api/health', async (_request, response) => {
  try {
    await pool.query('SELECT 1');
    response.json({ status: 'ok', database: 'connected' });
  } catch {
    response.status(503).json({
      status: 'error',
      database: 'disconnected'
    });
  }
});

app.listen(port, () => {
  console.log(`API listening on http://localhost:${port}`);
});

预期输出

text
API listening on http://localhost:3000

这段代码可独立运行,但要求 MySQL 已启动、目标数据库与账号已创建,并且根目录 .env 中的连接信息正确。

连接 React 页面并验证

替换 apps/web/src/App.tsx。组件在首次渲染时调用健康检查,并把结果直接显示在页面上。

tsx
import { useEffect, useState } from 'react';

type HealthResponse = {
  status: string;
  database: string;
};

export default function App() {
  const [message, setMessage] = useState('正在连接后端...');

  useEffect(() => {
    const loadHealth = async () => {
      const baseUrl = import.meta.env.VITE_API_BASE_URL ?? '/api';
      const response = await fetch(`${baseUrl}/health`);

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      const data = (await response.json()) as HealthResponse;
      setMessage(`API ${data.status},数据库 ${data.database}`);
    };

    loadHealth().catch((error: unknown) => {
      const reason = error instanceof Error ? error.message : '未知错误';
      setMessage(`连接失败:${reason}`);
    });
  }, []);

  return (
    <main>
      <h1>Task Manager</h1>
      <p>{message}</p>
    </main>
  );
}

预期结果

text
Task Manager
API ok,数据库 connected

复制环境变量并启动两个应用。

bash
node -e "require('fs').copyFileSync('.env.example', '.env')"
npm install
npm run dev

预期输出

text
[api] API listening on http://localhost:3000
[web] Local: http://localhost:5173/

浏览器打开 http://localhost:5173 后,页面应显示“API ok,数据库 connected”。如果页面显示连接失败,先检查 .env 的数据库账号,再直接访问 http://localhost:3000/api/health 判断问题位于 API 还是 Vite 代理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

搭建前后端项目骨架

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通