📚 LocoBook - 图书管理系统

一个基于 Rust Loco 后端和 Vue 3 前端的现代化图书管理系统。

✨ 特性

• 🔐 用户认证: JWT 基于 token 的登录/注册系统
• 📖 图书管理: 浏览、阅读图书,支持分页加载
• 📝 阅读记录: 自动保存阅读进度和历史记录
• 🎨 现代 UI: 使用 Tailwind CSS 4 构建的响应式界面
• ⚡ 高性能: Rust 后端提供快速稳定的 API 服务
• 🔧 开发友好: Vite 统一管理前后端,一键启动

🛠️ 技术栈

后端

• 框架: Loco.rs 0.16 (基于 Axum + SeaORM)
• 语言: Rust
• 数据库: SQLite
• 认证: JWT
• ORM: SeaORM

前端

• 框架: Vue 3.5 (Composition API)
• 构建工具: Vite 8.0
• 路由: Vue Router 4.5
• 状态管理: Pinia 2.3
• HTTP 客户端: Axios 1.7
• 样式: Tailwind CSS 4.2

📦 快速开始

前置要求

• Rust (最新稳定版)
• Node.js (v18+)
• Cargo Loco CLI

安装

1. 克隆仓库

git clone http://macrocc.com:3000/macrocc/locobook.git
cd locobook

2. 安装前端依赖

npm install

3. 初始化数据库

cd src-loco
cargo loco db migrate
cd ..

运行开发服务器

一键启动前后端:

npm run dev

这将:

• 启动后端服务器 (http://localhost:5150)
• 启动前端开发服务器 (http://localhost:5173)
• 自动打开浏览器

单独启动:

# 仅启动后端
cd src-loco && cargo loco start

# 仅启动前端
npm run dev:frontend

重启服务

修改 Rust 代码后需要重启:

npm run restart

📁 项目结构

locobook/
├── src-loco/              # Rust Loco 后端
│   ├── src/
│   │   ├── controllers/   # API 控制器
│   │   │   ├── auth.rs    # 认证相关接口
│   │   │   ├── books.rs   # 图书管理接口
│   │   │   └── reading.rs # 阅读记录接口
│   │   ├── models/        # 数据模型
│   │   │   ├── users.rs
│   │   │   ├── books.rs
│   │   │   └── reading_records.rs
│   │   ├── views/         # 响应视图
│   │   └── app.rs         # 应用配置
│   ├── migration/         # 数据库迁移
│   ├── tests/            # 后端测试
│   └── config/           # 配置文件
├── src/                  # Vue 3 前端
│   ├── views/            # 页面组件
│   │   ├── Login.vue
│   │   ├── Register.vue
│   │   ├── BookList.vue
│   │   ├── BookReader.vue
│   │   └── ReadingHistory.vue
│   ├── components/       # 通用组件
│   │   └── Navbar.vue
│   ├── api/             # API 封装
│   ├── router/          # 路由配置
│   └── main.js          # 入口文件
├── package.json         # 前端依赖和脚本
├── vite.config.js       # Vite 配置
└── README.md

🔌 API 接口

认证接口

方法	路径	描述	认证
POST	/api/auth/register	用户注册	❌
POST	/api/auth/login	用户登录	❌
POST	/api/auth/verify	验证邮箱	❌
GET	/api/auth/current	获取当前用户	✅

图书接口

方法	路径	描述	认证
GET	/api/books	获取图书列表(分页)	❌
GET	/api/books/:id	获取单本图书	❌
POST	/api/books	创建图书	✅
PUT	/api/books/:id	更新图书	✅
DELETE	/api/books/:id	删除图书	✅

分页参数:

GET /api/books?page=1&per_page=12

响应格式:

{
  "books": [...],
  "total": 100,
  "page": 1,
  "per_page": 12,
  "total_pages": 9
}

阅读记录接口

方法	路径	描述	认证
POST	/api/reading/record	保存阅读进度	✅
GET	/api/reading/history	获取阅读历史	✅

🧪 测试

运行后端测试

cd src-loco

# 运行所有测试
cargo test

# 运行特定模块测试
cargo test books
cargo test auth

# 运行单个测试
cargo test can_list_books_with_pagination

# 显示测试输出
cargo test -- --nocapture

测试文件位于 src-loco/tests/requests/:

• auth.rs - 认证接口测试
• books.rs - 图书接口测试
• prepare_data.rs - 测试数据准备

🎨 前端路由

路径	组件	描述	认证
/login	Login	登录页面	❌
/register	Register	注册页面	❌
/	BookList	图书列表	✅
/book/:id	BookReader	图书阅读器	✅
/history	ReadingHistory	阅读历史	✅

⚙️ 配置

后端配置

配置文件位于 src-loco/config/:

• development.yaml - 开发环境
• test.yaml - 测试环境
• production.yaml - 生产环境

主要配置项:

server:
  port: 5150
  
database:
  uri: sqlite://book-manager_development.sqlite?mode=rwc
  auto_migrate: true
  
auth:
  jwt:
    secret: your-secret-key
    expiration: 604800  # 7 days

前端配置

Vite 配置在 vite.config.js:

{
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://localhost:5150',
        changeOrigin: true
      }
    }
  },
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
}

🚀 部署

构建前端

npm run build

构建产物将输出到 dist/ 目录。

构建后端

cd src-loco
cargo build --release

二进制文件位于 target/release/book_manager-cli。

生产环境运行

# 后端
cd src-loco
cargo loco start --env production

# 前端 (使用静态文件服务器)
npm run preview

🤝 贡献

欢迎提交 Issue 和 Pull Request!

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

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

• Loco.rs - 优秀的 Rust Web 框架
• Vue.js - 渐进式 JavaScript 框架
• Tailwind CSS - 实用优先的 CSS 框架
• SeaORM - Rust ORM 框架

---

Made with ❤️ using Rust & Vue