核心结论 :多数「项目越写越乱」不是架构(Architecture)错了,是归属 错了------同一个功能的文件被拆到
controllers/、services/、models/、utils/四个按类型分的目录里。改架构要动接口与依赖方向,回归面大;改目录只是搬文件,改错了 import 立刻报错,机器帮你兜底 。所以顺序应该是先搬目录、再谈架构:本文给三条判据判断你到底属于哪一种,一份可直接运行的目录体检脚本,以及一组 16 文件的对照实测------同一功能散在 3 个目录 变成 1 个目录 后,跨目录 import 从 12 条降到 4 条。
📦 配套资源:目录体检脚本 structure_audit.py(含 --demo 对照样本,一条命令复算本文数字)
目录
-
- 一句话结论
-
- 为什么「乱」通常不是架构问题
-
- 三条判据:搬文件还是动架构
-
- 乱在哪:四个能被数出来的指标
-
- 完整可运行脚本:一次体检四个指标
-
- 实测对照:同一份代码的两套目录
-
- 五步渐进重排:不搞大爆炸
-
- AI 时代,目录就是检索索引
-
- 对照表:症状 → 原因 → 解法
-
- 发布前验收清单
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 节的脚本输出:
- 功能分布目录数 :文件名含某个功能关键词(如
order)的文件,散落在几个不同目录。这是主指标,1 最好,3 以上说明该切块。 - 跨目录 import 条数:一个源码文件引用了自己目录之外的模块,就计一条。数字越大,说明「读一个功能要跨几次目录」。
- 最大目录深度 :最深的源码文件在第几层。深度本身不是问题 ------按功能切块的目录通常会更深一层(
features/order/service.py),但它更集中。深度要配合第 1 项看,单看会误判。 - 单目录文件数极值:某个目录里的文件数。超过 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 |
三个必须说清的读法:
- 文件一个没少,只是位置变了。 16 对 16、3 对 3------这不是「删代码省出来的整洁」,纯粹是归属调整。所以它几乎没有回归风险。
- 跨目录 import 降了 8 条,降幅 67%。 分层版每条服务都要引
models/和utils/,每个控制器都要引services/;切块版只剩 4 条共享工具引用(每个功能各引一次shared/money)。少掉的 8 条,就是 AI 每次读这个功能时要多跳的 8 次目录。 - 切块版反而更深一层。 这条要专门讲,因为它容易被误读成「切块更乱」。深度从 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):
- The Perfect Folder Structure for Scalable Frontend(分层依赖方向) -- Feature-Sliced Design ⭐值得阅读
- Package by Layer vs Package by Feature(内聚与耦合对照表) -- jshingler
- How to Structure a Monorepo for AI Coding Agents(目录就近的 AGENTS.md 生效) -- swarmz.net ⭐值得阅读
- Code Organization(六周渐进迁移的实践记录) -- renderpx.dev
- Building AI Native Repos(知识区与工作区分层) -- nicknow.net
而AI 时代什么样的程序员不会被淘汰里那个结论在这里同样成立:AI 把「写出代码」变便宜了,把「改得动」变贵了。目录重排恰好是改动成本最低、收益最直接的那一类改动------它不改变行为,只改变可发现性。
9. 对照表:症状 → 原因 → 解法(Troubleshooting)
| 症状 | 原因 | 解法 |
|---|---|---|
| 改一个功能要开四个文件夹 | 按类型分层,功能被拆散 | 建 features/<功能>/,整功能搬迁 |
| 新同事两周还找不到代码 | 目录名只有「层」,没有「业务」 | 目录名改成业务名词,层降为文件后缀 |
| AI 改完一处漏掉另外三处 | 同一功能的文件不在同一目录 | 先把功能收拢,再让 AI 动手 |
| 某个目录 30 多个文件,什么都有 | 分类维度失效,成了杂物间 | 按功能拆成子目录,一次拆一个 |
| 一重构就要改两周、没人敢 review | 大爆炸式迁移 | 改成 touch 即搬,一次一个功能 |
| 搬完发现构建脚本挂了 | 漏了 CI / Docker / IDE 的路径引用 | 搬完立刻跑全链路,别只跑单测 |
10. 发布前验收清单(Checklist)
- 能一句话说出核心功能由哪几个文件组成,且它们在同一目录
- 随机挑一个功能,改动它需要打开的目录数 ≤ 2
- 跑过体检脚本,记录了迁移前的「功能分布目录数」与「跨目录 import」
- 新功能已全部进新结构,旧结构停止增长
- 每次迁移单独提交,且没有与内容修改混在一起
- 搬完后 CI、Docker、IDE 运行配置的路径都验证过
先搬目录、再谈架构:只要问题出在「文件住哪」,就不值得动承重墙;只有当依赖成环、概念重复时,才轮到架构上场。
本专栏《AI 开发范式》聚焦 AI 时代的代码组织、改动成本与协作方式,每篇都配一段可直接运行的脚本或清单,每周更新一篇。想按顺序读完,可在专栏页订阅。