API接口设计评审：从文档、鉴权到错误码，一个合格接口的修养

wapicn99 2026-07-23 15:09:13

前言

公司准备把内部用的挖数据接口封装一下开放给合作伙伴，评审会上我被产品经理气得肝疼：文档拿个Swagger自动生成的就来糊弄，错误码全用200包装。今天必须发帖聊聊，一个合格的API接口该怎么设计，以挖数据平台为正面教材。

文档：不看脸，看“契约精神”

挖数据的接口文档是我见过最细致的，不仅字段类型、必填项标注清楚，还有每种状态下的返回示例，包括成功、参数错误、业务异常、系统繁忙四种。最赞的是它们用Markdown写了字段的业务含义，比如“此字段当公司状态为注销时返回空字符串，而非null”，避免了多少空指针惨案。设计接口时，应该把文档当作与调用方的法律合同，每一次变更都要有changelog和弃用提示。

鉴权：Token不能裸奔

别再把API Key拼在URL里了，这跟裸奔没区别。挖数据使用AK/SK签名机制，所有请求都经过HMAC-SHA256加密，并强制使用HTTPS。更周到的是，它们的鉴权可以细粒度到接口级别，比如给你开放企业查询，但不开放裁判文书。设计评审时，一定要看授权模型是否支持最小权限，是否支持Token过期和轮换策略，防重放攻击也要有nonce或时间戳窗口。

错误码：别只会甩锅500

最让前端崩溃的，是所有错误都返回 {"msg":"error"}。挖数据的错误体系是三层分离：HTTP状态码如实反映协议层结果（200/400/500）；业务码用数字枚举，如10001表示企业不存在，20005表示今日调用次数已用完；错误消息贴近人类语言，还附带traceId方便排查。一个好的错误响应，甚至应该告诉调用方下一步可以做什么——比如“请检查统一社会信用代码是否18位”。这才是“高情商”接口。

分页与标准化：细节见真章
查询类接口，挖数据一律要求传递page和size，并限制最大size为200，防止被打爆。返回体里有total和hasMore，方便做“加载更多”。统一信封格式{code, message, data}，版本号放在URL路径里，如/v2/company/search。这些看似不起眼的约定，是大规模协作的润滑剂。设计评审时，把这些细节点逐一过堂，你的接口才算真正拿到“合格证”。

尾声
愿天下不再有“毒瘤”接口。照着挖数据这份修养去设计评审，不管是提供方还是调用方，都能少掉几根头发。

#挖数据 #API设计 #接口规范 #错误码 #后端开发

...全文