V1版本上线那天，产品在群里发了一晚上的庆祝消息，我盯着代码仓库却一点都高兴不起来。需求是赶出来的，联调是加班调的，主流程能跑，但代码里到处是复制粘贴的请求、写死的配置、同一个弹窗写了三套样式、接口地址散落在各个页面里。这个状态很多团队都经历过——V1最大的价值是验证了业务能跑通，代价则是技术债已经悄悄堆起来了。所以V1之后真正该做的不是急着开V2，而是把"封装"的活儿补上：把散落的逻辑收拢、把可复用的能力抽出来、把踩过的坑写进文档。这篇文章就围绕V1项目封装这件事，聊聊我做完整轮技术改造和项目总结的实操思路，包括请求层怎么二次封装、组件怎么抽、哪些地方千万别过度封装、复盘文档到底该写什么，适合正在做V1收尾或者准备开始V2的开发者参考。
1. 先从"烂摊子"说起：V1代码为什么必须做一次封装
1.1 V1交付后的真实状态
先说个扎心的真相：V1代码几乎没有不乱的。不是团队水平不行，而是V1的天然使命就是"用最小成本验证业务可行性"，这个使命本身就和代码整洁度冲突。我复盘自己的V1项目时打开仓库，发现三类典型问题：
第一类是请求逻辑完全失控。同一个获取用户信息的接口，在三个页面里各写了一遍axios调用，每个页面的loading状态、错误提示、token注入方式都不一样。有人用axios实例，有人直接axios.get，还有人封装了一个自己的request方法——结果全项目有四种请求写法。这种散落最直接的后果是：后端某天把接口路径从/api/v1/user/info改成/api/v2/user/profile，我需要改七个文件，还漏了一个。
第二类是硬编码和魔法值满天飞。翻页大小写死在代码里，状态码用1、2、3这种数字，接口超时时间每个请求单独配。最离谱的是一个字典映射表，同一个业务状态在三个文件里维护了三份，后面数据对不上了才被发现。
第三类是组件层的重复。一个确认弹窗，订单页写了一遍，退款页又写了一遍，设置页再写一遍，样式还是同一套，只是按钮文案和回调逻辑不一样。这种重复代码的维护成本是隐性的——你以为只是复制粘贴很快，实际上后续每次改样式都要同步改N个地方，漏改一个就是线上事故。
V1做完后的正确姿势，就是把这三类问题一次性收拢，也就是做一次系统性的封装重构。
1.2 如何划定封装范围
封装不是把所有代码都重写一遍，那是大爆炸式重构，风险极高。我先做了一次摸底，用静态统计的方式量化问题规模：在项目根目录跑一遍检索，数一下请求方法出现多少次、同一组件被复制了几份、配置项被硬编码的位置有多少。
# 统计 axios/get 请求的散落情况（示意） grep -rn "axios\|request(" src --include="*.ts" | wc -l # 找出复制粘贴的弹窗组件 find src -name "*Modal.vue" -o -name "*Dialog.vue" | sort拿到数字之后，我按"三层边界"来划分封装范围：第一层是基础设施层，包括请求、存储、日志、环境配置，这层必须抽，因为它是所有业务的地基；第二层是公共能力层，包括工具函数、通用组件、通用hooks，这层按"出现三次及以上"的原则抽；第三层是业务能力层，比如订单模块的表单、支付模块的回调统一处理，这层只在业务内部抽，不跨模块复用。
这个划分非常关键。很多人封装失败，就是因为把第三层的业务能力强行抽到了第二层，最后搞出一个"万能的订单组件"，参数十几个，谁也看不懂。封装范围的判断标准只有一个：这一份代码，是不是真的被两个以上互不相关的场景复用。没有复用的抽象，就是徒增复杂度。
2. 请求层封装：把散落的接口调用收拢到一个出口
2.1 axios 二次封装的最小可用设计
请求层是V1项目封装收益最高的一个点，因为它几乎触及所有页面。我见过很多团队所谓的"二次封装"就是新建了一个axios实例、导出一个request函数，然后就没有然后了。这种做法能统一baseURL，但解决不了错误处理、登录失效、重复请求这些真正烦人的问题。
我的做法是把请求封装拆成四个层次：axios实例配置、请求拦截器、响应拦截器、业务错误处理。先看axios实例和拦截器这部分核心代码：
// src/utils/request.ts import axios from 'axios' import { getToken, clearToken } from './auth' import { Message } from 'ant-design-vue' const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE_URL, timeout: 10000, // 关键点：让请求带上 cookie 凭证 withCredentials: true }) // 请求拦截器：注入 token、防重复提交 const pendingMap = new Map() function removePending(config) { const key = `${config.method} ${config.url}` if (pendingMap.has(key)) { const cancelToken = pendingMap.get(key) cancelToken('cancel') pendingMap.delete(key) } } service.interceptors.request.use( (config) => { const token = getToken() if (token) { config.headers.Authorization = `Bearer ${token}` } // 对需要防重复的请求做 cancel 处理 if (config.preventRepeat) { removePending(config) config.cancelToken = new axios.CancelToken((cancel) => { pendingMap.set(`${config.method} ${config.url}`, cancel) }) } return config }, (error) => Promise.reject(error) ) // 响应拦截器：统一错误码和登录失效 service.interceptors.response.use( (response) => { // 注意：这里返回的是业务数据，而不是整个 response const res = response.data if (res.code !== 0) { Message.error(res.message || '请求失败') return Promise.reject(new Error(res.message)) } return res.data }, (error) => { if (error.response?.status === 401) { clearToken() // 跳转登录页，同时记录当前页便于登录后回跳 window.location.href = `/login?redirect=${encodeURIComponent(window.location.pathname)}` } return Promise.reject(error) } ) export default service这里有个非常重要的设计点：响应拦截器直接返回res.data而不是整个response。这样做的好处是业务代码拿到的就是纯净的业务数据，不需要每处都写.data.data。很多团队的请求封装做了一半，就是因为拦截器没有统一返回值，业务层还是要各自拆包，等于白封装。
2.2 拦截器里真正该做的事
拦截器不是摆设，它是全项目请求逻辑的"唯一关卡"。我在实际封装中整理出拦截器真正该做的五件事，顺序也有讲究：
第一，注入凭证。token从本地存储读取，而不是从页面变量读，避免刷新丢状态。第二，统一防重复提交。用上面的pendingMap记录未完成的请求，快速点击提交按钮时直接cancel掉前一个请求，这个功能对表单页面尤其实用。第三，统一处理HTTP层错误。网络超时、断网、502这类错误，在拦截器里统一提示，业务代码不用catch。第四，统一映射业务错误码。登录失效返回401，权限不足返回403，这两个码在拦截器里统一切换页面或提示，不要散落在业务层。第五，把响应数据"剥壳"后返回，让业务层拿到的是纯数据。
这里有一个很多人踩过的坑：超时时间不要所有接口一刀切。文件上传接口和查询接口的耗时完全不同，我用config.timeout做覆盖，在调用处可以单独指定更长的超时时间，这是axios配置本身就支持的，封装时不要堵死这个口子。
2.3 流式接口（SSE）的封装思路
V1后期我们接了大模型相关的流式输出功能，这属于接口封装的一个新场景：SSE流式接口。普通的axios封装处理不了流式响应——你不能等整个响应结束了再返回数据，用户等不起，必须边接收边渲染。
我做的流式封装把传统的Promise思路改造成了"接收器模式"，核心是用fetch的ReadableStream逐块读取：
// src/utils/sseRequest.ts export async function streamRequest({ url, data, onMessage, onDone, signal }) { const response = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${getToken()}` }, body: JSON.stringify(data), signal }) if (!response.ok) { throw new Error(`HTTP ${response.status}`) } const reader = response.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 数据按双换行分割，每条消息以 data: 开头 const lines = buffer.split('\n') buffer = lines.pop() // 保留可能不完整的数据 for (const line of lines) { if (line.startsWith('data:')) { const payload = line.slice(5).trim() if (payload === '[DONE]') { onDone?.() return } onMessage?.(JSON.parse(payload)) } } } }这个封装的关键点有三个：一是用TextDecoder处理流式数据，注意要传{ stream: true }，否则中文会乱码；二是维护一个buffer，因为网络分块可能把一个完整SSE消息切成两半，不能读一块就解析一块，必须等换行符确认消息完整；三是把AbortSignal透传出去，让组件销毁或用户点击"停止生成"时能干净地中断请求。
流式接口封装做完之后，页面调用变成了一个非常简洁的形态，业务层不再关心底层到底是fetch还是WebSocket，只管"来一段渲染一段"。这才是接口封装应该达到的效果——调用的人不需要知道细节。
3. 组件与工具层封装：把重复劳动沉淀成资产
3.1 组件抽取的判断标准
请求层封装完之后，我接着处理组件重复的问题。组件抽取是最容易做过头的一层，所以我给自己定了一个硬性标准——"三处复用原则"：同一段UI结构和交互逻辑，在三个及以上互不相关的业务场景中出现，才值得抽成公共组件；只有两处使用时，先复制一份，等第三次出现再抽。
为什么是这个标准？因为组件抽取本身是有成本的：抽象props、设计插槽、考虑边界场景，这些工作量比复制粘贴大得多。如果只出现两次就抽，很可能抽完就发现两个场景的需求已经开始分叉了——一个要左边对齐，一个要右边对齐，你得为这个分叉加一个props，第三次、第四次分叉继续加，最后组件比原来的代码还难维护。
我的V1项目里抽得最成功的是一个"表格+筛选+分页"组合组件。三个列表页（订单列表、退款列表、操作日志）结构几乎一致，都是顶部筛选表单、中间表格、底部翻页。我把它们抽成一个ProTable组件，设计成数据驱动：
<!-- ProTable.vue 的核心 props --> <template> <div> <SearchForm :fields="searchFields" @search="handleSearch" /> <Table :columns="columns" :data-source="dataSource" :loading="loading" /> <Pagination :current="page" :total="total" :page-size="pageSize" @change="handlePageChange" /> </div> </template>抽完之后，页面的代码从几百行浓缩到几十行，只需要声明字段配置、列配置和请求函数。但这个组件之所以没翻车，是因为我严格控制了它的"业务边界"——它只负责渲染和数据状态管理，不掺入任何具体业务逻辑（比如订单状态怎么流转、退款金额怎么计算）。业务逻辑通过@loadData事件抛给父组件处理。
3.2 公共方法与配置封装
组件之外，工具函数和配置项也需要收拢。V1时代最让我头疼的是格式化逻辑到处都是——日期格式化有人用dayjs、有人用moment、还有人手写toLocaleString，输出格式还不一样。我的处理方式是建一个src/utils/format.ts，把所有格式化逻辑收口：
// src/utils/format.ts export function formatDate(date: Date | string | number, pattern = 'YYYY-MM-DD HH:mm:ss') { // 统一使用 dayjs return dayjs(date).format(pattern) } export function formatAmount(value: number | string, digits = 2) { const num = Number(value) if (Number.isNaN(num)) return '--' return num.toFixed(digits) } export function formatStatus(status: number) { // 字典表只维护一份 const MAP = { 0: '待处理', 1: '处理中', 2: '已完成', 3: '已取消' } return MAP[status] ?? '未知' }配置项封装我走的是另一个思路：环境变量优先，常量表其次，禁止在业务代码里出现魔法数字。baseURL、接口路径前缀、第三方平台的key，全部放到环境变量文件里，按.env.development、.env.production区分。业务状态码、枚举值这类固定映射，集中放在src/constants下，用TypeScript的as const锁定，保证全局只有一份定义。
这里有一个值得单独说的细节：封装配置时，顺带把git信息也做进去了。我们在V1后期经常遇到"这个bug是哪个版本引入的"这类问题，于是封装了一个基于构建时间的版本信息模块，在页面上通过一个隐藏入口就能看到当前构建的commit hash和构建时间。把这个能力沉淀成公共工具之后，排查线上问题的时间缩短了很多。
3.3 多端场景下的请求封装差异
V1做完Web端之后，我们同步启动了小程序端的开发，这时候发现"封装"这件事在不同端有完全不同的形态。小程序没有axios，用的是wx.request，但它比浏览器多了几个非常麻烦的问题：登录态管理、并发请求的token刷新、分包加载导致的基础库能力差异。
我刚接手小程序封装时，第一反应是把Web端的axios封装思路直接平移过去——统一request方法、统一错误码、统一loading。结果发现完全行不通，因为小程序请求有一个Web端没有的核心矛盾：token过期后需要静默调用wx.login换新token，但此时可能已经有多个请求在排队了，如果每个请求都各自去刷新token，会触发并发刷新，后端直接拒绝。
正确的封装姿势是维护一个"刷新中"的Promise单例，让所有等待的请求都挂在这个Promise上，刷新完成后再统一重放：
// 小程序端请求封装的核心：串行化token刷新 let refreshPromise = null function refreshToken() { if (refreshPromise) { return refreshPromise } refreshPromise = new Promise((resolve, reject) => { wx.login({ success: async (res) => { // 用 code 换取新 token const { token } = await api.exchangeToken(res.code) resolve(token) }, fail: reject }).finally(() => { refreshPromise = null }) }) return refreshPromise }这段代码的精髓就在于refreshPromise这个单例：第一个401请求触发刷新，后续的401请求不会再次触发，而是直接复用同一个Promise，等刷新完成后把各自的原请求重放一遍。如果每个请求都各自刷新，不仅后端扛不住，还会出现token相互覆盖的竞态问题。
所以封装这件事不能一套走天下，同样的目标（统一请求入口、统一错误处理），在Web端和小程序端的实现细节完全不同。封装的经验应该沉淀成"问题和解法"的清单，而不是"某段代码到处抄"。
4. 封装的边界：哪些代码不该动，哪些抽象是错的
4.1 三个迹象说明你正在过度封装
封装本身是好事，但V1项目最容易犯的错误不是不封装，而是封装上瘾。我见过一个项目，请求层套了三层：最外层是业务request，中间层是公共request，最底层是axios实例，每一层都只做了一点点事，但调用方为了搞清楚一个请求到底走了哪些逻辑，得把三层代码全部翻一遍。
我总结出三个"过度封装"的明显迹象：第一，抽象层的代码量超过了业务层的代码量。一个公司内部的项目，如果公共模块比业务模块还庞大，大概率不是业务简单，而是抽象失控了。第二，为了"将来可能用到"而设计。比如给一个只在当前页面使用的组件设计了十个props和四个插槽，理由是"以后应该会扩展"。YAGNI原则在封装领域同样成立——你现在不知道将来要什么，设计出来的"扩展点"往往全是错的。第三，调用方需要阅读源码才能理解封装的含义。封装的意义是让调用变得更简单，如果调用方不看实现就不知道怎么传参、不知道返回值是什么，那这个封装就是失败的。
4.2 封装失败的典型反模式
反模式一：万能工具函数。有人喜欢写一个processData(data, type, options)，通过type字段区分几十种处理逻辑，参数对象越来越复杂，函数体越来越长。这种"大杂烩"封装比不封装更糟，因为它把相关的逻辑拆散了，把不相关的逻辑揉在一起。正确的做法是一个函数只做一件事，功能不同就应该拆成不同名字的函数。
反模式二：继承滥用。业务组件之间有一点共性就抽一个父组件，用继承关系强行归并，结果子类需要覆写父类的一大堆方法才能工作。组件复用优先使用组合（props、插槽、组合式函数）而不是继承，尤其在前端领域，继承关系会让组件间的耦合变得极其隐蔽。
反模式三：把"长得像"当成"本质相同"。两个表单看起来长得像，但一个的提交逻辑是走订单流程，一个是走退款流程，就把它们硬抽到一个组件里，用type字段区分。结果就是组件里塞满了if (type === 'order') ... else if (type === 'refund') ...，每个新场景都要改公共组件。公共组件一旦需要为特定业务改动，说明抽象错了——它应该拆开。
4.3 我的取舍原则
经过V1这轮封装，我给自己定了几条取舍原则，供参考：
封装是给"已重复三遍的当下"付费，不是给"可能发生的未来"付费。判断一个东西要不要抽，只看它过去有没有被重复，不看它将来会不会被复用。用这个标准可以挡掉大部分过度设计。
接口不稳定的不封装。V1阶段业务还在摸索，订单状态机可能下个月就重构，此时花大力气把状态机封装成公共模块，等于绑定一个还没定型的逻辑。对不稳定的业务，允许重复，等稳定之后再一次抽干净，反而更省时间。
每次封装都要回答一个问题：调用方的代码因此变简单了吗？如果封装完之后，调用方要写的代码更少了、要理解的约束更少了，这个封装才算合格。我甚至会在封装完一个方法后，刻意把调用处的代码拿给另一个不熟悉这块的同事看，他如果不需要看实现就能用，才算通过。
5. 项目总结不是写周报：V1复盘应该沉淀什么
5.1 数据复盘与架构复盘
封装做完了，代码干净了，接下来是"总结"这个重头戏。很多人写项目总结就是一份流水账：做了什么功能、遇到了什么bug、加班了多少天，这种东西写完就没人看了。真正的项目总结应该是"下一轮项目可以直接拿来用的资产"。
我把V1总结拆成两个维度。第一个维度是数据复盘，目标是把感受变成数字。我会统计这几个指标：需求变更率（开发期间需求变更次数除以总需求数）、Bug分布（按模块、按产生阶段统计）、单模块开发耗时（用于下次估时）。拿Bug分布来说，如果数据表明60%的Bug集中出现在"表单校验"和"接口对接"这两个环节，那V2的技术方案就得在这两个环节下功夫——比如引入统一的校验规则声明、请求层的字段类型定义。
第二个维度是架构复盘，这个需要结合代码现状来看。V1项目最容易出现的架构问题是模块之间的依赖混乱：业务A直接import了业务B的内部组件，公共层反向依赖了业务层，循环引用时不时冒出来。复盘时我画了一张模块依赖图（文字版），标注每个模块的职责、对外暴露的能力、以及"不该依赖但实际依赖了"的坏味道。这张图的价值在于，V2开工时可以直接作为改造地图。
5.2 从总结里提炼可复用的清单
总结最有价值的部分，是把"经验"转换成"清单"。经验是模糊的，清单是可执行的。我从V1复盘里提炼了三份清单：
第一份是接口设计自检清单。内容包括：所有接口是否统一了返回结构？错误码是否有全局字典？分页参数是否统一？幂等性是否需要？这份清单在V2设计每个新接口时都会过一遍，避免V1踩过的坑（比如有的接口返回{data: []}、有的返回{list: []}）二次发生。
第二份是页面开发检查清单。内容包括：所有文案是否抽成了常量？空状态是否考虑？极端数据（超长文本、0条数据）是否测试？表单在提交中是否有防重复保护？这份清单我打印出来贴在工位上，每次提测前过一遍，肉眼可见地减少了低级bug。
第三份是性能检查清单。V1上线后我们遇到了首屏加载慢、图片懒加载缺失、大列表渲染卡顿等问题，我把这些问题和对应的优化手段沉淀成清单，V2的每张新页面开发时都要对照执行，而不是等问题暴露后再修。
5.3 交接文档怎么写给后来的人看
V1总结还有一个容易被忽略的用途：交接。项目可能换人维护，或者你负责的模块要交给别人。写交接文档最大的误区是"写文档等于写使用手册"，把每个函数的参数列一遍，那没有意义——代码自己就是最好的使用手册，注释都嫌多余。
真正有用的交接文档只回答三个问题：这项目是干什么的？整体架构是什么样的？有哪些坑是不能踩的？我写总结文档的固定结构是：一页纸的项目背景和核心业务流；一张文字版架构图（标注模块边界和依赖方向）；一份"踩坑记录"表，每行一个坑，写上现象、原因、解决方式；一份"改造建议"列表，记录我知道但目前没时间改的问题点。
特别是"踩坑记录"这张表，我强烈建议认真写。比如"接口A在某个边界参数下会返回500而不是合法错误码，处理时必须先判断字段是否存在""登录刷新token必须走公共方法，不能自己调login接口，否则会并发刷新"。这些信息在代码里完全看不出来，只有实际踩过的人才知道，不写下来就彻底丢了。
6. 封装与总结的收尾：一次小规模重构的真实记录
6.1 重构的节奏和验证方式
最后分享一次我实际操作的封装重构节奏。这个项目V1总共2.1万行业务代码，我用了两周半时间做封装收尾，没有一天是停工的，每步都跟着测试验证一起走。
我把顺序定成"自底向上"：先封装配置和工具函数（不涉及任何业务改动，风险最低），再封装请求层（改完所有接口调用都会切到新方法），接着抽公共组件（页面逐个替换），最后整理总结文档。每一层做完，跑一遍全量回归测试。这里的关键是：每一步都是可独立验证的增量修改，而不是推到重来。
有一点特别重要：封装和重构一定要守一个规矩——"行为不变"。我在这一轮封装里给自己定了死规定：不允许在封装的过程中顺手改业务逻辑，哪怕发现某个逻辑是错的。因为一旦把"重构"和"修bug"混在一起，出了问题你根本分不清是新封装的锅还是改逻辑的锅，排错成本直接翻倍。看到有bug，先记到TODO列表，封装完成之后再单独修。
6.2 效果量化
这轮封装做完，我用git统计和静态分析工具对比了前后数据（同分支规模下）：重复代码率从17%降到了6%左右；请求调用点从分散的40多处收敛到统一入口，新增一个接口的平均成本从半天降到一个小时左右；页面级公共组件抽出来4个，直接删掉的重复代码约3000行；因为统一了错误处理和loading逻辑，线上反馈的"操作后无反应"类问题明显下降。
数字能说明效率，但还有两件事数字体现不出来：一是新同事接手代码时的上手速度明显快了，原来要翻遍所有页面才能搞懂项目结构，现在看一眼文档里的架构图就懂了；二是后续V2新增需求时，团队不需要再讨论"这个功能应该放哪里"，封装边界已经画好了，大家照着边界填代码就行。
最后再分享一个我在这个过程中反复体会到的点：封装和总结最大的敌人不是技术难度，而是"觉得可以以后再弄"的心态。V1刚上线那周，我觉得功能都正常了，不如直接冲V2；但拖了三周之后，连我自己都开始记不清某个方法为什么要那样写了。代码的腐化速度比想象中快得多，趁着对业务和代码的上下文记忆还清晰的时候做封装总结，效果是最好的。一旦拖到V2开发到一半再回头补，你就得一边理解新需求一边回忆旧逻辑，成本直接翻倍。所以，V1版本发布会之后，真正该庆祝的不是上线这个动作，而是把这次交付变成下次交付的垫脚石。
