架构与系统设计 / 系统课时

核心接口先设计什么

核心接口先设计什么

系统设计面试中,接口设计不是把所有功能都列成 API,而是先找到用户完成核心动作时必须经过的业务入口。本篇将从用户行为出发,设计关键接口、输入输出和错误语义。

学习目标

  • 理解为什么接口设计应该从用户动作和业务结果开始
  • 掌握核心 API 的输入、输出和错误语义设计方法
  • 能在系统设计面试中快速描述接口边界

从用户动作找到核心接口

设计接口前先回答一个问题:用户最重要的动作是什么。系统不是围绕数据库表暴露能力,而是围绕业务目标提供服务。

例如设计一个订单系统,用户关注的是创建订单、查询订单状态、取消订单,而不是直接操作订单表。因此核心接口应该表达业务意图。

常见的接口设计过程如下:

  1. 找到主要参与者,例如用户、管理员、外部系统。
  2. 列出高频或关键动作,例如创建、查询、修改、确认。
  3. 为每个动作定义请求信息、返回结果和失败情况。

API 输入输出如何设计

好的接口输入应该包含完成业务动作所需的信息,避免把内部数据结构直接暴露给调用方。

例如创建订单接口可以这样设计:

http
POST /api/orders
Content-Type: application/json

{
  "userId": "<ID>",
  "items": [
    {
      "productId": "<ID>",
      "quantity": 2
    }
  ]
}

预期结果

text
HTTP 201 Created

{
  "orderId": "<ID>",
  "status": "CREATED"
}

这里的返回值只表达调用方需要知道的结果,例如订单编号和当前状态,而不是返回数据库中的全部字段。

错误语义比路径更重要

面试中很多人只关注 URL 和 HTTP 方法,但真实系统更关心失败时调用方如何处理。

常见错误需要区分业务失败和系统失败:

类型 示例 调用方处理
参数错误 商品数量非法 修改请求后重试
业务冲突 库存不足 提示用户重新选择
权限错误 无权访问订单 重新认证或拒绝操作
系统异常 服务不可用 根据策略重试

例如库存不足不应该返回普通服务器异常,否则客户端无法判断是否需要重新提交。

接口设计中的幂等问题

涉及创建、支付、扣库存等操作时,需要考虑重复请求。例如网络超时后,客户端可能再次发送创建订单请求。

一种常见方案是增加业务幂等键:

json
{
  "requestId": "<ID>",
  "userId": "<ID>",
  "items": [
    {
      "productId": "<ID>",
      "quantity": 1
    }
  ]
}

预期结果

text
相同 requestId 的重复请求返回第一次创建结果,不重复生成订单。

接口设计不是越多越好,而是让核心业务动作拥有稳定、清晰、可演进的契约。系统设计面试中,先说明用户行为,再给出接口,是比直接罗列 REST 路径更完整的表达方式。

按自己的节奏,确认真正理解。

目录与阅读设置

记录一个想法

核心接口先设计什么

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通