个人主页艾莉丝努力练剑❄专栏传送门《C语言》《数据结构与算法》《C/C干货分享学习过程记录》《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 基础概念RESTRepresentational 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,// 会话idmodel: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,// 单条消息唯一idrole:string,// 消息角色user / assistantcontent:string,// 消息正文内容timestamp:1700000200// int64_t消息生成时间戳秒级}]}3.5 发送消息‑全量返回模式等待大模型完整生成全部内容之后一次性返回全部应答结果。3.5.1 请求定义请求方法POST请求 URL/api/message请求体{session_id:string,// 目标会话IDmodel:string,// 模型名称message:string// 用户输入提问内容}3.5.2 响应体{success:true,// bool业务是否成功message:string,// 结果描述data:[{session_id:string,response:string// 大模型完整应答全部文本}]}3.6 发送消息‑流式 SSE 异步模式SSEServer‑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,// booltrue代表会话服务端删除成功前端需要同步删除本地页面会话条目message:string// 结果描述}4 ~ ChatServer 接口开发总结4.1 工程约束ChatServer 后端服务、前端页面交互逻辑必须严格遵循本套 RESTful 接口契约实现。前端页面调用全部接口完成会话全生命周期管理创建会话、发送消息、拉取历史、销毁会话。4.2 关键工程要点接口契约先行正式编码开发前完成 API 文档定义支撑前后端、测试多角色并行工作。两种消息返回模式选型全量返回逻辑简单适合简短问答大模型长输出场景用户体验差等待时间长。SSE 流式输出实时增量推送聊天产品主流方案客户端需要实现 SSE 事件监听、文本分片拼接逻辑。RESTful 无状态会话状态全部通过session_id参数携带服务端不在 HTTP 上下文存储会话信息。资源路径语义化使用 HTTP 动词表达增删改查行为URI 代表业务资源不使用 URL 中出现/getSession这类动词形式。结尾uu们本文的内容到这里就全部结束了艾莉丝在这里再次感谢您的阅读艾莉丝努力练剑C/C Linux 底层探索者 | 一个正在努力练剑的技术博主【关注】跟随我一起深耕技术领域见证每一次成长。❤️【点赞】让优质内容被更多人看见让知识传递更有力量。⭐【收藏】把核心知识点存好在需要时随时查、随时用。【评论】分享你的经验或疑问评论区一起交流避坑不要忘记给博主“一键四连”哦“今日练剑达成”“技术之路难免有困惑但同行的人会让前进更有方向。”结语希望对学习Linux相关内容的uu有所帮助不要忘记给博主“一键四连”哦往期回顾【AI大模型接入SDK】ChatServer项目整体概述与系统架构博主在这里放了一只小狗大家看完了摸摸小狗放松一下吧૮₍ ˶ ˊ ᴥ ˋ˶₎ა