从混乱到规范：如何通过skill书写规范提升代码可维护性

2次阅读

共计 2255 个字符，预计需要花费 6 分钟才能阅读完成。

去年我们的支付系统曾因一个 skill 命名冲突导致线上故障：两个团队各自开发了 queryBalance() 和QueryBalance()方法，由于大小写不敏感的文件系统，测试环境一切正常，但上线后 Linux 服务器直接报ModuleNotFoundError。更糟的是，异常被全局捕获后仅记录日志而未中断流程，最终造成 3000 多笔重复扣款。这次事故让我们意识到，skill 规范不是风格问题，而是生产安全的关键防线。

驼峰式(CamelCase)
适用场景：Java/JavaScript 等语言惯例，适合类名 / 方法名（如processPaymentRequest）
优势：编辑器自动补全友好，视觉连贯性强
下划线式(snake_case)
适用场景：Python/Ruby 等动态语言，尤其适合函数名（如validate_user_input）
优势：可读性高，与系统 API 风格统一
匈牙利命名法
现代开发已不推荐，但遗留系统中可能遇到（如strUserName）
特殊场景：Win32 API 或类型系统薄弱的旧代码

# 服务类方法用 svc_开头
async def svc_fetch_user_profile(user_id: int) -> User:
    ...

# API 路由处理用 api_开头
def api_v1_login(request: HttpRequest) -> JsonResponse:
    ...

# 工具函数用 util_开头
def util_generate_secure_token(length: int = 32) -> str:
    ...

from pydantic import BaseModel, validator
from typing import Optional

class PaymentRequest(BaseModel):
    amount: float
    currency: str
    memo: Optional[str] = None

    @validator('amount')
    def check_amount(cls, v):
        if v <= 0:
            raise ValueError('Amount must be positive')
        return round(v, 2)

# 使用示例
try:
    req = PaymentRequest(amount=19.99, currency='USD')
except ValueError as e:
    logger.error(f'Invalid request: {str(e)}')
    raise APIException(400, str(e))

from dataclasses import dataclass
from typing import TypeVar, Generic

T = TypeVar('T')

@dataclass
class Result(Generic[T]):
    success: bool
    data: T = None
    error: str = None

    @classmethod
    def ok(cls, data: T) -> 'Result':
        return cls(True, data=data)

    @classmethod
    def fail(cls, error: str) -> 'Result':
        return cls(False, error=error)

# 使用场景
def get_order(order_id: int) -> Result[Order]:
    try:
        order = db.query_order(order_id)
        return Result.ok(order) if order else Result.fail('Order not found')
    except DatabaseError as e:
        return Result.fail(f'Database error: {str(e)}')