企业官网建设流程全解析

1. 为什么你需要一条“代码卫生”流水线

先说个真实场景。上个月我接手了一个维护了三年的老项目，第一个需求改起来差点把我劝退：一个UserController类，3000多行，里面有一堆getUserInfo、getUserInfo2、getUserInfoNew，还有注释掉的旧逻辑、复制粘贴过来又改了半天的工具方法、一个看起来没用但谁也不敢删的StringUtil……改一个字段，全局搜索能找到十几个相关点，每个都得点开看一遍才能确定改哪个。这种项目没人敢动手，不是因为需求难，而是“代码卫生”太差——你永远不知道面前这堆代码，哪些是活资产，哪些是历史遗留的定时炸弹。

后来我给自己定了一条规矩：每次动代码之前，先做一轮“清扫”。这个习惯慢慢固化成了六步，也就是今天想分享的Hygiene-sweep——一条代码卫生六步清扫skill。它不是什么高深的理论，更像是一份“进场前先戴手套、动手前先盘点现场”的作业流程，把散乱的代码清理思维整理成了一套可以照着执行的操作清单。

这条skill解决的是三个问题：一是帮你快速摸清项目底细，别一上来就埋头改代码；二是用低成本的手段把“坏味道”集中清掉，避免小问题滚成大坑；三是把清理动作和日常开发节奏结合，让卫生检查不再是“大扫除日”才做的特殊活动。适合的人群很宽——不管是刚接手新项目的人、带团队做代码评审的TL，还是整天和遗留系统打交道的维护者，这套流程都能直接拿过去用。

我把它封装成skill，本质上是把“怎么做代码卫生”这件事从隐性经验变成了显性流程——不靠个人感觉，不靠某个前辈的灵光一现，每一条都是可重复、可检查、可执行的动作。下面从头拆解这套六步清扫法的设计思路和实操细节。

2. 六步清扫的完整拆解：从“看到什么”到“怎么处理”

2.1 第一步：盘点现状，先把项目的“器官”摸清楚

清扫的第一步不是动手删代码，而是做一次现状盘点。就像家政打扫之前先要在房子里转一圈，看看哪些地方积灰、哪些地方堆了杂物、有没有漏水隐患一样，代码卫生的第一步是搞清楚：这个项目的核心模块有哪些？每个模块的代码量多少？改动频繁的是哪几块？哪些文件是“陈年古迹”，哪些是最近还在活跃迭代的？

我在实际操作中习惯用一个三维度盘点法。第一维度是“活跃度”：看代码文件的最近修改时间，结合Git log统计最近三个月内被改动过的文件列表，那些长期没动过的文件大概率是稳定逻辑，优先级偏低；第二维度是“复杂度”：用代码分析工具跑一遍圈复杂度（Cyclomatic Complexity），高于10的函数一眼就能圈出来，这些是后续重读和修改的重点风险区；第三维度是“耦合度”：看看哪些类被大量其他模块引用——Util、Common、Helper这类“公共类”如果被几十个地方引用，动它的成本极高，必须放在清单里重点标注。

这个步骤的目标产出物是一份“清扫清单”。不一定非要写成正式文档，我在个人项目里通常只是维护一个TODO-CLEAN.md文件，随手记录三件事：文件路径、发现的问题类型（命名混乱/重复代码/死代码/结构不合理）、预估风险等级。别小看这一份清单，它让你从“感觉代码很乱”变成了“我知道乱在哪、为什么乱、优先级是什么”，这就是可执行清扫的第一步。

值得强调的是，这个盘点阶段的工具并不求全，能用grep、find加Git命令解决的事，不需要上重型平台。我的习惯是先用git log --name-only拿到文件活跃度，再用一个简单的圈复杂度计算脚本（很多IDE自带或者可以装插件）快速标记高风险区，半个小时就能完成一个小型项目的初步体检。

2.2 第二步：消灭“命名坏味道”，让代码会说话

清扫的第二件事是收拾命名。代码里的命名就像是房间里的标签——一个叫“数据1”的文件夹和一个叫“2024年Q3财务对账单”的文件夹，找东西的体验天差地别。代码卫生最直接的“脏乱差”就是命名问题，而这个问题恰恰是新手最常忽视的。

我在清理时会把命名问题分成几类，每一类对应不同的处理方式。

第一类是“语义模糊”：data、info、temp、result这样的通用命名，出现在哪里都行，但放在哪里都说不清楚含义。处理方式是结合上下文重命名为具体语义的标识符，比如data在用户登录场景下拆成loginRequest或authPayload。第二类是“信息冗余”：getUserInfo和getUserInfo2的问题是后缀数字本身就在告诉别人“代码失控了”。重命名不只是简单改掉数字，而是要区分两个方法各自的真实职责——getUserBasicInfo和getUserProfile之类，让名字直接表达差异。第三类是“误导性命名”：这类最危险，比如一个方法叫isExpired却返回了“是否未过期”的逻辑。

命名清理看起来是小动作，实际上牵一发动全身——因为改一个公开方法名，所有调用点都要跟着改。所以这里我给一个实用建议：命名清理优先做“局部变量和私有方法”，因为影响范围可控；而对外公开的API、公共类的公有方法，除非有配套的自动化测试兜底，否则不建议在清扫阶段大动干戈。这属于“卫生”和“重构”的边界问题——清扫解决的是“脏”，重构解决的是“乱”，两者可以同时启动，但节奏不能混。

2.3 第三步：做减法，删掉“看起来没用但不敢删”的死代码

代码卫生和居家大扫除最像的一点就是断舍离。项目里躺着大量“看起来没用但不敢删”的代码——注释掉的逻辑、从未被调用的工具方法、遗留的兼容分支、死掉的功能开关。留着它们的心理逻辑通常是“说不定以后用得上”，但这个“以后”往往永远不会来，反而让后来人每次读到那里都要停下来思考：“这段代码还有用吗？”

我的删除策略分三个层级。第一层是“可以安全删”：被注释掉的整段代码，Git历史里有完整记录，真想找回完全可以从版本库恢复，留在现场反而是噪音；没有被任何地方引用的私有方法，静态分析工具能直接查出来。第二层是“确认后删”：有些代码看起来没人调用，但可能是通过反射、Spring注入这类动态机制使用的，删之前要全局搜索一下字符串引用，确认是动态调用就先标注，别急着动手。第三层是“标注不动”：明确知道是历史包袱但暂时没有精力收尾的代码，用@Deprecated（Java）或者@deprecated标签标注，让IDE和静态分析工具自动高亮，提醒所有后续维护者绕道走。

删代码有个经典的心智负担：觉得删掉就等于“损失”。我自己走过这个阶段后想明白一件事——代码库里只有两种代码，一种是被执行的，负责产生价值；另一种是不被执行的，负责制造困惑。你删掉的不被执行的代码，没有损失任何可运行的价值，反而消除了大量的理解成本。只要确信这些逻辑都被版本控制保底，删除就是最安全的改动。

这一步操作上强烈建议配合IDE的“Find Usages”功能逐个确认，而不是凭感觉笃定“这个肯定没用了”。我开始也吃过亏，凭直觉删了一个“没人调用”的工具方法，结果在另一个模块里通过反射动态加载了它，上线直接炸了。从那以后，凡是被删除的目标，哪怕确认了99%，我都会全局搜一遍完整字符串，这多花一分钟，能省掉通宵排查的十个小时。

2.4 第四步：理结构，把“堆满杂物的房间”重新分区

处理好表面灰尘之后，要处理的是更深层的结构问题。我把这步称作“重新分区”——项目文件就像房间的收纳体系，刚住进去的时候也许还算整齐，但三年下来，什么东西随手放在哪就变成什么样了：工具方法堆在一个巨型类里、业务逻辑和底层数据访问混在一起、一个函数承担了“校验参数+查询数据+组装返回+记录日志”四重工作。

分区清理的第一优先级是“处理巨型函数”。一个超过50行、条件分支超过5个的函数，阅读成本呈指数级上升。处理方式是按职责拆成两个或更多小函数，拆分的核心是找到“可以独立命名”的代码块——凡是能用一个动词短语概括的连续代码段，就有资格拆出来。比如“校验用户输入”是一个职责，“组装查询条件”是一个职责，“格式化返回结果”是一个职责，混在一起就是灾难。

第二优先级是“处理明显的‘卧底’依赖”。什么叫卧底？就是一个本该只管展示的页面层，里面直接new了数据库查询对象；一个本该处理计算逻辑的工具类，里面混进了文件IO操作。这类问题的本质是分层不清晰，修起来往往需要牵动很多依赖方，所以清扫阶段我的建议不是全面推翻重建，而是“止血”：先把错位的调用标记出来，在注释里说明“此处绕过Service层直接访问DAO，待重构”，至少让后来人知道这是已知问题，而不是无意写出的坏代码。

第三优先级是“重复代码的合并”。两段逻辑一样的代码复制在项目里两个地方，是最让人头疼的维护陷阱——你改了一处，另一处没改，行为就开始分叉。清扫时如果发现纯复制粘贴的重复代码，抽取为公共方法；如果发现的是“改了几个变量还是同一个骨架”的相似代码，考虑用参数化或模板方法统一。

2.5 第五步：建护栏，让卫生问题不再“回潮”

清扫不能只靠一次性的大扫除，还得建立日常“防尘机制”。第五步的核心是引入自动化检查工具，把能交给机器判断的卫生规则全部交给机器。

我的脚手架配置一般包括这么几层。第一层是lint工具：Python系用flake8或ruff，JavaScript系用ESLint，Java系用checkstyle——它们负责在提交代码时就拦住明显的命名不规范、未使用变量、导入顺序混乱等基础问题。第二层是格式化工具：prettier、black、gofmt这些工具的意义不在于某个人审美多强，而在于统一——统一的格式让团队代码看起来像一个人写的，大大降低阅读摩擦。第三层是静态复杂度检查：比如eslint的complexity规则，或者Python的mccabe插件，把圈复杂度阈值设为10，超过就报错，逼迫大家在函数变大之前就拆。

这层机制最容易被误解成“限制开发自由”。实际上，把卫生规则交给机器之后，人的精力反而被解放了——你不需要在Code Review时浪费时间争论“这里是不是该换个名字”“这里空行是不是多了”，这些琐碎争议全部自动化解决，评审时间就剩下来专注讨论逻辑正确性和设计合理性。

我在项目里还有一个习惯：把lint和格式化挂到Git的pre-commit钩子上，利用husky（前端）、pre-commit（Python）这类工具在代码提交前自动执行检查和修格式。一开始队友可能会抱怨“怎么提交这么慢”，但跑一个lint加格式化通常只需几秒，换来的是代码库永远保持一个统一的起点。

2.6 第六步：固化成惯例，让卫生融入开发节奏

最后一步不是技术操作，而是流程习惯。代码卫生六步清扫最大的陷阱是“清扫一次，半年后再想起来”。所以第六步是把清扫动作固化到日常开发的节奏里，让卫生成为惯性而不是例外。

我的做法是设置“三个触发点”。第一个触发点：新任务开始前，花30分钟浏览相关代码区域，把顺手能清理的命名、死代码、小结构问题在开发过程中随手处理掉，而不是等要改的代码堆成山再一起扛。第二个触发点：功能合入主干前，快速过一遍自己本次改动的Diff，检查是否带入了不规范的命名、未经使用的变量、复制粘贴遗留的代码——这是在提交前最后一道自我检视的关卡。第三个触发点：每个迭代结束后，安排一次专门的“卫生日”或“卫生时间盒”，按照六步流程系统性地清扫一次，并结合团队成员在开发中积累的“小问题清单”。

这个习惯真正起效的关键是“降低单次清扫规模”。很多人洗完一次代码库，因为动作太大、时间太长，产生了强烈的疲惫感，从此再也不愿意做这件事。但如果你把清扫拆成每周一次的小动作，每次只处理清单里的几项，效果累加起来远比那一次性大扫除要好。我自己深有体会：每次改动代码时顺手清理20分钟，比集中花一天做“清理大会”的效率高得多，而且不会因为打断正常开发节奏而招来抵触。

3. 用一个真实案例把六步走一遍

理论说多了容易空，拿一个我最近实际清扫过的模块来演示一遍完整的流程。

接手的是一个订单导出功能模块，文件不大，但脏乱特性齐全。核心的OrderExporter类有400多行，一个exportOrders方法就占了两百多行，里面有文件输出逻辑、Excel模板填充逻辑、数据查询逻辑、字段映射逻辑，全串在一个函数里。方法命名也是老味道：getList、getOrderData、processData、processData2，不点进去看实现根本不知道它们各自到底处理什么。代码中间还夹着一大段被注释掉的旧版逻辑——就是那种“现在不用了但又舍不得删”的典型遗留。

第一步盘点花的时间不多，因为模块边界还算清楚。我用Git log确认了这个模块最近三个月只有两个提交，属于改动频率较低但一旦改就牵动下游导出的核心模块，复杂度上也确认了exportOrders是头号风险目标，于是把整个文件的清扫优先级定成最高。

第二步入手清理命名。getList更名为queryPendingOrders，processData2拆成了formatCellValue和convertFieldToColumn两个职责明确的小函数。这一步我严格控制了范围——只改了私有方法，对外公开的exportOrders签名保持不变，避免影响到已知的两个调用方。

第三步做删除。那一大段注释掉的旧逻辑直接删除，从Git历史里能找回原样。同时发现一个只被exportOrders使用过一次的generateTempFile方法，确认完没有其他调用点后也一并移除。

第四步处理结构。这是这次清扫里工作量最大的一步。我把两百多行的exportOrders按职责拆成了四个函数：validateExportParams负责入口校验、fetchOrderData负责数据查询、buildExcelBuffer负责用模板构建输出文件、writeToTargetPath负责落盘。拆完之后整个方法的阅读体验完全变了——从“一个两百行的大杂烩”到“一屏就能扫完的控制流程”。

第五步配置护栏。因为这是一个Java项目，我在相关目录的构建配置里加上了checkstyle的检查规则集，阈值设为圈复杂度不超过10，以后再有新代码试图往一个函数里堆逻辑，提交阶段就会被警告。同时把这个模块的命名规范和格式规范纳入CI检查范围。

第六步固化习惯。我在团队的知识库里更新了这个模块的“清扫记录”，说明哪些类被拆过、哪些方法被重命名过、后续新需求优先加在哪个函数上。这份记录只有两百来字，但极大降低了后来者重新摸索成本。整个过程断断续续做了大概四个小时，其中纯编码时间两小时左右，剩下的时间是确认行为边界和执行测试回归。

清理完跑了一遍原有测试用例，再加了一个抽查：手动执行一次订单导出，比对生成的文件和改动前的样板文件内容一致。确认没有问题之后，整个改动合入主干。这个例子想说明的是：六步清扫不需要你专门请假一天来做大工程，把它当作嵌入式的小任务，跟着需求改动一起推进，才是可持续的节奏。

4. 把六步流程封装成skill的实操思路

标题里的“skill”不是随便加的，我确实把六步清扫流程按照skill的模式固化了。现在不少AI辅助编程工具和agent框架都支持自定义skill，核心逻辑就是把一段经验流程写成一个结构化的描述文件，让AI在接手具体任务时能按这个流程走，而不是每次都即兴发挥。把Hygiene-sweep封装成skill，等于把上面这套六步方法变成了一个可以反复调用的“能力包”。

一个skill文件通常包含三部分：name和description用于让AI识别什么时候该调用这个能力；instructions是整个skill的核心，描述具体执行步骤和规则；可选的examples则用来给出参考场景。

我这里给一个精简但可用的skill描述示例。名字起作Hygiene-sweep，说明写清楚“当需要审查或清理一个代码库、模块、文件时触发，用于识别命名问题、死代码、重复逻辑和结构混乱，并按六步流程输出清理建议”。instructions部分，我会把六步写成明确的指令序列，并对每一步补充操作细节：比如“第1步盘点：使用代码搜索和仓库历史检查列出文件的活跃度、复杂度与依赖范围”“第2步命名：优先处理私有成员，公共API需有测试覆盖方可改名”等等。为了让AI输出可落地，我还会要求它以表格或多级列表的形式给出“清理清单”，每个条目包含“文件路径—发现的问题——建议动作—风险级别”（上文提到的TODO-CLEAN.md结构）。

如果你也在用agent类的开发环境，封装skill有一个容易被忽略的好处：AI每次帮你处理代码时，会按照你和它约定的流程走，而不是凭模型内部的“平均经验”。这意味着你自己踩坑换来的教训——比如“删除前全局搜索动态引用”“公共方法重命名必须看测试覆盖”这类反直觉细节——可以沉淀下来，变成AI协作时的硬约束。我自己就是一个很典型的例子：第一次让AI辅助清理代码时，它大刀阔斧地建议我删掉了一堆“从未引用”的方法，结果好几个是Spring通过配置注入的。把这条教训写进skill的规则后，这个坑再也没踩过。

5. 实操中的常见问题与排查技巧

代码卫生这个事，听起来简单，真正动手时会遇到各种实际情况。我把踩过的坑和排查思路整理成一个速查表，按出现频率排序，供大家参考。

还有一个非常实用的排查思路：在无法确认一处代码是否还有用的情况下，启用“观察法”。给它打上日志或者记一个临时计数，观察一个真实业务周期内是否被访问。如果一整个迭代周期内完全无访问记录，再回头删除，说服力和安全性都高得多。这招在处理“旧系统里的遗留接口”时尤其管用，比我之前“拍脑袋直接删”的方式稳妥太多。

最后聊一聊工具选择。现在静态分析领域可选工具非常多，但我不建议一上来就配一整排检查器。我个人的经验是：先上一个格式化工具，再上一个lint工具，跑两周让团队适应、把误报规则调一调，然后再考虑圈复杂度检查和依赖分析。工具链是辅助清扫的，不是用来制造对抗情绪的。项目里如果因为规则过严，导致大家都在想办法绕过规则或者屏蔽检查，那说明配置策略出了问题，要做的不是“坚持规则”，而是回到“卫生的目的”去重新设计规则。

我个人在实际操作中的体会是：代码卫生不是一次性的审美洁癖，而是每次动手开发前给自己铺路的习惯。花四十分钟做一次小额清扫，也许不会立刻提升什么性能指标，但它能让下一次在这个模块上开发的人——不管是别人还是三个月后的自己——开始工作的时候少一些困惑，多一些掌控感。这种回报看不见摸不着，但是实打实的。

六步清扫里的每一条都算不上新知识，命名、删死代码、拆函数、lint检查……任何一本编程书里都翻得到。真正的价值是把它们串成一个完整流程，并且每次动手都老老实实地走完。如果你也有一块“谁都不想碰”的老模块，不妨从这个周末开始，找出一个下午，按这六步扫一遍试试。等代码变得干净了，你会发现，原来不想碰的模块，后来变成了你愿意经常修修补补的地方。