Skip to content

API-Documentation.md

Latest commit

 

History

History
1162 lines (985 loc) · 22.5 KB

API-Documentation.md

File metadata and controls

1162 lines (985 loc) · 22.5 KB
Raw

失物招领系统 API 接口文档

基础信息

  • Base URL: http://localhost:8080
  • 认证方式: Bearer Token
  • 请求头: Authorization: Bearer {token}

一、用户相关接口

1.1 发送验证码

  • URL: /user/code
  • 方法: GET
  • 需要Token: ❌ 否
  • 参数:
    • email (query): 邮箱地址

请求示例:

GET /user/code?email=test@example.com

响应示例:

{
  "code": 200,
  "message": "发送成功",
  "data": null
}

1.2 用户注册

  • URL: /user/register
  • 方法: POST
  • 需要Token: ❌ 否
  • Content-Type: application/json

请求示例:

{
  "email": "test@example.com",
  "password": "123456",
  "name": "张三",
  "code": "123456"
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "email": "test@example.com",
    "name": "张三",
    "avatar": null,
    "phone": null,
    "created": "2025-10-11T10:00:00",
    "updated": "2025-10-11T10:00:00"
  }
}

1.3 用户登录

  • URL: /user/login
  • 方法: POST
  • 需要Token: ❌ 否
  • Content-Type: application/json

请求示例:

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

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "test@example.com",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

1.4 用户登出

  • URL: /user/logout
  • 方法: POST
  • 需要Token: ✅ 是

请求示例:

POST /user/logout
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "登出成功",
  "data": null
}

1.5 获取当前用户信息

  • URL: /user/me
  • 方法: GET
  • 需要Token: ✅ 是

请求示例:

GET /user/me
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "test@example.com",
    "phone": "13800138000",
    "avatar": "http://localhost:8080/uploads/2025/10/11/xxx.jpg"
  }
}

1.6 更新用户信息

  • URL: /user/me
  • 方法: PUT
  • 需要Token: ✅ 是
  • Content-Type: application/json

请求示例:

{
  "name": "李四",
  "avatar": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
  "phone": "13800138000"
}

响应示例:

{
  "code": 200,
  "message": "修改成功",
  "data": {
    "id": 1,
    "name": "李四",
    "email": "test@example.com",
    "phone": "13800138000",
    "avatar": "http://localhost:8080/uploads/2025/10/11/xxx.jpg"
  }
}

1.7 根据ID查询用户信息

  • URL: /user/info
  • 方法: GET
  • 需要Token: ✅ 是
  • 参数:
    • id (query): 用户ID

请求示例:

GET /user/info?id=1
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "张三",
    "email": "test@example.com",
    "phone": "13800138000",
    "avatar": "http://localhost:8080/uploads/2025/10/11/xxx.jpg"
  }
}

1.8 查询所有用户

  • URL: /user/
  • 方法: GET
  • 需要Token: ✅ 是

请求示例:

GET /user/
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "email": "test@example.com",
      "name": "张三",
      "avatar": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
      "phone": "13800138000"
    }
  ]
}

二、失物招领相关接口

2.1 发布失物/招领信息

  • URL: /item
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: application/json

请求示例:

{
  "title": "丢失黑色钱包",
  "description": "黑色皮质钱包，内有身份证和银行卡",
  "location": "图书馆三楼",
  "time": "2025-10-10T14:30:00",
  "imgUrl": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
  "status": "LOST"
}

字段说明:

  • status: 状态，可选值：
    • LOST: 丢失
    • FOUND: 拾到

响应示例:

{
  "code": 200,
  "message": "发布成功",
  "data": {
    "id": 1,
    "title": "丢失黑色钱包",
    "description": "黑色皮质钱包，内有身份证和银行卡",
    "imgUrl": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
    "time": "2025-10-10T14:30:00",
    "location": "图书馆三楼",
    "status": "LOST",
    "createdAt": "2025-10-11T10:00:00",
    "updatedAt": "2025-10-11T10:00:00"
  }
}

2.2 更新失物/招领信息

  • URL: /item
  • 方法: PUT
  • 需要Token: ✅ 是
  • Content-Type: application/json
  • 权限: 只能修改自己发布的信息

请求示例:

{
  "id": 1,
  "title": "更新后的标题",
  "description": "更新后的描述",
  "location": "更新后的位置",
  "time": "2025-10-10T15:00:00",
  "imgUrl": "http://localhost:8080/uploads/2025/10/11/new.jpg"
}

响应示例:

{
  "code": 200,
  "message": "修改成功",
  "data": {
    "id": 1,
    "title": "更新后的标题",
    "description": "更新后的描述",
    "imgUrl": "http://localhost:8080/uploads/2025/10/11/new.jpg",
    "time": "2025-10-10T15:00:00",
    "location": "更新后的位置",
    "status": "LOST",
    "publisherId": 1,
    "publisherName": "张三",
    "finderId": null,
    "finderName": null,
    "createdAt": "2025-10-11T10:00:00",
    "updatedAt": "2025-10-11T11:00:00"
  }
}

2.3 标记为已归还

  • URL: /item/{id}/returned
  • 方法: PUT
  • 需要Token: ✅ 是
  • 参数:
    • id (path): 失物ID
    • finderId (query, 可选): 找到者用户ID
  • 权限: 只有发布者可以操作

请求示例:

PUT /item/1/returned?finderId=2
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "已标记为归还",
  "data": null
}

2.4 标记为已完成

  • URL: /item/{id}/done
  • 方法: PUT
  • 需要Token: ✅ 是
  • 参数:
    • id (path): 失物ID
  • 权限: 只有发布者可以操作

请求示例:

PUT /item/1/done
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "已标记为完成",
  "data": null
}

2.5 删除失物/招领信息

  • URL: /item/{id}
  • 方法: DELETE
  • 需要Token: ✅ 是
  • 参数:
    • id (path): 失物ID
  • 权限: 只能删除自己发布的信息

请求示例:

DELETE /item/1
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

2.6 搜索失物/招领信息（分页）

  • URL: /item/search
  • 方法: GET
  • 需要Token: ❌ 否
  • 参数:
    • status (query, 可选): 状态筛选 (LOST/FOUND/RETURNED/WasDone)
    • location (query, 可选): 位置模糊搜索
    • keyword (query, 可选): 关键词搜索（标题和描述）
    • startTime (query, 可选): 开始时间 (格式: yyyy-MM-dd HH:mm:ss)
    • endTime (query, 可选): 结束时间 (格式: yyyy-MM-dd HH:mm:ss)
    • page (query, 可选): 页码，默认0
    • size (query, 可选): 每页大小，默认10

请求示例:

GET /item/search?status=LOST&location=图书馆&keyword=钱包&page=0&size=10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": 1,
        "title": "丢失黑色钱包",
        "description": "黑色皮质钱包，内有身份证和银行卡",
        "imgUrl": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
        "time": "2025-10-10T14:30:00",
        "location": "图书馆三楼",
        "status": "LOST",
        "publisherId": 1,
        "publisherName": "张三",
        "finderId": null,
        "finderName": null,
        "createdAt": "2025-10-11T10:00:00",
        "updatedAt": "2025-10-11T10:00:00"
      }
    ],
    "page": 0,
    "size": 10,
    "total": 1,
    "totalPages": 1
  }
}

2.7 获取我的发布列表（分页）

  • URL: /item/my
  • 方法: GET
  • 需要Token: ✅ 是
  • 参数:
    • page (query, 可选): 页码，默认0
    • size (query, 可选): 每页大小，默认10

请求示例:

GET /item/my?page=0&size=10
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": 1,
        "title": "丢失黑色钱包",
        "description": "黑色皮质钱包",
        "imgUrl": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
        "time": "2025-10-10T14:30:00",
        "location": "图书馆三楼",
        "status": "LOST",
        "publisherId": 1,
        "publisherName": "张三",
        "finderId": null,
        "finderName": null,
        "createdAt": "2025-10-11T10:00:00",
        "updatedAt": "2025-10-11T10:00:00"
      }
    ],
    "page": 0,
    "size": 10,
    "total": 1,
    "totalPages": 1
  }
}

2.8 查看失物/招领详情

  • URL: /item/{id}
  • 方法: GET
  • 需要Token: ❌ 否
  • 参数:
    • id (path): 失物ID

请求示例:

GET /item/1

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "title": "丢失黑色钱包",
    "description": "黑色皮质钱包，内有身份证和银行卡",
    "imgUrl": "http://localhost:8080/uploads/2025/10/11/xxx.jpg",
    "time": "2025-10-10T14:30:00",
    "location": "图书馆三楼",
    "status": "LOST",
    "publisherId": 1,
    "publisherName": "张三",
    "finderId": null,
    "finderName": null,
    "createdAt": "2025-10-11T10:00:00",
    "updatedAt": "2025-10-11T10:00:00"
  }
}

三、文件上传相关接口

3.1 上传单张图片

  • URL: /file/upload
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: multipart/form-data
  • 参数:
    • file (form-data): 图片文件

支持格式: jpg, jpeg, png, gif, bmp, webp
文件大小限制: 10MB

请求示例 (使用 Postman):

POST /file/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

Body (form-data):
  key: file
  type: File
  value: [选择图片文件]

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "http://localhost:8080/uploads/2025/10/11/uuid.jpg"
  }
}

3.2 上传多张图片

  • URL: /file/upload/multiple
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: multipart/form-data
  • 参数:
    • files (form-data): 多个图片文件

请求示例 (使用 Postman):

POST /file/upload/multiple
Authorization: Bearer {token}
Content-Type: multipart/form-data

Body (form-data):
  key: files
  type: File
  value: [选择多个图片文件]

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "http://localhost:8080/uploads/2025/10/11/uuid1.jpg,http://localhost:8080/uploads/2025/10/11/uuid2.jpg"
  }
}

3.3 删除图片

  • URL: /file/delete
  • 方法: DELETE
  • 需要Token: ✅ 是
  • 参数:
    • url (query): 图片URL

请求示例:

DELETE /file/delete?url=http://localhost:8080/uploads/2025/10/11/uuid.jpg
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

四、状态码说明

状态码 说明
200 成功
400 请求参数错误
401 未登录或登录已过期
403 权限不足
404 资源不存在
409 资源冲突（如邮箱已注册）
500 服务器内部错误

五、失物状态说明

状态 说明
LOST 丢失
FOUND 拾到
RETURNED 已归还
WasDone 已完成

六、使用流程示例

6.1 用户注册登录流程

1. GET /user/code?email=test@example.com          (发送验证码)
2. POST /user/register                             (注册)
3. POST /user/login                                (登录，获取token)

6.2 发布失物信息流程

1. POST /file/upload                               (上传图片，获取URL)
2. POST /item                                      (使用URL发布失物)

6.3 更新用户头像流程

1. POST /file/upload                               (上传头像，获取URL)
2. PUT /user/me                                    (使用URL更新头像)

6.4 失物找到后的流程

1. PUT /item/{id}/returned?finderId=2              (标记为已归还)
2. PUT /item/{id}/done                             (标记为已完成)

四、私聊消息相关接口

4.1 发送消息

  • URL: /message
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: application/json

请求示例:

{
  "receiverId": 2,
  "type": "TEXT",
  "content": "你好，请问你的钱包找到了吗？"
}

字段说明:

  • receiverId: 接收者用户ID
  • type: 消息类型，可选值：
    • TEXT: 文本消息
    • IMAGE: 图片消息
  • content: 消息内容（文本内容或图片URL）

响应示例:

{
  "code": 200,
  "message": "发送成功",
  "data": {
    "id": 1,
    "senderId": 1,
    "senderName": "张三",
    "senderAvatar": "http://localhost:8080/uploads/xxx.jpg",
    "receiverId": 2,
    "receiverName": "李四",
    "receiverAvatar": "http://localhost:8080/uploads/yyy.jpg",
    "type": "TEXT",
    "content": "你好，请问你的钱包找到了吗？",
    "isRead": false,
    "createdAt": "2025-10-13T15:30:00"
  }
}

4.2 获取与某人的聊天记录（分页）

  • URL: /message/conversation/{otherUserId}
  • 方法: GET
  • 需要Token: ✅ 是
  • 参数:
    • otherUserId (path): 对方用户ID
    • page (query, 可选): 页码，默认0
    • size (query, 可选): 每页大小，默认20

请求示例:

GET /message/conversation/2?page=0&size=20
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "content": [
      {
        "id": 1,
        "senderId": 1,
        "senderName": "张三",
        "senderAvatar": "http://localhost:8080/uploads/xxx.jpg",
        "receiverId": 2,
        "receiverName": "李四",
        "receiverAvatar": "http://localhost:8080/uploads/yyy.jpg",
        "type": "TEXT",
        "content": "你好",
        "isRead": true,
        "createdAt": "2025-10-13T15:30:00"
      }
    ],
    "page": 0,
    "size": 20,
    "total": 10,
    "totalPages": 1
  }
}

4.3 标记消息为已读

  • URL: /message/read/{otherUserId}
  • 方法: PUT
  • 需要Token: ✅ 是
  • 参数:
    • otherUserId (path): 对方用户ID

请求示例:

PUT /message/read/2
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "已标记为已读",
  "data": null
}

4.4 获取会话列表

  • URL: /message/conversations
  • 方法: GET
  • 需要Token: ✅ 是

请求示例:

GET /message/conversations
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 1,
      "otherUserId": 2,
      "otherUserName": "李四",
      "otherUserAvatar": "http://localhost:8080/uploads/xxx.jpg",
      "lastMessage": "你好，请问你的钱包找到了吗？",
      "unreadCount": 3,
      "updatedAt": "2025-10-13T15:30:00"
    }
  ]
}

4.5 获取未读消息数

  • URL: /message/unread-count
  • 方法: GET
  • 需要Token: ✅ 是

请求示例:

GET /message/unread-count
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": 5
}

五、WebSocket 实时消息

5.1 WebSocket 连接

  • 连接地址: ws://localhost:8080/ws/message?token={token}
  • 需要Token: ✅ 是（通过URL参数传递）
  • 协议: WebSocket

连接示例:

const token = "your_jwt_token";
const ws = new WebSocket(`ws://localhost:8080/ws/message?token=${token}`);

ws.onopen = function() {
    console.log('WebSocket 连接成功');
    // 连接成功后会自动推送离线消息
};

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    console.log('收到消息:', message);
};

5.2 消息推送格式

普通消息推送

{
  "id": 1,
  "senderId": 1,
  "senderName": "张三",
  "senderAvatar": "http://localhost:8080/uploads/xxx.jpg",
  "receiverId": 2,
  "receiverName": "李四",
  "receiverAvatar": "http://localhost:8080/uploads/yyy.jpg",
  "type": "TEXT",
  "content": "你好",
  "isRead": false,
  "createdAt": "2025-10-13T15:30:00"
}

离线消息推送完成通知

{
  "count": 5,
  "message": "离线消息推送完成",
  "type": "OFFLINE_MESSAGE_NOTIFICATION"
}

5.3 心跳检测

  • 发送: ping
  • 响应: pong
// 发送心跳包
ws.send('ping');

// 收到心跳响应
ws.onmessage = function(event) {
    if (event.data === 'pong') {
        console.log('心跳正常');
    }
};

六、聊天功能使用流程

6.1 发送文本消息流程

1. 用户登录获取 Token
2. 连接 WebSocket (可选，用于实时推送)
3. POST /message 发送消息
4. 接收者实时收到推送 (如果在线)

6.2 发送图片消息流程

1. POST /file/upload 上传图片获取 URL
2. POST /message 发送图片消息 (type=IMAGE, content=图片URL)
3. 接收者收到图片消息

6.3 离线消息处理流程

1. 用户A给离线的用户B发消息
2. 消息保存到数据库，标记为未读
3. 用户B上线连接 WebSocket
4. 系统自动推送所有未读消息
5. 推送完成后发送通知

6.4 会话管理流程

1. GET /message/conversations 获取会话列表
2. 点击会话 → GET /message/conversation/{userId} 加载聊天记录
3. PUT /message/read/{userId} 标记为已读
4. 发送新消息 → 会话列表自动更新

七、文件上传相关接口

7.1 上传单张图片

  • URL: /file/upload
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: multipart/form-data
  • 参数:
    • file (form-data): 图片文件

支持格式: jpg, jpeg, png, gif, bmp, webp
文件大小限制: 10MB

请求示例 (使用 Postman):

POST /file/upload
Authorization: Bearer {token}
Content-Type: multipart/form-data

Body (form-data):
  key: file
  type: File
  value: [选择图片文件]

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "http://localhost:8080/uploads/2025/10/13/uuid.jpg"
  }
}

7.2 上传多张图片

  • URL: /file/upload/multiple
  • 方法: POST
  • 需要Token: ✅ 是
  • Content-Type: multipart/form-data
  • 参数:
    • files (form-data): 多个图片文件

请求示例 (使用 Postman):

POST /file/upload/multiple
Authorization: Bearer {token}
Content-Type: multipart/form-data

Body (form-data):
  key: files
  type: File
  value: [选择多个图片文件]

响应示例:

{
  "code": 200,
  "message": "上传成功",
  "data": {
    "url": "http://localhost:8080/uploads/2025/10/13/uuid1.jpg,http://localhost:8080/uploads/2025/10/13/uuid2.jpg"
  }
}

7.3 删除图片

  • URL: /file/delete
  • 方法: DELETE
  • 需要Token: ✅ 是
  • 参数:
    • url (query): 图片URL

请求示例:

DELETE /file/delete?url=http://localhost:8080/uploads/2025/10/13/uuid.jpg
Authorization: Bearer {token}

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

八、状态码说明

状态码 说明
200 成功
400 请求参数错误
401 未登录或登录已过期
403 权限不足
404 资源不存在
409 资源冲突（如邮箱已注册）
500 服务器内部错误

九、消息类型说明

类型 说明 content 字段内容
TEXT 文本消息 文本内容
IMAGE 图片消息 图片完整URL

十、失物状态说明

状态 说明
LOST 丢失
FOUND 拾到
RETURNED 已归还
WasDone 已完成

十一、使用流程示例

11.1 用户注册登录流程

1. GET /user/code?email=test@example.com          (发送验证码)
2. POST /user/register                             (注册)
3. POST /user/login                                (登录，获取token)

11.2 发布失物信息流程

1. POST /file/upload                               (上传图片，获取URL)
2. POST /item                                      (使用URL发布失物)

11.3 更新用户头像流程

1. POST /file/upload                               (上传头像，获取URL)
2. PUT /user/me                                    (使用URL更新头像)

11.4 失物找到后的流程

1. PUT /item/{id}/returned?finderId=2              (标记为已归还)
2. PUT /item/{id}/done                             (标记为已完成)

11.5 完整聊天流程

1. 用户A登录 → POST /user/login
2. 用户A连接WebSocket → ws://localhost:8080/ws/message?token=xxx
3. 用户A发送消息 → POST /message
4. 用户B上线连接WebSocket → 自动收到离线消息
5. 用户B查看会话 → GET /message/conversations
6. 用户B回复消息 → POST /message
7. 实时聊天通过WebSocket推送

十二、注意事项

  1. Token 使用: 需要 Token 的接口必须在请求头中携带 Authorization: Bearer {token}
  2. WebSocket 连接: Token 通过 URL 参数传递：?token={token}
  3. 文件上传: 建议使用 Postman 或前端表单进行测试
  4. 图片 URL: 上传成功后返回的 URL 包含完整的服务器地址，可直接使用
  5. 时间格式: 使用 ISO 8601 格式：yyyy-MM-ddTHH:mm:ss
  6. 分页: 页码从 0 开始
  7. 权限控制: 只能修改/删除自己发布的信息，只能查看自己的聊天记录
  8. 跨域支持: 已配置 CORS，支持跨域访问
  9. 离线消息: 用户上线时自动推送未读消息
  10. 心跳检测: WebSocket 支持 ping/pong 心跳检测

十三、测试工具

  1. HTTP 接口测试: 使用项目根目录的 test.http 文件
  2. WebSocket 测试: 使用 websocket-test.html 页面进行完整聊天测试
  3. WebSocket 调试: 使用 websocket-debug.html 页面进行连接调试

文档版本: v2.0
最后更新: 2025-10-13