从手动实践到框架开发：重复代码如何变成可复用骨架

我大概到工作第三年才真正想明白框架这两个字意味着什么。当时我给自己定的框架开发实战笔记恰好整理到第六章我把这一章的第一小节命名成从手动实践到框架开发原因很朴素我见过太多人一上来就对着SpringBoot源码空谈框架却连自己项目里重复了三遍的代码都懒得抽。这篇内容算是那个6.1小节的正式展开用我自己真实走过的路子讲清楚框架到底是怎么从手动实践里一步步长出来的。如果你也是写了好几个类似功能、开始闻到自己代码里有重复味道的人这篇应该能帮你把模糊的感觉变成清晰的方法。1. 三个真实场景手动实践是怎么把我逼到想写框架的1.1 场景一每接一个第三方接口都在重复同一件事当时项目里要对接的第三方服务很多短信、支付、快递查询、电子发票五花八门。每个第三方的接口风格都不一样有的是RESTful JSON有的是SOAP XML有的还要处理一堆加密签名规则。每对接一个我的流程都高度雷同看对方文档、写签名工具、封装HTTP请求、做鉴权、加超时重试、解析返回、设计异常处理。一套下来少则一天多则一周。等到对接第五个的时候我复制粘贴的痕迹已经非常明显了连重试策略都忘了收敛五个对接代码里各写了一套有的超时时间是3秒有的是5秒有一个干脆没设超时。同事问我一笔请求失败后到底会自动重试几次我得打开三份文件才能回答他。那一刻我意识到这种手动实践压根不是勤奋而是在给团队埋雷。1.2 场景二同一个导出流程我写了六遍另一个场景更典型报表导出。一开始只是一个订单导出流程是查数据库、组装列表、用POI生成Excel、传OSS、发通知。第二个月加了一个用户导出需求流程一模一样只是查询条件和列定义变了。我当时又复制了一份把查询方法改一改列头改一改完事。第三个月同事要用同样的逻辑导出财务汇总。我看了一眼那两份几乎逐行相同的代码第一次产生了这个函数不该被复制的念头。可那会儿我只会复制硬着头皮又写了一遍。六份导出代码后来因为Excel样式调整我改了六遍其中两遍还漏改了线上导出来的表格列宽是旧的。改到第三遍的时候我连骂自己的力气都没了只想赶紧找一个不用再复制的方法。1.3 场景三测试脚本越写越像复制粘贴运动会测试这边也有类似问题。早期我们做接口自动化用的是最原始的方式Postman里存一堆请求每次上线前手动点一遍。后来开始写Python脚本用requests逐个调用断言写了一大篇。每来一个新接口测试脚本就复制旧脚本改改URL和断言。直到我接触pytest框架才注意到人家早就把收集用例、执行用例、断言、出错定位、生成报告这条流程抽象得干干净净。我只需要写一个test_开头的函数其余的交给框架。那会儿我真切感受到原来框架不是某个高深莫测的概念它就是把所有人都要重复做的那套流程替你完成掉只留出必须由你填的空。1.4 手动实践的三笔隐性账单让我真正决定动手做框架的不是代码行数而是三笔隐性成本逐渐压过来的结果。第一笔是改动成本。复制出来的每一份代码都是独立演化的修一个bug要在所有副本里各修一次漏掉一个就是线上事故。第二笔是沟通成本。就像前面那个重试超时问题代码分散在N个文件里团队里没人能说清楚标准做法到底是什么只能靠翻代码猜。第三笔是新人成本。新同事入职想搞清楚我们怎么接第三方接口得把五份对接代码都看一遍才能总结出规律。如果能有一个统一封装他只需要关心自己那部分的业务参数。这三笔成本加起来已经足以让我这种懒人下定决心重复不是勤奋是负债而框架就是用来还债的。2. 框架开发的第一步不是写代码而是找不变点2.1 用做菜理解框架的骨架流程与配料的哲学很多人面对框架开发四个字会不知所措觉得那是架构师才配干的事要么去啃Spring源码要么去买一堆设计模式的书。但我可以负责任地说框架开发的第一步跟编程语言关系不大跟设计模式关系也不大核心只做一件事把几次相似的实现摆在一起找出每次都不变的部分和每次都在变的部分。打个比方。番茄炒蛋和宫保鸡丁的配方完全不同但它们的烹饪流程骨架是一样的备料、热锅、下油、炒主料、调味、出锅装盘。饭店后厨管这个叫标准操作流程。你把这个流程写进菜谱预留几个空位让厨师填具体食材和调料这份菜谱就是一个小框架。框架开发的核心其实就是把流程固定住把变化值暴露成可填的空位。2.2 我实际怎么找不变点三次实现并排逐行对照具体做法很笨但非常有效我把之前写过的三个第三方接口对接代码并排打开逐行对照。样式完全一致的行直接用高亮标出来。结果出乎意料——签名计算、HTTP封装、超时重试、响应解析这四块超过80%的代码逐字相同。真正不同的只有三处接口URL、请求参数结构、响应结果的处理逻辑。这三处就是我这套对接逻辑里的可变点。其余那一大片相同的代码就是不变点。框架要做的事就是把这些不变点固化成骨架把可变点留成接口或配置位。2.3 可变点的四种典型类型后来我做过的框架多了总结出可变点最常见的几种类型这里用表格列出来可变点类型典型例子框架化的常用手段流程步骤可变对接接口的鉴权方式不同模板方法 钩子方法输入输出可变查询条件、返回字段不同泛型 参数化算法策略可变同一步骤有不止一种实现策略 注册表配置值可变URL、账号、超时时间不同配置化 / 约定优于配置识别出可变点属于哪一类基本上就能确定该用什么手段去框架化。这个分类动作本身比写框架代码更重要——分类错了后面全错。2.4 写到第三遍必须停下的判断标准我后来给团队定了一个简单的规矩同一段逻辑第一次正常写第二次认真抽取第三次必须停下来抽象。为什么是三次而不是两次因为两次样本太少你很难判断变化到底是真实的业务差异还是偶然情况。三次以上不变的部分基本稳定这时候抽象出来的框架才靠谱。这个判断标准帮我避免了很多为了抽象而抽象的浪费。我自己也见过反例有人刚写第二个接口就急着抽象框架结果抽象出来的API根本覆盖不了第三个场景推倒重来。记住框架不是设计出来的是从样本里归纳出来的样本够了再动手。3. 三种框架化的落地手法由轻到重框架的形态有很多种但我实际用过、可落地性最强的就三种模板方法、策略化、约定优于配置。逐个讲清楚。3.1 模板方法骨架固定钩子留口这是最入门也最安全的框架化手法。核心思路是把流程写成固定方法流程里的某些步骤开放成钩子由子类或回调函数来填充。以对接第三方接口为例我把获取Token、签名、发送请求、解析响应、统一异常处理写成模板方法把签名方式和响应解析留给调用方public abstract class ThirdPartyClient { // 模板方法定义整个流程子类不要重写 public final Response execute(MapString, Object params) { String token getToken(); String sign doSign(params, token); // 钩子方法 String resp doHttpPost(buildUrl(), params, sign); return doParse(resp); // 钩子方法 } protected abstract String doSign(MapString, Object params, String token); protected abstract Response doParse(String resp); }调用方只需要继承这个类实现doSign和doParse其他东西——超时、重试、鉴权、异常兜底——框架全包了。这比复制粘贴五个HTTP工具类要强得多因为重试策略、超时时间这类公共逻辑你以后只改一处就够了。这个手法在很多成熟框架里都能看到Spring的JdbcTemplate、各种BaseActivity、BaseService本质上都是模板方法的变体。3.2 策略与注册表把算法的选择权交给运行期模板方法适合流程相同、个别步骤不同的场景。但如果流程中某一步的实现有多个选择而且这些选择可能在运行时才决定就要用策略模式。举一个现在很热的例子AI Agent框架。做Agent的人经常要面对大模型提供商切换的问题同一段编排逻辑今天调OpenAI明天可能换DeepSeek后天切到本地部署的Qwen。那个调用大模型的动作就是一个策略点。框架的做法是定义一个统一的LLM接口各家当作策略注册进去上层编排逻辑完全不感知背后是谁。class LLMClient(ABC): abstractmethod def chat(self, messages: list[dict]) - str: ... class OpenAIAdapter(LLMClient): def chat(self, messages): ... class DeepSeekAdapter(LLMClient): def chat(self, messages): ...策略落地的关键还在于注册表。如果每次都在业务代码里new具体的Adapter那策略等于没策略。需要一个Registry让调用方只在配置文件或初始化阶段声明一次我要用哪家后面统一从注册表取。class LLMRegistry: _clients: dict[str, LLMClient] {} classmethod def register(cls, name, client): cls._clients[name] client classmethod def get(cls, name) - LLMClient: return cls._clients[name]很多主流Agent框架LangChain、agno这类的核心抽象就是这个套路。你再想想SpringBoot的自动配置本质也是这个逻辑框架定义接口starter通过条件注解加载对应实现。你从源码里读到的那些套路其实就是策略加注册表一点也不神秘。3.3 约定优于配置少写即正义但别滥用第三种手法最强大也最容易产生黑魔法感。它的核心是用一套人人遵守的约定代替显式配置让框架在绝大多数情况下什么都不用配就对了。最典型的例子还是SpringBoot。传统Spring项目要写一大堆XML配置SpringBoot直接按目录结构约定自动装配类放在controller包里框架自动认为它是Controller实现了CommandLineRunner框架自动在启动后执行它引入了一个starter依赖框架自动加载对应的自动配置类。同样的道理也体现在若依框架RuoYi上按它的命名规范写Controller用注解声明权限标识框架自动完成鉴权、操作日志、数据权限过滤。再比如pytest你只需要把测试函数命名为test_开头pytest自动收集、自动执行、自动断言连测试报告都给你生成好这就是约定优先于配置的力量。但我要提醒一句约定优于配置是把双刃剑。约定意味着隐性知识新人不知道约定框架在他眼里就是纯黑魔法出了问题完全无从下手。所以用这个手法时必须有非常详实的文档和示例代码最好在项目里提供一套完整的约定示范工程。3.4 三种手法怎么选看变化发生的位置我用一句话总结我的选择逻辑流程稳定、步骤可替换用模板方法算法多选一、运行时才决定用哪个用策略加注册表大部分场景都不需要变化、只有少数特例才要覆盖用约定优于配置。多数成熟框架是三种手法组合使用的。SpringBoot主推约定优于配置但内部大量使用条件装配策略模式对外又暴露了各种继承点模板方法。理解这三种手法再去看SpringBoot、若依、pytest这些框架的源码会有一种原来是这么回事的亲切感。4. 一次完整实战从手动接口开发到内部框架的全过程理论讲多了容易飘放一段真实经历把整个过程串起来。4.1 需求场景十几个管理后台接口同时砸过来当时负责一个后台管理系统业务方一口气提了十多个模块的CRUD接口用户管理、角色管理、公告管理、字典管理……每一个都是标准的列表查询、详情、新增、编辑、删除。如果按老路子来每个接口要写Controller、Service、Mapper、实体类、校验逻辑再加分页查询和参数校验一套下来得两三个小时十几个就是几十个小时。这块业务的重复度已经高到肉眼可见了。十个模块的差异说到底就是表名不同、字段不同、个别模块多了几个特殊校验。这不就是典型的流程不变、数据变的可变点场景4.2 第一版手动实践复制、替换、改字段、埋雷一开始我就是最原始的打法把用户管理那一套代码复制出来全局替换类名和表名再检查几处字段映射。做过的人都懂这种活儿不费脑子但费眼神而且极其容易埋坑。替换漏了某个字段编译报错倒是小事最怕的是运行期查出一个压根不该出现的字段或者分页查询把别的表的字段带出来了。那时候我干着干着就产生一种荒谬感我一天下来生产了好几千行代码但真正跟业务逻辑有关的可能只有几十行剩下全是重复的结构。这就是最典型的手动实践阶段它不创造价值只是在把已有代码复制成更多副本。4.3 第二版参数化把差异收敛到配置和泛型复制第三次之后我开始抽公共部分。思路很直接把每次必改的东西抽进配置表名、实体类、字段映射、查询条件、分页参数。Service层写一个通用的CrudService用泛型接收实体。public class CrudServiceT { Autowired private BaseMapperT mapper; public PageResultT page(PageQuery query) { return mapper.selectPage(query); } public T getById(Long id) { return mapper.selectById(id); } public int create(T entity) { return mapper.insert(entity); } public int update(T entity) { return mapper.updateById(entity); } public int delete(Long id) { return mapper.deleteById(id); } }这时候写一个新接口只需要建一张表对应的实体类继承CrudService再写一个几乎为空的Controller。每个接口的开发时间从三个小时压缩到半小时。这一版让我第一次尝到参数化的甜头我把所有不变的骨架写了一遍之后每个新需求只需要填那三分之一的差异。4.4 第三版框架化代码生成器与约定模板半小时还是太慢瓶颈变成了建实体类和空Controller这件无意义的体力活。于是参考了若依框架里的代码生成器思路根据数据库表结构自动生成实体、Mapper、Service、Controller四层代码开发者只需要手动填补业务校验等特殊逻辑。到这一步新接口的开发节奏变成了建表、跑一次代码生成器、把生成代码放进项目、补三行特殊校验、完成。十分钟左右一个接口。代码生成器本身其实就是把我们已经总结好的骨架模板用自动化手段输出出来它需要配合约定使用表名怎么转类名、字段怎么转属性、哪些类型怎么映射全是一套规则。这版做出来之后团队里最直观的感受是新来的同事第二天就能上手写接口而且写出来的代码风格和老师傅一模一样。这就是框架的价值它不止省时间还统一了团队的代码标准和心智模型。4.5 三版效率与维护成本对比对比项手动复制版参数化版框架化版单个接口耗时2到3小时约30分钟约10分钟新增接口成本复制改字段建实体继承建表生成代码改一处公共逻辑所有副本逐个改容易漏只改基类一处生效改基类生成器模板新人上手难度需要通读多份代码需要理解泛型只关心业务逻辑这个表我后来在内部技术分享里放过很多次。每次我都会强调三版的差异关键词不是代码量而是变更的传播半径。手动复制版里一次公共逻辑改动要扩散到N个副本框架化版本里公共逻辑只有一份改动天然集中。4.6 从若依和SpringBoot身上印证这个演进路线实战做完之后再回头看成熟的框架会发现它们就是别人的从手动到框架沉淀。若依框架的代码生成器本质上就是把我那第三版框架化做到极致还加上了前端页面生成你建完表它连增删改查的界面都给你生成了。SpringBoot的starter机制就是把我这套功能怎么接入各种环境这件事框架化。再比如PyTorch的nn.Module它封装好了参数管理、设备迁移、自动求导等一整套流程我们只需要写forward方法——这就是模板方法思想和框架化的最佳代表。你直接拿来用这些成熟框架就是在用别人踩过的坑换自己的时间。而你要自己写一个小框架走的也一定是类似路径先手动再参数化最后框架化。跳过中间步骤直接画架构图画出来的多半是空中楼阁。5. 框架的代价与边界千万别为了框架而框架这段得泼点冷水。框架开发很爽但不能把什么都框架化否则会从提升效率变成制造摩擦。5.1 过度框架化的典型症状配置比业务代码长我见过最典型的反面案例一个内部项目业务代码只有几千行配置文件写了上万行各种XML、YAML、属性配置层层嵌套。解Bug的时候需要像剥洋葱一样跨五六个配置文件才能弄清一个参数最终落在哪里。后来团队实在受不了推倒重来才发现大部分配置项根本是无效的是可能以后会用到才加上的。这就是过度框架化的代价框架把灵活性拉满的同时也把理解成本拉高了。灵活性和易用性是一对天然矛盾框架的每一层抽象都在消耗未来的阅读时间。所以框架开发一定要学会做减法不是把所有的可变点都开放出来而是只开放那些真实业务中出现过的可变点。5.2 该用成熟框架还是自研我的判断标准要不要自研框架我的判断标准非常简单如果市面上有成熟且被广泛验证的框架能用就用不要自研。新手最容易踩的坑是觉得自己写的框架比SpringBoot好这个概率约等于零。SpringBoot、若依、pytest、React/Vue、PyTorch这些框架背后是无数生产环境打磨出来的它们在边界情况、性能、生态上的积累远不是个人在半个月里能追上的。那什么时候该自研我总结下来需要同时满足几个条件团队内重复度极高且痛点明确、已有成熟框架覆盖不到或改造代价大于自研、你已经完成清晰的不变点与可变点分析。比如我们后来做的一套内部Agent编排框架就是因为通用Agent框架下写业务编排要粘大量胶水代码而我们的编排流程高度固定才决定自己封装一层薄薄的模板。如果你满足不了这些条件别碰自研老老实实选成熟框架。提示判断是否要自研时可以先问自己一个问题——这个坑是只有我们团队有还是全行业都有全行业都有的坑早有人填了直接拿着用只有你们团队独有的坑才值得自研去填。5.3 先手动后框架这个顺序为什么反不得最后强调一下顺序问题。我看到过不少团队上来就画架构图打算一劳永逸地设计一个完美框架结果做出来没人用。原因很简单没经历足够多的手动实践抽象出来的东西全是拍脑袋的应该会变和可能有用不是从真实业务里来的。框架的开发一定要以手动实践为前提。手动实践不是浪费时间你写的每一份重复代码都是在为抽象收集样本。样本够了框架自然浮出水面样本不够你设计出来的只是一堆装饰性抽象看着规整实际一点用没有。我自己走过的路就是最好的证明如果没有前六个第三方接口的手动实现我压根不知道签名和解析才是真正的可变点。6. 框架落地的最后一公里从我的框架到团队的框架一个框架写完真正的问题才开始怎么让团队接受它、用起来、持续演进。这里分享几条我踩过坑才总结出来的经验。6.1 文档要写怎么用更要写不要这样用文档这个问题没必要展开真正值钱的是反例。新同事用框架时最容易踩的坑不是不知道怎么用而是按错误方式用了还觉得自己没错。我后来在内部框架的文档开头专门加了一个不要这样用的区域把历史上所有人写出的错误用法列出来配上出错现象和正确做法。举个例子我们的内部CRUD框架默认带逻辑删除但有人为了省事在一个不该逻辑删除的明细表上直接调了delete方法结果数据全被假删了查都查不出来。这个案例被我写进文档的不要这样用区里后面再也没人犯过同样的错。这个区比整个代码注释都有效因为人都是看到别人摔过的坑才长记性。6.2 渐进式落地与逃生通道缺一不可框架落地最容易翻车的原因之一是要求团队一次性全量迁移。正确姿势是渐进式的先拿一个风险低的新项目做试点跑顺了再逐步把老项目迁移过来。同时框架要提供半自动模式——允许使用者绕过框架直接手动控制某些步骤保留逃生通道。没有逃生通道的框架遇到一个预期之外的业务就会变成灾难。使用者被困在框架的规则里做不了任何特殊处理只能去改框架源码改完框架的公共逻辑又污染了其他所有使用者。这个毒瘤一旦出现框架离废弃就不远了。6.3 版本演进的三阶段节奏先跑通、再加固、后扩展框架版本的演进节奏我总结为三步先跑通、再加固、后扩展。第一阶段只覆盖当前已确认的几个场景不追求完备接口保持尽量少。这时候框架多一个接口都是错因为你还不知道其他场景会怎么用。第二阶段基于真实使用反馈补齐边界处理、错误提示、日志输出把能用变成好用。第三阶段确认骨架稳了再开放插件机制、扩展点让有特殊需求的人能自行扩展。三个阶段的顺序非常重要。我见过一个框架第一天就把插件机制设计得完美精巧结果主路径都没人用插件机制成了自己欣赏的摆设。框架的扩展点永远是在使用者的真实需求逼出来之后再加提前做就是浪费。6.4 框架带给我的最大成就感与最大责任写到这里说点个人的真实感受。框架开发真正让我上头的不是代码复用或效率提升而是它把所有类似问题变成了同一套答案。以前新需求来了我要从头想一遍现在我敢跟业务方说这个不用讨论走标准流程你们只要给我三个参数。那种问题有了标准答案的感觉对工程师来说是很大的成就感。但反过来框架也是我在这一行里背过的最大的锅。框架里的一个抽象错误会被几十个项目同时放大。所以我现在的态度一直很收敛能不动底层就不动底层能动一个方法绝不动一个接口。框架的职责边界越清晰它的生命周期就越长边界一旦糊了后面只会越来越难受。最后分享一个小技巧。我每次写新功能之前都会先问自己这功能跟之前哪个功能有七分像。如果有我就把旧代码打开把那三分不同的地方先圈出来。那三分就是我该为框架预留的扩展点那七分就是我该复用的骨架。这个方法不起眼但帮我避开了大部分过度设计和重复劳动也算是我从手动实践走向框架开发这一个章节里最实用的一个落地动作。