《Linux操作系统编程详解》《笔试/面试常见算法：从基础到进阶》《Python干货分享》
🎬 艾莉丝的简介：
文章目录
- 1 ~> ChatServer 接口整体概述
- 1.1 业务功能点
- 1.2 API 预先约定的工程价值
- 2 ~> RESTful API 接口设计规范
- 2.1 RESTful 基础概念
- 2.1.1 核心要素
- 2.2 RESTful 接口通用报文范式
- 2.2.1 请求报文构成
- 2.2.2 响应报文通用结构
- 3 ~> ChatServer 全部接口契约定义
- 3.1 获取会话列表
- 3.1.1 请求定义
- 3.1.2 响应体
- 3.2 获取可用模型列表
- 3.2.1 请求定义
- 3.2.2 响应体
- 3.3 创建新会话
- 3.3.1 请求定义
- 3.3.2 响应体
- 3.4 获取会话历史消息
- 3.4.1 请求定义
- 3.4.2 响应体
- 3.5 发送消息‑全量返回模式
- 3.5.1 请求定义
- 3.5.2 响应体
- 3.6 发送消息‑流式 SSE 异步模式
- 3.6.1 请求定义
- 3.6.2 SSE 流式响应报文格式
- 3.7 删除会话
- 3.7.1 请求定义
- 3.7.2 响应体
- 4 ~> ChatServer 接口开发总结
- 4.1 工程约束
- 4.2 关键工程要点
- 结尾
1 ~> ChatServer 接口整体概述
1.1 业务功能点
ChatServer 聊天服务核心业务能力，客户端通过 HTTP 接口与服务端完成交互，实现前后端分离架构。
- 获取会话列表
- 获取支持的模型列表
- 新建会话
- 发送消息（支持全量返回、SSE 流式返回两种模式）
- 获取会话历史消息
- 删除会话
1.2 API 预先约定的工程价值
- 前后端依据同一套 API 文档并行开发，避免联调阶段接口契约不匹配问题。
- 测试人员可基于 API 文档提前编写测试用例、设计测试计划。
- 所有角色开发、测试工作同步推进，提升整体项目迭代效率。
2 ~> RESTful API 接口设计规范
2.1 RESTful 基础概念
REST：Representational State Transfer，表现层状态转移；RESTful 为基于 REST 思想的 API 设计风格，不是网络协议，是一套接口设计标准，底层依托 HTTP 协议实现客户端‑服务器通信。
2.1.1 核心要素
- 资源 (Resource)
- 将业务中每一个实体、对象抽象为资源，例如会话、模型、用户。
- 每一份资源使用唯一 URI 进行标识，URL 作为 URI 的具体实现形式。
- 示例：
/api/sessions代表会话集合资源。
- 表现层
- 代表资源在网络传输中的序列化格式，支持 JSON、XML、HTML。
- RESTful 工程实践优先选用JSON，具备轻量、程序易于解析的特性。
- HTTP 动作（HTTP Methods），使用 HTTP 方法描述对资源的操作行为
GET：获取资源POST：创建资源PUT：更新资源DELETE：删除资源
- 无状态特性
- 每一次 HTTP 请求完全独立；服务端不保存客户端会话上下文状态。
- 客户端每一次请求必须携带服务端处理业务所需要的全部参数信息。
- 若业务需要会话状态，必须额外自行实现会话存储机制。
2.2 RESTful 接口通用报文范式
2.2.1 请求报文构成
- HTTP 请求方法
- 资源 URI（请求 URL）
- 请求体 JSON 载荷（POST/PUT 场景）
2.2.2 响应报文通用结构
- HTTP 状态码标识请求传输层级结果；业务结果由响应体内业务字段表达。
- 响应体统一 JSON 格式，包含请求标识、业务错误码、错误信息、结果载体对象。
{"requestId":"string",// 请求唯一ID，用于链路追踪"errorCode":0,// 业务错误码，0代表业务执行成功"errorMsg":"",// 业务错误描述，成功时为空字符串"result":{}// 业务返回数据载体对象}3 ~> ChatServer 全部接口契约定义
公共约束：非流式接口 HTTP 返回状态码均为
200 OK，业务成功失败通过 JSON 内部布尔 / 错误码字段区分；所有非流式接口请求、响应均使用 JSON 格式。
3.1 获取会话列表
3.1.1 请求定义
- 请求方法：
GET - 请求 URL：
/api/sessions - 请求体：无
3.1.2 响应体
{"success":true,// bool，本次业务是否成功"message":"string",// 结果描述文本"data":[// array，会话列表数组{"id":"string",// 会话id"model":"string",// 使用的模型名称"created_at":1700000000,// int64_t，会话创建时间戳"updated_at":1700000100,// int64_t，会话最后更新时间戳"message_count":10,// int，该会话对话总次数"first_user_message":"string"// string，第一条用户消息正文，用于会话列表预览}]}3.2 获取可用模型列表
3.2.1 请求定义
- 请求方法：
GET - 请求 URL：
/api/models - 请求体：无
3.2.2 响应体
{"success":true,// bool，业务是否成功"message":"string",// 结果描述"data":[// array，可用模型数组{"name":"string",// 模型名称，调用时作为入参使用"desc":"string"// 模型功能描述}]}3.3 创建新会话
3.3.1 请求定义
- 请求方法：
POST - 请求 URL：
/api/session - 请求体
{"model":"string"// 需要使用的模型名称，来源于/api/models接口返回name字段}3.3.2 响应体
{"success":true,// bool，业务是否成功"message":"string",// 结果描述"data":[{"session_id":"string",// 会话唯一ID，后续所有会话相关接口必须携带该标识"model":"string"// 当前会话绑定的模型名称}]}3.4 获取会话历史消息
3.4.1 请求定义
- 请求方法：
GET - 请求 URL：
/api/session/${session_id}/history - 路径参数：
session_id，创建会话接口返回的会话 ID - 请求体：无
3.4.2 响应体
{"success":true,// bool，业务是否成功"message":"string",// 结果描述"data":[// array，消息历史数组，按时间排序{"id":"string",// 单条消息唯一id"role":"string",// 消息角色：user / assistant"content":"string",// 消息正文内容"timestamp":1700000200// int64_t，消息生成时间戳，秒级}]}3.5 发送消息‑全量返回模式
等待大模型完整生成全部内容之后，一次性返回全部应答结果。
3.5.1 请求定义
- 请求方法：
POST - 请求 URL：
/api/message - 请求体
{"session_id":"string",// 目标会话ID"model":"string",// 模型名称"message":"string"// 用户输入提问内容}3.5.2 响应体
{"success":true,// bool，业务是否成功"message":"string",// 结果描述"data":[{"session_id":"string","response":"string"// 大模型完整应答全部文本}]}3.6 发送消息‑流式 SSE 异步模式
SSE（Server‑Sent Events）服务端推送事件，分片逐块返回模型输出文本，前端实时渲染打字机效果；HTTP 状态码 200 OK，响应 Content‑Type 为
text/event‑stream。
3.6.1 请求定义
- 请求方法：
POST - 请求 URL：
/api/message/async - 请求体
{"session_id":"string","model":"string","message":"string"}3.6.2 SSE 流式响应报文格式
data:模型输出片段1 data:模型输出片段2 data:模型输出片段3 data:[DONE]- 每一条
data:代表一块增量输出文本；客户端持续拼接收到的 data 内容。 data:[DONE]为流结束标记，客户端收到该标记代表本次对话流式输出全部完成，关闭 SSE 连接。
3.7 删除会话
3.7.1 请求定义
- 请求方法：
DELETE - 请求 URL：
/api/session/${session_id} - 路径参数：
session_id，待删除会话 ID - 请求体：无
3.7.2 响应体
{"success":true,// bool；true代表会话服务端删除成功，前端需要同步删除本地页面会话条目"message":"string"// 结果描述}4 ~> ChatServer 接口开发总结
4.1 工程约束
- ChatServer 后端服务、前端页面交互逻辑，必须严格遵循本套 RESTful 接口契约实现。
- 前端页面调用全部接口，完成会话全生命周期管理：创建会话、发送消息、拉取历史、销毁会话。
4.2 关键工程要点
- 接口契约先行：正式编码开发前完成 API 文档定义，支撑前后端、测试多角色并行工作。
- 两种消息返回模式选型：
- 全量返回：逻辑简单，适合简短问答；大模型长输出场景用户体验差，等待时间长。
- SSE 流式输出：实时增量推送，聊天产品主流方案；客户端需要实现 SSE 事件监听、文本分片拼接逻辑。
- RESTful 无状态：会话状态全部通过
session_id参数携带，服务端不在 HTTP 上下文存储会话信息。 - 资源路径语义化：使用 HTTP 动词表达增删改查行为，URI 代表业务资源，不使用 URL 中出现
/getSession这类动词形式。
结尾
uu们，本文的内容到这里就全部结束了，艾莉丝在这里再次感谢您的阅读！
|
结语：希望对学习Linux相关内容的uu有所帮助，不要忘记给博主“一键四连”哦！
往期回顾：
【AI大模型接入SDK】ChatServer项目整体概述与系统架构
🗡博主在这里放了一只小狗，大家看完了摸摸小狗放松一下吧！🗡 ૮₍ ˶ ˊ ᴥ ˋ˶₎ა
