从入门到干这一行也有十来年了我发现一个特别魔幻的现象越着急写代码的人越忙越忙就越乱。要么需求理解偏了一版推倒重来要么数据结构没想好后面加字段加到想骂人要么接口设计没对齐联调阶段每天被人 八百遍。而那些看着“磨蹭”的程序员半天不动手先拿个本子写写画画结果人家一写一个准晚上八点前就下班了。“别急着动手写代码”这句话听起来像老生常谈但真正能做到的人极少。今天我就拿自己踩过的坑和修正后的工作方式聊聊写代码之前到底要“想清楚”什么以及为什么说这一步决定了你后面改八回还是一回不改。1. 跑得快的代价需求没锁死之前每一行代码都是负债先说个很多人都有的心理任务排期就三天需求文档就两句话PM 在群里催测试在边上等你有啥可想的先写出来再说呗。我特别理解这种心态因为我自己以前就这么干——上来就建工程、加依赖、把界面框架搭出来然后开始填逻辑。结果呢填到一半发现业务流程跟我理解的根本不是一个事于是开始拆代码、挪模块、改字段。第一周产出三千行第二周删掉两千行第三周重构了一千行排期还剩四天。这不是段子是我刚带项目时最真实的写照。程序员最贵的东西不是手速而是决策质量。敲键盘这件事本身不产生价值产生价值的是你敲出来的代码能不能稳定地解决问题。可很多人在动手之前连“问题”本身都没定义清楚就急着定义“解决方案”了。1.1 每行代码都是负资产直到你证明它是对的我后来跟团队里的新人说过一句话你觉得写代码是建造但其实它是负债投资。你每写一行系统就多了一行需要维护、需要测试、需要被后来人理解的资产。如果这行代码逻辑是错的或者交付后三个星期就要被删掉那它不仅不是资产还在不断吃利息——每次改需求你都得绕开它每次出 Bug 你都得排查它。就拿一个最常见的“加个筛选功能”来说。业务方说很简单列表页加个下拉框选完就筛。你上来就开搞用了半小时把 Dropdown 封装好绑定好数据接口也调通了。但接着你会发现筛选条件要不要反映在 URL 上刷新页面能不能保留筛选状态筛完没有数据要不要显示空态“全部”这个选项算不算一个筛选项这批数据要不要在前端过滤而不是走接口这么多问题你只要漏了一个后面就是一场返工。而且不是改一处是界面改完接口改接口改完缓存改缓存改完权限还得改。1.2 返工链条需求改一个字段代码改三座城做后端的朋友体会可能更深。一个看似普通的“用户列表”需求你建了张表字段有 id、name、phone。下周产品说要加一个会员等级筛选你给表加了 grade 字段再下周说需要按注册时间排序你又加了 created_at再下周说同一个手机号可能注册多个账号你开始怀疑人生为什么不一开始就建模成“账号”和“用户资料”两张表。到最后你花了三周把表拆了重构。这个链条就是典型的“前置思考缺失”引发的连锁返工。数据库表结构是系统里最底层的契约改一张表往往意味着改实体类、改 DAO、改 Service、改接口参数、改前端展示、改缓存 key、改定时任务里的查询逻辑。很多程序员愿意花三天改代码却不愿意花三十分钟把字段关系画清楚。这个账怎么算都是亏的。2. 开工前要逼自己回答的六类问题一个都别糊弄那什么才叫“想清楚”不是说你得写一个五十页的文档也不是说要做个 UML 大图吓唬人。而是说有几个核心问题你必须能给出明确的答案。答不出来就说明还没到写代码的时候。这六类问题我每次接需求都会过一遍今天完整写出来。2.1 需求的边界做什么和不做什么都要白纸黑字“给订单列表加一个导出功能”和“给订单列表加一个支持筛选当前筛选结果的导出功能”是两个完全不同的需求。如果你没在动手之前把这句话抠清楚就会出现以下剧情你做完了导出上线了产品说不对我选了一个 5 月到 6 月的时间范围导出的 Excel 里怎么是全量数据你说你也没说要筛选导出啊产品说这还用说需求文档里不是写了“导出当前筛选结果”吗你再一看需求文档被更新过更新时间和你说“开始做”的时间完全重合。这种扯皮没人赢赢的只有加班和焦虑。所以我会在自己心里存一份“范围清单”跟需求方确认两遍第一遍这个版本明确要做什么第二遍这个版本明确不做什么。不做什么要写得更具体因为它才是保护你不被范围蔓延拖死的关键。如果一个需求说“未来可能会支持多选导出”那你现在就不要为多选做任何前置设计简单写个 id 列表即可等真正要做时再改。这不是偷懒是把钱花在刀刃上。2.2 验收标准什么算“做完”你能说出可验证的依据吗经常有朋友说“这个功能我写完了”但你问他怎么算写完他只能说“能跑起来了”。能跑起来跟“能满足需求”中间的差距可能是一整个发布会崩现场。验收标准必须可观测、可量化。举例来说你不要告诉自己“列表查询接口完成了”而是写下来给这个接口传一个空参数返回全部数据传一个存在的关键字返回最多 20 条匹配项按时间倒序传一个不存在的关键字返回空数组和 200 状态码而不是 404传一个超长字符串返回参数校验错误提示传一个 SQL 注入的拼接字符服务端不能 500。只有这样你写代码的方向才是被约束的。没有验收标准的开发就是在打一场没有靶子的仗打完了也不知道自己命中没有。2.3 数据的来龙去脉数据从哪来、到哪里去、中间怎么流转这是返工重灾区尤其是国内大量业务系统的开发大部分时间不是在跟算法较劲而是在跟数据流较劲。拿到需求后你要能做三张表输入数据表这份数据从哪个上游来是用户提交、第三方接口回调、还是本系统其他模块生成处理逻辑表每一块输入数据经过哪些规则被转换比如手机号脱敏、金额四舍五入、时间戳转时区。输出数据表最终要给谁用是前端页面、报表、还是另一个下游系统对方要什么格式、什么协议、多长时间必须拿到。这三张表能画明白你的代码结构基本就已经定了七成。什么字段放哪个表、哪个字段要不要做冗余、哪个计算应该放在数据库还是应用层、是否需要加队列削峰全部建立在“数据流”的基础上。如果你没想清楚数据流就开始写,一定会出现“变量名换三遍、对象嵌套四层、参数越传越多”这种代码天灾。2.4 异常路径和边界条件正常流程谁都会写你赢在“奇葩输入”面试造火箭、工作拧螺丝这个吐槽很真实但它容易造成一个误区觉得边界条件不重要。真实情况是你代码里 80% 的 Bug 和返工全来自边界条件没想清楚。正常流程你写 30 行代码就通了但“用户手滑输入了负数”“上游服务超时返回 null”“网络断了但前端没有错误提示”“并发下两个请求同时抢到同一张券”每一个异常分支都是一颗雷踩到哪一个产品都会在群里质问你。我的建议是在写任何业务代码前先花十分钟用文字把异常路径描述一遍列出来不一定要写代码但要写清楚系统对每种异常的反应。比如“下单”操作至少有这些分支要明确超时是要给用户一个“处理中”的遮罩还是直接提示失败库存不足时前台是提示具体缺货数量还是统称“库存不足”支付回调重复到达幂等逻辑是放在哪个节点这个列表写得越完整后面测试给你提的 Bug 就越少。2.5 接口契约和调用方你的代码不是写给自己看的很多人写代码的时候只管自己写爽了接口参数想传什么传什么字段命名想叫啥叫啥返回结构今天一个样明天一个样。等到前后端联调前端同事怒气冲冲地过来跟你说“这个字段你上星期不是这个意思啊。”你才发现一个接口反复改结构已经影响到了页面、缓存、定时任务、移动端、第三方渠道五个调用方。我个人的习惯是在写接口之前先把接口请求参数、响应结构、错误码列表、鉴权方式、是否幂等这五项写成一个“接口契约草案”哪怕用记事本写都行发给不同端的同事看一眼大家确认了再进开发。这个动作不会超过半小时但能省掉联调阶段至少一个星期的扯皮。2.6 性能底线什么样的速度是“合格”性能问题有一个特点它不是开发阶段呈现的而是上线后被用户骂出来的。这也是为什么性能约束必须在写代码之前定义而不是等压测了再优化。别跟我说“先写对再优化”等代码写完了再优化你基本已经没有心情和时间了因为返工本身就把你的时间窗口吃光了。举个最朴素的例子一个列表页要展示用户最近一年的订单每条订单要关联查询订单详情、商品信息、物流状态、售后记录。你在开发环境数据量只有几百条随便写成三层 for 循环嵌套调用都没问题速度也不慢。等上线三个月单用户订单量到了几万条接口直接 15 秒超时。所以写之前就要定底线单接口响应时间 P95 不超过 800ms单用户单次请求的数据库查询次数不超过 5 次导出的数据量超过一万条时必须走异步队列。有了标准你自然会去考虑分页、缓存、联合查询、异步等方案而不是写完再回头填坑。3. “想清楚”不是空想动手前要产出这五样东西上面说的是思考的维度但思考只有转化为可看、可讨论、可评审的产出物才算真的想清楚了。否则很容易陷入“我觉得我想明白了”的自我感觉良好里。我现在接到一个中等以上规模需求会根据复杂度选择产出以下五样东西中的几样甚至全部再动键盘。3.1 一页纸需求澄清单用来对齐认知越短越好这其实是一份只有十几个问题的文档但足以戳破绝大多数模糊需求。我会把这些问题发给需求方或产品经理要求逐条回答这个功能的核心场景是什么用户为什么要用它主要用户群体是谁他们最熟练的操作路径是什么本次必须支持的平台是哪个PC/移动端/小程序/后端有没有硬性合规要求比如数据脱敏、敏感字符过滤哪些数据是敏感数据界面和日志里都不能出现目标上线时间如果延期了可以做哪些功能裁剪性能上有没有预期值比如首屏秒开、导出在一分钟内完成。这份澄清单我不会写太长也不做成一个正式 PPT。它真正的价值在于让业务方感觉到“你是在解决问题而不是在实现一个按钮”。很多程序员不敢问怕暴露自己“没听懂需求”其实恰恰相反问得越细对方对你越有信心。一个需求方最怕的不是你问得多而是你什么都不问然后交付一个不是他想要的东西。3.2 数据字典和状态机你的系统能变出什么花样全在这张表里数据结构属于“一层错层层错”的东西。所以我的习惯是第一版就尽量把核心实体和字段定义准确后面再微调。比如面对一个订单系统我不急着建表而是先把“订单”这个核心实体的状态机画出来待支付、已支付、已发货、已完成、已关闭、退款中、已退款。每个状态之间由什么动作触发什么角色能触发触发后哪些字段被改变这些变化能不能逆操作。我见过太多线上事故就是因为状态没有定义清楚。比如用户支付成功了但业务方操作失误把一个“已支付”的订单点成了“已完成”这时候用户想退款系统怎么处理如果你没有把“已完成可以进入退款流程”这个路径写进状态机那么产品上线后客服只能靠修改数据库来处理这种退款需求这妥妥是事故而不是小问题。状态机这件事看似是设计其实是救命的。3.3 接口契约草稿前后端一把梭的前提接口是最容易被忽略、又最容易引起返工的一层。我现在不管写前端还是后端都会先拉一个文档页把接口的路径、请求方法、查询参数、请求体、响应体、错误码定义下来。可能只是一个 Markdown 列表但它能让前端用 Mock 数据先开工不用苦等后端写完才能联调。这里要额外提一嘴很多人从网上下载示例代码直接改包括 Controller 里返回 ResponseEntity 的结构、字段命名风格每个人都不一样。如果你不约定统一响应体 { code, msg, data }前端就要为每个接口单独写一套解析逻辑这是典型的“为了省五分钟思考时间制造出一个要维护一年的问题”。3.4 逻辑步骤的文字描述比画图更重要的事很多教程喜欢教大家画各种图但在真实开发里画图工具有时候反而碍事需要频繁调整框框的位置。我更常用的做法是直接将业务逻辑用口语化的文字按顺序写出来。比如写一个“订单超时自动关闭”的功能我会先写如下这段订单创建后放入延迟队列延迟时间当前时间30分钟。30分钟后定时任务触发检查订单状态。如果订单是待支付则将状态改为已关闭并释放库存。如果订单已被支付则什么都不做。如果订单已处于关闭状态也什么都不做。释放库存后要检查库存表中当前商品剩余量如果低于预警值则给运营发通知。把这五句话写下来需要的逻辑全部展开代码基本就是翻译了。一个功能如果连用文字都说不清楚说明思维是混乱的这时候写代码只会把混乱写进文件里。3.5 测试用例清单把“验证什么”写在“怎么写”前面我并不是要求所有人做完整的 TDD但有一个行为值得普及在写某个功能前先列出你要验证的五到八条核心用例。不用写任何测试代码只需要写清楚“输入是什么、预期输出是什么”。这能倒逼你把接口的输入输出设计得清晰合理。例如写一个“登录”接口前我会列以下用例正确的用户名正确密码 → 返回 token 和用户基本信息正确的用户名错误密码 → 返回密码错误且错误码为 1002不存在的用户名 → 返回用户不存在错误码为 1001连续输错五次 → 触发验证码错误码为 1003登录接口在请求头带上一个过期 token → 返回 401用户名包含脚本标签 → 必须被转义而不是直接存库有这份清单在手写代码的时候你会发现自己思路非常清晰哪里要加 if、哪里要抛异常、哪里要加注释全部一目了然。而且这份清单将来可以直接转化为测试同事的用例来源惠及整个团队。4. 一次需求迭代的真实复盘两版代码的命运讲理论讲得再多不如看一个真实的对比。去年我接了一个内部运营后台的“批量导入”需求业务逻辑不复杂运营上传 CSV 文件系统解析后校验数据通过的数据入库不通过的给出错误明细。我先用“着急版”做了一版后来又用“想清楚版”重构了一版两者的体验天差地别。4.1 第一版需求一句话就开工结果改到想离职一开始产品丢过来一句话“做个批量导入导入商户信息把错的挑出来。”我想这还不简单写了一个 Controller接收 MultipartFile然后解析每一行把校验失败的行号收集起来最后返回一个错误报告。半天写完了功能看起来一切正常。但等到联调的时候问题接踵而至。第一运营用的 CSV 可能带有 BOM 头解析出的第一列字段名乱码第二文件编码有可能是 GBK 而不是 UTF-8Excel 导出的 CSV 和 WPS 导出的 CSV 编码不一样第三导入文件可能有一万行如果中间有一行数据格式不对整个文件全部回滚运营那边就会抱怨“就一行错了怎么全都进不去”第四物流信息里的手机号需要脱敏但我入库时直接存了明文后面数据合规检查直接被通报。这四条问题没有一条是“代码难写”导致的全部是前置需求没想清楚导致的。我被迫改了不下五轮先处理编码、再处理 BOM、再改分批提交、再改脱敏逻辑。最痛苦的是第一批导入的数据已经落库了我还得写一个修正脚本去把明文手机号批量加密替换。这时我才意识到如果能提前两天把“导入文件有哪些格式要求”“超过多少行需要分批”“哪些字段涉及敏感信息”这些问题问清楚后面一行的冤枉代码都不用写。4.2 第二版花半天想清楚两天写完一次过后面系统升级要支持“批量导入结算单”我吸取了上次的教训没有第一时间建 Controller。我花了一个下午做了两件事。第一件事找运营同事把文件模板拿到手花了一个小时从真实文件里总结格式规律文件编码不固定所以要在程序里对前三个字节做 BOM 探测和编码识别表头必须有指定列名且列名顺序可以不一致需要做映射日期字段可能同时出现“2024/1/5”“2024-01-05”“20240105”三种格式需要统一格式化金额可能是“¥1,000.00”这种带货币符号的格式需要清洗规则。第二件事把所有数据处理规则写成上面说的“文字版逻辑说明”并且创建一张“导入批次表”来承载每次导入的批次 ID、总数、成功数、失败数、导入人、导入时间、状态。这样每次导入都变成一个可追踪的任务而不是简单的“解析文件→写库”一气呵成。过程中我加入了一个“失败行明细表”每次校验一行失败就把错误原因、原始数据、行号存下来最终统一生成可下载的报错文件。结果整个功能我用了两天写完测试同事根据我列好的用例清单测了一轮竟然只提了一个样式类的优化建议没有功能性 Bug。上线后运营反馈也好因为大文件导入不会因为一行数据错误全部回滚他们也能下载错误明细快速修正。这个版本上线到现在半年多几乎没有返工。4.3 对比之后时间到底花在哪了有人可能觉得你第二版不是花了两天吗第一版只写了半天怎么还说第二版更高效账要这么算第一版半天开发 联调一天 修 Bug 两天 写数据修复脚本一天 四天半而且上线后还提心吊胆。第二版半天设计 两天开发 两天半全流程顺滑上线后没人找。设计时间只多了半天总工期却少了两天这就是“先想清楚”最直观的经济账。更关键的是第一版返工消耗的不是只有程序员的时间还有测试人员的时间、产品经理协调资源的时间、以及运营同事等待功能上线的不耐烦。这种隐性成本比写代码的时间贵得多。写代码这种事真的不是看你坐在电脑前时间长而是看你做的决策有没有给整个系统增加确定性。5. 把“先想清楚”变成肌肉记忆的五个抓手很多人看完上面这些感觉很有道理但到实际项目里又被业务方、领导、排期推着走了回到“先写再说”的老路。我自己也经历过几次反复现在靠几个很具体的小动作才慢慢把“想清楚”变成了一种习惯分享给你参考。5.1 接到需求先问“为什么”再问“怎么做”人脑有个惰性一旦开始想“怎么做”就会陷入方案细节很难再跳出来审视需求本身。所以我现在沟通需求时强制自己先问三个“为什么”。为什么要做这个功能为什么现在做为什么用这种方式做有时候问完发现业务方其实想要的是“让运营少做重复操作”但最初的需求却是“开发一个消息推送后台”。方向压根不对。如果顺着错误方向做了哪怕代码写得再漂亮返工也跑不掉。5.2 写代码前先写注释让未来的你先备案我个人的一个习惯是建好文件后先不写具体实现而是在关键函数上方写一段文字注释描述这段代码要做什么、输入是什么、输出是什么、调用方是谁、可能出错的点有哪些。这一步有点像“代码设计文档”的微型版。等你真想清楚了下面的实现就是机械翻译写起来会非常顺。如果你发现注释都写不出来或者前后逻辑矛盾那正好说明思考还不够先别忙写代码。有人说这样太浪费时间但我的亲身体验是先写注释的代码平均出错率比别人低一半根本不夸张。而且这个习惯对 AI 辅助编程时代尤为有用——你把意图描述清楚再让 AI 生成实现得到的代码质量也会高一个档次因为它能理解你的边界和目的。很多人吐槽 AI 写的代码不好用相当一部分原因是提问者自己都没想明白要写什么问题描述得模糊出的代码自然模糊。5.3 用最小闭环去验证最危险的假设而不是先铺开所有功能有时候“想清楚”不等于能一口气把所有细节都想出来尤其是新技术选型、新框架接入这类工作。这时候的正确做法是先挑一个最难、最不确定的点做最小验证Spike比如一个外部 SDK 的调用链能不能走通、一个中间件在高并发下会不会丢消息。用一两百行代码先把风险最高的环节跑通再回去完善整体设计。这个验证结果最好是落到一份“验证记录”里写清楚环境、版本、结果而不是留在脑子里。5.4 让 Code Review 尽早介入设计阶段很多人把 Code Review 当成“事后检查”代码写完提交了才拉人看。但真正有效的 Code Review 应该发生在动手之前。你可以拉上一位资深同事把你的数据字典、接口契约、逻辑步骤拿给他看一眼就问一句话“如果按这个方案做你觉得哪里会翻车”人脑在“设计评审”状态比“代码审查”状态能看到的问题层次深得多。很多致命设计缺陷越早暴露越省成本。5.5 复盘每一次返工把根因记下来而不是补丁每当你因为需求变更、逻辑漏洞、边界条件没想好而改代码时给自己留一条记录记录这个返工的根因。不是记“XX功能 XX月 XX日改了版本”而是记“我漏掉了 CSV 编码识别导致线上导入乱码”“我漏掉了筛选状态 URL 同步导致刷新后列表重置”。这些记录攒上几十条你就会发现自己踩坑的模式高度集中下次写代码前自然会下意识检查这些问题。我现在几乎每周都会翻一次自己的“返工清单”每次翻都觉得以前真是不开窍。这种复盘本质上就是在训练你的“前额叶”在动手前先预演一遍可能的失败路径。等你把这件事变成条件反射你就不再是那个永远在改 Bug 的程序员而是别人口中“想得比较周全”的靠谱同事。写代码这件事快不是目的稳才是。稳的前提不是打字快不是框架用得花哨而是你动手前已经把该想的都想清楚了。哪怕不能百分之百避免返工也足以让你少走一大半弯路。