校园二手交易平台

一个面向高校学生的二手商品交易全栈项目，支持用户认证、商品发布、商品搜索、图片上传、收藏管理、订单管理和热门商品缓存。项目采用前后端分离架构，前端使用 Vue 3 构建交互页面，后端使用 FastAPI 提供 RESTful API，并通过 Docker Compose 集成 MySQL、Redis、Nginx 完成容器化部署。

技术栈

层级	技术
前端	Vue 3、Vite、Vue Router、Lucide Icons
后端	Python、FastAPI、SQLAlchemy、Pydantic、JWT
数据库	MySQL 8.4
缓存	Redis 7.4
部署	Docker、Docker Compose、Nginx
认证	JWT Bearer Token

核心功能

• 用户注册、登录、JWT 身份认证
• 商品发布、编辑、软删除、详情查询
• 商品图片上传与静态资源访问
• 商品关键词搜索、分类筛选、分页查询
• 收藏夹添加、取消、列表查询
• 订单创建、订单列表、订单详情、订单状态更新
• Redis 缓存热门商品列表，降低数据库查询压力
• Docker Compose 一键启动前端、后端、MySQL、Redis、Nginx

项目亮点

• 前后端分离：Vue 前端通过 /api 调用 FastAPI 后端接口，结构清晰，便于扩展。
• RESTful API 设计：认证、商品、收藏、订单模块按资源划分，接口职责明确。
• JWT 鉴权：登录后签发访问令牌，受保护接口通过 Bearer Token 识别当前用户。
• 缓存优化：热门商品列表使用 Redis 缓存，减少重复查询。
• 容器化部署：使用 Docker Compose 编排五个服务，降低本地运行和部署成本。
• Nginx 统一入口：http://localhost 访问前端，/api 和 /uploads 反向代理到后端。

目录结构

.
├── app/                    # FastAPI 后端
│   ├── api/                # 接口路由
│   ├── core/               # 配置与安全模块
│   ├── db/                 # MySQL / Redis 连接
│   ├── models/             # SQLAlchemy 数据模型
│   ├── schemas/            # Pydantic 数据结构
│   └── main.py             # 应用入口
├── frontend/               # Vue 3 前端
│   ├── src/
│   │   ├── components/     # 通用组件
│   │   ├── views/          # 页面视图
│   │   ├── api.js          # API 请求封装
│   │   └── main.js         # 前端入口
│   └── Dockerfile
├── uploads/                # 商品图片上传目录
├── docker-compose.yml      # 服务编排
├── Dockerfile              # 后端镜像构建
├── nginx.conf              # 总入口 Nginx 配置
└── requirements.txt        # Python 依赖

快速启动

确保已经安装并启动 Docker Desktop，然后在项目根目录执行：

docker compose -p campus_trade up -d --build

启动成功后访问：

• 前端页面：http://localhost
• 后端接口文档：http://localhost:8000/docs
• ReDoc 文档：http://localhost:8000/redoc

首次启动会自动创建 MySQL 数据卷并初始化数据表。注册用户后即可在前端完成发布商品、浏览商品、收藏商品和创建订单等流程。

项目启动时会写入一组用于个人学习展示的官方参考商品，商品图片和信息参考 Apple 中国官网页面。这些商品会以 on_sale 状态进入数据库，可正常浏览详情和参与接口流程。本项目不是 Apple 官方项目，不涉及商业用途。

停止服务：

docker compose -p campus_trade down

查看运行状态：

docker ps

查看后端日志：

docker logs campus_trade_api

本地开发

后端

pip install -r requirements.txt
uvicorn app.main:app --reload

后端默认运行在：

http://localhost:8000

前端

cd frontend
npm install
npm run dev

前端开发服务默认运行在：

http://localhost:5173

主要接口

模块	方法	路径	说明
认证	POST	/api/auth/register	用户注册
认证	POST	/api/auth/login	用户登录
认证	GET	/api/auth/me	获取当前用户
商品	POST	/api/products	发布商品
商品	GET	/api/products	商品搜索与分页
商品	GET	/api/products/hot	热门商品
商品	GET	/api/products/{product_id}	商品详情
商品	PUT	/api/products/{product_id}	修改商品
商品	DELETE	/api/products/{product_id}	删除商品
商品	POST	/api/products/{product_id}/image	上传商品图片
收藏	POST	/api/favorites/{product_id}	添加收藏
收藏	GET	/api/favorites	收藏列表
收藏	DELETE	/api/favorites/{product_id}	取消收藏
订单	POST	/api/orders	创建订单
订单	GET	/api/orders	我的订单
订单	GET	/api/orders/{order_id}	订单详情
订单	PATCH	/api/orders/{order_id}/status	更新订单状态

环境变量

可参考 .env.example：

SECRET_KEY=change-me-in-production
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=campus
MYSQL_PASSWORD=campus123
MYSQL_DATABASE=campus_trade
REDIS_HOST=localhost
REDIS_PORT=6379
UPLOAD_DIR=uploads
BASE_URL=http://localhost:8000

适用场景

该项目适合作为 Python Web 全栈开发练习、校园交易类系统原型、后端接口项目展示和简历项目扩展基础。后续可继续扩展管理员审核、商品举报、站内消息、支付流程、对象存储、Alembic 数据库迁移和自动化测试。

开源与迭代

本项目已按开源学习项目进行维护，欢迎 Fork、学习和二次开发。

• 版本记录：CHANGELOG.md
• 后续计划：ROADMAP.md
• 贡献指南：CONTRIBUTING.md
• 开源协议：MIT License

建议迭代方式：

git checkout -b feature/your-feature
git add .
git commit -m "feat: describe your change"
git push origin feature/your-feature

正式版本会通过 Git Tag 和 GitHub Releases 记录，例如：

git tag v1.0.0
git push origin v1.0.0

仓库地址

https://github.com/Ringo538/campus-secondhand-platform