Python工程與模塊命名規范：構建可維護的大型項目架構

project-root/
├── src/                    # 源代碼目錄
│   └── package_name/       # 主包
│       ├── __init__.py
│       ├── core/           # 核心模塊
│       │   ├── __init__.py
│       │   ├── models.py
│       │   └── utils.py
│       ├── api/            # API模塊
│       │   ├── __init__.py
│       │   ├── routes.py
│       │   └── schemas.py
│       └── services/       # 服務層
│           ├── __init__.py
│           ├── user_service.py
│           └── payment_service.py
├── tests/                  # 測試目錄
│   ├── __init__.py
│   ├── conftest.py
│   ├── unit/
│   │   ├── test_models.py
│   │   └── test_services.py
│   └── integration/
│       ├── test_api.py
│       └── test_database.py
├── docs/                   # 文檔
├── scripts/                # 腳本文件
├── data/                   # 數據文件
├── requirements.txt        # 依賴文件
├── pyproject.toml          # 項目配置
└── README.md               # 項目說明

2.2 工程命名規范

2.2.1 項目根目錄命名

# 好的項目名
financial-analysis-tool  # 使用連字符
data_processing_pipeline  # 使用下劃線
imageClassifier  # 駝峰式（較少用）# 避免的項目名
myproject  # 太泛
project123  # 無意義數字
test-project  # 可能沖突

2.2.2 包和模塊命名

# 包名（目錄）
models/          # 復數形式
utils/           # 工具函數
services/        # 服務層
adapters/        # 適配器# 模塊名（文件）
user_model.py    # 明確單一職責
database_connection.py
config_loader.py

三、詳細命名約定與模式

3.1 變量命名規范

3.1.1 基礎變量命名

# 基本數據類型
count = 10                  # 整數
price = 29.99               # 浮點數
name = "Alice"              # 字符串
is_active = True            # 布爾值
items = []                  # 列表
user_map = {}               # 字典# 集合類型
user_list = []              # 列表
user_dict = {}              # 字典  
user_set = set()            # 集合
user_tuple = ()             # 元組

3.1.2 復合變量命名

# 使用有意義的復合名稱
max_retry_count = 3         # 最大重試次數
default_timeout_seconds = 30  # 默認超時秒數
is_user_authenticated = True  # 用戶是否認證# 避免的命名
temp = get_data()           # 無意義
var1 = calculate()          # 編號命名
flag = check_status()       # 過于泛化

3.2 函數與方法命名

3.2.1 動作-對象命名模式

# 好的函數名
def calculate_total_price(items): ...
def validate_user_input(input_data): ...
def send_email_notification(recipient, message): ...
def create_user_profile(user_data): ...# 動詞選擇指南
# 獲取數據: get_, fetch_, retrieve_, load_
# 修改數據: update_, modify_, set_, change_
# 創建數據: create_, add_, insert_, make_
# 刪除數據: delete_, remove_, drop_, erase_
# 檢查狀態: is_, has_, can_, should_, check_

3.2.2 布爾函數命名

# 返回布爾值的函數
def is_valid_email(email): ...
def has_permission(user, resource): ...
def should_retry_request(response): ...
def can_user_access(user, feature): ...# 使用正面的布爾命名
def is_available(): ...     # 而不是 is_not_available
def has_content(): ...      # 而不是 lacks_content

3.3 類命名規范

3.3.1 類與對象命名

# 類名使用駝峰式
class UserAccount: def __init__(self, username):self.username = username  # 實例變量使用下劃線self._private_data = {}   # 私有變量前加下劃線class DatabaseConnection:def connect(self):passclass HTTPRequestHandler:def handle_request(self):pass# 避免的類名
class myClass: ...          # 應使用駝峰
class User_Account: ...     # 不應使用下劃線

3.3.2 特殊方法命名

class Vector:def __init__(self, x, y):self.x = xself.y = y# 運算符重載def __add__(self, other):return Vector(self.x + other.x, self.y + other.y)# 字符串表示def __str__(self):return f"Vector({self.x}, {self.y})"# 容器協議def __len__(self):return 2# 上下文管理器def __enter__(self):return selfdef __exit__(self, exc_type, exc_val, exc_tb):pass

3.4 常量與配置命名

# 常量使用全大寫+下劃線
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30
API_BASE_URL = "https://api.example.com"
SUPPORTED_FILE_FORMATS = ['.json', '.csv', '.xml']# 配置類常量
class Config:DATABASE_URL = "postgresql://user:pass@localhost/db"LOG_LEVEL = "INFO"CACHE_TIMEOUT = 3600

四、模塊化設計與命名策略

4.1 模塊職責劃分

graph TBA[項目架構] --> B[核心模塊]A --> C[業務模塊]A --> D[工具模塊]A --> E[接口模塊]B --> B1[models.py]B --> B2[exceptions.py]B --> B3[constants.py]C --> C1[user_service.py]C --> C2[order_service.py]C --> C3[payment_service.py]D --> D1[database.py]D --> D2[logger.py]D --> D3[validators.py]E --> E1[api/E1 --> E11[routes.py]E1 --> E12[schemas.py]E1 --> E13[controllers.py]

4.2 模塊命名模式

4.2.1 按功能劃分模塊

# 數據模型模塊
# models.py
class User:passclass Product:passclass Order:pass# 服務模塊
# user_service.py
class UserService:def create_user(self, user_data): ...def get_user(self, user_id): ...# 工具模塊
# validation_utils.py
def validate_email(email): ...
def validate_phone(phone): ...

4.2.2 按層級劃分模塊

# 數據訪問層
# repositories/
# user_repository.py
class UserRepository:def save(self, user): ...def find_by_id(self, user_id): ...# 業務邏輯層  
# services/
# user_service.py
class UserService:def __init__(self, user_repo):self.user_repo = user_repodef register_user(self, user_data): ...# 表示層
# web/
# controllers.py
class UserController:def post_user(self, request): ...

五、高級命名模式與技巧

5.1 設計模式相關命名

# 工廠模式
class ConnectionFactory:def create_connection(self, config): ...# 單例模式
class DatabaseManager:_instance = Nonedef __new__(cls):if cls._instance is None:cls._instance = super().__new__(cls)return cls._instance# 觀察者模式
class EventPublisher:def __init__(self):self._subscribers = []def subscribe(self, subscriber): ...def notify_subscribers(self, event): ...class EventSubscriber:def on_event(self, event): ...# 策略模式
class CompressionStrategy:def compress(self, data): ...class ZipCompression(CompressionStrategy):def compress(self, data): ...class GzipCompression(CompressionStrategy):def compress(self, data): ...

5.2 領域驅動設計(DDD)命名

# 實體
class Customer:def __init__(self, customer_id, name):self.customer_id = customer_id  # 唯一標識self.name = name# 值對象
class Money:def __init__(self, amount, currency):self.amount = amountself.currency = currency# 聚合根
class Order:def __init__(self, order_id, order_items):self.order_id = order_idself.order_items = order_itemsdef add_item(self, product, quantity): ...def calculate_total(self): ...# 領域服務
class OrderProcessingService:def process_order(self, order): ...# 倉儲接口
class OrderRepository:def save(self, order): ...def find_by_id(self, order_id): ...

5.3 異步編程命名

import asyncioclass AsyncDataProcessor:# 異步方法使用async前綴或相關動詞async def fetch_data(self, url): ...async def process_data(self, data): ...async def save_results(self, results): ...# 回調函數命名def on_data_received(self, data): ...def on_processing_complete(self, result): ...def on_error(self, error): ...# 異步上下文管理器
class AsyncDatabaseConnection:async def __aenter__(self):await self.connect()return selfasync def __aexit__(self, exc_type, exc_val, exc_tb):await self.close()async def connect(self): ...async def close(self): ...

六、完整項目示例

6.1 電子商務項目結構

ecommerce-platform/
├── src/
│   └── ecommerce/
│       ├── __init__.py
│       ├── core/
│       │   ├── __init__.py
│       │   ├── models.py
│       │   ├── exceptions.py
│       │   └── types.py
│       ├── domain/
│       │   ├── __init__.py
│       │   ├── product.py
│       │   ├── order.py
│       │   ├── user.py
│       │   └── payment.py
│       ├── application/
│       │   ├── __init__.py
│       │   ├── product_service.py
│       │   ├── order_service.py
│       │   ├── user_service.py
│       │   └── payment_service.py
│       ├── infrastructure/
│       │   ├── __init__.py
│       │   ├── database/
│       │   │   ├── __init__.py
│       │   │   ├── connection.py
│       │   │   ├── repositories.py
│       │   │   └── migrations/
│       │   ├── cache/
│       │   │   ├── __init__.py
│       │   │   └── redis_client.py
│       │   └── external/
│       │       ├── __init__.py
│       │       ├── email_service.py
│       │       └── payment_gateway.py
│       ├── api/
│       │   ├── __init__.py
│       │   ├── routes/
│       │   │   ├── __init__.py
│       │   │   ├── product_routes.py
│       │   │   ├── order_routes.py
│       │   │   └── user_routes.py
│       │   ├── schemas/
│       │   │   ├── __init__.py
│       │   │   ├── product_schemas.py
│       │   │   ├── order_schemas.py
│       │   │   └── user_schemas.py
│       │   └── middleware/
│       │       ├── __init__.py
│       │       ├── authentication.py
│       │       ├── logging.py
│       │       └── error_handling.py
│       └── utils/
│           ├── __init__.py
│           ├── validation.py
│           ├── logging.py
│           ├── security.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── unit/
│   │   ├── __init__.py
│   │   ├── test_models.py
│   │   ├── test_services.py
│   │   └── test_utils.py
│   ├── integration/
│   │   ├── __init__.py
│   │   ├── test_api.py
│   │   ├── test_database.py
│   │   └── test_external_services.py
│   └── conftest.py
├── scripts/
│   ├── setup_database.py
│   ├── run_migrations.py
│   └── start_server.py
├── docs/
│   ├── api.md
│   ├── architecture.md
│   └── development.md
├── requirements/
│   ├── base.txt
│   ├── development.txt
│   └── production.txt
├── config/
│   ├── development.yaml
│   ├── production.yaml
│   └── test.yaml
├── .pre-commit-config.yaml
├── pyproject.toml
├── Dockerfile
└── README.md

6.2 核心模塊代碼示例

# src/ecommerce/core/models.py
"""數據模型定義"""from datetime import datetime
from typing import Optional, List
from decimal import Decimalclass BaseModel:"""所有模型的基類"""created_at: datetimeupdated_at: datetimeis_active: bool = Trueclass Product(BaseModel):"""產品實體"""def __init__(self,product_id: str,name: str,price: Decimal,description: Optional[str] = None,stock_quantity: int = 0):self.product_id = product_idself.name = nameself.price = priceself.description = descriptionself.stock_quantity = stock_quantityself.created_at = datetime.now()self.updated_at = datetime.now()def update_price(self, new_price: Decimal) -> None:"""更新產品價格"""if new_price <= 0:raise ValueError("價格必須大于0")self.price = new_priceself.updated_at = datetime.now()def reduce_stock(self, quantity: int) -> None:"""減少庫存"""if quantity > self.stock_quantity:raise ValueError("庫存不足")self.stock_quantity -= quantityself.updated_at = datetime.now()class Order(BaseModel):"""訂單實體"""def __init__(self, order_id: str, customer_id: str):self.order_id = order_idself.customer_id = customer_idself.order_items: List[OrderItem] = []self.status = "pending"self.total_amount = Decimal('0.00')self.created_at = datetime.now()self.updated_at = datetime.now()def add_item(self, product: Product, quantity: int) -> None:"""添加訂單項"""if quantity <= 0:raise ValueError("數量必須大于0")# 檢查庫存if quantity > product.stock_quantity:raise ValueError("產品庫存不足")item_total = product.price * quantityorder_item = OrderItem(product, quantity, item_total)self.order_items.append(order_item)self.total_amount += item_totalself.updated_at = datetime.now()def calculate_total(self) -> Decimal:"""計算訂單總額"""return sum(item.total_price for item in self.order_items)class OrderItem:"""訂單項值對象"""def __init__(self, product: Product, quantity: int, total_price: Decimal):self.product = productself.quantity = quantityself.total_price = total_price

6.3 服務層代碼示例

# src/ecommerce/application/order_service.py
"""訂單服務層"""from typing import List, Optional
from decimal import Decimal
from datetime import datetime
from ..core.models import Order, Product
from ..core.exceptions import (OrderNotFoundException,ProductNotFoundException,InsufficientStockException
)class OrderService:"""訂單業務服務"""def __init__(self, order_repository, product_repository):self.order_repository = order_repositoryself.product_repository = product_repositorydef create_order(self, customer_id: str, items: List[dict]) -> Order:"""創建新訂單"""order = Order(order_id=self._generate_order_id(),customer_id=customer_id)for item in items:product = self.product_repository.find_by_id(item['product_id'])if not product:raise ProductNotFoundException(f"產品 {item['product_id']} 不存在")try:order.add_item(product, item['quantity'])except ValueError as e:raise InsufficientStockException(str(e))self.order_repository.save(order)return orderdef get_order(self, order_id: str) -> Order:"""獲取訂單詳情"""order = self.order_repository.find_by_id(order_id)if not order:raise OrderNotFoundException(f"訂單 {order_id} 不存在")return orderdef update_order_status(self, order_id: str, new_status: str) -> Order:"""更新訂單狀態"""order = self.get_order(order_id)order.status = new_statusorder.updated_at = datetime.now()self.order_repository.save(order)return orderdef calculate_order_discount(self,order: Order,discount_percentage: Decimal) -> Decimal:"""計算訂單折扣"""if not 0 <= discount_percentage <= 100:raise ValueError("折扣百分比必須在0-100之間")discount_factor = discount_percentage / Decimal('100.00')return order.total_amount * discount_factordef _generate_order_id(self) -> str:"""生成訂單ID"""timestamp = datetime.now().strftime("%Y%m%d%H%M%S")return f"ORD{timestamp}"

6.4 API層代碼示例

# src/ecommerce/api/routes/order_routes.py
"""訂單API路由"""from fastapi import APIRouter, Depends, HTTPException, status
from typing import List
from ...application.order_service import OrderService
from ...infrastructure.database.repositories import get_order_repository
from ...infrastructure.database.repositories import get_product_repository
from ..schemas.order_schemas import (OrderCreateRequest,OrderResponse,OrderStatusUpdate
)router = APIRouter(prefix="/orders", tags=["orders"])@router.post("/", response_model=OrderResponse, status_code=status.HTTP_201_CREATED)
async def create_order(request: OrderCreateRequest,order_service: OrderService = Depends(get_order_service)
) -> OrderResponse:"""創建新訂單"""try:order = order_service.create_order(customer_id=request.customer_id,items=request.items)return OrderResponse.from_domain(order)except Exception as e:raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,detail=str(e))@router.get("/{order_id}", response_model=OrderResponse)
async def get_order(order_id: str,order_service: OrderService = Depends(get_order_service)
) -> OrderResponse:"""獲取訂單詳情"""try:order = order_service.get_order(order_id)return OrderResponse.from_domain(order)except Exception as e:raise HTTPException(status_code=status.HTTP_404_NOT_FOUND,detail=str(e))@router.patch("/{order_id}/status", response_model=OrderResponse)
async def update_order_status(order_id: str,status_update: OrderStatusUpdate,order_service: OrderService = Depends(get_order_service)
) -> OrderResponse:"""更新訂單狀態"""try:order = order_service.update_order_status(order_id=order_id,new_status=status_update.status)return OrderResponse.from_domain(order)except Exception as e:raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST,detail=str(e))def get_order_service():"""獲取訂單服務依賴"""order_repo = get_order_repository()product_repo = get_product_repository()return OrderService(order_repo, product_repo)

七、自動化檢查與工具

7.1 使用pre-commit進行命名檢查

# .pre-commit-config.yaml
repos:- repo: https://github.com/pre-commit/pre-commit-hooksrev: v4.4.0hooks:- id: trailing-whitespace- id: end-of-file-fixer- id: check-yaml- id: check-added-large-files- repo: https://github.com/PyCQA/flake8rev: 6.0.0hooks:- id: flake8additional_dependencies: [flake8-naming]- repo: https://github.com/psf/blackrev: 23.3.0hooks:- id: black- repo: https://github.com/pycqa/isortrev: 5.12.0hooks:- id: isort- repo: https://github.com/pre-commit/mirrors-mypyrev: v1.3.0hooks:- id: mypy

7.2 自定義命名檢查規則

# scripts/check_naming.py
"""自定義命名檢查腳本"""import ast
import re
from pathlib import Path
from typing import List, Dict, Anyclass NamingChecker(ast.NodeVisitor):"""AST節點訪問器，檢查命名規范"""def __init__(self):self.violations: List[Dict[str, Any]] = []self.class_names = set()self.function_names = set()def visit_ClassDef(self, node: ast.ClassDef) -> None:"""檢查類命名"""if not re.match(r'^[A-Z][a-zA-Z0-9]*$', node.name):self.violations.append({'type': 'class','name': node.name,'line': node.lineno,'message': '類名應使用駝峰命名法'})self.class_names.add(node.name)self.generic_visit(node)def visit_FunctionDef(self, node: ast.FunctionDef) -> None:"""檢查函數命名"""if not re.match(r'^[a-z_][a-z0-9_]*$', node.name):self.violations.append({'type': 'function','name': node.name,'line': node.lineno,'message': '函數名應使用蛇形命名法'})# 檢查布爾函數命名if node.name.startswith('is_') or node.name.startswith('has_'):# 應該返回布爾值passself.function_names.add(node.name)self.generic_visit(node)def visit_Name(self, node: ast.Name) -> None:"""檢查變量命名"""if isinstance(node.ctx, ast.Store):if not re.match(r'^[a-z_][a-z0-9_]*$', node.id):self.violations.append({'type': 'variable','name': node.id,'line': node.lineno,'message': '變量名應使用蛇形命名法'})self.generic_visit(node)def visit_Constant(self, node: ast.Constant) -> None:"""檢查常量命名（如果被賦值）"""if hasattr(node, 'parent') and isinstance(node.parent, ast.Assign):for target in node.parent.targets:if isinstance(target, ast.Name) and target.id.isupper():if not re.match(r'^[A-Z_][A-Z0-9_]*$', target.id):self.violations.append({'type': 'constant','name': target.id,'line': node.lineno,'message': '常量名應使用全大寫蛇形命名法'})def check_file_naming(file_path: Path) -> List[Dict[str, Any]]:"""檢查單個文件的命名規范"""try:with open(file_path, 'r', encoding='utf-8') as f:content = f.read()tree = ast.parse(content)checker = NamingChecker()checker.visit(tree)return checker.violationsexcept Exception as e:return [{'type': 'error','name': str(file_path),'line': 0,'message': f'解析文件時出錯: {str(e)}'}]def main():"""主檢查函數"""project_root = Path(__file__).parent.parentpython_files = list(project_root.rglob('*.py'))all_violations = []for file_path in python_files:if 'venv' in str(file_path) or '.pytest_cache' in str(file_path):continueviolations = check_file_naming(file_path)for violation in violations:violation['file'] = str(file_path.relative_to(project_root))all_violations.append(violation)if all_violations:print("命名規范檢查發現以下問題:")for violation in all_violations:print(f"{violation['file']}:{violation['line']} - "f"{violation['type']} '{violation['name']}': "f"{violation['message']}")return 1else:print("所有文件命名規范檢查通過!")return 0if __name__ == "__main__":exit(main())