⚡

模块化代码组织Skill modular-code

模块化代码组织是一种Python编程技能，专注于通过合理分割代码文件大小，提高代码的可维护性和AI辅助开发效率。关键词包括模块化、代码组织、Python、维护性、AI辅助开发、文件大小优化、架构设计、编程最佳实践。

架构设计 0 次安装 2 次浏览 更新于 3/14/2026

name: modular-code description: 模块化代码组织 user-invocable: false

模块化代码组织

编写模块化的Python代码，文件大小适合维护性和AI辅助开发。

文件大小指南

行数 状态 操作
150-500 最优 AI代码编辑器和人类理解的理想点
500-1000 大 寻找自然分割点
1000-2000 太大 重构为专注的模块
2000+ 关键 必须分割 - 导致工具问题和认知超载

何时分割

当任何以下情况适用时分割：

  • 文件超过500行
  • 同一文件中存在多个无关关注点
  • 滚动疲劳寻找函数
  • 文件的测试难以组织
  • AI工具截断或丢失上下文

如何分割

自然分割点

  1. 按领域概念: auth.py → auth/login.py, auth/tokens.py, auth/permissions.py
  2. 按抽象层: 分离接口和实现
  3. 按数据类型: 分组操作相关数据结构
  4. 按I/O边界: 隔离数据库、API、文件操作

包结构

feature/
├── __init__.py      # 保持最小，仅导出
├── core.py          # 主要逻辑（500行以下）
├── models.py        # 数据结构
├── handlers.py      # I/O和副作用
└── utils.py         # 纯辅助函数

要做

  • 使用有意义的模块名称（data_storage.py 而不是 utils2.py）
  • 保持 __init__.py 文件最小或为空
  • 将相关函数分组在一起
  • 隔离纯函数和副作用
  • 使用蛇形命名法（snake_case）命名模块

不要做

  • 仅凭行数任意分割文件
  • 创建单函数模块
  • 过度模块化到“包地狱”
  • 在模块名称中使用点或特殊字符
  • 使用“魔术”导入隐藏依赖

重构大文件

当分割现有大文件时：

  1. 识别簇: 找到相关函数组
  2. 增量提取: 一次移动一个簇
  3. 更新导入: 修复所有导入语句
  4. 运行测试: 验证每次移动后无损坏
  5. 文档化: 更新任何旧位置的引用

当前代码库候选

超过2000行需要关注的文件：

  • 数学计算模块（scipy, mpmath, numpy） - 领域特定，可能可接受
  • patterns.py - 考虑按模式类型分割
  • memory_backfill.py - 考虑按操作类型分割

来源