项目越写越乱?先别改架构:用一次目录重排 + 一份可复算的体检脚本把乱治住

核心结论 :多数「项目越写越乱」不是架构(Architecture)错了,是归属 错了------同一个功能的文件被拆到 controllers/、services/、models/、utils/ 四个按类型分的目录里。改架构要动接口与依赖方向,回归面大;改目录只是搬文件,改错了 import 立刻报错,机器帮你兜底 。所以顺序应该是先搬目录、再谈架构:本文给三条判据判断你到底属于哪一种,一份可直接运行的目录体检脚本,以及一组 16 文件的对照实测------同一功能散在 3 个目录 变成 1 个目录 后,跨目录 import 从 12 条降到 4 条。

📦 配套资源:目录体检脚本 structure_audit.py(含 --demo 对照样本,一条命令复算本文数字)

目录

    1. 一句话结论
    1. 为什么「乱」通常不是架构问题
    1. 三条判据:搬文件还是动架构
    1. 乱在哪:四个能被数出来的指标
    1. 完整可运行脚本:一次体检四个指标
    1. 实测对照:同一份代码的两套目录
    1. 五步渐进重排:不搞大爆炸
    1. AI 时代,目录就是检索索引
    1. 对照表:症状 → 原因 → 解法
    1. 发布前验收清单

1. 一句话结论(Conclusion)

项目乱的典型症状是「改一个功能,要在四个文件夹之间跳来跳去」。这时候最自然的反应是「架构不行了,重写吧」🎭------但九成情况下,你需要的只是把同一功能的文件搬到同一个文件夹里。

先分清两件事:

  • 架构(Architecture) 管的是模块边界与依赖方向:谁能调用谁,数据往哪流,哪些东西必须独立部署。
  • 目录(Directory Layout) 管的是文件放在哪 :order_service.py 放在 services/,还是放在 features/order/。

这两件事会互相影响,但不是同一件事。而且它们的失败方式完全不同:

动作 改错了会怎样 谁来发现
架构重写 接口语义悄悄变了,上线才炸 用户
目录重排 import 立刻找不到模块,测试立刻红 编译器与测试

先做那件失败可见的事,是工程上最划算的顺序。下文的三条判据,就是帮你确认自己到底站在哪一边。

2. 为什么「乱」通常不是架构问题(Mechanism)

按类型分层(Package by Layer)的目录,在小项目里非常舒服:controllers/ 放入口、services/ 放逻辑、models/ 放实体、utils/ 放工具。项目长到几十个功能之后,它的代价才开始显形------每加一个功能,都要往四个目录各塞一个文件。

于是「订单」这个功能,实际上由四个目录里的四个文件共同组成,但没有任何一个地方写着这件事。

打个比方 🧺:你的衣柜按「材质」分抽屉------棉的、羊毛的、化纤的。听着很有条理,可你早上要出门跑步时,得先开棉抽屉拿 T 恤、再开化纤抽屉拿速干裤、最后去玄关找袜子。分类维度选错了,抽屉越整齐,找东西越慢。按场合分(上班 / 运动 / 出差)就完全不同:拉开一个抽屉,一套齐了。

关键判断在这里:你并不需要一个新衣柜,你需要换一种分抽屉的方式。换抽屉不用拆墙,这就是「改目录」和「改架构」的区别。

反过来,什么情况才是真的架构坏了?当「订单」和「支付」共享一份可变的全局状态,或者两个模块互相 import 形成环------这时候搬文件救不了你,因为问题不在位置,在依赖方向。第 3 节给可判定的分界线。

3. 三条判据:搬文件还是动架构(Decision Rules)

不要凭感觉判断「乱」。用三个能当场回答的问题:

判据 ①:你能一句话说出「这个功能由哪几个文件组成」吗? 说不出来,或者答案里出现「大概还有 utils 里那个......」,说明是归属问题------文件散落,没有任何一个目录代表这个功能。这是目录问题,搬文件就能治。

判据 ②:改这一个功能,要打开几个同级目录? 打开 1--2 个属于正常;稳定在 3 个以上,说明功能被拆散了。这是最直观的一条,用手数就行。

判据 ③:跨目录 import 占全部 import 的比例高不高? 同一个功能内部的引用,本不该跨目录。这一条交给第 5 节的脚本数,别估。

反过来,出现下面任意一种,才是真的该动架构:

现象 性质 该做什么
同一个「订单」有两套字段不一致的模型 概念重复,边界没定 动架构:先统一模型与所有权
A 模块 import B,B 也 import A 依赖成环 动架构:抽中间层或反转依赖
两个功能共写一份可变全局状态 隐式耦合 动架构:显式化接口或事件
功能文件散在 3 个以上目录 归属不清 搬目录就够
同一目录塞了 20 多个不相关文件 分类维度失效 搬目录就够

一句话记法:问题在「谁依赖谁」,改架构;问题在「文件住哪」,搬目录。 前者是承重墙,后者是家具位置。

4. 乱在哪:四个能被数出来的指标(Metrics)

体检要数四个量,全部由第 5 节的脚本输出:

  1. 功能分布目录数 :文件名含某个功能关键词(如 order)的文件,散落在几个不同目录。这是主指标,1 最好,3 以上说明该切块。
  2. 跨目录 import 条数:一个源码文件引用了自己目录之外的模块,就计一条。数字越大,说明「读一个功能要跨几次目录」。
  3. 最大目录深度 :最深的源码文件在第几层。深度本身不是问题 ------按功能切块的目录通常会更深一层(features/order/service.py),但它更集中。深度要配合第 1 项看,单看会误判。
  4. 单目录文件数极值:某个目录里的文件数。超过 20 个且主题各异,说明这个目录已经失去分类能力,变成了杂物间。

这四项的共同点是不需要读代码 ,os.walk 一遍就能算。这也是它们的价值:讨论「要不要重构」时,最怕的是各说各的体感;换成四个数字,争论立刻收敛到「先改哪个」。

5. 完整可运行脚本:一次体检四个指标(Runnable Audit)

下面这段存成 audit.py,在项目根目录执行 python audit.py . order 即可。第二个参数是你要统计的功能关键词。

python 复制代码
"""目录体检:统计功能分散度、跨目录 import、最大深度与单目录文件数。"""
import os
import re
import sys
from collections import Counter

SKIP = {".git", "node_modules", "dist", "__pycache__", ".venv"}          # 体检时跳过的目录
IMPORT_RE = re.compile(r"^\s*(?:from|import)\s+([\w\.]+)")               # 抓 import 的模块路径


def collect(root):
    """遍历目录,返回(文件相对路径,所在目录)列表,并跳过依赖与缓存目录。"""
    out = []                                                            # 收集结果
    for cur, dirs, names in os.walk(root):                              # 逐层向下遍历
        dirs[:] = [d for d in dirs if d not in SKIP]                    # 原地过滤忽略目录
        for n in sorted(names):                                         # 固定顺序保证可复现
            if n.endswith((".py", ".js", ".ts", ".jsx", ".tsx")):       # 只看源码文件
                rel = os.path.relpath(os.path.join(cur, n), root).replace("\\", "/")
                out.append((rel, os.path.dirname(rel)))                 # 记录文件与所在目录
    return out


def main():
    """输出四项指标:功能分布目录数、跨目录 import、最大深度、单目录文件数。"""
    root = sys.argv[1] if len(sys.argv) > 1 else "."                    # 体检目录
    key = sys.argv[2] if len(sys.argv) > 2 else "order"                 # 功能关键词
    files = collect(root)                                               # 全量源码文件
    hit = [(r, d) for r, d in files if key in r.lower()]                # 命中功能关键词的文件
    spread = len({d for _, d in hit})                                   # 功能散落在几个目录

    dirs = {d for _, d in files}                                        # 全部目录集合
    cross = 0                                                           # 跨目录引用计数
    for rel, _ in files:                                                # 逐文件解析 import
        if not rel.endswith(".py"):                                     # 只解析 Python 便于复现
            continue
        for mod in IMPORT_RE.findall(open(os.path.join(root, rel), encoding="utf-8").read()):
            cand = mod.replace(".", "/")                                # 模块路径转目录形态
            if any(d and (cand + "/").startswith(d.split("/")[-1] + "/") for d in dirs):
                cross += 1                                              # 命中其它目录即计一条

    depth = max((d.count("/") + (1 if d else 0) for _, d in files), default=0)
    top = Counter(d for _, d in files).most_common(3)                    # 文件最多的三个目录

    print(f"功能 {key}: {len(hit)} 个文件,散在 {spread} 个目录")        # 主指标
    print(f"跨目录 import: {cross} 条")                                 # 耦合指标
    print(f"最大深度: {depth} 层 / 源码文件 {len(files)} 个")            # 结构指标
    for d, n in top:                                                    # 最拥挤目录
        print(f"  {d or '(根目录)'}: {n} 个文件")


if __name__ == "__main__":
    main()

脚本故意不做「智能建议」:它只负责把体感换成数字。判断该不该搬、先搬哪个,仍然要你来做------这部分机器替不了,也不该替。

6. 实测对照:同一份代码的两套目录(Measurement)

配套资源里的完整版脚本带 --demo 模式,会现场生成两套各 16 个文件 的对照样本:一套按类型分层(controllers/ + services/ + models/ + utils/),一套按功能切块(features/{order,user,pay,report}/ + shared/)。两套的功能数量、文件数量、依赖关系完全一样,只有目录组织方式不同。

执行 python structure_audit.py --demo 的实测输出:

指标 按类型分层 按功能切块 差值
源码文件数 16 16 0
目录数 4 5 +1
order 文件数 3 3 0
order 分布目录数 3 1 −2
跨目录 import 条数 12 4 −8
最大目录深度 1 2 +1

三个必须说清的读法:

  1. 文件一个没少,只是位置变了。 16 对 16、3 对 3------这不是「删代码省出来的整洁」,纯粹是归属调整。所以它几乎没有回归风险。
  2. 跨目录 import 降了 8 条,降幅 67%。 分层版每条服务都要引 models/ 和 utils/,每个控制器都要引 services/;切块版只剩 4 条共享工具引用(每个功能各引一次 shared/money)。少掉的 8 条,就是 AI 每次读这个功能时要多跳的 8 次目录。
  3. 切块版反而更深一层。 这条要专门讲,因为它容易被误读成「切块更乱」。深度从 1 层变 2 层,但功能分布从 3 个目录收到 1 个------深度是位置,分散是路数,路数少才是真的少走路。

口径声明:以上数字来自脚本现场生成的对照样本,不是某个真实商业仓库;你可以用 --demo 原样复算,也可以换成自己的目录跑同一个脚本。样本是合成的,但指标定义与代码逻辑是同一套。

7. 五步渐进重排:不搞大爆炸(Migration)

知道该搬,接下来最容易犯的错是「周末开个分支,把所有目录一次搬完」------那会得到一个三千行改动的 diff,没人敢 review,也没人知道哪里漏了。正确的做法是让新结构自己长出来:

第 1 步:只建目录,不搬文件。 先加一个 features/(或 modules/),写一份 README 说明规则:新功能一律进 features/<功能名>/。老代码不动,从今天起停止变得更乱。

第 2 步:touch 即搬。 定一条团队规则------你这次任务改到哪个文件,就顺手把该文件所在的那个功能整体搬到 features/ 下。搬的是整个功能,不是单个文件,否则你会得到「半个功能在新目录、半个在旧目录」的更糟状态。

第 3 步:一次只搬一个功能,用 git mv。 保留文件历史,方便出事时 git log --follow 追溯。不要在同一次提交里既搬位置又改内容------两个变更混在一起,review 时谁也看不出你到底动了什么。

第 4 步:搬完立刻跑。 这一步是目录重排最大的优势:漏改的 import 会当场报错,测试会当场红。把「搬完马上跑测试」做成硬规则,你就把一次高风险重构,换成了几十次零风险的小移动。

第 5 步:两周后再搬下一个。 观察一段时间,确认没有隐藏的路径依赖(构建脚本、CI 配置、Docker 挂载、IDE 运行配置最容易被漏掉),再动第二个功能。按这个节奏,一个几十功能的中型项目,两三个月会自然迁移完,而且任何一天停下来都不影响发布。

这套「touch 即搬、不搞大爆炸」的做法,在前端社区已有实践记录:新建 features/ 目录、只把新功能放进去、碰到旧文件时顺手迁移,六周内代码库自然完成迁移,全程没有一次性大重构。

8. AI 时代,目录就是检索索引(AI Context)

这一节是「特别是 AI 时代」的真正原因:AI 找文件,靠的是路径语义,不是你的注释。

人读代码时能靠模糊记忆------「那个算折扣的函数好像在哪见过」。AI 没有这段记忆,它拿到任务后做的第一件事是 glob 和 grep:按文件名、按目录名、按关键词定位候选文件。这意味着:

  • 目录名就是它唯一的分类标签。 你把 order_service.py 放在 services/,它要在「所有服务」里筛;放在 features/order/,它打开一个目录就拿到了订单功能的全部上下文。
  • 功能散在 3 个目录,AI 就要检索 3 次、读 3 段上下文。 第 6 节实测的 12 条跨目录 import,换成 AI 的视角就是 12 次跨目录跳转;每次跳转都要多带一段文件头、多耗一份 token。
  • 更隐蔽的代价是漏改。 人改代码会顺手全局搜索,AI 往往只改它读到的那几个文件。功能分散时,它极可能只改了 order_service.py,漏掉 models/order.py 里的对应逻辑------这不是模型笨,是你没把「这些文件属于同一件事」这个信息放进它的视野。
  • 目录边界还会变成规则边界。 现在主流的 AI 编码工具支持在子目录放局部的 AGENTS.md / CLAUDE.md,agent 读到离目标文件最近的那份并把它当作该目录的权威说明。你把目录切对了,规则就能跟着目录走;切错了,一份全局规则要管所有场景,只能越写越长。

这也是为什么每个文件夹都放一份 README 让 AI 先读那篇讲的是同一件事的另一半:那篇解决「AI 怎么知道这个目录是干什么的」,这篇解决「这个目录本身该不该存在」。先有合理的目录,README 才有东西可写。

而那套「touch 即搬、六周自然迁移完」的实践记录,出自下面的前端目录组织资料。

AI 时代目录组织参考资料(检索于 2026-11-16):

而AI 时代什么样的程序员不会被淘汰里那个结论在这里同样成立:AI 把「写出代码」变便宜了,把「改得动」变贵了。目录重排恰好是改动成本最低、收益最直接的那一类改动------它不改变行为,只改变可发现性。

9. 对照表:症状 → 原因 → 解法(Troubleshooting)

症状 原因 解法
改一个功能要开四个文件夹 按类型分层,功能被拆散 建 features/<功能>/,整功能搬迁
新同事两周还找不到代码 目录名只有「层」,没有「业务」 目录名改成业务名词,层降为文件后缀
AI 改完一处漏掉另外三处 同一功能的文件不在同一目录 先把功能收拢,再让 AI 动手
某个目录 30 多个文件,什么都有 分类维度失效,成了杂物间 按功能拆成子目录,一次拆一个
一重构就要改两周、没人敢 review 大爆炸式迁移 改成 touch 即搬,一次一个功能
搬完发现构建脚本挂了 漏了 CI / Docker / IDE 的路径引用 搬完立刻跑全链路,别只跑单测

10. 发布前验收清单(Checklist)

  • 能一句话说出核心功能由哪几个文件组成,且它们在同一目录
  • 随机挑一个功能,改动它需要打开的目录数 ≤ 2
  • 跑过体检脚本,记录了迁移前的「功能分布目录数」与「跨目录 import」
  • 新功能已全部进新结构,旧结构停止增长
  • 每次迁移单独提交,且没有与内容修改混在一起
  • 搬完后 CI、Docker、IDE 运行配置的路径都验证过

先搬目录、再谈架构:只要问题出在「文件住哪」,就不值得动承重墙;只有当依赖成环、概念重复时,才轮到架构上场。

本专栏《AI 开发范式》聚焦 AI 时代的代码组织、改动成本与协作方式,每篇都配一段可直接运行的脚本或清单,每周更新一篇。想按顺序读完,可在专栏页订阅。

相关推荐
Karl_fang16 分钟前
🥳 再也不用拿起手机抄验证码!我做了一个 Android → Mac 的「验证码接力」工具
前端·macos·ai编程
Dmz丶1 小时前
前端转 AI 100 天 Day 45:阶段复盘——从“会调 API”到“做出 AI 产品”
python
ZhengEnCi1 小时前
AI 规则越多越费 Token:无关规则让每次回答多耗 46% 的规则体检提示词
aigc·ai编程·claude
Sakura_j_h_1 小时前
MCP SDK 2.0 实战:用 MCPServer 搭本地笔记检索服务
开发语言·笔记·python·qt·ai工具·mcp·mcpserver
谭光志1 小时前
如何让 AI 高效工作
前端·后端·ai编程
ServBay2 小时前
连AI自己也不愿意维护自己的屎山代码
后端·ai编程·claude
QuZhengRong2 小时前
【AI】Agent 全栈进阶|AgentScope 沙箱源码解析
python·学习·ai·agent·沙箱
袋鼠云数栈UED团队2 小时前
Agent外循环实践:如何编排任务、验证结果并可靠交付
ai编程
Eider19982 小时前
Python基础语法之并发相关3
开发语言·python