1. 类的书写规范从能跑到像样1.1 为什么新手写的类一眼假老手写的类能直接进项目我在看代码评审的时候经常看到一些刚学完Python基础的朋友提交的类第一眼就能猜出写了多久——不是技术深不深的问题是规范感差了一截。什么叫规范不是说非得死背PEP8那几百条而是说类写出来以后别人能顺着你的结构快速读懂你能在一个月后自己打开还能立刻想起来当初的逻辑。Python类有个很奇怪的特点怎么写都能跑。你全写在一个文件里、函数名乱起、变量满天飞程序照样不报错。但也正因为这样很多人写类就放飞了自我等代码上到几千行才发现改一个需求要翻半天。先说最基本的命名规范这是网上教程都会说但你最容易忽略的一条类名用驼峰命名法CapWords比如ConfigManager、UserProfile方法名和属性名用小写加下划线比如get_user_name、_cache_data。招标的时候还不明显一旦你的类一个文件写到了五六百行光靠名字就能看出所属和用途这个价值巨大。然后说一下类内部的结构顺序。很多新手想到哪写到哪一会儿写方法一会儿写属性最后没有规律。规范化类建议按这个顺序组织类的文档字符串docstring放在class声明正下方用三引号包起来说明这个类是干什么的。类属性所有实例共享的字段比如MAX_RETRY 3这样的常量放在最前面。__init__构造方法紧随类属性之后做初始化。特殊方法__str__、__repr__、__eq__等有就放在__init__后面。普通方法按业务逻辑组织尽量把同一类行为的方法放一块。property装饰器方法放在普通方法之后。staticmethod和classmethod放最后因为它们和实例状态无关。这个顺序不是强制的但非常符合人的阅读习惯先知道类是什么、有什么全局状态再看构造逻辑然后看行为。你有一次按这个顺序重排了几个老类就会发现维护成本明显下降。1.2 属性私有化的分寸感不要一上来就下划线焦虑Python没有真正意义上的私有属性和方法所谓的私有只是约定一个下划线开头的_name表示这是内部使用的外部不要直接碰两个下划线开头的__name会触发名称改写name mangling变成_ClassName__name用于防止子类意外覆盖。新手最容易栽的坑就是看到Java或者C的私有特性后在Python里把所有属性全部套上__结果代码里到处都是self.__data、self.__config外部想访问还要写obj._ClassName__data又丑又难维护。我的建议非常简单默认所有属性和方法都公有或单下划线除非你真的需要防止子类继承覆盖才用双下划线。双下划线不是用来自嗨的是为了解决多继承冲突和子类意外重名问题。你可以在实际调用时先试试单下划线够用就停在这个级别不够再加深。另外一个细节容易被忽略定义带默认参数的方法时绝对不要用可变对象做默认值。# 错误示范所有实例共享同一个列表 class Order: def __init__(self, items[]): self.items items # 正确示范默认参数用None方法内创建新列表 class Order: def __init__(self, itemsNone): self.items items if items is not None else []这个坑我见过不下十次。默认参数在函数定义时就被求值一次之后所有实例都会拿到同一个列表对象。一次在新实例里往self.items加数据之前几个实例的列表同步变了排查起来极其痛苦。所以默认值只穿不可变类型或者用None做占位再在方法内部处理。1.3 写出有灵魂的类封装、行为、状态的三角平衡很多新手把类当成装函数的壳子一个类里塞了一堆互不相关的函数美其名曰工具类。实际写下来工具类不是不能用但更应该考虑的是这个类到底封装了怎样的状态和行为。我判断一个类设计得好不好就看三个问题这个类对外暴露了什么行为它内部维护了什么状态外部改变状态只能通过哪些路径好的类内部状态尽量不裸奔。比如你有一个ConfigManager不要直接让外部config.data[host] xxx应该提供config.set_host()或config.update()方法。哪怕只是个薄薄的一层也给后续改存储方式从普通字典换成数据库留了后路。类的行为要有内聚性一个方法只干一件事。如果一个方法名字里面出现并且说明它该拆了——parse_and_save_and_send这种一旦出问题你连问题出在前半段中段还是后段都不知道。拆分以后每个方法可以单独测、单独调试、单独复用这才是类设计真正值钱的地方。2. 单例模式不要见什么类都套但要会用2.1 单例模式的本质与适用场景它解决的不是性能问题单例模式可能是设计模式里被讨论最多、也最容易被误解的一个。很多教程一上来就放UML图、放类图一套Java写法看着高深但很少有人说清楚你为什么需要它。单例模式的本质是保证一个类在整个程序生命周期内只有一个实例并且提供一个全局访问点。也就是说不管你在代码的哪个位置不管调用了多少次构造方法拿到的都是同一个对象。为什么需要这个最典型的应用就是配置管理器和日志记录器。一个程序的配置应该全局只有一份如果你在模块A改了配置模块B读到的是另一份那整个程序的状态就分裂了。日志记录器同理你希望所有模块往同一个logger里写最后才能汇聚成一个完整的日志流。另外一个真实场景是数据库连接池。一个应用通常会维护一个共享的连接池对象所有数据访问都从里面获取连接。如果每个请求都创建新的连接池很快就能把数据库的连接数打满。我记得有次线上排查问题发现几百个空闲连接把开发库卡死最后一个一个查代码找到根源就是某处初始化代码里直接在每次请求时新建了连接池对象。单例模式不是用来解决创建对象太慢这种性能问题的——它解决的是状态一致性和资源统一管理的问题。这个定位先想清楚才不会到处滥用。2.2 Python实现单例模式的四种写法从简单到进阶网上搜Python单例模式能搜到一堆写法有的靠谱有的花哨。这里我按从简单到进阶的逻辑梳理四种我在实际项目里真实用过的写法。第一种模块级单例最Pythonic的方案# config.py class _ConfigManager: def __init__(self): self.host 127.0.0.1 self.port 8080 config_manager _ConfigManager()使用方只需要from config import config_manager天然全局唯一。因为Python模块在第一次导入时执行一次后面导入都直接复用sys.modules里的缓存这个机制本身就是单例的。这种写法最推荐简单到不需要任何技巧。第二种重写__new__方法class Singleton: _instance None def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance__new__在__init__之前被调用负责创建实例。这样无论外部调用多少次Singleton()拿到的都是同一个对象。这个写法适用于你无法控制使用方、但必须保证单例的场景。第三种装饰器写法def singleton(cls): instances {} def get_instance(*args, **kwargs): if cls not in instances: instances[cls] cls(*args, **kwargs) return instances[cls] return get_instance singleton class ConfigManager: pass装饰器把单例的逻辑和类的业务逻辑解耦了你的类本身还保持看起来没有单例约束的状态代码可读性不错。第四种元类写法class SingletonMeta(type): _instances {} def __call__(cls, *args, **kwargs): if cls not in cls._instances: cls._instances[cls] super().__call__(*args, **kwargs) return cls._instances[cls] class ConfigManager(metaclassSingletonMeta): pass元类拦截了类的调用过程是相对底层的实现适合你在一个框架里统一控制多个类的单例行为。对于日常业务代码元类往往过度了解即可不建议为了炫技强行用。2.3 单例模式在Python里的几个大坑尤其是__init__重复执行上面第二种写法有一个容易被忽略的问题__new__确实只会在第一次创建实例时执行但__init__每次调用Singleton()时都会再执行一遍。s1 Singleton() s2 Singleton() print(s1 is s2) # True # 但如果__init__里有初始化逻辑它会被执行两次这意味着如果你的__init__里有重置状态、累加计数、读取文件等逻辑单例的状态可能会被第二次实例化意外重置。解决办法很简单在__init__里加一道实例级别判断已经初始化过就直接返回。class Singleton: _instance None _initialized False def __new__(cls, *args, **kwargs): if cls._instance is None: cls._instance super().__new__(cls) return cls._instance def __init__(self): if self._initialized: return self.value 0 self._initialized True还有一个多线程的问题。_instance的判断和赋值不是原子操作如果两个线程同时首次访问Singleton()理论上可能出现两个实例。不过实际上由于全局解释器锁GIL的存在Python的赋值操作在CPython里不会真正并发执行所以你遇到这个问题的概率极低。真的需要极致严谨可以在类上加一把线程锁兜底但日常项目完全没必要。最后说一句我的体会单例模式在Python里很多时候直接用模块级变量就够了不需要额外造轮子。能用修饰符就不用元类能用模块结构就不用单例类这是我在生产环境总结出来的优先级。3. 包与模块让你的代码能被别人优雅地复用3.1 模块、包、__init__.py到底各是什么三者什么关系说到包和模块很多教程喜欢从定义开始讲但我觉得不如从一个生活化类比开始。一个模块就是一个工具抽屉——一个.py文件里面存放一组相关的函数、类、变量。一个包就是一个工具箱——一个目录里面放了多个模块还有一个__init__.py文件做标记。你的项目早期可能只有两三个.py文件全局写一盘散沙也没关系。但当你开始思考我要把这套工具分享给别的项目用、我要把配置、工具函数、数据库操作拆分细一点的时候就必须理解包的结构了。一个典型的包长这样mypackage/ ├── __init__.py ├── config.py ├── utils.py └── core/ ├── __init__.py ├── engine.py └── parser.py__init__.py不一定需要写很多内容哪怕是一个空文件也能让Python把目录当成包来导入。它有几个常见用途定义__all__、在包被导入时执行初始化代码、暴露便捷的导入入口。这里要注意一个细节Python 3.3以后引入了命名空间包没有__init__.py的目录在特定情况下也能被导入。但实际项目里我强烈建议保留__init__.py因为它让你能精确控制包的初始化行为和对外接口。空文件也比没有文件好。__init__.py里写__all__是一个好习惯——它声明了from mypackage import *时导入的名字。更重要的是它能提示读者这个包对外承诺暴露了哪些接口把实现细节封印在包内部。还有一个提一下__name__ __main__这个判断几乎是所有可复用模块的标配。加了它这个.py文件既能被导入使用又能被直接运行做测试或演示。不加的话一个模块被导入时也会执行所有顶层代码很容易引发意想不到的副作用。3.2 制作一个本地方包并安装从setup.py到pyproject.toml有了包结构接下来就是让它能被安装进环境像requests、numpy那样直接import使用。这一步通常被新手忽略但恰恰是能跑跨到工程化的分水岭。传统方式是用setup.py加setuptoolsfrom setuptools import setup, find_packages setup( namemypackage, version0.1.0, packagesfind_packages(), install_requires[ requests2.20, ], )然后在项目根目录执行pip install -e .-e表示可编辑安装你改了源码环境里引用的就是最新代码不需要反复重新安装。调试阶段特别方便我基本百分之百用它。现在更推荐的方式是pyproject.toml这是PEP 517/518定义的现代构建规范。一个最小可用的pyproject.toml长这样[build-system] requires [setuptools61.0] build-backend setuptools.build_meta [project] name mypackage version 0.1.0 dependencies [requests2.20]写好后同样执行pip install -e .。如果你的包还要往里放数据文件、写资源文件需要额外配置tool.setuptools.package-data等字段这个可以根据项目实际需要再查文档不过上面这个最小结构已经能覆盖日常需求了。顺便说下导入搜索路径机制当你import mypackage时Python会按顺序在以下位置查找sys.path里的第一条路径往往是脚本所在目录环境变量PYTHONPATH标准库路径site-packages里已安装的第三方包如果你在一个目录里放脚本跑到另一个目录里用终端执行常常出现明明依赖装了但导入失败的情况多半就是这个查找顺序的问题。最快速的办法是直接打印sys.path看看到底找到了哪些路径一清二楚。3.3 相对导入与绝对导入什么时候用.什么时候用全路径包内模块互相导入时你会面对一个选择from . import engine还是from mypackage.core import engine绝对导入的好处是路径清晰、不依赖当前模块位置重构时不容易出错。相对导入的好处是写起来短尤其适合包内模块之间紧密协作的场景。实际项目中我的习惯是包内部模块互用用相对导入跨包、跨项目引用用绝对导入。这里有个深坑必须提醒你如果你的包内模块用了相对导入然后直接python mypackage/core/engine.py去运行它Python会立刻抛一个ImportError: attempted relative import with no known parent package。原因很简单——直接运行脚本时Python把这个文件当作顶层模块__package__是空值相对导入无从谈起。正确做法是运行整个包而不是单独跑某一个模块python -m mypackage.core.engine-m参数告诉Python以模块方式运行它内部会自动处理包路径。记住这一条能省掉一大截排查时间。3.4 循环导入你以为只有C才有的问题Python也躲不掉当模块A import模块B而模块B又需要import模块A时就会产生循环导入。Python的导入机制是边执行边注册的模块在导入过程中会先把自己挂到sys.modules里再执行模块体内的代码。如果此时它需要导入一个还没执行完的模块就会拿到一个不完整的模块对象——那些还没定义进去的函数或类自然就不存在。我遇到过的真实场景是serializer.py导入了models.py里的用户模型而models.py又需要从serializer.py导入一个序列化工具类。两个模块互相牵制最后运行时报ImportError: cannot import name UserSerializer from ...。解决循环导入的办法有几个按优先级排列调整依赖方向把公共依赖抽到第三个模块里两个原模块都只依赖它互不依赖。这是最根本的解法。延迟导入把其中一个导入语句挪到函数内部等到函数真正执行时再去导入。比如在models.py的某个方法里from .serializer import UserSerializer。用importlib动态导入进阶方案实际场景中用到得很少。我记得网上有一个比较直观的比喻循环导入就像是两个人互相站在对方肩膀上谁也看不见对方更别提站上去了。所以设计模块结构时尽量让依赖方向呈树状不要成环。4. 常见问题与排查技巧实录我踩过之后整理出来的一手笔记4.1 类与模块的五个高频坑每个都是真实翻车现场这几个问题和排查手段是我在带新人、帮朋友看代码时反复遇到的整理出来供你直接对比排查。问题现象根本原因排查与解决ModuleNotFoundError: No module named xxx包没安装或不在sys.path里先用pip show xxx确认再打印sys.path查路径ImportError: cannot import name yyy from xxx目标名字未被定义或循环导入中途引用去掉导入语句单独运行模块看完整报错堆栈attempted relative import with no known parent package直接把包内模块当脚本运行改用python -m运行或把入口文件移到包外类里默认参数是可变对象所有实例数据打架def __init__(self, items[])的经典坑默认值改成None在方法内部再建新列表同一个类有两份代码改A处B处不变复制粘贴模块时复制到两个目录导入了旧版本检查sys.modules里的路径清理__pycache__最后一条尤其折磨人。有次我在项目里改了一个类的行为改完运行毫无变化查来查去发现系统里有两个同名模块一个在项目目录、一个在site-packages里由于sys.path里项目目录排在前面导入的一直是旧的那个。这种问题无法靠代码内检查发现只能靠路径管理去梳理。4.2 单例模式的调试技巧如何快速确认你的对象是不是同一个想知道你的单例写对了没有最快的方法就是打印对象的id和内存地址。Python的id()返回对象在内存中的唯一标识同一个实例的id必然相同。s1 Singleton() s2 Singleton() print(id(s1), id(s2), s1 is s2)如果输出id不同说明你的单例代码在某个环节漏了。还有一种隐蔽情况你在多个模块里各写了一份单例逻辑但导入路径不同比如一个走相对导入一个走绝对导入导致实际加载了两个类定义。判断方法是打印type(s1).__module__和type(s1).__qualname__看两个对象的类是否同一来源。排查单例问题还有一条思路检查是不是有人直接copy.deepcopy(singleton)或者用pickle反序列化出了新实例。副本和反序列化对象默认不会走__new__逻辑会绕过单例约束。如果你的单例被复制使用了这是一个隐蔽且容易忽视的突破口。4.3 让代码想跑就跑入口文件的摆放哲学很多刚起步的朋友喜欢把业务逻辑全写在一个脚本里然后再拆。拆包之后入口文件放哪里、怎么启动成为new手最容易卡壳的地方。我的经验是建立一个清晰的目录结构入口脚本永远放在包外面。project/ ├── main.py └── mypackage/ ├── __init__.py ├── config.py └── core/ ├── __init__.py └── engine.pymain.py里写from mypackage.core import engine然后python main.py直接启动。这样mypackage永远是作为一个整体包被导入不存在相对导入时的no known parent package问题。如果你把启动脚本塞在包里后面一定会遇到入口脚本调不到模块的尴尬。再说一个小工具dir()函数在排查导入结果时非常有用。当你怀疑某个模块没导入对时直接打印dir(module)看里面有哪些名字。比如hasattr(module, some_func)一秒钟就能验证到位。4.4 调试技巧别急着改代码先搞清导入链路有一次我在一个项目里改了一个模块的依赖结果导致好几个功能崩溃。当时第一反应是猜哪处代码写错了改来改去浪费了一下午。后来我学乖了遇到导入类问题先做三件事。第一看完整堆栈不要只看最后一行。Python的ImportError报错会告诉你完整的导入链路往往源头在几层之前的模块导入语句里。第二用python -v运行脚本它会逐条打印所有模块的加载过程你能看到哪个模块从哪个路径被加载哪些是重复加载哪些加载失败。这个参数平时用得少但排查导入问题是真的好用。第三手动测试模块导入在终端进入交互模式一行一行import看到哪一行卡住问题就在哪。交互试错比一次次重启脚本要快得多。有一次我就是这么发现一个隐藏的循环导入的模块A在顶层导入BB在顶层导入CC又反向导入A。执行到一半C拿到的A是个空壳立刻抛错。如果用python -v把顺序过一遍一眼就能看出环在哪里。5. 把这些知识串起来一个能直接抄的包结构示例说了这么多我直接给出一份可以照着搭的小示例把类规范、单例、包结构串在一起。假设你在做一个简单的日志配置管理工具。demo_project/ ├── main.py └── mylogger/ ├── __init__.py ├── config.py ├── logger.py └── utils.pyconfig.py里放单例配置用最简单的模块级单例写法class _Config: def __init__(self): self.log_level INFO self.log_dir ./logs def set_level(self, level: str): self.log_level level config _Config()logger.py里是一个标准的类用了规范的结构和属性私有化from .config import config class Logger: 统一日志操作入口 MAX_BACKUP 5 def __init__(self, name: str app): self._name name self._messages [] def log(self, message: str): self._messages.append(message) print(f[{self._name}] {message}) def dump(self): return self._messages__init__.py里做包对外接口的收敛from .config import config from .logger import Logger __all__ [config, Logger]main.py里这样用from mylogger import config, Logger logger Logger(demo) logger.log(start)整个链路清爽直观单例的配置在包任何位置拿到都是同一份类结构规范统一包对外只暴露了__all__声明的两个名字内部模块不会泄露到外面。按这个结构写出来的代码不用额外解释队友一两分钟就能看明白模块职责。这才是包和类规范真正该有的样子。我个人在实际操作中的体会是写类、写包一定要把命名习惯和目录习惯当回事它们带来的维护收益在短期项目里不明显但三个月后再回来看你会感谢当时自己的克制。单例模式能少写就不写真要写优先选模块级方案包管理上多用-m运行、多用pip install -e调试、多画一画依赖关系图远远比记一堆API实在。最后分享一个日常习惯每次新建项目我先把__init__.py、入口main.py、pyproject.toml这三件套搭好再开始写代码。无论项目最终多大多小这个骨架永远不会浪费反而会让后面每一步都顺很多。
