ProStock/.kilocode/rules/python-development-guidelines.md

Python 开发规范

1 代码风格规范

1.1 缩进与空格

• 使用 4个空格 进行缩进（禁止使用Tab）
• 每行代码最大长度限制为 120字符
• 二元运算符前后使用空格（链式赋值除外）
• 函数参数周围空格一致

# 正确示例
def calculate_total_price(price: float, tax_rate: float) -> float:
    total = price * (1 + tax_rate)
    return round(total, 2)

# 错误示例
def calculate_total_price(price:float,tax_rate:float)->float:
    total=price*(1+tax_rate)
    return round(total,2)

1.2 导入规范

• 导入位于文件顶部，位于模块注释和文档字符串之后
• 标准库导入放在最前面，其次是第三方库，最后是本地应用模块
• 使用绝对导入，禁止使用通配符导入（from module import *）
• 每组导入之间保留一个空行

# 标准库
import os
import sys
from datetime import datetime

# 第三方库
import numpy as np
import pandas as pd
from pydantic import BaseModel

# 本地模块
from src.config import settings
from src.utils.logger import get_logger

1.3 命名规范

类型	规范	示例
模块	全小写，下划线分隔	data_processor.py
包	全小写，禁止下划线	src/utils
类	PascalCase，首字母大写	UserAccount, DataValidator
函数	snake_case，全小写	get_user_data(), calculate_total()
变量	snake_case，全小写	user_name, total_count
常量	UPPER_SNAKE_CASE	MAX_RETRY_COUNT, DEFAULT_TIMEOUT
私有方法/变量	单下划线前缀	_internal_method(), _private_var
类型变量	PascalCase	UserType, T = TypeVar('T')

1.4 注释规范

• 使用英文注释，禁止使用中文注释
• 复杂逻辑必须添加注释说明意图
• 注释与代码同步更新，禁止过时注释

# 单行注释（与代码同行时，注释前保留2个空格）
def process_data(data: list) -> dict:  # Process input data and return statistics
    pass

# 多行文档字符串（Google风格）
def calculate_metrics(values: list[float]) -> dict[str, float]:
    """Calculate statistical metrics for a list of values.

    Args:
        values: List of numeric values to analyze

    Returns:
        Dictionary containing mean, median, and standard deviation

    Raises:
        ValueError: If input list is empty
    """
    pass

2 架构设计规范

2.1 模块结构

src/
├── core/           # 核心业务逻辑
├── modules/        # 功能模块
├── utils/          # 工具函数
├── config/         # 配置管理
├── services/       # 服务层
├── models/         # 数据模型
├── repositories/   # 数据访问层
└── schemas/        # Pydantic模型

2.2 依赖原则

• 依赖倒置：高层模块不依赖低层模块，两者都依赖抽象
• 禁止循环依赖：模块间引用必须形成有向无环图
• 单一职责：每个类/模块只负责一项职责

# 错误示例：高内聚低耦合违反
class UserService:
    def __init__(self, db_connection, email_sender, cache_manager):
        pass

# 正确示例：通过抽象接口解耦
class UserService:
    def __init__(self, user_repository: IUserRepository):
        self.repository = user_repository

2.3 函数设计

• 单一职责：每个函数只做一件事
• 参数控制：函数参数不超过5个，超过则使用对象封装
• 返回值明确：返回类型必须注解

# 错误示例：函数职责过多
def process_user_registration(name, email, password, send_email, create_session):
    if send_email:
        send_verification_email(email)
    if create_session:
        create_user_session(email)
    return save_user(name, email, password)

# 正确示例：单一职责拆分
class UserRegistrationService:
    def register(self, user_data: UserCreateDto) -> User:
        user = self._validate_and_create_user(user_data)
        self._send_verification_email(user)
        self._create_session(user)
        return user

    def _validate_and_create_user(self, data: UserCreateDto) -> User:
        pass

    def _send_verification_email(self, user: User) -> None:
        pass

3 配置管理规范

3.1 禁止硬编码

所有关键配置必须外置，禁止在代码中硬编码

类型	必须外置的配置
数据库连接	HOST, PORT, USER, PASSWORD, DATABASE
API密钥	SECRET_KEY, API_KEY
外部服务	ENDPOINT, TIMEOUT, RETRY_COUNT
业务参数	MAX_RETRIES, CACHE_TTL, RATE_LIMIT

3.2 配置目录结构

config/
├── .env.example          # 环境变量模板（不包含敏感信息）
├── .env.local            # 本地环境配置（被.gitignore忽略）
├── config.yaml           # 通用配置
├── config.development.yaml  # 开发环境配置
├── config.production.yaml   # 生产环境配置
└── config.test.yaml      # 测试环境配置

3.3 配置加载示例

# src/config/settings.py
from pydantic_settings import BaseSettings
from functools import lru_cache


class Settings(BaseSettings):
    """应用配置类，从环境变量加载"""
    
    # 数据库配置
    database_host: str = "localhost"
    database_port: int = 5432
    database_name: str = "prostock"
    database_user: str
    database_password: str
    
    # API配置
    api_key: str
    secret_key: str
    jwt_algorithm: str = "HS256"
    access_token_expire_minutes: int = 30
    
    # Redis配置
    redis_host: str = "localhost"
    redis_port: int = 6379
    
    class Config:
        env_file = ".env.local"
        env_file_encoding = "utf-8"


@lru_cache()
def get_settings() -> Settings:
    """获取配置单例"""
    return Settings()

3.4 .env.example 模板

# ===========================================
# ProStock 环境变量配置模板
# 复制此文件为 .env.local 并填入实际值
# ===========================================

# 数据库配置
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=prostock
DATABASE_USER=your_username
DATABASE_PASSWORD=your_password

# API密钥配置
API_KEY=your_api_key
SECRET_KEY=your_secret_key_here

# Redis配置（可选）
REDIS_HOST=localhost
REDIS_PORT=6379

4 错误处理规范

4.1 异常分类

# src/core/exceptions.py
class BaseCustomException(Exception):
    """基础异常类"""
    status_code: int = 500
    detail: str = "An unexpected error occurred"
    
    def __init__(self, detail: str = None):
        self.detail = detail or self.detail
        super().__init__(self.detail)


class ValidationError(BaseCustomException):
    """数据验证异常"""
    status_code = 422
    detail = "Validation error"


class AuthenticationError(BaseCustomException):
    """认证异常"""
    status_code = 401
    detail = "Authentication required"


class AuthorizationError(BaseCustomException):
    """授权异常"""
    status_code = 403
    detail = "Permission denied"


class NotFoundError(BaseCustomException):
    """资源不存在"""
    status_code = 404
    detail = "Resource not found"

4.2 错误处理原则

• 向上层传递有意义的信息
• 记录详细日志（不含敏感信息）
• 区分可恢复和不可恢复错误

5 测试规范

5.1 测试要求

• 所有核心功能必须有单元测试
• 关键业务逻辑测试覆盖率不低于80%
• 使用 pytest 作为测试框架
• 使用 pytest-cov 生成覆盖率报告

5.2 测试文件结构

tests/
├── conftest.py           # 共享fixtures
├── unit/                 # 单元测试
│   ├── test_models.py
│   ├── test_services.py
│   └── test_utils.py
├── integration/          # 集成测试
│   └── test_api.py
└── fixtures/             # 测试数据

6 Git提交规范

6.1 提交信息格式

<type>(<scope>): <subject>

<body>

<footer>

6.2 类型标识

类型	说明
feat	新功能
fix	Bug修复
docs	文档更新
style	代码格式调整
refactor	重构
test	测试相关
chore	构建/辅助工具

7 代码审查清单

• 代码符合PEP 8规范
• 关键配置未硬编码
• 函数/类添加了类型注解
• 复杂逻辑有注释说明
• 单元测试覆盖关键逻辑
• 无循环依赖
• 命名符合规范
• 日志不包含敏感信息