后端服务接口开发与数据逻辑处理

一、整体分层：让接口只负责"翻译"

一个稳定的后端服务通常分为四层，职责边界清晰，后续扩展才不会失控：

层次	职责	不该做的事
Router / Controller	路由、参数解析、鉴权、返回包装	写业务规则、直连数据库
Service	业务编排、事务边界、领域校验	拼 SQL、处理 HTTP 状态码
Repository	数据访问、查询构造	业务判断、抛业务异常
Model / Schema	数据结构与序列化契约	承载业务逻辑

接口层的核心工作只有一件：把外部请求翻译成领域入参，再把领域结果翻译回响应。业务规则一旦下沉到 Controller，复用与测试都会变得困难。

二、接口契约：先定输入输出的形状

用 Pydantic 定义请求与响应模型，把校验前移到入口：

python 复制代码

from pydantic import BaseModel, Field, field_validator
from typing import Optional

class OrderCreateReq(BaseModel):
    user_id: int = Field(gt=0)
    sku_code: str = Field(min_length=6, max_length=32)
    quantity: int = Field(ge=1, le=99)
    coupon_id: Optional[int] = None

    @field_validator("sku_code")
    @classmethod
    def upper(cls, v: str) -> str:
        return v.strip().upper()

统一的响应封装让前端不必为每个接口写不同的解析逻辑：

python 复制代码

def ok(data=None, code=0, msg="success"):
    return {"code": code, "msg": msg, "data": data, "trace_id": get_trace_id()}

约定三件事：错误码分段 （1xxxx 参数类、2xxxx 业务类、5xxxx 系统类）、分页字段固定 （page/size/total/list）、时间统一 ISO8601 + 时区。这三条定死之后，联调成本会显著下降。

三、数据逻辑处理：事务、幂等、并发

1. 事务边界放在 Service 层

python 复制代码

def create_order(req: OrderCreateReq) -> Order:
    with db.transaction():
        stock = repo.deduct_stock(req.sku_code, req.quantity)   # 条件更新，库存不足返回 None
        if stock is None:
            raise BizError(20001, "库存不足")
        order = repo.insert_order(req, amount=calc_amount(req, stock))
        if req.coupon_id:
            repo.lock_coupon(req.coupon_id, req.user_id)        # 校验归属与状态
    return order

事务要短：不要在事务里调用外部 HTTP、发消息、写日志文件。跨系统的一致性靠本地消息表 + 补偿任务，而不是长事务。

2. 幂等是接口的必备属性

客户端重试、网关超时重发都会造成重复写入。最省事的做法是"业务唯一键 + 唯一索引"：

python 复制代码

# 唯一索引 uk_user_sku_req (user_id, sku_code, request_id)
try:
    repo.insert_order(req, request_id=req.request_id)
except IntegrityError:
    return repo.get_order_by_request_id(req.request_id)   # 直接返回首次结果

对扣减类操作，用条件更新代替"先查后改"，避免并发超卖：

sql 复制代码

UPDATE stock SET available = available - :n
WHERE sku_code = :sku AND available >= :n;

3. 读写分离下的"读到旧数据"

主从延迟是真实存在的。写后立即读的场景，要么强制走主库（打标 force_master），要么在缓存里做短时写穿。不要用"业务上应该没问题"来赌。

四、查询、分页与缓存

深分页 ：limit offset 在百万行时会退化为全表扫描，改用游标分页 where id < last_id order by id desc limit n。
N+1 查询：列表页务必一次性批量取关联数据，而不是在循环里查。
缓存三件事：key 设计带版本前缀、过期时间加随机抖动防雪崩、更新走"先更库再删缓存"并接受短暂不一致。

python 复制代码

CACHE_KEY = "order:detail:v2:{order_id}"

def get_order_detail(order_id: int) -> dict:
    cached = redis.get(CACHE_KEY.format(order_id=order_id))
    if cached:
        return json.loads(cached)
    data = repo.get_order_detail(order_id)
    redis.setex(CACHE_KEY.format(order_id=order_id), 300 + random.randint(0, 60), json.dumps(data))
    return data

五、异常与可观测性

业务异常用自定义 BizError(code, msg)，由全局异常处理器统一转成 HTTP 200 + 业务码（或按团队规范映射 4xx），系统异常一律 500 且不把堆栈暴露给调用方：

python 复制代码

@app.exception_handler(BizError)
async def biz_handler(request, exc: BizError):
    return JSONResponse(ok(None, code=exc.code, msg=exc.msg))

日志里必须带 trace_id，从网关透传到 Service 与 SQL 层。一个请求的完整链路能靠一个 ID 串起来，排障时间会从小时级降到分钟级。

六、上线前的检查清单

入参校验是否覆盖边界（空、超长、负数、非法枚举）。
每个写接口是否具备幂等能力。
事务内是否有外部调用。
列表接口是否有分页上限与 N+1 风险。
异常是否被吞掉、是否泄露内部信息。
是否有监控指标：QPS、P99、错误率、慢 SQL。

接口开发的难点从来不是"把功能跑通"，而是在并发、失败、重试、延迟这些非正常路径上依然给出确定的行为。把契约定清楚、把事务收窄、把幂等做实，剩下的才是业务细节。

海量精选技术文档和实战案例持续更新，敬请关注【风骏时光少年】