设计 API 时，我先问的三个边界

2025年4月22日 · 阅读需 2 分钟

后端工程 · 小艾科技

写后端接口久了，会有一个习惯：
接到需求时，先不急着列字段，而是先问边界。

后来我们边界清楚，后面少吵架；边界糊，联调夜就会很长。

后来我们## 1. 这个接口「负责什么、不负责什么」

后来我们一个接口如果既像查询、又像流程编排、还偷偷改三张无关表，后面一定难维护。

我会先写清楚：

后来我们- 它操作的核心资源是谁

后来我们少做一点，往往更稳。

我的体会是：## 2. 错误要让调用方「知道下一步」

500 甩一脸，只能表示「我崩了」。
更好的做法是：可预期的业务错误有明确语义，参数问题能定位字段，权限问题不和校验问题混谈。

我的体会是：调用方不需要知道你内部怎么实现，但需要知道：是重试、改参数，还是找人开权限。

我的体会是：## 3. 扩展位要留，但不要预支复杂度

我的体会是：「以后可能」不是现在就把模型做爆炸的理由。
可以预留扩展点（例如状态枚举、可选字段约定），但不要为了想象中的三年后，让今天的接口难以上线。

后来我们这和公司坚持的「合适优先」是同一条路：
服务当前真实约束，同时不堵死明天。