最近我把手头一个AI交互类项目做到了V1阶段的整体收口核心动作就俩字封装。这个V1项目是一个多端AI问答助手前端覆盖了PC端、H5和小程序后端能力基于大模型的SSE流式输出。V1开发到后期代码里满是散落的axios调用、到处重复的中断逻辑、每个页面都要重新处理的域名切换以及一堆说不清归属的工具函数。这才意识到V1不只是一个功能版本更是一次封装的边界测试。这篇文章把整个封装过程完整记录下来包括请求层二次封装、SSE流式渲染与abort中断控制、uniapp H5多域名指向方案、组件与工具沉淀以及真实踩过的坑适合正在做AI对话类应用、需要管理多端请求层、或者正在犹豫要不要做封装重构的前端同学参考。1. 这个V1项目要封装的到底是什么1.1 项目形态与三个核心痛点先交代一下项目背景。这是一个面向企业客户的AI知识库问答工具用户在Web端或者小程序里输入问题后端调用大模型接口把回答以SSE流式数据实时推回前端。V1的核心功能不复杂但就是不复杂的三个字骗了很多人。开发到中后期我梳理了一下代码仓库痛点集中在三个地方。第一个痛点是请求层完全裸奔每个页面直接import axios然后各自设置baseURL、各自处理token、各自写错误提示一旦接口域名需要切换得全局搜索替换。第二个痛点是AI流式输出的逻辑散落在组件内部有的用EventSource有的用fetch手动解析生成过程中的停止按钮、超时处理、组件卸载时的请求清理都没有统一方案导致用户点停止之后画面还在滚动输出组件已经销毁了网络请求还在跑。第三个痛点是多端适配uniapp打包出来的H5要按不同域名指向不同API环境小程序端又有一套独立逻辑配置分散导致改一处漏三处。这三个痛点对应到文章后面就是请求层封装、AI交互层封装、多域名配置封装。V1阶段的封装不是把代码包一层就完事而是要把这些高频变化点收敛成少数几个稳定的入口。1.2 从OOP三大特性到业务封装的层次理解说到封装很多同学第一反应是OOP里的封装继承多态脑子里浮现的是class、private、protected。这些概念本身没错但放在真实项目里容易产生误导。V1项目里我最大的体会是业务封装跟前端框架层面的抽象根本是两个层次的东西。类层面的封装强调的是信息隐藏把属性私有化对外暴露方法调用方不需要知道内部怎么实现。业务层面的封装做的是同一件事把变化点藏起来对外暴露稳定的语义接口。比如请求层封装业务方只需要调用request.get()或者request.post()不需要关心当前是哪个域名、token怎么拼、错误码怎么映射。再比如AI交互层业务方只需要startGenerate()和stopGenerate()不需要关心SSE解析逻辑和中断细节。所以封装继承多态里的封装是手段而业务封装是目的。V1项目里我们没有刻意去设计复杂的继承关系也没有硬造一堆抽象基类而是先找出那些每个页面都要写一遍、每次需求变更都要动一遍的代码把它们往同一处收敛。这才是这个阶段真正该做的封装。1.3 封装时机的判断标准什么时候该封装什么时候不该封装这大概是V1团队里争论最多的问题。我的判断标准只有三条。第一条重复出现三次以上才值得封装。只有一两个地方用到的逻辑强行抽出来反而增加跳转成本读代码的时候还得来回翻文件。V1里某个时间格式化函数一开始只在消息列表里用到我没有抽后来历史记录页面、详情页都开始用凑够三次才下沉到工具层。第二条变化频率高的点必须封装。域名切换、token注入、错误码映射、流式中断这几个点在整个V1迭代过程中反复变不封装的代价就是每次改需求都要把所有调用处翻一遍漏改一处就是线上事故。第三条调用方和使用方属于不同团队或者不同模块时接口必须稳定。AI交互逻辑由前端组自己用还稍微宽松一点但请求层是全局基础设施一旦业务方开始依赖接口就不能随意变。V1的请求层从第一版设计开始就定了get/post/put/delete四个方法签名后面内部实现大改过三次业务方零改动。这三条标准可以帮大家在过度封装和不封装之间找到一个平衡点。V1项目里我也踩过过度封装的坑后面专门有一节讲什么时候该停止封装。2. 网络请求层的二次封装从axios到业务层2.1 为什么不能绕过axios直接调后端有同事问过一个问题axios本身已经支持拦截器、超时、取消请求为什么还要再包一层直接在每个页面用axios不就行了这个问题看起来有道理但放到V1这个多端多域名的项目里完全站不住脚。axios只是HTTP客户端它不管业务层的约定。比如我们后端有个统一响应包装code字段为0才是成功message字段直接给用户看这些约定如果在每个页面各写一遍判断将来后端改字段名就是灾难。再比如登录态失效时的401统一处理如果散落在页面里有的弹提示、有的静默失败、有的跳转登录页用户看到的行为完全不一致。二次封装的价值是把HTTP通信和业务语义剥离开。HTTP层面的事交给axios处理业务层面的约定收敛到封装层。实际开发中页面里不该出现response.data.code这样的代码所有业务判断都在拦截器里完成业务方拿到的就是已经处理好的业务数据或者被拒绝的错误。这就是封装后调用方心智负担大幅下降的原因。2.2 多域名多环境的baseURL自动指向方案V1项目里域名问题比较棘手因为AI交互场景涉及多个后端服务。主API是一个域名文件上传是另一个域名SSE流式接口又挂在独立网关下面这些服务在开发、测试、生产环境各有不同地址。再加上uniapp H5打包后要挂在不同入口域名下指向不同环境这就是热搜里说的uniapp封装h5如何指向2个域名的真实场景。我采用的方案是环境配置文件加运行时判断双管齐下。// config/index.js const ENV_MAP { dev: { main: https://dev-api.example.com, upload: https://dev-upload.example.com, stream: https://dev-stream.example.com }, test: { main: https://test-api.example.com, upload: https://test-upload.example.com, stream: https://test-stream.example.com }, prod: { main: https://api.example.com, upload: https://upload.example.com, stream: https://stream.example.com } } function getEnvKey() { // uni-app里可以用process.env.NODE_ENV也可以用自定义变量 if (import.meta.env?.MODE) { return import.meta.env.MODE development ? dev : prod } return prod } export function getBaseURL(service main) { const env getEnvKey() return ENV_MAP[env][service] || ENV_MAP[env].main } export function getDomainLevel() { // H5场景下通过location.host判断当前站点 if (typeof window undefined) return main const host window.location.host if (host.startsWith(kb.)) return kb if (host.startsWith(admin.)) return admin return main }H5页面里调用接口时就可以根据站点类型自动决定走哪套API域名。实际遇到的情况是知识库站点挂载在kb.example.com管理后台挂在admin.example.com两套站点共用一套前端代码但API网关入口不同。用运行时host判断之后打包产物就一份部署到不同域名下自动适配。这是我在V1里比较满意的一个细节。小程序端不用location.host就在config里根据uni.getAccountInfoSync().miniProgram.envVersion判断是开发版、体验版还是正式版再映射到对应环境。多端配置看起来代码量不大但把这些逻辑从业务代码里抠出来是请求层封装的第一步。2.3 拦截器、错误码与取消请求的统一处理axios二次封装的重点在于两个拦截器。请求拦截器负责注入token、设置baseURL、附加公共参数响应拦截器负责统一解析业务包装、统一错误提示、统一处理登录失效以及识别取消请求。V1项目的错误码规范是后端定的code为0表示成功非0时message可直接展示给用户。响应拦截器里的逻辑不能只判断HTTP状态码还要判断业务码。同时要考虑一种特殊情况用户主动取消请求时axios会抛出一个ERR_CANCELED错误这个不能走业务错误提示否则用户点一下停止按钮就弹一条报错体验极差。关于取消请求我建议所有请求在发起时都注册cancelToken回调放到一个全局Map里统一管理。这样登录失效时可以把所有进行中的请求全部取消不再给他们回调的机会。V1的AI问答页面里用户切换会话、退出登录、组件卸载时都会调用这个统一取消方法。// request/index.js import axios from axios import { getBaseURL } from /config const service axios.create({ timeout: 30000 }) const pendingMap new Map() function addPending(config) { const key ${config.method}:${config.url} config.cancelToken new axios.CancelToken((cancel) { pendingMap.set(key, cancel) }) } function removePending(key) { if (pendingMap.has(key)) { pendingMap.get(key)() pendingMap.delete(key) } } export function cancelAllRequests() { pendingMap.forEach((cancel) cancel()) pendingMap.clear() } service.interceptors.request.use((config) { removePending(${config.method}:${config.url}) addPending(config) const token uni.getStorageSync(token) if (token) { config.headers.Authorization Bearer ${token} } const serviceName config.service || main config.baseURL getBaseURL(serviceName) return config }, (error) Promise.reject(error)) service.interceptors.response.use( (response) { const res response.data if (res.code ! 0) { uni.showToast({ title: res.message || 请求失败, icon: none }) return Promise.reject(new Error(res.message || request error)) } return res.data }, (error) { if (axios.isCancel(error)) { return Promise.reject(Object.assign(error, { isCanceled: true })) } const status error.response?.status if (status 401) { uni.showToast({ title: 登录已过期请重新登录, icon: none }) cancelAllRequests() // 路由跳转登录页逻辑 } else if (status 500) { uni.showToast({ title: 服务异常请稍后重试, icon: none }) } return Promise.reject(error) } ) export default service这段代码在V1项目里稳定跑了三个月。值得一提的一个细节是加pendingMap如果同一接口短时间内重复点击先取消前一个再发新的避免用户双击导致重复请求堆积。这是个容易被忽略的场景但在AI问答里用户连续点击发送按钮的概率非常高。2.4 业务层的api模块封装请求层封装只是地基业务接口层还需要再包一层让页面完全感知不到HTTP细节。V1项目里每个业务域一个文件方法名直接对应后端接口语义。// api/chat.js import request from /request export function sendChatMessage(data) { return request.post(/chat/send, data, { service: main }) } export function getChatHistory(params) { return request.get(/chat/history, { params, service: main }) } export function uploadAttachment(file) { return request.upload(/file/upload, { file, service: upload }) }到这里业务方调用就变成了一行await sendChatMessage(data)不用关心baseURL、不用拼接路径、不用处理loading和错误码。我见过一些项目在页面里直接写request.post(/api/xxx)这其实只做了一半封装。真正的封装要连接口路径也收口否则后端改路径时页面还是要跟着改。接口层封装还有一个附带好处方便mock。V1早期后端并发紧张时前端只需要在api模块里加一个条件判断开发环境返回mock数据页面完全不需要改。这个优势在联调阶段非常明显。3. AI交互逻辑的封装SSE流式输出与中断控制3.1 为什么选SSE而不是WebSocket或轮询AI对话场景的技术选型上团队内部做过一轮讨论大模型回答是单向流式返回服务端持续往客户端推文本客户端基本不往服务端发消息这种情况下轮询、WebSocket、SSE三种技术各有适合场景。轮询的缺点很直观每隔一两秒拉一次接口消息延迟高而且大量请求是无效的服务端压力大用户体验也差。WebSocket是全双工协议能力强但复杂度也高需要处理连接维持、心跳、断线重连、消息帧解析对项目前期的交付压力太大。SSE是Server-Sent Events基于HTTP长连接服务端单向推送浏览器原生支持协议简单连接断开还能自动重连。对大模型流式输出这个场景SSE几乎是量身定做的。唯一需要注意的是EventSource的限制不仅只支持GET请求还不能自定义请求头token只能拼在URL上不太安全。所以V1方案里没有直接用new EventSource(url)而是用fetch加上ReadableStream来手动解析SSE协议这样既能用POST传递消息体也能在Header里带token还能在需要的时候用AbortController随时掐断连接。3.2 fetchReadableStream的SSE实时渲染实现SSE协议格式比较简单服务端返回的内容按data:开头多个事件之间用空行分隔。用fetch收到响应之后body是一个ReadableStream需要用getReader()逐块读取按行切分逐条解析。// utils/sse.js export async function fetchSSE({ url, body, token, signal, onMessage, onDone, onError }) { try { const resp await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${token} }, body: JSON.stringify(body), signal }) if (!resp.ok || !resp.body) { throw new Error(HTTP ${resp.status}) } const reader resp.body.getReader() const decoder new TextDecoder(utf-8) let buffer while (true) { const { done, value } await reader.read() if (done) break buffer decoder.decode(value, { stream: true }) // SSE事件以空行分割按行取出 const lines buffer.split(\n) buffer lines.pop() || for (const line of lines) { const trimmed line.trim() if (!trimmed.startsWith(data:)) continue const dataStr trimmed.slice(5).trim() if (dataStr [DONE]) { onDone onDone() return } try { const json JSON.parse(dataStr) onMessage onMessage(json) } catch (e) { console.warn(SSE parse error:, e) } } } } catch (error) { if (error.name AbortError) { console.log(SSE aborted by user) return } onError onError(error) } }这个封装函数在V1项目的多个页面里复用AI对话页用它拿流式回答语音转写结果页也用它推送转写进度。几个页面之间的差异只是onMessage里的业务处理不一样协议解析逻辑统一收敛在这里。有个细节需要特别强调TextDecoder的stream参数必须传。decoder.decode(value, { stream: true })意味着本次解码可能不完整中文字符的UTF-8字节被拆到两次读取时stream模式能把未完成的字节保留到下一次解码。我第一次写的时候漏了这个参数英文内容一切正常切到中文问答就频繁出现乱码和半个字符。这个问题排查了整整一个下午最后发现就是一行参数的事。3.3 AbortController的正确打开方式AI问答场景对中断控制的诉求特别强烈。用户点击停止按钮要立即停止文字输出切换会话要中断上一个还没生成完的回答页面销毁时所有网络请求必须终止否则会造成请求泄漏和状态错乱。V1项目在store层做了一层AI交互状态管理把开始生成、停止生成、会话切换的逻辑统一收口。// store/chat.js import { fetchSSE } from /utils/sse export const useChatStore defineStore(chat, { state: () ({ messages: [], generating: false, sseController: null, currentAnswer: }), actions: { async startGenerate() { if (this.generating) return this.generating true this.currentAnswer const controller new AbortController() this.sseController controller try { await fetchSSE({ url: ${getBaseURL(main)}/chat/stream, body: { messages: this.messages }, token: uni.getStorageSync(token), signal: controller.signal, onMessage: (json) { if (json.type content) { this.currentAnswer json.text this.updateLastMessage(this.currentAnswer) } else if (json.type title) { this.setTitle(json.text) } }, onDone: () { this.generating false this.sseController null }, onError: (err) { this.generating false this.sseController null console.error(err) } }) } finally { this.generating false this.sseController null } }, stopGenerate() { if (this.sseController) { this.sseController.abort() this.sseController null this.generating false } }, switchSession(sessionId) { this.stopGenerate() // 切换会话逻辑 } } })这里有个非常关键的设计把sseController放进store而不是放在组件data里。因为组件可能被销毁但store是全局的切换页面、切换会话、点击停止按钮时都可以通过store拿到正在执行的请求实例并中止。AbortController的使用还有一个隐藏细节当控制器被abort之后同一个controller无法复用必须在每次新请求时重新new AbortController()。我在V1里就是因为复用了旧controller导致第二次请求直接秒失败。每次生成前都要创建新的实例这是abort语义的基本要求。另外页面卸载时也要主动调stop。Vue3的onUnmounted里调chatStore.stopGenerate()React里对应useEffect的清理函数。uniapp小程序页面的onUnload同样要处理。只依赖store还不够必须在每一个可能销毁组件的地方都加上清理动作。3.4 事件协议与生成状态机设计SSE接口返回的不只是内容文本还包含多种事件类型。V1项目的协议设计是type字段区分title生成会话标题、content增量回答文本、done任务结束、error服务端错误。客户端在onMessage里根据type分发到不同处理逻辑。这个协议让生成状态机变得很清晰。我把生成过程定义为四个状态空闲、生成中、已中断、已完成。用户操作对应三个动作开始、停止、切换。状态机的流转规则是空闲时才能开始生成中才能停止停止后再次开始必须重新创建AbortController切换会话时自动执行停止。协议和状态机一定要在设计阶段就定好。V1早期后端同学返回的数据结构没有完全统一出现过一次返回纯字符串、一次返回JSON字符串、一次返回带markdown标记的文本前端被迫写了三种解析分支。后来把协议格式固化为JSON结构每种类型字段含义明确前端解析逻辑稳定了很多。这件事给团队的教训是流式接口的协议文档和普通接口一样重要甚至会更重要因为流过过程中的每个字段都牵涉到界面状态变化。4. 组件层与工具层的封装沉淀4.1 消息流组件的封装要点AI对话页面最核心的组件是消息列表这个组件在V1里经历了两轮重构。第一版是每个页面各自渲染消息列表样式和交互都差不多但代码重复了三份。第二版把消息列表抽成通用组件暴露的消息数组、加载状态、生成状态、滚动行为等几个props结果发现还是不够因为不同页面对消息气泡的渲染差异很大。最终敲定的组件设计方案是消息列表组件只负责渲染结构、滚动管理、点击事件回调不关心消息内容的具体展示。消息内容通过插槽传入这样提问气泡、回答气泡、代码块、表格等都可以由外部自定义渲染。这个设计让消息列表组件在AI对话页、历史记录页、分享页里都能复用改动最小。组件里比较难处理的是自动滚动。用户滚动到底部时新消息来了要自动滚到底用户上翻查看历史时新消息就不能抢走滚动位置。V1实现方案是记录滚动容器的scrollTop和scrollHeight差值如果差值小于阈值则认为在底部否则停留在当前位置。这个逻辑虽然代码不多但如果每个页面都写一遍很容易写出bug封装进组件后就不怕漏了。4.2 工具函数的二次封装工具函数是封装最容易过度的地方但V1项目里确实沉淀了几个高频复用的函数。最典型的是停止生成按钮上的防抖逻辑用户连续点击发送按钮时短时间内发出多个请求会把会话顺序搞乱我在发送入口加了一个300毫秒的防抖确保只有最后一次点击生效。还有markdown渲染。AI回答基本都是markdown格式uniapp里没有现成的markdown组件V1选择了自己封装一个组件内部包含解析、代码高亮、代码块复制按钮。封装这个组件的难点不在解析本身而在代码块复制在uniapp里要区分H5和小程序H5用navigator.clipboard小程序要用uni.setClipboardData这个差异被收敛在组件内部业务方不用感知。另外用户输入的安全性也要注意。AI回答里可能出现HTML标签必须转义后再渲染否则会注入页面。V1在markdown组件里默认做了XSS过滤把脚本标签和事件属性全部剥离。这个安全细节在封装时一定要考虑进去否则组件给业务方用就是埋雷。4.3 用git做封装版本对比与回溯封装过程中代码变动很大版本管理必须跟上。V1项目发布前打了个v1.0.0的tag然后对照v0.9.0拉了一遍差异重点看封装的公共模块有没有改动到不该动的地方。# 打版本标签 git tag -a v1.0.0 -m V1 release: request layer SSE components # 查看两个版本间公共模块的改动 git diff v0.9.0 v1.0.0 -- src/request/ src/components/ src/utils/ # 找出封装接口的签名变化 git diff v0.9.0 v1.0.0 -- src/api/这里有几个实操心得。一个是封装模块的API签名尽量在V1阶段冻结后面只改内部实现。另一个是公共模块的改动要在提交信息里写清楚影响范围V1团队约定的提交格式是type(scope): message比如refactor(request): add cancelToken map这样回看历史时一眼就知道哪些提交动了封装层。版本对比不只是为了发版记录更重要的是给V2开发提供决策依据。通过git log --oneline v0.9.0..v1.0.0能看到哪类改动最频繁这些频繁改动的点就是V2需要进一步优化的封装方向。5. 踩坑记录与排查技巧实录5.1 问题速查表V1封装过程中遇到了一堆真实问题我整理成了速查表方便大家直接对照排查。问题现象根本原因解决方案SSE中文乱码TextDecoder未传stream参数解码时传{ stream: true }点击停止后文字仍继续输出abort后未及时更新generating状态停止逻辑同时abort并置状态且finally兜底第二次请求秒失败复用了已abort的AbortController每次请求new一个新controller同一接口重复请求双击触发多个请求请求层统一cancelToken管理后发取消先发登录失效后旧请求仍回调未统一取消pending请求401时调用cancelAllRequestsH5打包后接口指向错环境配置中心只判断了构建模式未判断运行时域名使用location.host动态判断站点类型接口域名切换漏改业务页面硬编码baseURL所有调用收敛到api模块配置文件统一管理用户上翻历史时自动滚到底部滚动判断逻辑错误根据scrollTop与scrollHeight差值判断是否吸底这些坑大多数只出现一次因为我坚持把修复方案沉淀回封装层而不是在某个页面里打补丁。比如解码乱码的修复是改fetchSSE内部一行所有用到SSE的页面同时受益如果当时在AI问答页内部绕过去其他页面还会踩同一个坑。5.2 从现象到根因的三次真实排障第一次排障是线上H5被反馈API地址指向了测试环境。当时的配置方案只在构建时用import.meta.env.MODE区分环境生产构建的包却部署在了两个域名下一个走正式网关一个走灰度网关共用同一份静态资源运行时无法区分。排查从配置中心开始先确认构建产物再用window.location.host打印对比几分钟就确定了是运行时域名的判断缺失。修复方案就是前面第2章里说的getDomainLevel()函数把站点归属判断放进请求层。第二次排障比较隐蔽现象是部分用户反馈AI回答到一半就停了没有任何报错。查日志发现SSE连接还在但数据不再流动。后来复现确认是服务端网关空闲超时设置太短30秒没有新数据就断开连接。前端没有重连机制SSE直接结束。这个问题的前端修复是在onError里增加自动重试最多重试两次中间加1秒延迟。断线重试逻辑放在fetchSSE内部因为所有流式接口都想用这个能力。第三次排障是小程序端偶发token失效但请求还在继续。原因是退出登录时只清了本地storage没有打断进行中的请求接口回调里拿到401又触发一次登录跳转形成循环。修复方案是在登录失效逻辑里先cancelAllRequests()再跳转页面。这个顺序很重要先取消再跳转否则请求回调先于页面跳转执行会出现短暂的白屏和报错。5.3 什么时候该停止封装不夸张地说V1项目里我犯过的最严重错误是过度封装。有一次为了统一处理列表加载状态我写了一个高阶函数把loading、error、retry、分页全部收敛进去结果业务方用了这个高阶函数之后发现它的配置项比直接写列表逻辑还复杂新同事接手时需要查半天文档才能跑通一个简单列表。那次之后我立了一条规矩每个封装函数必须让调用方的代码明显变短、变清晰否则这个封装是负资产。封装不是把复杂度藏起来而是把复杂度挪到它该在的地方。如果一个组件、一个函数、一个模块的调用成本大于使用成本就没有封装的价值。V1后期的判断标准是一个封装点是否有超过两个调用方是否有明确的稳定接口内部实现是否可以独立修改而不影响外部这三个问题只要有一个回答是否就要重新考虑封装方案。封装过度和封装不足都是病只有符合项目实际节奏的封装才是有价值的。6. 从软件封装到硬件封装一个跨界视角6.1 PCB封装思想对软件封装的启发整理V1总结时我偶然翻到硬件PCB封装的资料并联想到热搜里大量关于ALLEGRO封装制作、AD封装库、0603/0805封装尺寸、emmc封装引脚的内容。硬件里的封装和软件里的封装字面相同语法各异但思想底层惊人地一致。拿PCB封装库来类比。原理图里的symbol定义的是芯片的逻辑引脚功能比如引脚1是电源、引脚2是地、引脚3是时钟PCB里的footprint定义的则是实体焊盘的物理尺寸和位置。symbol和footprint通过引脚编号映射关联同一个逻辑芯片可以对应多种物理封装换封装只需要替换footprint不需要改原理图。这不就是软件封装里的接口与实现分离吗我们设计request.js的对外方法时业务方依赖的是request.get这个symbol至于内部是用axios还是fetch实现就是footprint层面的事换HTTP库不用改业务代码。再看0805封装尺寸、0603封装尺寸这些参数为什么要标准化因为标准化的封装能让不同厂商的器件互相替换、让贴片机能稳定生产、让设计者不用每次重新发明轮子。软件封装的标准化意义也一样统一的请求封装、统一的事件协议、统一的组件接口让团队协作时不用每次重新约定让新人接手时不用重新翻代码。ALLEGRO制作封装的流程里有一句很关键的经验封装必须经过DRC验证才能使用引脚间距、焊盘大小、丝印层标注都要核对。软件封装同样需要DRC——请求接口签名有没有版本兼容性检查组件props有没有写类型校验SSE协议字段有没有运行时防御这些检查在V1阶段不一定做得很完善但至少要建立意识否则封装库就成了藏bug的仓库。6.2 这些思想在V2里还能怎么用V1结束后我在复盘文档里给V2列了几个方向全都沿用了硬件封装的思维。第一个方向是封装库的组件化与版本化。V1的组件封装是散在仓库里的V2计划把通用组件、请求封装、SSE工具整理成独立npm包打版本号业务工程通过依赖引入。这就相当于硬件团队维护一个统一的封装库网站项目引用时锁定版本降级回滚都有据可查。第二个方向是引脚兼容设计。V2的AI交互层计划支持接入多个大模型厂商就像PCB里同一个符号对应多个footprint。我把对话接口设计成适配器模式每个模型一个适配器对外暴露相同的方法签名业务层完全无感。这个设计如果V1阶段就做切换模型会容易很多。第三个方向是自动化验证。硬件封装有DRC检查软件封装也应该有接口契约测试。V2我给请求层和SSE层设计了自动化测试用例保证封装接口签名不回归、中断逻辑不失效、多域名指向不误配。这些测试跑在CI里每次提交都会检查就不怕封装层被无意破坏。7. 最后聊几句实操感受V1这个项目做完封装与总结我最深的一个体会是封装不是高深的设计模式也不是代码洁癖而是给团队减少认知负担的过程。V1刚开发时大家都在赶功能散落的代码能跑就行但越到后期越发现每一次需求变更都要在重复代码里打补丁每一处流式输出逻辑都要重新排查一遍。我个人现在更倾向的做法是封装从第一行代码就考虑但不要在第一天就做完。先让功能和逻辑自然暴露等重复出现三次左右再动手抽离同时把封装的接口设计得尽量贴近业务语义。像sendChatMessage、stopGenerate这样的方法名业务方一看就懂不需要读内部实现。还有一个小技巧值得分享V1封装的每一个公共模块我都写了一个短小的README放进对应目录不是正式文档就三五行写明这个模块是干什么的、调用示例是什么、改内部实现时要注意什么。这个习惯在后来的排障和交接里帮了大忙新人接到AI问答模块时打开目录就知道该用什么不该用什么。V1只是开始封装也永远没有终态。希望这些踩过的坑和整理好的方案能帮你少走几步弯路。
AI对话项目封装实战：从axios到SSE流式输出与多域名配置
最近我把手头一个AI交互类项目做到了V1阶段的整体收口核心动作就俩字封装。这个V1项目是一个多端AI问答助手前端覆盖了PC端、H5和小程序后端能力基于大模型的SSE流式输出。V1开发到后期代码里满是散落的axios调用、到处重复的中断逻辑、每个页面都要重新处理的域名切换以及一堆说不清归属的工具函数。这才意识到V1不只是一个功能版本更是一次封装的边界测试。这篇文章把整个封装过程完整记录下来包括请求层二次封装、SSE流式渲染与abort中断控制、uniapp H5多域名指向方案、组件与工具沉淀以及真实踩过的坑适合正在做AI对话类应用、需要管理多端请求层、或者正在犹豫要不要做封装重构的前端同学参考。1. 这个V1项目要封装的到底是什么1.1 项目形态与三个核心痛点先交代一下项目背景。这是一个面向企业客户的AI知识库问答工具用户在Web端或者小程序里输入问题后端调用大模型接口把回答以SSE流式数据实时推回前端。V1的核心功能不复杂但就是不复杂的三个字骗了很多人。开发到中后期我梳理了一下代码仓库痛点集中在三个地方。第一个痛点是请求层完全裸奔每个页面直接import axios然后各自设置baseURL、各自处理token、各自写错误提示一旦接口域名需要切换得全局搜索替换。第二个痛点是AI流式输出的逻辑散落在组件内部有的用EventSource有的用fetch手动解析生成过程中的停止按钮、超时处理、组件卸载时的请求清理都没有统一方案导致用户点停止之后画面还在滚动输出组件已经销毁了网络请求还在跑。第三个痛点是多端适配uniapp打包出来的H5要按不同域名指向不同API环境小程序端又有一套独立逻辑配置分散导致改一处漏三处。这三个痛点对应到文章后面就是请求层封装、AI交互层封装、多域名配置封装。V1阶段的封装不是把代码包一层就完事而是要把这些高频变化点收敛成少数几个稳定的入口。1.2 从OOP三大特性到业务封装的层次理解说到封装很多同学第一反应是OOP里的封装继承多态脑子里浮现的是class、private、protected。这些概念本身没错但放在真实项目里容易产生误导。V1项目里我最大的体会是业务封装跟前端框架层面的抽象根本是两个层次的东西。类层面的封装强调的是信息隐藏把属性私有化对外暴露方法调用方不需要知道内部怎么实现。业务层面的封装做的是同一件事把变化点藏起来对外暴露稳定的语义接口。比如请求层封装业务方只需要调用request.get()或者request.post()不需要关心当前是哪个域名、token怎么拼、错误码怎么映射。再比如AI交互层业务方只需要startGenerate()和stopGenerate()不需要关心SSE解析逻辑和中断细节。所以封装继承多态里的封装是手段而业务封装是目的。V1项目里我们没有刻意去设计复杂的继承关系也没有硬造一堆抽象基类而是先找出那些每个页面都要写一遍、每次需求变更都要动一遍的代码把它们往同一处收敛。这才是这个阶段真正该做的封装。1.3 封装时机的判断标准什么时候该封装什么时候不该封装这大概是V1团队里争论最多的问题。我的判断标准只有三条。第一条重复出现三次以上才值得封装。只有一两个地方用到的逻辑强行抽出来反而增加跳转成本读代码的时候还得来回翻文件。V1里某个时间格式化函数一开始只在消息列表里用到我没有抽后来历史记录页面、详情页都开始用凑够三次才下沉到工具层。第二条变化频率高的点必须封装。域名切换、token注入、错误码映射、流式中断这几个点在整个V1迭代过程中反复变不封装的代价就是每次改需求都要把所有调用处翻一遍漏改一处就是线上事故。第三条调用方和使用方属于不同团队或者不同模块时接口必须稳定。AI交互逻辑由前端组自己用还稍微宽松一点但请求层是全局基础设施一旦业务方开始依赖接口就不能随意变。V1的请求层从第一版设计开始就定了get/post/put/delete四个方法签名后面内部实现大改过三次业务方零改动。这三条标准可以帮大家在过度封装和不封装之间找到一个平衡点。V1项目里我也踩过过度封装的坑后面专门有一节讲什么时候该停止封装。2. 网络请求层的二次封装从axios到业务层2.1 为什么不能绕过axios直接调后端有同事问过一个问题axios本身已经支持拦截器、超时、取消请求为什么还要再包一层直接在每个页面用axios不就行了这个问题看起来有道理但放到V1这个多端多域名的项目里完全站不住脚。axios只是HTTP客户端它不管业务层的约定。比如我们后端有个统一响应包装code字段为0才是成功message字段直接给用户看这些约定如果在每个页面各写一遍判断将来后端改字段名就是灾难。再比如登录态失效时的401统一处理如果散落在页面里有的弹提示、有的静默失败、有的跳转登录页用户看到的行为完全不一致。二次封装的价值是把HTTP通信和业务语义剥离开。HTTP层面的事交给axios处理业务层面的约定收敛到封装层。实际开发中页面里不该出现response.data.code这样的代码所有业务判断都在拦截器里完成业务方拿到的就是已经处理好的业务数据或者被拒绝的错误。这就是封装后调用方心智负担大幅下降的原因。2.2 多域名多环境的baseURL自动指向方案V1项目里域名问题比较棘手因为AI交互场景涉及多个后端服务。主API是一个域名文件上传是另一个域名SSE流式接口又挂在独立网关下面这些服务在开发、测试、生产环境各有不同地址。再加上uniapp H5打包后要挂在不同入口域名下指向不同环境这就是热搜里说的uniapp封装h5如何指向2个域名的真实场景。我采用的方案是环境配置文件加运行时判断双管齐下。// config/index.js const ENV_MAP { dev: { main: https://dev-api.example.com, upload: https://dev-upload.example.com, stream: https://dev-stream.example.com }, test: { main: https://test-api.example.com, upload: https://test-upload.example.com, stream: https://test-stream.example.com }, prod: { main: https://api.example.com, upload: https://upload.example.com, stream: https://stream.example.com } } function getEnvKey() { // uni-app里可以用process.env.NODE_ENV也可以用自定义变量 if (import.meta.env?.MODE) { return import.meta.env.MODE development ? dev : prod } return prod } export function getBaseURL(service main) { const env getEnvKey() return ENV_MAP[env][service] || ENV_MAP[env].main } export function getDomainLevel() { // H5场景下通过location.host判断当前站点 if (typeof window undefined) return main const host window.location.host if (host.startsWith(kb.)) return kb if (host.startsWith(admin.)) return admin return main }H5页面里调用接口时就可以根据站点类型自动决定走哪套API域名。实际遇到的情况是知识库站点挂载在kb.example.com管理后台挂在admin.example.com两套站点共用一套前端代码但API网关入口不同。用运行时host判断之后打包产物就一份部署到不同域名下自动适配。这是我在V1里比较满意的一个细节。小程序端不用location.host就在config里根据uni.getAccountInfoSync().miniProgram.envVersion判断是开发版、体验版还是正式版再映射到对应环境。多端配置看起来代码量不大但把这些逻辑从业务代码里抠出来是请求层封装的第一步。2.3 拦截器、错误码与取消请求的统一处理axios二次封装的重点在于两个拦截器。请求拦截器负责注入token、设置baseURL、附加公共参数响应拦截器负责统一解析业务包装、统一错误提示、统一处理登录失效以及识别取消请求。V1项目的错误码规范是后端定的code为0表示成功非0时message可直接展示给用户。响应拦截器里的逻辑不能只判断HTTP状态码还要判断业务码。同时要考虑一种特殊情况用户主动取消请求时axios会抛出一个ERR_CANCELED错误这个不能走业务错误提示否则用户点一下停止按钮就弹一条报错体验极差。关于取消请求我建议所有请求在发起时都注册cancelToken回调放到一个全局Map里统一管理。这样登录失效时可以把所有进行中的请求全部取消不再给他们回调的机会。V1的AI问答页面里用户切换会话、退出登录、组件卸载时都会调用这个统一取消方法。// request/index.js import axios from axios import { getBaseURL } from /config const service axios.create({ timeout: 30000 }) const pendingMap new Map() function addPending(config) { const key ${config.method}:${config.url} config.cancelToken new axios.CancelToken((cancel) { pendingMap.set(key, cancel) }) } function removePending(key) { if (pendingMap.has(key)) { pendingMap.get(key)() pendingMap.delete(key) } } export function cancelAllRequests() { pendingMap.forEach((cancel) cancel()) pendingMap.clear() } service.interceptors.request.use((config) { removePending(${config.method}:${config.url}) addPending(config) const token uni.getStorageSync(token) if (token) { config.headers.Authorization Bearer ${token} } const serviceName config.service || main config.baseURL getBaseURL(serviceName) return config }, (error) Promise.reject(error)) service.interceptors.response.use( (response) { const res response.data if (res.code ! 0) { uni.showToast({ title: res.message || 请求失败, icon: none }) return Promise.reject(new Error(res.message || request error)) } return res.data }, (error) { if (axios.isCancel(error)) { return Promise.reject(Object.assign(error, { isCanceled: true })) } const status error.response?.status if (status 401) { uni.showToast({ title: 登录已过期请重新登录, icon: none }) cancelAllRequests() // 路由跳转登录页逻辑 } else if (status 500) { uni.showToast({ title: 服务异常请稍后重试, icon: none }) } return Promise.reject(error) } ) export default service这段代码在V1项目里稳定跑了三个月。值得一提的一个细节是加pendingMap如果同一接口短时间内重复点击先取消前一个再发新的避免用户双击导致重复请求堆积。这是个容易被忽略的场景但在AI问答里用户连续点击发送按钮的概率非常高。2.4 业务层的api模块封装请求层封装只是地基业务接口层还需要再包一层让页面完全感知不到HTTP细节。V1项目里每个业务域一个文件方法名直接对应后端接口语义。// api/chat.js import request from /request export function sendChatMessage(data) { return request.post(/chat/send, data, { service: main }) } export function getChatHistory(params) { return request.get(/chat/history, { params, service: main }) } export function uploadAttachment(file) { return request.upload(/file/upload, { file, service: upload }) }到这里业务方调用就变成了一行await sendChatMessage(data)不用关心baseURL、不用拼接路径、不用处理loading和错误码。我见过一些项目在页面里直接写request.post(/api/xxx)这其实只做了一半封装。真正的封装要连接口路径也收口否则后端改路径时页面还是要跟着改。接口层封装还有一个附带好处方便mock。V1早期后端并发紧张时前端只需要在api模块里加一个条件判断开发环境返回mock数据页面完全不需要改。这个优势在联调阶段非常明显。3. AI交互逻辑的封装SSE流式输出与中断控制3.1 为什么选SSE而不是WebSocket或轮询AI对话场景的技术选型上团队内部做过一轮讨论大模型回答是单向流式返回服务端持续往客户端推文本客户端基本不往服务端发消息这种情况下轮询、WebSocket、SSE三种技术各有适合场景。轮询的缺点很直观每隔一两秒拉一次接口消息延迟高而且大量请求是无效的服务端压力大用户体验也差。WebSocket是全双工协议能力强但复杂度也高需要处理连接维持、心跳、断线重连、消息帧解析对项目前期的交付压力太大。SSE是Server-Sent Events基于HTTP长连接服务端单向推送浏览器原生支持协议简单连接断开还能自动重连。对大模型流式输出这个场景SSE几乎是量身定做的。唯一需要注意的是EventSource的限制不仅只支持GET请求还不能自定义请求头token只能拼在URL上不太安全。所以V1方案里没有直接用new EventSource(url)而是用fetch加上ReadableStream来手动解析SSE协议这样既能用POST传递消息体也能在Header里带token还能在需要的时候用AbortController随时掐断连接。3.2 fetchReadableStream的SSE实时渲染实现SSE协议格式比较简单服务端返回的内容按data:开头多个事件之间用空行分隔。用fetch收到响应之后body是一个ReadableStream需要用getReader()逐块读取按行切分逐条解析。// utils/sse.js export async function fetchSSE({ url, body, token, signal, onMessage, onDone, onError }) { try { const resp await fetch(url, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${token} }, body: JSON.stringify(body), signal }) if (!resp.ok || !resp.body) { throw new Error(HTTP ${resp.status}) } const reader resp.body.getReader() const decoder new TextDecoder(utf-8) let buffer while (true) { const { done, value } await reader.read() if (done) break buffer decoder.decode(value, { stream: true }) // SSE事件以空行分割按行取出 const lines buffer.split(\n) buffer lines.pop() || for (const line of lines) { const trimmed line.trim() if (!trimmed.startsWith(data:)) continue const dataStr trimmed.slice(5).trim() if (dataStr [DONE]) { onDone onDone() return } try { const json JSON.parse(dataStr) onMessage onMessage(json) } catch (e) { console.warn(SSE parse error:, e) } } } } catch (error) { if (error.name AbortError) { console.log(SSE aborted by user) return } onError onError(error) } }这个封装函数在V1项目的多个页面里复用AI对话页用它拿流式回答语音转写结果页也用它推送转写进度。几个页面之间的差异只是onMessage里的业务处理不一样协议解析逻辑统一收敛在这里。有个细节需要特别强调TextDecoder的stream参数必须传。decoder.decode(value, { stream: true })意味着本次解码可能不完整中文字符的UTF-8字节被拆到两次读取时stream模式能把未完成的字节保留到下一次解码。我第一次写的时候漏了这个参数英文内容一切正常切到中文问答就频繁出现乱码和半个字符。这个问题排查了整整一个下午最后发现就是一行参数的事。3.3 AbortController的正确打开方式AI问答场景对中断控制的诉求特别强烈。用户点击停止按钮要立即停止文字输出切换会话要中断上一个还没生成完的回答页面销毁时所有网络请求必须终止否则会造成请求泄漏和状态错乱。V1项目在store层做了一层AI交互状态管理把开始生成、停止生成、会话切换的逻辑统一收口。// store/chat.js import { fetchSSE } from /utils/sse export const useChatStore defineStore(chat, { state: () ({ messages: [], generating: false, sseController: null, currentAnswer: }), actions: { async startGenerate() { if (this.generating) return this.generating true this.currentAnswer const controller new AbortController() this.sseController controller try { await fetchSSE({ url: ${getBaseURL(main)}/chat/stream, body: { messages: this.messages }, token: uni.getStorageSync(token), signal: controller.signal, onMessage: (json) { if (json.type content) { this.currentAnswer json.text this.updateLastMessage(this.currentAnswer) } else if (json.type title) { this.setTitle(json.text) } }, onDone: () { this.generating false this.sseController null }, onError: (err) { this.generating false this.sseController null console.error(err) } }) } finally { this.generating false this.sseController null } }, stopGenerate() { if (this.sseController) { this.sseController.abort() this.sseController null this.generating false } }, switchSession(sessionId) { this.stopGenerate() // 切换会话逻辑 } } })这里有个非常关键的设计把sseController放进store而不是放在组件data里。因为组件可能被销毁但store是全局的切换页面、切换会话、点击停止按钮时都可以通过store拿到正在执行的请求实例并中止。AbortController的使用还有一个隐藏细节当控制器被abort之后同一个controller无法复用必须在每次新请求时重新new AbortController()。我在V1里就是因为复用了旧controller导致第二次请求直接秒失败。每次生成前都要创建新的实例这是abort语义的基本要求。另外页面卸载时也要主动调stop。Vue3的onUnmounted里调chatStore.stopGenerate()React里对应useEffect的清理函数。uniapp小程序页面的onUnload同样要处理。只依赖store还不够必须在每一个可能销毁组件的地方都加上清理动作。3.4 事件协议与生成状态机设计SSE接口返回的不只是内容文本还包含多种事件类型。V1项目的协议设计是type字段区分title生成会话标题、content增量回答文本、done任务结束、error服务端错误。客户端在onMessage里根据type分发到不同处理逻辑。这个协议让生成状态机变得很清晰。我把生成过程定义为四个状态空闲、生成中、已中断、已完成。用户操作对应三个动作开始、停止、切换。状态机的流转规则是空闲时才能开始生成中才能停止停止后再次开始必须重新创建AbortController切换会话时自动执行停止。协议和状态机一定要在设计阶段就定好。V1早期后端同学返回的数据结构没有完全统一出现过一次返回纯字符串、一次返回JSON字符串、一次返回带markdown标记的文本前端被迫写了三种解析分支。后来把协议格式固化为JSON结构每种类型字段含义明确前端解析逻辑稳定了很多。这件事给团队的教训是流式接口的协议文档和普通接口一样重要甚至会更重要因为流过过程中的每个字段都牵涉到界面状态变化。4. 组件层与工具层的封装沉淀4.1 消息流组件的封装要点AI对话页面最核心的组件是消息列表这个组件在V1里经历了两轮重构。第一版是每个页面各自渲染消息列表样式和交互都差不多但代码重复了三份。第二版把消息列表抽成通用组件暴露的消息数组、加载状态、生成状态、滚动行为等几个props结果发现还是不够因为不同页面对消息气泡的渲染差异很大。最终敲定的组件设计方案是消息列表组件只负责渲染结构、滚动管理、点击事件回调不关心消息内容的具体展示。消息内容通过插槽传入这样提问气泡、回答气泡、代码块、表格等都可以由外部自定义渲染。这个设计让消息列表组件在AI对话页、历史记录页、分享页里都能复用改动最小。组件里比较难处理的是自动滚动。用户滚动到底部时新消息来了要自动滚到底用户上翻查看历史时新消息就不能抢走滚动位置。V1实现方案是记录滚动容器的scrollTop和scrollHeight差值如果差值小于阈值则认为在底部否则停留在当前位置。这个逻辑虽然代码不多但如果每个页面都写一遍很容易写出bug封装进组件后就不怕漏了。4.2 工具函数的二次封装工具函数是封装最容易过度的地方但V1项目里确实沉淀了几个高频复用的函数。最典型的是停止生成按钮上的防抖逻辑用户连续点击发送按钮时短时间内发出多个请求会把会话顺序搞乱我在发送入口加了一个300毫秒的防抖确保只有最后一次点击生效。还有markdown渲染。AI回答基本都是markdown格式uniapp里没有现成的markdown组件V1选择了自己封装一个组件内部包含解析、代码高亮、代码块复制按钮。封装这个组件的难点不在解析本身而在代码块复制在uniapp里要区分H5和小程序H5用navigator.clipboard小程序要用uni.setClipboardData这个差异被收敛在组件内部业务方不用感知。另外用户输入的安全性也要注意。AI回答里可能出现HTML标签必须转义后再渲染否则会注入页面。V1在markdown组件里默认做了XSS过滤把脚本标签和事件属性全部剥离。这个安全细节在封装时一定要考虑进去否则组件给业务方用就是埋雷。4.3 用git做封装版本对比与回溯封装过程中代码变动很大版本管理必须跟上。V1项目发布前打了个v1.0.0的tag然后对照v0.9.0拉了一遍差异重点看封装的公共模块有没有改动到不该动的地方。# 打版本标签 git tag -a v1.0.0 -m V1 release: request layer SSE components # 查看两个版本间公共模块的改动 git diff v0.9.0 v1.0.0 -- src/request/ src/components/ src/utils/ # 找出封装接口的签名变化 git diff v0.9.0 v1.0.0 -- src/api/这里有几个实操心得。一个是封装模块的API签名尽量在V1阶段冻结后面只改内部实现。另一个是公共模块的改动要在提交信息里写清楚影响范围V1团队约定的提交格式是type(scope): message比如refactor(request): add cancelToken map这样回看历史时一眼就知道哪些提交动了封装层。版本对比不只是为了发版记录更重要的是给V2开发提供决策依据。通过git log --oneline v0.9.0..v1.0.0能看到哪类改动最频繁这些频繁改动的点就是V2需要进一步优化的封装方向。5. 踩坑记录与排查技巧实录5.1 问题速查表V1封装过程中遇到了一堆真实问题我整理成了速查表方便大家直接对照排查。问题现象根本原因解决方案SSE中文乱码TextDecoder未传stream参数解码时传{ stream: true }点击停止后文字仍继续输出abort后未及时更新generating状态停止逻辑同时abort并置状态且finally兜底第二次请求秒失败复用了已abort的AbortController每次请求new一个新controller同一接口重复请求双击触发多个请求请求层统一cancelToken管理后发取消先发登录失效后旧请求仍回调未统一取消pending请求401时调用cancelAllRequestsH5打包后接口指向错环境配置中心只判断了构建模式未判断运行时域名使用location.host动态判断站点类型接口域名切换漏改业务页面硬编码baseURL所有调用收敛到api模块配置文件统一管理用户上翻历史时自动滚到底部滚动判断逻辑错误根据scrollTop与scrollHeight差值判断是否吸底这些坑大多数只出现一次因为我坚持把修复方案沉淀回封装层而不是在某个页面里打补丁。比如解码乱码的修复是改fetchSSE内部一行所有用到SSE的页面同时受益如果当时在AI问答页内部绕过去其他页面还会踩同一个坑。5.2 从现象到根因的三次真实排障第一次排障是线上H5被反馈API地址指向了测试环境。当时的配置方案只在构建时用import.meta.env.MODE区分环境生产构建的包却部署在了两个域名下一个走正式网关一个走灰度网关共用同一份静态资源运行时无法区分。排查从配置中心开始先确认构建产物再用window.location.host打印对比几分钟就确定了是运行时域名的判断缺失。修复方案就是前面第2章里说的getDomainLevel()函数把站点归属判断放进请求层。第二次排障比较隐蔽现象是部分用户反馈AI回答到一半就停了没有任何报错。查日志发现SSE连接还在但数据不再流动。后来复现确认是服务端网关空闲超时设置太短30秒没有新数据就断开连接。前端没有重连机制SSE直接结束。这个问题的前端修复是在onError里增加自动重试最多重试两次中间加1秒延迟。断线重试逻辑放在fetchSSE内部因为所有流式接口都想用这个能力。第三次排障是小程序端偶发token失效但请求还在继续。原因是退出登录时只清了本地storage没有打断进行中的请求接口回调里拿到401又触发一次登录跳转形成循环。修复方案是在登录失效逻辑里先cancelAllRequests()再跳转页面。这个顺序很重要先取消再跳转否则请求回调先于页面跳转执行会出现短暂的白屏和报错。5.3 什么时候该停止封装不夸张地说V1项目里我犯过的最严重错误是过度封装。有一次为了统一处理列表加载状态我写了一个高阶函数把loading、error、retry、分页全部收敛进去结果业务方用了这个高阶函数之后发现它的配置项比直接写列表逻辑还复杂新同事接手时需要查半天文档才能跑通一个简单列表。那次之后我立了一条规矩每个封装函数必须让调用方的代码明显变短、变清晰否则这个封装是负资产。封装不是把复杂度藏起来而是把复杂度挪到它该在的地方。如果一个组件、一个函数、一个模块的调用成本大于使用成本就没有封装的价值。V1后期的判断标准是一个封装点是否有超过两个调用方是否有明确的稳定接口内部实现是否可以独立修改而不影响外部这三个问题只要有一个回答是否就要重新考虑封装方案。封装过度和封装不足都是病只有符合项目实际节奏的封装才是有价值的。6. 从软件封装到硬件封装一个跨界视角6.1 PCB封装思想对软件封装的启发整理V1总结时我偶然翻到硬件PCB封装的资料并联想到热搜里大量关于ALLEGRO封装制作、AD封装库、0603/0805封装尺寸、emmc封装引脚的内容。硬件里的封装和软件里的封装字面相同语法各异但思想底层惊人地一致。拿PCB封装库来类比。原理图里的symbol定义的是芯片的逻辑引脚功能比如引脚1是电源、引脚2是地、引脚3是时钟PCB里的footprint定义的则是实体焊盘的物理尺寸和位置。symbol和footprint通过引脚编号映射关联同一个逻辑芯片可以对应多种物理封装换封装只需要替换footprint不需要改原理图。这不就是软件封装里的接口与实现分离吗我们设计request.js的对外方法时业务方依赖的是request.get这个symbol至于内部是用axios还是fetch实现就是footprint层面的事换HTTP库不用改业务代码。再看0805封装尺寸、0603封装尺寸这些参数为什么要标准化因为标准化的封装能让不同厂商的器件互相替换、让贴片机能稳定生产、让设计者不用每次重新发明轮子。软件封装的标准化意义也一样统一的请求封装、统一的事件协议、统一的组件接口让团队协作时不用每次重新约定让新人接手时不用重新翻代码。ALLEGRO制作封装的流程里有一句很关键的经验封装必须经过DRC验证才能使用引脚间距、焊盘大小、丝印层标注都要核对。软件封装同样需要DRC——请求接口签名有没有版本兼容性检查组件props有没有写类型校验SSE协议字段有没有运行时防御这些检查在V1阶段不一定做得很完善但至少要建立意识否则封装库就成了藏bug的仓库。6.2 这些思想在V2里还能怎么用V1结束后我在复盘文档里给V2列了几个方向全都沿用了硬件封装的思维。第一个方向是封装库的组件化与版本化。V1的组件封装是散在仓库里的V2计划把通用组件、请求封装、SSE工具整理成独立npm包打版本号业务工程通过依赖引入。这就相当于硬件团队维护一个统一的封装库网站项目引用时锁定版本降级回滚都有据可查。第二个方向是引脚兼容设计。V2的AI交互层计划支持接入多个大模型厂商就像PCB里同一个符号对应多个footprint。我把对话接口设计成适配器模式每个模型一个适配器对外暴露相同的方法签名业务层完全无感。这个设计如果V1阶段就做切换模型会容易很多。第三个方向是自动化验证。硬件封装有DRC检查软件封装也应该有接口契约测试。V2我给请求层和SSE层设计了自动化测试用例保证封装接口签名不回归、中断逻辑不失效、多域名指向不误配。这些测试跑在CI里每次提交都会检查就不怕封装层被无意破坏。7. 最后聊几句实操感受V1这个项目做完封装与总结我最深的一个体会是封装不是高深的设计模式也不是代码洁癖而是给团队减少认知负担的过程。V1刚开发时大家都在赶功能散落的代码能跑就行但越到后期越发现每一次需求变更都要在重复代码里打补丁每一处流式输出逻辑都要重新排查一遍。我个人现在更倾向的做法是封装从第一行代码就考虑但不要在第一天就做完。先让功能和逻辑自然暴露等重复出现三次左右再动手抽离同时把封装的接口设计得尽量贴近业务语义。像sendChatMessage、stopGenerate这样的方法名业务方一看就懂不需要读内部实现。还有一个小技巧值得分享V1封装的每一个公共模块我都写了一个短小的README放进对应目录不是正式文档就三五行写明这个模块是干什么的、调用示例是什么、改内部实现时要注意什么。这个习惯在后来的排障和交接里帮了大忙新人接到AI问答模块时打开目录就知道该用什么不该用什么。V1只是开始封装也永远没有终态。希望这些踩过的坑和整理好的方案能帮你少走几步弯路。
