蔬菜网上超市源码解析：3个核心模块拆解项目落地难点

刚学完Python语法，对着官方文档敲代码没问题，但真要做个蔬菜网上超市，脑子一片空白？别慌。很多新手卡在“知道怎么写if-else，但不知道if-else该放在哪个文件里”。今天这篇源码解析，不讲虚的，直接拿一个精简版的蔬菜网上超市项目开刀。

我们重点拆解三个最容易让新手翻车的环节：用户认证、库存扣减、订单状态机。这三个点搞懂了，你就能从“语法搬运工”变成“项目搭建者”。以下内容基于一个使用FastAPI + PostgreSQL + Redis的开源项目结构进行改造分析，逻辑清晰，适合项目现场管理员直接参考。

1. 入口定位：请求是怎么流转的

很多新手看源码，第一眼就陷进某个具体函数里，越看越晕。正确的打开方式是看“流”。

在蔬菜网上超市中，用户点击“购买青菜”这个动作，数据是这样走的：

前端请求：POST /api/orders/create，携带 user_id、item_id、quantity。
API层：order_router.py 接收请求，做参数校验（Pydantic Model）。
服务层：order_service.py 执行业务逻辑，这是核心。
数据层：调用 stock_service 扣库存，调用 db 写订单表。
响应：返回订单号。

关键设计思想：API层不写业务逻辑，只负责“接货”和“发货”。业务逻辑全在Service层。这样以后换接口（比如从REST换GraphQL），Service层代码一行不用改。

2. 核心片段一：高并发下的库存扣减

这是电商项目最大的坑。两个用户同时买最后一颗白菜，如果处理不好，就会出现“超卖”——用户付了钱，但菜没了。

很多教程教你用 SELECT ... FOR UPDATE 数据库行锁，但在高并发下，数据库压力巨大。更优雅的方案是用 Redis 原子操作 做前置拦截，数据库做最终一致性。

以下是 stock_service.py 中的核心代码片段：

import redis
import asyncio
from fastapi import HTTPException
from .db import get_db# 初始化Redis连接，这里假设已经配置好
redis_client = redis.Redis(host='localhost', port=6379, db=0)async def deduct_stock(item_id: int, quantity: int) -> bool:"""原子性扣减库存:param item_id: 商品ID:param quantity: 购买数量:return: 是否扣减成功"""# 1. 构建Redis Key，例如 stock:1001key = f"stock:{item_id}"# 2. 使用Lua脚本保证原子性# 这是Redis官方文档推荐的高并发安全做法# 逻辑：如果当前库存 > 0 且 库存 >= 请求数量，则扣减并返回1，否则返回0lua_script = """local stock = tonumber(redis.call('get', KEYS[1]))if (stock == false) thenreturn -1  -- 商品不存在或缓存未预热elseif (stock < tonumber(ARGV[1])) thenreturn 0   -- 库存不足elseredis.call('decrby', KEYS[1], ARGV[1])return 1   -- 扣减成功end"""# 3. 执行Lua脚本# client.eval(script, numkeys, key, arg)result = await asyncio.to_thread(redis_client.eval, lua_script, 1, key, quantity)# 4. 处理结果if result == 1:return Trueelif result == 0:raise HTTPException(status_code=400, detail="库存不足")else:# 缓存失效，需要回源数据库查询await fallback_to_db(item_id, quantity)return Falseasync def fallback_to_db(item_id: int, quantity: int):"""当Redis缓存未命中或异常时，回源数据库这里使用数据库乐观锁或行锁作为兜底"""db = await get_db()try:# 注意：这里需要确保数据库层面的原子性# 实际项目中应结合事务和锁机制query = f"UPDATE items SET stock = stock - {quantity} WHERE id = {item_id} AND stock >= {quantity}"result = await db.execute(query)if result.rowcount == 0:raise HTTPException(status_code=400, detail="库存不足")finally:await db.close()

逐行解析要点：

为什么用Lua脚本？ Redis单线程模型下，Lua脚本是原子执行的。如果不用Lua，而是先get再decrby，中间会有时间窗口，两个请求可能同时get到足够库存，导致超卖。
asyncio.to_thread：FastAPI是异步框架，但redis-py的同步操作会阻塞事件循环。用to_thread将阻塞操作扔进线程池，避免卡死整个服务。
兜底策略：Redis不是万能的，宕机或缓存穿透时，必须回源数据库。数据库层使用WHERE stock >= quantity条件更新，这是最基础的防超卖手段。

3. 核心片段二：订单状态机与合格标准

蔬菜易腐，订单状态比一般电商更复杂。除了“待支付”、“已支付”，还有“拣货中”、“已出库”、“已送达”、“已退款”等。状态流转如果写乱，就是灾难。

合格标准：状态流转必须不可逆（除了特定取消场景），且每次变更都要有日志。

我们用状态机模式来管理。以下是一个简化的 order_status.py：

from enum import Enum
from typing import Dict, Listclass OrderStatus(str, Enum):PENDING = "pending"       # 待支付PAID = "paid"             # 已支付PICKING = "picking"       # 拣货中SHIPPED = "shipped"       # 已出库DELIVERED = "delivered"   # 已送达CANCELLED = "cancelled"   # 已取消REFUNDED = "refunded"     # 已退款class OrderStateMachine:def __init__(self):# 定义合法的状态转换规则# key: 当前状态, value: 允许转换到的下一个状态列表self.transitions: Dict[str, List[str]] = {OrderStatus.PENDING: [OrderStatus.PAID, OrderStatus.CANCELLED],OrderStatus.PAID: [OrderStatus.PICKING, OrderStatus.CANCELLED],OrderStatus.PICKING: [OrderStatus.SHIPPED],OrderStatus.SHIPPED: [OrderStatus.DELIVERED],OrderStatus.DELIVERED: [OrderStatus.REFUNDED],OrderStatus.CANCELLED: [],  # 终态OrderStatus.REFUNDED: []    # 终态}def can_transition(self, current_status: str, next_status: str) -> bool:"""检查状态转换是否合法:param current_status: 当前状态:param next_status: 目标状态:return: 是否允许转换"""if current_status not in self.transitions:return Falseallowed_next_states = self.transitions[current_status]return next_status in allowed_next_statesdef get_allowed_next_states(self, current_status: str) -> List[str]:"""获取当前状态允许的所有下一步状态用于前端展示按钮或后台权限控制"""if current_status not in self.transitions:return []return self.transitions[current_status]# 使用示例
# state_machine = OrderStateMachine()
# is_valid = state_machine.can_transition("pending", "paid")  # True
# is_invalid = state_machine.can_transition("pending", "shipped") # False

设计思想：

集中管理：所有状态规则集中在一个类里，而不是散落在各个Service方法中。
前后端解耦：前端可以调用get_allowed_next_states来决定显示“取消”还是“确认收货”按钮，避免硬编码。
易扩展：如果以后增加“部分退款”状态，只需在transitions字典中加一行，不用改业务逻辑代码。

4. 手写简化版：从零搭建骨架

理解了核心逻辑，我们来搭个最简骨架。假设你只有一台服务器，没有Redis，用纯SQL防超卖。

项目结构：

vegetable_market/
├── main.py
├── models.py
├── services/
│   ├── __init__.py
│   └── order_service.py
└── requirements.txt

main.py (入口)：

from fastapi import FastAPI
from .routers import order_routerapp = FastAPI(title="蔬菜网上超市API")# 注册路由
app.include_router(order_router.router, prefix="/api")@app.get("/")
def root():return {"message": "蔬菜网上超市运行中"}

models.py (数据模型)：

from pydantic import BaseModel
from typing import Optionalclass CreateOrderRequest(BaseModel):user_id: intitem_id: intquantity: intclass OrderResponse(BaseModel):order_id: strstatus: str

services/order_service.py (核心逻辑)：

import uuid
import asyncio
from sqlalchemy.ext.asyncio import AsyncSession
from ..db import get_db
from ..models import CreateOrderRequest, OrderResponseasync def create_order(request: CreateOrderRequest) -> OrderResponse:db: AsyncSession = await get_db()try:# 1. 生成唯一订单IDorder_id = str(uuid.uuid4())# 2. 开启事务# 注意：实际项目中应使用更严谨的事务管理async with db.begin():# 3. 扣减库存 (使用SQL条件更新防超卖)# 假设items表有stock字段from sqlalchemy import textquery = text("UPDATE items SET stock = stock - :qty WHERE id = :item_id AND stock >= :qty")result = await db.execute(query, {"qty": request.quantity, "item_id": request.item_id})if result.rowcount == 0:# 库存不足，抛出异常，事务回滚raise ValueError("库存不足")# 4. 创建订单记录from sqlalchemy import insertorder_data = {"id": order_id,"user_id": request.user_id,"item_id": request.item_id,"quantity": request.quantity,"status": "pending"}await db.execute(insert("orders"), order_data)# 5. 返回成功响应return OrderResponse(order_id=order_id, status="pending")except ValueError as e:# 业务异常，直接抛出HTTPExceptionfrom fastapi import HTTPExceptionraise HTTPException(status_code=400, detail=str(e))finally:await db.close()

避坑指南：

事务边界：db.begin() 确保扣库存和写订单是原子的。如果扣库存成功但写订单失败，库存必须回滚，否则用户付了钱但订单没了。
异步Session：FastAPI配合SQLAlchemy 2.0异步模式，必须用AsyncSession，不能用同步的Session，否则阻塞。
错误处理：ValueError是业务错误，要转成HTTP 400；其他异常如数据库连接错误，应转成HTTP 500并记录日志。

5. 应用场景与进阶技巧

这套源码解析的结构，适用于所有库存敏感型业务。不仅是蔬菜，水果、生鲜、票务、酒店预订都类似。

进阶技巧：

缓存预热：系统启动时，将所有蔬菜的库存加载到Redis，避免第一个请求回源数据库。
幂等性：用户可能重复点击“支付”。前端加按钮防抖，后端用order_id作为幂等键，Redis设置SETNX，防止重复扣款。
监控告警：对“库存不足”异常加监控，如果某蔬菜频繁报库存不足，可能是库存同步延迟，需要人工介入。

证书变更与注销流程（针对项目现场管理员）：在实际运维中，如果涉及SSL证书变更（如HTTPS升级），流程如下：

变更：在Nginx配置中替换证书文件，执行nginx -s reload。确保新证书包含SAN（Subject Alternative Name），覆盖所有域名。
注销：如果证书泄露或过期，需在CA机构官网提交注销请求，通常需要提供CSR和身份验证。
合格标准：新证书必须通过openssl s_client -connect domain:443 -showcerts验证，确保证书链完整，无警告。

通过率：在自动化测试中，订单创建接口的通过率应达到100%。建议编写单元测试，模拟高并发场景，使用locust或jmeter压测，确保P99延迟在200ms以内，无超卖发生。