Python 业务开发“词汇表”：从用户登录到支付回调的常用变量与代码模版

在业务系统开发中，很多变量命名和逻辑结构是高度复用的。掌握这套“行业黑话”和通用模版，你读开源项目（如 Django、Flask 项目）会顺畅 10 倍，自己写代码也不再需要反复纠结变量叫什么。

这篇文章整理了 Web 开发、自动化脚本中最常见的 变量命名规范、用户交互逻辑​ 和 支付/业务处理​ 的代码片段。

一、通用变量命名规范（行业惯例）

写代码就像写文章，变量名就是名词。遵循这些规范，代码看起来会非常“专业”。

1. 布尔值（Boolean）：用 is_、has_、can_ 开头

这是 Python 之禅（Zen of Python）推崇的可读性写法。

# ✅ 推荐
is_active = True       # 是否激活
is_authenticated = False # 是否已认证
has_permission = True  # 是否有权限
can_edit = False       # 是否可以编辑
is_deleted = False     # 软删除标志（非常重要）

# ❌ 不推荐
active = True
permission = True
delete = False

2. 复数名词表示集合（List/Dict）

当你存储的是一组数据时，用复数。

# ✅ 推荐
users = []             # 用户列表
items = ["apple", "banana"]
product_ids = [1001, 1002, 1003]
config_map = {"host": "...", "port": 8080}

# ❌ 不推荐
user_list = []         # 冗余
productIdList = []     # 不符合 Python 蛇形命名法 (snake_case)

3. 数据库/ORM 字段常用前缀

在处理数据库记录时，这些是约定俗成的：

# id 相关
id = 123               # 主键
user_id = 123          # 外键
uid = "u_abc_123"      # 业务唯一ID（字符串类型，常用于分布式系统）

# 时间相关（非常重要）
created_at = datetime.now()  # 创建时间
updated_at = datetime.now()  # 更新时间
deleted_at = None            # 删除时间（用于软删除）
timestamp = 1700000000       # 时间戳

# 状态机（State Machine）
status = "pending"           # 状态：pending(待处理), processing(处理中), success(成功), failed(失败)
state = "published"          # 状态：draft(草稿), published(发布), archived(归档)

二、用户交互与鉴权（User & Auth）

用户系统是互联网产品的基石，以下是标准字段和验证逻辑。

1. 用户注册/登录的标准字段

# 用户核心字段
username = "kimi_ai"        # 用户名（唯一）
password = "raw_password"   # 原始密码（严禁存明文！）
password_hash = ""          # 加密后的密码（存数据库用）
email = "user@example.com"
phone = "+8613800138000"

# 登录凭证（Token）
access_token = "eyJhbGciOi..."   # 短期令牌（用于接口鉴权，有效期短，如2小时）
refresh_token = "def502..."      # 刷新令牌（用于获取新的 access_token，有效期长，如7天）
session_id = "sess_xyz"          # Session ID（传统 Web 应用常用）

# 验证码
captcha_code = "AbCd"            # 图形验证码
sms_code = "123456"              # 短信验证码
expires_in = 300                 # 过期时间（秒）

2. 密码加密与验证（必知必会）

绝对不要使用 MD5，请使用 bcrypt 或 hashlib.pbkdf2_hmac。

import hashlib
import os

def hash_password(password: str) -> str:
    """使用 PBKDF2 加密密码"""
    salt = os.urandom(16)  # 生成随机盐值
    key = hashlib.pbkdf2_hmac(
        'sha256',
        password.encode('utf-8'),
        salt,
        100000  # 迭代次数，越高越安全，但越慢
    )
    # 存储时将盐值和密钥拼接
    return salt.hex() + ':' + key.hex()

def verify_password(stored_password: str, provided_password: str) -> bool:
    """验证密码"""
    salt_hex, key_hex = stored_password.split(':')
    salt = bytes.fromhex(salt_hex)
    stored_key = bytes.fromhex(key_hex)
    
    new_key = hashlib.pbkdf2_hmac(
        'sha256',
        provided_password.encode('utf-8'),
        salt,
        100000
    )
    return new_key == stored_key

# 使用示例
hashed = hash_password("my_secret_password")
print(f"验证结果: {verify_password(hashed, 'my_secret_password')}")

三、支付与订单系统（Payment & Order）

这是业务逻辑最复杂的地方，涉及金钱必须严谨。

1. 金额处理（血泪教训：别用 Float！）

永远使用整数（分）或 Decimal 来存储金额，不要用 float（会有精度丢失）。

from decimal import Decimal

# ✅ 正确姿势
price_cents = 9999          # 价格（单位：分），数据库中存这个
amount = Decimal("99.99")   # 金额（单位：元），计算时用 Decimal

# ❌ 致命错误
price_float = 99.99         # 计算机二进制无法精确表示 0.99，会导致对账不平

# 转换
total_fee_yuan = Decimal("199.98")
total_fee_fen = int(total_fee_yuan * 100)  # 微信/支付宝接口通常要求传分

# 订单状态机
ORDER_STATUS = {
    "PENDING": "pending",           # 待支付
    "PAID": "paid",                 # 已支付
    "SHIPPED": "shipped",           # 已发货
    "COMPLETED": "completed",       # 已完成
    "REFUNDING": "refunding",       # 退款中
    "REFUNDED": "refunded",         # 已退款
    "CLOSED": "closed"              # 已关闭（超时未支付）
}

2. 模拟支付接口回调（Webhook）

第三方支付平台（如支付宝、Stripe）通常会向你发送回调通知。

import hmac
import hashlib
import json

def verify_payment_callback(payload: bytes, signature: str, secret: str) -> bool:
    """
    验证支付回调的签名（防止伪造请求）
    payload: 接收到的原始请求体（bytes）
    signature: 请求头里的签名
    secret: 商户密钥
    """
    expected_signature = hmac.new(
        key=secret.encode('utf-8'),
        msg=payload,
        digestmod=hashlib.sha256
    ).hexdigest()
    
    # 安全的比较方式（防止时序攻击）
    return hmac.compare_digest(expected_signature, signature)

def handle_payment_notify(data: dict):
    """处理支付成功逻辑"""
    out_trade_no = data.get("out_trade_no")  # 商户订单号
    trade_no = data.get("trade_no")          # 第三方交易号
    total_amount = data.get("total_amount")   # 支付金额
    
    print(f"订单 {out_trade_no} 支付成功！")
    print(f"第三方流水号: {trade_no}, 金额: {total_amount}")
    
    # 1. 校验订单是否存在
    # 2. 校验金额是否一致（防止少付）
    # 3. 校验订单状态是否为 pending
    # 4. 更新订单状态为 paid
    # 5. 增加用户积分/发货
    # 6. 返回 "success" 字符串给第三方，告知已收到通知

四、API 交互与配置（API & Config）

1. 配置文件（Settings）

不要把密钥写在代码里！

# config.py 或 settings.py
import os
from dataclasses import dataclass

@dataclass
class Settings:
    """应用配置"""
    # 从环境变量读取，如果没有则使用默认值
    DATABASE_URL: str = os.getenv("DB_URL", "sqlite:///./test.db")
    REDIS_HOST: str = os.getenv("REDIS_HOST", "localhost")
    
    # 密钥（必须放在环境变量中）
    SECRET_KEY: str = os.getenv("SECRET_KEY", "unsafe_default_key")
    WECHAT_APP_ID: str = os.getenv("WECHAT_APP_ID", "")
    WECHAT_MCH_KEY: str = os.getenv("WECHAT_MCH_KEY", "")
    
    # API 限流
    RATE_LIMIT_PER_MINUTE: int = 60

settings = Settings()

2. HTTP 请求标准模版

import requests
from typing import Optional, Dict

def api_request(
    url: str, 
    method: str = "GET", 
    params: Optional[Dict] = None, 
    data: Optional[Dict] = None,
    timeout: int = 10
) -> Dict:
    """统一的 API 请求封装"""
    headers = {
        "User-Agent": "MyApp/1.0",
        "Authorization": f"Bearer {settings.SECRET_KEY}",
        "Content-Type": "application/json"
    }
    try:
        response = requests.request(
            method=method.upper(),
            url=url,
            params=params,
            json=data,  # 自动序列化字典为 JSON
            headers=headers,
            timeout=timeout
        )
        response.raise_for_status()  # 如果状态码是 4xx/5xx，抛出异常
        return response.json()
    except requests.exceptions.Timeout:
        print("请求超时")
        return {"error": "timeout"}
    except requests.exceptions.HTTPError as e:
        print(f"HTTP 错误: {e.response.status_code}")
        return {"error": str(e)}

五、日志与错误处理（Logging）

不要只用 print，学会用 logging。

import logging

# 基础配置
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    handlers=[
        logging.FileHandler("app.log"),  # 输出到文件
        logging.StreamHandler()          # 输出到控制台
    ]
)
logger = logging.getLogger(__name__)

def process_order(order_id: str):
    logger.info(f"开始处理订单 {order_id}")
    try:
        # 业务逻辑
        result = 10 / 0
    except ZeroDivisionError as e:
        logger.error(f"订单 {order_id} 处理失败: {e}", exc_info=True)  # exc_info=True 打印堆栈信息
        raise  # 重新抛出异常，让上层处理
    finally:
        logger.info(f"订单 {order_id} 处理流程结束")

总结：记住这些“定式”

这套命名和代码逻辑在 80% 的后端项目和复杂脚本中都通用。如果你想针对某个特定框架（比如 FastAPI 或 Django）看看它们是如何组织这些变量的，我可以接着给你拆解。