企业官网建设流程全解析

上个月帮一位刚转行做数据处理的同事看代码，他写了一个两千行的脚本，所有逻辑都堆在一个文件里，函数十几处重复定义，变量名互相覆盖，跑一次没问题，改一个参数捅出一串Bug。我帮他花了一个下午把脚本拆成函数、模块和包，第二天他跟我说，原来改代码可以这么轻松。

这不是个例。很多人学Python，基础语法滚瓜烂熟，一到实际项目就发懵，代码全堆在一个文件里，定义一堆全局变量，哪个函数要用直接引用。前期“能跑”掩盖了问题，等项目变复杂，维护成本开始暴涨。这时候最该补的，不是某个高级框架，而是函数、模块与包这套代码组织的基本功。

这篇文章就是围绕这三个概念展开的。函数解决的是逻辑复用，模块解决的是文件组织，包解决的是项目分发。我会从底层原理出发，把参数传递、作用域、import机制、目录结构这些容易踩坑的地方讲透，最后带你把一个散乱的脚本工程改造成规范的项目结构。适合已经掌握Python基础语法、开始写中等规模脚本、想提升代码可维护性的开发者。

1. 为什么要把代码拆成函数、模块和包

1.1 从“能跑”到“能维护”的临界点

脚本编程有个特点：前几百行代码怎么写都能跑。函数重复就重复，反正最后执行的是最新定义的那份；变量冲突就冲突，最多是某个值被意外覆盖，调试一下就能发现。但这只是假象。

一旦代码超过某个量级，问题就开始集中爆发。最常见的场景是：你在文件A里写了一个处理数据的逻辑，文件B里也需要用，于是复制粘贴了一份。后来需求变了，你改了A，忘了B，程序跑出来的结果不一致，你花半天查为什么。再比如，全局变量满天飞，一个函数改了另一个函数正在使用的值，排查起来根本没有头绪。

这个临界点没有固定行数，取决于逻辑复杂度。我见过三百行就乱成一团的脚本，也见过一千行还勉强能维护的脚本。但有个共性规律：当出现“同一份逻辑需要改动多处”的时候，就是拆分的信号。

1.2 函数、模块、包的职责边界

很多初学者把这三个概念混为一谈，觉得都是“拆代码”。其实它们解决的是不同层面的问题。

• 函数：最小单位的逻辑复用。把一段重复使用的代码封装起来，通过参数控制行为，通过返回值传递结果。解决的是“一段逻辑”的复用问题。
• 模块：把相关的函数、类、常量组织在一个.py文件里，通过import引入。解决的是“一组逻辑”的组织问题，同时提供了独立的命名空间，避免变量互相污染。
• 包：一个带__init__.py的目录，里面可以放多个模块和子包。解决的是“一组模块”的分发和部署问题，让项目可以被安装、被引用、被团队协作。

打个比方：函数是一道菜的做法，模块是一个菜谱集，包是整本烹饪书的分册出版。你单做饭不需要书，做满汉全席就离不开体系了。

明确了这个边界，后面看代码就知道该往哪一层去拆。函数解决局部重复，模块解决文件职责，包解决项目结构，三者配合，代码才能既灵活又清晰。

2. 函数：参数、作用域与可复用性的底层逻辑

函数看着简单，def f(x): return x + 1谁都会写，但实际写项目时，函数相关的坑是最多的。核心问题集中在参数传递、默认值、作用域和高阶用法这几个地方。

2.1 参数传递的本质：对象引用，不是值也不是裸引用

Python官方文档的说法是，参数传递是“对象引用传递”，但这句解释经常被误解。关键在于分清可变对象和不可变对象。

看这段代码：

def add_one(x): x = x + 1 print("函数内部:", x) # 6 return x a = 5 add_one(a) print("函数外部:", a) # 5

很多人拿这个例子说Python是“传值”，因为a没变。但这不准确。准确的说法是：a和x开始都指向整数对象5，执行x = x + 1时，因为整数不可变，Python创建了新对象6让x指向它，a依然指向5。

再换一个可变对象的例子：

def append_item(lst): lst.append("new") return lst my_list = [] append_item(my_list) print(my_list) # ['new']

这里my_list变了，因为列表可变，lst.append是在原对象上修改，函数内外指向同一个列表对象。所以结论是：Python传递的是对象引用，能不能在函数内影响外部变量，取决于你是“重新绑定”还是在“修改对象本身”。

理解了这一点，很多面试题和实际Bug都能想明白：函数内做的操作如果只是重新赋值，外部不受影响；如果是调用可变对象的方法，外部会跟着变。

2.2 默认参数的经典陷阱：可变对象只在定义时创建一次

这是Python函数里最经典的坑，没有之一。

def add_item(item, cache=[]): cache.append(item) return cache print(add_item(1)) # [1] print(add_item(2)) # [1, 2] print(add_item(3)) # [1, 2, 3]

第二次、第三次调用时，cache并没有重新变成空列表，而是保留了上一次的结果。原因在于：默认参数是在函数定义时求值并保存的，不是每次调用时重新创建。cache始终指向同一个列表对象。

正确的写法是用None作为默认值，在函数体内部创建新列表：

def add_item(item, cache=None): if cache is None: cache = [] cache.append(item) return cache

这个坑出现在很多真实场景里，比如用默认参数保存配置、缓存数据、存放回调函数，都是一样的毛病。规则很简单：默认参数只用不可变对象，需要可变容器就在函数体内创建。

2.3 变量作用域：LEGB规则与global、nonlocal

Python在函数内查找变量时，按照LEGB顺序：Local（局部）→ Enclosing（外层函数）→ Global（全局）→ Built-in（内置）。很多人对这个规则最大的误解是：在函数内给全局变量赋值就能改全局。

counter = 0 def increment(): counter = counter + 1 # 报错：UnboundLocalError

这里会直接报错。原因是Python在编译函数时发现counter在函数体内被赋值，所以把它标记为局部变量，但counter + 1引用时局部还没有绑定，于是报错。这不是因为没找到全局变量，而是局部变量遮蔽了全局变量。

想在函数内修改全局变量，必须显式声明global：

counter = 0 def increment(): global counter counter = counter + 1

嵌套函数修改外层函数的变量，用nonlocal：

def outer(): count = 0 def inner(): nonlocal count count += 1 inner() return count

我实际调试项目的经验是：尽量别在函数里用global。全局可变状态会让程序的因果链变得极其难追踪，这个函数改一下，另一个函数莫名其妙受影响。更好的做法是把状态封装成类，或者通过参数显式传入、返回值显式传出。

2.4 *args与**kwargs：处理不确定数量的参数

当函数需要接收不定数量的参数时，*args和**kwargs就派上用场了。*args把多余的位置参数收集成元组，**kwargs把多余的关键字参数收集成字典。

def log(level, *messages, **meta): print("级别:", level) for msg in messages: print("内容:", msg) for key, value in meta.items(): print("元信息:", key, "=", value) log("INFO", "用户登录", "IP: 127.0.0.1", event_id=1024)

这里messages是("用户登录", "IP: 127.0.0.1")，meta是{"event_id": 1024}。这个写法在写装饰器、日志系统、框架扩展点时特别常用。反向操作也值得记住：调用函数时，用*列表或**字典解包参数。

params = {"host": "localhost", "port": 3306} connect(**params)

等价于connect(host="localhost", port=3306)。这个技巧在处理配置字典转函数参数时能省一大堆重复代码。

2.5 装饰器：函数也是对象的实战应用

Python里函数是一等公民，可以像普通变量一样传递、返回、赋给另一个名字。装饰器正是基于这个特性：装饰器是一个接收函数、返回新函数的函数。

一个最简单的计时装饰器：

import time def timer(func): def wrapper(*args, **kwargs): start = time.perf_counter() result = func(*args, **kwargs) elapsed = time.perf_counter() - start print(f"{func.__name__} 耗时: {elapsed:.4f}秒") return result return wrapper @timer def compute_sum(n): return sum(range(n)) compute_sum(1000000)

@timer等价于compute_sum = timer(compute_sum)，执行compute_sum时实际执行的是wrapper。wrapper内部用*args, **kwargs兜住了所有参数类型，这是装饰器的标准姿势。

实际项目中，装饰器常用来做权限校验、日志记录、重试机制、缓存等横切逻辑。它的好处是不需要改动原有函数代码，就能附加行为。但要留意：多层装饰器叠加时执行顺序是从下往上的，@a @b def f()会先执行b再执行a，调试时容易绕晕。

3. 模块：import的运作机制与常见陷阱

函数再牛，写在一个文件里也白搭。这时需要模块化。理解import到底做了什么，很多诡异的问题就能迎刃而解。

3.1 import做的事：查找、编译、执行、绑定

当你写下import utils，Python实际上做了四件事：

1. 查找：在sys.path列出的目录里找utils.py文件（或utils包）。
2. 编译：把.py源码编译成字节码，生成__pycache__里的.pyc文件。
3. 执行：从上到下执行utils.py的代码，创建模块对象。
4. 绑定：把utils这个名字绑定到当前作用域，指向该模块对象。

很多人忽略第3步：import模块等于执行模块代码。如果模块顶层写了一大堆耗时操作，import时就会卡住；如果模块顶层引用了尚未准备好的资源，import就可能报错。常见的做法是把“加载时的动作”尽量放进函数或if __name__ == "__main__":块里。

3.2 sys.path的查找顺序：为什么你的模块导入不了

sys.path是Python查找模块的目录列表，顺序大致是：

• 当前脚本所在目录（或者交互模式下的当前目录）
• PYTHONPATH环境变量指定的目录
• 标准库目录
• 第三方包安装目录（site-packages）

有一个高频问题：我在src目录下建了文件，跑main.py时导入src.helper却报ModuleNotFoundError。原因通常是当前工作目录不在sys.path里，或者项目结构不合理。

最简单的排查办法是打印实际路径：

import sys for path in sys.path: print(path)

如果期望的目录不在列表里，可以用sys.path.insert(0, "期望路径")临时处理，但这只是权宜之计。更规范的做法是把项目做成可安装的包（后面会细说），或者从项目根目录启动脚本，让根目录自动进入sys.path。

3.3 import的缓存机制：为什么改代码不生效

Python对模块做了缓存。同一个模块只执行一次，后续import直接复用缓存。这在Ipython或Notebook这类交互环境里特别明显：你改了.py文件，重新import，代码还是旧的。

这是因为Python把module对象存在了sys.modules字典里。手动清缓存或者用importlib.reload()可以强制重新执行：

import importlib import helper importlib.reload(helper)

但reload也有副作用：已经有变量引用旧模块对象时，reload不会同步更新那些引用，可能造成新旧版本混用。我的建议是：交互调试时用reload救急可以，正式代码里不要依赖它。写完代码重启进程，让一切回到干净状态。

3.4 循环导入：A引B，B又引A的经典死局

循环导入是模块化之后最常遇到的报错之一。错误信息通常是ImportError: cannot import name 'xxx' from 'yyy'，看起来不知所云，其实是两个模块互相import导致的。

看一个具体例子：

a_module.py

from b_module import b_func def a_func(): return "a"

b_module.py

from a_module import a_func def b_func(): return "b"

运行import a_module时，流程是这样的：加载a_module，执行到from b_module import b_func，开始加载b_module，b_module执行到from a_module import a_func，此时a_module还没执行完，a_func还没定义，于是报错。

解决思路有几种：

• 延迟导入：把import b_module放进函数内部，需要时才加载。
• 调整设计：把共用的代码下沉到第三个模块，两个模块都依赖它，而不是互相依赖。
• 仅导入模块名：import b_module，使用时写b_module.b_func()，避免在导入阶段就解析具体属性。

我个人的经验是，循环导入往往意味着模块划分不够干净。如果只是改导入方式绕过，可能会埋下更深的隐患。先想想有没有公共逻辑可以抽出来，这才是根治。

3.5 import的三种写法与命名空间污染

import有三种常见写法：

import math # 导入模块名，使用 math.sqrt from math import sqrt # 导入模块内的名字，直接用 sqrt from math import * # 把所有非下划线开头的名字导入当前作用域

第三种from math import *问题最大。它会盲目标记可见命名，很可能覆盖你已有的变量和函数。比如模块里有个max函数，你本来也用from math import *,结果把内置max给遮蔽了，程序行为直接改变。

推荐的做法是：import module为主，from module import specific_name为辅，控制在最小导入范围。大型项目里经常用__all__来控制from module import *的实际导出内容，但绝大多数情况下还是别用星号导入。

4. 包：目录结构与可安装项目的正确姿势

当模块数量变多，散落在一堆.py文件里同样会产生管理问题。包就是用来解决这个问题的：用一个带__init__.py的目录，把相关模块组织起来。

4.1init.py到底做了什么

在Python 3.3之前，__init__.py是目录成为包的“身份证”，没有这个文件，解释器就不认这个目录是一个包。Python 3.3之后引入了命名空间包，没有__init__.py的目录也有可能被当成包，但为了避免各种边界问题，建议还是显式创建__init__.py。

__init__.py在包被导入时执行，它的作用包括：

• 标记目录是包
• 初始化包级变量
• 控制from package import *时导出哪些名字
• 提前导入子模块，方便使用方写短路径

举个例子，一个utils/包：

# utils/__init__.py from .parsing import parse_csv from .formatting import format_table

这样使用者导入包后直接utils.parse_csv就能用，不需要关心内部文件名。这属于包的“对外接口收敛”，把复杂内部结构封装成友好接口。

4.2 绝对导入与相对导入：点的位置很关键

在包内部，模块之间互相引用有两种方式。绝对导入从包名开始写：

from myproject.utils.parsing import parse_csv

相对导入用点表示当前或上级包：

from .parsing import parse_csv # 当前包内的 parsing 模块 from ..config import settings # 上级包里的 config 模块

相对导入的优势是：包整体移动位置时，内部导入不需要改动。缺点是：相对导入只能用在包内模块里，不能直接运行模块。比如你运行python utils/parsing.py作为主脚本，from .parsing就会报错，因为没有包上下文。

实际上，很多项目采用“所有内部引用都用绝对导入”的约定，以包名为根。这样脚本可以直接运行模块，也便于IDE跳转。代价是包一旦重命名，所有导入都要改。两条路没有绝对优劣，关键是同一个项目里保持一致。我自己更倾向绝对导入，因为运行方式灵活，团队协作时认知负担低。

4.3all：定义对外边界

一个包或模块可以定义__all__列表，声明哪些名字是公开的：

# utils/__init__.py __all__ = ["parse_csv", "format_table", "validate_data"] from .parsing import parse_csv from .formatting import format_table from .validation import validate_data

__all__有两个实际作用：一是from utils import *只导入列表里声明的名字；二是给开发者一个明确的信号“这个包对外提供哪些接口”，内部其他模块属于私有实现。写公共库时这个列表尤为重要，少写一个名字，使用者就导不出来。

4.4 把包做成可安装的项目：pyproject.toml

包再往前一步，就是变成“可安装的项目”。这让你的代码不再依赖脚本路径，而是可以像第三方库一样被任意脚本import。

Python 3.9以后，官方推荐的构建方式是pyproject.toml。下面是一个最小可用配置：

[build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "my-data-tool" version = "0.1.0" description = "数据处理工具集" requires-python = ">=3.9" [project.scripts] my-tool = "my_data_tool.cli:main"

配合项目结构：

my-data-tool/ ├── pyproject.toml └── src/ └── my_data_tool/ ├── __init__.py ├── cli.py └── core.py

安装时在项目根目录运行pip install -e .，开发模式安装，改代码即时生效，不用反复重装。这里有一个设计细节：源码放在src/目录下而不是根目录，被称为src布局。它能确保你测试的代码确实是安装后的包，而不是当前路径下意外加载的本地文件，踩过坑的人都知道这个布局多值钱。

5. 实操：把脚本堆改造成标准项目结构

理论说了一大堆，现在用一个贴近现实的例子走一遍完整流程。假设你有一个数据清洗脚本，从一个目录里读取多个CSV文件，做过滤、去重、汇总，输出统计表。最初它正是一个一千来行的单文件脚本。

5.1 最初的散乱状态长什么样

改造前的脚本analysis.py大概结构如下：

import csv import os import sys THRESHOLD = 3 OUTPUT_COLUMNS = ["region", "count"] def read_all_csv(data_dir): rows = [] for fname in os.listdir(data_dir): if not fname.endswith(".csv"): continue path = os.path.join(data_dir, fname) with open(path, newline="") as f: reader = csv.DictReader(f) for row in reader: rows.append(row) return rows def filter_rows(rows): filtered = [] for row in rows: if int(row["times"]) >= THRESHOLD: filtered.append(row) return filtered def deduplicate_rows(rows): seen = set() result = [] for row in rows: key = (row["phone"], row["date"]) if key not in seen: seen.add(key) result.append(row) return result def summarize(rows): stats = {} for row in rows: region = row["region"] stats[region] = stats.get(region, 0) + 1 return stats def export_report(stats, output_path): with open(output_path, "w", newline="") as f: writer = csv.writer(f) writer.writerow(OUTPUT_COLUMNS) for region, count in sorted(stats.items()): writer.writerow([region, count]) def main(): data_dir = sys.argv[1] if len(sys.argv) > 1 else "data" output_path = sys.argv[2] if len(sys.argv) > 2 else "report.csv" rows = read_all_csv(data_dir) rows = filter_rows(rows) rows = deduplicate_rows(rows) stats = summarize(rows) export_report(stats, output_path) print(f"完成，共 {sum(stats.values())} 条记录") if __name__ == "__main__": main()

看着还行吧？但这个脚本一旦要加功能，问题立刻冒出来：过滤规则要配置化，日志要加，多个任务要复用读取逻辑，测试要写……全部堆在一个文件里就是一场灾难。

5.2 改造步骤：按职责切片

改造第一步不是动代码，而是画一张“职责地图”。上面的代码里明显有几类职责：文件读取（io）、过滤规则（filter）、去重逻辑（dedupe）、汇总统计（summary）、报告导出（report）。这些彼此相对独立，拆起来最顺。

第二步是决定模块划分。我规划了下面这个结构：

data_analysis_project/ ├── requirements.txt ├── README.md ├── src/ │ └── data_analysis/ │ ├── __init__.py │ ├── config.py │ ├── io_utils.py │ ├── processing.py │ ├── reporting.py │ └── cli.py └── tests/ └── test_processing.py

config.py放阈值、输出列名等配置；io_utils.py放文件读取相关；processing.py放过滤、去重、汇总函数；reporting.py放导出函数；cli.py作为命令行入口；tests/放单元测试。

第三步才是动手写代码。以processing.py为例：

def filter_rows(rows, threshold): return [row for row in rows if int(row["times"]) >= threshold] def deduplicate_rows(rows, keys): seen = set() result = [] for row in rows: key = tuple(row[k] for k in keys) if key not in seen: seen.add(key) result.append(row) return result def summarize(rows, group_key): stats = {} for row in rows: value = row[group_key] stats[value] = stats.get(value, 0) + 1 return stats

注意一个关键变化：原来的函数直接读取全局变量THRESHOLD和写死的列名，现在改成通过参数传入。这是一个函数通用性的核心设计——不让函数依赖外部可变状态，只依赖参数和返回值。这样写的好处是，你也可以在测试里随意指定阈值和字段，不需要为每个阈值写一个新函数。

5.3 为什么把入口单独放到cli.py

原来的脚本用if __name__ == "__main__"作为入口，现在拆包后，这部分移到了cli.py：

import argparse from .config import load_config from .io_utils import read_all_csv from .processing import filter_rows, deduplicate_rows, summarize from .reporting import export_report def main(): parser = argparse.ArgumentParser() parser.add_argument("--data-dir", default="data") parser.add_argument("--output", default="report.csv") parser.add_argument("--threshold", type=int, default=3) args = parser.parse_args() rows = read_all_csv(args.data_dir) rows = filter_rows(rows, args.threshold) rows = deduplicate_rows(rows, ["phone", "date"]) stats = summarize(rows, "region") export_report(stats, args.output) if __name__ == "__main__": main()

入口和业务逻辑分离的意义在于：业务函数是纯Python逻辑，可以被问答系统、定时任务、Web服务等任意调用方复用，而命令行入口只是众多调用方之一。很多人把入口逻辑和业务逻辑混在一起，导致想调用函数还得带着整个脚本的参数解析逻辑，切割干净后就没有这个负担了。

5.4 进阶：用声明式配置代替散落的常量

再往前一步，我会把阈值、去重字段、分组字段这些“业务参数”搬进yaml或toml配置，而不是放在代码里硬编码。config.py这样写：

import tomllib def load_config(path): with open(path, "rb") as f: return tomllib.load(f)

参数化能让一个脚本在不同场景下复用，只改配置不碰代码。这个思路在数据管道、批处理任务里尤其重要。不过也不要一上来就上配置，前期两三处常量直接用函数参数传就行，等确实有变化需求再引入配置文件，避免过度设计。

6. 实测定会遇到的几个坑和我的应对习惯

拆包改造过程中，有几个坑几乎每个人都会撞上，这里提前说清楚。

6.1 同名包与标准库/第三方库冲突

有一次我把自己的包命名为email_utils，里面有个模块叫email。结果运行时报错，Python在执行某些操作时把标准库的email包给遮蔽了。加上PYTHONPATH里有自己的目录，import email整个乱了。

经验是：包和模块的命名一定要有项目前缀。比如你的项目叫data_analysis，那根包就叫data_analysis，子模块用data_analysis.io_utils这种形式。避免使用email、test、time、utils这类通用名，它们极容易和标准库或已安装的第三方库撞名。

6.2 命令空间包带来的“隐形陷阱”

前面提到Python 3.3之后允许没有__init__.py的目录作为包，这个特性在拆分大型项目时容易被触发。比如你有一个目录叫analysis/，里面有个processing.py，你没有写__init__.py，它也能被导入。表面看省事儿了，但当你给analysis添加__init__.py想升级成正规包时，可能因为相对导入、命名冲突等问题冒出一堆新错误。

我的建议比较保守：包目录一律显式添加__init__.py，哪怕文件内容是空的。虽然多一个文件，但行为确定性大大提升，团队协作时也不会出现“这个目录到底是不是包”的争论。

6.3 开发模式下改了代码不重启

用pip install -e .装了开发模式后，改包内代码不需要重新安装。但如果你用的是交互式环境或者已经运行的脚本，模块缓存还是旧的。这个前面讲过，关键在于每次测试前确认进程是新起的。我习惯在写测试时用小脚本直接python -m pytest跑，保证每次都是全新进程，避免缓存问题干扰判断。

6.4 测试里导入包的正确姿势

拆成src布局后，写测试时导入包偶尔会失败，因为当前工作目录不在sys.path里。用pip install -e .可以解决大部分情况。如果不想安装，也可以这样运行测试：

python -m pytest

只要是模块方式运行，Python会把当前目录放进sys.path。注意是python -m pytest，不是直接敲pytest。前者能正确处理src布局下的导入路径。

6.5 什么时候不要拆：别为小脚本背大结构

最后说一个反方向的经验：不是所有程序都要拆成包结构。一个单文件两百行的脚本，拆成七八个模块纯属自找麻烦。函数该拆就拆，这是第一级救赎；模块该拆就拆，这是第二级；包结构只有当项目需要被多文件、多模块、多人协作或者需要安装分发时才真正必要。

我实际判断的标准很简单：如果你改一个字段需要同时打开三个文件，那拆得过头了；如果你改一个功能需要在一个文件里滚动五百行，那拆得不够。模块化的目标是让每个文件能独立讲清一件事，而不是把代码切得越碎越好。

7. 从构想到产出：这套组织方式能带来的实际变化

拆包这件事带来的最直接变化是可测试性。单文件脚本的输出结果很难验证，你可能要靠肉眼盯着一百行打印日志找问题。拆成纯函数之后，每个环节都对应一个函数，输入输出都明确，测试代码几分钟就能写出来。

def test_filter_rows_threshold(): rows = [ {"times": "5", "region": "a"}, {"times": "2", "region": "b"}, ] result = filter_rows(rows, threshold=3) assert len(result) == 1 assert result[0]["region"] == "a"

这段测试代码的价值不在于它测了两个数据，而在于它把“过滤逻辑正确”这件事固化下来。以后你改了过滤规则，跑一遍测试就知道有没有破坏已有行为。没有模块化，测试根本无从下手。

其次是协作体验。多人开发一个项目时，如果所有代码堆在一个文件里，Git冲突就是频繁爆发战。拆成模块后，每个人负责自己的模块，交集降到最低，合并代码的心理负担大幅减少。

然后是复用能力。我之前做过一个数据清洗模块，第一次是给某个报表系统用，后来另一个同事要做实时管道，直接import同一个包里的处理函数，省了一半开发时间。这种复用在单文件脚本时代是无法想象的。

我自己动手拆包的经验是，一次性完成“函数→模块→包”的全过程，比渐进式改造更顺畅。因为中间状态往往会出现模块之间导入关系还乱着、测试还没跟上、命令行入口位置不统一等一堆模糊地带，反而更难调试。干脆集中一个下午改完，再处理遗留细节。

8. 最后放几个我常用的检查清单

改造完一个项目，我会过一遍下面这些问题，如果答案都是肯定的，基本可以认为模块化到位了。

• 每个模块的职责能不能用一句话说清楚？说不清楚的模块通常是职责混杂，需要继续拆分或合并。
• 有没有哪个函数依赖了模块级或全局的可变状态？如果有，它在并行调用、测试时迟早出事。
• 所有模块之间的依赖方向是否清晰？A依赖B，B依赖C，单向依赖最理想；出现循环依赖就要停下来重想划分。
• 命令行入口是否独立于业务逻辑？入口文件可以薄，但要让核心函数可以被任何调用方使用。
• 测试文件能不能在没有网络、没有真实数据的情况下跑通？如果测试依赖真实环境，迟早有人因为环境问题跳过测试。
• 新同事接手时，能不能从README和目录结构里快速知道从哪个文件开始看？项目结构的自解释能力很重要。

模块化的本质不是堆积文件和目录，而是为代码建立清晰的边界。边界清晰了，你才能在这些边界之上安全地演进：加功能、改逻辑、替换实现，都不会引发连锁爆炸。

回想开头的同事，他现在写新脚本时已经形成了肌肉记忆：先把功能在纸上拆成几个函数，再决定哪些函数放哪个模块，最后把入口单独留出来。他用了一个月之后跟我说，现在写代码最大的变化是敢动手了，因为每一块都可以单独验证。这就是函数、模块与包这套基本功最实在的回报。