声明：本文档为接口文档，内容由 AI 辅助生成、博主整理优化，仅作本项目开发参考使用。

---

✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
🎯 你正在阅读「Java项目-轻聊」系列文章 🎯
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

🔥 弹简特 个人主页

❄️ 个人专栏直通车：

• 💻 软件测试入门记
• 📱 野生测试修炼手册 | APP 专项测试笔记
• 🔌 接口测试从入门到跑路
• ☕ 一个后端的 JavaEE 续命指南
• 🛜 网络原理续命手册
• 🐍 Python 从零摸索日记
• ☕ Java项目-轻聊
• ☕ Java项目-企悦抽

✨ 靠热爱去书写自己，靠勇敢去书写生活！
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨

---

🌟 博主简介:

---

写在最前-项目同步码云

📦 项目源码 | 码云仓库


点击👉 点我看项目同步代码

---

轻聊 — 接口文档

文档说明

项目	说明
基础 URL	http://127.0.0.1:8080
编码	UTF-8
认证方式	登录成功后使用 HttpSession（Cookie: JSESSIONID）
数据格式	HTTP 接口多为 表单参数 或 Query；响应多为 JSON（除头像二进制流）
WebSocket	ws://127.0.0.1:8080/WebSocketMessage（需先 HTTP 登录）

---

通用约定

登录态

• 登录成功：服务端创建 Session，属性 user 为当前用户对象。
• 未登录或 Session 失效：需登录接口返回空用户（userId 为 0 或字段为空）或空列表、ok: false 等。

通用错误表现

场景	典型响应
未登录调用需登录接口	空对象、空数组，或 { ok: false, message: "未登录" }
参数无效	{ ok: false, message: "..." }

---

一、用户模块

1.1 用户登录

项	内容
URL	POST /login
Content-Type	application/x-www-form-urlencoded
是否需登录	否

请求参数

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码（明文，与库中一致）

成功响应（200，JSON）

{
  "userId": 1,
  "username": "张三",
  "password": "",
  "avatarPath": null
}

字段	说明
userId	大于 0 表示成功
password	恒为空字符串，不返回真实密码

失败响应 A — 用户名或密码错误

{
  "userId": 0,
  "username": "",
  "password": "",
  "avatarPath": null
}

失败响应 B — 重复登录

{
  "userId": 0,
  "message": "该账号已在其他地方登录，请勿重复登录"
}

---

1.2 用户注册

项	内容
URL	POST /register
是否需登录	否

请求参数

参数	类型	必填	说明
username	string	是	用户名，唯一
password	string	是	密码

成功响应

{
  "userId": 5,
  "username": "新用户",
  "password": "",
  "avatarPath": null
}

失败响应（用户名重复）

{
  "userId": 0,
  "username": "",
  "password": "",
  "avatarPath": null
}

---

1.3 退出登录

项	内容
URL	POST /logout
是否需登录	建议已登录

响应

{
  "ok": true
}

副作用：Session 失效；该用户 WebSocket 连接被关闭。

---

1.4 获取当前用户信息

项	内容
URL	GET /userInfo
是否需登录	是

成功响应

{
  "userId": 1,
  "username": "张三",
  "password": "",
  "avatarPath": "/avatars/xxx.jpg"
}

未登录响应：userId 为 0 的空用户对象。

---

1.5 上传头像

项	内容
URL	POST /user/uploadAvatar
Content-Type	multipart/form-data
是否需登录	是

请求参数

参数	类型	必填	说明
file	file	是	图片文件
userId	int	是	必须为当前登录用户 ID

成功响应

{
  "ok": true,
  "avatarPath": "/avatars/xxxxxxxx.jpg",
  "avatarUrl": "/avatars/xxxxxxxx.jpg",
  "message": "头像上传成功"
}

失败响应示例

{ "ok": false, "message": "未登录" }
{ "ok": false, "message": "只能修改自己的头像" }
{ "ok": false, "message": "仅支持 jpg、jpeg、png 格式" }
{ "ok": false, "message": "图片大小不能超过 2MB" }

---

1.6 获取用户头像（二进制）

项	内容
URL	GET /user/getAvatar?userId={userId}
是否需登录	否（建议登录后测）
响应	图片流；无头像时返回默认 SVG

---

1.7 搜索用户（加好友用）

项	内容
URL	GET /search/user?keyword={keyword}
是否需登录	是

请求参数

参数	说明
keyword	用户名模糊匹配关键词

成功响应（JSON 数组）

[
  {
    "userId": 4,
    "username": "赵六",
    "avatarPath": null
  }
]

过滤规则（服务端）：不包含自己；已是好友；已有待处理好友请求（双向）的用户不出现。

---

二、好友模块

2.1 好友列表

项	内容
URL	GET /friendList
是否需登录	是

成功响应

[
  {
    "friendId": 2,
    "friendName": "李四",
    "avatarPath": "/avatars/xxx.jpg"
  }
]

未登录：[]

---

三、好友请求模块

3.1 待处理好友请求列表

项	内容
URL	GET /friend/request/list
是否需登录	是

成功响应

[
  {
    "requestId": 1,
    "fromUserId": 3,
    "fromName": "王五",
    "reason": "同学"
  }
]

---

3.2 发送好友请求

项	内容
URL	POST /friend/request
是否需登录	是

请求参数

参数	类型	必填	说明
toUserId	int	是	目标用户 ID
reason	string	否	申请理由，默认空

成功响应

{
  "ok": true,
  "message": "好友请求已发送"
}

失败响应示例

message
未登录
目标用户无效
不能添加自己为好友
目标用户不存在
对方已是你的好友
已发送过好友请求，请勿重复提交
对方已向你发送好友请求，请在会话列表中处理

副作用：若对方 WebSocket 在线，推送 type=FRIEND_REQUEST 消息。

---

3.3 处理好友请求

项	内容
URL	POST /friend/handle
是否需登录	是

请求参数

参数	类型	必填	说明
requestId	int	是	请求 ID
action	string	是	accept 或 reject

成功响应

{
  "ok": true,
  "message": "已同意好友请求"
}

或

{
  "ok": true,
  "message": "已拒绝好友请求"
}

同意副作用：双向写入 friend 表；删除该请求；向双方 WebSocket 推送 type=FRIEND_ACCEPTED。

---

四、会话模块

4.1 会话列表

项	内容
URL	GET /sessionList
是否需登录	是

成功响应

[
  {
    "sessionId": 1,
    "friends": [
      {
        "friendId": 2,
        "friendName": "李四",
        "avatarPath": null
      }
    ],
    "lastMessage": "晚上见"
  }
]

字段	说明
friends	会话中除自己外的成员（单聊为 1 人）
lastMessage	该会话最新一条消息内容，无则 ""

规则：同一好友多个 session 时，列表只保留一条（有最后消息优先，否则 sessionId 较小者）。

---

4.2 创建会话

项	内容
URL	POST /session?toUserId={toUserId}
是否需登录	是（依赖 Session 属性 user）

请求参数

参数	说明
toUserId	对方用户 ID

成功响应

{
  "sessionId": 3
}

规则：两人已有会话则直接返回已有 sessionId，不重复创建。

---

五、消息模块

5.1 历史消息

项	内容
URL	GET /message?sessionId={sessionId}
是否需登录	否（前端在登录后调用）

成功响应（JSON 数组，时间升序，最多 100 条）

[
  {
    "messageId": 1,
    "fromId": 1,
    "fromName": "张三",
    "sessionId": 1,
    "content": "晚上吃什么",
    "avatarPath": "/avatars/xxx.jpg"
  }
]

---

六、WebSocket 接口

6.1 连接

项	内容
URL	ws://127.0.0.1:8080/WebSocketMessage
握手	携带与 HTTP 相同的 Cookie（JSESSIONID）
拦截器	HttpSessionHandshakeInterceptor 将 Session 中 user 写入 WS 属性

连接失败场景：未登录时 user 为空，连接建立但不登记在线。

重复连接：同 userId 已有 WS 时，新连接被拒绝关闭（先登录的浏览器保持在线）。

---

6.2 客户端 → 服务端（发送聊天消息）

文本帧 JSON：

{
  "type": "message",
  "sessionId": 1,
  "content": "你好"
}

字段	必填	说明
type	是	固定 message
sessionId	是	会话 ID
content	是	消息正文

服务端行为：解析后转发给对方与自己（用于刷新 UI），并写入 message 表。两人之间存在 canonical sessionId 时，以较小 sessionId 落库。

---

6.3 服务端 → 客户端（推送）

6.3.1 聊天消息

{
  "type": "message",
  "fromId": 1,
  "fromName": "张三",
  "content": "你好",
  "sessionId": 1,
  "sessionName": "李四",
  "avatarPath": "/avatars/xxx.jpg"
}

字段	说明
sessionName	接收方会话列表标题：对方看发送者名；发送方看自己会话中对方名

6.3.2 好友请求通知

{
  "type": "FRIEND_REQUEST",
  "requestId": 2,
  "fromUserId": 3,
  "fromName": "王五",
  "reason": "认识一下"
}

6.3.3 好友请求被同意

{
  "type": "FRIEND_ACCEPTED",
  "friendUserId": 3,
  "friendName": "王五"
}

---

6.4 测试 WebSocket（回显，非业务）

| URL | ws://127.0.0.1:8080/chat |
| 说明 | TestWebSocketController，原样回显，无需登录 |

---

七、静态资源

路径	说明
/login.html	登录页
/register.html	注册页
/client.html	主界面
/avatars/{filename}	上传头像访问（映射 upload/avatars）
/img/default-avatar.svg	默认头像

---

八、接口测试检查清单（汇总）

模块	接口数	建议顺序
用户	7	注册 → 登录 → userInfo → 头像 → 搜索
好友	1	friendList
好友请求	3	发送 → 列表 → 同意/拒绝
会话	2	sessionList → 创建 session
消息	1	历史 message
WebSocket	1 连接 + 3 类推送	登录后连接，双用户互发

---

OK，老铁们，我们接口文档约束好之后，后续我们就开始一步一步实现项目的开发了~
咱们下一期就从用户管理模块开始。