小说阅读器 - 前端项目

基于 Vue 3 + TypeScript + Vite 构建的现代化小说阅读器前端应用。

📚 技术栈

• 框架: Vue 3 (Composition API)
• 语言: TypeScript
• 构建工具: Vite
• UI组件库: Element Plus
• 状态管理: Pinia
• 路由: Vue Router 4
• HTTP客户端: Axios
• 样式: SCSS

✨ 核心特性

• 🎯 完整的阅读体验：图书浏览、搜索、上传、阅读一体化
• 🔐 安全可靠：JWT认证、权限控制、数据验证
• 📱 响应式设计：完美支持桌面端、平板、手机
• ⚡ 高性能：Vite快速构建、按需加载、路由懒加载
• 🎨 现代化UI：Element Plus组件库、流畅动画、优雅交互
• 🔄 实时同步：阅读进度自动保存、数据即时更新

🚀 快速开始

环境要求

• Node.js >= 16.0.0
• npm >= 7.0.0

安装依赖

npm install

开发模式

npm run dev

应用将在 http://localhost:3003 运行

构建生产版本

npm run build

预览生产构建

npm run preview

📁 项目结构

novel-reader-web/
├── src/
│   ├── api/                # API接口封装
│   │   ├── user.ts         # 用户相关接口（登录、注册、获取信息）
│   │   ├── book.ts         # 图书相关接口（列表、详情、上传、更新、删除、章节）
│   │   └── bookshelf.ts    # 书架相关接口（添加、移除、进度同步）
│   ├── views/              # 页面组件
│   │   ├── Home.vue        # 首页（公开访问、搜索功能）
│   │   ├── Login.vue       # 登录页
│   │   ├── Register.vue    # 注册页
│   │   ├── books/          # 图书相关页面
│   │   │   ├── List.vue    # 图书列表（分页、搜索、筛选）
│   │   │   └── Detail.vue  # 图书详情（编辑、加入书架、开始阅读）
│   │   ├── Bookshelf.vue   # 我的书架（阅读进度、继续阅读）
│   │   ├── Reader.vue      # 阅读器（章节切换、目录、主题、字体调整）
│   │   ├── Upload.vue      # 上传图书（文件验证、进度提示）
│   │   └── Profile.vue     # 个人中心（修改密码、用户信息）
│   ├── components/         # 公共组件
│   ├── stores/             # Pinia状态管理
│   │   └── user.ts         # 用户状态（登录、登出、信息缓存）
│   ├── router/             # 路由配置（路由守卫、权限控制）
│   ├── utils/              # 工具函数
│   │   └── request.ts      # Axios封装（请求/响应拦截器、错误处理）
│   ├── types/              # TypeScript类型定义
│   ├── App.vue             # 根组件
│   └── main.ts             # 应用入口
├── vite.config.ts          # Vite配置（代理、插件）
├── tsconfig.json           # TypeScript配置
├── .env.development        # 开发环境变量
├── .env.production         # 生产环境变量
└── package.json

🔧 功能模块详解

1. 用户模块 ✅

• 用户登录：用户名/密码登录，JWT Token认证
• 用户注册：新用户注册，表单验证
• 个人中心：查看用户信息、修改密码
• 会话管理：Token持久化、自动续期、401自动跳转
• 状态恢复：页面刷新后自动恢复登录状态

2. 图书模块 ✅

• 图书列表：分页展示、关键词搜索、高级筛选
• 图书详情：完整信息展示、字数统计、章节数
• 图书上传：
  • 支持 TXT、EPUB、PDF 格式
  • 文件大小限制 195MB（后端限制 200MB）
  • 书名、作者必填验证
  • 拖拽上传、进度提示
• 图书更新：仅所有者可编辑书名、作者、简介
• 图书删除：仅所有者可删除
• 智能刷新：上传/更新后自动刷新列表，无需手动刷新页面

3. 书架模块 ✅

• 我的书架：个人收藏图书列表
• 添加书架：一键加入书架
• 移除书架：从书架中删除
• 阅读进度：
  • 自动保存当前阅读章节
  • 显示阅读进度百分比
  • "继续阅读"快速跳转

4. 阅读器模块 ✅

• 章节阅读：真实API加载章节内容
• 章节导航：
  • 上一章/下一章按钮
  • 目录侧边栏快速跳转
  • 键盘快捷键支持（← →）
• 阅读设置：
  • 字体大小调整（14px - 24px）
  • 主题切换（浅色/深色/护眼绿）
  • 行间距调整
• 进度同步：自动保存阅读进度到服务器
• 性能优化：章节内容缓存、平滑滚动

5. 首页模块 ✅

• 公开访问：未登录用户可浏览
• 图书搜索：全局搜索功能
• 热门推荐：展示热门图书
• 无认证依赖：不调用需要认证的API

🌐 API对接规范

接口通信规范

• 统一POST方法：所有接口使用POST方法（遵循后端规范）
• 参数传递：通过请求体（request body）传递参数
• 响应格式：统一 { code, message, data } 结构
• 认证机制：请求头携带 Authorization: Bearer {token}

服务端口配置

服务	端口	说明
前端开发服务器	3003	Vite Dev Server
网关服务	8088	Spring Cloud Gateway
用户服务	8081	用户认证、信息管理
图书服务	8082	图书CRUD、章节管理
书架服务	8083	书架管理、进度同步

环境变量

开发环境 (.env.development)

VITE_API_BASE_URL=/api

生产环境 (.env.production)

VITE_API_BASE_URL=http://your-domain.com/api

🎨 UI设计规范

设计原则

• 扁平化设计：简洁现代、视觉层次清晰
• 一致性：统一的配色、间距、圆角、阴影
• 响应式：适配各种屏幕尺寸
• 无障碍：合理的对比度、焦点管理

配色方案

• 主色调：#409EFF（Element Plus Primary）
• 成功色：#67C23A
• 警告色：#E6A23C
• 危险色：#F56C6C
• 背景色：#F5F7FA（浅灰）

组件规范

• 卡片：白色背景、8px圆角、轻微阴影
• 按钮：Primary/Success/Warning/Danger四种类型
• 表单：清晰的标签、即时的验证反馈
• 导航：渐变色头部、粘性定位

📱 响应式断点

设备	断点	布局策略
手机	< 640px	单列布局、简化导航
平板	640px - 1024px	双列布局、折叠菜单
桌面	> 1024px	多列布局、完整功能

🔐 安全与认证

JWT认证流程

1. 用户登录 → 获取Token
2. Token存储到localStorage
3. 每次请求自动携带Token（请求拦截器）
4. 401响应 → 清除Token → 跳转登录页
5. 页面刷新 → 检查Token → 自动获取用户信息

权限控制

• 路由守卫：未登录用户无法访问受保护页面
• 组件级权限：根据用户身份显示/隐藏操作按钮
• 数据级权限：仅图书所有者可编辑/删除

数据安全

• 密码加密：后端BCrypt加密存储
• XSS防护：Vue自动转义、避免v-html
• CSRF防护：Token认证机制

🚀 性能优化

构建优化

• 代码分割：路由懒加载、按需加载
• Tree Shaking：移除未使用的代码
• 压缩：生产环境自动压缩JS/CSS

运行时优化

• 组件缓存：keep-alive缓存常用组件
• 防抖节流：搜索输入、滚动事件
• 图片懒加载：图书封面延迟加载
• API缓存：避免重复请求相同数据

网络优化

• 请求合并：批量操作合并请求
• 超时控制：普通请求10s、上传60s
• 错误重试：网络失败自动重试

🧪 测试建议

手动测试清单

• 用户注册/登录/登出
• 图书搜索/筛选/分页
• 图书上传（小文件/大文件）
• 图书编辑/删除（权限验证）
• 加入书架/移除
• 阅读器功能（章节切换、主题、字体）
• 阅读进度同步
• 响应式布局（不同设备）
• 错误处理（网络异常、401等）

浏览器兼容性

• ✅ Chrome (推荐)
• ✅ Firefox
• ✅ Safari
• ✅ Edge
• ⚠️ IE不支持

🛠️ 开发工具推荐

VS Code 插件

• Volar：Vue 3官方推荐的TypeScript支持
• ESLint：代码质量检查
• Prettier：代码格式化
• Auto Rename Tag：自动重命名HTML标签
• Path Intellisense：路径自动补全

调试工具

• Vue DevTools：Vue组件调试
• Chrome DevTools：Network、Console调试
• Postman/Apifox：API接口测试

📝 常见问题

Q: 上传图书后列表没有刷新？

A: 已实现自动刷新机制，通过URL时间戳参数触发。如仍有问题，请检查控制台日志。

Q: 登录后刷新页面需要重新登录？

A: 系统会自动恢复登录状态。如果失效，请检查localStorage中的token是否存在。

Q: 阅读器章节内容为空？

A: 确保后端章节接口正常，检查Network面板的API响应。

Q: 跨域问题？

A: 开发环境通过Vite代理解决，生产环境需配置CORS或Nginx反向代理。

🤝 贡献指南

1. Fork本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

📄 License

MIT License

👥 联系方式

如有问题或建议，请提Issue或联系开发者。

---

最后更新时间: 2026-05-06