架构与系统设计 / 系统课时
核心接口先设计什么
核心接口先设计什么
系统设计面试中,接口设计不是把所有功能都列成 API,而是先找到用户完成核心动作时必须经过的业务入口。本篇将从用户行为出发,设计关键接口、输入输出和错误语义。
学习目标
- 理解为什么接口设计应该从用户动作和业务结果开始
- 掌握核心 API 的输入、输出和错误语义设计方法
- 能在系统设计面试中快速描述接口边界
从用户动作找到核心接口
设计接口前先回答一个问题:用户最重要的动作是什么。系统不是围绕数据库表暴露能力,而是围绕业务目标提供服务。
例如设计一个订单系统,用户关注的是创建订单、查询订单状态、取消订单,而不是直接操作订单表。因此核心接口应该表达业务意图。
常见的接口设计过程如下:
- 找到主要参与者,例如用户、管理员、外部系统。
- 列出高频或关键动作,例如创建、查询、修改、确认。
- 为每个动作定义请求信息、返回结果和失败情况。
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 路径更完整的表达方式。
按自己的节奏,确认真正理解。