文章目录
- 项目概述
- 技术架构选型
- 技术架构选型
- 后端技术栈
- 项目结构设计
- 数据库设计与实现
- 数据库初始化
- 后端 API 架构
- 认证模块（/auth）
- 用户管理模块（/user）
- 任务管理模块（/task）
- 枚举配置模块（/enum）
- 前端实现细节
- 状态管理设计
- 请求拦截器配置
- 组件化开发实践
- 全链路数据流
- 环境配置与部署
- 环境变量管理
- 开发环境启动
- 静态资源处理
- 开发经验与最佳实践
- 1. 前后端分离架构优势
- 2. 鉴权安全实践
- 3.错误处理统一化
- 4.数据库设计考量
- GitCode源码
- 演示效果
- 项目总结
项目概述
在现代化应用开发中，全链路项目开发能力已成为工程师的核心竞争力。本文将通过一个完整的待办事项系统（ywt-task-pro）案例，分享从前端用户界面到后端 API 设计，直至数据库架构的全流程交付经验。该系统实现了用户管理、任务增删改查、JWT 鉴权等核心功能，展现了全栈开发的完整技术闭环。
技术架构选型
技术架构选型
- Vue 3：采用组合式 API 实现响应式界面
- Vite：构建工具，提供快速的开发服务器
- Vue Router：单页面应用路由管理
- Vuex：集中式状态管理
- Element Plus：UI 组件库，加速界面开发
- Axios：HTTP 客户端，处理 API 请求
后端技术栈
- Koa：轻量级 Node.js Web 框架
- Koa Router：路由中间件
- koa-body：请求体解析
- JWT：基于 jsonwebtoken 的认证机制
- MySQL：使用 mysql2 驱动进行数据持久化
项目结构设计
ywt-task-pro/
├── backend/ # 后端服务
│ ├── app.js # 服务器入口文件
│ ├── routes/ # API 路由定义
│ ├── controllers/ # 业务逻辑控制器
│ ├── models/ # 数据模型
│ ├── middleware/ # 中间件（鉴权、验证等）
│ ├── config/ # 配置文件
│ └── public/avatar/ # 静态资源存储
└── frontend/ # 前端应用├── src/│ ├── store/modules/ # Vuex 状态管理模块│ ├── utils/request.js # 统一请求封装│ └── ... # 组件、视图等└── public/ # 静态资源数据库设计与实现
数据库初始化
CREATE DATABASE ywt_task_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;根据业务需求，设计了用户表（users）和任务表（tasks）等核心数据表：
- users 表：存储用户信息，包括用户名、密码哈希、头像路径等
- tasks 表：存储任务数据，包含任务内容、状态、创建时间、用户关联等
- 枚举表：管理系统中的固定枚举值，如任务状态、优先级等
数据库连接配置位于 backend/config/database.js，建议在实际部署时使用环境变量替代硬编码配置。
后端 API 架构
认证模块（/auth）
// JWT 鉴权中间件示例
const authenticateToken = async (ctx, next) => {
const token = ctx.cookies.get('token') || ctx.headers.authorization;
// token 验证逻辑
await next();
};核心 API 端点：
- POST /auth/login - 用户登录，生成 JWT Token
- POST /auth/register - 用户注册
- POST /auth/refresh - Token 刷新
- POST /auth/logout - 用户注销
用户管理模块（/user）
- GET /user/list - 获取用户列表（需鉴权）
- POST /user/add - 创建用户
- PUT /user/update/:id - 更新用户信息
- POST /user/editAvatar - 头像上传（multipart/form-data）
任务管理模块（/task）
- GET /task/list - 获取任务列表，支持分页和过滤
- POST /task/add - 创建新任务
- PUT /task/update/:id - 更新任务状态或内容
- DELETE /task/delete/:id - 删除任务
枚举配置模块（/enum）
- GET /enum/all - 获取所有枚举配置
- GET /enum/:enumName - 按名称获取特定枚举
前端实现细节
状态管理设计
// Vuex store 模块示例
const taskModule = {
state: () => ({
tasks: [],
loading: false
}),
mutations: {
SET_TASKS(state, tasks) {
state.tasks = tasks;
}
},
actions: {
async fetchTasks({ commit }) {
const response = await api.get('/task/list');
commit('SET_TASKS', response.data);
}
}
};请求拦截器配置
// src/utils/request.js
import axios from 'axios';
const request = axios.create({
baseURL: 'http://localhost:3010',
timeout: 10000
});
// 请求拦截器：自动添加 Token
request.interceptors.request.use(config => {
const token = store.state.user.token;
if (token) {
config.headers.Authorization = `Bearer ${token}`;
}
return config;
});
// 响应拦截器：统一错误处理
request.interceptors.response.use(
response => response,
error => {
if (error.response.status === 401) {
// Token 过期，跳转到登录页
router.push('/login');
}
return Promise.reject(error);
}
);组件化开发实践
- 任务列表组件：展示任务卡片，支持状态筛选
- 任务表单组件：创建和编辑任务的模态框
- 用户配置组件：管理用户信息和头像上传
全链路数据流
1.用户交互：前端界面触发动作（如添加任务）
2.状态管理：Vuex action 发起 API 请求
3.API 调用：Axios 发送请求到后端对应端点
4.中间件处理：JWT 鉴权、参数验证
5.业务逻辑：Controller 处理业务规则
6.数据持久化：Model 层与 MySQL 交互
7.响应返回：数据经由相同路径返回前端
8.界面更新：Vue 组件响应式更新界
环境配置与部署
环境变量管理
创建 .env 文件管理敏感信息：
COOKIE_SECRET=your_cookie_secret
JWT_SECRET=your_jwt_secret
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=your_db_password
DB_NAME=ywt_task_db
PORT=3010开发环境启动
# 后端服务
cd backend
npm install
npm start # 使用 nodemon 监听文件变化
# 前端开发服务器
cd ../frontend
npm install
npm run dev # Vite 开发服务器，默认端口 5173静态资源处理
后端通过 KoaStaticCache 中间件提供静态资源服务：
app.use(staticCache(path.join(__dirname, 'public'), {
prefix: '/public',
maxAge: 365 * 24 * 60 * 60
}));开发经验与最佳实践
1. 前后端分离架构优势
- 前端后端可并行开发，通过 API 契约进行协作
- 前端可使用 Mock 数据进行开发，不阻塞后端进度
- 技术栈选择灵活，可独立升级优化
2. 鉴权安全实践
- JWT Token 存储在 HttpOnly Cookie 中，防止 XSS 攻击
- Token 设置合理的过期时间，提供刷新机制
- 密码使用 bcrypt 等算法进行哈希存储
3.错误处理统一化
- 前端实现统一的错误处理拦截器
- 后端返回标准化的错误响应格式
- 日志记录系统运行异常
4.数据库设计考量
- 使用 utf8mb4 字符集支持完整 Unicode
- 为常用查询字段添加索引
- 设计适当的外键关系保证数据一致性
GitCode源码
- 前端：https://gitcode.com/qnxb0628/ywt-task-console
- 后端：https://gitcode.com/qnxb0628/ywt-task-pro
演示效果
项目总结
通过这个待办事项系统的全链路开发，我们实践了现代 Web 应用的完整开发流程。从前端的组件化开发、状态管理，到后端的 API 设计、中间件链、数据库操作，每个环节都体现了软件工程的最佳实践。
这种全栈项目经验不仅帮助开发者理解技术栈的协同工作方式，更重要的是培养了系统化思维——从用户界面到数据存储的完整视角。对于希望提升全栈能力的开发者而言，实现这样一个端到端的项目无疑是极佳的练手机会。
项目代码已开源，开发者可以根据实际需求进行功能扩展，如添加任务分类、团队协作、消息通知等高级功能，进一步深化全栈开发技能。
最后：个人学习的一点记录，<如有疏漏或谬误，望码友能不吝赐教~>