电商平台API设计涉及完整的多领域业务，是API设计的经典案例。本文以一个真实电商平台建设过程为背景，分享商品浏览、下单支付、订单管理等核心API的设计经验和注意事项。
商品服务API设计
商品服务是电商的核心，API需要兼顾查询性能和灵活性。商品列表：GET /v1/products 支持分类筛选、价格区间、关键词搜索和综合排序。商品详情：GET /v1/products/{productId} 返回商品信息、规格参数、SKU列表和评价摘要。SKU查询：GET /v1/products/{productId}/skus 查询具体规格的库存和价格。商品搜索走ES搜索引擎，支持中文分词和拼音搜索。库存查询需要实时准确，缓存策略要谨慎。
购物车API设计
购物车是用户浏览和下单的中间状态，需要实时同步。加入购物车：POST /v1/cart/items 参数含商品ID、SKU ID和数量。购物车列表：GET /v1/cart/items 返回购物车中的所有商品及其最新价格和库存状态。修改数量：PUT /v1/cart/items/{itemId} 修改指定商品数量。删除商品：DELETE /v1/cart/items/{itemId} 移出购物车。购物车服务需要每次查询实时拉取最新价格，防止下单时价格与展示不一致。
订单服务API设计
订单API涉及创建、支付、发货、收货的完整状态流转。创建订单：POST /v1/orders 提交订单信息，包含收货地址、商品列表和优惠券，创建时锁定库存。订单列表：GET /v1/orders 支持按状态筛选和分页。订单详情：GET /v1/orders/{orderId} 返回订单的完整信息和状态变更历史。取消订单：POST /v1/orders/{orderId}/cancel 只有待支付状态可取消，取消后解锁库存。订单API是事务密集型接口，分布式事务通过Saga模式实现。