🔍 智能失物招领系统 (Lost & Found Platform)

一个基于 Spring Boot 的现代化失物招领管理平台

功能特性 • 技术架构 • 快速开始 • API 文档 • 项目结构

📖 项目简介

智能失物招领系统是一个功能完善、架构清晰的校园失物招领管理平台。系统采用前后端分离架构，后端基于 Spring Boot 3.x 构建，提供 RESTful API 接口，支持失物发布、招领信息管理、智能搜索、图片上传等核心功能。

🎯 项目亮点

🔐 安全可靠: JWT Token 认证 + Redis 会话管理，支持登出失效机制
📧 邮件验证: 集成邮件服务，注册时发送验证码，保障账户安全
🖼️ 图片管理: 完善的文件上传系统，支持多种图片格式，自动生成访问 URL
🔍 智能搜索: 多条件组合查询，支持关键词、位置、时间范围、状态筛选
📄 分页查询: 高效的分页机制，优化大数据量场景下的查询性能
🎨 状态管理: 完整的失物状态流转（丢失→已归还→已完成）
🛡️ 异常处理: 全局异常处理机制，统一响应格式，友好的错误提示
📱 RESTful API: 标准的 RESTful 接口设计，易于前端集成

✨ 功能特性

👤 用户管理

✅ 邮箱注册（验证码验证）
✅ 用户登录/登出
✅ 个人信息管理
✅ 头像上传更新
✅ 用户信息查询

📦 失物招领

✅ 发布失物信息
✅ 发布招领信息
✅ 信息编辑更新
✅ 状态流转管理（丢失/拾到/已归还/已完成）
✅ 失物信息删除
✅ 我的发布列表

🔍 搜索功能

✅ 关键词搜索（标题、描述）
✅ 位置筛选
✅ 状态筛选
✅ 时间范围查询
✅ 多条件组合搜索
✅ 分页查询

🖼️ 文件管理

✅ 单文件上传
✅ 多文件上传
✅ 文件删除
✅ 图片格式验证
✅ 文件大小限制
✅ 按日期分类存储

💬 实时聊天

✅ WebSocket 实时通信
✅ HTTP API 降级方案
✅ 离线消息存储
✅ 上线自动推送离线消息
✅ 会话列表管理
✅ 未读消息统计
✅ 消息已读标记
✅ 文本和图片消息

🏗️ 技术架构

后端技术栈

技术	版本	说明
Java	21	编程语言
Spring Boot	3.5.6	应用框架
Spring Data JPA	3.5.6	ORM 框架
MySQL	9.4+	关系型数据库
Redis	Latest	缓存数据库
Spring Mail	3.5.6	邮件服务
Spring WebSocket	3.5.6	WebSocket 支持
Hutool	5.8.40	Java 工具库
Lombok	Latest	简化代码
Maven	3.8+	项目管理

核心特性

分层架构: Controller → Service → DAO，职责清晰
RESTful API: 标准的 REST 接口设计
JWT 认证: 无状态的 Token 认证机制
Redis 缓存: 验证码存储、Token 管理
JPA 审计: 自动记录创建和更新时间
全局异常处理: 统一的异常处理和响应格式
参数校验: 基于 Validation 的参数校验
文件上传: 支持图片上传和管理

🚀 快速开始

环境要求

JDK 21+
Maven 3.8+
MySQL 9.4+
Redis 6.0+

安装步骤

克隆项目

git clone https://github.com/your-username/lost-and-found.git
cd lost-and-found

配置数据库

创建数据库：

CREATE DATABASE lnf CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

执行初始化脚本：

mysql -u root -p lnf < database-init.sql

配置应用

编辑 src/main/resources/application.yml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/lnf
    username: your_username
    password: your_password
  
  data:
    redis:
      host: localhost
      port: 6379
  
  mail:
    host: smtp.qq.com
    username: your_email@qq.com
    password: your_email_password

jwt:
  key: YOUR_SECRET_KEY
  exp: 24

file:
  upload:
    base-url: http://localhost:8080

启动 Redis

redis-server

运行项目

mvn clean install
mvn spring-boot:run

访问应用

http://localhost:8080

📚 API 文档

完整的 API 接口文档请查看：API-Documentation.md

快速预览

用户接口

POST /user/register - 用户注册
POST /user/login - 用户登录
GET /user/me - 获取当前用户信息
PUT /user/me - 更新用户信息

失物招领接口

POST /item - 发布失物/招领
GET /item/search - 搜索失物
GET /item/my - 我的发布
PUT /item/{id}/returned - 标记已归还

文件上传接口

POST /file/upload - 上传图片
DELETE /file/delete - 删除图片

聊天消息接口

WebSocket /ws/message - WebSocket 实时通信
POST /api/messages/send - 发送消息（HTTP 降级）
GET /api/messages/conversation/{userId} - 获取聊天记录
PUT /api/messages/read/{userId} - 标记已读
GET /api/messages/conversations - 获取会话列表
GET /api/messages/unread-count - 获取未读数

💡 聊天功能架构: 详见 CHAT-ARCHITECTURE.md 和 CHAT-TEST-GUIDE.md

📁 项目结构

lost-and-found/
├── src/main/java/com/lost/find/lnf/
│   ├── common/              # 公共类
│   │   └── Result.java      # 统一响应格式
│   ├── config/              # 配置类
│   │   ├── JpaConfig.java   # JPA 配置
│   │   ├── WebConfig.java   # Web 配置
│   │   └── ResourceConfig.java  # 静态资源配置
│   ├── controller/          # 控制器层
│   │   ├── UserCtl.java     # 用户控制器
│   │   ├── LnfItemCtl.java  # 失物招领控制器
│   │   ├── FileCtl.java     # 文件上传控制器
│   │   └── MessageController.java  # 消息控制器
│   ├── service/             # 服务层
│   │   ├── UserService.java
│   │   ├── LnfItemService.java
│   │   ├── EmailService.java
│   │   ├── FileService.java
│   │   └── MessageService.java
│   ├── Dao/                 # 数据访问层
│   │   ├── UserDao.java
│   │   ├── LnfItemDao.java
│   │   ├── MessageDao.java
│   │   └── ConversationDao.java
│   ├── entry/               # 实体类
│   │   ├── User.java
│   │   ├── LnfItem.java
│   │   ├── Message.java
│   │   └── Conversation.java
│   ├── websocket/           # WebSocket 处理
│   │   └── WebSocketHandler.java
│   ├── dto/                 # 数据传输对象
│   │   ├── LoginRequest.java
│   │   ├── RegisterRequest.java
│   │   └── lnfitem/
│   ├── vo/                  # 视图对象
│   │   ├── LoginResponse.java
│   │   ├── UserInfoResponse.java
│   │   └── LnfItemResponse.java
│   ├── exception/           # 异常处理
│   │   ├── BusinessException.java
│   │   └── GlobalExceptionHandler.java
│   ├── interceptor/         # 拦截器
│   │   └── AuthInterceptor.java
│   └── util/                # 工具类
│       ├── JWTHelper.java
│       ├── UserContext.java
│       └── BeanOptionalCopier.java
├── src/main/resources/
│   ├── application.yml      # 应用配置
│   ├── static/uploads/      # 文件上传目录
│   └── templates/email/     # 邮件模板
├── database-init.sql        # 数据库初始化脚本
├── API-Documentation.md     # API 接口文档
├── CHAT-ARCHITECTURE.md     # 聊天功能架构文档
├── CHAT-TEST-GUIDE.md       # 聊天功能测试指南
├── test.http                # HTTP 测试文件
├── websocket-test.html      # WebSocket 测试页面
└── pom.xml                  # Maven 配置

🔧 核心功能实现

1. JWT 认证机制

// Token 生成
String token = JWTHelper.createToken(userId, email, name);

// Token 验证
boolean isValid = JWTHelper.verify(token);

// 获取用户信息
Integer userId = UserContext.getCurrentUserId();

2. 邮件验证码

// 发送验证码
emailService.sendVerificationCode(email);

// 验证码校验
boolean isValid = emailService.verifyCode(email, code);

3. 文件上传

// 上传文件
String url = fileService.uploadImage(file);
// 返回: http://localhost:8080/uploads/2025/10/11/uuid.jpg

// 删除文件
fileService.deleteImage(url);

4. 分页查询

// 构建分页参数
Pageable pageable = PageRequest.of(page, size, Sort.by("createdAt").descending());

// 执行查询
Page<LnfItem> result = lnfItemDao.findByConditions(..., pageable);

5. WebSocket 实时通信

// 连接 WebSocket
ws://localhost:8080/ws/message?token=YOUR_JWT_TOKEN

// 发送消息
{
  "receiverId": 2,
  "type": "TEXT",
  "content": "你好"
}

// 接收消息（自动推送）
{
  "id": 1,
  "senderId": 1,
  "senderName": "张三",
  "content": "你好",
  "createdAt": "2025-10-14T10:30:00"
}

🎨 数据库设计

用户表 (users)

字段	类型	说明
id	INT	主键
email	VARCHAR(64)	邮箱（唯一）
password	VARCHAR(128)	密码
name	VARCHAR(32)	用户名
avatar	VARCHAR(255)	头像 URL
phone	VARCHAR(11)	手机号
created	DATETIME	创建时间
updated	DATETIME	更新时间

失物招领表 (lnf)

字段	类型	说明
id	INT	主键
title	VARCHAR(64)	标题
description	TEXT	描述
img_url	VARCHAR(1024)	图片 URL
time	DATETIME	丢失/拾到时间
location	VARCHAR(255)	位置
publisher_id	INT	发布者 ID
finder_id	INT	找到者 ID
status	VARCHAR(10)	状态
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

消息表 (messages)

字段	类型	说明
id	INT	主键
sender_id	INT	发送者 ID
receiver_id	INT	接收者 ID
type	VARCHAR(10)	消息类型
content	TEXT	消息内容
is_read	BOOLEAN	是否已读
created_at	DATETIME	创建时间

会话表 (conversations)

字段	类型	说明
id	INT	主键
user1_id	INT	用户1 ID
user2_id	INT	用户2 ID
last_message	TEXT	最后一条消息
unread_count1	INT	用户1未读数
unread_count2	INT	用户2未读数
created_at	DATETIME	创建时间
updated_at	DATETIME	更新时间

🧪 测试

使用 HTTP 文件测试

项目包含 test.http 文件，可以使用 IDEA HTTP Client 进行测试：

### 用户登录
POST http://localhost:8080/user/login
Content-Type: application/json

{
  "email": "test@example.com",
  "password": "123456"
}

### 搜索失物
GET http://localhost:8080/item/search?keyword=钱包&page=0&size=10

使用 Postman 测试

导入 API-Documentation.md 中的接口示例到 Postman 进行测试。

📝 开发规范

代码规范

遵循阿里巴巴 Java 开发手册
使用 Lombok 简化代码
统一的异常处理
RESTful API 设计规范

命名规范

Controller: XxxCtl
Service: XxxService
DAO: XxxDao
DTO: XxxRequest/XxxResponse
Entity: 实体名称

Git 提交规范

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具变动

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

👨‍💻 作者

Your Name

GitHub: @your-username
Email: your-email@example.com

🙏 致谢

感谢以下开源项目：

📮 联系方式

如有问题或建议，欢迎通过以下方式联系：

提交 Issue
发送邮件至：your-email@example.com

⭐ 如果这个项目对你有帮助，请给一个 Star！⭐

Made with ❤️ by Your Name

Name		Name	Last commit message	Last commit date
.mvn/wrapper		.mvn/wrapper
src		src
.gitattributes		.gitattributes
.gitignore		.gitignore
API-Documentation.md		API-Documentation.md
README.md		README.md
database-init.sql		database-init.sql
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml
test.http		test.http

Latest commit

History

Folders and files

Repository files navigation