全栈Todo应用实战：从零到一的本地部署与深度解析

全栈Todo应用实战：从零到一的本地部署与深度解析

前言

在现代Web开发中，全栈应用已成为主流。本文将以一个经典的Todo（待办事项）应用为例，详细记录从项目下载、环境配置、后端启动、数据库交互到前端运行的完整流程。我们将深入探讨在此过程中遇到的一个典型问题——CORS与API请求失败，并提供从“快速修复”到“最佳实践”的解决方案。这不仅是一份操作指南，更是一次宝贵的实战经验总结。

你将从本博客中学到：

• 如何配置并运行一个基于Node.js和MySQL的全栈项目。
• 如何使用Navicat或命令行工具管理和查看数据库。
• 理解并解决因file:///协议导致的前后端通信失败问题。
• 掌握使用live-server等工具启动前端开发服务器的正确姿势。
• 一个完整的本地开发工作流。

---

技术栈概览

• 前端:
  • HTML5, CSS3, 原生JavaScript (ES6+)
  • Fetch API (用于与后端通信)
  • Live-server (用于本地开发)
• 后端:
  • Node.js
  • Express.js (作为Web框架)
  • mysql2 (高性能MySQL驱动)
  • dotenv (管理环境变量)
  • cors (处理跨域资源共享)
• 数据库:
  • MySQL

---

️ 环境准备

在开始之前，请确保您的开发环境中已安装以下软件：

1. Node.js: 下载地址 (建议使用LTS版本)
2. MySQL: 确保服务已安装并正在运行。
3. 数据库管理工具 (推荐): Navicat, DBeaver, 或MySQL Workbench。本文以Navicat为例。
4. 代码编辑器: Visual Studio Code (推荐)

---

⚙️ 第一步：配置并启动后端服务

后端是整个应用的大脑，负责处理业务逻辑和数据存储。

1. 数据库与环境配置

首先，我们需要告诉后端应用如何连接到我们的数据库。

1. 进入后端目录: cd backend

2. 创建环境变量文件: 项目中提供了一个.env.example文件作为模板。我们复制它并重命名为.env。

3. 编辑.env文件: 打开.env文件，填入您的MySQL数据库信息。

   # .env
   DB_HOST=localhost
   DB_USER=root
   DB_PASSWORD=你的MySQL密码
   DB_NAME=todoapp
   PORT=5000
   

2. 安装依赖

Node.js项目通过package.json文件管理依赖。我们需要安装这些依赖。

# 在 backend 目录下运行
npm install

3. 启动服务

一切就绪后，启动后端服务器。

# 在 backend 目录下运行
npm start

如果一切顺利，您将在终端看到以下输出，表示后端已成功启动并连接到数据库：

✅ MySQL数据库连接成功
✅ todos表检查/创建完成
 服务器运行在端口 5000
 API文档: http://localhost:5000/api/health
 数据库: MySQL

效果如下：

---

️ 第二步：数据库的创建与交互

数据是应用的血液。后端启动后，我们需要确保数据库和表都已就绪。

1. 创建数据库

后端应用需要一个名为todoapp的数据库。您可以使用Navicat或命令行创建它。

使用Navicat:

1. 连接到您的MySQL。
2. 右键点击连接，选择“新建数据库”。
3. 输入数据库名 todoapp，选择字符集为 utf8mb4。
4. 点击“确定”。

2. 自动化的表创建

这个项目的后端代码非常友好，它会在启动时自动检查todos表是否存在，如果不存在，则会自动创建。您无需手动创建表结构。

3. 查看数据库信息

当您在前端添加了两个待办事项后，有多种方法可以查看数据库中的信息。

方法一：使用Navicat图形界面（推荐）

正如项目中的 Navicat操作指南.md 所述，使用图形化工具是最直观的方式。

1. 打开 Navicat 并连接到您的本地MySQL数据库。
2. 在左侧的连接列表中，找到并双击打开 todoapp 数据库。
3. 展开 todoapp 数据库，您会看到一个名为“表”的分类。
4. 双击 todos 表。

之后，您应该能在一个表格中看到刚刚添加的两条待办事项记录。
效果如下：

方法二：使用MySQL命令行

如果您更习惯使用命令行，可以按照以下步骤操作：

1. 打开一个新的终端或命令提示符。
2. 登录到MySQL（系统会提示您输入密码）：

   mysql -u root -p
   

3. 选择 todoapp 数据库：

   USE todoapp;
   

4. 查询 todos 表中的所有数据：

   SELECT * FROM todos;
   

5. 执行后，您将在终端中看到一个包含您数据的表格。
6. 退出MySQL：

   exit;
   

方法三：通过应用的API接口

您也可以直接通过浏览器访问后端提供的API来查看数据，这同时也能验证API是否工作正常。

1. 打开您的网页浏览器。
2. 访问以下地址：
   http://localhost:5000/api/todos

浏览器页面上会显示一个JSON格式的数组，其中就包含了您添加的两条待办事项。

---

️ 第三步：运行前端应用（并解决关键问题）

前端是用户与应用交互的界面。在这里，我们遇到了一个非常典型且重要的问题。

1. 问题诊断：为什么直接打开HTML会失败？

很多初学者会直接在文件管理器中双击frontend/index.html来运行前端。这时，浏览器的地址栏会显示一个以file:///开头的路径。

当您在这种模式下尝试添加待办事项时，操作会失败。打开浏览器开发者工具（按F12），您会在控制台看到类似**CORS (跨域资源共享)**的错误。

根本原因:

• 协议不同: 浏览器将file://协议和后端服务所在的http://协议视为不同的“源”(Origin)。
• 安全策略: 出于安全考虑，浏览器默认禁止跨源的HTTP请求。
• 代码逻辑错误: 我们项目index.html中的判断逻辑 window.location.hostname === 'localhost' 会失败，因为在file://协议下，hostname是空的，导致API请求地址错误地指向了一个不存在的生产环境URL。

2. 临时解决方案：硬编码API地址

为了快速解决这个问题，我们进行了一个简单的修改：将API地址写死。

修改前:

const API_BASE_URL = window.location.hostname === 'localhost' 
    ? 'http://localhost:5000'
    : 'https://your-backend-url.railway.app';

修改后:

const API_BASE_URL = 'http://localhost:5000';

这个修改能让应用在本地file:///模式下工作，但它不是一个好的长期方案，因为它破坏了开发环境和生产环境之间切换的灵活性。

3. 最佳实践：使用开发服务器

正确的做法是，在本地也通过http://协议来提供前端文件服务，模拟真实的网络环境。

frontend/package.json已经为我们准备好了工具——live-server。

操作步骤:

1. 进入前端目录:

   cd frontend
   

2. 安装依赖:

   npm install
   

   这个命令会下载live-server。
3. 启动前端开发服务器:

   npm run dev
   

   执行后，live-server会自动在您的默认浏览器中打开一个新页面，地址通常是http://127.0.0.1:3000或http://localhost:3000。

现在，前端和后端都通过http协议提供服务，它们属于不同的端口，但后端已经配置了cors中间件，允许来自任何源的请求，因此可以完美通信。

---

最终效果：

✅ 总结：完整的开发流程

现在，我们来梳理一下从头到尾的正确开发流程：

1. 启动数据库: 确保您的MySQL服务正在运行。
2. 启动后端: 打开一个终端，进入backend目录，运行npm start。
3. 启动前端: 打开另一个终端，进入frontend目录，运行npm run dev。
4. 开始使用: 在live-server自动打开的浏览器页面中操作Todo应用。
5. 验证数据: 使用Navicat或访问API URL来查看数据库中的实时数据变化。

---

核心要点与总结

• 环境变量的重要性: 使用.env文件可以安全、灵活地管理敏感信息和配置，避免将其硬编码在代码中。
• 前后端分离的开发模式: 后端和前端作为独立的服务运行，通过API进行通信。
• CORS是朋友，不是敌人: 跨域策略是浏览器的一项重要安全功能。理解它并正确配置后端（使用cors中间件）是全栈开发的基础。
• 告别file:///: 任何现代Web开发都应该在本地使用开发服务器，以确保开发环境与生产环境尽可能一致。

---

结语

通过本次实践，我们不仅成功地在本地部署了一个全栈应用，更重要的是，我们深入理解了其背后的工作原理和开发中的常见“陷阱”。希望这篇博客能为您未来的全栈开发之旅提供有价值的参考。

源码链接如下：源码